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.\" 4. 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$ 30.\" 31.Dd July 21, 2015 32.Dt SYSLOG 3 33.Os 34.Sh NAME 35.Nm syslog , 36.Nm vsyslog , 37.Nm openlog , 38.Nm closelog , 39.Nm setlogmask 40.Nd control system log 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In syslog.h 45.In stdarg.h 46.Ft void 47.Fn syslog "int priority" "const char *message" "..." 48.Ft void 49.Fn vsyslog "int priority" "const char *message" "va_list args" 50.Ft void 51.Fn openlog "const char *ident" "int logopt" "int facility" 52.Ft void 53.Fn closelog void 54.Ft int 55.Fn setlogmask "int maskpri" 56.Sh DESCRIPTION 57The 58.Fn syslog 59function 60writes 61.Fa message 62to the system message logger. 63The message is then written to the system console, log files, 64logged-in users, or forwarded to other machines as appropriate. 65(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 alternate form in which the arguments have already been captured 84using the variable-length argument facilities of 85.Xr stdarg 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 130.Fa ident 131argument 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 163argument 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_NTP 206The network time protocol system. 207.It Dv LOG_SECURITY 208Security subsystems, such as 209.Xr ipfw 4 . 210.It Dv LOG_SYSLOG 211Messages generated internally by 212.Xr syslogd 8 . 213.It Dv LOG_USER 214Messages generated by random user processes. 215This is the default facility identifier if none is specified. 216.It Dv LOG_UUCP 217The uucp system. 218.It Dv LOG_LOCAL0 219Reserved for local use. 220Similarly for 221.Dv LOG_LOCAL1 222through 223.Dv LOG_LOCAL7 . 224.El 225.Pp 226The 227.Fn closelog 228function 229can be used to close the log file. 230.Pp 231The 232.Fn setlogmask 233function 234sets the log priority mask to 235.Fa maskpri 236and returns the previous mask. 237Calls to 238.Fn syslog 239with a priority not set in 240.Fa maskpri 241are rejected. 242The mask for an individual priority 243.Fa pri 244is calculated by the macro 245.Fn LOG_MASK pri ; 246the mask for all priorities up to and including 247.Fa toppri 248is given by the macro 249.Fn LOG_UPTO toppri ; . 250The default allows all priorities to be logged. 251.Sh RETURN VALUES 252The routines 253.Fn closelog , 254.Fn openlog , 255.Fn syslog 256and 257.Fn vsyslog 258return no value. 259.Pp 260The routine 261.Fn setlogmask 262always returns the previous log mask level. 263.Sh EXAMPLES 264.Bd -literal -offset indent -compact 265syslog(LOG_ALERT, "who: internal error 23"); 266 267openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP); 268 269setlogmask(LOG_UPTO(LOG_ERR)); 270 271syslog(LOG_INFO, "Connection from host %d", CallingHost); 272 273syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); 274.Ed 275.Sh SEE ALSO 276.Xr logger 1 , 277.Xr syslogd 8 278.Sh HISTORY 279These 280functions appeared in 281.Bx 4.2 . 282.Sh BUGS 283Never pass a string with user-supplied data as a format without using 284.Ql %s . 285An attacker can put format specifiers in the string to mangle your stack, 286leading to a possible security hole. 287This holds true even if the string was built using a function like 288.Fn snprintf , 289as the resulting string may still contain user-supplied conversion specifiers 290for later interpolation by 291.Fn syslog . 292.Pp 293Always use the proper secure idiom: 294.Pp 295.Dl syslog(priority, "%s", string); 296