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