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