original/man3/syslog.3

   1 .\" Written  Feb 1994 by Steve Greenland (stevegr@neosoft.com)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Updated 1999.12.19 by Karl M. Hegbloom <karlheg@debian.org>
  26 .\"
  27 .\" Updated 13 Oct 2001, Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\"     Added description of vsyslog
  29 .\"     Added descriptions of LOG_ODELAY and LOG_NOWAIT
  30 .\"     Added brief description of facility and option arguments
  31 .\"     Added CONFORMING TO section
  32 .\" 2001-10-13, aeb, minor changes
  33 .\" Modified 13 Dec 2001, Martin Schulze <joey@infodrom.org>
  34 .\" Modified 3 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  35 .\"
  36 .TH SYSLOG 3 2012-08-17 "Linux" "Linux Programmer's Manual"
  37 .SH NAME
  38 closelog, openlog, syslog, vsyslog \- send messages to the system logger
  39 .SH SYNOPSIS
  40 .B #include <syslog.h>
  41 .sp
  42 .BI "void openlog(const char *" ident ", int " option ", int " facility );
  43 .br
  44 .BI "void syslog(int " priority ", const char *" format ", ...);"
  45 .br
  46 .B "void closelog(void);"
  47 .sp
  48 .B #include <stdarg.h>
  49 .sp
  50 .BI "void vsyslog(int " priority ", const char *" format ", va_list " ap );
  51 .sp
  52 .in -4n
  53 Feature Test Macro Requirements for glibc (see
  54 .BR feature_test_macros (7)):
  55 .in
  56 .sp
  57 .BR vsyslog ():
  58 _BSD_SOURCE
  59 .SH DESCRIPTION
  60 .BR closelog ()
  61 closes the descriptor being used to write to the system logger.
  62 The use of
  63 .BR closelog ()
  64 is optional.
  65 .sp
  66 .BR openlog ()
  67 opens a connection to the system logger for a program.
  68 The string pointed to by
  69 .I ident
  70 is prepended to every message, and is typically set to the program name.
  71 If
  72 .I ident
  73 is NULL, the program name is used.
  74 (POSIX.1-2008 does not specify the behavior when
  75 .I ident
  76 is NULL.)
  77
  78 The
  79 .I option
  80 argument specifies flags which control the operation of
  81 .BR openlog ()
  82 and subsequent calls to
  83 .BR syslog ().
  84 The
  85 .I facility
  86 argument establishes a default to be used if
  87 none is specified in subsequent calls to
  88 .BR syslog ().
  89 Values for
  90 .I option
  91 and
  92 .I facility
  93 are given below.
  94 The use of
  95 .BR openlog ()
  96 is optional; it will automatically be called by
  97 .BR syslog ()
  98 if necessary, in which case
  99 .I ident
 100 will default to NULL.
 101 .sp
 102 .BR syslog ()
 103 generates a log message, which will be distributed by
 104 .BR syslogd (8).
 105 The
 106 .I priority
 107 argument is formed by ORing the
 108 .I facility
 109 and the
 110 .I level
 111 values (explained below).
 112 The remaining arguments
 113 are a
 114 .IR format ,
 115 as in
 116 .BR printf (3)
 117 and any arguments required by the
 118 .IR format ,
 119 except that the two character sequence
 120 .B %m
 121 will be replaced by
 122 the error message string
 123 .IR strerror ( errno ).
 124 A trailing newline may be added if needed.
 125
 126 The function
 127 .BR vsyslog ()
 128 performs the same task as
 129 .BR syslog ()
 130 with the difference that it takes a set of arguments which have
 131 been obtained using the
 132 .BR stdarg (3)
 133 variable argument list macros.
 134
 135 The subsections below list the parameters used to set the values of
 136 .IR option , " facility" ", and " priority .
 137 .SS option
 138 The
 139 .I option
 140 argument to
 141 .BR openlog ()
 142 is an OR of any of these:
 143 .TP 15
 144 .B LOG_CONS
 145 Write directly to system console if there is an error while sending to
 146 system logger.
 147 .TP
 148 .B LOG_NDELAY
 149 Open the connection immediately (normally, the connection is opened when
 150 the first message is logged).
 151 .TP
 152 .B LOG_NOWAIT
 153 Don't wait for child processes that may have been created while logging
 154 the message.
 155 (The GNU C library does not create a child process, so this
 156 option has no effect on Linux.)
 157 .TP
 158 .B LOG_ODELAY
 159 The converse of
 160 .BR LOG_NDELAY ;
 161 opening of the connection is delayed until
 162 .BR syslog ()
 163 is called.
 164 (This is the default, and need not be specified.)
 165 .TP
 166 .B LOG_PERROR
 167 (Not in POSIX.1-2001 or POSIX.1-2008.)
 168 Print to \fIstderr\fP as well.
 169 .TP
 170 .B LOG_PID
 171 Include PID with each message.
 172 .SS facility
 173 The
 174 .I facility
 175 argument is used to specify what type of program is logging the message.
 176 This lets the configuration file specify that messages from different
 177 facilities will be handled differently.
 178 .TP 15
 179 .B LOG_AUTH
 180 security/authorization messages
 181 .TP
 182 .B LOG_AUTHPRIV
 183 security/authorization messages (private)
 184 .TP
 185 .B LOG_CRON
 186 clock daemon
 187 .RB ( cron " and " at )
 188 .TP
 189 .B LOG_DAEMON
 190 system daemons without separate facility value
 191 .TP
 192 .B LOG_FTP
 193 ftp daemon
 194 .TP
 195 .B LOG_KERN
 196 kernel messages (these can't be generated from user processes)
 197 .\" LOG_KERN has the value 0; if used as a facility, zero translates to:
 198 .\" "use the default facility".
 199 .TP
 200 .BR LOG_LOCAL0 " through " LOG_LOCAL7
 201 reserved for local use
 202 .TP
 203 .B LOG_LPR
 204 line printer subsystem
 205 .TP
 206 .B LOG_MAIL
 207 mail subsystem
 208 .TP
 209 .B LOG_NEWS
 210 USENET news subsystem
 211 .TP
 212 .B LOG_SYSLOG
 213 messages generated internally by
 214 .BR syslogd (8)
 215 .TP
 216 .BR LOG_USER " (default)"
 217 generic user-level messages
 218 .TP
 219 .B LOG_UUCP
 220 UUCP subsystem
 221 .SS level
 222 This determines the importance of the message.
 223 The levels are, in order of decreasing importance:
 224 .TP 15
 225 .B LOG_EMERG
 226 system is unusable
 227 .TP
 228 .B LOG_ALERT
 229 action must be taken immediately
 230 .TP
 231 .B LOG_CRIT
 232 critical conditions
 233 .TP
 234 .B LOG_ERR
 235 error conditions
 236 .TP
 237 .B LOG_WARNING
 238 warning conditions
 239 .TP
 240 .B LOG_NOTICE
 241 normal, but significant, condition
 242 .TP
 243 .B LOG_INFO
 244 informational message
 245 .TP
 246 .B LOG_DEBUG
 247 debug-level message
 248 .LP
 249 The function
 250 .BR setlogmask (3)
 251 can be used to restrict logging to specified levels only.
 252 .SH CONFORMING TO
 253 The functions
 254 .BR openlog (),
 255 .BR closelog (),
 256 and
 257 .BR syslog ()
 258 (but not
 259 .BR vsyslog ())
 260 are specified in SUSv2, POSIX.1-2001, and POSIX.1-2008.
 261 POSIX.1-2001 specifies only the
 262 .B LOG_USER
 263 and
 264 .B LOG_LOCAL*
 265 values for
 266 .IR facility .
 267 However, with the exception of
 268 .B LOG_AUTHPRIV
 269 and
 270 .BR LOG_FTP ,
 271 the other
 272 .I facility
 273 values appear on most UNIX systems.
 274 The
 275 .B LOG_PERROR
 276 value for
 277 .I option
 278 is not specified by POSIX.1-2001 or POSIX.1-2008, but is available
 279 in most versions of UNIX.
 280 .\" .SH HISTORY
 281 .\" A
 282 .\" .BR syslog ()
 283 .\" function call appeared in 4.2BSD.
 284 .\" 4.3BSD documents
 285 .\" .BR openlog (),
 286 .\" .BR syslog (),
 287 .\" .BR closelog (),
 288 .\" and
 289 .\" .BR setlogmask ().
 290 .\" 4.3BSD-Reno also documents
 291 .\" .BR vsyslog ().
 292 .\" Of course early v* functions used the
 293 .\" .I <varargs.h>
 294 .\" mechanism, which is not compatible with
 295 .\" .IR <stdarg.h> .
 296 .SH NOTES
 297 The argument
 298 .I ident
 299 in the call of
 300 .BR openlog ()
 301 is probably stored as-is.
 302 Thus, if the string it points to
 303 is changed,
 304 .BR syslog ()
 305 may start prepending the changed string, and if the string
 306 it points to ceases to exist, the results are undefined.
 307 Most portable is to use a string constant.
 308 .LP
 309 Never pass a string with user-supplied data as a format,
 310 use the following instead:
 311 .nf
 312
 313     syslog(priority, "%s", string);
 314 .fi
 315 .SH SEE ALSO
 316 .BR logger (1),
 317 .BR setlogmask (3),
 318 .BR syslog.conf (5),
 319 .BR syslogd (8)
 320 .SH COLOPHON
 321 This page is part of release 3.68 of the Linux
 322 .I man-pages
 323 project.
 324 A description of the project,
 325 information about reporting bugs,
 326 and the latest version of this page,
 327 can be found at
 328 \%http://www.kernel.org/doc/man\-pages/.