1.\" $NetBSD: krb5_openlog.3,v 1.2 2017/01/28 21:31:49 christos Exp $ 2.\" 3.\" Copyright (c) 1997, 1999, 2001 - 2002 Kungliga Tekniska Högskolan 4.\" (Royal Institute of Technology, Stockholm, Sweden). 5.\" 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.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" 3. Neither the name of the Institute nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" Id 35.Dd August 6, 1997 36.Dt KRB5_OPENLOG 3 37.Os 38.Sh NAME 39.Nm krb5_initlog , 40.Nm krb5_openlog , 41.Nm krb5_closelog , 42.Nm krb5_addlog_dest , 43.Nm krb5_addlog_func , 44.Nm krb5_log , 45.Nm krb5_vlog , 46.Nm krb5_log_msg , 47.Nm krb5_vlog_msg 48.Nd Heimdal logging functions 49.Sh LIBRARY 50Kerberos 5 Library (libkrb5, -lkrb5) 51.Sh SYNOPSIS 52.In krb5/krb5.h 53.Ft "typedef void" 54.Fn "\*(lp*krb5_log_log_func_t\*(rp" "const char *time" "const char *message" "void *data" 55.Ft "typedef void" 56.Fn "\*(lp*krb5_log_close_func_t\*(rp" "void *data" 57.Ft krb5_error_code 58.Fn krb5_addlog_dest "krb5_context context" "krb5_log_facility *facility" "const char *destination" 59.Ft krb5_error_code 60.Fn krb5_addlog_func "krb5_context context" "krb5_log_facility *facility" "int min" "int max" "krb5_log_log_func_t log" "krb5_log_close_func_t close" "void *data" 61.Ft krb5_error_code 62.Fn krb5_closelog "krb5_context context" "krb5_log_facility *facility" 63.Ft krb5_error_code 64.Fn krb5_initlog "krb5_context context" "const char *program" "krb5_log_facility **facility" 65.Ft krb5_error_code 66.Fn krb5_log "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "..." 67.Ft krb5_error_code 68.Fn krb5_log_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "..." 69.Ft krb5_error_code 70.Fn krb5_openlog "krb5_context context" "const char *program" "krb5_log_facility **facility" 71.Ft krb5_error_code 72.Fn krb5_vlog "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "va_list arglist" 73.Ft krb5_error_code 74.Fn krb5_vlog_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "va_list arglist" 75.Sh DESCRIPTION 76These functions logs messages to one or more destinations. 77.Pp 78The 79.Fn krb5_openlog 80function creates a logging 81.Fa facility , 82that is used to log messages. A facility consists of one or more 83destinations (which can be files or syslog or some other device). The 84.Fa program 85parameter should be the generic name of the program that is doing the 86logging. This name is used to lookup which destinations to use. This 87information is contained in the 88.Li logging 89section of the 90.Pa krb5.conf 91configuration file. If no entry is found for 92.Fa program , 93the entry for 94.Li default 95is used, or if that is missing too, 96.Li SYSLOG 97will be used as destination. 98.Pp 99To close a logging facility, use the 100.Fn krb5_closelog 101function. 102.Pp 103To log a message to a facility use one of the functions 104.Fn krb5_log , 105.Fn krb5_log_msg , 106.Fn krb5_vlog , 107or 108.Fn krb5_vlog_msg . 109The functions ending in 110.Li _msg 111return in 112.Fa reply 113a pointer to the message that just got logged. This string is allocated, 114and should be freed with 115.Fn free . 116The 117.Fa format 118is a standard 119.Fn printf 120style format string (but see the BUGS section). 121.Pp 122If you want better control of where things gets logged, you can instead of using 123.Fn krb5_openlog 124call 125.Fn krb5_initlog , 126which just initializes a facility, but doesn't define any actual logging 127destinations. You can then add destinations with the 128.Fn krb5_addlog_dest 129and 130.Fn krb5_addlog_func 131functions. The first of these takes a string specifying a logging 132destination, and adds this to the facility. If you want to do some 133non-standard logging you can use the 134.Fn krb5_addlog_func 135function, which takes a function to use when logging. 136The 137.Fa log 138function is called for each message with 139.Fa time 140being a string specifying the current time, and 141.Fa message 142the message to log. 143.Fa close 144is called when the facility is closed. You can pass application specific data in the 145.Fa data 146parameter. The 147.Fa min 148and 149.Fa max 150parameter are the same as in a destination (defined below). To specify a 151max of infinity, pass -1. 152.Pp 153.Fn krb5_openlog 154calls 155.Fn krb5_initlog 156and then calls 157.Fn krb5_addlog_dest 158for each destination found. 159.Ss Destinations 160The defined destinations (as specified in 161.Pa krb5.conf ) 162follows: 163.Bl -tag -width "xxx" -offset indent 164.It Li STDERR 165This logs to the program's stderr. 166.It Li FILE: Ns Pa /file 167.It Li FILE= Ns Pa /file 168Log to the specified file. The form using a colon appends to the file, the 169form with an equal truncates the file. The truncating form keeps the file 170open, while the appending form closes it after each log message (which 171makes it possible to rotate logs). The truncating form is mainly for 172compatibility with the MIT libkrb5. 173.It Li DEVICE= Ns Pa /device 174This logs to the specified device, at present this is the same as 175.Li FILE:/device . 176.It Li CONSOLE 177Log to the console, this is the same as 178.Li DEVICE=/dev/console . 179.It Li SYSLOG Ns Op :priority Ns Op :facility 180Send messages to the syslog system, using priority, and facility. To 181get the name for one of these, you take the name of the macro passed 182to 183.Xr syslog 3 , 184and remove the leading 185.Li LOG_ 186.No ( Li LOG_NOTICE 187becomes 188.Li NOTICE ) . 189The default values (as well as the values used for unrecognised 190values), are 191.Li ERR , 192and 193.Li AUTH , 194respectively. See 195.Xr syslog 3 196for a list of priorities and facilities. 197.El 198.Pp 199Each destination may optionally be prepended with a range of logging 200levels, specified as 201.Li min-max/ . 202If the 203.Fa level 204parameter to 205.Fn krb5_log 206is within this range (inclusive) the message gets logged to this 207destination, otherwise not. Either of the min and max valued may be 208omitted, in this case min is assumed to be zero, and max is assumed to be 209infinity. If you don't include a dash, both min and max gets set to the 210specified value. If no range is specified, all messages gets logged. 211.Sh EXAMPLES 212.Bd -literal -offset indent 213[logging] 214 kdc = 0/FILE:/var/log/kdc.log 215 kdc = 1-/SYSLOG:INFO:USER 216 default = STDERR 217.Ed 218.Pp 219This will log all messages from the 220.Nm kdc 221program with level 0 to 222.Pa /var/log/kdc.log , 223other messages will be logged to syslog with priority 224.Li LOG_INFO , 225and facility 226.Li LOG_USER . 227All other programs will log all messages to their stderr. 228.Sh SEE ALSO 229.Xr syslog 3 , 230.Xr krb5.conf 5 231.Sh BUGS 232These functions use 233.Fn asprintf 234to format the message. If your operating system does not have a working 235.Fn asprintf , 236a replacement will be used. At present this replacement does not handle 237some correct conversion specifications (like floating point numbers). Until 238this is fixed, the use of these conversions should be avoided. 239.Pp 240If logging is done to the syslog facility, these functions might not be 241thread-safe, depending on the implementation of 242.Fn openlog , 243and 244.Fn syslog . 245