diff options
Diffstat (limited to 'man3/syslog.3')
| -rw-r--r-- | man3/syslog.3 | 360 |
1 files changed, 360 insertions, 0 deletions
diff --git a/man3/syslog.3 b/man3/syslog.3 new file mode 100644 index 0000000..e8c9dc4 --- /dev/null +++ b/man3/syslog.3 @@ -0,0 +1,360 @@ +'\" t +.\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com) +.\" and Copyright 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Updated 1999.12.19 by Karl M. Hegbloom <karlheg@debian.org> +.\" +.\" Updated 13 Oct 2001, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added description of vsyslog +.\" Added descriptions of LOG_ODELAY and LOG_NOWAIT +.\" Added brief description of facility and option arguments +.\" Added CONFORMING TO section +.\" 2001-10-13, aeb, minor changes +.\" Modified 13 Dec 2001, Martin Schulze <joey@infodrom.org> +.\" Modified 3 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.TH syslog 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +closelog, openlog, syslog, vsyslog \- send messages to the system logger +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <syslog.h> +.PP +.BI "void openlog(const char *" ident ", int " option ", int " facility ); +.BI "void syslog(int " priority ", const char *" format ", ...);" +.B "void closelog(void);" +.PP +.BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR vsyslog (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +.SS openlog() +.BR openlog () +opens a connection to the system logger for a program. +.PP +The string pointed to by +.I ident +is prepended to every message, and is typically set to the program name. +If +.I ident +is NULL, the program name is used. +(POSIX.1-2008 does not specify the behavior when +.I ident +is NULL.) +.PP +The +.I option +argument specifies flags which control the operation of +.BR openlog () +and subsequent calls to +.BR syslog (). +The +.I facility +argument establishes a default to be used if +none is specified in subsequent calls to +.BR syslog (). +The values that may be specified for +.I option +and +.I facility +are described below. +.PP +The use of +.BR openlog () +is optional; it will automatically be called by +.BR syslog () +if necessary, in which case +.I ident +will default to NULL. +.\" +.SS syslog() and vsyslog() +.BR syslog () +generates a log message, which will be distributed by +.BR syslogd (8). +.PP +The +.I priority +argument is formed by ORing together a +.I facility +value and a +.I level +value (described below). +If no +.I facility +value is ORed into +.IR priority , +then the default value set by +.BR openlog () +is used, or, if there was no preceding +.BR openlog () +call, a default of +.B LOG_USER +is employed. +.PP +The remaining arguments are a +.IR format , +as in +.BR printf (3), +and any arguments required by the +.IR format , +except that the two-character sequence +.B %m +will be replaced by +the error message string +.IR strerror ( errno ). +The format string need not include a terminating newline character. +.PP +The function +.BR vsyslog () +performs the same task as +.BR syslog () +with the difference that it takes a set of arguments which have +been obtained using the +.BR stdarg (3) +variable argument list macros. +.\" +.SS closelog() +.BR closelog () +closes the file descriptor being used to write to the system logger. +The use of +.BR closelog () +is optional. +.\" +.SS Values for \fIoption\fP +The +.I option +argument to +.BR openlog () +is a bit mask constructed by ORing together any of the following values: +.TP 15 +.B LOG_CONS +Write directly to the system console if there is an error while sending to +the system logger. +.TP +.B LOG_NDELAY +Open the connection immediately (normally, the connection is opened when +the first message is logged). +This may be useful, for example, if a subsequent +.BR chroot (2) +would make the pathname used internally by the logging facility unreachable. +.TP +.B LOG_NOWAIT +Don't wait for child processes that may have been created while logging +the message. +(The GNU C library does not create a child process, so this +option has no effect on Linux.) +.TP +.B LOG_ODELAY +The converse of +.BR LOG_NDELAY ; +opening of the connection is delayed until +.BR syslog () +is called. +(This is the default, and need not be specified.) +.TP +.B LOG_PERROR +(Not in POSIX.1-2001 or POSIX.1-2008.) +Also log the message to +.IR stderr . +.TP +.B LOG_PID +Include the caller's PID with each message. +.\" +.SS Values for \fIfacility\fP +The +.I facility +argument is used to specify what type of program is logging the message. +This lets the configuration file specify that messages from different +facilities will be handled differently. +.TP 15 +.B LOG_AUTH +security/authorization messages +.TP +.B LOG_AUTHPRIV +security/authorization messages (private) +.TP +.B LOG_CRON +clock daemon +.RB ( cron " and " at ) +.TP +.B LOG_DAEMON +system daemons without separate facility value +.TP +.B LOG_FTP +ftp daemon +.TP +.B LOG_KERN +kernel messages (these can't be generated from user processes) +.\" LOG_KERN has the value 0; if used as a facility, zero translates to: +.\" "use the default facility". +.TP +.BR LOG_LOCAL0 " through " LOG_LOCAL7 +reserved for local use +.TP +.B LOG_LPR +line printer subsystem +.TP +.B LOG_MAIL +mail subsystem +.TP +.B LOG_NEWS +USENET news subsystem +.TP +.B LOG_SYSLOG +messages generated internally by +.BR syslogd (8) +.TP +.BR LOG_USER " (default)" +generic user-level messages +.TP +.B LOG_UUCP +UUCP subsystem +.\" +.SS Values for \fIlevel\fP +This determines the importance of the message. +The levels are, in order of decreasing importance: +.TP 15 +.B LOG_EMERG +system is unusable +.TP +.B LOG_ALERT +action must be taken immediately +.TP +.B LOG_CRIT +critical conditions +.TP +.B LOG_ERR +error conditions +.TP +.B LOG_WARNING +warning conditions +.TP +.B LOG_NOTICE +normal, but significant, condition +.TP +.B LOG_INFO +informational message +.TP +.B LOG_DEBUG +debug-level message +.PP +The function +.BR setlogmask (3) +can be used to restrict logging to specified levels only. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR openlog (), +.BR closelog () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR syslog (), +.BR vsyslog () +T} Thread safety MT-Safe env locale +.TE +.sp 1 +.SH STANDARDS +.TP +.BR syslog () +.TQ +.BR openlog () +.TQ +.BR closelog () +POSIX.1-2008. +.TP +.BR vsyslog () +None. +.SH HISTORY +.TP +.BR syslog () +4.2BSD, SUSv2, POSIX.1-2001. +.TP +.BR openlog () +.TQ +.BR closelog () +4.3BSD, SUSv2, POSIX.1-2001. +.\" .SH HISTORY +.\" 4.3BSD documents +.\" .BR setlogmask (). +.TP +.BR vsyslog () +4.3BSD-Reno. +.\" Of course early v* functions used the +.\" .I <varargs.h> +.\" mechanism, which is not compatible with +.\" .IR <stdarg.h> . +.PP +POSIX.1-2001 specifies only the +.B LOG_USER +and +.B LOG_LOCAL* +values for +.IR facility . +However, with the exception of +.B LOG_AUTHPRIV +and +.BR LOG_FTP , +the other +.I facility +values appear on most UNIX systems. +.PP +The +.B LOG_PERROR +value for +.I option +is not specified by POSIX.1-2001 or POSIX.1-2008, but is available +in most versions of UNIX. +.SH NOTES +The argument +.I ident +in the call of +.BR openlog () +is probably stored as-is. +Thus, if the string it points to +is changed, +.BR syslog () +may start prepending the changed string, and if the string +it points to ceases to exist, the results are undefined. +Most portable is to use a string constant. +.PP +Never pass a string with user-supplied data as a format, +use the following instead: +.PP +.in +4n +.EX +syslog(priority, "%s", string); +.EE +.in +.SH SEE ALSO +.BR journalctl (1), +.BR logger (1), +.BR setlogmask (3), +.BR syslog.conf (5), +.BR syslogd (8) |