From 30ca3915e50a9d9f71a28b7779fce81f8b6453d5 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Pavel=20B=C5=99ezina?= <pbrezina@redhat.com>
Date: Mon, 16 Apr 2012 13:32:02 +0200
Subject: [PATCH] Talloc doc: talloc_asprintf_append_buffer()

Explains the difference between _append and _append_buffer.
---
 lib/talloc/talloc.h | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/lib/talloc/talloc.h b/lib/talloc/talloc.h
index 244785b3a45..c1b56502669 100644
--- a/lib/talloc/talloc.h
+++ b/lib/talloc/talloc.h
@@ -1540,6 +1540,25 @@ char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3
 /**
  * @brief Append a formatted string to another string.
  *
+ * This is a more efficient version of talloc_asprintf_append(). It determines
+ * the length of the destination string by the size of the talloc context.
+ *
+ * Use this very carefully as it produces a different result than
+ * talloc_asprintf_append() when a zero character is in the middle of the
+ * destination string.
+ *
+ * @code
+ *      char *str_a = talloc_strdup(NULL, "hello world");
+ *      char *str_b = talloc_strdup(NULL, "hello world");
+ *      str_a[5] = str_b[5] = '\0'
+ *
+ *      char *app = talloc_asprintf_append(str_a, "%s", ", hello");
+ *      char *buf = talloc_strdup_append_buffer(str_b, "%s", ", hello");
+ *
+ *      printf("%s\n", app); // hello, hello (app = "hello, hello")
+ *      printf("%s\n", buf); // hello (buf = "hello\0world, hello")
+ * @endcode
+ *
  * @param[in]  s        The string to append to
  *
  * @param[in]  fmt      The format string.
@@ -1547,6 +1566,9 @@ char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3
  * @param[in]  ...      The parameters used to fill fmt.
  *
  * @return              The formatted string, NULL on error.
+ *
+ * @see talloc_asprintf()
+ * @see talloc_asprintf_append()
  */
 char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
 
-- 
2.11.4.GIT