X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/be78fd264a7fecf726dedf30ffe59177dd61dbb9..ae59e04cb5f746d72d5e3e8c84dad7862c9b50e7:/usr/src/lib/libc/gen/syslog.3 diff --git a/usr/src/lib/libc/gen/syslog.3 b/usr/src/lib/libc/gen/syslog.3 index ea411ca94a..0d1f43cb5f 100644 --- a/usr/src/lib/libc/gen/syslog.3 +++ b/usr/src/lib/libc/gen/syslog.3 @@ -1,162 +1,238 @@ -.\" Copyright (c) 1983 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1985, 1991 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)syslog.3 6.2 (Berkeley) %G% +.\" %sccs.include.redist.man% .\" -.TH SYSLOG 3 "" -.UC 5 -.SH NAME -syslog, openlog, closelog, setlogmask \- control system log -.SH SYNOPSIS -.B "#include -.PP -.B "openlog(ident, logopt, facility) -.br -.B "char *ident; -.PP -.B "syslog(priority, message, parameters ... ) -.br -.B "char *message; -.PP -.B "closelog() -.PP -.B "setlogmask(maskpri) -.SH DESCRIPTION -.I Syslog -arranges to write -.I message -onto the system log maintained by -.IR syslogd (8). +.\" @(#)syslog.3 6.17 (Berkeley) %G% +.\" +.Dd +.Dt SYSLOG 3 +.Os BSD 4.2 +.Sh NAME +.Nm syslog , +.Nm vsyslog , +.Nm openlog , +.Nm closelog , +.Nm setlogmask +.Nd control system log +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Ft void +.Fn syslog "int priority" "const char *message" "..." +.Ft void +.Fn vsyslog "int priority" "const char *message" "va_list args" +.Ft void +.Fn openlog "const char *ident" "int logopt" "int facility" +.Ft void +.Fn closelog void +.Ft int +.Fn setlogmask "int maskpri" +.Sh DESCRIPTION +The +.Fn syslog +function +writes +.Fa message +to the system message logger. +The message is then written to the system console, log files, +logged-in users, or forwarded to other machines as appropriate. (See +.Xr syslogd 8 . ) +.Pp +The message is identical to a +.Xr printf 3 +format string, except that +.Ql %m +is replaced by the current error +message. (As denoted by the global variable +.Va errno ; +see +.Xr strerror 3 . ) +A trailing newline is added if none is present. +.Pp +The +.Fn vsyslog +function +is an alternate form in which the arguments have already been captured +using the variable-length argument facilities of +.Xr varargs 3 . +.Pp The message is tagged with -.IR priority . -The message looks like a -.IR printf (3) -string except that -.B %m -is replaced by the current error message (collected from -.IR errno ). -A trailing newline is added if needed. -This message will be read by -.IR syslogd (8) -and written to the system console, log files, or forwarded to -.I syslogd -on another host as appropriate. -.PP +.Fa priority . Priorities are encoded as a -.I facility +.Fa facility and a -.IR level . +.Em level . The facility describes the part of the system generating the message. -The level is selected from an ordered list: -.IP LOG_EMERG \w'LOG_WARNING'u+3 +The level is selected from the following +.Em ordered +(high to low) list: +.Bl -tag -width LOG_AUTHPRIV +.It Dv LOG_EMERG A panic condition. This is normally broadcast to all users. -.IP LOG_ALERT \w'LOG_WARNING'u+3 -A condition that should be corrected immediately, -such as a corrupted system database. -.IP LOG_CRIT \w'LOG_WARNING'u+3 -Critical conditions, -e.g., hard device errors. -.IP LOG_ERR \w'LOG_WARNING'u+3 +.It Dv LOG_ALERT +A condition that should be corrected immediately, such as a corrupted +system database. +.It Dv LOG_CRIT +Critical conditions, e.g., hard device errors. +.It Dv LOG_ERR Errors. -.IP LOG_WARNING \w'LOG_WARNING'u+3 +.It Dv LOG_WARNING Warning messages. -.IP LOG_NOTICE \w'LOG_WARNING'u+3 +.It Dv LOG_NOTICE Conditions that are not error conditions, but should possibly be handled specially. -.IP LOG_INFO \w'LOG_WARNING'u+3 +.It Dv LOG_INFO Informational messages. -.IP LOG_DEBUG \w'LOG_WARNING'u+3 +.It Dv LOG_DEBUG Messages that contain information normally of use only when debugging a program. -.PP +.El +.Pp +The +.Fn openlog +function +provides for more specialized processing of the messages sent +by +.Fn syslog +and +.Fn vsyslog . +The parameter +.Fa ident +is a string that will be prepended to every message. +The +.Fa logopt +argument +is a bit field specifying logging options, which is formed by +.Tn OR Ns 'ing +one or more of the following values: +.Bl -tag -width LOG_AUTHPRIV +.It Dv LOG_CONS If -.I syslog +.Fn syslog cannot pass the message to -.I syslogd -and the message is priority LOG_ERR or higher, -it attempts to write the message on -.IR /dev/console. -.PP -If special processing is needed, -.I openlog -can be called to initialize the log file. -The parameter -.I ident -is a string that is prepended to every message. -.I Logopt -is a bit field indicating logging options. -Current values for -.I logopt -are: -.IP LOG_PID \w'LOG_WARNING'u+3 -log the process id with each message: -useful for identifying instantiations of daemons. -.IP LOG_CONS \w'LOG_WARNING'u+3 -Force writing messages to the console if unable to send it to -.I syslogd. -This option is safe to use in daemon processes that have no controlling -terminal since -.I syslog -will fork before opening the console. -.IP LOG_ODELAY \w'LOG_WARNING'u+3 -Delay opening the connection to -.I syslogd -until the first message is logged. -Useful for programs that need to manage the -order in which file descriptors are allocated. -.PP +.Xr syslogd +it will attempt to write the message to the console +.Pq Dq Pa /dev/console. +.It Dv LOG_NDELAY +Open the connection to +.Xr syslogd +immediately. +Normally the open is delayed until the first message is logged. +Useful for programs that need to manage the order in which file +descriptors are allocated. +.It Dv LOG_PERROR +Write the message to standard error output as well to the system log. +.It Dv LOG_PID +Log the process id with each message: useful for identifying +instantiations of daemons. +.El +.Pp The -.I facility -parameter is encodes a default facility to be assigned to all messages +.Fa facility +parameter encodes a default facility to be assigned to all messages that do not have an explicit facility encoded: -.IP LOG_KERN \w'LOG_WARNING'u+3 +.Bl -tag -width LOG_AUTHPRIV +.It Dv LOG_AUTH +The authorization system: +.Xr login 1 , +.Xr su 1 , +.Xr getty 8 , +etc. +.It Dv LOG_AUTHPRIV +The same as +.Dv LOG_AUTH , +but logged to a file readable only by +selected individuals. +.It Dv LOG_CRON +The clock daemon. +.It Dv LOG_DAEMON +System daemons, such as +.Xr ftpd 8 , +.Xr routed 8 , +etc., that are not provided for explicitly by other facilities. +.It Dv LOG_KERN Messages generated by the kernel. These cannot be generated by any user processes. -.IP LOG_USER \w'LOG_WARNING'u+3 -Messages generated by random user processes. -This is the default if none is specified. -.IP LOG_MAIL \w'LOG_WARNING'u+3 -The mail system. -.IP LOG_DAEMON \w'LOG_WARNING'u+3 -System daemons, such as -.IR lpd (8), -.IR routed (8), -etc. -.IP LOG_AUTH \w'LOG_WARNING'u+3 -The authorization system: -.IR login (1), -.IR su (1), -.IR getty (8), +.It Dv LOG_LPR +The line printer spooling system: +.Xr lpr 1 , +.Xr lpc 8 , +.Xr lpd 8 , etc. -.IP LOG_LOCAL0 \w'LOG_WARNING'u+3 +.It Dv LOG_MAIL +The mail system. +.It Dv LOG_NEWS +The network news system. +.It Dv LOG_SYSLOG +Messages generated internally by +.Xr syslogd 8 . +.It Dv LOG_USER +Messages generated by random user processes. +This is the default facility identifier if none is specified. +.It Dv LOG_UUCP +The uucp system. +.It Dv LOG_LOCAL0 Reserved for local use. -Similarly for LOG_LOCAL1 through LOG_LOCAL7. -.PP -.I Closelog +Similarly for +.Dv LOG_LOCAL1 +through +.Dv LOG_LOCAL7 . +.El +.Pp +The +.Fn closelog +function can be used to close the log file. -.PP -.I Setlogmask +.Pp +The +.Fn setlogmask +function sets the log priority mask to -.I maskpri +.Fa maskpri and returns the previous mask. Calls to -.I syslog -with a priority lower than -.I maskpri +.Fn syslog +with a priority not set in +.Fa maskpri are rejected. +The mask for an individual priority +.Fa pri +is calculated by the macro +.Fn LOG_MASK pri ; +the mask for all priorities up to and including +.Fa toppri +is given by the macro +.Fn LOG_UPTO toppri ; . The default allows all priorities to be logged. -.SH EXAMPLES -.nf +.Sh RETURN VALUES +The routines +.Fn closelog , +.Fn openlog , +.Fn syslog +and +.Fn vsyslog +return no value. +.Pp +The routine +.Fn setlogmask +always returns the previous log mask level. +.Sh EXAMPLES +.Bd -literal -offset indent -compact syslog(LOG_ALERT, "who: internal error 23"); openlog("ftpd", LOG_PID, LOG_DAEMON); +setlogmask(LOG_UPTO(LOG_ERR)); syslog(LOG_INFO, "Connection from host %d", CallingHost); syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); -.fi -.SH "SEE ALSO" -logger(1), -syslogd(8) +.Ed +.Sh SEE ALSO +.Xr logger 1 , +.Xr syslogd 8 +.Sh HISTORY +These +functions appeared in +.Bx 4.2 .