crypto/heimdal/lib/krb5/krb5_openlog.3

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