| .\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com) |
| .\" and Copyright 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| closelog, openlog, syslog, vsyslog \- send messages to the system logger |
| .SH SYNOPSIS |
| .B #include <syslog.h> |
| .PP |
| .BI "void openlog(const char *" ident ", int " option ", int " facility ); |
| .br |
| .BI "void syslog(int " priority ", const char *" format ", ...);" |
| .br |
| .B "void closelog(void);" |
| .PP |
| .BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR vsyslog (): |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| Glibc 2.19 and earlier: |
| _BSD_SOURCE |
| .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 |
| .BR 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; |
| lbw21 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR openlog (), |
| .BR closelog () |
| T} Thread safety MT-Safe |
| T{ |
| .BR syslog (), |
| .BR vsyslog () |
| T} Thread safety MT-Safe env locale |
| .TE |
| .SH CONFORMING TO |
| The functions |
| .BR openlog (), |
| .BR closelog (), |
| and |
| .BR syslog () |
| (but not |
| .BR vsyslog ()) |
| are specified in SUSv2, POSIX.1-2001, and POSIX.1-2008. |
| .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 HISTORY |
| .\" A |
| .\" .BR syslog () |
| .\" function call appeared in 4.2BSD. |
| .\" 4.3BSD documents |
| .\" .BR openlog (), |
| .\" .BR syslog (), |
| .\" .BR closelog (), |
| .\" and |
| .\" .BR setlogmask (). |
| .\" 4.3BSD-Reno also documents |
| .\" .BR vsyslog (). |
| .\" Of course early v* functions used the |
| .\" .I <varargs.h> |
| .\" mechanism, which is not compatible with |
| .\" .IR <stdarg.h> . |
| .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) |