crypto/heimdal-0.6.3/lib/krb5/krb5_openlog.3

   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: krb5_openlog.3,v 1.9 2003/04/16 13:58:12 lha Exp $
  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
  48 Kerberos 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
  74 These functions logs messages to one or more destinations.
  75 .Pp
  76 The
  77 .Fn krb5_openlog
  78 function creates a logging
  79 .Fa facility ,
  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
  82 .Fa program
  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
  86 .Li logging
  87 section of the
  88 .Pa krb5.conf
  89 configuration file.  If no entry is found for
  90 .Fa program ,
  91 the entry for
  92 .Li default
  93 is used, or if that is missing too,
  94 .Li SYSLOG
  95 will be used as destination.
  96 .Pp
  97 To close a logging facility, use the
  98 .Fn krb5_closelog
  99 function.
 100 .Pp
 101 To log a message to a facility use one of the functions
 102 .Fn krb5_log ,
 103 .Fn krb5_log_msg ,
 104 .Fn krb5_vlog ,
 105 or
 106 .Fn krb5_vlog_msg .
 107 The functions ending in
 108 .Li _msg
 109 return in
 110 .Fa reply
 111 a pointer to the message that just got logged. This string is allocated,
 112 and should be freed with
 113 .Fn free .
 114 The
 115 .Fa format
 116 is a standard
 117 .Fn printf
 118 style format string (but see the BUGS section).
 119 .Pp
 120 If you want better control of where things gets logged, you can instead of using
 121 .Fn krb5_openlog
 122 call
 123 .Fn krb5_initlog ,
 124 which just initializes a facility, but doesn't define any actual logging
 125 destinations. You can then add destinations with the
 126 .Fn krb5_addlog_dest
 127 and
 128 .Fn krb5_addlog_func
 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
 132 .Fn krb5_addlog_func
 133 function, which takes a function to use when logging.
 134 The
 135 .Fa log
 136 function is called for each message with
 137 .Fa time
 138 being a string specifying the current time, and
 139 .Fa message
 140 the message to log.
 141 .Fa close
 142 is called when the facility is closed. You can pass application specific data in the
 143 .Fa data
 144 parameter. The
 145 .Fa min
 146 and
 147 .Fa max
 148 parameter are the same as in a destination (defined below). To specify a
 149 max of infinity, pass -1.
 150 .Pp
 151 .Fn krb5_openlog
 152 calls
 153 .Fn krb5_initlog
 154 and then calls
 155 .Fn krb5_addlog_dest
 156 for each destination found.
 157 .Ss Destinations
 158 The defined destinations (as specified in
 159 .Pa krb5.conf )
 160 follows:
 161 .Bl -tag -width "xxx" -offset indent
 162 .It Li STDERR
 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
 173 .Li FILE:/device .
 174 .It Li CONSOLE
 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
 180 to
 181 .Xr syslog 3 ,
 182 and remove the leading
 183 .Li LOG_
 184 .No ( Li LOG_NOTICE
 185 becomes
 186 .Li NOTICE ) .
 187 The default values (as well as the values used for unrecognised
 188 values), are
 189 .Li ERR ,
 190 and
 191 .Li AUTH ,
 192 respectively.  See
 193 .Xr syslog 3
 194 for a list of priorities and facilities.
 195 .El
 196 .Pp
 197 Each destination may optionally be prepended with a range of logging
 198 levels, specified as
 199 .Li min-max/ .
 200 If the
 201 .Fa level
 202 parameter to
 203 .Fn krb5_log
 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.
 209 .Sh EXAMPLE
 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
 217 This will log all messages from the
 218 .Nm kdc
 219 program with level 0 to
 220 .Pa /var/log/kdc.log ,
 221 other messages will be logged to syslog with priority
 222 .Li LOG_INFO ,
 223 and facility
 224 .Li LOG_USER .
 225 All other programs will log all messages to their stderr.
 226 .Sh BUGS
 227 These functions use
 228 .Fn asprintf
 229 to format the message. If your operating system does not have a working
 230 .Fn asprintf ,
 231 a replacement will be used. At present this replacement does not handle
 232 some correct conversion specifications (like floating point numbers). Until
 233 this is fixed, the use of these conversions should be avoided.
 234 .Pp
 235 If logging is done to the syslog facility, these functions might not be
 236 thread-safe, depending on the implementation of
 237 .Fn openlog ,
 238 and
 239 .Fn syslog .
 240 .Sh SEE ALSO
 241 .Xr syslog 3 ,
 242 .Xr krb5.conf 5