1.\" $NetBSD: syslog.3,v 1.21 2006/10/26 13:08:17 wiz Exp $ 2.\" $OpenBSD: syslog.3,v 1.25 2005/07/22 03:16:58 jaredy Exp $ 3.\" 4.\" Copyright (c) 1985, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)syslog.3 8.1 (Berkeley) 6/4/93 32.\" 33.Dd October 25, 2006 34.Dt SYSLOG 3 35.Os 36.Sh NAME 37.Nm syslog , 38.Nm syslog_r , 39.Nm vsyslog , 40.Nm vsyslog_r , 41.Nm openlog , 42.Nm openlog_r , 43.Nm closelog , 44.Nm closelog_r , 45.Nm setlogmask , 46.Nm setlogmask_r 47.Nd control system log 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.In syslog.h 52.Ft void 53.Fn syslog "int priority" "const char *message" "..." 54.Ft void 55.Fn syslog_r "int priority" "struct syslog_data *data" "const char *message" "..." 56.Ft void 57.Fn openlog "const char *ident" "int logopt" "int facility" 58.Ft void 59.Fn openlog_r "const char *ident" "int logopt" "int facility" "struct syslog_data *data" 60.Ft void 61.Fn closelog void 62.Ft void 63.Fn closelog_r "struct syslog_data *data" 64.Ft int 65.Fn setlogmask "int maskpri" 66.Ft int 67.Fn setlogmask_r "int maskpri" "struct syslog_data *data" 68.In stdarg.h 69.Ft void 70.Fn vsyslog "int priority" "const char *message" "va_list args" 71.Ft void 72.Fn vsyslog_r "int priority" "struct syslog_data *data" "const char *message" "va_list args" 73.Bd -literal 74 75struct syslog_data { 76 int log_file; 77 int connected; 78 int opened; 79 int log_stat; 80 const char *log_tag; 81 int log_fac; 82 int log_mask; 83}; 84 85#define SYSLOG_DATA_INIT { \e 86 .log_file = -1, \e 87 .log_fac = LOG_USER, \e 88 .log_mask = 0xff, \e 89} 90.Ed 91.Sh DESCRIPTION 92The 93.Fn syslog 94function 95writes 96.Fa message 97to the system message logger. 98The message is then written to the system console, log files, 99logged-in users, or forwarded to other machines as appropriate (See 100.Xr syslogd 8 ) . 101.Pp 102The message is identical to a 103.Xr printf 3 104format string, except that 105.Ql %m 106is replaced by the current error 107message. 108(As denoted by the global variable 109.Va errno ; 110see 111.Xr strerror 3 . ) 112A trailing newline is added if none is present. 113The 114.Fn syslog_r 115function is a reentrant version of the 116.Fn syslog 117function. 118It takes a pointer to a 119.Fa syslog_data 120structure which is used to store 121information. 122This parameter must be initialized before 123.Fn syslog_r 124is called. 125The 126.Dv SYSLOG_DATA_INIT 127constant is used for this purpose. 128The 129.Fa syslog_data 130structure is composed of the following elements: 131.Bl -tag -width connected 132.It Dv log_file 133contains the file descriptor of the file where the message is logged 134.It Dv connected 135indicates if connect has been done 136.It Dv opened 137indicates if 138.Fn openlog_r 139has been called 140.It Dv log_stat 141status bits, set by 142.Fn openlog_r 143.It Dv log_tag 144string to tag the entry with 145.It Dv log_fac 146facility code 147.It Dv log_mask 148mask of priorities to be logged 149.El 150.Pp 151The 152.Fn vsyslog 153function 154is an alternative form in which the arguments have already been captured 155using the variable-length argument facilities of 156.Xr varargs 3 . 157.Pp 158The message is tagged with 159.Fa priority . 160Priorities are encoded as a 161.Fa facility 162and a 163.Em level . 164The facility describes the part of the system 165generating the message. 166The level is selected from the following 167.Em ordered 168(high to low) list: 169.Bl -tag -width LOG_AUTHPRIV 170.It Dv LOG_EMERG 171A panic condition. 172This is normally broadcast to all users. 173.It Dv LOG_ALERT 174A condition that should be corrected immediately, such as a corrupted 175system database. 176.It Dv LOG_CRIT 177Critical conditions, e.g., hard device errors. 178.It Dv LOG_ERR 179Errors. 180.It Dv LOG_WARNING 181Warning messages. 182.It Dv LOG_NOTICE 183Conditions that are not error conditions, 184but should possibly be handled specially. 185.It Dv LOG_INFO 186Informational messages. 187.It Dv LOG_DEBUG 188Messages that contain information 189normally of use only when debugging a program. 190.El 191.Pp 192The 193.Fn vsyslog_r 194is used the same way as 195.Fn vsyslog 196except that it takes an additional pointer to a 197.Fa syslog_data 198structure. 199It is a reentrant version of the 200.Fn vsyslog 201function described above. 202.Pp 203The 204.Fn openlog 205function 206provides for more specialized processing of the messages sent 207by 208.Fn syslog 209and 210.Fn vsyslog . 211The parameter 212.Fa ident 213is a string that will be prepended to every message. 214The 215.Fa logopt 216argument 217is a bit field specifying logging options, which is formed by 218.Tn OR Ns 'ing 219one or more of the following values: 220.Bl -tag -width LOG_AUTHPRIV 221.It Dv LOG_CONS 222If 223.Fn syslog 224cannot pass the message to 225.Xr syslogd 8 226it will attempt to write the message to the console 227.Pq Dq Pa /dev/console . 228.It Dv LOG_NDELAY 229Open the connection to 230.Xr syslogd 8 231immediately. 232Normally the open is delayed until the first message is logged. 233Useful for programs that need to manage the order in which file 234descriptors are allocated. 235.It Dv LOG_PERROR 236Write the message to standard error output as well to the system log. 237.It Dv LOG_PID 238Log the process id with each message: useful for identifying 239instantiations of daemons. 240(This PID is placed within brackets 241between the ident and the message.) 242.El 243.Pp 244The 245.Fa facility 246parameter encodes a default facility to be assigned to all messages 247that do not have an explicit facility encoded: 248.Bl -tag -width LOG_AUTHPRIV 249.It Dv LOG_AUTH 250The authorization system: 251.Xr login 1 , 252.Xr su 1 , 253.Xr getty 8 , 254etc. 255.It Dv LOG_AUTHPRIV 256The same as 257.Dv LOG_AUTH , 258but logged to a file readable only by 259selected individuals. 260.It Dv LOG_CRON 261The cron daemon: 262.Xr cron 8 . 263.It Dv LOG_DAEMON 264System daemons, such as 265.Xr routed 8 , 266that are not provided for explicitly by other facilities. 267.It Dv LOG_FTP 268The file transfer protocol daemon: 269.Xr ftpd 8 . 270.It Dv LOG_KERN 271Messages generated by the kernel. 272These cannot be generated by any user processes. 273.It Dv LOG_LPR 274The line printer spooling system: 275.Xr lpr 1 , 276.Xr lpc 8 , 277.Xr lpd 8 , 278etc. 279.It Dv LOG_MAIL 280The mail system. 281.It Dv LOG_NEWS 282The network news system. 283.It Dv LOG_SYSLOG 284Messages generated internally by 285.Xr syslogd 8 . 286.It Dv LOG_USER 287Messages generated by random user processes. 288This is the default facility identifier if none is specified. 289.It Dv LOG_UUCP 290The uucp system. 291.It Dv LOG_LOCAL0 292Reserved for local use. 293Similarly for 294.Dv LOG_LOCAL1 295through 296.Dv LOG_LOCAL7 . 297.El 298.Pp 299The 300.Fn openlog_r 301function is the reentrant version of the 302.Fn openlog 303function. 304It takes an additional pointer to a 305.Fa syslog_data 306structure. 307This function must be used in conjunction with the other 308reentrant functions. 309.Pp 310The 311.Fn closelog 312function 313can be used to close the log file. 314.Pp 315The 316.Fn closelog_r 317does the same thing as 318.Xr closelog 3 319but in a reentrant way and takes an additional 320pointer to a 321.Fa syslog_data 322structure. 323.Pp 324The 325.Fn setlogmask 326function 327sets the log priority mask to 328.Fa maskpri 329and returns the previous mask. 330Calls to 331.Fn syslog 332with a priority not set in 333.Fa maskpri 334are rejected. 335The mask for an individual priority 336.Fa pri 337is calculated by the macro 338.Fn LOG_MASK pri ; 339the mask for all priorities up to and including 340.Fa toppri 341is given by the macro 342.Fn LOG_UPTO toppri . 343The default allows all priorities to be logged. 344.Pp 345The 346.Fn setlogmask_r 347function is the reentrant version of 348.Fn setlogmask . 349It takes an additional pointer to a 350.Fa syslog_data 351structure. 352.Sh RETURN VALUES 353The routines 354.Fn closelog , 355.Fn closelog_r , 356.Fn openlog , 357.Fn openlog_r , 358.Fn syslog , 359.Fn syslog_r , 360.Fn vsyslog , 361and 362.Fn vsyslog_r 363return no value. 364.Pp 365The routines 366.Fn setlogmask 367and 368.Fn setlogmask_r 369always return the previous log mask level. 370.Sh EXAMPLES 371.Bd -literal -offset indent -compact 372syslog(LOG_ALERT, "who: internal error 23"); 373 374openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP); 375 376setlogmask(LOG_UPTO(LOG_ERR)); 377 378syslog(LOG_INFO, "Connection from host %d", CallingHost); 379 380syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); 381.Ed 382.Pp 383For the reentrant functions: 384.Bd -literal -offset indent 385struct syslog_data sdata = SYSLOG_DATA_INIT; 386 387syslog_r(LOG_INFO|LOG_LOCAL2, \*[Am]sdata, "foobar error: %m"); 388.Ed 389.Sh SEE ALSO 390.Xr logger 1 , 391.Xr syslogd 8 392.Sh HISTORY 393These non-reentrant functions appeared in 394.Bx 4.2 . 395The reentrant functions appeared in 396.Ox 3.1 397and then in 398.Nx 4.0 . 399.Sh CAVEATS 400It is important never to pass a string with user-supplied data as a 401format without using 402.Ql %s . 403An attacker can put format specifiers in the string to mangle your stack, 404leading to a possible security hole. 405This holds true even if you have built the string 406.Dq by hand 407using a function like 408.Fn snprintf , 409as the resulting string may still contain user-supplied conversion specifiers 410for later interpolation by 411.Fn syslog . 412.Pp 413Always be sure to use the proper secure idiom: 414.Bd -literal -offset indent 415syslog(priority, "%s", string); 416.Ed 417.Pp 418.Fn syslog_r 419and the other reentrant functions should only be used where 420reentrancy is required (for instance, in a signal handler). 421.Fn syslog 422being not reentrant, only 423.Fn syslog_r 424should be used here. 425For more information about reentrancy and signal handlers, see 426.Xr signal 3 . 427