modules: update documentation examples so they compile under ccanlint.

[ccan] / ccan / talloc / talloc.h

diff --git a/ccan/talloc/talloc.h b/ccan/talloc/talloc.h
index e38d05b8095ca9d55abdbd8e9ac833e31ca08c0c..54790055ea8bf1c56f3452585596b744fd03c5f7 100644 (file)
--- a/ccan/talloc/talloc.h
+++ b/ccan/talloc/talloc.h
@@ -27,6 +27,7 @@
 #include <stdio.h>
 #include <stdarg.h>
 #include <ccan/typesafe_cb/typesafe_cb.h>
+#include <ccan/compiler/compiler.h>
 #include "config.h"
 
 /*
@@ -39,16 +40,6 @@
 #define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
 #endif
 
-#if HAVE_ATTRIBUTE_PRINTF
-/** Use gcc attribute to check printf fns.  a1 is the 1-based index of
- * the parameter containing the format, and a2 the index of the first
- * argument. Note that some gcc 2.x versions don't handle this
- * properly **/
-#define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
-#else
-#define PRINTF_ATTRIBUTE(a1, a2)
-#endif
-
 /* try to make talloc_set_destructor() and talloc_steal() type safe,
    if we have a recent gcc */
 #if HAVE_TYPEOF
@@ -87,6 +78,30 @@
  */
 #define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
 
+/**
+ * talloc_set - allocate dynamic memory for a type, into a pointer
+ * @ptr: pointer to the pointer to assign.
+ * @ctx: context to be parent of this allocation, or NULL.
+ *
+ * talloc_set() does a talloc, but also adds a destructor which will make the
+ * pointer invalid when it is freed.  This can find many use-after-free bugs.
+ *
+ * Note that the destructor is chained off a zero-length allocation, and so
+ * is not affected by talloc_set_destructor().
+ *
+ * Example:
+ *     unsigned int *b, *a;
+ *     a = talloc(NULL, unsigned int);
+ *     talloc_set(&b, a);
+ *     talloc_free(a);
+ *     *b = 1; // This will crash!
+ *
+ * See Also:
+ *     talloc.
+ */
+#define talloc_set(pptr, ctx) \
+       _talloc_set((pptr), (ctx), sizeof(&**(pptr)), __location__)
+
 /**
  * talloc_free - free talloc'ed memory and its children
  * @ptr: the talloced pointer to free
@@ -122,7 +137,7 @@
 int talloc_free(const void *ptr);
 
 /**
- * talloc_set_destructor: set a destructor for when this pointer is freed
+ * talloc_set_destructor - set a destructor for when this pointer is freed
  * @ptr: the talloc pointer to set the destructor on
  * @destructor: the function to be called
  *
@@ -155,7 +170,7 @@ int talloc_free(const void *ptr);
  *     return 0;
  * }
  *
- * int *open_file(const char *filename)
+ * static int *open_file(const char *filename)
  * {
  *     int *fd = talloc(NULL, int);
  *     *fd = open(filename, O_RDONLY);
@@ -172,7 +187,7 @@ int talloc_free(const void *ptr);
  *     talloc, talloc_free
  */
 #define talloc_set_destructor(ptr, function)                                 \
-       _talloc_set_destructor((ptr), typesafe_cb(int, (function), (ptr)))
+       _talloc_set_destructor((ptr), typesafe_cb_def(int, (function), (ptr)))
 
 /**
  * talloc_zero - allocate zeroed dynamic memory for a type
@@ -231,6 +246,7 @@ int talloc_free(const void *ptr);
  *
  * Example:
  *     void *mem = talloc_size(NULL, 100);
+ *     memset(mem, 0xFF, 100);
  *
  * See Also:
  *     talloc, talloc_array, talloc_zero_size
@@ -327,13 +343,13 @@ void talloc_report_full(const void *ptr, FILE *f);
  *     a = talloc(NULL, unsigned int);
  *     b = talloc(NULL, unsigned int);
  *     c = talloc(a, unsigned int);
- *     // b also serves as a parent of c.
- *     talloc_reference(b, c);
+ *     // b also serves as a parent of c (don't care about errors)
+ *     (void)talloc_reference(b, c);
  */
 #define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference((ctx),(ptr))
 
 /**
- * talloc_unlink: remove a specific parent from a talloc pointer.
+ * talloc_unlink - remove a specific parent from a talloc pointer.
  * @context: the parent to remove
  * @ptr: the talloc pointer
  *
@@ -348,13 +364,14 @@ void talloc_report_full(const void *ptr, FILE *f);
  * 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.
+ *
  * Example:
  *     unsigned int *a, *b, *c;
  *     a = talloc(NULL, unsigned int);
  *     b = talloc(NULL, unsigned int);
  *     c = talloc(a, unsigned int);
  *     // b also serves as a parent of c.
- *     talloc_reference(b, c);
+ *     (void)talloc_reference(b, c);
  *     talloc_unlink(b, c);
  */
 int talloc_unlink(const void *context, void *ptr);
@@ -940,6 +957,7 @@ void *talloc_add_external(const void *ctx,
 
 /* The following definitions come from talloc.c  */
 void *_talloc(const void *context, size_t size);
+void _talloc_set(void *ptr, const void *ctx, size_t size, const char *name);
 void _talloc_set_destructor(const void *ptr, int (*destructor)(void *));
 size_t talloc_reference_count(const void *ptr);
 void *_talloc_reference(const void *context, const void *ptr);