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().

ticket: 7775 (new)
target_version: 1.12
tags: pullup

1 files changed, 25 insertions, 6 deletions

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index f2ba06f..8d7a650 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -4375,8 +4375,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.
@@ -4388,10 +4400,14 @@ krb5_cc_default_name(krb5_context context);
  * Set the default credential cache name.
  *
  * @param [in] context          Library context
- * @param [in] name             Default credential cache name
+ * @param [in] name             Default credential cache name or NULL
  *
- * 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
@@ -4404,11 +4420,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]  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