Manual page.
git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@2719 ec53bebd-3082-4978-b11e-865c3cabbd6b
This commit is contained in:
Johan Danielsson
170
lib/krb5/krb5_openlog.3
Normal file
170
lib/krb5/krb5_openlog.3
Normal file
@@ -0,0 +1,170 @@
|
||||
.\" Copyright (c) 1997 Kungliga Tekniska H<>gskolan
|
||||
.\" $Id$
|
||||
.Dd August 6, 1997
|
||||
.Dt KRB5_OPENLOG 3
|
||||
.Os HEIMDAL
|
||||
.Sh NAME
|
||||
.Nm krb5_openlog ,
|
||||
.Nm krb5_closelog ,
|
||||
.Nm krb5_log ,
|
||||
.Nm krb5_vlog ,
|
||||
.Nm krb5_log_msg ,
|
||||
.Nm krb5_vlog_msg
|
||||
.Nd Heimdal logging functions
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <krb5.h>
|
||||
.Ft krb5_error_code
|
||||
.Fn krb5_closelog "krb5_context context" "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).
|
||||
|
||||
.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 .
|
||||
.Pp
|
||||
It should be possible to pass a list of destinations to
|
||||
.Fn krb5_openlog .
|
||||
.Sh SEE ALSO
|
||||
.Xr syslog 3 ,
|
||||
.Xr krb5.conf 5
|
||||
Reference in New Issue
Block a user