lib/libc/gen/syslog.3

   1 .\" Copyright (c) 1985, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)syslog.3    8.1 (Berkeley) 6/4/93
  29 .\"
  30 .Dd July 3, 2023
  31 .Dt SYSLOG 3
  32 .Os
  33 .Sh NAME
  34 .Nm syslog ,
  35 .Nm vsyslog ,
  36 .Nm openlog ,
  37 .Nm closelog ,
  38 .Nm setlogmask
  39 .Nd control system log
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In syslog.h
  44 .Ft void
  45 .Fn syslog "int priority" "const char *message" "..."
  46 .Ft void
  47 .Fn openlog "const char *ident" "int logopt" "int facility"
  48 .Ft void
  49 .Fn closelog void
  50 .Ft int
  51 .Fn setlogmask "int maskpri"
  52 .In syslog.h
  53 .In stdarg.h
  54 .Ft void
  55 .Fn vsyslog "int priority" "const char *message" "va_list args"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn syslog
  59 function
  60 writes
  61 .Fa message
  62 to the system message logger.
  63 The message is then written to the system console, log files,
  64 logged-in users, or forwarded to other machines as appropriate.
  65 (See
  66 .Xr syslogd 8 . )
  67 .Pp
  68 The message is identical to a
  69 .Xr printf 3
  70 format string, except that
  71 .Ql %m
  72 is replaced by the current error
  73 message.
  74 (As denoted by the global variable
  75 .Va errno ;
  76 see
  77 .Xr strerror 3 . )
  78 A trailing newline is added if none is present.
  79 .Pp
  80 The
  81 .Fn vsyslog
  82 function
  83 is an alternate form in which the arguments have already been captured
  84 using the variable-length argument facilities of
  85 .Xr stdarg 3 .
  86 .Pp
  87 The message is tagged with
  88 .Fa priority .
  89 Priorities are encoded as a
  90 .Fa facility
  91 and a
  92 .Em level .
  93 The facility describes the part of the system
  94 generating the message.
  95 The level is selected from the following
  96 .Em ordered
  97 (high to low) list:
  98 .Bl -tag -width LOG_AUTHPRIV
  99 .It Dv LOG_EMERG
 100 A panic condition.
 101 This is normally broadcast to all users.
 102 .It Dv LOG_ALERT
 103 A condition that should be corrected immediately, such as a corrupted
 104 system database.
 105 .It Dv LOG_CRIT
 106 Critical conditions, e.g., hard device errors.
 107 .It Dv LOG_ERR
 108 Errors.
 109 .It Dv LOG_WARNING
 110 Warning messages.
 111 .It Dv LOG_NOTICE
 112 Conditions that are not error conditions,
 113 but should possibly be handled specially.
 114 .It Dv LOG_INFO
 115 Informational messages.
 116 .It Dv LOG_DEBUG
 117 Messages that contain information
 118 normally of use only when debugging a program.
 119 .El
 120 .Pp
 121 The
 122 .Fn openlog
 123 function
 124 provides for more specialized processing of the messages sent
 125 by
 126 .Fn syslog
 127 and
 128 .Fn vsyslog .
 129 The
 130 .Fa ident
 131 argument
 132 is a string that will be prepended to every message.
 133 It may be formatted as
 134 .Fa ident[N]
 135 in which case decimal number
 136 .Fa N
 137 replaces the process id within messages.
 138 The
 139 .Fa logopt
 140 argument
 141 is a bit field specifying logging options, which is formed by
 142 .Tn OR Ns 'ing
 143 one or more of the following values:
 144 .Bl -tag -width LOG_AUTHPRIV
 145 .It Dv LOG_CONS
 146 If
 147 .Fn syslog
 148 cannot pass the message to
 149 .Xr syslogd 8
 150 it will attempt to write the message to the console
 151 .Pq Dq Pa /dev/console .
 152 .It Dv LOG_NDELAY
 153 Open the connection to
 154 .Xr syslogd 8
 155 immediately.
 156 Normally the open is delayed until the first message is logged.
 157 Useful for programs that need to manage the order in which file
 158 descriptors are allocated.
 159 .It Dv LOG_PERROR
 160 Write the message to standard error output as well to the system log.
 161 .It Dv LOG_PID
 162 Log the process id with each message: useful for identifying
 163 instantiations of daemons.
 164 On
 165 .Fx ,
 166 this option is enabled by default and cannot be disabled.
 167 .El
 168 .Pp
 169 The
 170 .Fa facility
 171 argument encodes a default facility to be assigned to all messages
 172 that do not have an explicit facility encoded:
 173 .Bl -tag -width LOG_AUTHPRIV
 174 .It Dv LOG_AUTH
 175 The authorization system:
 176 .Xr login 1 ,
 177 .Xr su 1 ,
 178 .Xr getty 8 ,
 179 etc.
 180 .It Dv LOG_AUTHPRIV
 181 The same as
 182 .Dv LOG_AUTH ,
 183 but logged to a file readable only by
 184 selected individuals.
 185 .It Dv LOG_CONSOLE
 186 Messages written to
 187 .Pa /dev/console
 188 by the kernel console output driver.
 189 .It Dv LOG_CRON
 190 The cron daemon:
 191 .Xr cron 8 .
 192 .It Dv LOG_DAEMON
 193 System daemons, such as
 194 .Xr routed 8 ,
 195 that are not provided for explicitly by other facilities.
 196 .It Dv LOG_FTP
 197 The file transfer protocol daemons:
 198 .Xr ftpd 8 ,
 199 .Xr tftpd 8 .
 200 .It Dv LOG_KERN
 201 Messages generated by the kernel.
 202 These cannot be generated by any user processes.
 203 .It Dv LOG_LPR
 204 The line printer spooling system:
 205 .Xr lpr 1 ,
 206 .Xr lpc 8 ,
 207 .Xr lpd 8 ,
 208 etc.
 209 .It Dv LOG_MAIL
 210 The mail system.
 211 .It Dv LOG_NEWS
 212 The network news system.
 213 .It Dv LOG_NTP
 214 The network time protocol system.
 215 .It Dv LOG_SECURITY
 216 Security subsystems, such as
 217 .Xr ipfw 4 .
 218 .It Dv LOG_SYSLOG
 219 Messages generated internally by
 220 .Xr syslogd 8 .
 221 .It Dv LOG_USER
 222 Messages generated by random user processes.
 223 This is the default facility identifier if none is specified.
 224 .It Dv LOG_UUCP
 225 The uucp system.
 226 .It Dv LOG_LOCAL0
 227 Reserved for local use.
 228 Similarly for
 229 .Dv LOG_LOCAL1
 230 through
 231 .Dv LOG_LOCAL7 .
 232 .El
 233 .Pp
 234 The
 235 .Fn closelog
 236 function
 237 can be used to close the log file.
 238 .Pp
 239 The
 240 .Fn setlogmask
 241 function
 242 sets the log priority mask to
 243 .Fa maskpri
 244 and returns the previous mask.
 245 Calls to
 246 .Fn syslog
 247 with a priority not set in
 248 .Fa maskpri
 249 are rejected.
 250 The mask for an individual priority
 251 .Fa pri
 252 is calculated by the macro
 253 .Fn LOG_MASK pri ;
 254 the mask for all priorities up to and including
 255 .Fa toppri
 256 is given by the macro
 257 .Fn LOG_UPTO toppri ; .
 258 The default allows all priorities to be logged.
 259 .Sh RETURN VALUES
 260 The routines
 261 .Fn closelog ,
 262 .Fn openlog ,
 263 .Fn syslog
 264 and
 265 .Fn vsyslog
 266 return no value.
 267 .Pp
 268 The routine
 269 .Fn setlogmask
 270 always returns the previous log mask level.
 271 .Sh EXAMPLES
 272 .Bd -literal -offset indent -compact
 273 syslog(LOG_ALERT, "who: internal error 23");
 274
 275 openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP);
 276
 277 setlogmask(LOG_UPTO(LOG_ERR));
 278
 279 syslog(LOG_INFO, "Connection from host %d", CallingHost);
 280
 281 syslog(LOG_ERR|LOG_LOCAL2, "foobar error: %m");
 282 .Ed
 283 .Sh SEE ALSO
 284 .Xr logger 1 ,
 285 .Xr syslogd 8
 286 .Sh HISTORY
 287 These
 288 functions appeared in
 289 .Bx 4.2 .
 290 .Sh BUGS
 291 Never pass a string with user-supplied data as a format without using
 292 .Ql %s .
 293 An attacker can put format specifiers in the string to mangle your stack,
 294 leading to a possible security hole.
 295 This holds true even if the string was built using a function like
 296 .Fn snprintf ,
 297 as the resulting string may still contain user-supplied conversion specifiers
 298 for later interpolation by
 299 .Fn syslog .
 300 .Pp
 301 Always use the proper secure idiom:
 302 .Pp
 303 .Dl syslog(priority, \*q%s\*q, string);