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