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