1 .\" Copyright (c) 1997, 1999, 2001 - 2002 Kungliga Tekniska Högskolan
2 .\" (Royal Institute of Technology, Stockholm, Sweden).
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
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.
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.
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
40 .Nm krb5_addlog_dest ,
41 .Nm krb5_addlog_func ,
46 .Nd Heimdal logging functions
48 Kerberos 5 Library (libkrb5, -lkrb5)
52 .Fn "\*(lp*krb5_log_log_func_t\*(rp" "const char *time" "const char *message" "void *data"
54 .Fn "\*(lp*krb5_log_close_func_t\*(rp" "void *data"
56 .Fn krb5_addlog_dest "krb5_context context" "krb5_log_facility *facility" "const char *destination"
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"
60 .Fn krb5_closelog "krb5_context context" "krb5_log_facility *facility"
62 .Fn krb5_initlog "krb5_context context" "const char *program" "krb5_log_facility **facility"
64 .Fn krb5_log "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "..."
66 .Fn krb5_log_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "..."
68 .Fn krb5_openlog "krb5_context context" "const char *program" "krb5_log_facility **facility"
70 .Fn krb5_vlog "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "va_list arglist"
72 .Fn krb5_vlog_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "va_list arglist"
74 These functions logs messages to one or more destinations.
78 function creates a logging
80 that is used to log messages. A facility consists of one or more
81 destinations (which can be files or syslog or some other device). The
83 parameter should be the generic name of the program that is doing the
84 logging. This name is used to lookup which destinations to use. This
85 information is contained in the
89 configuration file. If no entry is found for
93 is used, or if that is missing too,
95 will be used as destination.
97 To close a logging facility, use the
101 To log a message to a facility use one of the functions
107 The functions ending in
111 a pointer to the message that just got logged. This string is allocated,
112 and should be freed with
118 style format string (but see the BUGS section).
120 If you want better control of where things gets logged, you can instead of using
124 which just initializes a facility, but doesn't define any actual logging
125 destinations. You can then add destinations with the
129 functions. The first of these takes a string specifying a logging
130 destination, and adds this to the facility. If you want to do some
131 non-standard logging you can use the
133 function, which takes a function to use when logging.
136 function is called for each message with
138 being a string specifying the current time, and
142 is called when the facility is closed. You can pass application specific data in the
148 parameter are the same as in a destination (defined below). To specify a
149 max of infinity, pass -1.
156 for each destination found.
158 The defined destinations (as specified in
161 .Bl -tag -width "xxx" -offset indent
163 This logs to the program's stderr.
164 .It Li FILE: Ns Pa /file
165 .It Li FILE= Ns Pa /file
166 Log to the specified file. The form using a colon appends to the file, the
167 form with an equal truncates the file. The truncating form keeps the file
168 open, while the appending form closes it after each log message (which
169 makes it possible to rotate logs). The truncating form is mainly for
170 compatibility with the MIT libkrb5.
171 .It Li DEVICE= Ns Pa /device
172 This logs to the specified device, at present this is the same as
175 Log to the console, this is the same as
176 .Li DEVICE=/dev/console .
177 .It Li SYSLOG Ns Op :priority Ns Op :facility
178 Send messages to the syslog system, using priority, and facility. To
179 get the name for one of these, you take the name of the macro passed
182 and remove the leading
187 The default values (as well as the values used for unrecognised
194 for a list of priorities and facilities.
197 Each destination may optionally be prepended with a range of logging
204 is within this range (inclusive) the message gets logged to this
205 destination, otherwise not. Either of the min and max valued may be
206 omitted, in this case min is assumed to be zero, and max is assumed to be
207 infinity. If you don't include a dash, both min and max gets set to the
208 specified value. If no range is specified, all messages gets logged.
210 .Bd -literal -offset indent
212 kdc = 0/FILE:/var/log/kdc.log
213 kdc = 1-/SYSLOG:INFO:USER
217 This will log all messages from the
219 program with level 0 to
220 .Pa /var/log/kdc.log ,
221 other messages will be logged to syslog with priority
225 All other programs will log all messages to their stderr.
232 to format the message. If your operating system does not have a working
234 a replacement will be used. At present this replacement does not handle
235 some correct conversion specifications (like floating point numbers). Until
236 this is fixed, the use of these conversions should be avoided.
238 If logging is done to the syslog facility, these functions might not be
239 thread-safe, depending on the implementation of