talloc: Sync to talloc 2.0.8 from upstream

Signed-off-by: Amitay Isaacs <amitay@gmail.com>

(This used to be ctdb commit 3bffca8c17e441364525df115ee2ac16b5969e24)

1 files changed, 188 insertions, 16 deletions

diff --git a/ctdb/lib/talloc/talloc.h b/ctdb/lib/talloc/talloc.h
index 96c7e2467c..f3cbcd0e7c 100644
--- a/ctdb/lib/talloc/talloc.h
+++ b/ctdb/lib/talloc/talloc.h
@@ -1,16 +1,16 @@
 #ifndef _TALLOC_H_
 #define _TALLOC_H_
-/* 
+/*
    Unix SMB/CIFS implementation.
    Samba temporary memory allocation functions
 
    Copyright (C) Andrew Tridgell 2004-2005
    Copyright (C) Stefan Metzmacher 2006
-   
+
      ** NOTE! The following LGPL license applies to the talloc
      ** library. This does NOT imply that all of Samba is released
      ** under the LGPL
-   
+
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
@@ -194,6 +194,11 @@ void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
  * talloc_set_log_stderr() for more information on talloc logging
  * functions.
  *
+ * If <code>TALLOC_FREE_FILL</code> environment variable is set,
+ * the memory occupied by the context is filled with the value of this variable.
+ * The value should be a numeric representation of the character you want to
+ * use.
+ *
  * talloc_free() operates recursively on its children.
  *
  * @param[in]  ptr      The chunk to be freed.
@@ -822,6 +827,10 @@ void *talloc_find_parent_bytype(const void *ptr, #type);
  * recursively. If you use the child of the talloc pool as a parent for
  * grand-children, their memory is also taken from the talloc pool.
  *
+ * If there is not enough memory in the pool to allocate the new child,
+ * it will create a new talloc chunk as if the parent was a normal talloc
+ * context.
+ *
  * If you talloc_free() children of a talloc pool, the memory is not given
  * back to the system. Instead, free(3) is only called if the talloc_pool()
  * itself is released with talloc_free().
@@ -830,7 +839,8 @@ void *talloc_find_parent_bytype(const void *ptr, #type);
  * talloc pool to a talloc parent outside the pool, the whole pool memory is
  * not free(3)'ed until that moved chunk is also talloc_free()ed.
  *
- * @param[in]  context  The talloc context to hang the result off.
+ * @param[in]  context  The talloc context to hang the result off (must not
+ *			be another pool).
  *
  * @param[in]  size     Size of the talloc pool.
  *
@@ -1290,28 +1300,64 @@ void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
 char *talloc_strdup(const void *t, const char *p);
 
 /**
- * @brief Append a string to given string and duplicate the result.
+ * @brief Append a string to given string.
+ *
+ * The destination string is reallocated to take
+ * <code>strlen(s) + strlen(a) + 1</code> characters.
+ *
+ * This functions sets the name of the new pointer to the new
+ * string. This is equivalent to:
+ *
+ * @code
+ *      talloc_set_name_const(ptr, ptr)
+ * @endcode
+ *
+ * If <code>s == NULL</code> then new context is created.
  *
  * @param[in]  s        The destination to append to.
  *
  * @param[in]  a        The string you want to append.
  *
- * @return              The duplicated string, NULL on error.
+ * @return              The concatenated strings, NULL on error.
  *
  * @see talloc_strdup()
+ * @see talloc_strdup_append_buffer()
  */
 char *talloc_strdup_append(char *s, const char *a);
 
 /**
- * @brief Append a string to a given buffer and duplicate the result.
+ * @brief Append a string to a given buffer.
+ *
+ * This is a more efficient version of talloc_strdup_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_strdup_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_strdup_append(str_a, ", hello");
+ *      char *buf = talloc_strdup_append_buffer(str_b, ", hello");
+ *
+ *      printf("%s\n", app); // hello, hello (app = "hello, hello")
+ *      printf("%s\n", buf); // hello (buf = "hello\0world, hello")
+ * @endcode
+ *
+ * If <code>s == NULL</code> then new context is created.
  *
  * @param[in]  s        The destination buffer to append to.
  *
  * @param[in]  a        The string you want to append.
  *
- * @return              The duplicated string, NULL on error.
+ * @return              The concatenated strings, NULL on error.
  *
  * @see talloc_strdup()
+ * @see talloc_strdup_append()
+ * @see talloc_array_length()
  */
 char *talloc_strdup_append_buffer(char *s, const char *a);
 
