From f51cf94a6247ae175774b3e2cb981a1e9f794dd7 Mon Sep 17 00:00:00 2001 From: Russell Bryant Date: Wed, 29 Nov 2006 17:59:13 +0000 Subject: - Fix a few spelling mistakes. - Add some more documentation for the ast_dynamic_str_............() function to document the behavior of the function in the case of a partial write. Also, document the return value and note that the function should never need to be called directly. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@48110 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/threadstorage.h | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/include/asterisk/threadstorage.h b/include/asterisk/threadstorage.h index 25bc24b71..f03e264b2 100644 --- a/include/asterisk/threadstorage.h +++ b/include/asterisk/threadstorage.h @@ -205,7 +205,7 @@ struct ast_dynamic_str * attribute_malloc ast_dynamic_str_create(size_t init_len * current length may be bigger if previous operations in this thread have * caused it to increase. * - * \return This function will return the thread locally storaged dynamic string + * \return This function will return the thread locally stored dynamic string * associated with the thread storage management variable passed as the * first argument. * The result will be NULL in the case of a memory allocation error. @@ -261,7 +261,7 @@ enum { * \arg buf This is the address of a pointer to an ast_dynamic_str which should * have been retrieved using ast_dynamic_str_thread_get. It will need to * be updated in the case that the buffer has to be reallocated to - * accomodate a longer string than what it currently has space for. + * accommodate a longer string than what it currently has space for. * \arg max_len This is the maximum length to allow the string buffer to grow * to. If this is set to 0, then there is no maximum length. * \arg ts This is a pointer to the thread storage structure declared by using @@ -332,6 +332,21 @@ enum { * ast_dynamic_str_thread_set_va except for an addition argument, append. * If append is non-zero, this will append to the current string instead of * writing over it. + * + * In the case that this function is called and the buffer was not large enough + * to hold the result, the partial write will be truncated, and the result + * AST_DYNSTR_BUILD_RETRY will be returned to indicate that the buffer size + * was increased, and the function should be called a second time. + * + * A return of AST_DYNSTR_BUILD_FAILED indicates a memory allocation error. + * + * A return value greater than or equal to zero indicates the number of + * characters that have been written, not including the terminating '\0'. + * In the append case, this only includes the number of characters appended. + * + * \note This function should never need to be called directly. It should + * through calling one of the other functions or macros defined in this + * file. */ int ast_dynamic_str_thread_build_va(struct ast_dynamic_str **buf, size_t max_len, struct ast_threadstorage *ts, int append, const char *fmt, va_list ap); @@ -419,7 +434,7 @@ int __attribute__ ((format (printf, 4, 5))) ast_dynamic_str_thread_append( * * \arg buf This is the address of a pointer to an ast_dynamic_str. It will * need to be updated in the case that the buffer has to be reallocated to - * accomodate a longer string than what it currently has space for. + * accommodate a longer string than what it currently has space for. * \arg max_len This is the maximum length to allow the string buffer to grow * to. If this is set to 0, then there is no maximum length. * @@ -443,7 +458,7 @@ int __attribute__ ((format (printf, 3, 4))) ast_dynamic_str_set( ) /*! - * \brief Append to a dynatic string + * \brief Append to a dynamic string * * The arguments, return values, and usage of this function are the same as * ast_dynamic_str_set(). However, this function appends to the string instead -- cgit v1.2.3