<!-- #bbinclude "header.template" #PAGETITLE#="Kerberos Errors API" #BASEHREF#="" --> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <HTML> <HEAD> <BASE HREF="http://web.mit.edu/macdev/KfM/KerberosFramework/KerberosErrors/Documentation/api.html"> <META NAME="keywords" CONTENT="#KEYWORDS#"> <META NAME="description" CONTENT="#DESCRIPTION#"> <TITLE>Kerberos Errors API</TITLE> <STYLE TYPE="text/css"> @import url(../../../Common/Documentation/templates/site.css); </STYLE> </HEAD> <BODY> <DIV ID="menu"> <IMG SRC="../../../Common/Documentation/graphics/Kerberos.jpg" ALT="Kerberos for Macintosh Logo"> <HR> <P><A HREF="../../../Common/Documentation/index.html">Home</A></P> <P><A HREF="http://web.mit.edu/kerberos/">MIT Kerberos</A></P> <P><A HREF="http://web.mit.edu/ist/">MIT IS&T</A></P> <HR> <P><A HREF="../../../Common/Documentation/news.html">News</A></P> <P><A HREF="../../../Common/Documentation/documentation.html">Documentation</A></P> <P><A HREF="../../../Common/Documentation/developer.html">Developer Resources</A></P> <P><A HREF="../../../Common/Documentation/license.html">License</A></P> <HR> <P><A HREF="../../../Common/Documentation/download.html">Download</A></P> <P><A HREF="../../../Common/Documentation/support.html">Support</A></P> <P><A HREF="../../../Common/Documentation/contact.html">Contact Us</A></P> </DIV> <DIV ID="body"> <!-- end bbinclude --> <!-- #bbinclude "icon.template" #ICON#="../../../Common/Documentation/graphics/ThreeHeadsAndKey.gif" #TEXT#="<H2>Kerberos Errors API</H2>" --> <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0> <TR VALIGN=middle> <TD ALIGN=center> <IMG CLASS=icon SRC="../../../Common/Documentation/graphics/ThreeHeadsAndKey.gif" ALT="An icon image (description text to the right)" WIDTH=32 HEIGHT=32> </TD> <TD ALIGN=left> <H2>Kerberos Errors API</H2> </TD> </TR> </TABLE> <!-- end bbinclude --> <HR> <H2>Types:</H2> <BLOCKQUOTE> <PRE>typedef long errcode_t;</PRE> <P> The error code integer type. The value of each error code is determined by <CODE>compile_et</CODE> based on the four character name of the API the error codes belong to.</P> <HR> <PRE>struct error_table { const char * const * const messages; int32_t base; int32_t count; };</PRE> <P> The error table type. This is the fallback error tables used if the bundle strings are not available. You can add and remove these from Kerberos Error's search path using <CODE>add_error_table()</CODE> and <CODE>remove_error_table()</CODE></P> <HR> <PRE>typedef void (*com_err_handler_t) (const char *whoami, errcode_t code, const char *format, va_list args);</PRE> <P> The com_err display hook callback. Your application should define this if it wants to use <CODE>com_err()</CODE> or <CODE>com_err_va()</CODE> to display error messages and does not want them <CODE>printf</CODE>ed to <CODE>stderr</CODE>.</P> <HR> </BLOCKQUOTE> <H2>Functions:</H2> <BLOCKQUOTE> <PRE><CODE>char const *error_message (errcode_t code);</CODE></PRE> <P><CODE>error_message()</CODE> converts an error code to a UTF8 string so it can be reported to the user.<P> <HR> <PRE><CODE>com_err_handler_t set_com_err_hook(com_err_handler_t handler); com_err_handler_t reset_com_err_hook(void);</CODE></PRE> <P> <CODE>set_com_err_hook()</CODE> sets the com_err display hook function to <CODE>handler</CODE>. <CODE>reset_com_err_hook()</CODE> sets it back to the default function, which <CODE>fprintf</CODE>'s to stderr.</P> <HR> <PRE>void com_err (const char *progname, errcode_t code, const char *format, ...); void com_err_va (const char *progname, errcode_t code, const char *format, va_list args);</PRE> <P> <CODE>com_err()</CODE> and <CODE>com_err_va()</CODE> print an error message using the com_err hook function. The default hook function prints a string of the form "<CODE>progname</CODE>: <CODE>error_message (code></CODE> <CODE>format</CODE>" to <CODE>stderr</CODE>. You can set your own hook function with <CODE>set_com_err_hook()</CODE>. </P> <HR> <PRE>errcode_t add_error_table (const struct error_table *et); errcode_t remove_error_table (const struct error_table *et);</PRE> <P><CODE>add_error_table()</CODE> and <CODE>remove_error_table()</CODE> add and remove com_err C string error tables to the list of fallback error tables. These tables are searched after Kerberos Errors has failed to find a bundle string for the error code. You will only need these functions if your code does not have a bundle or if you do not install the strings list generated by the Kerberos Errors <CODE>compile_et</CODE>. <P> </BLOCKQUOTE> <!-- #bbinclude "footer.template" --> </DIV> <DIV ID="footer"> <P> Copyright 2005 Massachusetts Institute of Technology.<BR> Last updated on $Date: 2005/05/04 18:24:10 $ <BR> Last modified by $Author: lxs $ </P> </DIV> <!-- Begin MIT-use only web reporting counter --> <IMG SRC="http://counter.mit.edu/tally" WIDTH=1 HEIGHT=1 ALT=""> <!-- End MIT-use only web reporting counter --> </BODY></HTML> <!-- end bbinclude -->