1.\" Copyright (c) 1985, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)syslog.3 8.1 (Berkeley) 06/04/93 7.\" 8.Dd 9.Dt SYSLOG 3 10.Os BSD 4.2 11.Sh NAME 12.Nm syslog , 13.Nm vsyslog , 14.Nm openlog , 15.Nm closelog , 16.Nm setlogmask 17.Nd control system log 18.Sh SYNOPSIS 19.Fd #include <syslog.h> 20.Fd #include <varargs.h> 21.Ft void 22.Fn syslog "int priority" "const char *message" "..." 23.Ft void 24.Fn vsyslog "int priority" "const char *message" "va_list args" 25.Ft void 26.Fn openlog "const char *ident" "int logopt" "int facility" 27.Ft void 28.Fn closelog void 29.Ft int 30.Fn setlogmask "int maskpri" 31.Sh DESCRIPTION 32The 33.Fn syslog 34function 35writes 36.Fa message 37to the system message logger. 38The message is then written to the system console, log files, 39logged-in users, or forwarded to other machines as appropriate. (See 40.Xr syslogd 8 . ) 41.Pp 42The message is identical to a 43.Xr printf 3 44format string, except that 45.Ql %m 46is replaced by the current error 47message. (As denoted by the global variable 48.Va errno ; 49see 50.Xr strerror 3 . ) 51A trailing newline is added if none is present. 52.Pp 53The 54.Fn vsyslog 55function 56is an alternate form in which the arguments have already been captured 57using the variable-length argument facilities of 58.Xr varargs 3 . 59.Pp 60The message is tagged with 61.Fa priority . 62Priorities are encoded as a 63.Fa facility 64and a 65.Em level . 66The facility describes the part of the system 67generating the message. 68The level is selected from the following 69.Em ordered 70(high to low) list: 71.Bl -tag -width LOG_AUTHPRIV 72.It Dv LOG_EMERG 73A panic condition. 74This is normally broadcast to all users. 75.It Dv LOG_ALERT 76A condition that should be corrected immediately, such as a corrupted 77system database. 78.It Dv LOG_CRIT 79Critical conditions, e.g., hard device errors. 80.It Dv LOG_ERR 81Errors. 82.It Dv LOG_WARNING 83Warning messages. 84.It Dv LOG_NOTICE 85Conditions that are not error conditions, 86but should possibly be handled specially. 87.It Dv LOG_INFO 88Informational messages. 89.It Dv LOG_DEBUG 90Messages that contain information 91normally of use only when debugging a program. 92.El 93.Pp 94The 95.Fn openlog 96function 97provides for more specialized processing of the messages sent 98by 99.Fn syslog 100and 101.Fn vsyslog . 102The parameter 103.Fa ident 104is a string that will be prepended to every message. 105The 106.Fa logopt 107argument 108is a bit field specifying logging options, which is formed by 109.Tn OR Ns 'ing 110one or more of the following values: 111.Bl -tag -width LOG_AUTHPRIV 112.It Dv LOG_CONS 113If 114.Fn syslog 115cannot pass the message to 116.Xr syslogd 117it will attempt to write the message to the console 118.Pq Dq Pa /dev/console. 119.It Dv LOG_NDELAY 120Open the connection to 121.Xr syslogd 122immediately. 123Normally the open is delayed until the first message is logged. 124Useful for programs that need to manage the order in which file 125descriptors are allocated. 126.It Dv LOG_PERROR 127Write the message to standard error output as well to the system log. 128.It Dv LOG_PID 129Log the process id with each message: useful for identifying 130instantiations of daemons. 131.El 132.Pp 133The 134.Fa facility 135parameter encodes a default facility to be assigned to all messages 136that do not have an explicit facility encoded: 137.Bl -tag -width LOG_AUTHPRIV 138.It Dv LOG_AUTH 139The authorization system: 140.Xr login 1 , 141.Xr su 1 , 142.Xr getty 8 , 143etc. 144.It Dv LOG_AUTHPRIV 145The same as 146.Dv LOG_AUTH , 147but logged to a file readable only by 148selected individuals. 149.It Dv LOG_CRON 150The clock daemon. 151.It Dv LOG_DAEMON 152System daemons, such as 153.Xr routed 8 , 154that are not provided for explicitly by other facilities. 155.It Dv LOG_KERN 156Messages generated by the kernel. 157These cannot be generated by any user processes. 158.It Dv LOG_LPR 159The line printer spooling system: 160.Xr lpr 1 , 161.Xr lpc 8 , 162.Xr lpd 8 , 163etc. 164.It Dv LOG_MAIL 165The mail system. 166.It Dv LOG_NEWS 167The network news system. 168.It Dv LOG_SYSLOG 169Messages generated internally by 170.Xr syslogd 8 . 171.It Dv LOG_USER 172Messages generated by random user processes. 173This is the default facility identifier if none is specified. 174.It Dv LOG_UUCP 175The uucp system. 176.It Dv LOG_LOCAL0 177Reserved for local use. 178Similarly for 179.Dv LOG_LOCAL1 180through 181.Dv LOG_LOCAL7 . 182.El 183.Pp 184The 185.Fn closelog 186function 187can be used to close the log file. 188.Pp 189The 190.Fn setlogmask 191function 192sets the log priority mask to 193.Fa maskpri 194and returns the previous mask. 195Calls to 196.Fn syslog 197with a priority not set in 198.Fa maskpri 199are rejected. 200The mask for an individual priority 201.Fa pri 202is calculated by the macro 203.Fn LOG_MASK pri ; 204the mask for all priorities up to and including 205.Fa toppri 206is given by the macro 207.Fn LOG_UPTO toppri ; . 208The default allows all priorities to be logged. 209.Sh RETURN VALUES 210The routines 211.Fn closelog , 212.Fn openlog , 213.Fn syslog 214and 215.Fn vsyslog 216return no value. 217.Pp 218The routine 219.Fn setlogmask 220always returns the previous log mask level. 221.Sh EXAMPLES 222.Bd -literal -offset indent -compact 223syslog(LOG_ALERT, "who: internal error 23"); 224 225openlog("ftpd", LOG_PID, LOG_DAEMON); 226setlogmask(LOG_UPTO(LOG_ERR)); 227syslog(LOG_INFO, "Connection from host %d", CallingHost); 228 229syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); 230.Ed 231.Sh SEE ALSO 232.Xr logger 1 , 233.Xr syslogd 8 234.Sh HISTORY 235These 236functions appeared in 237.Bx 4.2 . 238