Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1985, 1991 The Regents of the University of California. |
5442f39e | 2 | .\" All rights reserved. |
609b3d57 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
5442f39e | 5 | .\" |
ae59e04c | 6 | .\" @(#)syslog.3 6.17 (Berkeley) %G% |
609b3d57 | 7 | .\" |
ae59e04c CL |
8 | .Dd |
9 | .Dt SYSLOG 3 | |
10 | .Os BSD 4.2 | |
11 | .Sh NAME | |
12 | .Nm syslog , | |
13 | .Nm vsyslog , | |
14 | .Nm openlog , | |
15 | .Nm closelog , | |
16 | .Nm setlogmask | |
17 | .Nd control system log | |
18 | .Sh SYNOPSIS | |
19 | .Fd #include <syslog.h> | |
20 | .Fd #include <varargs.h> | |
21 | .Ft void | |
22 | .Fn syslog "int priority" "const char *message" "..." | |
23 | .Ft void | |
24 | .Fn vsyslog "int priority" "const char *message" "va_list args" | |
25 | .Ft void | |
26 | .Fn openlog "const char *ident" "int logopt" "int facility" | |
27 | .Ft void | |
28 | .Fn closelog void | |
29 | .Ft int | |
30 | .Fn setlogmask "int maskpri" | |
31 | .Sh DESCRIPTION | |
32 | The | |
33 | .Fn syslog | |
34 | function | |
51dad0a9 | 35 | writes |
ae59e04c | 36 | .Fa message |
51dad0a9 | 37 | to the system message logger. |
ae59e04c CL |
38 | The message is then written to the system console, log files, |
39 | logged-in users, or forwarded to other machines as appropriate. (See | |
40 | .Xr syslogd 8 . ) | |
41 | .Pp | |
51dad0a9 | 42 | The message is identical to a |
ae59e04c CL |
43 | .Xr printf 3 |
44 | format string, except that | |
45 | .Ql %m | |
46 | is replaced by the current error | |
47 | message. (As denoted by the global variable | |
48 | .Va errno ; | |
51dad0a9 | 49 | see |
ae59e04c | 50 | .Xr strerror 3 . ) |
51dad0a9 | 51 | A trailing newline is added if none is present. |
ae59e04c CL |
52 | .Pp |
53 | The | |
54 | .Fn vsyslog | |
55 | function | |
51dad0a9 KB |
56 | is an alternate form in which the arguments have already been captured |
57 | using the variable-length argument facilities of | |
ae59e04c CL |
58 | .Xr varargs 3 . |
59 | .Pp | |
51dad0a9 | 60 | The message is tagged with |
ae59e04c | 61 | .Fa priority . |
be78fd26 | 62 | Priorities are encoded as a |
ae59e04c | 63 | .Fa facility |
be78fd26 | 64 | and a |
ae59e04c | 65 | .Em level . |
be78fd26 EA |
66 | The facility describes the part of the system |
67 | generating the message. | |
51dad0a9 | 68 | The level is selected from the following |
ae59e04c | 69 | .Em ordered |
51dad0a9 | 70 | (high to low) list: |
ae59e04c CL |
71 | .Bl -tag -width LOG_AUTHPRIV |
72 | .It Dv LOG_EMERG | |
3f4b96b5 KB |
73 | A panic condition. |
74 | This is normally broadcast to all users. | |
ae59e04c | 75 | .It Dv LOG_ALERT |
51dad0a9 KB |
76 | A condition that should be corrected immediately, such as a corrupted |
77 | system database. | |
ae59e04c | 78 | .It Dv LOG_CRIT |
51dad0a9 | 79 | Critical conditions, e.g., hard device errors. |
ae59e04c | 80 | .It Dv LOG_ERR |
be78fd26 | 81 | Errors. |
ae59e04c | 82 | .It Dv LOG_WARNING |
51dad0a9 | 83 | Warning messages. |
ae59e04c | 84 | .It Dv LOG_NOTICE |
be78fd26 EA |
85 | Conditions that are not error conditions, |
86 | but should possibly be handled specially. | |
ae59e04c | 87 | .It Dv LOG_INFO |
51dad0a9 | 88 | Informational messages. |
ae59e04c | 89 | .It Dv LOG_DEBUG |
51dad0a9 KB |
90 | Messages that contain information |
91 | normally of use only when debugging a program. | |
ae59e04c CL |
92 | .El |
93 | .Pp | |
94 | The | |
95 | .Fn openlog | |
96 | function | |
51dad0a9 KB |
97 | provides for more specialized processing of the messages sent |
98 | by | |
ae59e04c | 99 | .Fn syslog |
51dad0a9 | 100 | and |
ae59e04c | 101 | .Fn vsyslog . |
ed6316b8 | 102 | The parameter |
ae59e04c | 103 | .Fa ident |
51dad0a9 | 104 | is a string that will be prepended to every message. |
ae59e04c CL |
105 | The |
106 | .Fa logopt | |
107 | argument | |
51dad0a9 | 108 | is a bit field specifying logging options, which is formed by |
ae59e04c | 109 | .Tn OR Ns 'ing |
51dad0a9 | 110 | one or more of the following values: |
ae59e04c CL |
111 | .Bl -tag -width LOG_AUTHPRIV |
112 | .It Dv LOG_CONS | |
51dad0a9 | 113 | If |
ae59e04c | 114 | .Fn syslog |
51dad0a9 | 115 | cannot pass the message to |
ae59e04c CL |
116 | .Xr syslogd |
117 | it will attempt to write the message to the console | |
118 | .Pq Dq Pa /dev/console. | |
119 | .It Dv LOG_NDELAY | |
6a71ef00 | 120 | Open the connection to |
ae59e04c | 121 | .Xr syslogd |
0c9a57bf | 122 | immediately. |
51dad0a9 KB |
123 | Normally the open is delayed until the first message is logged. |
124 | Useful for programs that need to manage the order in which file | |
125 | descriptors are allocated. | |
ae59e04c | 126 | .It Dv LOG_PERROR |
51dad0a9 | 127 | Write the message to standard error output as well to the system log. |
ae59e04c | 128 | .It Dv LOG_PID |
51dad0a9 KB |
129 | Log the process id with each message: useful for identifying |
130 | instantiations of daemons. | |
ae59e04c CL |
131 | .El |
132 | .Pp | |
ed6316b8 | 133 | The |
ae59e04c | 134 | .Fa facility |
6a71ef00 | 135 | parameter encodes a default facility to be assigned to all messages |
be78fd26 | 136 | that do not have an explicit facility encoded: |
ae59e04c CL |
137 | .Bl -tag -width LOG_AUTHPRIV |
138 | .It Dv LOG_AUTH | |
3f4b96b5 | 139 | The authorization system: |
ae59e04c CL |
140 | .Xr login 1 , |
141 | .Xr su 1 , | |
142 | .Xr getty 8 , | |
3f4b96b5 | 143 | etc. |
ae59e04c CL |
144 | .It Dv LOG_AUTHPRIV |
145 | The same as | |
146 | .Dv LOG_AUTH , | |
147 | but logged to a file readable only by | |
51dad0a9 | 148 | selected individuals. |
ae59e04c | 149 | .It Dv LOG_CRON |
3f4b96b5 | 150 | The clock daemon. |
ae59e04c | 151 | .It Dv LOG_DAEMON |
be78fd26 | 152 | System daemons, such as |
ae59e04c CL |
153 | .Xr ftpd 8 , |
154 | .Xr routed 8 , | |
51dad0a9 | 155 | etc., that are not provided for explicitly by other facilities. |
ae59e04c | 156 | .It Dv LOG_KERN |
3f4b96b5 KB |
157 | Messages generated by the kernel. |
158 | These cannot be generated by any user processes. | |
ae59e04c | 159 | .It Dv LOG_LPR |
a4e75007 | 160 | The line printer spooling system: |
ae59e04c CL |
161 | .Xr lpr 1 , |
162 | .Xr lpc 8 , | |
163 | .Xr lpd 8 , | |
a4e75007 | 164 | etc. |
ae59e04c | 165 | .It Dv LOG_MAIL |
3f4b96b5 | 166 | The mail system. |
ae59e04c | 167 | .It Dv LOG_NEWS |
c262cc40 | 168 | The network news system. |
ae59e04c | 169 | .It Dv LOG_SYSLOG |
3f4b96b5 | 170 | Messages generated internally by |
ae59e04c CL |
171 | .Xr syslogd 8 . |
172 | .It Dv LOG_USER | |
3f4b96b5 KB |
173 | Messages generated by random user processes. |
174 | This is the default facility identifier if none is specified. | |
ae59e04c | 175 | .It Dv LOG_UUCP |
c262cc40 | 176 | The uucp system. |
ae59e04c | 177 | .It Dv LOG_LOCAL0 |
be78fd26 | 178 | Reserved for local use. |
ae59e04c CL |
179 | Similarly for |
180 | .Dv LOG_LOCAL1 | |
181 | through | |
182 | .Dv LOG_LOCAL7 . | |
183 | .El | |
184 | .Pp | |
185 | The | |
186 | .Fn closelog | |
187 | function | |
609b3d57 | 188 | can be used to close the log file. |
ae59e04c CL |
189 | .Pp |
190 | The | |
191 | .Fn setlogmask | |
192 | function | |
ed6316b8 | 193 | sets the log priority mask to |
ae59e04c | 194 | .Fa maskpri |
ed6316b8 | 195 | and returns the previous mask. |
be78fd26 | 196 | Calls to |
ae59e04c | 197 | .Fn syslog |
6a71ef00 | 198 | with a priority not set in |
ae59e04c | 199 | .Fa maskpri |
be78fd26 | 200 | are rejected. |
6a71ef00 | 201 | The mask for an individual priority |
ae59e04c CL |
202 | .Fa pri |
203 | is calculated by the macro | |
204 | .Fn LOG_MASK pri ; | |
6a71ef00 | 205 | the mask for all priorities up to and including |
ae59e04c CL |
206 | .Fa toppri |
207 | is given by the macro | |
208 | .Fn LOG_UPTO toppri ; . | |
be78fd26 | 209 | The default allows all priorities to be logged. |
ae59e04c CL |
210 | .Sh RETURN VALUES |
211 | The routines | |
212 | .Fn closelog , | |
213 | .Fn openlog , | |
214 | .Fn syslog | |
215 | and | |
216 | .Fn vsyslog | |
217 | return no value. | |
218 | .Pp | |
219 | The routine | |
220 | .Fn setlogmask | |
221 | always returns the previous log mask level. | |
222 | .Sh EXAMPLES | |
223 | .Bd -literal -offset indent -compact | |
be78fd26 | 224 | syslog(LOG_ALERT, "who: internal error 23"); |
609b3d57 | 225 | |
be78fd26 | 226 | openlog("ftpd", LOG_PID, LOG_DAEMON); |
6a71ef00 | 227 | setlogmask(LOG_UPTO(LOG_ERR)); |
609b3d57 | 228 | syslog(LOG_INFO, "Connection from host %d", CallingHost); |
be78fd26 EA |
229 | |
230 | syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); | |
ae59e04c CL |
231 | .Ed |
232 | .Sh SEE ALSO | |
233 | .Xr logger 1 , | |
234 | .Xr syslogd 8 | |
235 | .Sh HISTORY | |
236 | These | |
237 | functions appeared in | |
238 | .Bx 4.2 . |