docs: Added All OpenBSD Manuals

1 files changed, 423 insertions, 0 deletions

diff --git a/static/openbsd/man3/syslog.3 b/static/openbsd/man3/syslog.3
new file mode 100644
index 00000000..ab411f3a
--- /dev/null
+++ b/static/openbsd/man3/syslog.3
@@ -0,0 +1,423 @@
+.\"	$OpenBSD: syslog.3,v 1.38 2024/06/11 23:35:27 jsg 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.
+.\"
+.Dd $Mdocdate: June 11 2024 $
+.Dt SYSLOG 3
+.Os
+.Sh NAME
+.Nm syslog ,
+.Nm syslog_r ,
+.Nm vsyslog ,
+.Nm vsyslog_r ,
+.Nm openlog ,
+.Nm openlog_r ,
+.Nm closelog ,
+.Nm closelog_r ,
+.Nm setlogmask ,
+.Nm setlogmask_r
+.Nd control system log
+.Sh SYNOPSIS
+.In syslog.h
+.In stdarg.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 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 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"
+.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.
+.Pp
+The
+.Fn syslog_r
+function is a reentrant 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.
+.Pp
+The
+.Fn vsyslog
+function is an alternate form in which the arguments have already been captured
+using the variable-length argument facilities of
+.Xr va_start 3 .
+.Pp
+The message is tagged with
+.Fa priority .
+Priorities are encoded as a
+.Fa facility
+and a
+.Fa level .
+The
+.Fa facility
+describes the part of the system
+generating the message:
+.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 dhcpd 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
+.Fa level
+(ORed with the
+.Fa facility )
+is selected from the following list, ordered by decreasing importance:
+.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
+function is used the same way as
+.Fn vsyslog
+except that it takes an additional pointer to a
+.Fa syslog_data
+structure.
+It is a reentrant version of the
+.Fn vsyslog
+function described above.
+.Pp
+The
+.Fn openlog
+function provides for more specialized processing of the messages sent by
+.Fn syslog
+and
+.Fn vsyslog .
+The parameter
+.Fa ident
+points to a string that will be prepended to every message;
+its storage must persist until
+.Fn closelog
+or the corresponding
+.Fn closelog_r .
+If the content of the string is changed, behaviour is unspecified.
+.Pp
+The
+.Fa logopt
+argument
+is a bit field specifying logging options, which is formed by OR'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 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.
+This option must be used in programs that call
+.Xr chroot 2
+where the new root does not have its own log socket.
+.It Dv LOG_ODELAY
+Delay opening the connection to
+.Xr syslogd 8
+until the first message is logged.
+This is the opposite of
+.Dv LOG_NDELAY
+and is the default behaviour when neither option is specified.
+.It Dv LOG_PERROR
+Write the message to standard error output as well as to the system log.
+.It Dv LOG_PID
+Log the process ID with each message; useful for identifying
+instantiations of daemons.
+.El
+.Pp
+The
+.Fa facility
+parameter encodes a default facility to be assigned to all messages
+that do not have an explicit facility encoded.
+.Pp
+The
+.Fn openlog_r
+function is the reentrant 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
+reentrant functions.
+.Pp
+The
+.Fn closelog
+function can be used to close the log file.
+.Fn closelog_r
+does the same thing but in a reentrant 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, which
+corresponds to
+.Li setlogmask(LOG_UPTO(LOG_DEBUG)) .
+.Pp
+The
+.Fn setlogmask_r
+function is the reentrant version of
+.Fn setlogmask .
+It takes an additional pointer to a
+.Fa syslog_data
+structure.
+.Sh RETURN VALUES
+The routines
+.Fn setlogmask
+and
+.Fn setlogmask_r
+always return the previous log mask level.
+.Sh EXAMPLES
+.Bd -literal -offset indent
+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");
+.Ed
+.Pp
+For the reentrant 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
+.Sh STANDARDS
+The functions
+.Fn syslog ,
+.Fn openlog ,
+.Fn closelog ,
+and
+.Fn setlogmask
+conform to the X/Open Systems Interfaces option of
+.St -p1003.1-2008 .
+.Pp
+The facilities
+.Dv LOG_AUTHPRIV ,
+.Dv LOG_FTP ,
+and
+.Dv LOG_SYSLOG ,
+the option
+.Dv LOG_PERROR ,
+and the macro
+.Fn LOG_UPTO
+are extensions to that standard.
+.Pp
+The standard option
+.Dv LOG_NOWAIT
+is deprecated in
+.Ox
+and has no effect.
+.Sh HISTORY
+The functions
+.Fn syslog ,
+.Fn openlog ,
+and
+.Fn closelog
+appeared in
+.Bx 4.2 ,
+.Fn setlogmask
+in
+.Bx 4.3 ,
+and
+.Fn vsyslog
+in
+.Bx 4.3 Net/1 .
+.Pp
+The functions
+.Fn syslog_r ,
+.Fn vsyslog_r ,
+.Fn openlog_r ,
+.Fn closelog_r ,
+and
+.Fn setlogmask_r
+appeared in
+.Ox 3.1 .
+.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 the stack,
+leading to a possible security hole.
+This holds true even if the string has been built
+.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
+.Fn syslog_r
+and the other reentrant functions should only be used where
+reentrancy is required (for instance, in a signal handler).
+.Fn syslog
+being not reentrant, only
+.Fn syslog_r
+should be used here.
+For more information about reentrancy and signal handlers, see
+.Xr signal 3 .