[svn-commits] russell: trunk r48110 -
/trunk/include/asterisk/threadstorage.h
svn-commits at lists.digium.com
svn-commits at lists.digium.com
Wed Nov 29 10:59:15 MST 2006
Author: russell
Date: Wed Nov 29 11:59:13 2006
New Revision: 48110
URL: http://svn.digium.com/view/asterisk?view=rev&rev=48110
Log:
- 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.
Modified:
trunk/include/asterisk/threadstorage.h
Modified: trunk/include/asterisk/threadstorage.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/threadstorage.h?view=diff&rev=48110&r1=48109&r2=48110
==============================================================================
--- trunk/include/asterisk/threadstorage.h (original)
+++ trunk/include/asterisk/threadstorage.h Wed Nov 29 11:59:13 2006
@@ -205,7 +205,7 @@
* 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.
@@ -257,6 +257,102 @@
/*!
* \brief Set a thread locally stored dynamic string from a va_list
+ *
+ * \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
+ * 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
+ * the AST_THREADSTORAGE macro. If declared with
+ * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be
+ * (&my_buf).
+ * \arg fmt This is the format string (printf style)
+ * \arg ap This is the va_list
+ *
+ * \return The return value of this function is the same as that of the printf
+ * family of functions.
+ *
+ * Example usage:
+ * \code
+ * AST_THREADSTORAGE(my_str, my_str_init);
+ * #define MY_STR_INIT_SIZE 128
+ * ...
+ * void my_func(const char *fmt, ...)
+ * {
+ * struct ast_dynamic_str *buf;
+ * va_list ap;
+ *
+ * if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
+ * return;
+ * ...
+ * va_start(fmt, ap);
+ * ast_dynamic_str_thread_set_va(&buf, 0, &my_str, fmt, ap);
+ * va_end(ap);
+ *
+ * printf("This is the string we just built: %s\n", buf->str);
+ * ...
+ * }
+ * \endcode
+ */
+#define ast_dynamic_str_thread_set_va(buf, max_len, ts, fmt, ap) \
+ ({ \
+ int __res; \
+ while ((__res = ast_dynamic_str_thread_build_va(buf, max_len, \
+ ts, 0, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) { \
+ va_end(ap); \
+ va_start(ap, fmt); \
+ } \
+ (__res); \
+ })
+
+/*!
+ * \brief Append to a thread local dynamic string using a va_list
+ *
+ * The arguments, return values, and usage of this are the same as those for
+ * ast_dynamic_str_thread_set_va(). However, instead of setting a new value
+ * for the string, this will append to the current value.
+ */
+#define ast_dynamic_str_thread_append_va(buf, max_len, ts, fmt, ap) \
+ ({ \
+ int __res; \
+ while ((__res = ast_dynamic_str_thread_build_va(buf, max_len, \
+ ts, 1, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) { \
+ va_end(ap); \
+ va_start(ap, fmt); \
+ } \
+ (__res); \
+ })
+
+/*!
+ * \brief Core functionality of ast_dynamic_str_thread_(set|append)_va
+ *
+ * The arguments to this function are the same as those described for
+ * 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);
+
+/*!
+ * \brief Set a thread locally stored dynamic string using variable arguments
*
* \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
@@ -269,87 +365,6 @@
* AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be
* (&my_buf).
* \arg fmt This is the format string (printf style)
- * \arg ap This is the va_list
- *
- * \return The return value of this function is the same as that of the printf
- * family of functions.
- *
- * Example usage:
- * \code
- * AST_THREADSTORAGE(my_str, my_str_init);
- * #define MY_STR_INIT_SIZE 128
- * ...
- * void my_func(const char *fmt, ...)
- * {
- * struct ast_dynamic_str *buf;
- * va_list ap;
- *
- * if (!(buf = ast_dynamic_str_thread_get(&my_str, MY_STR_INIT_SIZE)))
- * return;
- * ...
- * va_start(fmt, ap);
- * ast_dynamic_str_thread_set_va(&buf, 0, &my_str, fmt, ap);
- * va_end(ap);
- *
- * printf("This is the string we just built: %s\n", buf->str);
- * ...
- * }
- * \endcode
- */
-#define ast_dynamic_str_thread_set_va(buf, max_len, ts, fmt, ap) \
- ({ \
- int __res; \
- while ((__res = ast_dynamic_str_thread_build_va(buf, max_len, \
- ts, 0, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) { \
- va_end(ap); \
- va_start(ap, fmt); \
- } \
- (__res); \
- })
-
-/*!
- * \brief Append to a thread local dynamic string using a va_list
- *
- * The arguments, return values, and usage of this are the same as those for
- * ast_dynamic_str_thread_set_va(). However, instead of setting a new value
- * for the string, this will append to the current value.
- */
-#define ast_dynamic_str_thread_append_va(buf, max_len, ts, fmt, ap) \
- ({ \
- int __res; \
- while ((__res = ast_dynamic_str_thread_build_va(buf, max_len, \
- ts, 1, fmt, ap)) == AST_DYNSTR_BUILD_RETRY) { \
- va_end(ap); \
- va_start(ap, fmt); \
- } \
- (__res); \
- })
-
-/*!
- * \brief Core functionality of ast_dynamic_str_thread_(set|append)_va
- *
- * The arguments to this function are the same as those described for
- * 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.
- */
-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);
-
-/*!
- * \brief Set a thread locally stored dynamic string using variable arguments
- *
- * \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.
- * \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
- * the AST_THREADSTORAGE macro. If declared with
- * AST_THREADSTORAGE(my_buf, my_buf_init), then this argument would be
- * (&my_buf).
- * \arg fmt This is the format string (printf style)
*
* \return The return value of this function is the same as that of the printf
* family of functions.
@@ -419,7 +434,7 @@
*
* \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 @@
)
/*!
- * \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
More information about the svn-commits
mailing list