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