krb5_clear_error_string(3)

NAME

     krb5_abort, krb5_abortx, krb5_clear_error_string, krb5_err, krb5_errx,
     krb5_free_error_string, krb5_get_err_text, krb5_get_error_message,
     krb5_get_error_string, krb5_have_error_string, krb5_set_error_string,
     krb5_set_warn_dest, krb5_get_warn_dest, krb5_vabort, krb5_vabortx,
     krb5_verr, krb5_verrx, krb5_vset_error_string, krb5_vwarn, krb5_vwarnx,
     krb5_warn, krb5_warnx -- Heimdal warning and error functions

LIBRARY

     Kerberos 5 Library (libkrb5, -lkrb5)

SYNOPSIS

     #include <krb5.h>

     krb5_error_code
     krb5_abort(krb5_context context, krb5_error_code code, const char *fmt,
         ...);

     krb5_error_code
     krb5_abortx(krb5_context context, krb5_error_code code, const char *fmt,
         ...);

     void
     krb5_clear_error_string(krb5_context context);

     krb5_error_code
     krb5_err(krb5_context context, int eval, krb5_error_code code,
         const char *format, ...);

     krb5_error_code
     krb5_errx(krb5_context context, int eval, const char *format, ...);

     void
     krb5_free_error_string(krb5_context context, char *str);

     krb5_error_code
     krb5_verr(krb5_context context, int eval, krb5_error_code code,
         const char *format, va_list ap);

     krb5_error_code
     krb5_verrx(krb5_context context, int eval, const char *format,
         va_list ap);

     krb5_error_code
     krb5_vset_error_string(krb5_context context, const char *fmt,
         va_list args);

     krb5_error_code
     krb5_vwarn(krb5_context context, krb5_error_code code,
         const char *format, va_list ap);

     krb5_error_code
     krb5_vwarnx(krb5_context context, const char *format, va_list ap);

     krb5_error_code
     krb5_warn(krb5_context context, krb5_error_code code, const char *format,
         ...);

     krb5_error_code
     krb5_warnx(krb5_context context, const char *format, ...);

     krb5_error_code
     krb5_set_error_string(krb5_context context, const char *fmt, ...);

     krb5_error_code
     krb5_set_warn_dest(krb5_context context, krb5_log_facility *facility);

     char *

     krb5_log_facility *
     krb5_get_warn_dest(krb5_context context);

     krb5_get_err_text(krb5_context context, krb5_error_code code);

     char*
     krb5_get_error_string(krb5_context context);

     char*
     krb5_get_error_message(krb5_context context, krb5_error_code code);

     krb5_boolean
     krb5_have_error_string(krb5_context context);

     krb5_error_code
     krb5_vabortx(krb5_context context, const char *fmt, va_list ap);

     krb5_error_code
     krb5_vabort(krb5_context context, const char *fmt, va_list ap);

DESCRIPTION

     These functions print a warning message to some destination.  format is a
     printf style format specifying the message to print. The forms not ending
     in an ``x'' print the error string associated with code along with the
     message.  The ``err'' functions exit with exit status eval after printing
     the message.

     Applications that want to get the error message to report it to a user or
     store it in a log want to use krb5_get_error_message().

     The krb5_set_warn_func() function sets the destination for warning mes-
     sages to the specified facility.  Messages logged with the ``warn'' func-
     tions have a log level of 1, while the ``err'' functions log with level
     0.

     krb5_get_err_text() fetches the human readable strings describing the
     error-code.

     krb5_abort() and krb5_abortx behaves like krb5_err and krb5_errx but
     instead of exiting using the exit(3) call, abort(3) is used.

     krb5_free_error_string() frees the error string str returned by
     krb5_get_error_string().

     krb5_clear_error_string() clears the error string from the context.

     krb5_set_error_string() and krb5_vset_error_string() sets an verbose
     error string in context.

     krb5_get_error_string() fetches the error string from context.  The error
     message in the context is consumed and must be freed using
     krb5_free_error_string() by the caller.  See also
     krb5_get_error_message(), what is usually less verbose to use.

     krb5_have_error_string() returns TRUE if there is a verbose error message
     in the context.

     krb5_get_error_message() fetches the error string from the context, or if
     there is no customized error string in context, uses code to return a
     error string.  In either case, the error message in the context is con-
     sumed and must be freed using krb5_free_error_string() by the caller.

     krb5_set_warn_dest() and krb5_get_warn_dest() sets and get the log con-
     text that is used by krb5_warn() and friends.  By using this the applica-
     tion can control where the output should go.  For example, this is imper-
     ative to inetd servers where logging status and error message will end up
     on the output stream to the client.

EXAMPLES

     Below is a simple example how to report error messages from the Kerberos
     library in an application.

     #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;
     }

SEE ALSO

     krb5(3), krb5_openlog(3)

HEIMDAL                           May 1, 2006                          HEIMDAL