@@ -1338,8 +1384,19 @@ char *talloc_strdup_append_buffer(char *s, const char *a);
 char *talloc_strndup(const void *t, const char *p, size_t n);
 
 /**
- * @brief Append at most n characters of a string to given string and duplicate
- *        the result.
+ * @brief Append at most n characters of a string to given string.
+ *
+ * The destination string is reallocated to take
+ * <code>strlen(s) + strnlen(a, n) + 1</code> characters.
+ *
+ * This functions sets the name of the new pointer to the new
+ * string. This is equivalent to:
+ *
+ * @code
+ *      talloc_set_name_const(ptr, ptr)
+ * @endcode
+ *
+ * If <code>s == NULL</code> then new context is created.
  *
  * @param[in]  s        The destination string to append to.
  *
@@ -1348,15 +1405,36 @@ char *talloc_strndup(const void *t, const char *p, size_t n);
  * @param[in]  n        The number of characters you want to append from the
  *                      string.
  *
- * @return              The duplicated string, NULL on error.
+ * @return              The concatenated strings, NULL on error.
  *
  * @see talloc_strndup()
+ * @see talloc_strndup_append_buffer()
  */
 char *talloc_strndup_append(char *s, const char *a, size_t n);
 
 /**
- * @brief Append at most n characters of a string to given buffer and duplicate
- *        the result.
+ * @brief Append at most n characters of a string to given buffer
+ *
+ * This is a more efficient version of talloc_strndup_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_strndup_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_strndup_append(str_a, ", hello", 7);
+ *      char *buf = talloc_strndup_append_buffer(str_b, ", hello", 7);
+ *
+ *      printf("%s\n", app); // hello, hello (app = "hello, hello")
+ *      printf("%s\n", buf); // hello (buf = "hello\0world, hello")
+ * @endcode
+ *
+ * If <code>s == NULL</code> then new context is created.
  *
  * @param[in]  s        The destination buffer to append to.
  *
@@ -1365,9 +1443,11 @@ char *talloc_strndup_append(char *s, const char *a, size_t n);
  * @param[in]  n        The number of characters you want to append from the
  *                      string.
  *
- * @return              The duplicated string, NULL on error.
+ * @return              The concatenated strings, NULL on error.
  *
  * @see talloc_strndup()
+ * @see talloc_strndup_append()
+ * @see talloc_array_length()
  */
 char *talloc_strndup_append_buffer(char *s, const char *a, size_t n);
 
@@ -1462,6 +1542,8 @@ char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3)
  *      talloc_set_name_const(ptr, ptr)
  * @endcode
  *
+ * If <code>s == NULL</code> then new context is created.
+ *
  * @param[in]  s        The string to append to.
  *
  * @param[in]  fmt      The format string.
@@ -1475,6 +1557,27 @@ 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
+ *
+ * If <code>s == NULL</code> then new context is created.
+ *
  * @param[in]  s        The string to append to
  *
  * @param[in]  fmt      The format string.
@@ -1482,6 +1585,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);
 
@@ -1685,12 +1791,78 @@ void talloc_enable_leak_report(void);
  */
 void talloc_enable_leak_report_full(void);
 
-/* @} ******************************************************************/
-
+/**
+ * @brief Set a custom "abort" function that is called on serious error.
+ *
+ * The default "abort" function is <code>abort()</code>.
+ *
+ * The "abort" function is called when:
+ *
+ * <ul>
+ *  <li>talloc_get_type_abort() fails</li>
+ *  <li>the provided pointer is not a valid talloc context</li>
+ *  <li>when the context meta data are invalid</li>
+ *  <li>when access after free is detected</li>
+ * </ul>
+ *
+ * Example:
+ *
+ * @code
+ * void my_abort(const char *reason)
+ * {
+ *      fprintf(stderr, "talloc abort: %s\n", reason);
+ *      abort();
+ * }
+ *
+ *      talloc_set_abort_fn(my_abort);
+ * @endcode
+ *
+ * @param[in]  abort_fn      The new "abort" function.
+ *
+ * @see talloc_set_log_fn()
+ * @see talloc_get_type()
+ */
 void talloc_set_abort_fn(void (*abort_fn)(const char *reason));
+
+/**
+ * @brief Set a logging function.
+ *
+ * @param[in]  log_fn      The logging function.
+ *
+ * @see talloc_set_log_stderr()
+ * @see talloc_set_abort_fn()
+ */
 void talloc_set_log_fn(void (*log_fn)(const char *message));
+
+/**
+ * @brief Set stderr as the output for logs.
+ *
+ * @see talloc_set_log_fn()
+ * @see talloc_set_abort_fn()
+ */
 void talloc_set_log_stderr(void);
 
+/**
+ * @brief Set a max memory limit for the current context hierarchy
+ *	  This affects all children of this context and constrain any
+ *	  allocation in the hierarchy to never exceed the limit set.
+ *	  The limit can be removed by setting 0 (unlimited) as the
+ *	  max_size by calling the funciton again on the sam context.
+ *	  Memory limits can also be nested, meaning a hild can have
+ *	  a stricter memory limit than a parent.
+ *	  Memory limits are enforced only at memory allocation time.
+ *	  Stealing a context into a 'limited' hierarchy properly
+ *	  updates memory usage but does *not* cause failure if the
+ *	  move causes the new parent to exceed its limits. However
+ *	  any further allocation on that hierarchy will then fail.
+ *
+ * @param[in]	ctx		The talloc context to set the limit on
+ * @param[in]	max_size	The (new) max_size
+ */
+int talloc_set_memlimit(const void *ctx, size_t max_size);
+
+/* @} ******************************************************************/
+
 #if TALLOC_DEPRECATED
 #define talloc_zero_p(ctx, type) talloc_zero(ctx, type)
 #define talloc_p(ctx, type) talloc(ctx, type)