]>
Commit | Line | Data |
---|---|---|
d52b6462 UD |
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 | ||
e4cf5229 | 62 | Syslogd can also handle messages from other systems. It listens on the |
d52b6462 UD |
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 | |
56e74aef | 92 | defined priority values are: debug, informational, warning and critical. |
88197030 | 93 | For the complete list, see @ref{syslog; vsyslog}. Except for |
d52b6462 UD |
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 | ||
1f77f049 | 110 | @Theglibc{} provides functions to submit messages to Syslog. They |
d52b6462 UD |
111 | do it by writing to the @file{/dev/log} socket. @xref{Submitting Syslog |
112 | Messages}. | |
113 | ||
1f77f049 | 114 | The @glibcadj{} functions only work to submit messages to the Syslog |
d52b6462 UD |
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 | ||
1f77f049 | 123 | @Theglibc{} provides functions to submit messages to the Syslog |
d52b6462 UD |
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 | ||
b750d5e7 | 147 | @deftypefun void openlog (const char *@var{ident}, int @var{option}, int @var{facility}) |
d08a7e4c | 148 | @standards{BSD, syslog.h} |
d9e02532 AO |
149 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} |
150 | @c openlog @asulock @aculock @acsfd | |
151 | @c libc_lock_lock @asulock @aculock | |
152 | @c openlog_internal @acsfd [always guarded by syslog_lock, so no race] | |
153 | @c strncpy dup ok | |
154 | @c socket dup @acsfd | |
155 | @c fcntl dup ok | |
156 | @c connect dup ok | |
157 | @c close dup @acsfd | |
158 | @c cancel_handler(NULL) @aculock | |
159 | @c libc_lock_unlock @aculock | |
d52b6462 UD |
160 | |
161 | @code{openlog} opens or reopens a connection to Syslog in preparation | |
162 | for submitting messages. | |
163 | ||
164 | @var{ident} is an arbitrary identification string which future | |
165 | @code{syslog} invocations will prefix to each message. This is intended | |
166 | to identify the source of the message, and people conventionally set it | |
167 | to the name of the program that will submit the messages. | |
168 | ||
b750d5e7 UD |
169 | If @var{ident} is NULL, or if @code{openlog} is not called, the default |
170 | identification string used in Syslog messages will be the program name, | |
171 | taken from argv[0]. | |
172 | ||
173 | Please note that the string pointer @var{ident} will be retained | |
174 | internally by the Syslog routines. You must not free the memory that | |
175 | @var{ident} points to. It is also dangerous to pass a reference to an | |
176 | automatic variable since leaving the scope would mean ending the | |
177 | lifetime of the variable. If you want to change the @var{ident} string, | |
178 | you must call @code{openlog} again; overwriting the string pointed to by | |
179 | @var{ident} is not thread-safe. | |
180 | ||
181 | You can cause the Syslog routines to drop the reference to @var{ident} and | |
182 | go back to the default string (the program name taken from argv[0]), by | |
183 | calling @code{closelog}: @xref{closelog}. | |
184 | ||
185 | In particular, if you are writing code for a shared library that might get | |
186 | loaded and then unloaded (e.g. a PAM module), and you use @code{openlog}, | |
187 | you must call @code{closelog} before any point where your library might | |
188 | get unloaded, as in this example: | |
189 | ||
190 | @smallexample | |
191 | #include <syslog.h> | |
192 | ||
193 | void | |
194 | shared_library_function (void) | |
195 | @{ | |
196 | openlog ("mylibrary", option, priority); | |
197 | ||
198 | syslog (LOG_INFO, "shared library has been invoked"); | |
199 | ||
200 | closelog (); | |
201 | @} | |
202 | @end smallexample | |
203 | ||
204 | Without the call to @code{closelog}, future invocations of @code{syslog} | |
205 | by the program using the shared library may crash, if the library gets | |
206 | unloaded and the memory containing the string @code{"mylibrary"} becomes | |
207 | unmapped. This is a limitation of the BSD syslog interface. | |
208 | ||
d52b6462 | 209 | @code{openlog} may or may not open the @file{/dev/log} socket, depending |
e4cf5229 | 210 | on @var{option}. If it does, it tries to open it and connect it as a |
d52b6462 UD |
211 | stream socket. If that doesn't work, it tries to open it and connect it |
212 | as a datagram socket. The socket has the ``Close on Exec'' attribute, | |
213 | so the kernel will close it if the process performs an exec. | |
214 | ||
215 | You don't have to use @code{openlog}. If you call @code{syslog} without | |
216 | having called @code{openlog}, @code{syslog} just opens the connection | |
217 | implicitly and uses defaults for the information in @var{ident} and | |
e4cf5229 | 218 | @var{options}. |
d52b6462 UD |
219 | |
220 | @var{options} is a bit string, with the bits as defined by the following | |
221 | single bit masks: | |
222 | ||
2fe82ca6 | 223 | @vtable @code |
d52b6462 UD |
224 | @item LOG_PERROR |
225 | If on, @code{openlog} sets up the connection so that any @code{syslog} | |
226 | on this connection writes its message to the calling process' Standard | |
227 | Error stream in addition to submitting it to Syslog. If off, @code{syslog} | |
228 | does not write the message to Standard Error. | |
229 | ||
230 | @item LOG_CONS | |
231 | If on, @code{openlog} sets up the connection so that a @code{syslog} on | |
232 | this connection that fails to submit a message to Syslog writes the | |
233 | message instead to system console. If off, @code{syslog} does not write | |
234 | to the system console (but of course Syslog may write messages it | |
235 | receives to the console). | |
236 | ||
237 | @item LOG_PID | |
238 | When on, @code{openlog} sets up the connection so that a @code{syslog} | |
239 | on this connection inserts the calling process' Process ID (PID) into | |
240 | the message. When off, @code{openlog} does not insert the PID. | |
241 | ||
242 | @item LOG_NDELAY | |
243 | When on, @code{openlog} opens and connects the @file{/dev/log} socket. | |
244 | When off, a future @code{syslog} call must open and connect the socket. | |
245 | ||
246 | @strong{Portability note:} In early systems, the sense of this bit was | |
247 | exactly the opposite. | |
248 | ||
249 | @item LOG_ODELAY | |
250 | This bit does nothing. It exists for backward compatibility. | |
251 | ||
2fe82ca6 | 252 | @end vtable |
d52b6462 UD |
253 | |
254 | If any other bit in @var{options} is on, the result is undefined. | |
255 | ||
256 | @var{facility} is the default facility code for this connection. A | |
257 | @code{syslog} on this connection that specifies default facility causes | |
258 | this facility to be associated with the message. See @code{syslog} for | |
56e74aef | 259 | possible values. A value of zero means the default, which is |
d52b6462 UD |
260 | @code{LOG_USER}. |
261 | ||
262 | If a Syslog connection is already open when you call @code{openlog}, | |
263 | @code{openlog} ``reopens'' the connection. Reopening is like opening | |
264 | except that if you specify zero for the default facility code, the | |
265 | default facility code simply remains unchanged and if you specify | |
266 | LOG_NDELAY and the socket is already open and connected, @code{openlog} | |
267 | just leaves it that way. | |
268 | ||
269 | @c There is a bug in closelog() (glibc 2.1.3) wherein it does not reset the | |
270 | @c default log facility to LOG_USER, which means the default default log | |
271 | @c facility could be whatever the default log facility was for a previous | |
272 | @c Syslog connection. I have documented what the function should be rather | |
273 | @c than what it is because I think if anyone ever gets concerned, the code | |
274 | @c will change. | |
275 | ||
276 | @end deftypefun | |
277 | ||
278 | ||
279 | @node syslog; vsyslog | |
280 | @subsection syslog, vsyslog | |
281 | ||
282 | The symbols referred to in this section are declared in the file | |
283 | @file{syslog.h}. | |
284 | ||
285 | @c syslog() is implemented as a call to vsyslog(). | |
8ded91fb | 286 | @deftypefun void syslog (int @var{facility_priority}, const char *@var{format}, @dots{}) |
d08a7e4c | 287 | @standards{BSD, syslog.h} |
d9e02532 AO |
288 | @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} |
289 | @c syslog @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd | |
290 | @c va_start dup ok | |
291 | @c vsyslog_chk @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd | |
292 | @c syslog(INTERNALLOG) dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd | |
293 | @c open_memstream @ascuheap @acsmem | |
294 | @c stpcpy dup ok | |
295 | @c getpid dup ok | |
296 | @c mempcpy dup ok | |
297 | @c fsetlocking [no @mtasurace:stream @asulock for exclusive stream] | |
298 | @c fprintf @mtslocale @ascuheap @acsmem [no @asucorrupt @aculock @acucorrupt on temp memstream] | |
299 | @c time dup ok | |
300 | @c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd | |
301 | @c strftime_l(C) dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd | |
302 | @c ftell dup ok [no @asucorrupt @aculock @acucorrupt on temp memstream] | |
303 | @c fputs_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream] | |
304 | @c putc_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream] | |
305 | @c vfprintf/vfprintf_chk dup @mtslocale @ascuheap @acsmem [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream] | |
306 | @c fclose dup @ascuheap @acsmem [no @asulock @aculock @acsfd on caller-locked memstream] | |
307 | @c writev dup ok | |
308 | @c libc_lock_lock dup @asulock @aculock | |
309 | @c memset dup ok | |
310 | @c sigemptyset dup ok | |
311 | @c sigaction(SIGPIPE) dup @mtasusig:PIPE @acusig:PIPE | |
312 | @c openlog_internal dup @acsfd | |
313 | @c send dup ok | |
314 | @c closelog_internal dup @acsfd | |
315 | @c open dup @acsfd | |
316 | @c dprintf dup ok | |
317 | @c libc_lock_unlock @asulock @aculock | |
318 | @c free dup @acsuheap @acsmem | |
319 | @c va_end dup ok | |
d52b6462 UD |
320 | |
321 | @code{syslog} submits a message to the Syslog facility. It does this by | |
322 | writing to the Unix domain socket @code{/dev/log}. | |
323 | ||
324 | @code{syslog} submits the message with the facility and priority indicated | |
325 | by @var{facility_priority}. The macro @code{LOG_MAKEPRI} generates a | |
e4cf5229 | 326 | facility/priority from a facility and a priority, as in the following |
d52b6462 UD |
327 | example: |
328 | ||
329 | @smallexample | |
330 | LOG_MAKEPRI(LOG_USER, LOG_WARNING) | |
331 | @end smallexample | |
332 | ||
333 | The possible values for the facility code are (macros): | |
334 | ||
335 | @c Internally, there is also LOG_KERN, but LOG_KERN == 0, which means | |
336 | @c if you try to use it here, just selects default. | |
337 | ||
e4cf5229 | 338 | @vtable @code |
d52b6462 UD |
339 | @item LOG_USER |
340 | A miscellaneous user process | |
341 | @item LOG_MAIL | |
342 | ||
343 | @item LOG_DAEMON | |
344 | A miscellaneous system daemon | |
345 | @item LOG_AUTH | |
346 | Security (authorization) | |
347 | @item LOG_SYSLOG | |
348 | Syslog | |
349 | @item LOG_LPR | |
350 | Central printer | |
351 | @item LOG_NEWS | |
352 | Network news (e.g. Usenet) | |
353 | @item LOG_UUCP | |
354 | UUCP | |
355 | @item LOG_CRON | |
356 | Cron and At | |
357 | @item LOG_AUTHPRIV | |
358 | Private security (authorization) | |
359 | @item LOG_FTP | |
360 | Ftp server | |
361 | @item LOG_LOCAL0 | |
362 | Locally defined | |
363 | @item LOG_LOCAL1 | |
364 | Locally defined | |
365 | @item LOG_LOCAL2 | |
366 | Locally defined | |
367 | @item LOG_LOCAL3 | |
368 | Locally defined | |
369 | @item LOG_LOCAL4 | |
370 | Locally defined | |
371 | @item LOG_LOCAL5 | |
372 | Locally defined | |
373 | @item LOG_LOCAL6 | |
374 | Locally defined | |
375 | @item LOG_LOCAL7 | |
376 | Locally defined | |
e4cf5229 | 377 | @end vtable |
d52b6462 UD |
378 | |
379 | Results are undefined if the facility code is anything else. | |
380 | ||
48b22986 | 381 | @strong{NB:} @code{syslog} recognizes one other facility code: that of |
e4cf5229 UD |
382 | the kernel. But you can't specify that facility code with these |
383 | functions. If you try, it looks the same to @code{syslog} as if you are | |
384 | requesting the default facility. But you wouldn't want to anyway, | |
1f77f049 | 385 | because any program that uses @theglibc{} is not the kernel. |
d52b6462 UD |
386 | |
387 | You can use just a priority code as @var{facility_priority}. In that | |
388 | case, @code{syslog} assumes the default facility established when the | |
389 | Syslog connection was opened. @xref{Syslog Example}. | |
390 | ||
391 | The possible values for the priority code are (macros): | |
392 | ||
e4cf5229 | 393 | @vtable @code |
d52b6462 UD |
394 | @item LOG_EMERG |
395 | The message says the system is unusable. | |
396 | @item LOG_ALERT | |
397 | Action on the message must be taken immediately. | |
398 | @item LOG_CRIT | |
399 | The message states a critical condition. | |
400 | @item LOG_ERR | |
401 | The message describes an error. | |
402 | @item LOG_WARNING | |
403 | The message is a warning. | |
404 | @item LOG_NOTICE | |
405 | The message describes a normal but important event. | |
406 | @item LOG_INFO | |
407 | The message is purely informational. | |
408 | @item LOG_DEBUG | |
409 | The message is only for debugging purposes. | |
e4cf5229 | 410 | @end vtable |
d52b6462 UD |
411 | |
412 | Results are undefined if the priority code is anything else. | |
413 | ||
11bf311e | 414 | If the process does not presently have a Syslog connection open (i.e., |
d52b6462 UD |
415 | it did not call @code{openlog}), @code{syslog} implicitly opens the |
416 | connection the same as @code{openlog} would, with the following defaults | |
417 | for information that would otherwise be included in an @code{openlog} | |
418 | call: The default identification string is the program name. The | |
419 | default default facility is @code{LOG_USER}. The default for all the | |
420 | connection options in @var{options} is as if those bits were off. | |
421 | @code{syslog} leaves the Syslog connection open. | |
422 | ||
696da859 | 423 | If the @file{/dev/log} socket is not open and connected, @code{syslog} |
d52b6462 UD |
424 | opens and connects it, the same as @code{openlog} with the |
425 | @code{LOG_NDELAY} option would. | |
426 | ||
427 | @code{syslog} leaves @file{/dev/log} open and connected unless its attempt | |
428 | to send the message failed, in which case @code{syslog} closes it (with the | |
429 | hope that a future implicit open will restore the Syslog connection to a | |
430 | usable state). | |
431 | ||
432 | Example: | |
433 | ||
434 | @smallexample | |
435 | ||
436 | #include <syslog.h> | |
e4cf5229 UD |
437 | syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR), |
438 | "Unable to make network connection to %s. Error=%m", host); | |
d52b6462 UD |
439 | |
440 | @end smallexample | |
441 | ||
442 | @end deftypefun | |
443 | ||
444 | ||
8ded91fb | 445 | @deftypefun void vsyslog (int @var{facility_priority}, const char *@var{format}, va_list @var{arglist}) |
d08a7e4c | 446 | @standards{BSD, syslog.h} |
d9e02532 AO |
447 | @safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}} |
448 | @c vsyslog @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd | |
449 | @c vsyslog_chk dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd | |
d52b6462 UD |
450 | |
451 | This is functionally identical to @code{syslog}, with the BSD style variable | |
452 | length argument. | |
453 | ||
454 | @end deftypefun | |
455 | ||
456 | ||
457 | @node closelog | |
458 | @subsection closelog | |
459 | ||
460 | The symbols referred to in this section are declared in the file | |
461 | @file{syslog.h}. | |
462 | ||
e4cf5229 | 463 | @deftypefun void closelog (void) |
d08a7e4c | 464 | @standards{BSD, syslog.h} |
d9e02532 AO |
465 | @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}} |
466 | @c closelog @asulock @aculock @acsfd | |
467 | @c libc_lock_lock @asulock @aculock | |
468 | @c closelog_internal @acsfd [always guarded by syslog_lock, so no race] | |
469 | @c close dup@acsfd | |
470 | @c cancel_handler(NULL) @aculock | |
471 | @c libc_lock_unlock @aculock | |
d52b6462 UD |
472 | |
473 | @code{closelog} closes the current Syslog connection, if there is one. | |
696da859 | 474 | This includes closing the @file{/dev/log} socket, if it is open. |
b750d5e7 UD |
475 | @code{closelog} also sets the identification string for Syslog messages |
476 | back to the default, if @code{openlog} was called with a non-NULL argument | |
477 | to @var{ident}. The default identification string is the program name | |
478 | taken from argv[0]. | |
479 | ||
480 | If you are writing shared library code that uses @code{openlog} to | |
1f77f049 JM |
481 | generate custom syslog output, you should use @code{closelog} to drop |
482 | @theglibc{}'s internal reference to the @var{ident} pointer when you are | |
b750d5e7 UD |
483 | done. Please read the section on @code{openlog} for more information: |
484 | @xref{openlog}. | |
485 | ||
486 | @code{closelog} does not flush any buffers. You do not have to call | |
54472e9c | 487 | @code{closelog} before re-opening a Syslog connection with @code{openlog}. |
b750d5e7 | 488 | Syslog connections are automatically closed on exec or exit. |
d52b6462 UD |
489 | |
490 | @end deftypefun | |
491 | ||
492 | ||
493 | @node setlogmask | |
494 | @subsection setlogmask | |
495 | ||
496 | The symbols referred to in this section are declared in the file | |
497 | @file{syslog.h}. | |
498 | ||
d52b6462 | 499 | @deftypefun int setlogmask (int @var{mask}) |
d08a7e4c | 500 | @standards{BSD, syslog.h} |
d9e02532 AO |
501 | @safety{@prelim{}@mtunsafe{@mtasurace{:LogMask}}@asunsafe{}@acsafe{}} |
502 | @c Read and modify are not guarded by syslog_lock, so concurrent changes | |
503 | @c or even uses are undefined. This should use an atomic swap instead, | |
504 | @c at least for modifications. | |
d52b6462 UD |
505 | |
506 | @code{setlogmask} sets a mask (the ``logmask'') that determines which | |
507 | future @code{syslog} calls shall be ignored. If a program has not | |
508 | called @code{setlogmask}, @code{syslog} doesn't ignore any calls. You | |
509 | can use @code{setlogmask} to specify that messages of particular | |
510 | priorities shall be ignored in the future. | |
511 | ||
512 | A @code{setlogmask} call overrides any previous @code{setlogmask} call. | |
513 | ||
514 | Note that the logmask exists entirely independently of opening and | |
515 | closing of Syslog connections. | |
516 | ||
517 | Setting the logmask has a similar effect to, but is not the same as, | |
518 | configuring Syslog. The Syslog configuration may cause Syslog to | |
519 | discard certain messages it receives, but the logmask causes certain | |
520 | messages never to get submitted to Syslog in the first place. | |
521 | ||
522 | @var{mask} is a bit string with one bit corresponding to each of the | |
523 | possible message priorities. If the bit is on, @code{syslog} handles | |
524 | messages of that priority normally. If it is off, @code{syslog} | |
525 | discards messages of that priority. Use the message priority macros | |
526 | described in @ref{syslog; vsyslog} and the @code{LOG_MASK} to construct | |
527 | an appropriate @var{mask} value, as in this example: | |
528 | ||
529 | @smallexample | |
530 | LOG_MASK(LOG_EMERG) | LOG_MASK(LOG_ERROR) | |
531 | @end smallexample | |
532 | ||
533 | or | |
534 | ||
535 | @smallexample | |
536 | ~(LOG_MASK(LOG_INFO)) | |
537 | @end smallexample | |
538 | ||
539 | There is also a @code{LOG_UPTO} macro, which generates a mask with the bits | |
540 | on for a certain priority and all priorities above it: | |
541 | ||
542 | @smallexample | |
543 | LOG_UPTO(LOG_ERROR) | |
544 | @end smallexample | |
545 | ||
e4cf5229 | 546 | The unfortunate naming of the macro is due to the fact that internally, |
d52b6462 UD |
547 | higher numbers are used for lower message priorities. |
548 | ||
549 | @end deftypefun | |
550 | ||
551 | ||
552 | @node Syslog Example | |
553 | @subsection Syslog Example | |
554 | ||
555 | Here is an example of @code{openlog}, @code{syslog}, and @code{closelog}: | |
556 | ||
557 | This example sets the logmask so that debug and informational messages | |
558 | get discarded without ever reaching Syslog. So the second @code{syslog} | |
559 | in the example does nothing. | |
560 | ||
561 | @smallexample | |
562 | #include <syslog.h> | |
563 | ||
e4cf5229 | 564 | setlogmask (LOG_UPTO (LOG_NOTICE)); |
d52b6462 | 565 | |
e4cf5229 | 566 | openlog ("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1); |
d52b6462 | 567 | |
e4cf5229 UD |
568 | syslog (LOG_NOTICE, "Program started by User %d", getuid ()); |
569 | syslog (LOG_INFO, "A tree falls in a forest"); | |
d52b6462 | 570 | |
e4cf5229 | 571 | closelog (); |
d52b6462 UD |
572 | |
573 | @end smallexample |