diff options
Diffstat (limited to 'crypto/heimdal/lib/krb5/krb5_openlog.3')
| -rw-r--r-- | crypto/heimdal/lib/krb5/krb5_openlog.3 | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/crypto/heimdal/lib/krb5/krb5_openlog.3 b/crypto/heimdal/lib/krb5/krb5_openlog.3 new file mode 100644 index 0000000..87040ba --- /dev/null +++ b/crypto/heimdal/lib/krb5/krb5_openlog.3 @@ -0,0 +1,225 @@ +.\" Copyright (c) 1997 Kungliga Tekniska Högskolan +.\" $Id: krb5_openlog.3,v 1.4 1999/04/07 14:06:32 joda Exp $ +.Dd August 6, 1997 +.Dt KRB5_OPENLOG 3 +.Os HEIMDAL +.Sh NAME +.Nm krb5_initlog , +.Nm krb5_openlog , +.Nm krb5_closelog , +.Nm krb5_addlog_dest , +.Nm krb5_addlog_func , +.Nm krb5_log , +.Nm krb5_vlog , +.Nm krb5_log_msg , +.Nm krb5_vlog_msg +.Nd Heimdal logging functions +.Sh SYNOPSIS +.Fd #include <krb5.h> + +.\" ouch! +.ds xx \\*(fP\fR(\fP\\*(lI*\\*(fP +.ds xy \fR)\|\fP +.Fn "\\*(lItypedef void \\*(xxkrb5_log_log_func_t\\*(xy" "const char *time" "const char *message" "void *data" +.Fn "\\*(lItypedef void \\*(xxkrb5_log_close_func_t\\*(xy" "void *data" + +.Ft krb5_error_code +.Fn krb5_addlog_dest "krb5_context context" "krb5_log_facility *facility" "const char *destination" + +.Ft krb5_error_code +.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" + +.Ft krb5_error_code +.Fn krb5_closelog "krb5_context context" "krb5_log_facility *facility" + +.Ft krb5_error_code +.Fn krb5_initlog "krb5_context context" "const char *program" "krb5_log_facility **facility" + +.Ft krb5_error_code +.Fn krb5_log "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "..." + +.Ft krb5_error_code +.Fn krb5_log_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "..." + +.Ft krb5_error_code +.Fn krb5_openlog "krb5_context context" "const char *program" "krb5_log_facility **facility" + +.Ft krb5_error_code +.Fn krb5_vlog "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "va_list arglist" + +.Ft krb5_error_code +.Fn krb5_vlog_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "va_list arglist" + +.Sh DESCRIPTION +These functions logs messages to one or more destinations. +.Pp +The +.Fn krb5_openlog +function creates a logging +.Fa facility , +that is used to log messages. A facility consists of one or more +destinations (which can be files or syslog or some other device). The +.Fa program +parameter should be the generic name of the program that is doing the +logging. This name is used to lookup which destinations to use. This +information is contained in the +.Li logging +section of the +.Pa krb5.conf +configuration file. If no entry is found for +.Fa program , +the entry for +.Li default +is used, or if that is missing too, +.Li SYSLOG +will be used as destination. +.Pp +To close a logging facility, use the +.Fn krb5_closelog +function. +.Pp +To log a message to a facility use one of the functions +.Fn krb5_log , +.Fn krb5_log_msg , +.Fn krb5_vlog , +or +.Fn krb5_vlog_msg . +The functions ending in +.Li _msg +return in +.Fa reply +a pointer to the message that just got logged. This string is allocated, +and should be freed with +.Fn free . +The +.Fa format +is a standard +.Fn printf +style format string (but see the BUGS section). +.Pp + +If you want better control of where things gets logged, you can instead of using +.Fn krb5_openlog +call +.Fn krb5_initlog , +which just initializes a facility, but doesn't define any actual logging +destinations. You can then add destinations with the +.Fn krb5_addlog_dest +and +.Fn krb5_addlog_func +functions. The first of these takes a string specifying a logging +destination, and adds this to the facility. If you want to do some +non-standard logging you can use the +.Fn krb5_addlog_func +function, which takes a function to use when logging. +The +.Fa log +function is called for each message with +.Fa time +being a string specifying the current time, and +.Fa message +the message to log. +.Fa close +is called when the facility is closed. You can pass application specific data in the +.Fa data +parameter. The +.Fa min +and +.Fa max +parameter are the same as in a destination (defined below). To specify a +max of infinity, pass -1. +.Pp +.Fn krb5_openlog +calls +.Fn krb5_initlog +and then calls +.Fn krb5_addlog_dest +for each destination found. + +.Ss Destinations + +The defined destinations (as specified in +.Pa krb5.conf ) +follows: +.Bl -tag -width "xxx" -offset indent +.It Li STDERR +This logs to the program's stderr. +.It Li FILE: Ns Pa /file +.It Li FILE= Ns Pa /file +Log to the specified file. The form using a colon appends to the file, the +form with an equal truncates the file. The truncating form keeps the file +open, while the appending form closes it after each log message (which +makes it possible to rotate logs). The truncating form is mainly for +compatibility with the MIT libkrb5. +.It Li DEVICE= Ns Pa /device +This logs to the specified device, at present this is the same as +.Li FILE:/device . +.It Li CONSOLE +Log to the console, this is the same as +.Li DEVICE=/dev/console . +.It Li SYSLOG Ns Op :priority Ns Op :facility +Send messages to the syslog system, using priority, and facility. To +get the name for one of these, you take the name of the macro passed +to +.Xr syslog 3 , +and remove the leading +.Li LOG_ +.No ( Li LOG_NOTICE +becomes +.Li NOTICE ) . +The default values (as well as the values used for unrecognised +values), are +.Li ERR , +and +.Li AUTH , +respectively. See +.Xr syslog 3 +for a list of priorities and facilities. +.El +.Pp +Each destination may optionally be prepended with a range of logging +levels, specified as +.Li min-max/ . +If the +.Fa level +parameter to +.Fn krb5_log +is within this range (inclusive) the message gets logged to this +destination, otherwise not. Either of the min and max valued may be +omitted, in this case min is assumed to be zero, and max is assumed to be +infinity. If you don't include a dash, both min and max gets set to the +specified value. If no range is specified, all messages gets logged. +.Sh EXAMPLE +.Bd -literal -offset indent +[logging] + kdc = 0/FILE:/var/log/kdc.log + kdc = 1-/SYSLOG:INFO:USER + default = STDERR +.Ed +.Pp +This will log all messages from the +.Nm kdc +program with level 0 to +.Pa /var/log/kdc.log , +other messages will be logged to syslog with priority +.Li LOG_INFO , +and facility +.Li LOG_USER . +All other programs will log all messages to their stderr. +.Sh BUGS +These functions use +.Fn asprintf +to format the message. If your operating system does not have a working +.Fn asprintf , +a replacement will be used. At present this replacement does not handle +some correct conversion specifications (like floating point numbers). Until +this is fixed, the use of these conversions should be avoided. +.Pp +If logging is done to the syslog facility, these functions might not be +thread-safe, depending on the implementation of +.Fn openlog , +and +.Fn syslog . +.Sh SEE ALSO +.Xr syslog 3 , +.Xr krb5.conf 5 |
