1.\" Copyright (c) 1985, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)syslog.3 6.17 (Berkeley) 04/19/91 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 ftpd 8 , 154.Xr routed 8 , 155etc., that are not provided for explicitly by other facilities. 156.It Dv LOG_KERN 157Messages generated by the kernel. 158These cannot be generated by any user processes. 159.It Dv LOG_LPR 160The line printer spooling system: 161.Xr lpr 1 , 162.Xr lpc 8 , 163.Xr lpd 8 , 164etc. 165.It Dv LOG_MAIL 166The mail system. 167.It Dv LOG_NEWS 168The network news system. 169.It Dv LOG_SYSLOG 170Messages generated internally by 171.Xr syslogd 8 . 172.It Dv LOG_USER 173Messages generated by random user processes. 174This is the default facility identifier if none is specified. 175.It Dv LOG_UUCP 176The uucp system. 177.It Dv LOG_LOCAL0 178Reserved for local use. 179Similarly for 180.Dv LOG_LOCAL1 181through 182.Dv LOG_LOCAL7 . 183.El 184.Pp 185The 186.Fn closelog 187function 188can be used to close the log file. 189.Pp 190The 191.Fn setlogmask 192function 193sets the log priority mask to 194.Fa maskpri 195and returns the previous mask. 196Calls to 197.Fn syslog 198with a priority not set in 199.Fa maskpri 200are rejected. 201The mask for an individual priority 202.Fa pri 203is calculated by the macro 204.Fn LOG_MASK pri ; 205the mask for all priorities up to and including 206.Fa toppri 207is given by the macro 208.Fn LOG_UPTO toppri ; . 209The default allows all priorities to be logged. 210.Sh RETURN VALUES 211The routines 212.Fn closelog , 213.Fn openlog , 214.Fn syslog 215and 216.Fn vsyslog 217return no value. 218.Pp 219The routine 220.Fn setlogmask 221always returns the previous log mask level. 222.Sh EXAMPLES 223.Bd -literal -offset indent -compact 224syslog(LOG_ALERT, "who: internal error 23"); 225 226openlog("ftpd", LOG_PID, LOG_DAEMON); 227setlogmask(LOG_UPTO(LOG_ERR)); 228syslog(LOG_INFO, "Connection from host %d", CallingHost); 229 230syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); 231.Ed 232.Sh SEE ALSO 233.Xr logger 1 , 234.Xr syslogd 8 235.Sh HISTORY 236These 237functions appeared in 238.Bx 4.2 . 239