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 $ 34.\" $DragonFly: src/lib/libc/gen/syslog.3,v 1.2 2003/06/17 04:26:42 dillon Exp $ 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 . 284