crypto/external/bsd/heimdal/dist/lib/krb5/krb5_openlog.3

   1 .\"     $NetBSD: krb5_openlog.3,v 1.1.1.2 2011/04/14 14:09:23 elric Exp $
   2 .\"
   3 .\" Copyright (c) 1997, 1999, 2001 - 2002 Kungliga Tekniska Högskolan
   4 .\" (Royal Institute of Technology, Stockholm, Sweden).
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" 3. Neither the name of the Institute nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\" Id
  35 .Dd August 6, 1997
  36 .Dt KRB5_OPENLOG 3
  37 .Os
  38 .Sh NAME
  39 .Nm krb5_initlog ,
  40 .Nm krb5_openlog ,
  41 .Nm krb5_closelog ,
  42 .Nm krb5_addlog_dest ,
  43 .Nm krb5_addlog_func ,
  44 .Nm krb5_log ,
  45 .Nm krb5_vlog ,
  46 .Nm krb5_log_msg ,
  47 .Nm krb5_vlog_msg
  48 .Nd Heimdal logging functions
  49 .Sh LIBRARY
  50 Kerberos 5 Library (libkrb5, -lkrb5)
  51 .Sh SYNOPSIS
  52 .In krb5/krb5.h
  53 .Ft "typedef void"
  54 .Fn "\*(lp*krb5_log_log_func_t\*(rp" "const char *time" "const char *message" "void *data"
  55 .Ft "typedef void"
  56 .Fn "\*(lp*krb5_log_close_func_t\*(rp" "void *data"
  57 .Ft krb5_error_code
  58 .Fn krb5_addlog_dest "krb5_context context" "krb5_log_facility *facility" "const char *destination"
  59 .Ft krb5_error_code
  60 .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"
  61 .Ft krb5_error_code
  62 .Fn krb5_closelog "krb5_context context" "krb5_log_facility *facility"
  63 .Ft krb5_error_code
  64 .Fn krb5_initlog "krb5_context context" "const char *program" "krb5_log_facility **facility"
  65 .Ft krb5_error_code
  66 .Fn krb5_log "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "..."
  67 .Ft krb5_error_code
  68 .Fn krb5_log_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "..."
  69 .Ft krb5_error_code
  70 .Fn krb5_openlog "krb5_context context" "const char *program" "krb5_log_facility **facility"
  71 .Ft krb5_error_code
  72 .Fn krb5_vlog "krb5_context context" "krb5_log_facility *facility" "int level" "const char *format" "va_list arglist"
  73 .Ft krb5_error_code
  74 .Fn krb5_vlog_msg "krb5_context context" "krb5_log_facility *facility" "char **reply" "int level" "const char *format" "va_list arglist"
  75 .Sh DESCRIPTION
  76 These functions logs messages to one or more destinations.
  77 .Pp
  78 The
  79 .Fn krb5_openlog
  80 function creates a logging
  81 .Fa facility ,
  82 that is used to log messages. A facility consists of one or more
  83 destinations (which can be files or syslog or some other device). The
  84 .Fa program
  85 parameter should be the generic name of the program that is doing the
  86 logging. This name is used to lookup which destinations to use. This
  87 information is contained in the
  88 .Li logging
  89 section of the
  90 .Pa krb5.conf
  91 configuration file.  If no entry is found for
  92 .Fa program ,
  93 the entry for
  94 .Li default
  95 is used, or if that is missing too,
  96 .Li SYSLOG
  97 will be used as destination.
  98 .Pp
  99 To close a logging facility, use the
 100 .Fn krb5_closelog
 101 function.
 102 .Pp
 103 To log a message to a facility use one of the functions
 104 .Fn krb5_log ,
 105 .Fn krb5_log_msg ,
 106 .Fn krb5_vlog ,
 107 or
 108 .Fn krb5_vlog_msg .
 109 The functions ending in
 110 .Li _msg
 111 return in
 112 .Fa reply
 113 a pointer to the message that just got logged. This string is allocated,
 114 and should be freed with
 115 .Fn free .
 116 The
 117 .Fa format
 118 is a standard
 119 .Fn printf
 120 style format string (but see the BUGS section).
 121 .Pp
 122 If you want better control of where things gets logged, you can instead of using
 123 .Fn krb5_openlog
 124 call
 125 .Fn krb5_initlog ,
 126 which just initializes a facility, but doesn't define any actual logging
 127 destinations. You can then add destinations with the
 128 .Fn krb5_addlog_dest
 129 and
 130 .Fn krb5_addlog_func
 131 functions.  The first of these takes a string specifying a logging
 132 destination, and adds this to the facility. If you want to do some
 133 non-standard logging you can use the
 134 .Fn krb5_addlog_func
 135 function, which takes a function to use when logging.
 136 The
 137 .Fa log
 138 function is called for each message with
 139 .Fa time
 140 being a string specifying the current time, and
 141 .Fa message
 142 the message to log.
 143 .Fa close
 144 is called when the facility is closed. You can pass application specific data in the
 145 .Fa data
 146 parameter. The
 147 .Fa min
 148 and
 149 .Fa max
 150 parameter are the same as in a destination (defined below). To specify a
 151 max of infinity, pass -1.
 152 .Pp
 153 .Fn krb5_openlog
 154 calls
 155 .Fn krb5_initlog
 156 and then calls
 157 .Fn krb5_addlog_dest
 158 for each destination found.
 159 .Ss Destinations
 160 The defined destinations (as specified in
 161 .Pa krb5.conf )
 162 follows:
 163 .Bl -tag -width "xxx" -offset indent
 164 .It Li STDERR
 165 This logs to the program's stderr.
 166 .It Li FILE: Ns Pa /file
 167 .It Li FILE= Ns Pa /file
 168 Log to the specified file. The form using a colon appends to the file, the
 169 form with an equal truncates the file. The truncating form keeps the file
 170 open, while the appending form closes it after each log message (which
 171 makes it possible to rotate logs). The truncating form is mainly for
 172 compatibility with the MIT libkrb5.
 173 .It Li DEVICE= Ns Pa /device
 174 This logs to the specified device, at present this is the same as
 175 .Li FILE:/device .
 176 .It Li CONSOLE
 177 Log to the console, this is the same as
 178 .Li DEVICE=/dev/console .
 179 .It Li SYSLOG Ns Op :priority Ns Op :facility
 180 Send messages to the syslog system, using priority, and facility. To
 181 get the name for one of these, you take the name of the macro passed
 182 to
 183 .Xr syslog 3 ,
 184 and remove the leading
 185 .Li LOG_
 186 .No ( Li LOG_NOTICE
 187 becomes
 188 .Li NOTICE ) .
 189 The default values (as well as the values used for unrecognised
 190 values), are
 191 .Li ERR ,
 192 and
 193 .Li AUTH ,
 194 respectively.  See
 195 .Xr syslog 3
 196 for a list of priorities and facilities.
 197 .El
 198 .Pp
 199 Each destination may optionally be prepended with a range of logging
 200 levels, specified as
 201 .Li min-max/ .
 202 If the
 203 .Fa level
 204 parameter to
 205 .Fn krb5_log
 206 is within this range (inclusive) the message gets logged to this
 207 destination, otherwise not. Either of the min and max valued may be
 208 omitted, in this case min is assumed to be zero, and max is assumed to be
 209 infinity.  If you don't include a dash, both min and max gets set to the
 210 specified value. If no range is specified, all messages gets logged.
 211 .Sh EXAMPLES
 212 .Bd -literal -offset indent
 213 [logging]
 214         kdc = 0/FILE:/var/log/kdc.log
 215         kdc = 1-/SYSLOG:INFO:USER
 216         default = STDERR
 217 .Ed
 218 .Pp
 219 This will log all messages from the
 220 .Nm kdc
 221 program with level 0 to
 222 .Pa /var/log/kdc.log ,
 223 other messages will be logged to syslog with priority
 224 .Li LOG_INFO ,
 225 and facility
 226 .Li LOG_USER .
 227 All other programs will log all messages to their stderr.
 228 .Sh SEE ALSO
 229 .Xr syslog 3 ,
 230 .Xr krb5.conf 5
 231 .Sh BUGS
 232 These functions use
 233 .Fn asprintf
 234 to format the message. If your operating system does not have a working
 235 .Fn asprintf ,
 236 a replacement will be used. At present this replacement does not handle
 237 some correct conversion specifications (like floating point numbers). Until
 238 this is fixed, the use of these conversions should be avoided.
 239 .Pp
 240 If logging is done to the syslog facility, these functions might not be
 241 thread-safe, depending on the implementation of
 242 .Fn openlog ,
 243 and
 244 .Fn syslog .