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