1.\" $NetBSD: syslog.3,v 1.20 2006/10/25 23:49:31 christos 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. 113.Fn syslog_r 114function is a reentrant version of the 115.Fn syslog 116function. 117It takes a pointer to a 118.Fa syslog_data 119structure which is used to store 120information. 121This parameter must be initialized before 122.Fn syslog_r 123is called. 124The 125.Dv SYSLOG_DATA_INIT 126constant is used for this purpose. 127The 128.Fa syslog_data 129structure is composed of the following elements: 130.Bl -tag -width connected 131.It Dv log_file 132contains the file descriptor of the file where the message is logged 133.It Dv connected 134indicates if connect has been done 135.It Dv opened 136indicates if 137.Xr openlog_r 3 138has been called 139.It Dv log_stat 140status bits, set by 141.Xr openlog_r 3 142.It Dv log_tag 143string to tag the entry with 144.It Dv log_fac 145facility code 146.It Dv log_mask 147mask of priorities to be logged 148.El 149.Pp 150The 151.Fn vsyslog 152function 153is an alternative form in which the arguments have already been captured 154using the variable-length argument facilities of 155.Xr varargs 3 . 156.Pp 157The message is tagged with 158.Fa priority . 159Priorities are encoded as a 160.Fa facility 161and a 162.Em level . 163The facility describes the part of the system 164generating the message. 165The level is selected from the following 166.Em ordered 167(high to low) list: 168.Bl -tag -width LOG_AUTHPRIV 169.It Dv LOG_EMERG 170A panic condition. 171This is normally broadcast to all users. 172.It Dv LOG_ALERT 173A condition that should be corrected immediately, such as a corrupted 174system database. 175.It Dv LOG_CRIT 176Critical conditions, e.g., hard device errors. 177.It Dv LOG_ERR 178Errors. 179.It Dv LOG_WARNING 180Warning messages. 181.It Dv LOG_NOTICE 182Conditions that are not error conditions, 183but should possibly be handled specially. 184.It Dv LOG_INFO 185Informational messages. 186.It Dv LOG_DEBUG 187Messages that contain information 188normally of use only when debugging a program. 189.El 190.Pp 191The 192.Fn vsyslog_r 193is used the same way as 194.Fn vsyslog 195except that it takes an additional pointer on a 196.Fa syslog_data 197structure. 198It is a reentrant version of the 199.Fn vsyslog 200function described above. 201.Pp 202The 203.Fn openlog 204function 205provides for more specialized processing of the messages sent 206by 207.Fn syslog 208and 209.Fn vsyslog . 210The parameter 211.Fa ident 212is a string that will be prepended to every message. 213The 214.Fa logopt 215argument 216is a bit field specifying logging options, which is formed by 217.Tn OR Ns 'ing 218one or more of the following values: 219.Bl -tag -width LOG_AUTHPRIV 220.It Dv LOG_CONS 221If 222.Fn syslog 223cannot pass the message to 224.Xr syslogd 8 225it will attempt to write the message to the console 226.Pq Dq Pa /dev/console . 227.It Dv LOG_NDELAY 228Open the connection to 229.Xr syslogd 8 230immediately. 231Normally the open is delayed until the first message is logged. 232Useful for programs that need to manage the order in which file 233descriptors are allocated. 234.It Dv LOG_PERROR 235Write the message to standard error output as well to the system log. 236.It Dv LOG_PID 237Log the process id with each message: useful for identifying 238instantiations of daemons. 239(This PID is placed within brackets 240between the ident and the message.) 241.El 242.Pp 243The 244.Fa facility 245parameter encodes a default facility to be assigned to all messages 246that do not have an explicit facility encoded: 247.Bl -tag -width LOG_AUTHPRIV 248.It Dv LOG_AUTH 249The authorization system: 250.Xr login 1 , 251.Xr su 1 , 252.Xr getty 8 , 253etc. 254.It Dv LOG_AUTHPRIV 255The same as 256.Dv LOG_AUTH , 257but logged to a file readable only by 258selected individuals. 259.It Dv LOG_CRON 260The cron daemon: 261.Xr cron 8 . 262.It Dv LOG_DAEMON 263System daemons, such as 264.Xr routed 8 , 265that are not provided for explicitly by other facilities. 266.It Dv LOG_FTP 267The file transfer protocol daemon: 268.Xr ftpd 8 . 269.It Dv LOG_KERN 270Messages generated by the kernel. 271These cannot be generated by any user processes. 272.It Dv LOG_LPR 273The line printer spooling system: 274.Xr lpr 1 , 275.Xr lpc 8 , 276.Xr lpd 8 , 277etc. 278.It Dv LOG_MAIL 279The mail system. 280.It Dv LOG_NEWS 281The network news system. 282.It Dv LOG_SYSLOG 283Messages generated internally by 284.Xr syslogd 8 . 285.It Dv LOG_USER 286Messages generated by random user processes. 287This is the default facility identifier if none is specified. 288.It Dv LOG_UUCP 289The uucp system. 290.It Dv LOG_LOCAL0 291Reserved for local use. 292Similarly for 293.Dv LOG_LOCAL1 294through 295.Dv LOG_LOCAL7 . 296.El 297.Pp 298The 299.Fn openlog_r 300function is the reentrant version of the 301.Fn openlog 302function. 303It takes an additional pointer on a 304.Fa syslog_data 305structure. 306This function must be used in conjunction with the other 307reentrant functions. 308.Pp 309The 310.Fn closelog 311function 312can be used to close the log file. 313.Pp 314The 315.Fn closelog_r 316does the same thing as 317.Xr closelog 3 318but in a reentrant way and takes an additional 319pointer on a 320.Fa syslog_data 321structure. 322.Pp 323The 324.Fn setlogmask 325function 326sets the log priority mask to 327.Fa maskpri 328and returns the previous mask. 329Calls to 330.Fn syslog 331with a priority not set in 332.Fa maskpri 333are rejected. 334The mask for an individual priority 335.Fa pri 336is calculated by the macro 337.Fn LOG_MASK pri ; 338the mask for all priorities up to and including 339.Fa toppri 340is given by the macro 341.Fn LOG_UPTO toppri . 342The default allows all priorities to be logged. 343.Pp 344The 345.Fn setlogmask_r 346function is the reentrant version of 347.Fn setlogmask . 348It takes an additional pointer on a 349.Fa syslog_data 350structure. 351.Sh RETURN VALUES 352The routines 353.Fn closelog , 354.Fn closelog_r , 355.Fn openlog , 356.Fn openlog_r , 357.Fn syslog, 358.Fn syslog_r, 359.Fn vsyslog, 360and 361.Fn vsyslog_r 362return no value. 363.Pp 364The routines 365.Fn setlogmask 366and 367.Fn setlogmask_r 368always return the previous log mask level. 369.Sh EXAMPLES 370.Bd -literal -offset indent -compact 371syslog(LOG_ALERT, "who: internal error 23"); 372 373openlog("ftpd", LOG_PID | LOG_NDELAY, LOG_FTP); 374 375setlogmask(LOG_UPTO(LOG_ERR)); 376 377syslog(LOG_INFO, "Connection from host %d", CallingHost); 378 379syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); 380.Ed 381.Pp 382For the reentrant functions: 383.Bd -literal -offset indent 384struct syslog_data sdata = SYSLOG_DATA_INIT; 385 386syslog_r(LOG_INFO|LOG_LOCAL2, &sdata, "foobar error: %m"); 387.Ed 388.Sh SEE ALSO 389.Xr logger 1 , 390.Xr syslogd 8 391.Sh HISTORY 392These non-reentrant functions appeared in 393.Bx 4.2 . 394The reentrant functions appeared in 395.Ox 3.1 396and then in 397.Nx 4.0 . 398.Sh CAVEATS 399It is important never to pass a string with user-supplied data as a 400format without using 401.Ql %s . 402An attacker can put format specifiers in the string to mangle your stack, 403leading to a possible security hole. 404This holds true even if you have built the string 405.Dq by hand 406using a function like 407.Fn snprintf , 408as the resulting string may still contain user-supplied conversion specifiers 409for later interpolation by 410.Fn syslog . 411.Pp 412Always be sure to use the proper secure idiom: 413.Bd -literal -offset indent 414syslog(priority, "%s", string); 415.Ed 416.Pp 417.Fn syslog_r 418and the other reentrant functions should only be used where 419reentrancy is required (for instance, in a signal handler). 420.Fn syslog 421being not reentrant, only 422.Fn syslog_r 423should be used here. 424For more information about reentrancy and signal handlers, see 425.Xr signal 3 . 426