Make some notes about common usage of pbx_builtin_getvar_helper() that is not

thread-safe.


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@111909 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 14 insertions, 0 deletions

diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index 1761a9bd7..56bd83fa5 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -800,6 +800,20 @@ int pbx_builtin_serialize_variables(struct ast_channel *chan, struct ast_str **b
 
 /*!
  * \note Will lock the channel.
+ *
+ * \note This function will return a pointer to the buffer inside the channel
+ * variable.  This value should only be accessed with the channel locked.  If
+ * the value needs to be kept around, it should be done by using the following
+ * thread-safe code:
+ * \code
+ *		const char *var;
+ *
+ *		ast_channel_lock(chan);
+ *		if ((var = pbx_builtin_getvar_helper(chan, "MYVAR"))) {
+ *			var = ast_strdupa(var);
+ *		}
+ *		ast_channel_unlock(chan);
+ * \endcode
  */
 const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);