*/
#define TALLOC_VERSION_MAJOR 2
-#define TALLOC_VERSION_MINOR 0
+#define TALLOC_VERSION_MINOR 1
int talloc_version_major(void);
int talloc_version_minor(void);
* destructors. Likewise, if "ptr" is NULL, then the function will make
* no modifications and return -1.
*
- * If this pointer has an additional parent when talloc_free() is called
- * then the memory is not actually released, but instead the most
- * recently established parent is destroyed. See talloc_reference() for
- * details on establishing additional parents.
- *
- * For more control on which parent is removed, see talloc_unlink()
- *
- * talloc_free() operates recursively on its children.
- *
- * From the 2.0 version of talloc, as a special case, talloc_free() is
- * refused on pointers that have more than one parent, as talloc would
- * have no way of knowing which parent should be removed. To free a
+ * From version 2.0 and onwards, as a special case, talloc_free() is
+ * refused on pointers that have more than one parent associated, as talloc
+ * would have no way of knowing which parent should be removed. This is
+ * different from older versions in the sense that always the reference to
+ * the most recently established parent has been destroyed. Hence to free a
* pointer that has more than one parent please use talloc_unlink().
*
* To help you find problems in your code caused by this behaviour, if
* talloc_set_log_stderr() for more information on talloc logging
* functions.
*
+ * talloc_free() operates recursively on its children.
+ *
* @param[in] ptr The chunk to be freed.
*
* @return Returns 0 on success and -1 on error. A possible
* The function walks along the list of all children of a talloc context and
* talloc_free()s only the children, not the context itself.
*
- * @param[in] ptr The chunk that you want to free the children of.
+ * A NULL argument is handled as no-op.
+ *
+ * @param[in] ptr The chunk that you want to free the children of
+ * (NULL is allowed too)
*/
void talloc_free_children(void *ptr);
*
* @param[in] new_ctx The new parent context.
*
- * @param[in] ptr Pointer to the talloc chunk to move.
+ * @param[in] pptr Pointer to the talloc chunk to move.
*
* @return The pointer of the talloc chunk it has been moved to,
* NULL on error.
*/
-void *talloc_move(const void *new_ctx, const void *ptr);
+void *talloc_move(const void *new_ctx, void **pptr);
#else
-#define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
+#define talloc_move(ctx, pptr) (_TALLOC_TYPEOF(*(pptr)))_talloc_move((ctx),(void *)(pptr))
void *_talloc_move(const void *new_ctx, const void *pptr);
#endif
/**
* @brief Assign a type to a talloc chunk.
*
- * This macro allows you to force the name of a pointer to be a particular type.
- * This can be used in conjunction with talloc_get_type() to do type checking on
- * void* pointers.
+ * This macro allows you to force the name of a pointer to be of a particular
+ * type. This can be used in conjunction with talloc_get_type() to do type
+ * checking on void* pointers.
*
* It is equivalent to this:
*
* will reduce the number of parents of this pointer by 1, and will
* cause this pointer to be freed if it runs out of parents.
*
- * - you can talloc_free() the pointer itself. That will destroy the
- * most recently established parent to the pointer and leave the
- * pointer as a child of its current parent.
+ * - you can talloc_free() the pointer itself if it has at maximum one
+ * parent. This behaviour has been changed since the release of version
+ * 2.0. Further informations in the description of "talloc_free".
*
* For more control on which parent to remove, see talloc_unlink()
* @param[in] ctx The additional parent.
void *_talloc_reference_loc(const void *context, const void *ptr, const char *location);
#endif
+/**
+ * @brief Mark a talloc pointer as being referencable.
+ *
+ * The talloc_may_reference() function marks ptr as having future
+ * references. As referenced (aka multi-parent) objects need to be
+ * handled differently, this helps debugging: you will get a warning
+ * from talloc_steal() and talloc_free() even if there is only a
+ * single (or NULL) parent.
+ *
+ * It will also warn on talloc_parent() or talloc_parent_name() on
+ * such pointers.
+ *
+ * @param[in] ptr The pointer you may create an additional parent for.
+ *
+ * Example:
+ * @code
+ * unsigned int *a;
+ * // We may reference this later; be careful!
+ * a = talloc(NULL, unsigned int);
+ * talloc_may_reference(a);
+ * @endcode
+ *
+ * @see talloc_reference(), talloc_set_flag()
+ */
+void *talloc_may_reference(const void *ptr);
+
/**
* @brief Remove a specific parent from a talloc chunk.
*
* either be a context used in talloc_reference() with this pointer, or must be
* a direct parent of ptr.
*
- * Usually you can just use talloc_free() instead of talloc_unlink(), but
- * sometimes it is useful to have the additional control on which parent is
- * removed.
+ * You can just use talloc_free() instead of talloc_unlink() if there
+ * is at maximum one parent. This behaviour has been changed since the
+ * release of version 2.0. Further informations in the description of
+ * "talloc_free".
*
* @param[in] context The talloc parent to remove.
*
/**
* @brief Get the size of a talloc chunk.
*
- * This function lets you know the amount of memory alloced so far by
+ * This function lets you know the amount of memory allocated so far by
* this context. It does NOT account for subcontext memory.
* This can be used to calculate the size of an array.
*
* @endcode
*
* @see talloc()
- * @see talloc_array_zero()
+ * @see talloc_zero_array()
*/
void *talloc_array(const void *ctx, #type, unsigned count);
#else
* @brief Append a formatted string to another string.
*
* This function appends the given formatted string to the given string. Use
- * this varient when the string in the current talloc buffer may have been
+ * this variant when the string in the current talloc buffer may have been
* truncated in length.
*
* This functions sets the name of the new pointer to the new
* @brief Print a summary report of all memory used by ptr.
*
* This provides a more detailed report than talloc_report(). It will
- * recursively print the ensire tree of memory referenced by the
+ * recursively print the entire tree of memory referenced by the
* pointer. References in the tree are shown by giving the name of the
* pointer that is referenced.
*
*/
void talloc_enable_leak_report_full(void);
+#define TALLOC_FLAG_WARN_MAY_REFERENCE 0x1
+/**
+ * @brief Set a global flag which alters talloc's behavior.
+ *
+ * 0 is returned if the flag is known, -1 otherwise.
+ *
+ * Flag is one of the following:
+ * TALLOC_FLAG_WARN_MAY_REFERENCE:
+ * Warn if talloc_reference() is called on a pointer without talloc_may_reference()
+ * being called first.
+ */
+int talloc_set_flag(unsigned int flag);
+
+/**
+ * @brief Remove a global flag which alters talloc's behavior.
+ *
+ * 0 is returned if the flag is known, -1 otherwise.
+ */
+int talloc_unset_flag(unsigned int flag);
+
/* @} ******************************************************************/
void talloc_set_abort_fn(void (*abort_fn)(const char *reason));
git.samba.org / rusty / samba.git / blobdiff