man3/syslog.3

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