Debian Codegraph @

upstream/debian-unstable/man3/syslog.3

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