crypto/heimdal/lib/krb5/krb5_openlog.3

   1 .\" Copyright (c) 1997 Kungliga Tekniska Högskolan
   2 .\" $Id: krb5_openlog.3,v 1.7 2002/08/28 15:30:55 joda Exp $
   3 .Dd August 6, 1997
   4 .Dt KRB5_OPENLOG 3
   5 .Os HEIMDAL
   6 .Sh NAME
   7 .Nm krb5_initlog ,
   8 .Nm krb5_openlog ,
   9 .Nm krb5_closelog ,
  10 .Nm krb5_addlog_dest ,
  11 .Nm krb5_addlog_func ,
  12 .Nm krb5_log ,
  13 .Nm krb5_vlog ,
  14 .Nm krb5_log_msg ,
  15 .Nm krb5_vlog_msg
  16 .Nd Heimdal logging functions
  17 .Sh LIBRARY
  18 Kerberos 5 Library (libkrb5, -lkrb5)
  19 .Sh SYNOPSIS
  20 .Fd #include <krb5.h>
  21 .Ft "typedef void"
  22 .Fn "\*(lp*krb5_log_log_func_t\*(rp" "const char *time" "const char *message" "void *data"
  23 .Ft "typedef void"
  24 .Fn "\*(lp*krb5_log_close_func_t\*(rp" "void *data"
  25 .Ft krb5_error_code
  26 .Fn krb5_addlog_dest "krb5_context context" "krb5_log_facility *facility" "const char *destination"
  27 .Ft krb5_error_code
  28 .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"
  29 .Ft krb5_error_code
  30 .Fn krb5_closelog "krb5_context context" "krb5_log_facility *facility"
  31 .Ft krb5_error_code
  32 .Fn krb5_initlog "krb5_context context" "const char *program" "krb5_log_facility **facility"
  33 .Ft krb5_error_code
  34 .Fn krb5_log "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "..."
  35 .Ft krb5_error_code
  36 .Fn krb5_log_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "..."
  37 .Ft krb5_error_code
  38 .Fn krb5_openlog "krb5_context context" "const char *program" "krb5_log_facility **facility"
  39 .Ft krb5_error_code
  40 .Fn krb5_vlog "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "va_list arglist"
  41 .Ft krb5_error_code
  42 .Fn krb5_vlog_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "va_list arglist"
  43 .Sh DESCRIPTION
  44 These functions logs messages to one or more destinations.
  45 .Pp
  46 The
  47 .Fn krb5_openlog
  48 function creates a logging
  49 .Fa facility ,
  50 that is used to log messages. A facility consists of one or more
  51 destinations (which can be files or syslog or some other device). The
  52 .Fa program
  53 parameter should be the generic name of the program that is doing the
  54 logging. This name is used to lookup which destinations to use. This
  55 information is contained in the
  56 .Li logging
  57 section of the
  58 .Pa krb5.conf
  59 configuration file.  If no entry is found for
  60 .Fa program ,
  61 the entry for
  62 .Li default
  63 is used, or if that is missing too,
  64 .Li SYSLOG
  65 will be used as destination.
  66 .Pp
  67 To close a logging facility, use the
  68 .Fn krb5_closelog
  69 function.
  70 .Pp
  71 To log a message to a facility use one of the functions
  72 .Fn krb5_log ,
  73 .Fn krb5_log_msg ,
  74 .Fn krb5_vlog ,
  75 or
  76 .Fn krb5_vlog_msg .
  77 The functions ending in
  78 .Li _msg
  79 return in
  80 .Fa reply
  81 a pointer to the message that just got logged. This string is allocated,
  82 and should be freed with
  83 .Fn free .
  84 The
  85 .Fa format
  86 is a standard
  87 .Fn printf
  88 style format string (but see the BUGS section).
  89 .Pp
  90 If you want better control of where things gets logged, you can instead of using
  91 .Fn krb5_openlog
  92 call
  93 .Fn krb5_initlog ,
  94 which just initializes a facility, but doesn't define any actual logging
  95 destinations. You can then add destinations with the
  96 .Fn krb5_addlog_dest
  97 and
  98 .Fn krb5_addlog_func
  99 functions.  The first of these takes a string specifying a logging
 100 destination, and adds this to the facility. If you want to do some
 101 non-standard logging you can use the
 102 .Fn krb5_addlog_func
 103 function, which takes a function to use when logging.
 104 The
 105 .Fa log
 106 function is called for each message with
 107 .Fa time
 108 being a string specifying the current time, and
 109 .Fa message
 110 the message to log.
 111 .Fa close
 112 is called when the facility is closed. You can pass application specific data in the
 113 .Fa data
 114 parameter. The
 115 .Fa min
 116 and
 117 .Fa max
 118 parameter are the same as in a destination (defined below). To specify a
 119 max of infinity, pass -1.
 120 .Pp
 121 .Fn krb5_openlog
 122 calls
 123 .Fn krb5_initlog
 124 and then calls
 125 .Fn krb5_addlog_dest
 126 for each destination found.
 127 .Ss Destinations
 128 The defined destinations (as specified in
 129 .Pa krb5.conf )
 130 follows:
 131 .Bl -tag -width "xxx" -offset indent
 132 .It Li STDERR
 133 This logs to the program's stderr.
 134 .It Li FILE: Ns Pa /file
 135 .It Li FILE= Ns Pa /file
 136 Log to the specified file. The form using a colon appends to the file, the
 137 form with an equal truncates the file. The truncating form keeps the file
 138 open, while the appending form closes it after each log message (which
 139 makes it possible to rotate logs). The truncating form is mainly for
 140 compatibility with the MIT libkrb5.
 141 .It Li DEVICE= Ns Pa /device
 142 This logs to the specified device, at present this is the same as
 143 .Li FILE:/device .
 144 .It Li CONSOLE
 145 Log to the console, this is the same as
 146 .Li DEVICE=/dev/console .
 147 .It Li SYSLOG Ns Op :priority Ns Op :facility
 148 Send messages to the syslog system, using priority, and facility. To
 149 get the name for one of these, you take the name of the macro passed
 150 to
 151 .Xr syslog 3 ,
 152 and remove the leading
 153 .Li LOG_
 154 .No ( Li LOG_NOTICE
 155 becomes
 156 .Li NOTICE ) .
 157 The default values (as well as the values used for unrecognised
 158 values), are
 159 .Li ERR ,
 160 and
 161 .Li AUTH ,
 162 respectively.  See
 163 .Xr syslog 3
 164 for a list of priorities and facilities.
 165 .El
 166 .Pp
 167 Each destination may optionally be prepended with a range of logging
 168 levels, specified as
 169 .Li min-max/ .
 170 If the
 171 .Fa level
 172 parameter to
 173 .Fn krb5_log
 174 is within this range (inclusive) the message gets logged to this
 175 destination, otherwise not. Either of the min and max valued may be
 176 omitted, in this case min is assumed to be zero, and max is assumed to be
 177 infinity.  If you don't include a dash, both min and max gets set to the
 178 specified value. If no range is specified, all messages gets logged.
 179 .Sh EXAMPLE
 180 .Bd -literal -offset indent
 181 [logging]
 182         kdc = 0/FILE:/var/log/kdc.log
 183         kdc = 1-/SYSLOG:INFO:USER
 184         default = STDERR
 185 .Ed
 186 .Pp
 187 This will log all messages from the
 188 .Nm kdc
 189 program with level 0 to
 190 .Pa /var/log/kdc.log ,
 191 other messages will be logged to syslog with priority
 192 .Li LOG_INFO ,
 193 and facility
 194 .Li LOG_USER .
 195 All other programs will log all messages to their stderr.
 196 .Sh BUGS
 197 These functions use
 198 .Fn asprintf
 199 to format the message. If your operating system does not have a working
 200 .Fn asprintf ,
 201 a replacement will be used. At present this replacement does not handle
 202 some correct conversion specifications (like floating point numbers). Until
 203 this is fixed, the use of these conversions should be avoided.
 204 .Pp
 205 If logging is done to the syslog facility, these functions might not be
 206 thread-safe, depending on the implementation of
 207 .Fn openlog ,
 208 and
 209 .Fn syslog .
 210 .Sh SEE ALSO
 211 .Xr syslog 3 ,
 212 .Xr krb5.conf 5