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