diff options
Diffstat (limited to 'crypto/heimdal/lib/krb5/krb5_warn.3')
| -rw-r--r-- | crypto/heimdal/lib/krb5/krb5_warn.3 | 189 |
1 files changed, 177 insertions, 12 deletions
diff --git a/crypto/heimdal/lib/krb5/krb5_warn.3 b/crypto/heimdal/lib/krb5/krb5_warn.3 index 7ed4b31..5610cd8 100644 --- a/crypto/heimdal/lib/krb5/krb5_warn.3 +++ b/crypto/heimdal/lib/krb5/krb5_warn.3 @@ -1,32 +1,86 @@ -.\" Copyright (c) 1997 Kungliga Tekniska Högskolan -.\" $Id: krb5_warn.3,v 1.7 2003/04/16 19:31:49 lha Exp $ -.Dd August 8, 1997 +.\" Copyright (c) 1997, 2001 - 2006 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: krb5_warn.3 19085 2006-11-21 07:55:20Z lha $ +.\" +.Dd May 1, 2006 .Dt KRB5_WARN 3 .Os HEIMDAL .Sh NAME -.Nm krb5_warn , -.Nm krb5_warnx , -.Nm krb5_vwarn , -.Nm krb5_vwarnx , +.Nm krb5_abort , +.Nm krb5_abortx , +.Nm krb5_clear_error_string , .Nm krb5_err , .Nm krb5_errx , +.Nm krb5_free_error_string , +.Nm krb5_get_err_text , +.Nm krb5_get_error_message , +.Nm krb5_get_error_string , +.Nm krb5_have_error_string , +.Nm krb5_set_error_string , +.Nm krb5_set_warn_dest , +.Nm krb5_get_warn_dest , +.Nm krb5_vabort , +.Nm krb5_vabortx , .Nm krb5_verr , .Nm krb5_verrx , -.Nm krb5_set_warn_dest +.Nm krb5_vset_error_string , +.Nm krb5_vwarn , +.Nm krb5_vwarnx , +.Nm krb5_warn , +.Nm krb5_warnx .Nd Heimdal warning and error functions .Sh LIBRARY Kerberos 5 Library (libkrb5, -lkrb5) .Sh SYNOPSIS .In krb5.h .Ft krb5_error_code +.Fn krb5_abort "krb5_context context" "krb5_error_code code" "const char *fmt" "..." +.Ft krb5_error_code +.Fn krb5_abortx "krb5_context context" "krb5_error_code code" "const char *fmt" "..." +.Ft void +.Fn krb5_clear_error_string "krb5_context context" +.Ft krb5_error_code .Fn krb5_err "krb5_context context" "int eval" "krb5_error_code code" "const char *format" "..." .Ft krb5_error_code .Fn krb5_errx "krb5_context context" "int eval" "const char *format" "..." +.Ft void +.Fn krb5_free_error_string "krb5_context context" "char *str" .Ft krb5_error_code .Fn krb5_verr "krb5_context context" "int eval" "krb5_error_code code" "const char *format" "va_list ap" .Ft krb5_error_code .Fn krb5_verrx "krb5_context context" "int eval" "const char *format" "va_list ap" .Ft krb5_error_code +.Fn krb5_vset_error_string "krb5_context context" "const char *fmt" "va_list args" +.Ft krb5_error_code .Fn krb5_vwarn "krb5_context context" "krb5_error_code code" "const char *format" "va_list ap" .Ft krb5_error_code .Fn krb5_vwarnx "krb5_context context" "const char *format" "va_list ap" @@ -35,23 +89,43 @@ Kerberos 5 Library (libkrb5, -lkrb5) .Ft krb5_error_code .Fn krb5_warnx "krb5_context context" "const char *format" "..." .Ft krb5_error_code +.Fn krb5_set_error_string "krb5_context context" "const char *fmt" "..." +.Ft krb5_error_code .Fn krb5_set_warn_dest "krb5_context context" "krb5_log_facility *facility" .Ft "char *" +.Ft krb5_log_facility * +.Fo krb5_get_warn_dest +.Fa "krb5_context context" +.Fc .Fn krb5_get_err_text "krb5_context context" "krb5_error_code code" +.Ft char* +.Fn krb5_get_error_string "krb5_context context" +.Ft char* +.Fn krb5_get_error_message "krb5_context context, krb5_error_code code" +.Ft krb5_boolean +.Fn krb5_have_error_string "krb5_context context" +.Ft krb5_error_code +.Fn krb5_vabortx "krb5_context context" "const char *fmt" "va_list ap" +.Ft krb5_error_code +.Fn krb5_vabort "krb5_context context" "const char *fmt" "va_list ap" .Sh DESCRIPTION -These functions prints a warning message to some destination. +These functions print a warning message to some destination. .Fa format is a printf style format specifying the message to print. The forms not ending in an .Dq x -prints the error string associated with +print the error string associated with .Fa code along with the message. The .Dq err -functions exits with exit status +functions exit with exit status .Fa eval after printing the message. .Pp +Applications that want to get the error message to report it to a user +or store it in a log want to use +.Fn krb5_get_error_message . +.Pp The .Fn krb5_set_warn_func function sets the destination for warning messages to the specified @@ -60,9 +134,100 @@ Messages logged with the .Dq warn functions have a log level of 1, while the .Dq err -functions logs with level 0. +functions log with level 0. .Pp .Fn krb5_get_err_text fetches the human readable strings describing the error-code. +.Pp +.Fn krb5_abort +and +.Nm krb5_abortx +behaves like +.Nm krb5_err +and +.Nm krb5_errx +but instead of exiting using the +.Xr exit 3 +call, +.Xr abort 3 +is used. +.Pp +.Fn krb5_free_error_string +frees the error string +.Fa str +returned by +.Fn krb5_get_error_string . +.Pp +.Fn krb5_clear_error_string +clears the error string from the +.Fa context . +.Pp +.Fn krb5_set_error_string +and +.Fn krb5_vset_error_string +sets an verbose error string in +.Fa context . +.Pp +.Fn krb5_get_error_string +fetches the error string from +.Fa context . +The error message in the context is consumed and must be freed using +.Fn krb5_free_error_string +by the caller. +See also +.Fn krb5_get_error_message , +what is usually less verbose to use. +.Pp +.Fn krb5_have_error_string +returns +.Dv TRUE +if there is a verbose error message in the +.Fa context . +.Pp +.Fn krb5_get_error_message +fetches the error string from the context, or if there +is no customized error string in +.Fa context , +uses +.Fa code +to return a error string. +In either case, the error message in the context is consumed and must +be freed using +.Fn krb5_free_error_string +by the caller. +.Pp +.Fn krb5_set_warn_dest +and +.Fn krb5_get_warn_dest +sets and get the log context that is used by +.Fn krb5_warn +and friends. By using this the application can control where the +output should go. For example, this is imperative to inetd servers +where logging status and error message will end up on the output +stream to the client. +.Sh EXAMPLES +Below is a simple example how to report error messages from the +Kerberos library in an application. +.Bd -literal +#include <krb5.h> + +krb5_error_code +function (krb5_context context) +{ + krb5_error_code ret; + + ret = krb5_function (context, arg1, arg2); + if (ret) { + char *s = krb5_get_error_message(context, ret); + if (s == NULL) + errx(1, "kerberos error: %d (and out of memory)", ret); + application_logger("krb5_function failed: %s", s); + krb5_free_error_string(context, s); + return ret; + } + return 0; +} +.Ed .Sh SEE ALSO +.Xr krb5 3 , .Xr krb5_openlog 3 |
