NAME

syslog, syslog_r, vsyslog, vsyslog_r, syslogp, syslogp_r, vsyslogp, vsyslogp_r, openlog, openlog_r, closelog, closelog_r, setlogmask, setlogmask_r — control system log

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <syslog.h>

void
syslog(int priority, const char *message, ...);

void
syslog_r(int priority, struct syslog_data *data, const char *message, ...);

void
syslogp(int priority, const char *msgid, const char *sdfmt, const char *message, ...);

void
syslogp_r(int priority, struct syslog_data *data, const char *msgid, const char *sdfmt, const char *message, ...);

void
openlog(const char *ident, int logopt, int facility);

void
openlog_r(const char *ident, int logopt, int facility, struct syslog_data *data);

void
closelog(void);

void
closelog_r(struct syslog_data *data);

int
setlogmask(int maskpri);

int
setlogmask_r(int maskpri, struct syslog_data *data);

#include <stdarg.h>

void
vsyslog(int priority, const char *message, va_list args);

void
vsyslog_r(int priority, struct syslog_data *data, const char *message, va_list args);

void
vsyslogp(int priority, const char *msgid, const char *sdfmt, const char *message, va_list args);

void
vsyslogp_r(int priority, struct syslog_data *data, const char *msgid, const char *sdfmt, const char *message, va_list args);

DESCRIPTION

The syslog() function writes 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 syslogd(8)).

The message is identical to a printf(3) format string, except that ‘%m' is replaced by the current error message. (As denoted by the global variable errno; see strerror(3).) A trailing newline is added if none is present.

The syslog_r() function is a multithread-safe version of the syslog() function. It takes a pointer to a syslog_data structure which is used to store information. This parameter must be initialized before syslog_r() is called. The SYSLOG_DATA_INIT constant is used for this purpose. The syslog_data structure and the SYSLOG_DATA_INIT constant are defined as:

struct syslog_data { 
        int             log_file; 
        int             connected; 
        int             opened; 
        int             log_stat; 
        const char     *log_tag; 
        int             log_fac; 
        int             log_mask; 
}; 
 
#define SYSLOG_DATA_INIT { \ 
    .log_file = -1, \ 
    .log_fac = LOG_USER, \ 
    .log_mask = 0xff, \ 
}

The structure is composed of the following elements:

The vsyslog() function is an alternative form in which the arguments have already been captured using the variable-length argument facilities of stdarg(3).

The syslogp() variants take additional arguments which correspond to new fields in the syslog-protocol message format. All three arguments are evaluated as printf(3) format strings and any of them can be NULL. This enables applications to use message IDs, structured data, and UTF-8 encoded content in messages.

The message is tagged with priority. Priorities are encoded as a facility and a level. The facility describes the part of the system generating the message. The level is selected from the following ordered (high to low) list:

The vsyslog_r() is used the same way as vsyslog() except that it takes an additional pointer to a syslog_data structure. It is a multithread-safe version of the vsyslog() function described above.

The openlog() function provides for more specialized processing of the messages sent by syslog() and vsyslog(). The parameter ident is a string that will be prepended to every message. The logopt argument is a bit field specifying logging options, which is formed by OR'ing one or more of the following values:

The facility parameter encodes a default facility to be assigned to all messages that do not have an explicit facility encoded:

The openlog_r() function is the multithread-safe version of the openlog() function. It takes an additional pointer to a syslog_data structure. This function must be used in conjunction with the other multithread-safe functions.

The closelog() function can be used to close the log file.

The closelog_r() does the same thing as closelog(3) but in a multithread-safe way and takes an additional pointer to a syslog_data structure.

The setlogmask() function sets the log priority mask to maskpri and returns the previous mask. Calls to syslog() with a priority not set in maskpri are rejected. The mask for an individual priority pri is calculated by the macro LOG_MASK(pri); the mask for all priorities up to and including toppri is given by the macro LOG_UPTO(toppri). The default allows all priorities to be logged.

The setlogmask_r() function is the multithread-safe version of setlogmask(). It takes an additional pointer to a syslog_data structure.

RETURN VALUES

The routines closelog(), closelog_r(), openlog(), openlog_r(), syslog(), syslog_r(), vsyslog(), vsyslog_r(), syslogp(), syslogp_r(), vsyslogp(), and vsyslogp_r() return no value.

The routines setlogmask() and setlogmask_r() always return the previous log mask level.

EXAMPLES

syslog(LOG_ALERT, "who: internal error 23"); 
 
openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP); 
 
setlogmask(LOG_UPTO(LOG_ERR)); 
 
syslog(LOG_INFO, "Connection from host %d", CallingHost); 
 
syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); 
 
syslogp(LOG_INFO|LOG_LOCAL2, NULL, NULL, "foobar error: %m"); 
 
syslogp(LOG_INFO, "ID%d", "[meta language=\"en-US\"]", 
        "event: %s", 42, EventDescription);

For the multithread-safe functions:

struct syslog_data sdata = SYSLOG_DATA_INIT; 
 
syslog_r(LOG_INFO|LOG_LOCAL2, &sdata, "foobar error: %m");

HISTORY

These non-multithread-safe functions appeared in 4.2BSD. The multithread-safe functions appeared in OpenBSD 3.1 and then in NetBSD 4.0. The async-signal-safe functions appeared in NetBSD 4.0. The syslog-protocol functions appeared in NetBSD 5.0.

CAVEATS

It is important never to pass a string with user-supplied data as a format without using ‘%s'. An attacker can put format specifiers in the string to mangle your stack, leading to a possible security hole. This holds true even if you have built the string “by hand” using a function like snprintf(), as the resulting string may still contain user-supplied conversion specifiers for later interpolation by syslog().

Always be sure to use the proper secure idiom:

syslog(priority, "%s", string);

With syslogp() the caller is responsible to use the right formatting for the message fields. A msgid must only contain up to 32 ASCII characters. A sdfmt has strict rules for paranthesis and character quoting. If the msgfmt contains UTF-8 characters, then it has to start with a Byte Order Mark.