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