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