crypto/dist/heimdal/lib/krb5/krb5_warn.3

   1 .\" Copyright (c) 1997, 2001 - 2006 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_warn.3 19085 2006-11-21 07:55:20Z lha $
  33 .\" $NetBSD$
  34 .\"
  35 .Dd May  1, 2006
  36 .Dt KRB5_WARN 3
  37 .Os
  38 .Sh NAME
  39 .Nm krb5_abort ,
  40 .Nm krb5_abortx ,
  41 .Nm krb5_clear_error_string ,
  42 .Nm krb5_err ,
  43 .Nm krb5_errx ,
  44 .Nm krb5_free_error_string ,
  45 .Nm krb5_get_err_text ,
  46 .Nm krb5_get_error_message ,
  47 .Nm krb5_get_error_string ,
  48 .Nm krb5_have_error_string ,
  49 .Nm krb5_set_error_string ,
  50 .Nm krb5_set_warn_dest ,
  51 .Nm krb5_get_warn_dest ,
  52 .Nm krb5_vabort ,
  53 .Nm krb5_vabortx ,
  54 .Nm krb5_verr ,
  55 .Nm krb5_verrx ,
  56 .Nm krb5_vset_error_string ,
  57 .Nm krb5_vwarn ,
  58 .Nm krb5_vwarnx ,
  59 .Nm krb5_warn ,
  60 .Nm krb5_warnx
  61 .Nd Heimdal warning and error functions
  62 .Sh LIBRARY
  63 Kerberos 5 Library (libkrb5, -lkrb5)
  64 .Sh SYNOPSIS
  65 .In krb5/krb5.h
  66 .Ft krb5_error_code
  67 .Fn krb5_abort "krb5_context context" "krb5_error_code code" "const char *fmt"  "..."
  68 .Ft krb5_error_code
  69 .Fn krb5_abortx "krb5_context context" "krb5_error_code code" "const char *fmt"  "..."
  70 .Ft void
  71 .Fn krb5_clear_error_string "krb5_context context"
  72 .Ft krb5_error_code
  73 .Fn krb5_err "krb5_context context" "int eval" "krb5_error_code code" "const char *format" "..."
  74 .Ft krb5_error_code
  75 .Fn krb5_errx "krb5_context context" "int eval" "const char *format" "..."
  76 .Ft void
  77 .Fn krb5_free_error_string "krb5_context context" "char *str"
  78 .Ft krb5_error_code
  79 .Fn krb5_verr "krb5_context context" "int eval" "krb5_error_code code" "const char *format" "va_list ap"
  80 .Ft krb5_error_code
  81 .Fn krb5_verrx "krb5_context context" "int eval" "const char *format" "va_list ap"
  82 .Ft krb5_error_code
  83 .Fn krb5_vset_error_string "krb5_context context" "const char *fmt" "va_list args"
  84 .Ft krb5_error_code
  85 .Fn krb5_vwarn "krb5_context context" "krb5_error_code code" "const char *format" "va_list ap"
  86 .Ft krb5_error_code
  87 .Fn krb5_vwarnx "krb5_context context" "const char *format" "va_list ap"
  88 .Ft krb5_error_code
  89 .Fn krb5_warn "krb5_context context" "krb5_error_code code" "const char *format" "..."
  90 .Ft krb5_error_code
  91 .Fn krb5_warnx "krb5_context context" "const char *format" "..."
  92 .Ft krb5_error_code
  93 .Fn krb5_set_error_string "krb5_context context" "const char *fmt" "..."
  94 .Ft krb5_error_code
  95 .Fn krb5_set_warn_dest "krb5_context context" "krb5_log_facility *facility"
  96 .Ft "char *"
  97 .Ft krb5_log_facility *
  98 .Fo krb5_get_warn_dest
  99 .Fa "krb5_context context"
 100 .Fc
 101 .Fn krb5_get_err_text "krb5_context context" "krb5_error_code code"
 102 .Ft char*
 103 .Fn krb5_get_error_string "krb5_context context"
 104 .Ft char*
 105 .Fn krb5_get_error_message "krb5_context context, krb5_error_code code"
 106 .Ft krb5_boolean
 107 .Fn krb5_have_error_string "krb5_context context"
 108 .Ft krb5_error_code
 109 .Fn krb5_vabortx "krb5_context context" "const char *fmt" "va_list ap"
 110 .Ft krb5_error_code
 111 .Fn krb5_vabort "krb5_context context" "const char *fmt" "va_list ap"
 112 .Sh DESCRIPTION
 113 These functions print a warning message to some destination.
 114 .Fa format
 115 is a printf style format specifying the message to print. The forms not ending in an
 116 .Dq x
 117 print the error string associated with
 118 .Fa code
 119 along with the message.
 120 The
 121 .Dq err
 122 functions exit with exit status
 123 .Fa eval
 124 after printing the message.
 125 .Pp
 126 Applications that want to get the error message to report it to a user
 127 or store it in a log want to use
 128 .Fn krb5_get_error_message .
 129 .Pp
 130 The
 131 .Fn krb5_set_warn_func
 132 function sets the destination for warning messages to the specified
 133 .Fa facility .
 134 Messages logged with the
 135 .Dq warn
 136 functions have a log level of 1, while the
 137 .Dq err
 138 functions log with level 0.
 139 .Pp
 140 .Fn krb5_get_err_text
 141 fetches the human readable strings describing the error-code.
 142 .Pp
 143 .Fn krb5_abort
 144 and
 145 .Nm krb5_abortx
 146 behaves like
 147 .Nm krb5_err
 148 and
 149 .Nm krb5_errx
 150 but instead of exiting using the
 151 .Xr exit 3
 152 call,
 153 .Xr abort 3
 154 is used.
 155 .Pp
 156 .Fn krb5_free_error_string
 157 frees the error string
 158 .Fa str
 159 returned by
 160 .Fn krb5_get_error_string .
 161 .Pp
 162 .Fn krb5_clear_error_string
 163 clears the error string from the
 164 .Fa context .
 165 .Pp
 166 .Fn krb5_set_error_string
 167 and
 168 .Fn krb5_vset_error_string
 169 sets an verbose error string in
 170 .Fa context .
 171 .Pp
 172 .Fn krb5_get_error_string
 173 fetches the error string from
 174 .Fa context .
 175 The error message in the context is consumed and must be freed using
 176 .Fn krb5_free_error_string
 177 by the caller.
 178 See also
 179 .Fn krb5_get_error_message ,
 180 what is usually less verbose to use.
 181 .Pp
 182 .Fn krb5_have_error_string
 183 returns
 184 .Dv TRUE
 185 if there is a verbose error message in the
 186 .Fa context .
 187 .Pp
 188 .Fn krb5_get_error_message
 189 fetches the error string from the context, or if there
 190 is no customized error string in
 191 .Fa context ,
 192 uses
 193 .Fa code
 194 to return a error string.
 195 In either case, the error message in the context is consumed and must
 196 be freed using
 197 .Fn krb5_free_error_string
 198 by the caller.
 199 .Pp
 200 .Fn krb5_set_warn_dest
 201 and
 202 .Fn krb5_get_warn_dest
 203 sets and get the log context that is used by
 204 .Fn krb5_warn
 205 and friends.  By using this the application can control where the
 206 output should go.  For example, this is imperative to inetd servers
 207 where logging status and error message will end up on the output
 208 stream to the client.
 209 .Sh EXAMPLES
 210 Below is a simple example how to report error messages from the
 211 Kerberos library in an application.
 212 .Bd -literal
 213 #include <krb5/krb5.h>
 214
 215 krb5_error_code
 216 function (krb5_context context)
 217 {
 218     krb5_error_code ret;
 219
 220     ret = krb5_function (context, arg1, arg2);
 221     if (ret) {
 222         char *s = krb5_get_error_message(context, ret);
 223         if (s == NULL)
 224              errx(1, "kerberos error: %d (and out of memory)", ret);
 225         application_logger("krb5_function failed: %s", s);
 226         krb5_free_error_string(context, s);
 227         return ret;
 228     }
 229     return 0;
 230 }
 231 .Ed
 232 .Sh SEE ALSO
 233 .Xr krb5 3 ,
 234 .Xr krb5_openlog 3