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. 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.Dd July 3, 2023 29.Dt SYSLOG 3 30.Os 31.Sh NAME 32.Nm syslog , 33.Nm vsyslog , 34.Nm openlog , 35.Nm closelog , 36.Nm setlogmask 37.Nd control system log 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In syslog.h 42.Ft void 43.Fn syslog "int priority" "const char *message" "..." 44.Ft void 45.Fn openlog "const char *ident" "int logopt" "int facility" 46.Ft void 47.Fn closelog void 48.Ft int 49.Fn setlogmask "int maskpri" 50.In syslog.h 51.In stdarg.h 52.Ft void 53.Fn vsyslog "int priority" "const char *message" "va_list args" 54.Sh DESCRIPTION 55The 56.Fn syslog 57function 58writes 59.Fa message 60to the system message logger. 61The message is then written to the system console, log files, 62logged-in users, or forwarded to other machines as appropriate. 63(See 64.Xr syslogd 8 . ) 65.Pp 66The message is identical to a 67.Xr printf 3 68format string, except that 69.Ql %m 70is replaced by the current error 71message. 72(As denoted by the global variable 73.Va errno ; 74see 75.Xr strerror 3 . ) 76A trailing newline is added if none is present. 77.Pp 78The 79.Fn vsyslog 80function 81is an alternate form in which the arguments have already been captured 82using the variable-length argument facilities of 83.Xr stdarg 3 . 84.Pp 85The message is tagged with 86.Fa priority . 87Priorities are encoded as a 88.Fa facility 89and a 90.Em level . 91The facility describes the part of the system 92generating the message. 93The level is selected from the following 94.Em ordered 95(high to low) list: 96.Bl -tag -width LOG_AUTHPRIV 97.It Dv LOG_EMERG 98A panic condition. 99This is normally broadcast to all users. 100.It Dv LOG_ALERT 101A condition that should be corrected immediately, such as a corrupted 102system database. 103.It Dv LOG_CRIT 104Critical conditions, e.g., hard device errors. 105.It Dv LOG_ERR 106Errors. 107.It Dv LOG_WARNING 108Warning messages. 109.It Dv LOG_NOTICE 110Conditions that are not error conditions, 111but should possibly be handled specially. 112.It Dv LOG_INFO 113Informational messages. 114.It Dv LOG_DEBUG 115Messages that contain information 116normally of use only when debugging a program. 117.El 118.Pp 119The 120.Fn openlog 121function 122provides for more specialized processing of the messages sent 123by 124.Fn syslog 125and 126.Fn vsyslog . 127The 128.Fa ident 129argument 130is a string that will be prepended to every message. 131It may be formatted as 132.Fa ident[N] 133in which case decimal number 134.Fa N 135replaces the process id within messages. 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. 162On 163.Fx , 164this option is enabled by default and cannot be disabled. 165.El 166.Pp 167The 168.Fa facility 169argument encodes a default facility to be assigned to all messages 170that do not have an explicit facility encoded: 171.Bl -tag -width LOG_AUTHPRIV 172.It Dv LOG_AUTH 173The authorization system: 174.Xr login 1 , 175.Xr su 1 , 176.Xr getty 8 , 177etc. 178.It Dv LOG_AUTHPRIV 179The same as 180.Dv LOG_AUTH , 181but logged to a file readable only by 182selected individuals. 183.It Dv LOG_CONSOLE 184Messages written to 185.Pa /dev/console 186by the kernel console output driver. 187.It Dv LOG_CRON 188The cron daemon: 189.Xr cron 8 . 190.It Dv LOG_DAEMON 191System daemons, such as 192.Xr routed 8 , 193that are not provided for explicitly by other facilities. 194.It Dv LOG_FTP 195The file transfer protocol daemons: 196.Xr ftpd 8 , 197.Xr tftpd 8 . 198.It Dv LOG_KERN 199Messages generated by the kernel. 200These cannot be generated by any user processes. 201.It Dv LOG_LPR 202The line printer spooling system: 203.Xr lpr 1 , 204.Xr lpc 8 , 205.Xr lpd 8 , 206etc. 207.It Dv LOG_MAIL 208The mail system. 209.It Dv LOG_NEWS 210The network news system. 211.It Dv LOG_NTP 212The network time protocol system. 213.It Dv LOG_SECURITY 214Security subsystems, such as 215.Xr ipfw 4 . 216.It Dv LOG_SYSLOG 217Messages generated internally by 218.Xr syslogd 8 . 219.It Dv LOG_USER 220Messages generated by random user processes. 221This is the default facility identifier if none is specified. 222.It Dv LOG_UUCP 223The uucp system. 224.It Dv LOG_LOCAL0 225Reserved for local use. 226Similarly for 227.Dv LOG_LOCAL1 228through 229.Dv LOG_LOCAL7 . 230.El 231.Pp 232The 233.Fn closelog 234function 235can be used to close the log file. 236.Pp 237The 238.Fn setlogmask 239function 240sets the log priority mask to 241.Fa maskpri 242and returns the previous mask. 243Calls to 244.Fn syslog 245with a priority not set in 246.Fa maskpri 247are rejected. 248The mask for an individual priority 249.Fa pri 250is calculated by the macro 251.Fn LOG_MASK pri ; 252the mask for all priorities up to and including 253.Fa toppri 254is given by the macro 255.Fn LOG_UPTO toppri ; . 256The default allows all priorities to be logged. 257.Sh RETURN VALUES 258The routines 259.Fn closelog , 260.Fn openlog , 261.Fn syslog 262and 263.Fn vsyslog 264return no value. 265.Pp 266The routine 267.Fn setlogmask 268always returns the previous log mask level. 269.Sh EXAMPLES 270.Bd -literal -offset indent -compact 271syslog(LOG_ALERT, "who: internal error 23"); 272 273openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP); 274 275setlogmask(LOG_UPTO(LOG_ERR)); 276 277syslog(LOG_INFO, "Connection from host %d", CallingHost); 278 279syslog(LOG_ERR|LOG_LOCAL2, "foobar error: %m"); 280.Ed 281.Sh SEE ALSO 282.Xr logger 1 , 283.Xr syslogd 8 284.Sh HISTORY 285These 286functions appeared in 287.Bx 4.2 . 288.Sh BUGS 289Never pass a string with user-supplied data as a format without using 290.Ql %s . 291An attacker can put format specifiers in the string to mangle your stack, 292leading to a possible security hole. 293This holds true even if the string was built using a function like 294.Fn snprintf , 295as the resulting string may still contain user-supplied conversion specifiers 296for later interpolation by 297.Fn syslog . 298.Pp 299Always use the proper secure idiom: 300.Pp 301.Dl syslog(priority, \*q%s\*q, string); 302