diff options
Diffstat (limited to 'ctdb/lib/talloc/talloc.h')
| -rw-r--r-- | ctdb/lib/talloc/talloc.h | 204 |
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) |