1.\" $NetBSD: syslog.3,v 1.14 2002/10/01 16:48:35 wiz 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. 78(As denoted by the global variable 79.Va errno ; 80see 81.Xr strerror 3 . ) 82A trailing newline is added if none is present. 83.Pp 84The 85.Fn vsyslog 86function 87is an alternative form in which the arguments have already been captured 88using the variable-length argument facilities of 89.Xr varargs 3 . 90.Pp 91The message is tagged with 92.Fa priority . 93Priorities are encoded as a 94.Fa facility 95and a 96.Em level . 97The facility describes the part of the system 98generating the message. 99The level is selected from the following 100.Em ordered 101(high to low) list: 102.Bl -tag -width LOG_AUTHPRIV 103.It Dv LOG_EMERG 104A panic condition. 105This is normally broadcast to all users. 106.It Dv LOG_ALERT 107A condition that should be corrected immediately, such as a corrupted 108system database. 109.It Dv LOG_CRIT 110Critical conditions, e.g., hard device errors. 111.It Dv LOG_ERR 112Errors. 113.It Dv LOG_WARNING 114Warning messages. 115.It Dv LOG_NOTICE 116Conditions that are not error conditions, 117but should possibly be handled specially. 118.It Dv LOG_INFO 119Informational messages. 120.It Dv LOG_DEBUG 121Messages that contain information 122normally of use only when debugging a program. 123.El 124.Pp 125The 126.Fn openlog 127function 128provides for more specialized processing of the messages sent 129by 130.Fn syslog 131and 132.Fn vsyslog . 133The parameter 134.Fa ident 135is a string that will be prepended to every message. 136The 137.Fa logopt 138argument 139is a bit field specifying logging options, which is formed by 140.Tn OR Ns 'ing 141one or more of the following values: 142.Bl -tag -width LOG_AUTHPRIV 143.It Dv LOG_CONS 144If 145.Fn syslog 146cannot pass the message to 147.Xr syslogd 8 148it will attempt to write the message to the console 149.Pq Dq Pa /dev/console . 150.It Dv LOG_NDELAY 151Open the connection to 152.Xr syslogd 8 153immediately. 154Normally the open is delayed until the first message is logged. 155Useful for programs that need to manage the order in which file 156descriptors are allocated. 157.It Dv LOG_PERROR 158Write the message to standard error output as well to the system log. 159.It Dv LOG_PID 160Log the process id with each message: useful for identifying 161instantiations of daemons. 162.El 163.Pp 164The 165.Fa facility 166parameter encodes a default facility to be assigned to all messages 167that do not have an explicit facility encoded: 168.Bl -tag -width LOG_AUTHPRIV 169.It Dv LOG_AUTH 170The authorization system: 171.Xr login 1 , 172.Xr su 1 , 173.Xr getty 8 , 174etc. 175.It Dv LOG_AUTHPRIV 176The same as 177.Dv LOG_AUTH , 178but logged to a file readable only by 179selected individuals. 180.It Dv LOG_CRON 181The cron daemon: 182.Xr cron 8 . 183.It Dv LOG_DAEMON 184System daemons, such as 185.Xr routed 8 , 186that are not provided for explicitly by other facilities. 187.It Dv LOG_FTP 188The file transfer protocol daemon: 189.Xr ftpd 8 . 190.It Dv LOG_KERN 191Messages generated by the kernel. 192These cannot be generated by any user processes. 193.It Dv LOG_LPR 194The line printer spooling system: 195.Xr lpr 1 , 196.Xr lpc 8 , 197.Xr lpd 8 , 198etc. 199.It Dv LOG_MAIL 200The mail system. 201.It Dv LOG_NEWS 202The network news system. 203.It Dv LOG_SYSLOG 204Messages generated internally by 205.Xr syslogd 8 . 206.It Dv LOG_USER 207Messages generated by random user processes. 208This is the default facility identifier if none is specified. 209.It Dv LOG_UUCP 210The uucp system. 211.It Dv LOG_LOCAL0 212Reserved for local use. 213Similarly for 214.Dv LOG_LOCAL1 215through 216.Dv LOG_LOCAL7 . 217.El 218.Pp 219The 220.Fn closelog 221function 222can be used to close the log file. 223.Pp 224The 225.Fn setlogmask 226function 227sets the log priority mask to 228.Fa maskpri 229and returns the previous mask. 230Calls to 231.Fn syslog 232with a priority not set in 233.Fa maskpri 234are rejected. 235The mask for an individual priority 236.Fa pri 237is calculated by the macro 238.Fn LOG_MASK pri ; 239the mask for all priorities up to and including 240.Fa toppri 241is given by the macro 242.Fn LOG_UPTO toppri ; . 243The default allows all priorities to be logged. 244.Sh RETURN VALUES 245The routines 246.Fn closelog , 247.Fn openlog , 248.Fn syslog 249and 250.Fn vsyslog 251return no value. 252.Pp 253The routine 254.Fn setlogmask 255always returns the previous log mask level. 256.Sh EXAMPLES 257.Bd -literal -offset indent -compact 258syslog(LOG_ALERT, "who: internal error 23"); 259 260openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP); 261 262setlogmask(LOG_UPTO(LOG_ERR)); 263 264syslog(LOG_INFO, "Connection from host %d", CallingHost); 265 266syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); 267.Ed 268.Sh SEE ALSO 269.Xr logger 1 , 270.Xr syslogd 8 271.Sh HISTORY 272These 273functions appeared in 274.Bx 4.2 . 275.Sh CAVEATS 276It is important never to pass a string with user-supplied data as a 277format without using 278.Ql %s . 279An attacker can put format specifiers in the string to mangle your stack, 280leading to a possible security hole. 281This holds true even if you have built the string 282.Dq by hand 283using a function like 284.Fn snprintf , 285as the resulting string may still contain user-supplied conversion specifiers 286for later interpolation by 287.Fn syslog . 288.Pp 289Always be sure to use the proper secure idiom: 290.Bd -literal -offset indent 291syslog(priority, "%s", string); 292.Ed 293