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