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