usr/src/man/man3c/syslog.3c

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright (c) 1983 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.
   4 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at  http://www.opengroup.org/bookstore/.
   6 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text
   7 .\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical
   8 .\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   9 .\"  This notice shall appear on any product containing this material.
  10 .TH SYSLOG 3C "Mar 16, 2009"
  11 .SH NAME
  12 syslog, openlog, closelog, setlogmask \- control system log
  13 .SH SYNOPSIS
  14 .LP
  15 .nf
  16 #include <syslog.h>
  17
  18 \fBvoid\fR \fBopenlog\fR(\fBconst char *\fR\fIident\fR, \fBint\fR \fIlogopt\fR, \fBint\fR \fIfacility\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBvoid\fR \fBsyslog\fR(\fBint\fR \fIpriority\fR, \fBconst char *\fR\fImessage\fR, \fB\&.../*\fR \fIarguments\fR */);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBvoid\fR \fBcloselog\fR(\fBvoid\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBsetlogmask\fR(\fBint\fR \fImaskpri\fR);
  34 .fi
  35
  36 .SH DESCRIPTION
  37 .LP
  38 The \fBsyslog()\fR function sends a message to \fBsyslogd\fR(1M), which,
  39 depending on the configuration of \fB/etc/syslog.conf\fR, logs it in an
  40 appropriate system log, writes it to the system console, forwards it to a list
  41 of users, or forwards it to \fBsyslogd\fR on another host over the network.
  42 The logged message includes a message header and a message body.  The message
  43 header consists of a facility indicator, a severity level indicator, a
  44 timestamp, a tag string, and optionally the process ID.
  45 .sp
  46 .LP
  47 The message body is generated from the \fImessage\fR and following arguments in
  48 the same manner as if these were arguments to \fBprintf\fR(3UCB), except that
  49 occurrences of \fB%m\fR in the format string pointed to by the \fImessage\fR
  50 argument are replaced by the error message string associated with the current
  51 value of \fBerrno\fR.  A trailing \fBNEWLINE\fR character is added if needed.
  52 .sp
  53 .LP
  54 Symbolic constants for use as values of the \fIlogopt\fR, \fIfacility\fR,
  55 \fIpriority\fR, and \fImaskpri\fR arguments are defined in the <\fBsyslog.h\fR>
  56 header.
  57 .sp
  58 .LP
  59 Values of the \fIpriority\fR argument are formed by ORing together a
  60 \fIseverity level\fR value and an optional \fIfacility\fR value.  If no
  61 facility value is specified, the current default facility value is used.
  62 .sp
  63 .LP
  64 Possible values of severity level include, in decreasing order:
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBLOG_EMERG\fR\fR
  69 .ad
  70 .RS 15n
  71 A panic condition.  This is normally broadcast to all users.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBLOG_ALERT\fR\fR
  78 .ad
  79 .RS 15n
  80 A condition that should be corrected immediately, such as a corrupted system
  81 database.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBLOG_CRIT\fR\fR
  88 .ad
  89 .RS 15n
  90 Critical conditions, such as hard device errors.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBLOG_ERR\fR\fR
  97 .ad
  98 .RS 15n
  99 Errors.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBLOG_WARNING\fR\fR
 106 .ad
 107 .RS 15n
 108 Warning messages.
 109 .RE
 110
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBLOG_NOTICE\fR\fR
 115 .ad
 116 .RS 15n
 117 Conditions that are not error conditions, but that may require special
 118 handling.
 119 .RE
 120
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBLOG_INFO\fR\fR
 125 .ad
 126 .RS 15n
 127 Informational messages.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBLOG_DEBUG\fR\fR
 134 .ad
 135 .RS 15n
 136 Messages that contain information normally of use only when debugging a
 137 program.
 138 .RE
 139
 140 .sp
 141 .LP
 142 The facility indicates the application or system component generating the
 143 message.  Possible facility values include:
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBLOG_KERN\fR\fR
 148 .ad
 149 .RS 14n
 150 Messages generated by the kernel. These cannot be generated by any user
 151 processes.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBLOG_USER\fR\fR
 158 .ad
 159 .RS 14n
 160 Messages generated by random user processes. This is the default facility
 161 identifier if none is specified.
 162 .RE
 163
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBLOG_MAIL\fR\fR
 168 .ad
 169 .RS 14n
 170 The mail system.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBLOG_DAEMON\fR\fR
 177 .ad
 178 .RS 14n
 179 System daemons.
 180 .RE
 181
 182 .sp
 183 .ne 2
 184 .na
 185 \fB\fBLOG_AUTH\fR\fR
 186 .ad
 187 .RS 14n
 188 The authentication / security / authorization system: \fBlogin\fR(1),
 189 \fBsu\fR(1M), \fBgetty\fR(1M).
 190 .RE
 191
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fBLOG_LPR\fR\fR
 196 .ad
 197 .RS 14n
 198 The line printer spooling system: \fBlpr\fR(1B), \fBlpc\fR(1B).
 199 .RE
 200
 201 .sp
 202 .ne 2
 203 .na
 204 \fB\fBLOG_NEWS\fR\fR
 205 .ad
 206 .RS 14n
 207 Designated for the \fBUSENET\fR network news system.
 208 .RE
 209
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fBLOG_UUCP\fR\fR
 214 .ad
 215 .RS 14n
 216 Designated for the \fBUUCP\fR system; it does not currently use \fBsyslog()\fR.
 217 .RE
 218
 219 .sp
 220 .ne 2
 221 .na
 222 \fB\fBLOG_CRON\fR\fR
 223 .ad
 224 .RS 14n
 225 The \fBcron\fR/\fBat\fR facility; \fBcrontab\fR(1), \fBat\fR(1),
 226 \fBcron\fR(1M).
 227 .RE
 228
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fBLOG_AUDIT\fR\fR
 233 .ad
 234 .RS 14n
 235 The audit facility, for example, \fBauditd\fR(1M).
 236 .RE
 237
 238 .sp
 239 .ne 2
 240 .na
 241 \fB\fBLOG_LOCAL0\fR\fR
 242 .ad
 243 .RS 14n
 244 Designated for local use.
 245 .RE
 246
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBLOG_LOCAL1\fR\fR
 251 .ad
 252 .RS 14n
 253 Designated for local use.
 254 .RE
 255
 256 .sp
 257 .ne 2
 258 .na
 259 \fB\fBLOG_LOCAL2\fR\fR
 260 .ad
 261 .RS 14n
 262 Designated for local use.
 263 .RE
 264
 265 .sp
 266 .ne 2
 267 .na
 268 \fB\fBLOG_LOCAL3\fR\fR
 269 .ad
 270 .RS 14n
 271 Designated for local use.
 272 .RE
 273
 274 .sp
 275 .ne 2
 276 .na
 277 \fB\fBLOG_LOCAL4\fR\fR
 278 .ad
 279 .RS 14n
 280 Designated for local use.
 281 .RE
 282
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fBLOG_LOCAL5\fR\fR
 287 .ad
 288 .RS 14n
 289 Designated for local use.
 290 .RE
 291
 292 .sp
 293 .ne 2
 294 .na
 295 \fB\fBLOG_LOCAL6\fR\fR
 296 .ad
 297 .RS 14n
 298 Designated for local use.
 299 .RE
 300
 301 .sp
 302 .ne 2
 303 .na
 304 \fB\fBLOG_LOCAL7\fR\fR
 305 .ad
 306 .RS 14n
 307 Designated for local use.
 308 .RE
 309
 310 .sp
 311 .LP
 312 The \fBopenlog()\fR function sets process attributes that affect subsequent
 313 calls to \fBsyslog()\fR. The \fIident\fR argument is a string that is prepended
 314 to every message. The \fBopenlog()\fR function uses the passed-in \fIident\fR
 315 argument directly, rather than making a private copy of it. The \fIlogopt\fR
 316 argument indicates logging options.  Values for \fIlogopt\fR are constructed by
 317 a bitwise-inclusive OR of zero or more of the following:
 318 .sp
 319 .ne 2
 320 .na
 321 \fB\fBLOG_PID\fR\fR
 322 .ad
 323 .RS 14n
 324 Log the process \fBID\fR with each message.  This is useful for identifying
 325 specific daemon processes (for daemons that fork).
 326 .RE
 327
 328 .sp
 329 .ne 2
 330 .na
 331 \fB\fBLOG_CONS\fR\fR
 332 .ad
 333 .RS 14n
 334 Write messages to the system console if they cannot be sent to
 335 \fBsyslogd\fR(1M). This option is safe to use in daemon processes that have no
 336 controlling terminal, since \fBsyslog()\fR forks before opening the console.
 337 .RE
 338
 339 .sp
 340 .ne 2
 341 .na
 342 \fB\fBLOG_NDELAY\fR\fR
 343 .ad
 344 .RS 14n
 345 Open the connection to \fBsyslogd\fR(1M) immediately.  Normally the open is
 346 delayed until the first message is logged. This is useful for programs that
 347 need to manage the order in which file descriptors are allocated.
 348 .RE
 349
 350 .sp
 351 .ne 2
 352 .na
 353 \fB\fBLOG_ODELAY\fR\fR
 354 .ad
 355 .RS 14n
 356 Delay open until \fBsyslog()\fR is called.
 357 .RE
 358
 359 .sp
 360 .ne 2
 361 .na
 362 \fB\fBLOG_NOWAIT\fR\fR
 363 .ad
 364 .RS 14n
 365 Do not wait for child processes that have been forked to log messages onto the
 366 console.  This option should be used by processes that enable notification of
 367 child termination using \fBSIGCHLD\fR, since \fBsyslog()\fR may otherwise block
 368 waiting for a child whose exit status has already been collected.
 369 .RE
 370
 371 .sp
 372 .LP
 373 The \fIfacility\fR argument encodes a default facility to be assigned to all
 374 messages that do not have an explicit facility already encoded.  The initial
 375 default facility is \fBLOG_USER\fR.
 376 .sp
 377 .LP
 378 The \fBopenlog()\fR and \fBsyslog()\fR functions may allocate a file
 379 descriptor.  It is not necessary to call \fBopenlog()\fR prior to calling
 380 \fBsyslog()\fR.
 381 .sp
 382 .LP
 383 The \fBcloselog()\fR function closes any open file descriptors allocated by
 384 previous calls to \fBopenlog()\fR or \fBsyslog()\fR.
 385 .sp
 386 .LP
 387 The \fBsetlogmask()\fR function sets the log priority mask for the current
 388 process to \fImaskpri\fR and returns the previous mask.  If the \fImaskpri\fR
 389 argument is 0, the current log mask is not modified.  Calls by the current
 390 process to \fBsyslog()\fR with a priority not set in \fImaskpri\fR are
 391 rejected.  The mask for an individual priority \fIpri\fR is calculated by the
 392 macro \fBLOG_MASK(\fIpri\fR)\fR; the mask for all priorities up to and
 393 including \fItoppri\fR is given by the macro \fBLOG_UPTO(\fItoppri\fR)\fR. The
 394 default log mask allows all priorities to be logged.
 395 .SH RETURN VALUES
 396 .LP
 397 The \fBsetlogmask()\fR function returns the previous log priority mask. The
 398 \fBcloselog()\fR, \fBopenlog()\fR and \fBsyslog()\fR functions return no value.
 399 .SH ERRORS
 400 .LP
 401 No errors are defined.
 402 .SH EXAMPLES
 403 .LP
 404 \fBExample 1 \fRExample of \fBLOG_ALERT\fR message.
 405 .sp
 406 .LP
 407 This call logs a message at priority \fBLOG_ALERT\fR:
 408
 409 .sp
 410 .in +2
 411 .nf
 412 \fBsyslog(LOG_ALERT, "who: internal error 23")\fR;
 413 .fi
 414 .in -2
 415 .sp
 416
 417 .sp
 418 .LP
 419 The \fBFTP\fR daemon \fBftpd\fR would make this call to \fBopenlog()\fR to
 420 indicate that all messages it logs should have an identifying string of
 421 \fBftpd\fR, should be treated by \fBsyslogd\fR(1M) as other messages from
 422 system daemons are, should include the process \fBID\fR of the process logging
 423 the message:
 424
 425 .sp
 426 .in +2
 427 .nf
 428 \fBopenlog("ftpd", LOG_PID, LOG_DAEMON)\fR;
 429 .fi
 430 .in -2
 431 .sp
 432
 433 .sp
 434 .LP
 435 Then it would make the following call to \fBsetlogmask()\fR to indicate that
 436 messages at priorities from \fBLOG_EMERG\fR through \fBLOG_ERR\fR should be
 437 logged, but that no messages at any other priority should be logged:
 438
 439 .sp
 440 .in +2
 441 .nf
 442 \fBsetlogmask(LOG_UPTO(LOG_ERR))\fR;
 443 .fi
 444 .in -2
 445 .sp
 446
 447 .sp
 448 .LP
 449 Then, to log a message at priority \fBLOG_INFO\fR, it would make the following
 450 call to \fBsyslog\fR:
 451
 452 .sp
 453 .in +2
 454 .nf
 455 \fBsyslog(LOG_INFO, "Connection from host %d", CallingHost)\fR;
 456 .fi
 457 .in -2
 458 .sp
 459
 460 .sp
 461 .LP
 462 A locally-written utility could use the following call to \fBsyslog()\fR to log
 463 a message at priority \fBLOG_INFO\fR to be treated by \fBsyslogd\fR(1M) as
 464 other messages to the facility  \fBLOG_LOCAL2\fR are:
 465
 466 .sp
 467 .in +2
 468 .nf
 469 \fBsyslog(LOG_INFO|LOG_LOCAL2, "error: %m")\fR;
 470 .fi
 471 .in -2
 472 .sp
 473
 474 .SH ATTRIBUTES
 475 .LP
 476 See \fBattributes\fR(5) for descriptions of the following attributes:
 477 .sp
 478
 479 .sp
 480 .TS
 481 box;
 482 c | c
 483 l | l .
 484 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 485 _
 486 Interface Stability     Committed
 487 _
 488 MT-Level        Safe
 489 _
 490 Standard        See \fBstandards\fR(5).
 491 .TE
 492
 493 .SH SEE ALSO
 494 .LP
 495 \fBat\fR(1), \fBcrontab\fR(1), \fBlogger\fR(1), \fBlogin\fR(1), \fBlpc\fR(1B),
 496 \fBlpr\fR(1B), \fBauditd\fR(1M), \fBcron\fR(1M), \fBgetty\fR(1M),
 497 \fBsu\fR(1M), \fBsyslogd\fR(1M), \fBprintf\fR(3UCB),
 498 \fBsyslog.conf\fR(4), \fBattributes\fR(5), \fBstandards\fR(5)