krb5 commit [krb5-1.12]: Improve default ccache name API documentation
Tom Yu
tlyu at MIT.EDU
Mon Nov 25 16:26:17 EST 2013
https://github.com/krb5/krb5/commit/dc92daab85566a4e05bddbf943bac164df4b774f
commit dc92daab85566a4e05bddbf943bac164df4b774f
Author: Greg Hudson <ghudson at mit.edu>
Date: Thu Nov 21 17:30:54 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().
(cherry picked from commit 3e5fe754b9f9742d1c9b1564633d4172277166db)
ticket: 7775
version_fixed: 1.12
status: resolved
src/include/krb5/krb5.hin | 31 +++++++++++++++++++++++++------
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
More information about the cvs-krb5
mailing list