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

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