xref: /freebsd/lib/libc/gen/syslog.3 (revision ee12faa062c04a49bf6fe4e6867bad8606e2413f)
1.\" Copyright (c) 1985, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)syslog.3	8.1 (Berkeley) 6/4/93
29.\"
30.Dd July 3, 2023
31.Dt SYSLOG 3
32.Os
33.Sh NAME
34.Nm syslog ,
35.Nm vsyslog ,
36.Nm openlog ,
37.Nm closelog ,
38.Nm setlogmask
39.Nd control system log
40.Sh LIBRARY
41.Lb libc
42.Sh SYNOPSIS
43.In syslog.h
44.Ft void
45.Fn syslog "int priority" "const char *message" "..."
46.Ft void
47.Fn openlog "const char *ident" "int logopt" "int facility"
48.Ft void
49.Fn closelog void
50.Ft int
51.Fn setlogmask "int maskpri"
52.In syslog.h
53.In stdarg.h
54.Ft void
55.Fn vsyslog "int priority" "const char *message" "va_list args"
56.Sh DESCRIPTION
57The
58.Fn syslog
59function
60writes
61.Fa message
62to the system message logger.
63The message is then written to the system console, log files,
64logged-in users, or forwarded to other machines as appropriate.
65(See
66.Xr syslogd 8 . )
67.Pp
68The message is identical to a
69.Xr printf 3
70format string, except that
71.Ql %m
72is replaced by the current error
73message.
74(As denoted by the global variable
75.Va errno ;
76see
77.Xr strerror 3 . )
78A trailing newline is added if none is present.
79.Pp
80The
81.Fn vsyslog
82function
83is an alternate form in which the arguments have already been captured
84using the variable-length argument facilities of
85.Xr stdarg 3 .
86.Pp
87The message is tagged with
88.Fa priority .
89Priorities are encoded as a
90.Fa facility
91and a
92.Em level .
93The facility describes the part of the system
94generating the message.
95The level is selected from the following
96.Em ordered
97(high to low) list:
98.Bl -tag -width LOG_AUTHPRIV
99.It Dv LOG_EMERG
100A panic condition.
101This is normally broadcast to all users.
102.It Dv LOG_ALERT
103A condition that should be corrected immediately, such as a corrupted
104system database.
105.It Dv LOG_CRIT
106Critical conditions, e.g., hard device errors.
107.It Dv LOG_ERR
108Errors.
109.It Dv LOG_WARNING
110Warning messages.
111.It Dv LOG_NOTICE
112Conditions that are not error conditions,
113but should possibly be handled specially.
114.It Dv LOG_INFO
115Informational messages.
116.It Dv LOG_DEBUG
117Messages that contain information
118normally of use only when debugging a program.
119.El
120.Pp
121The
122.Fn openlog
123function
124provides for more specialized processing of the messages sent
125by
126.Fn syslog
127and
128.Fn vsyslog .
129The
130.Fa ident
131argument
132is a string that will be prepended to every message.
133It may be formatted as
134.Fa ident[N]
135in which case decimal number
136.Fa N
137replaces the process id within messages.
138The
139.Fa logopt
140argument
141is a bit field specifying logging options, which is formed by
142.Tn OR Ns 'ing
143one or more of the following values:
144.Bl -tag -width LOG_AUTHPRIV
145.It Dv LOG_CONS
146If
147.Fn syslog
148cannot pass the message to
149.Xr syslogd 8
150it will attempt to write the message to the console
151.Pq Dq Pa /dev/console .
152.It Dv LOG_NDELAY
153Open the connection to
154.Xr syslogd 8
155immediately.
156Normally the open is delayed until the first message is logged.
157Useful for programs that need to manage the order in which file
158descriptors are allocated.
159.It Dv LOG_PERROR
160Write the message to standard error output as well to the system log.
161.It Dv LOG_PID
162Log the process id with each message: useful for identifying
163instantiations of daemons.
164On
165.Fx ,
166this option is enabled by default and cannot be disabled.
167.El
168.Pp
169The
170.Fa facility
171argument encodes a default facility to be assigned to all messages
172that do not have an explicit facility encoded:
173.Bl -tag -width LOG_AUTHPRIV
174.It Dv LOG_AUTH
175The authorization system:
176.Xr login 1 ,
177.Xr su 1 ,
178.Xr getty 8 ,
179etc.
180.It Dv LOG_AUTHPRIV
181The same as
182.Dv LOG_AUTH ,
183but logged to a file readable only by
184selected individuals.
185.It Dv LOG_CONSOLE
186Messages written to
187.Pa /dev/console
188by the kernel console output driver.
189.It Dv LOG_CRON
190The cron daemon:
191.Xr cron 8 .
192.It Dv LOG_DAEMON
193System daemons, such as
194.Xr routed 8 ,
195that are not provided for explicitly by other facilities.
196.It Dv LOG_FTP
197The file transfer protocol daemons:
198.Xr ftpd 8 ,
199.Xr tftpd 8 .
200.It Dv LOG_KERN
201Messages generated by the kernel.
202These cannot be generated by any user processes.
203.It Dv LOG_LPR
204The line printer spooling system:
205.Xr lpr 1 ,
206.Xr lpc 8 ,
207.Xr lpd 8 ,
208etc.
209.It Dv LOG_MAIL
210The mail system.
211.It Dv LOG_NEWS
212The network news system.
213.It Dv LOG_NTP
214The network time protocol system.
215.It Dv LOG_SECURITY
216Security subsystems, such as
217.Xr ipfw 4 .
218.It Dv LOG_SYSLOG
219Messages generated internally by
220.Xr syslogd 8 .
221.It Dv LOG_USER
222Messages generated by random user processes.
223This is the default facility identifier if none is specified.
224.It Dv LOG_UUCP
225The uucp system.
226.It Dv LOG_LOCAL0
227Reserved for local use.
228Similarly for
229.Dv LOG_LOCAL1
230through
231.Dv LOG_LOCAL7 .
232.El
233.Pp
234The
235.Fn closelog
236function
237can be used to close the log file.
238.Pp
239The
240.Fn setlogmask
241function
242sets the log priority mask to
243.Fa maskpri
244and returns the previous mask.
245Calls to
246.Fn syslog
247with a priority not set in
248.Fa maskpri
249are rejected.
250The mask for an individual priority
251.Fa pri
252is calculated by the macro
253.Fn LOG_MASK pri ;
254the mask for all priorities up to and including
255.Fa toppri
256is given by the macro
257.Fn LOG_UPTO toppri ; .
258The default allows all priorities to be logged.
259.Sh RETURN VALUES
260The routines
261.Fn closelog ,
262.Fn openlog ,
263.Fn syslog
264and
265.Fn vsyslog
266return no value.
267.Pp
268The routine
269.Fn setlogmask
270always returns the previous log mask level.
271.Sh EXAMPLES
272.Bd -literal -offset indent -compact
273syslog(LOG_ALERT, "who: internal error 23");
274
275openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP);
276
277setlogmask(LOG_UPTO(LOG_ERR));
278
279syslog(LOG_INFO, "Connection from host %d", CallingHost);
280
281syslog(LOG_ERR|LOG_LOCAL2, "foobar error: %m");
282.Ed
283.Sh SEE ALSO
284.Xr logger 1 ,
285.Xr syslogd 8
286.Sh HISTORY
287These
288functions appeared in
289.Bx 4.2 .
290.Sh BUGS
291Never pass a string with user-supplied data as a format without using
292.Ql %s .
293An attacker can put format specifiers in the string to mangle your stack,
294leading to a possible security hole.
295This holds true even if the string was built using a function like
296.Fn snprintf ,
297as the resulting string may still contain user-supplied conversion specifiers
298for later interpolation by
299.Fn syslog .
300.Pp
301Always use the proper secure idiom:
302.Pp
303.Dl syslog(priority, \*q%s\*q, string);
304