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