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