243 lines
8.0 KiB
Groff
243 lines
8.0 KiB
Groff
.\" Copyright (c) 1997, 1999, 2001 - 2002 Kungliga Tekniska Högskolan
|
|
.\" (Royal Institute of Technology, Stockholm, Sweden).
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" 3. Neither the name of the Institute nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $Id: krb5_openlog.3 12329 2003-05-26 14:09:04Z lha $
|
|
.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 LIBRARY
|
|
Kerberos 5 Library (libkrb5, -lkrb5)
|
|
.Sh SYNOPSIS
|
|
.In krb5.h
|
|
.Ft "typedef void"
|
|
.Fn "\*(lp*krb5_log_log_func_t\*(rp" "const char *time" "const char *message" "void *data"
|
|
.Ft "typedef void"
|
|
.Fn "\*(lp*krb5_log_close_func_t\*(rp" "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 EXAMPLES
|
|
.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 SEE ALSO
|
|
.Xr syslog 3 ,
|
|
.Xr krb5.conf 5
|
|
.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 .
|