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