diff options
author | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2006-11-29 17:59:13 +0000 |
---|---|---|
committer | russell <russell@f38db490-d61c-443f-a65b-d21fe96a405b> | 2006-11-29 17:59:13 +0000 |
commit | 2942427c7ec3988b07ef078805c323928b7c2c72 (patch) | |
tree | 574b606958c052eec61378e61b36db633f6998b7 /include | |
parent | 700f9d585c82e839e2c9044a4ef1b89edeecb8e2 (diff) |
- 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: http://svn.digium.com/svn/asterisk/trunk@48110 f38db490-d61c-443f-a65b-d21fe96a405b
Diffstat (limited to 'include')
-rw-r--r-- | include/asterisk/threadstorage.h | 23 |
1 files 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 |