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