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