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