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