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