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