krb5 commit [krb5-1.11]: Improve default ccache name API documentation

[Tom Yu]

https://github.com/krb5/krb5/commit/1467acb9392cb31c895586c186db5de19246328e
commit 1467acb9392cb31c895586c186db5de19246328e
Author: Tom Yu <tlyu at mit.edu>
Date:   Tue Nov 26 17:57:51 2013 -0500

    Improve default ccache name API documentation
    
    Document the lifetime and caching behavior of the
    krb5_cc_default_name() return value.  Document that
    krb5_cc_set_default_name() may be called with NULL to purge the cached
    value.  Correct a typo in the krb5_cc_default() summary and explicitly
    reference krb5_cc_default_name().
    
    (back ported from commit 3e5fe754b9f9742d1c9b1564633d4172277166db)
    
    ticket: 7781 (new)
    version_fixed: 1.11.5
    status: resolved

 src/include/krb5/krb5.hin |   29 ++++++++++++++++++++++++-----
 1 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index 1543172..36d1ef1 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -4356,8 +4356,20 @@ krb5_cc_dup(krb5_context context, krb5_ccache in, krb5_ccache *out);
  *
  * @param [in] context          Library context
  *
- * Try the environment variable @a KRB5CCNAME first then, if it is not set,
- * fall back on the default ccache name for the OS.
+ * Return a pointer to the default credential cache name for @a context, as
+ * determined by a prior call to krb5_cc_set_default_name(), by the KRB5CCNAME
+ * environment variable, by the default_ccache_name profile variable, or by the
+ * operating system or build-time default value.  The returned value must not
+ * be modified or freed by the caller.  The returned value becomes invalid when
+ * @a context is destroyed krb5_free_context() or if a subsequent call to
+ * krb5_cc_set_default_name() is made on @a context.
+ *
+ * The default credential cache name is cached in @a context between calls to
+ * this function, so if the value of KRB5CCNAME changes in the process
+ * environment after the first call to this function on, that change will not
+ * be reflected in later calls with the same context.  The caller can invoke
+ * krb5_cc_set_default_name() with a NULL value of @a name to clear the cached
+ * value and force the default name to be recomputed.
  *
  * @return
  * Name of default credential cache for the current user.
@@ -4371,8 +4383,12 @@ krb5_cc_default_name(krb5_context context);
  * @param [in,out]  context     Library context
  * @param [in]      name        Default credential cache name
  *
- * This function frees the old default credential cache name and then sets it
- * to @a name.
+ * Set the default credential cache name to @a name for future operations using
+ * @a context.  If @a name is NULL, clear any previous application-set default
+ * name and forget any cached value of the default name for @a context.
+ *
+ * Calls to this function invalidate the result of any previous calls to
+ * krb5_cc_default_name() using @a context.
  *
  * @retval
  *  0  Success
@@ -4385,11 +4401,14 @@ krb5_error_code KRB5_CALLCONV
 krb5_cc_set_default_name(krb5_context context, const char *name);
 
 /**
- * Resolve the default crendentials cache name.
+ * Resolve the default credential cache name.
  *
  * @param [in,out] context      Library context
  * @param [out]    ccache       Pointer to credential cache name
  *
+ * Create a handle to the default credential cache as given by
+ * krb5_cc_default_name().
+ *
  * @retval
  * 0  Success
  * @retval