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