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