summaryrefslogtreecommitdiffstats
path: root/man3/syslog.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/syslog.3')
-rw-r--r--man3/syslog.3360
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)