| .\" Written Feb 1994 by Steve Greenland (stevegr@neosoft.com) |
| .\" |
| .\" 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. |
| .\" |
| .\" Updated 1999.12.19 by Karl M. Hegbloom <karlheg@debian.org> |
| .\" |
| .\" Updated 13 Oct 2001, Michael Kerrisk <mtk-manpages@gmx.net> |
| .\" Added description of vsyslog |
| .\" Added descriptions of (SUSv3-specified) 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@gmx.net> |
| .\" |
| .TH SYSLOG 3 2002-01-03 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| closelog, openlog, syslog \- send messages to the system logger |
| .SH SYNOPSIS |
| .B #include <syslog.h> |
| .sp |
| .BI "void openlog(const char *" ident ", int " option ", int " facility ); |
| .br |
| .BI "void syslog(int " priority ", const char *" format ", ...);" |
| .br |
| .BI "void closelog(void);" |
| .sp |
| .B #include <stdarg.h> |
| .sp |
| .BI "void vsyslog(int " priority ", const char *" format ", va_list " ap ); |
| .br |
| .SH DESCRIPTION |
| .BR closelog () |
| closes the descriptor being used to write to the system logger. The use of |
| .BR closelog () |
| is optional. |
| .sp |
| .BR openlog () |
| opens a connection to the system logger for a program. The string pointed |
| to by |
| .I ident |
| is prepended to every message, and is typically set to the program name. |
| 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 (). |
| Values for |
| .I option |
| and |
| .I facility |
| are given below. 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. |
| .sp |
| .BR syslog () |
| generates a log message, which will be distributed by |
| .BR syslogd (8). |
| The |
| .I priority |
| argument is formed by ORing the |
| .I facility |
| and the |
| .I level |
| values (explained below). 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 %m will be replaced by |
| the error message string |
| .IR strerror ( errno ). |
| A trailing newline is added when needed. |
| |
| 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. |
| .SH PARAMETERS |
| This section lists the parameters used to set the values of |
| .IR option , " facility" ", and " priority . |
| .SS option |
| The |
| .I option |
| argument to |
| .BR openlog () |
| is an OR of any of these: |
| .TP |
| .B LOG_CONS |
| Write directly to system console if there is an error while sending to |
| system logger. |
| .TP |
| .B LOG_NDELAY |
| Open the connection immediately (normally, the connection is opened when |
| the first message is logged). |
| .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 SUSv3.) Print to stderr as well. |
| .TP |
| .B LOG_PID |
| Include PID with each message. |
| .SS facility |
| 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 |
| .B LOG_AUTH |
| security/authorization messages (DEPRECATED Use |
| .B LOG_AUTHPRIV |
| instead) |
| .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 |
| .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 |
| .B syslogd |
| .TP |
| .BR LOG_USER " (default)" |
| generic user-level messages |
| .TP |
| .B LOG_UUCP |
| UUCP subsystem |
| |
| .SS level |
| This determines the importance of the message. The levels are, in order |
| of decreasing importance: |
| .TP |
| .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 |
| .LP |
| The function |
| .BR setlogmask (3) |
| can be used to restrict logging to specified levels only. |
| .SH "CONFORMING TO" |
| The functions |
| .BR openlog (), |
| .BR closelog (), |
| and |
| .BR syslog () |
| (but not |
| .BR vsyslog ()) |
| are specified in SUSv2 and POSIX 1003.1-2001. |
| POSIX 1003.1-2001 specifies only the |
| .B LOG_USER |
| and |
| .BR LOG_LOCAL* |
| values for |
| .IR facility . |
| However, with the exception of |
| .BR LOG_AUTHPRIV |
| and |
| .BR LOG_FTP , |
| the other |
| .I facility |
| values appear on most Unix systems. |
| The |
| .B LOG_PERROR |
| value for |
| .I option |
| is not specified by POSIX 1003.1-2001, 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 parameter |
| .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. |
| .LP |
| Never pass a string with user-supplied data as a format, use |
| .RS |
| syslog(priority, "%s", string); |
| .RE |
| instead. |
| .SH "SEE ALSO" |
| .BR logger (1), |
| .BR setlogmask (3), |
| .BR syslog.conf (5), |
| .BR syslogd (8) |