diff options
author | Greg Hudson <ghudson@mit.edu> | 2013-11-21 17:30:54 -0500 |
---|---|---|
committer | Greg Hudson <ghudson@mit.edu> | 2013-11-22 11:59:04 -0500 |
commit | 3e5fe754b9f9742d1c9b1564633d4172277166db (patch) | |
tree | e6be781682d94b11984a6715336a3cc7705c22e8 /src/include | |
parent | 39bac22ed7f5ff583e92d082b34f0c5a2a3cad4c (diff) | |
download | krb5-3e5fe754b9f9742d1c9b1564633d4172277166db.zip krb5-3e5fe754b9f9742d1c9b1564633d4172277166db.tar.gz krb5-3e5fe754b9f9742d1c9b1564633d4172277166db.tar.bz2 |
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
Diffstat (limited to 'src/include')
-rw-r--r-- | 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 |