]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com) |
aad9077c | 2 | .\" and Copyright 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Updated 1999.12.19 by Karl M. Hegbloom <karlheg@debian.org> | |
27 | .\" | |
c11b1abf | 28 | .\" Updated 13 Oct 2001, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 29 | .\" Added description of vsyslog |
68e1685c | 30 | .\" Added descriptions of LOG_ODELAY and LOG_NOWAIT |
fea681da MK |
31 | .\" Added brief description of facility and option arguments |
32 | .\" Added CONFORMING TO section | |
33 | .\" 2001-10-13, aeb, minor changes | |
34 | .\" Modified 13 Dec 2001, Martin Schulze <joey@infodrom.org> | |
c11b1abf | 35 | .\" Modified 3 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 36 | .\" |
4b8c67d9 | 37 | .TH SYSLOG 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 38 | .SH NAME |
0484cc70 | 39 | closelog, openlog, syslog, vsyslog \- send messages to the system logger |
fea681da MK |
40 | .SH SYNOPSIS |
41 | .B #include <syslog.h> | |
68e4db0a | 42 | .PP |
fea681da MK |
43 | .BI "void openlog(const char *" ident ", int " option ", int " facility ); |
44 | .br | |
45 | .BI "void syslog(int " priority ", const char *" format ", ...);" | |
46 | .br | |
0daa9e92 | 47 | .B "void closelog(void);" |
68e4db0a | 48 | .PP |
fea681da | 49 | .BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); |
68e4db0a | 50 | .PP |
cc4615cc MK |
51 | .in -4n |
52 | Feature Test Macro Requirements for glibc (see | |
53 | .BR feature_test_macros (7)): | |
54 | .in | |
68e4db0a | 55 | .PP |
cc4615cc | 56 | .BR vsyslog (): |
51c612fb MK |
57 | Since glibc 2.19: |
58 | _DEFAULT_SOURCE | |
59 | Glibc 2.19 and earlier: | |
60 | _BSD_SOURCE | |
fea681da | 61 | .SH DESCRIPTION |
aad9077c | 62 | .SS openlog() |
63aa9df0 | 63 | .BR openlog () |
c13182ef | 64 | opens a connection to the system logger for a program. |
847e0d88 | 65 | .PP |
c13182ef | 66 | The string pointed to by |
fea681da MK |
67 | .I ident |
68 | is prepended to every message, and is typically set to the program name. | |
e0fba797 MK |
69 | If |
70 | .I ident | |
71 | is NULL, the program name is used. | |
72 | (POSIX.1-2008 does not specify the behavior when | |
73 | .I ident | |
74 | is NULL.) | |
847e0d88 | 75 | .PP |
fea681da MK |
76 | The |
77 | .I option | |
78 | argument specifies flags which control the operation of | |
63aa9df0 | 79 | .BR openlog () |
fea681da | 80 | and subsequent calls to |
63aa9df0 | 81 | .BR syslog (). |
fea681da MK |
82 | The |
83 | .I facility | |
84 | argument establishes a default to be used if | |
85 | none is specified in subsequent calls to | |
63aa9df0 | 86 | .BR syslog (). |
1d8ee5b8 | 87 | The values that may be specified for |
fea681da MK |
88 | .I option |
89 | and | |
90 | .I facility | |
1d8ee5b8 | 91 | are described below. |
847e0d88 | 92 | .PP |
c13182ef | 93 | The use of |
63aa9df0 | 94 | .BR openlog () |
fea681da | 95 | is optional; it will automatically be called by |
63aa9df0 | 96 | .BR syslog () |
c13182ef | 97 | if necessary, in which case |
fea681da MK |
98 | .I ident |
99 | will default to NULL. | |
aad9077c MK |
100 | .\" |
101 | .SS syslog() and vsyslog() | |
63aa9df0 | 102 | .BR syslog () |
c13182ef | 103 | generates a log message, which will be distributed by |
fea681da | 104 | .BR syslogd (8). |
847e0d88 | 105 | .PP |
fea681da MK |
106 | The |
107 | .I priority | |
1d8ee5b8 | 108 | argument is formed by ORing together a |
fea681da | 109 | .I facility |
1d8ee5b8 | 110 | value and a |
fea681da | 111 | .I level |
1d8ee5b8 | 112 | value (described below). |
6b5652c1 MK |
113 | If no |
114 | .I facility | |
115 | value is ORed into | |
116 | .IR priority , | |
117 | then the default value set by | |
118 | .BR openlog () | |
119 | is used, or, if there was no preceding | |
120 | .BR openlog () | |
121 | call, a default of | |
122 | .BR LOG_USER | |
123 | is employed. | |
847e0d88 | 124 | .PP |
aad9077c | 125 | The remaining arguments are a |
fea681da | 126 | .IR format , |
c13182ef | 127 | as in |
d302d9c9 | 128 | .BR printf (3), |
c13182ef MK |
129 | and any arguments required by the |
130 | .IR format , | |
d302d9c9 | 131 | except that the two-character sequence |
5adafd6d MK |
132 | .B %m |
133 | will be replaced by | |
c13182ef | 134 | the error message string |
fea681da | 135 | .IR strerror ( errno ). |
d302d9c9 | 136 | The format string need not include a terminating newline character. |
847e0d88 | 137 | .PP |
fea681da | 138 | The function |
63aa9df0 | 139 | .BR vsyslog () |
fea681da | 140 | performs the same task as |
63aa9df0 | 141 | .BR syslog () |
fea681da MK |
142 | with the difference that it takes a set of arguments which have |
143 | been obtained using the | |
144 | .BR stdarg (3) | |
145 | variable argument list macros. | |
aad9077c MK |
146 | .\" |
147 | .SS closelog() | |
148 | .BR closelog () | |
149 | closes the file descriptor being used to write to the system logger. | |
150 | The use of | |
151 | .BR closelog () | |
152 | is optional. | |
153 | .\" | |
154 | .SS Values for \fIoption\fP | |
fea681da MK |
155 | The |
156 | .I option | |
c13182ef | 157 | argument to |
63aa9df0 | 158 | .BR openlog () |
1d8ee5b8 | 159 | is a bit mask constructed by ORing together any of the following values: |
64c85cc4 | 160 | .TP 15 |
fea681da | 161 | .B LOG_CONS |
1d8ee5b8 MK |
162 | Write directly to the system console if there is an error while sending to |
163 | the system logger. | |
fea681da MK |
164 | .TP |
165 | .B LOG_NDELAY | |
166 | Open the connection immediately (normally, the connection is opened when | |
167 | the first message is logged). | |
1d8ee5b8 MK |
168 | This may be useful, for example, if a subsequent |
169 | .BR chroot (2) | |
170 | would make the pathname used internally by the logging facility unreachable. | |
fea681da MK |
171 | .TP |
172 | .B LOG_NOWAIT | |
173 | Don't wait for child processes that may have been created while logging | |
c13182ef MK |
174 | the message. |
175 | (The GNU C library does not create a child process, so this | |
fea681da MK |
176 | option has no effect on Linux.) |
177 | .TP | |
178 | .B LOG_ODELAY | |
179 | The converse of | |
180 | .BR LOG_NDELAY ; | |
181 | opening of the connection is delayed until | |
63aa9df0 | 182 | .BR syslog () |
c13182ef MK |
183 | is called. |
184 | (This is the default, and need not be specified.) | |
fea681da MK |
185 | .TP |
186 | .B LOG_PERROR | |
d865ce2d | 187 | (Not in POSIX.1-2001 or POSIX.1-2008.) |
1d8ee5b8 MK |
188 | Also log the message to |
189 | .IR stderr . | |
fea681da MK |
190 | .TP |
191 | .B LOG_PID | |
1d8ee5b8 | 192 | Include the caller's PID with each message. |
aad9077c MK |
193 | .\" |
194 | .SS Values for \fIfacility\fP | |
c13182ef | 195 | The |
fea681da MK |
196 | .I facility |
197 | argument is used to specify what type of program is logging the message. | |
198 | This lets the configuration file specify that messages from different | |
199 | facilities will be handled differently. | |
64c85cc4 | 200 | .TP 15 |
fea681da | 201 | .B LOG_AUTH |
dee998a2 | 202 | security/authorization messages |
fea681da MK |
203 | .TP |
204 | .B LOG_AUTHPRIV | |
c13182ef | 205 | security/authorization messages (private) |
fea681da MK |
206 | .TP |
207 | .B LOG_CRON | |
c13182ef | 208 | clock daemon |
fea681da MK |
209 | .RB ( cron " and " at ) |
210 | .TP | |
211 | .B LOG_DAEMON | |
212 | system daemons without separate facility value | |
213 | .TP | |
214 | .B LOG_FTP | |
215 | ftp daemon | |
216 | .TP | |
217 | .B LOG_KERN | |
88d61d8a | 218 | kernel messages (these can't be generated from user processes) |
ed279485 MI |
219 | .\" LOG_KERN has the value 0; if used as a facility, zero translates to: |
220 | .\" "use the default facility". | |
fea681da MK |
221 | .TP |
222 | .BR LOG_LOCAL0 " through " LOG_LOCAL7 | |
223 | reserved for local use | |
224 | .TP | |
225 | .B LOG_LPR | |
226 | line printer subsystem | |
227 | .TP | |
228 | .B LOG_MAIL | |
229 | mail subsystem | |
230 | .TP | |
231 | .B LOG_NEWS | |
232 | USENET news subsystem | |
233 | .TP | |
234 | .B LOG_SYSLOG | |
235 | messages generated internally by | |
f19a0f03 | 236 | .BR syslogd (8) |
fea681da MK |
237 | .TP |
238 | .BR LOG_USER " (default)" | |
c13182ef | 239 | generic user-level messages |
fea681da MK |
240 | .TP |
241 | .B LOG_UUCP | |
242 | UUCP subsystem | |
aad9077c MK |
243 | .\" |
244 | .SS Values for \fIlevel\fP | |
c13182ef MK |
245 | This determines the importance of the message. |
246 | The levels are, in order of decreasing importance: | |
64c85cc4 | 247 | .TP 15 |
fea681da MK |
248 | .B LOG_EMERG |
249 | system is unusable | |
250 | .TP | |
251 | .B LOG_ALERT | |
252 | action must be taken immediately | |
253 | .TP | |
254 | .B LOG_CRIT | |
255 | critical conditions | |
256 | .TP | |
257 | .B LOG_ERR | |
258 | error conditions | |
259 | .TP | |
260 | .B LOG_WARNING | |
261 | warning conditions | |
262 | .TP | |
263 | .B LOG_NOTICE | |
264 | normal, but significant, condition | |
265 | .TP | |
266 | .B LOG_INFO | |
267 | informational message | |
268 | .TP | |
269 | .B LOG_DEBUG | |
270 | debug-level message | |
dd3568a1 | 271 | .PP |
fea681da MK |
272 | The function |
273 | .BR setlogmask (3) | |
274 | can be used to restrict logging to specified levels only. | |
a2e554cc PH |
275 | .SH ATTRIBUTES |
276 | For an explanation of the terms used in this section, see | |
277 | .BR attributes (7). | |
278 | .TS | |
279 | allbox; | |
280 | lbw21 lb lb | |
281 | l l l. | |
282 | Interface Attribute Value | |
283 | T{ | |
284 | .BR openlog (), | |
285 | .BR closelog () | |
286 | T} Thread safety MT-Safe | |
287 | T{ | |
288 | .BR syslog (), | |
289 | .BR vsyslog () | |
290 | T} Thread safety MT-Safe env locale | |
291 | .TE | |
47297adb | 292 | .SH CONFORMING TO |
fea681da | 293 | The functions |
63aa9df0 MK |
294 | .BR openlog (), |
295 | .BR closelog (), | |
fea681da | 296 | and |
63aa9df0 | 297 | .BR syslog () |
fea681da | 298 | (but not |
63aa9df0 | 299 | .BR vsyslog ()) |
d865ce2d | 300 | are specified in SUSv2, POSIX.1-2001, and POSIX.1-2008. |
847e0d88 | 301 | .PP |
68e1685c | 302 | POSIX.1-2001 specifies only the |
fea681da MK |
303 | .B LOG_USER |
304 | and | |
0daa9e92 | 305 | .B LOG_LOCAL* |
fea681da MK |
306 | values for |
307 | .IR facility . | |
308 | However, with the exception of | |
0daa9e92 | 309 | .B LOG_AUTHPRIV |
fea681da MK |
310 | and |
311 | .BR LOG_FTP , | |
312 | the other | |
313 | .I facility | |
008f1ecc | 314 | values appear on most UNIX systems. |
847e0d88 | 315 | .PP |
fea681da MK |
316 | The |
317 | .B LOG_PERROR | |
318 | value for | |
319 | .I option | |
d865ce2d | 320 | is not specified by POSIX.1-2001 or POSIX.1-2008, but is available |
008f1ecc | 321 | in most versions of UNIX. |
889829be MK |
322 | .\" .SH HISTORY |
323 | .\" A | |
324 | .\" .BR syslog () | |
325 | .\" function call appeared in 4.2BSD. | |
326 | .\" 4.3BSD documents | |
327 | .\" .BR openlog (), | |
328 | .\" .BR syslog (), | |
329 | .\" .BR closelog (), | |
330 | .\" and | |
331 | .\" .BR setlogmask (). | |
332 | .\" 4.3BSD-Reno also documents | |
333 | .\" .BR vsyslog (). | |
334 | .\" Of course early v* functions used the | |
335 | .\" .I <varargs.h> | |
336 | .\" mechanism, which is not compatible with | |
337 | .\" .IR <stdarg.h> . | |
fea681da | 338 | .SH NOTES |
c4bb193f | 339 | The argument |
fea681da MK |
340 | .I ident |
341 | in the call of | |
63aa9df0 | 342 | .BR openlog () |
c13182ef MK |
343 | is probably stored as-is. |
344 | Thus, if the string it points to | |
fea681da | 345 | is changed, |
63aa9df0 | 346 | .BR syslog () |
fea681da MK |
347 | may start prepending the changed string, and if the string |
348 | it points to ceases to exist, the results are undefined. | |
349 | Most portable is to use a string constant. | |
dd3568a1 | 350 | .PP |
e5dc9f8c | 351 | Never pass a string with user-supplied data as a format, |
daac762c | 352 | use the following instead: |
a2b7a144 MK |
353 | .PP |
354 | .in +4n | |
355 | .EX | |
356 | syslog(priority, "%s", string); | |
357 | .EE | |
358 | .in | |
47297adb | 359 | .SH SEE ALSO |
84ec7d43 | 360 | .BR journalctl (1), |
d64b3725 | 361 | .BR logger (1), |
fea681da MK |
362 | .BR setlogmask (3), |
363 | .BR syslog.conf (5), | |
364 | .BR syslogd (8) |