Try to explain krb5_ccache, krb5_principal and errors.

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@16180 ec53bebd-3082-4978-b11e-865c3cabbd6b

doc/programming.texi

@@ -16,14 +16,15 @@ introduction text (@pxref{What is Kerberos?}).
 @node Kerberos 5 API Overview, Walkthru a sample Kerberos 5 client, Programming with Kerberos, Programming with Kerberos
 @section Kerberos 5 API Overview
 
-Most functions are documenteded in manual pages.  This overview only
+All functions are documenteded in manual pages.  This section tries to
-tries to point to where to look for a specific function.
+give an overview of the major components used in Kerberos library, and
+point to where to look for a specific function.
 
 @subsection Kerberos context
 
 A kerberos context (@code{krb5_context}) holds all per thread state. All global variables that
 are context specific are stored in this struture, including default
-encryption types, credential-cache (ticket file), and default realms.
+encryption types, credential cache (for example, a ticket file), and default realms.
 
 See the manual pages for @manpage{krb5_context,3} and
 @manpage{krb5_init_context,3}.
@@ -42,18 +43,57 @@ replay cache, and checksum types.
 
 See the manual page for @manpage{krb5_auth_context,3}.
 
+@subsection Kerberos principal
+
+The Kerberos principal is the structure that identifies a user or
+service in Kerberos. The structure that holds the principal is the
+@code{krb5_principal}. There are function os extract the realm and
+elements of the principal, but Most applications have no reason to
+inspect the content of the structure.
+
+The are several ways to create a principal (with diffrent degree of
+portibility), and one way to free it.
+
+See manual page for @manpage{krb5_principal,3} for more information
+about the functions.
+
+@subsection Credential cache
+
+A credential cache holds the tickets for a user. A given user can have
+several credential caches, one for each realm where the user have the
+initial tickets (the first krbtgt).
+
+The credential cache data can be store several diffrent way, each for
+diffrent proposes. File credential (FILE) caches and processes based
+(KCM) caches are for permanent storage, while memory caches (MEMORY)
+are local caches to the local process.
+
+Caches are opened with @manpage{krb5_cc_resolve,3} or created with
+@manpage{krb5_cc_gen_unique,3}.
+
+If the cache needs to be opened again (using
+@manpage{krb5_cc_resolve,3}) @manpage{krb5_cc_close,3} will close the
+handle, but not the remove the cache. @manpage{krb5_cc_destroy,3} will
+zero out the cache, remove the cache so it can no longer be
+referenced.
+
+See also manual page for @manpage{krb5_ccache,3}
+
+@subsection Kerberos errors
+
+See also manual page for @manpage{krb5_get_error_string,3} and
+@manpage{krb5_get_err_text,3}.
+
 @subsection Keytab management
 
 A keytab is a storage for locally stored keys. Heimdal includes keytab
 support for Kerberos 5 keytabs, Kerberos 4 srvtab, AFS-KeyFile's,
 and for storing keys in memory.
 
+Keytabs are used for servers and long-running services.
+
 See also manual page for @manpage{krb5_keytab,3}
 
-@subsection Kerberos principal
-
-See also manual page for @manpage{krb5_principal,3}
-
 @subsection Kerberos crypto
 
 See also manual page for @manpage{krb5_crypto_init,3},