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$ 34.\" 35.Dd June 4, 1993 36.Dt SYSLOG 3 37.Os BSD 4.2 38.Sh NAME 39.Nm syslog , 40.Nm vsyslog , 41.Nm openlog , 42.Nm closelog , 43.Nm setlogmask 44.Nd control system log 45.Sh SYNOPSIS 46.Fd #include <syslog.h> 47.Fd #include <varargs.h> 48.Ft void 49.Fn syslog "int priority" "const char *message" "..." 50.Ft void 51.Fn vsyslog "int priority" "const char *message" "va_list args" 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.Sh DESCRIPTION 59The 60.Fn syslog 61function 62writes 63.Fa message 64to the system message logger. 65The message is then written to the system console, log files, 66logged-in users, or forwarded to other machines as appropriate. (See 67.Xr syslogd 8 . ) 68.Pp 69The message is identical to a 70.Xr printf 3 71format string, except that 72.Ql %m 73is replaced by the current error 74message. (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 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.El 159.Pp 160The 161.Fa facility 162parameter encodes a default facility to be assigned to all messages 163that do not have an explicit facility encoded: 164.Bl -tag -width LOG_AUTHPRIV 165.It Dv LOG_AUTH 166The authorization system: 167.Xr login 1 , 168.Xr su 1 , 169.Xr getty 8 , 170etc. 171.It Dv LOG_AUTHPRIV 172The same as 173.Dv LOG_AUTH , 174but logged to a file readable only by 175selected individuals. 176.It Dv LOG_CRON 177The cron daemon: 178.Xr cron 8 . 179.It Dv LOG_DAEMON 180System daemons, such as 181.Xr routed 8 , 182that are not provided for explicitly by other facilities. 183.It Dv LOG_FTP 184The file transfer protocol daemons: 185.Xr ftpd 8 , 186.Xr tftpd 8 . 187.It Dv LOG_KERN 188Messages generated by the kernel. 189These cannot be generated by any user processes. 190.It Dv LOG_LPR 191The line printer spooling system: 192.Xr lpr 1 , 193.Xr lpc 8 , 194.Xr lpd 8 , 195etc. 196.It Dv LOG_MAIL 197The mail system. 198.It Dv LOG_NEWS 199The network news system. 200.It Dv LOG_SECURITY 201Security subsystems, such as 202.It Dv LOG_SYSLOG 203Messages generated internally by 204.Xr syslogd 8 . 205.It Dv LOG_USER 206Messages generated by random user processes. 207This is the default facility identifier if none is specified. 208.It Dv LOG_UUCP 209The uucp system. 210.Xr ipfw 4 . 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