Import NetBSD syslog.3 v1.33 as syslogp.3
Signed-off-by: Joachim Nilsson <troglobit@gmail.com>
This commit is contained in:
Joachim Nilsson
@@ -1,3 +1,4 @@
|
||||
dist_man1_MANS = logger.1
|
||||
dist_man3_MANS = syslogp.3
|
||||
dist_man5_MANS = syslog.conf.5
|
||||
dist_man8_MANS = syslogd.8 klogd.8
|
||||
|
||||
524
man/syslogp.3
Normal file
524
man/syslogp.3
Normal file
@@ -0,0 +1,524 @@
|
||||
.\" $NetBSD: syslog.3,v 1.33 2017/07/03 21:32:49 wiz Exp $
|
||||
.\" $OpenBSD: syslog.3,v 1.25 2005/07/22 03:16:58 jaredy Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 1985, 1991, 1993
|
||||
.\" The Regents of the University of California. All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\" 3. Neither the name of the University nor the names of its contributors
|
||||
.\" may be used to endorse or promote products derived from this software
|
||||
.\" without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" @(#)syslog.3 8.1 (Berkeley) 6/4/93
|
||||
.\"
|
||||
.Dd March 22, 2017
|
||||
.Dt SYSLOG 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm syslog ,
|
||||
.Nm syslog_r ,
|
||||
.Nm vsyslog ,
|
||||
.Nm vsyslog_r ,
|
||||
.Nm syslogp ,
|
||||
.Nm syslogp_r ,
|
||||
.Nm vsyslogp ,
|
||||
.Nm vsyslogp_r ,
|
||||
.Nm openlog ,
|
||||
.Nm openlog_r ,
|
||||
.Nm closelog ,
|
||||
.Nm closelog_r ,
|
||||
.Nm setlogmask ,
|
||||
.Nm setlogmask_r
|
||||
.Nd control system log
|
||||
.Sh LIBRARY
|
||||
.Lb libc
|
||||
.Sh SYNOPSIS
|
||||
.In syslog.h
|
||||
.Ft void
|
||||
.Fn syslog "int priority" "const char *message" "..."
|
||||
.Ft void
|
||||
.Fn syslog_r "int priority" "struct syslog_data *data" "const char *message" "..."
|
||||
.Ft void
|
||||
.Fn syslogp "int priority" "const char *msgid" "const char *sdfmt" "const char *message" "..."
|
||||
.Ft void
|
||||
.Fn syslogp_r "int priority" "struct syslog_data *data" "const char *msgid" "const char *sdfmt" "const char *message" "..."
|
||||
.\" .Ft void
|
||||
.\" .Fn syslog_ss "int priority" "struct syslog_data *data" "const char *message" "..."
|
||||
.Ft void
|
||||
.Fn openlog "const char *ident" "int logopt" "int facility"
|
||||
.Ft void
|
||||
.Fn openlog_r "const char *ident" "int logopt" "int facility" "struct syslog_data *data"
|
||||
.Ft void
|
||||
.Fn closelog void
|
||||
.Ft void
|
||||
.Fn closelog_r "struct syslog_data *data"
|
||||
.Ft int
|
||||
.Fn setlogmask "int maskpri"
|
||||
.Ft int
|
||||
.Fn setlogmask_r "int maskpri" "struct syslog_data *data"
|
||||
.In stdarg.h
|
||||
.Ft void
|
||||
.Fn vsyslog "int priority" "const char *message" "va_list args"
|
||||
.Ft void
|
||||
.Fn vsyslog_r "int priority" "struct syslog_data *data" "const char *message" "va_list args"
|
||||
.Ft void
|
||||
.Fn vsyslogp "int priority" "const char *msgid" "const char *sdfmt" "const char *message" "va_list args"
|
||||
.Ft void
|
||||
.Fn vsyslogp_r "int priority" "struct syslog_data *data" "const char *msgid" "const char *sdfmt" "const char *message" "va_list args"
|
||||
.\" .Ft void
|
||||
.\" .Fn vsyslog_ss "int priority" "struct syslog_data *data" "const char *message" "va_list args"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn syslog
|
||||
function
|
||||
writes
|
||||
.Fa 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
|
||||
.Xr syslogd 8 ) .
|
||||
.Pp
|
||||
The message is identical to a
|
||||
.Xr printf 3
|
||||
format string, except that
|
||||
.Ql %m
|
||||
is replaced by the current error
|
||||
message.
|
||||
(As denoted by the global variable
|
||||
.Va errno ;
|
||||
see
|
||||
.Xr strerror 3 . )
|
||||
A trailing newline is added if none is present.
|
||||
.\" shouldn't the newline statement be removed?
|
||||
.\" when logging through a socket a newline is
|
||||
.\" not added nor is it required. -- ms
|
||||
.Pp
|
||||
The
|
||||
.Fn syslog_r
|
||||
function is a multithread-safe version of the
|
||||
.Fn syslog
|
||||
function.
|
||||
It takes a pointer to a
|
||||
.Fa syslog_data
|
||||
structure which is used to store
|
||||
information.
|
||||
This parameter must be initialized before
|
||||
.Fn syslog_r
|
||||
is called.
|
||||
The
|
||||
.Dv SYSLOG_DATA_INIT
|
||||
constant is used for this purpose.
|
||||
The
|
||||
.Fa syslog_data
|
||||
structure and the
|
||||
.Dv SYSLOG_DATA_INIT
|
||||
constant are defined as:
|
||||
.Bd -literal -offset indent
|
||||
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 { \e
|
||||
.log_file = -1, \e
|
||||
.log_fac = LOG_USER, \e
|
||||
.log_mask = 0xff, \e
|
||||
}
|
||||
.Ed
|
||||
.Pp
|
||||
The structure is composed of the following elements:
|
||||
.Bl -tag -width connected -offset indent
|
||||
.It Va log_file
|
||||
contains the file descriptor of the file where the message is logged
|
||||
.It Va connected
|
||||
indicates if connect has been done
|
||||
.It Va opened
|
||||
indicates if
|
||||
.Fn openlog_r
|
||||
has been called
|
||||
.It Va log_stat
|
||||
status bits, set by
|
||||
.Fn openlog_r
|
||||
.It Va log_tag
|
||||
string to tag the entry with
|
||||
.It Va log_fac
|
||||
facility code
|
||||
.It Va log_mask
|
||||
mask of priorities to be logged
|
||||
.El
|
||||
.\" .Pp
|
||||
.\" The
|
||||
.\" .Fn syslog_ss
|
||||
.\" is the async-signal-safe version of
|
||||
.\" .Fn syslog_r
|
||||
.\" and is also multithread-safe.
|
||||
.\" It has the following limitations:
|
||||
.\" .Bl -enum -offset indent
|
||||
.\" .It
|
||||
.\" The format string cannot contain multi-byte character sequences.
|
||||
.\" .It
|
||||
.\" Floating point formats are not supported and print
|
||||
.\" .Dq UNK .
|
||||
.\" .It
|
||||
.\" The time of the event is not sent to
|
||||
.\" .Xr syslogd 8 .
|
||||
.\" .It
|
||||
.\" The error string in the %m format is not printed symbolically but as
|
||||
.\" .Dq Error %d .
|
||||
.\" .El
|
||||
.\" .Pp
|
||||
.\" For more information about async-signal-safe functions and signal handlers, see
|
||||
.\" .Xr signal 7 .
|
||||
.Pp
|
||||
The
|
||||
.Fn vsyslog
|
||||
function
|
||||
is an alternative form in which the arguments have already been captured
|
||||
using the variable-length argument facilities of
|
||||
.Xr stdarg 3 .
|
||||
.Pp
|
||||
The
|
||||
.Fn syslogp
|
||||
variants take additional arguments which correspond to new fields in the
|
||||
syslog-protocol message format.
|
||||
All three arguments are evaluated as
|
||||
.Xr printf 3
|
||||
format strings and any of them can be
|
||||
.Dv NULL .
|
||||
This enables applications to use message IDs, structured data, and UTF-8 encoded
|
||||
content in messages.
|
||||
.Pp
|
||||
The message is tagged with
|
||||
.Fa priority .
|
||||
Priorities are encoded as a
|
||||
.Fa facility
|
||||
and a
|
||||
.Em level .
|
||||
The facility describes the part of the system
|
||||
generating the message.
|
||||
The level is selected from the following
|
||||
.Em ordered
|
||||
(high to low) list:
|
||||
.Bl -tag -width LOG_AUTHPRIV
|
||||
.It Dv LOG_EMERG
|
||||
A panic condition.
|
||||
This is normally broadcast to all users.
|
||||
.It Dv LOG_ALERT
|
||||
A condition that should be corrected immediately, such as a corrupted
|
||||
system database.
|
||||
.It Dv LOG_CRIT
|
||||
Critical conditions, e.g., hard device errors.
|
||||
.It Dv LOG_ERR
|
||||
Errors.
|
||||
.It Dv LOG_WARNING
|
||||
Warning messages.
|
||||
.It Dv LOG_NOTICE
|
||||
Conditions that are not error conditions,
|
||||
but should possibly be handled specially.
|
||||
.It Dv LOG_INFO
|
||||
Informational messages.
|
||||
.It Dv LOG_DEBUG
|
||||
Messages that contain information
|
||||
normally of use only when debugging a program.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn vsyslog_r
|
||||
is used the same way as
|
||||
.Fn vsyslog
|
||||
except that it takes an additional pointer to a
|
||||
.Fa syslog_data
|
||||
structure.
|
||||
It is a multithread-safe version of the
|
||||
.Fn vsyslog
|
||||
function described above.
|
||||
.\" The
|
||||
.\" .Fn vsyslog_ss
|
||||
.\" is the async-signal-safe version of
|
||||
.\" .Fn vsyslog_r ,
|
||||
.\" is also multithread-safe, and has the same limitations as
|
||||
.\" .Fn syslog_ss .
|
||||
.Pp
|
||||
The
|
||||
.Fn openlog
|
||||
function
|
||||
provides for more specialized processing of the messages sent
|
||||
by
|
||||
.Fn syslog
|
||||
and
|
||||
.Fn vsyslog .
|
||||
The parameter
|
||||
.Fa ident
|
||||
is a string that will be prepended to every message.
|
||||
The
|
||||
.Fa logopt
|
||||
argument
|
||||
is a bit field specifying logging options, which is formed by
|
||||
.Tn OR Ns 'ing
|
||||
one or more of the following values:
|
||||
.Bl -tag -width LOG_AUTHPRIV
|
||||
.It Dv LOG_CONS
|
||||
If
|
||||
.Fn syslog
|
||||
cannot pass the message to
|
||||
.Xr syslogd 8
|
||||
it will attempt to write the message to the console
|
||||
.Pq Dq Pa /dev/console .
|
||||
.It Dv LOG_NDELAY
|
||||
Open the connection to
|
||||
.Xr syslogd 8
|
||||
immediately.
|
||||
Normally the open is delayed until the first message is logged.
|
||||
Useful for programs that need to manage the order in which file
|
||||
descriptors are allocated.
|
||||
.It Dv LOG_NLOG
|
||||
Stops syslog from writing to the system log.
|
||||
Only useful with
|
||||
.Dv LOG_PERROR .
|
||||
.It Dv LOG_PERROR
|
||||
Write the message to standard error output as well to the system log.
|
||||
.It Dv LOG_PID
|
||||
Log the process id with each message: useful for identifying
|
||||
instantiations of daemons.
|
||||
(This PID is placed within brackets
|
||||
between the ident and the message.)
|
||||
.It Dv LOG_PTRIM
|
||||
Trim anything syslog added to the message before writing to
|
||||
standard error output.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fa facility
|
||||
parameter encodes a default facility to be assigned to all messages
|
||||
that do not have an explicit facility encoded:
|
||||
.Bl -tag -width LOG_AUTHPRIV
|
||||
.It Dv LOG_AUTH
|
||||
The authorization system:
|
||||
.Xr login 1 ,
|
||||
.Xr su 1 ,
|
||||
.Xr getty 8 ,
|
||||
etc.
|
||||
.It Dv LOG_AUTHPRIV
|
||||
The same as
|
||||
.Dv LOG_AUTH ,
|
||||
but logged to a file readable only by
|
||||
selected individuals.
|
||||
.It Dv LOG_CRON
|
||||
The cron daemon:
|
||||
.Xr cron 8 .
|
||||
.It Dv LOG_DAEMON
|
||||
System daemons, such as
|
||||
.Xr routed 8 ,
|
||||
that are not provided for explicitly by other facilities.
|
||||
.It Dv LOG_FTP
|
||||
The file transfer protocol daemon:
|
||||
.Xr ftpd 8 .
|
||||
.It Dv LOG_KERN
|
||||
Messages generated by the kernel.
|
||||
These cannot be generated by any user processes.
|
||||
.It Dv LOG_LPR
|
||||
The line printer spooling system:
|
||||
.Xr lpr 1 ,
|
||||
.Xr lpc 8 ,
|
||||
.Xr lpd 8 ,
|
||||
etc.
|
||||
.It Dv LOG_MAIL
|
||||
The mail system.
|
||||
.It Dv LOG_NEWS
|
||||
The network news system.
|
||||
.It Dv LOG_SYSLOG
|
||||
Messages generated internally by
|
||||
.Xr syslogd 8 .
|
||||
.It Dv LOG_USER
|
||||
Messages generated by random user processes.
|
||||
This is the default facility identifier if none is specified.
|
||||
.It Dv LOG_UUCP
|
||||
The uucp system.
|
||||
.It Dv LOG_LOCAL0
|
||||
Reserved for local use.
|
||||
Similarly for
|
||||
.Dv LOG_LOCAL1
|
||||
through
|
||||
.Dv LOG_LOCAL7 .
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn openlog_r
|
||||
function is the multithread-safe version of the
|
||||
.Fn openlog
|
||||
function.
|
||||
It takes an additional pointer to a
|
||||
.Fa syslog_data
|
||||
structure.
|
||||
This function must be used in conjunction with the other
|
||||
multithread-safe functions.
|
||||
.Pp
|
||||
The
|
||||
.Fn closelog
|
||||
function
|
||||
can be used to close the log file.
|
||||
.Pp
|
||||
The
|
||||
.Fn closelog_r
|
||||
does the same thing as
|
||||
.Xr closelog 3
|
||||
but in a multithread-safe way and takes an additional
|
||||
pointer to a
|
||||
.Fa syslog_data
|
||||
structure.
|
||||
.Pp
|
||||
The
|
||||
.Fn setlogmask
|
||||
function
|
||||
sets the log priority mask to
|
||||
.Fa maskpri
|
||||
and returns the previous mask.
|
||||
Calls to
|
||||
.Fn syslog
|
||||
with a priority not set in
|
||||
.Fa maskpri
|
||||
are rejected.
|
||||
The mask for an individual priority
|
||||
.Fa pri
|
||||
is calculated by the macro
|
||||
.Fn LOG_MASK pri ;
|
||||
the mask for all priorities up to and including
|
||||
.Fa toppri
|
||||
is given by the macro
|
||||
.Fn LOG_UPTO toppri .
|
||||
The default allows all priorities to be logged.
|
||||
.Pp
|
||||
The
|
||||
.Fn setlogmask_r
|
||||
function is the multithread-safe version of
|
||||
.Fn setlogmask .
|
||||
It takes an additional pointer to a
|
||||
.Fa syslog_data
|
||||
structure.
|
||||
.Sh RETURN VALUES
|
||||
The routines
|
||||
.Fn closelog ,
|
||||
.Fn closelog_r ,
|
||||
.Fn openlog ,
|
||||
.Fn openlog_r ,
|
||||
.Fn syslog ,
|
||||
.Fn syslog_r ,
|
||||
.Fn vsyslog ,
|
||||
.Fn vsyslog_r ,
|
||||
.Fn syslogp ,
|
||||
.Fn syslogp_r ,
|
||||
.Fn vsyslogp ,
|
||||
and
|
||||
.Fn vsyslogp_r
|
||||
return no value.
|
||||
.Pp
|
||||
The routines
|
||||
.Fn setlogmask
|
||||
and
|
||||
.Fn setlogmask_r
|
||||
always return the previous log mask level.
|
||||
.Sh EXAMPLES
|
||||
.Bd -literal -offset indent -compact
|
||||
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=\e"en-US\e"]",
|
||||
"event: %s", 42, EventDescription);
|
||||
.Ed
|
||||
.Pp
|
||||
For the multithread-safe functions:
|
||||
.Bd -literal -offset indent
|
||||
struct syslog_data sdata = SYSLOG_DATA_INIT;
|
||||
|
||||
syslog_r(LOG_INFO|LOG_LOCAL2, &sdata, "foobar error: %m");
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr logger 1 ,
|
||||
.Xr syslogd 8
|
||||
.Rs
|
||||
.%R RFC
|
||||
.%N 3164
|
||||
.%D August 2001
|
||||
.%T The BSD syslog Protocol
|
||||
.Re
|
||||
.Rs
|
||||
.%R Internet-Draft
|
||||
.%N draft-ietf-syslog-protocol-23
|
||||
.%D September 2007
|
||||
.%T The syslog Protocol
|
||||
.Re
|
||||
.Sh HISTORY
|
||||
These non-multithread-safe functions appeared in
|
||||
.Bx 4.2 .
|
||||
The multithread-safe functions appeared in
|
||||
.Ox 3.1
|
||||
and then in
|
||||
.Nx 4.0 .
|
||||
The async-signal-safe functions appeared in
|
||||
.Nx 4.0 .
|
||||
The syslog-protocol functions appeared in
|
||||
.Nx 5.0 .
|
||||
.Sh CAVEATS
|
||||
It is important never to pass a string with user-supplied data as a
|
||||
format without using
|
||||
.Ql %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
|
||||
.Dq by hand
|
||||
using a function like
|
||||
.Fn snprintf ,
|
||||
as the resulting string may still contain user-supplied conversion specifiers
|
||||
for later interpolation by
|
||||
.Fn syslog .
|
||||
.Pp
|
||||
Always be sure to use the proper secure idiom:
|
||||
.Bd -literal -offset indent
|
||||
syslog(priority, "%s", string);
|
||||
.Ed
|
||||
.Pp
|
||||
With
|
||||
.Fn syslogp
|
||||
the caller is responsible to use the right formatting for the message fields.
|
||||
A
|
||||
.Fa msgid
|
||||
must only contain up to 32 ASCII characters.
|
||||
A
|
||||
.Fa sdfmt
|
||||
has strict rules for parenthesis and character quoting.
|
||||
If the
|
||||
.Fa msgfmt
|
||||
contains UTF-8 characters, then it has to start with a Byte Order Mark.
|
||||
Reference in New Issue
Block a user