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