1.\" Copyright (c) 1997 Kungliga Tekniska H�gskolan 2.\" $Id: krb5_openlog.3,v 1.5 2001/01/26 22:43:22 assar Exp $ 3.Dd August 6, 1997 4.Dt KRB5_OPENLOG 3 5.Os HEIMDAL 6.Sh NAME 7.Nm krb5_initlog , 8.Nm krb5_openlog , 9.Nm krb5_closelog , 10.Nm krb5_addlog_dest , 11.Nm krb5_addlog_func , 12.Nm krb5_log , 13.Nm krb5_vlog , 14.Nm krb5_log_msg , 15.Nm krb5_vlog_msg 16.Nd Heimdal logging functions 17.Sh SYNOPSIS 18.Fd #include <krb5.h> 19.Ft "typedef void" 20.Fn "\*(lp*krb5_log_log_func_t\*(rp" "const char *time" "const char *message" "void *data" 21.Ft "typedef void" 22.Fn "\*(lp*krb5_log_close_func_t\*(rp" "void *data" 23.Ft krb5_error_code 24.Fn krb5_addlog_dest "krb5_context context" "krb5_log_facility *facility" "const char *destination" 25.Ft krb5_error_code 26.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" 27.Ft krb5_error_code 28.Fn krb5_closelog "krb5_context context" "krb5_log_facility *facility" 29.Ft krb5_error_code 30.Fn krb5_initlog "krb5_context context" "const char *program" "krb5_log_facility **facility" 31.Ft krb5_error_code 32.Fn krb5_log "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "..." 33.Ft krb5_error_code 34.Fn krb5_log_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "..." 35.Ft krb5_error_code 36.Fn krb5_openlog "krb5_context context" "const char *program" "krb5_log_facility **facility" 37.Ft krb5_error_code 38.Fn krb5_vlog "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "va_list arglist" 39.Ft krb5_error_code 40.Fn krb5_vlog_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "va_list arglist" 41.Sh DESCRIPTION 42These functions logs messages to one or more destinations. 43.Pp 44The 45.Fn krb5_openlog 46function creates a logging 47.Fa facility , 48that is used to log messages. A facility consists of one or more 49destinations (which can be files or syslog or some other device). The 50.Fa program 51parameter should be the generic name of the program that is doing the 52logging. This name is used to lookup which destinations to use. This 53information is contained in the 54.Li logging 55section of the 56.Pa krb5.conf 57configuration file. If no entry is found for 58.Fa program , 59the entry for 60.Li default 61is used, or if that is missing too, 62.Li SYSLOG 63will be used as destination. 64.Pp 65To close a logging facility, use the 66.Fn krb5_closelog 67function. 68.Pp 69To log a message to a facility use one of the functions 70.Fn krb5_log , 71.Fn krb5_log_msg , 72.Fn krb5_vlog , 73or 74.Fn krb5_vlog_msg . 75The functions ending in 76.Li _msg 77return in 78.Fa reply 79a pointer to the message that just got logged. This string is allocated, 80and should be freed with 81.Fn free . 82The 83.Fa format 84is a standard 85.Fn printf 86style format string (but see the BUGS section). 87.Pp 88If you want better control of where things gets logged, you can instead of using 89.Fn krb5_openlog 90call 91.Fn krb5_initlog , 92which just initializes a facility, but doesn't define any actual logging 93destinations. You can then add destinations with the 94.Fn krb5_addlog_dest 95and 96.Fn krb5_addlog_func 97functions. The first of these takes a string specifying a logging 98destination, and adds this to the facility. If you want to do some 99non-standard logging you can use the 100.Fn krb5_addlog_func 101function, which takes a function to use when logging. 102The 103.Fa log 104function is called for each message with 105.Fa time 106being a string specifying the current time, and 107.Fa message 108the message to log. 109.Fa close 110is called when the facility is closed. You can pass application specific data in the 111.Fa data 112parameter. The 113.Fa min 114and 115.Fa max 116parameter are the same as in a destination (defined below). To specify a 117max of infinity, pass -1. 118.Pp 119.Fn krb5_openlog 120calls 121.Fn krb5_initlog 122and then calls 123.Fn krb5_addlog_dest 124for each destination found. 125.Ss Destinations 126The defined destinations (as specified in 127.Pa krb5.conf ) 128follows: 129.Bl -tag -width "xxx" -offset indent 130.It Li STDERR 131This logs to the program's stderr. 132.It Li FILE: Ns Pa /file 133.It Li FILE= Ns Pa /file 134Log to the specified file. The form using a colon appends to the file, the 135form with an equal truncates the file. The truncating form keeps the file 136open, while the appending form closes it after each log message (which 137makes it possible to rotate logs). The truncating form is mainly for 138compatibility with the MIT libkrb5. 139.It Li DEVICE= Ns Pa /device 140This logs to the specified device, at present this is the same as 141.Li FILE:/device . 142.It Li CONSOLE 143Log to the console, this is the same as 144.Li DEVICE=/dev/console . 145.It Li SYSLOG Ns Op :priority Ns Op :facility 146Send messages to the syslog system, using priority, and facility. To 147get the name for one of these, you take the name of the macro passed 148to 149.Xr syslog 3 , 150and remove the leading 151.Li LOG_ 152.No ( Li LOG_NOTICE 153becomes 154.Li NOTICE ) . 155The default values (as well as the values used for unrecognised 156values), are 157.Li ERR , 158and 159.Li AUTH , 160respectively. See 161.Xr syslog 3 162for a list of priorities and facilities. 163.El 164.Pp 165Each destination may optionally be prepended with a range of logging 166levels, specified as 167.Li min-max/ . 168If the 169.Fa level 170parameter to 171.Fn krb5_log 172is within this range (inclusive) the message gets logged to this 173destination, otherwise not. Either of the min and max valued may be 174omitted, in this case min is assumed to be zero, and max is assumed to be 175infinity. If you don't include a dash, both min and max gets set to the 176specified value. If no range is specified, all messages gets logged. 177.Sh EXAMPLE 178.Bd -literal -offset indent 179[logging] 180 kdc = 0/FILE:/var/log/kdc.log 181 kdc = 1-/SYSLOG:INFO:USER 182 default = STDERR 183.Ed 184.Pp 185This will log all messages from the 186.Nm kdc 187program with level 0 to 188.Pa /var/log/kdc.log , 189other messages will be logged to syslog with priority 190.Li LOG_INFO , 191and facility 192.Li LOG_USER . 193All other programs will log all messages to their stderr. 194.Sh BUGS 195These functions use 196.Fn asprintf 197to format the message. If your operating system does not have a working 198.Fn asprintf , 199a replacement will be used. At present this replacement does not handle 200some correct conversion specifications (like floating point numbers). Until 201this is fixed, the use of these conversions should be avoided. 202.Pp 203If logging is done to the syslog facility, these functions might not be 204thread-safe, depending on the implementation of 205.Fn openlog , 206and 207.Fn syslog . 208.Sh SEE ALSO 209.Xr syslog 3 , 210.Xr krb5.conf 5 211