| blob | 1b7baeda67bb906f7685e43a049a9ae2366336cb |
1 .\" $NetBSD: syslog.3,v 1.29 2011/07/25 19:42:50 njoly Exp $
2 .\" $OpenBSD: syslog.3,v 1.25 2005/07/22 03:16:58 jaredy Exp $
3 .\"
4 .\" Copyright (c) 1985, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .\" @(#)syslog.3 8.1 (Berkeley) 6/4/93
32 .\"
33 .Dd May 3, 2010
34 .Dt SYSLOG 3
35 .Os
36 .Sh NAME
37 .Nm syslog ,
38 .Nm syslog_r ,
39 .Nm vsyslog ,
40 .Nm vsyslog_r ,
41 .Nm syslogp ,
42 .Nm syslogp_r ,
43 .Nm vsyslogp ,
44 .Nm vsyslogp_r ,
45 .Nm openlog ,
46 .Nm openlog_r ,
47 .Nm closelog ,
48 .Nm closelog_r ,
49 .Nm setlogmask ,
50 .Nm setlogmask_r
51 .Nd control system log
52 .Sh LIBRARY
53 .Lb libc
54 .Sh SYNOPSIS
55 .In syslog.h
56 .Ft void
57 .Fn syslog "int priority" "const char *message" "..."
58 .Ft void
59 .Fn syslog_r "int priority" "struct syslog_data *data" "const char *message" "..."
60 .Ft void
61 .Fn syslogp "int priority" "const char *msgid" "const char *sdfmt" "const char *message" "..."
62 .Ft void
63 .Fn syslogp_r "int priority" "struct syslog_data *data" "const char *msgid" "const char *sdfmt" "const char *message" "..."
64 .\" .Ft void
65 .\" .Fn syslog_ss "int priority" "struct syslog_data *data" "const char *message" "..."
66 .Ft void
67 .Fn openlog "const char *ident" "int logopt" "int facility"
68 .Ft void
69 .Fn openlog_r "const char *ident" "int logopt" "int facility" "struct syslog_data *data"
70 .Ft void
71 .Fn closelog void
72 .Ft void
73 .Fn closelog_r "struct syslog_data *data"
74 .Ft int
75 .Fn setlogmask "int maskpri"
76 .Ft int
77 .Fn setlogmask_r "int maskpri" "struct syslog_data *data"
78 .In stdarg.h
79 .Ft void
80 .Fn vsyslog "int priority" "const char *message" "va_list args"
81 .Ft void
82 .Fn vsyslog_r "int priority" "struct syslog_data *data" "const char *message" "va_list args"
83 .Ft void
84 .Fn vsyslogp "int priority" "const char *msgid" "const char *sdfmt" "const char *message" "va_list args"
85 .Ft void
86 .Fn vsyslogp_r "int priority" "struct syslog_data *data" "const char *msgid" "const char *sdfmt" "const char *message" "va_list args"
87 .\" .Ft void
88 .\" .Fn vsyslog_ss "int priority" "struct syslog_data *data" "const char *message" "va_list args"
89 .Sh DESCRIPTION
90 The
91 .Fn syslog
92 function
93 writes
94 .Fa message
95 to the system message logger.
96 The message is then written to the system console, log files,
97 logged-in users, or forwarded to other machines as appropriate (see
98 .Xr syslogd 8 ) .
99 .Pp
100 The message is identical to a
101 .Xr printf 3
102 format string, except that
103 .Ql %m
104 is replaced by the current error
105 message.
106 (As denoted by the global variable
107 .Va errno ;
108 see
109 .Xr strerror 3 . )
110 A trailing newline is added if none is present.
111 .\" shouldn't the newline statement be removed?
112 .\" when logging through a socket a newline is
113 .\" not added nor is it required. -- ms
114 .Pp
115 The
116 .Fn syslog_r
117 function is a multithread-safe version of the
118 .Fn syslog
119 function.
120 It takes a pointer to a
121 .Fa syslog_data
122 structure which is used to store
123 information.
124 This parameter must be initialized before
125 .Fn syslog_r
126 is called.
127 The
128 .Dv SYSLOG_DATA_INIT
129 constant is used for this purpose.
130 The
131 .Fa syslog_data
132 structure and the
133 .Dv SYSLOG_DATA_INIT
134 constant are defined as:
135 .Bd -literal -offset indent
136 struct syslog_data {
137 int log_file;
138 int connected;
139 int opened;
140 int log_stat;
141 const char *log_tag;
142 int log_fac;
143 int log_mask;
144 };
146 #define SYSLOG_DATA_INIT { \e
147 .log_file = -1, \e
148 .log_fac = LOG_USER, \e
149 .log_mask = 0xff, \e
150 }
151 .Ed
152 .Pp
153 The structure is composed of the following elements:
154 .Bl -tag -width connected -offset indent
155 .It Va log_file
156 contains the file descriptor of the file where the message is logged
157 .It Va connected
158 indicates if connect has been done
159 .It Va opened
160 indicates if
161 .Fn openlog_r
162 has been called
163 .It Va log_stat
164 status bits, set by
165 .Fn openlog_r
166 .It Va log_tag
167 string to tag the entry with
168 .It Va log_fac
169 facility code
170 .It Va log_mask
171 mask of priorities to be logged
172 .El
173 .\" .Pp
174 .\" The
175 .\" .Fn syslog_ss
176 .\" is the async-signal-safe version of
177 .\" .Fn syslog_r
178 .\" and is also multithread-safe.
179 .\" It has the following limitations:
180 .\" .Bl -enum -offset indent
181 .\" .It
182 .\" The format string cannot contain multi-byte character sequences.
183 .\" .It
184 .\" Floating point formats are not supported and print
185 .\" .Dq UNK .
186 .\" .It
187 .\" The time of the event is not sent to
188 .\" .Xr syslogd 8 .
189 .\" .It
190 .\" The error string in the %m format is not printed symbolically but as
191 .\" .Dq Error %d .
192 .\" .El
193 .\" .Pp
194 .\" For more information about async-signal-safe functions and signal handlers, see
195 .\" .Xr signal 7 .
196 .Pp
197 The
198 .Fn vsyslog
199 function
200 is an alternative form in which the arguments have already been captured
201 using the variable-length argument facilities of
202 .Xr stdarg 3 .
203 .Pp
204 The
205 .Fn syslogp
206 variants take additional arguments which correspond to new fields in the
207 syslog-protocol message format.
208 All three arguments are evaluated as
209 .Xr printf 3
210 format strings and any of them can be
211 .Dv NULL .
212 This enables applications to use message IDs, structured data, and UTF-8 encoded
213 content in messages.
214 .Pp
215 The message is tagged with
216 .Fa priority .
217 Priorities are encoded as a
218 .Fa facility
219 and a
220 .Em level .
221 The facility describes the part of the system
222 generating the message.
223 The level is selected from the following
224 .Em ordered
225 (high to low) list:
226 .Bl -tag -width LOG_AUTHPRIV
227 .It Dv LOG_EMERG
228 A panic condition.
229 This is normally broadcast to all users.
230 .It Dv LOG_ALERT
231 A condition that should be corrected immediately, such as a corrupted
232 system database.
233 .It Dv LOG_CRIT
234 Critical conditions, e.g., hard device errors.
235 .It Dv LOG_ERR
236 Errors.
237 .It Dv LOG_WARNING
238 Warning messages.
239 .It Dv LOG_NOTICE
240 Conditions that are not error conditions,
241 but should possibly be handled specially.
242 .It Dv LOG_INFO
243 Informational messages.
244 .It Dv LOG_DEBUG
245 Messages that contain information
246 normally of use only when debugging a program.
247 .El
248 .Pp
249 The
250 .Fn vsyslog_r
251 is used the same way as
252 .Fn vsyslog
253 except that it takes an additional pointer to a
254 .Fa syslog_data
255 structure.
256 It is a multithread-safe version of the
257 .Fn vsyslog
258 function described above.
259 .\" The
260 .\" .Fn vsyslog_ss
261 .\" is the async-signal-safe version of
262 .\" .Fn vsyslog_r ,
263 .\" is also multithread-safe, and has the same limitations as
264 .\" .Fn syslog_ss .
265 .Pp
266 The
267 .Fn openlog
268 function
269 provides for more specialized processing of the messages sent
270 by
271 .Fn syslog
272 and
273 .Fn vsyslog .
274 The parameter
275 .Fa ident
276 is a string that will be prepended to every message.
277 The
278 .Fa logopt
279 argument
280 is a bit field specifying logging options, which is formed by
281 .Tn OR Ns 'ing
282 one or more of the following values:
283 .Bl -tag -width LOG_AUTHPRIV
284 .It Dv LOG_CONS
285 If
286 .Fn syslog
287 cannot pass the message to
288 .Xr syslogd 8
289 it will attempt to write the message to the console
290 .Pq Dq Pa /dev/console .
291 .It Dv LOG_NDELAY
292 Open the connection to
293 .Xr syslogd 8
294 immediately.
295 Normally the open is delayed until the first message is logged.
296 Useful for programs that need to manage the order in which file
297 descriptors are allocated.
298 .It Dv LOG_PERROR
299 Write the message to standard error output as well to the system log.
300 .It Dv LOG_PID
301 Log the process id with each message: useful for identifying
302 instantiations of daemons.
303 (This PID is placed within brackets
304 between the ident and the message.)
305 .El
306 .Pp
307 The
308 .Fa facility
309 parameter encodes a default facility to be assigned to all messages
310 that do not have an explicit facility encoded:
311 .Bl -tag -width LOG_AUTHPRIV
312 .It Dv LOG_AUTH
313 The authorization system:
314 .Xr login 1 ,
315 .Xr su 1 ,
316 .Xr getty 8 ,
317 etc.
318 .It Dv LOG_AUTHPRIV
319 The same as
320 .Dv LOG_AUTH ,
321 but logged to a file readable only by
322 selected individuals.
323 .It Dv LOG_CRON
324 The cron daemon:
325 .Xr cron 8 .
326 .It Dv LOG_DAEMON
327 System daemons, such as
328 .Xr routed 8 ,
329 that are not provided for explicitly by other facilities.
330 .It Dv LOG_FTP
331 The file transfer protocol daemon:
332 .Xr ftpd 8 .
333 .It Dv LOG_KERN
334 Messages generated by the kernel.
335 These cannot be generated by any user processes.
336 .It Dv LOG_LPR
337 The line printer spooling system:
338 .Xr lpr 1 ,
339 .Xr lpc 8 ,
340 .Xr lpd 8 ,
341 etc.
342 .It Dv LOG_MAIL
343 The mail system.
344 .It Dv LOG_NEWS
345 The network news system.
346 .It Dv LOG_SYSLOG
347 Messages generated internally by
348 .Xr syslogd 8 .
349 .It Dv LOG_USER
350 Messages generated by random user processes.
351 This is the default facility identifier if none is specified.
352 .It Dv LOG_UUCP
353 The uucp system.
354 .It Dv LOG_LOCAL0
355 Reserved for local use.
356 Similarly for
357 .Dv LOG_LOCAL1
358 through
359 .Dv LOG_LOCAL7 .
360 .El
361 .Pp
362 The
363 .Fn openlog_r
364 function is the multithread-safe version of the
365 .Fn openlog
366 function.
367 It takes an additional pointer to a
368 .Fa syslog_data
369 structure.
370 This function must be used in conjunction with the other
371 multithread-safe functions.
372 .Pp
373 The
374 .Fn closelog
375 function
376 can be used to close the log file.
377 .Pp
378 The
379 .Fn closelog_r
380 does the same thing as
381 .Xr closelog 3
382 but in a multithread-safe way and takes an additional
383 pointer to a
384 .Fa syslog_data
385 structure.
386 .Pp
387 The
388 .Fn setlogmask
389 function
390 sets the log priority mask to
391 .Fa maskpri
392 and returns the previous mask.
393 Calls to
394 .Fn syslog
395 with a priority not set in
396 .Fa maskpri
397 are rejected.
398 The mask for an individual priority
399 .Fa pri
400 is calculated by the macro
401 .Fn LOG_MASK pri ;
402 the mask for all priorities up to and including
403 .Fa toppri
404 is given by the macro
405 .Fn LOG_UPTO toppri .
406 The default allows all priorities to be logged.
407 .Pp
408 The
409 .Fn setlogmask_r
410 function is the multithread-safe version of
411 .Fn setlogmask .
412 It takes an additional pointer to a
413 .Fa syslog_data
414 structure.
415 .Sh RETURN VALUES
416 The routines
417 .Fn closelog ,
418 .Fn closelog_r ,
419 .Fn openlog ,
420 .Fn openlog_r ,
421 .Fn syslog ,
422 .Fn syslog_r ,
423 .Fn vsyslog ,
424 .Fn vsyslog_r ,
425 .Fn syslogp ,
426 .Fn syslogp_r ,
427 .Fn vsyslogp ,
428 and
429 .Fn vsyslogp_r
430 return no value.
431 .Pp
432 The routines
433 .Fn setlogmask
434 and
435 .Fn setlogmask_r
436 always return the previous log mask level.
437 .Sh EXAMPLES
438 .Bd -literal -offset indent -compact
439 syslog(LOG_ALERT, "who: internal error 23");
441 openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP);
443 setlogmask(LOG_UPTO(LOG_ERR));
445 syslog(LOG_INFO, "Connection from host %d", CallingHost);
447 syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m");
449 syslogp(LOG_INFO|LOG_LOCAL2, NULL, NULL, "foobar error: %m");
451 syslogp(LOG_INFO, "ID%d", "[meta language=\e"en-US\e"]",
452 "event: %s", 42, EventDescription);
453 .Ed
454 .Pp
455 For the multithread-safe functions:
456 .Bd -literal -offset indent
457 struct syslog_data sdata = SYSLOG_DATA_INIT;
459 syslog_r(LOG_INFO|LOG_LOCAL2, \*[Am]sdata, "foobar error: %m");
460 .Ed
461 .Sh SEE ALSO
462 .Xr logger 1 ,
463 .Xr syslogd 8
464 .Rs
465 .%R RFC
466 .%N 3164
467 .%D August 2001
468 .%T The BSD syslog Protocol
469 .Re
470 .Rs
471 .%R Internet-Draft
472 .%N draft-ietf-syslog-protocol-23
473 .%D September 2007
474 .%T The syslog Protocol
475 .Re
476 .Sh HISTORY
477 These non-multithread-safe functions appeared in
478 .Bx 4.2 .
479 The multithread-safe functions appeared in
480 .Ox 3.1
481 and then in
482 .Nx 4.0 .
483 The async-signal-safe functions appeared in
484 .Nx 4.0 .
485 The syslog-protocol functions appeared in
486 .Nx 5.0 .
487 .Sh CAVEATS
488 It is important never to pass a string with user-supplied data as a
489 format without using
490 .Ql %s .
491 An attacker can put format specifiers in the string to mangle your stack,
492 leading to a possible security hole.
493 This holds true even if you have built the string
494 .Dq by hand
495 using a function like
496 .Fn snprintf ,
497 as the resulting string may still contain user-supplied conversion specifiers
498 for later interpolation by
499 .Fn syslog .
500 .Pp
501 Always be sure to use the proper secure idiom:
502 .Bd -literal -offset indent
503 syslog(priority, "%s", string);
504 .Ed
505 .Pp
506 With
507 .Fn syslogp
508 the caller is responsible to use the right formatting for the message fields.
509 A
510 .Fa msgid
511 must only contain up to 32 ASCII characters.
512 A
513 .Fa sdfmt
514 has strict rules for paranthesis and character quoting.
515 If the
516 .Fa msgfmt
517 contains UTF-8 characters, then it has to start with a Byte Order Mark.