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