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