Fix some potential misuses of ast_str in the code.

Passing an ast_str pointer by value that then calls
ast_str_set(), ast_str_set_va(), ast_str_append(), or
ast_str_append_va() can result in the pointer originally
passed by value being invalidated if the ast_str had
to be reallocated.

This fixes places in the code that do this. Only the
example in ccss.c could result in pointer invalidation
though since the other cases use a stack-allocated ast_str
and cannot be reallocated.

I've also updated the doxygen in strings.h to include
notes about potential misuse of the functions mentioned
previously.

Review: https://reviewboard.asterisk.org/r/2161
........

Merged revisions 375025 from http://svn.asterisk.org/svn/asterisk/branches/1.8
........

Merged revisions 375026 from http://svn.asterisk.org/svn/asterisk/branches/10
........

Merged revisions 375027 from http://svn.asterisk.org/svn/asterisk/branches/11


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@375044 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 21 insertions, 0 deletions

diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h
index 6861477f1..84261cdcb 100644
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -793,6 +793,12 @@ char *__ast_str_helper2(struct ast_str **buf, ssize_t max_len,
  *      ...
  * }
  * \endcode
+ *
+ * \note Care should be taken when using this function. The function can
+ * result in reallocating the ast_str. If a pointer to the ast_str is passed
+ * by value to a function that calls ast_str_set_va(), then the original ast_str
+ * pointer may be invalidated due to a reallocation.
+ *
  */
 AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_set_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap),
 {
@@ -805,6 +811,11 @@ AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_set_va(struct a
  *
  * Same as ast_str_set_va(), but append to the current content.
  *
+ * \note Care should be taken when using this function. The function can
+ * result in reallocating the ast_str. If a pointer to the ast_str is passed
+ * by value to a function that calls ast_str_append_va(), then the original ast_str
+ * pointer may be invalidated due to a reallocation.
+ *
  * \param buf, max_len, fmt, ap
  */
 AST_INLINE_API(int __attribute__((format(printf, 3, 0))) ast_str_append_va(struct ast_str **buf, ssize_t max_len, const char *fmt, va_list ap),
@@ -844,6 +855,11 @@ AST_INLINE_API(char *ast_str_append_escapecommas(struct ast_str **buf, ssize_t m
 /*!
  * \brief Set a dynamic string using variable arguments
  *
+ * \note Care should be taken when using this function. The function can
+ * result in reallocating the ast_str. If a pointer to the ast_str is passed
+ * by value to a function that calls ast_str_set(), then the original ast_str
+ * pointer may be invalidated due to a reallocation.
+ *
  * \param buf This is the address of a pointer to a struct ast_str which should
  *      have been retrieved using ast_str_thread_get.  It will need to
  *      be updated in the case that the buffer has to be reallocated to
@@ -876,6 +892,11 @@ int __attribute__((format(printf, 3, 4))) ast_str_set(
 /*!
  * \brief Append to a thread local dynamic string
  *
+ * \note Care should be taken when using this function. The function can
+ * result in reallocating the ast_str. If a pointer to the ast_str is passed
+ * by value to a function that calls ast_str_append(), then the original ast_str
+ * pointer may be invalidated due to a reallocation.
+ *
  * The arguments, return values, and usage of this function are the same as
  * ast_str_set(), but the new data is appended to the current value.
  */