1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright (c) 1983 Regents of the University of California. All rights reserved. The Berkeley software License Agreement specifies the terms and conditions for redistribution.
4 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/.
6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
7 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
8 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 .\" This notice shall appear on any product containing this material.
10 .TH SYSLOG 3C "Mar 16, 2009"
11 .SH NAME
12 syslog, openlog, closelog, setlogmask \- control system log
13 .SH SYNOPSIS
14 .LP
15 .nf
16 #include <syslog.h>
17
18 \fBvoid\fR \fBopenlog\fR(\fBconst char *\fR\fIident\fR, \fBint\fR \fIlogopt\fR, \fBint\fR \fIfacility\fR);
19 .fi
20
21 .LP
22 .nf
23 \fBvoid\fR \fBsyslog\fR(\fBint\fR \fIpriority\fR, \fBconst char *\fR\fImessage\fR, \fB\&.../*\fR \fIarguments\fR */);
24 .fi
25
26 .LP
27 .nf
28 \fBvoid\fR \fBcloselog\fR(\fBvoid\fR);
29 .fi
30
31 .LP
32 .nf
33 \fBint\fR \fBsetlogmask\fR(\fBint\fR \fImaskpri\fR);
34 .fi
35
36 .SH DESCRIPTION
37 .LP
38 The \fBsyslog()\fR function sends a message to \fBsyslogd\fR(1M), which,
39 depending on the configuration of \fB/etc/syslog.conf\fR, logs it in an
40 appropriate system log, writes it to the system console, forwards it to a list
41 of users, or forwards it to \fBsyslogd\fR on another host over the network.
42 The logged message includes a message header and a message body. The message
43 header consists of a facility indicator, a severity level indicator, a
44 timestamp, a tag string, and optionally the process ID.
45 .sp
46 .LP
47 The message body is generated from the \fImessage\fR and following arguments in
48 the same manner as if these were arguments to \fBprintf\fR(3UCB), except that
49 occurrences of \fB%m\fR in the format string pointed to by the \fImessage\fR
50 argument are replaced by the error message string associated with the current
51 value of \fBerrno\fR. A trailing \fBNEWLINE\fR character is added if needed.
52 .sp
53 .LP
54 Symbolic constants for use as values of the \fIlogopt\fR, \fIfacility\fR,
55 \fIpriority\fR, and \fImaskpri\fR arguments are defined in the <\fBsyslog.h\fR>
56 header.
57 .sp
58 .LP
59 Values of the \fIpriority\fR argument are formed by ORing together a
60 \fIseverity level\fR value and an optional \fIfacility\fR value. If no
61 facility value is specified, the current default facility value is used.
62 .sp
63 .LP
64 Possible values of severity level include, in decreasing order:
65 .sp
66 .ne 2
67 .na
68 \fB\fBLOG_EMERG\fR\fR
69 .ad
70 .RS 15n
71 A panic condition. This is normally broadcast to all users.
72 .RE
73
74 .sp
75 .ne 2
76 .na
77 \fB\fBLOG_ALERT\fR\fR
78 .ad
79 .RS 15n
80 A condition that should be corrected immediately, such as a corrupted system
81 database.
82 .RE
83
84 .sp
85 .ne 2
86 .na
87 \fB\fBLOG_CRIT\fR\fR
88 .ad
89 .RS 15n
90 Critical conditions, such as hard device errors.
91 .RE
92
93 .sp
94 .ne 2
95 .na
96 \fB\fBLOG_ERR\fR\fR
97 .ad
98 .RS 15n
99 Errors.
100 .RE
101
102 .sp
103 .ne 2
104 .na
105 \fB\fBLOG_WARNING\fR\fR
106 .ad
107 .RS 15n
108 Warning messages.
109 .RE
110
111 .sp
112 .ne 2
113 .na
114 \fB\fBLOG_NOTICE\fR\fR
115 .ad
116 .RS 15n
117 Conditions that are not error conditions, but that may require special
118 handling.
119 .RE
120
121 .sp
122 .ne 2
123 .na
124 \fB\fBLOG_INFO\fR\fR
125 .ad
126 .RS 15n
127 Informational messages.
128 .RE
129
130 .sp
131 .ne 2
132 .na
133 \fB\fBLOG_DEBUG\fR\fR
134 .ad
135 .RS 15n
136 Messages that contain information normally of use only when debugging a
137 program.
138 .RE
139
140 .sp
141 .LP
142 The facility indicates the application or system component generating the
143 message. Possible facility values include:
144 .sp
145 .ne 2
146 .na
147 \fB\fBLOG_KERN\fR\fR
148 .ad
149 .RS 14n
150 Messages generated by the kernel. These cannot be generated by any user
151 processes.
152 .RE
153
154 .sp
155 .ne 2
156 .na
157 \fB\fBLOG_USER\fR\fR
158 .ad
159 .RS 14n
160 Messages generated by random user processes. This is the default facility
161 identifier if none is specified.
162 .RE
163
164 .sp
165 .ne 2
166 .na
167 \fB\fBLOG_MAIL\fR\fR
168 .ad
169 .RS 14n
170 The mail system.
171 .RE
172
173 .sp
174 .ne 2
175 .na
176 \fB\fBLOG_DAEMON\fR\fR
177 .ad
178 .RS 14n
179 System daemons.
180 .RE
181
182 .sp
183 .ne 2
184 .na
185 \fB\fBLOG_AUTH\fR\fR
186 .ad
187 .RS 14n
188 The authentication / security / authorization system: \fBlogin\fR(1),
189 \fBsu\fR(1M), \fBgetty\fR(1M).
190 .RE
191
192 .sp
193 .ne 2
194 .na
195 \fB\fBLOG_LPR\fR\fR
196 .ad
197 .RS 14n
198 The line printer spooling system: \fBlpr\fR(1B), \fBlpc\fR(1B).
199 .RE
200
201 .sp
202 .ne 2
203 .na
204 \fB\fBLOG_NEWS\fR\fR
205 .ad
206 .RS 14n
207 Designated for the \fBUSENET\fR network news system.
208 .RE
209
210 .sp
211 .ne 2
212 .na
213 \fB\fBLOG_UUCP\fR\fR
214 .ad
215 .RS 14n
216 Designated for the \fBUUCP\fR system; it does not currently use \fBsyslog()\fR.
217 .RE
218
219 .sp
220 .ne 2
221 .na
222 \fB\fBLOG_CRON\fR\fR
223 .ad
224 .RS 14n
225 The \fBcron\fR/\fBat\fR facility; \fBcrontab\fR(1), \fBat\fR(1),
226 \fBcron\fR(1M).
227 .RE
228
229 .sp
230 .ne 2
231 .na
232 \fB\fBLOG_AUDIT\fR\fR
233 .ad
234 .RS 14n
235 The audit facility, for example, \fBauditd\fR(1M).
236 .RE
237
238 .sp
239 .ne 2
240 .na
241 \fB\fBLOG_LOCAL0\fR\fR
242 .ad
243 .RS 14n
244 Designated for local use.
245 .RE
246
247 .sp
248 .ne 2
249 .na
250 \fB\fBLOG_LOCAL1\fR\fR
251 .ad
252 .RS 14n
253 Designated for local use.
254 .RE
255
256 .sp
257 .ne 2
258 .na
259 \fB\fBLOG_LOCAL2\fR\fR
260 .ad
261 .RS 14n
262 Designated for local use.
263 .RE
264
265 .sp
266 .ne 2
267 .na
268 \fB\fBLOG_LOCAL3\fR\fR
269 .ad
270 .RS 14n
271 Designated for local use.
272 .RE
273
274 .sp
275 .ne 2
276 .na
277 \fB\fBLOG_LOCAL4\fR\fR
278 .ad
279 .RS 14n
280 Designated for local use.
281 .RE
282
283 .sp
284 .ne 2
285 .na
286 \fB\fBLOG_LOCAL5\fR\fR
287 .ad
288 .RS 14n
289 Designated for local use.
290 .RE
291
292 .sp
293 .ne 2
294 .na
295 \fB\fBLOG_LOCAL6\fR\fR
296 .ad
297 .RS 14n
298 Designated for local use.
299 .RE
300
301 .sp
302 .ne 2
303 .na
304 \fB\fBLOG_LOCAL7\fR\fR
305 .ad
306 .RS 14n
307 Designated for local use.
308 .RE
309
310 .sp
311 .LP
312 The \fBopenlog()\fR function sets process attributes that affect subsequent
313 calls to \fBsyslog()\fR. The \fIident\fR argument is a string that is prepended
314 to every message. The \fBopenlog()\fR function uses the passed-in \fIident\fR
315 argument directly, rather than making a private copy of it. The \fIlogopt\fR
316 argument indicates logging options. Values for \fIlogopt\fR are constructed by
317 a bitwise-inclusive OR of zero or more of the following:
318 .sp
319 .ne 2
320 .na
321 \fB\fBLOG_PID\fR\fR
322 .ad
323 .RS 14n
324 Log the process \fBID\fR with each message. This is useful for identifying
325 specific daemon processes (for daemons that fork).
326 .RE
327
328 .sp
329 .ne 2
330 .na
331 \fB\fBLOG_CONS\fR\fR
332 .ad
333 .RS 14n
334 Write messages to the system console if they cannot be sent to
335 \fBsyslogd\fR(1M). This option is safe to use in daemon processes that have no
336 controlling terminal, since \fBsyslog()\fR forks before opening the console.
337 .RE
338
339 .sp
340 .ne 2
341 .na
342 \fB\fBLOG_NDELAY\fR\fR
343 .ad
344 .RS 14n
345 Open the connection to \fBsyslogd\fR(1M) immediately. Normally the open is
346 delayed until the first message is logged. This is useful for programs that
347 need to manage the order in which file descriptors are allocated.
348 .RE
349
350 .sp
351 .ne 2
352 .na
353 \fB\fBLOG_ODELAY\fR\fR
354 .ad
355 .RS 14n
356 Delay open until \fBsyslog()\fR is called.
357 .RE
358
359 .sp
360 .ne 2
361 .na
362 \fB\fBLOG_NOWAIT\fR\fR
363 .ad
364 .RS 14n
365 Do not wait for child processes that have been forked to log messages onto the
366 console. This option should be used by processes that enable notification of
367 child termination using \fBSIGCHLD\fR, since \fBsyslog()\fR may otherwise block
368 waiting for a child whose exit status has already been collected.
369 .RE
370
371 .sp
372 .LP
373 The \fIfacility\fR argument encodes a default facility to be assigned to all
374 messages that do not have an explicit facility already encoded. The initial
375 default facility is \fBLOG_USER\fR.
376 .sp
377 .LP
378 The \fBopenlog()\fR and \fBsyslog()\fR functions may allocate a file
379 descriptor. It is not necessary to call \fBopenlog()\fR prior to calling
380 \fBsyslog()\fR.
381 .sp
382 .LP
383 The \fBcloselog()\fR function closes any open file descriptors allocated by
384 previous calls to \fBopenlog()\fR or \fBsyslog()\fR.
385 .sp
386 .LP
387 The \fBsetlogmask()\fR function sets the log priority mask for the current
388 process to \fImaskpri\fR and returns the previous mask. If the \fImaskpri\fR
389 argument is 0, the current log mask is not modified. Calls by the current
390 process to \fBsyslog()\fR with a priority not set in \fImaskpri\fR are
391 rejected. The mask for an individual priority \fIpri\fR is calculated by the
392 macro \fBLOG_MASK(\fIpri\fR)\fR; the mask for all priorities up to and
393 including \fItoppri\fR is given by the macro \fBLOG_UPTO(\fItoppri\fR)\fR. The
394 default log mask allows all priorities to be logged.
395 .SH RETURN VALUES
396 .LP
397 The \fBsetlogmask()\fR function returns the previous log priority mask. The
398 \fBcloselog()\fR, \fBopenlog()\fR and \fBsyslog()\fR functions return no value.
399 .SH ERRORS
400 .LP
401 No errors are defined.
402 .SH EXAMPLES
403 .LP
404 \fBExample 1 \fRExample of \fBLOG_ALERT\fR message.
405 .sp
406 .LP
407 This call logs a message at priority \fBLOG_ALERT\fR:
408
409 .sp
410 .in +2
411 .nf
412 \fBsyslog(LOG_ALERT, "who: internal error 23")\fR;
413 .fi
414 .in -2
415 .sp
416
417 .sp
418 .LP
419 The \fBFTP\fR daemon \fBftpd\fR would make this call to \fBopenlog()\fR to
420 indicate that all messages it logs should have an identifying string of
421 \fBftpd\fR, should be treated by \fBsyslogd\fR(1M) as other messages from
422 system daemons are, should include the process \fBID\fR of the process logging
423 the message:
424
425 .sp
426 .in +2
427 .nf
428 \fBopenlog("ftpd", LOG_PID, LOG_DAEMON)\fR;
429 .fi
430 .in -2
431 .sp
432
433 .sp
434 .LP
435 Then it would make the following call to \fBsetlogmask()\fR to indicate that
436 messages at priorities from \fBLOG_EMERG\fR through \fBLOG_ERR\fR should be
437 logged, but that no messages at any other priority should be logged:
438
439 .sp
440 .in +2
441 .nf
442 \fBsetlogmask(LOG_UPTO(LOG_ERR))\fR;
443 .fi
444 .in -2
445 .sp
446
447 .sp
448 .LP
449 Then, to log a message at priority \fBLOG_INFO\fR, it would make the following
450 call to \fBsyslog\fR:
451
452 .sp
453 .in +2
454 .nf
455 \fBsyslog(LOG_INFO, "Connection from host %d", CallingHost)\fR;
456 .fi
457 .in -2
458 .sp
459
460 .sp
461 .LP
462 A locally-written utility could use the following call to \fBsyslog()\fR to log
463 a message at priority \fBLOG_INFO\fR to be treated by \fBsyslogd\fR(1M) as
464 other messages to the facility \fBLOG_LOCAL2\fR are:
465
466 .sp
467 .in +2
468 .nf
469 \fBsyslog(LOG_INFO|LOG_LOCAL2, "error: %m")\fR;
470 .fi
471 .in -2
472 .sp
473
474 .SH ATTRIBUTES
475 .LP
476 See \fBattributes\fR(5) for descriptions of the following attributes:
477 .sp
478
479 .sp
480 .TS
481 box;
482 c | c
483 l | l .
484 ATTRIBUTE TYPE ATTRIBUTE VALUE
485 _
486 Interface Stability Committed
487 _
488 MT-Level Safe
489 _
490 Standard See \fBstandards\fR(5).
491 .TE
492
493 .SH SEE ALSO
494 .LP
495 \fBat\fR(1), \fBcrontab\fR(1), \fBlogger\fR(1), \fBlogin\fR(1), \fBlpc\fR(1B),
496 \fBlpr\fR(1B), \fBauditd\fR(1M), \fBcron\fR(1M), \fBgetty\fR(1M),
497 \fBsu\fR(1M), \fBsyslogd\fR(1M), \fBprintf\fR(3UCB),
498 \fBsyslog.conf\fR(4), \fBattributes\fR(5), \fBstandards\fR(5)