(argz_delete): Fix prototype.
[kopensolaris-gnu/glibc.git] / manual / syslog.texi
1 @node Syslog, Mathematics, Low-Level Terminal Interface, Top
2 @c %MENU% System logging and messaging
3 @chapter Syslog
4
5
6 This chapter describes facilities for issuing and logging messages of
7 system administration interest.  This chapter has nothing to do with
8 programs issuing messages to their own users or keeping private logs
9 (One would typically do that with the facilities described in
10 @ref{I/O on Streams}).
11
12 Most systems have a facility called ``Syslog'' that allows programs to
13 submit messages of interest to system administrators and can be
14 configured to pass these messages on in various ways, such as printing
15 on the console, mailing to a particular person, or recording in a log
16 file for future reference.
17
18 A program uses the facilities in this chapter to submit such messages.
19
20 @menu
21 * Overview of Syslog::           Overview of a system's Syslog facility
22 * Submitting Syslog Messages::   Functions to submit messages to Syslog
23 @end menu
24
25 @node Overview of Syslog
26 @section Overview of Syslog
27
28 System administrators have to deal with lots of different kinds of
29 messages from a plethora of subsystems within each system, and usually
30 lots of systems as well.  For example, an FTP server might report every
31 connection it gets.  The kernel might report hardware failures on a disk
32 drive.  A DNS server might report usage statistics at regular intervals.
33
34 Some of these messages need to be brought to a system administrator's
35 attention immediately.  And it may not be just any system administrator
36 -- there may be a particular system administrator who deals with a
37 particular kind of message.  Other messages just need to be recorded for
38 future reference if there is a problem.  Still others may need to have
39 information extracted from them by an automated process that generates
40 monthly reports.
41
42 To deal with these messages, most Unix systems have a facility called
43 "Syslog."  It is generally based on a daemon called ``Syslogd''
44 Syslogd listens for messages on a Unix domain socket named
45 @file{/dev/log}.  Based on classification information in the messages
46 and its configuration file (usually @file{/etc/syslog.conf}), Syslogd
47 routes them in various ways.  Some of the popular routings are:
48
49 @itemize @bullet
50 @item
51 Write to the system console
52 @item
53 Mail to a specific user
54 @item
55 Write to a log file
56 @item
57 Pass to another daemon
58 @item
59 Discard
60 @end itemize
61
62 Syslogd can also handle messages from other systems.  It listens on the
63 @code{syslog} UDP port as well as the local socket for messages.
64
65 Syslog can handle messages from the kernel itself.  But the kernel
66 doesn't write to @file{/dev/log}; rather, another daemon (sometimes
67 called ``Klogd'') extracts messages from the kernel and passes them on to
68 Syslog as any other process would (and it properly identifies them as
69 messages from the kernel).
70
71 Syslog can even handle messages that the kernel issued before Syslogd or
72 Klogd was running.  A Linux kernel, for example, stores startup messages
73 in a kernel message ring and they are normally still there when Klogd
74 later starts up.  Assuming Syslogd is running by the time Klogd starts,
75 Klogd then passes everything in the message ring to it.
76
77 In order to classify messages for disposition, Syslog requires any process
78 that submits a message to it to provide two pieces of classification
79 information with it:
80
81 @table @asis
82 @item facility
83 This identifies who submitted the message.  There are a small number of
84 facilities defined.  The kernel, the mail subsystem, and an FTP server
85 are examples of recognized facilities.  For the complete list,
86 @xref{syslog; vsyslog}.  Keep in mind that these are
87 essentially arbitrary classifications.  "Mail subsystem" doesn't have any
88 more meaning than the system administrator gives to it.
89
90 @item priority
91 This tells how important the content of the message is.  Examples of
92 defined priority values are: debug, informational, warning, critical.
93 For the complete list, @xref{syslog; vsyslog}.  Except for
94 the fact that the priorities have a defined order, the meaning of each
95 of these priorities is entirely determined by the system administrator.
96
97 @end table
98
99 A ``facility/priority'' is a number that indicates both the facility
100 and the priority.
101
102 @strong{Warning:} This terminology is not universal.  Some people use
103 ``level'' to refer to the priority and ``priority'' to refer to the
104 combination of facility and priority.  A Linux kernel has a concept of a
105 message ``level,'' which corresponds both to a Syslog priority and to a
106 Syslog facility/priority (It can be both because the facility code for
107 the kernel is zero, and that makes priority and facility/priority the
108 same value).
109
110 The GNU C library provides functions to submit messages to Syslog.  They
111 do it by writing to the @file{/dev/log} socket.  @xref{Submitting Syslog
112 Messages}.
113
114 The GNU C library functions only work to submit messages to the Syslog
115 facility on the same system.  To submit a message to the Syslog facility
116 on another system, use the socket I/O functions to write a UDP datagram
117 to the @code{syslog} UDP port on that system.  @xref{Sockets}.
118
119
120 @node Submitting Syslog Messages
121 @section Submitting Syslog Messages
122
123 The GNU C library provides functions to submit messages to the Syslog
124 facility:
125
126 @menu
127 * openlog::                      Open connection to Syslog
128 * syslog; vsyslog::              Submit message to Syslog
129 * closelog::                     Close connection to Syslog
130 * setlogmask::                   Cause certain messages to be ignored
131 * Syslog Example::               Example of all of the above
132 @end menu
133
134 These functions only work to submit messages to the Syslog facility on
135 the same system.  To submit a message to the Syslog facility on another
136 system, use the socket I/O functions to write a UDP datagram to the
137 @code{syslog} UDP port on that system.  @xref{Sockets}.
138
139
140
141 @node openlog
142 @subsection openlog
143
144 The symbols referred to in this section are declared in the file
145 @file{syslog.h}.
146
147 @comment syslog.h
148 @comment BSD
149 @deftypefun void openlog (const char *@var{ident}, int @var{option}, int @var{facility})
150
151 @code{openlog} opens or reopens a connection to Syslog in preparation
152 for submitting messages.
153
154 @var{ident} is an arbitrary identification string which future
155 @code{syslog} invocations will prefix to each message.  This is intended
156 to identify the source of the message, and people conventionally set it
157 to the name of the program that will submit the messages.
158
159 If @var{ident} is NULL, or if @code{openlog} is not called, the default
160 identification string used in Syslog messages will be the program name,
161 taken from argv[0].
162
163 Please note that the string pointer @var{ident} will be retained
164 internally by the Syslog routines.  You must not free the memory that
165 @var{ident} points to.  It is also dangerous to pass a reference to an
166 automatic variable since leaving the scope would mean ending the
167 lifetime of the variable.  If you want to change the @var{ident} string,
168 you must call @code{openlog} again; overwriting the string pointed to by
169 @var{ident} is not thread-safe.
170
171 You can cause the Syslog routines to drop the reference to @var{ident} and
172 go back to the default string (the program name taken from argv[0]), by
173 calling @code{closelog}: @xref{closelog}.
174
175 In particular, if you are writing code for a shared library that might get
176 loaded and then unloaded (e.g. a PAM module), and you use @code{openlog},
177 you must call @code{closelog} before any point where your library might
178 get unloaded, as in this example:
179
180 @smallexample
181 #include <syslog.h>
182
183 void
184 shared_library_function (void)
185 @{
186   openlog ("mylibrary", option, priority);
187
188   syslog (LOG_INFO, "shared library has been invoked");
189
190   closelog ();
191 @}
192 @end smallexample
193
194 Without the call to @code{closelog}, future invocations of @code{syslog}
195 by the program using the shared library may crash, if the library gets
196 unloaded and the memory containing the string @code{"mylibrary"} becomes
197 unmapped.  This is a limitation of the BSD syslog interface.
198
199 @code{openlog} may or may not open the @file{/dev/log} socket, depending
200 on @var{option}.  If it does, it tries to open it and connect it as a
201 stream socket.  If that doesn't work, it tries to open it and connect it
202 as a datagram socket.  The socket has the ``Close on Exec'' attribute,
203 so the kernel will close it if the process performs an exec.
204
205 You don't have to use @code{openlog}.  If you call @code{syslog} without
206 having called @code{openlog}, @code{syslog} just opens the connection
207 implicitly and uses defaults for the information in @var{ident} and
208 @var{options}.
209
210 @var{options} is a bit string, with the bits as defined by the following
211 single bit masks:
212
213 @table @code
214 @item LOG_PERROR
215 If on, @code{openlog} sets up the connection so that any @code{syslog}
216 on this connection writes its message to the calling process' Standard
217 Error stream in addition to submitting it to Syslog.  If off, @code{syslog}
218 does not write the message to Standard Error.
219
220 @item LOG_CONS
221 If on, @code{openlog} sets up the connection so that a @code{syslog} on
222 this connection that fails to submit a message to Syslog writes the
223 message instead to system console.  If off, @code{syslog} does not write
224 to the system console (but of course Syslog may write messages it
225 receives to the console).
226
227 @item LOG_PID
228 When on, @code{openlog} sets up the connection so that a @code{syslog}
229 on this connection inserts the calling process' Process ID (PID) into
230 the message.  When off, @code{openlog} does not insert the PID.
231
232 @item LOG_NDELAY
233 When on, @code{openlog} opens and connects the @file{/dev/log} socket.
234 When off, a future @code{syslog} call must open and connect the socket.
235
236 @strong{Portability note:}  In early systems, the sense of this bit was
237 exactly the opposite.
238
239 @item LOG_ODELAY
240 This bit does nothing.  It exists for backward compatibility.
241
242 @end table
243
244 If any other bit in @var{options} is on, the result is undefined.
245
246 @var{facility} is the default facility code for this connection.  A
247 @code{syslog} on this connection that specifies default facility causes
248 this facility to be associated with the message.  See @code{syslog} for
249 possible values.  A value of zero means the default default, which is
250 @code{LOG_USER}.
251
252 If a Syslog connection is already open when you call @code{openlog},
253 @code{openlog} ``reopens'' the connection.  Reopening is like opening
254 except that if you specify zero for the default facility code, the
255 default facility code simply remains unchanged and if you specify
256 LOG_NDELAY and the socket is already open and connected, @code{openlog}
257 just leaves it that way.
258
259 @c There is a bug in closelog() (glibc 2.1.3) wherein it does not reset the
260 @c default log facility to LOG_USER, which means the default default log
261 @c facility could be whatever the default log facility was for a previous
262 @c Syslog connection.  I have documented what the function should be rather
263 @c than what it is because I think if anyone ever gets concerned, the code
264 @c will change.
265
266 @end deftypefun
267
268
269 @node syslog; vsyslog
270 @subsection syslog, vsyslog
271
272 The symbols referred to in this section are declared in the file
273 @file{syslog.h}.
274
275 @c syslog() is implemented as a call to vsyslog().
276 @comment syslog.h
277 @comment BSD
278 @deftypefun void syslog (int @var{facility_priority}, char *@var{format}, ...)
279
280 @code{syslog} submits a message to the Syslog facility.  It does this by
281 writing to the Unix domain socket @code{/dev/log}.
282
283 @code{syslog} submits the message with the facility and priority indicated
284 by @var{facility_priority}.  The macro @code{LOG_MAKEPRI} generates a
285 facility/priority from a facility and a priority, as in the following
286 example:
287
288 @smallexample
289 LOG_MAKEPRI(LOG_USER, LOG_WARNING)
290 @end smallexample
291
292 The possible values for the facility code are (macros):
293
294 @c Internally, there is also LOG_KERN, but LOG_KERN == 0, which means
295 @c if you try to use it here, just selects default.
296
297 @vtable @code
298 @item LOG_USER
299 A miscellaneous user process
300 @item LOG_MAIL
301 Mail
302 @item LOG_DAEMON
303 A miscellaneous system daemon
304 @item LOG_AUTH
305 Security (authorization)
306 @item LOG_SYSLOG
307 Syslog
308 @item LOG_LPR
309 Central printer
310 @item LOG_NEWS
311 Network news (e.g. Usenet)
312 @item LOG_UUCP
313 UUCP
314 @item LOG_CRON
315 Cron and At
316 @item LOG_AUTHPRIV
317 Private security (authorization)
318 @item LOG_FTP
319 Ftp server
320 @item LOG_LOCAL0
321 Locally defined
322 @item LOG_LOCAL1
323 Locally defined
324 @item LOG_LOCAL2
325 Locally defined
326 @item LOG_LOCAL3
327 Locally defined
328 @item LOG_LOCAL4
329 Locally defined
330 @item LOG_LOCAL5
331 Locally defined
332 @item LOG_LOCAL6
333 Locally defined
334 @item LOG_LOCAL7
335 Locally defined
336 @end vtable
337
338 Results are undefined if the facility code is anything else.
339
340 @strong{note:} @code{syslog} recognizes one other facility code: that of
341 the kernel.  But you can't specify that facility code with these
342 functions.  If you try, it looks the same to @code{syslog} as if you are
343 requesting the default facility.  But you wouldn't want to anyway,
344 because any program that uses the GNU C library is not the kernel.
345
346 You can use just a priority code as @var{facility_priority}.  In that
347 case, @code{syslog} assumes the default facility established when the
348 Syslog connection was opened.  @xref{Syslog Example}.
349
350 The possible values for the priority code are (macros):
351
352 @vtable @code
353 @item LOG_EMERG
354 The message says the system is unusable.
355 @item LOG_ALERT
356 Action on the message must be taken immediately.
357 @item LOG_CRIT
358 The message states a critical condition.
359 @item LOG_ERR
360 The message describes an error.
361 @item LOG_WARNING
362 The message is a warning.
363 @item LOG_NOTICE
364 The message describes a normal but important event.
365 @item LOG_INFO
366 The message is purely informational.
367 @item LOG_DEBUG
368 The message is only for debugging purposes.
369 @end vtable
370
371 Results are undefined if the priority code is anything else.
372
373 If the process does not presently have a Syslog connection open (i.e.
374 it did not call @code{openlog}), @code{syslog} implicitly opens the
375 connection the same as @code{openlog} would, with the following defaults
376 for information that would otherwise be included in an @code{openlog}
377 call: The default identification string is the program name.  The
378 default default facility is @code{LOG_USER}.  The default for all the
379 connection options in @var{options} is as if those bits were off.
380 @code{syslog} leaves the Syslog connection open.
381
382 If the @file{dev/log} socket is not open and connected, @code{syslog}
383 opens and connects it, the same as @code{openlog} with the
384 @code{LOG_NDELAY} option would.
385
386 @code{syslog} leaves @file{/dev/log} open and connected unless its attempt
387 to send the message failed, in which case @code{syslog} closes it (with the
388 hope that a future implicit open will restore the Syslog connection to a
389 usable state).
390
391 Example:
392
393 @smallexample
394
395 #include <syslog.h>
396 syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR),
397         "Unable to make network connection to %s.  Error=%m", host);
398
399 @end smallexample
400
401 @end deftypefun
402
403
404 @comment syslog.h
405 @comment BSD
406 @deftypefun void vsyslog (int @var{facility_priority}, char *@var{format}, va_list arglist)
407
408 This is functionally identical to @code{syslog}, with the BSD style variable
409 length argument.
410
411 @end deftypefun
412
413
414 @node closelog
415 @subsection closelog
416
417 The symbols referred to in this section are declared in the file
418 @file{syslog.h}.
419
420 @comment syslog.h
421 @comment BSD
422 @deftypefun void closelog (void)
423
424 @code{closelog} closes the current Syslog connection, if there is one.
425 This includes closing the @file{dev/log} socket, if it is open.
426 @code{closelog} also sets the identification string for Syslog messages
427 back to the default, if @code{openlog} was called with a non-NULL argument
428 to @var{ident}.  The default identification string is the program name
429 taken from argv[0].
430
431 If you are writing shared library code that uses @code{openlog} to
432 generate custom syslog output, you should use @code{closelog} to drop the
433 GNU C library's internal reference to the @var{ident} pointer when you are
434 done.  Please read the section on @code{openlog} for more information:
435 @xref{openlog}.
436
437 @code{closelog} does not flush any buffers.  You do not have to call
438 @code{closelog} before re-opening a Syslog connection with @code{initlog}.
439 Syslog connections are automatically closed on exec or exit.
440
441 @end deftypefun
442
443
444 @node setlogmask
445 @subsection setlogmask
446
447 The symbols referred to in this section are declared in the file
448 @file{syslog.h}.
449
450 @comment syslog.h
451 @comment BSD
452 @deftypefun int setlogmask (int @var{mask})
453
454 @code{setlogmask} sets a mask (the ``logmask'') that determines which
455 future @code{syslog} calls shall be ignored.  If a program has not
456 called @code{setlogmask}, @code{syslog} doesn't ignore any calls.  You
457 can use @code{setlogmask} to specify that messages of particular
458 priorities shall be ignored in the future.
459
460 A @code{setlogmask} call overrides any previous @code{setlogmask} call.
461
462 Note that the logmask exists entirely independently of opening and
463 closing of Syslog connections.
464
465 Setting the logmask has a similar effect to, but is not the same as,
466 configuring Syslog.  The Syslog configuration may cause Syslog to
467 discard certain messages it receives, but the logmask causes certain
468 messages never to get submitted to Syslog in the first place.
469
470 @var{mask} is a bit string with one bit corresponding to each of the
471 possible message priorities.  If the bit is on, @code{syslog} handles
472 messages of that priority normally.  If it is off, @code{syslog}
473 discards messages of that priority.  Use the message priority macros
474 described in @ref{syslog; vsyslog} and the @code{LOG_MASK} to construct
475 an appropriate @var{mask} value, as in this example:
476
477 @smallexample
478 LOG_MASK(LOG_EMERG) | LOG_MASK(LOG_ERROR)
479 @end smallexample
480
481 or
482
483 @smallexample
484 ~(LOG_MASK(LOG_INFO))
485 @end smallexample
486
487 There is also a @code{LOG_UPTO} macro, which generates a mask with the bits
488 on for a certain priority and all priorities above it:
489
490 @smallexample
491 LOG_UPTO(LOG_ERROR)
492 @end smallexample
493
494 The unfortunate naming of the macro is due to the fact that internally,
495 higher numbers are used for lower message priorities.
496
497 @end deftypefun
498
499
500 @node Syslog Example
501 @subsection Syslog Example
502
503 Here is an example of @code{openlog}, @code{syslog}, and @code{closelog}:
504
505 This example sets the logmask so that debug and informational messages
506 get discarded without ever reaching Syslog.  So the second @code{syslog}
507 in the example does nothing.
508
509 @smallexample
510 #include <syslog.h>
511
512 setlogmask (LOG_UPTO (LOG_NOTICE));
513
514 openlog ("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);
515
516 syslog (LOG_NOTICE, "Program started by User %d", getuid ());
517 syslog (LOG_INFO, "A tree falls in a forest");
518
519 closelog ();
520
521 @end smallexample