gitify the tree, especially the web makefile.

[ccan] / ccan / talloc / talloc.h

diff --git a/ccan/talloc/talloc.h b/ccan/talloc/talloc.h
index fb2cbad7446d013076971da5c4e5a227426c9402..e65588cd57d3966b7b9108e35cfde35706d05797 100644 (file)
--- a/ccan/talloc/talloc.h
+++ b/ccan/talloc/talloc.h
@@ -90,9 +90,9 @@
  * is not affected by talloc_set_destructor().
  *
  * Example:
- *     unsigned int *a;
+ *     unsigned int *b, *a;
  *     a = talloc(NULL, unsigned int);
- *     talloc_set(&b, a, unsigned int);
+ *     talloc_set(&b, a);
  *     talloc_free(a);
  *     *b = 1; // This will crash!
  *
@@ -137,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
  *
@@ -170,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);
@@ -246,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
@@ -342,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
  *
@@ -363,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);
@@ -570,7 +572,7 @@ char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3)
  *
  *    talloc_set_name_const(ptr, ptr)
  */
-char *talloc_append_string(char *orig, const char *append);
+char *WARN_UNUSED_RESULT talloc_append_string(char *orig, const char *append);
 
 /**
  * talloc_asprintf_append - sprintf onto the end of a talloc buffer.
@@ -584,7 +586,8 @@ char *talloc_append_string(char *orig, const char *append);
  * equivalent to:
  *   talloc_set_name_const(ptr, ptr)
  */
-char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
+char *WARN_UNUSED_RESULT talloc_asprintf_append(char *s, const char *fmt, ...)
+       PRINTF_ATTRIBUTE(2,3);
 
 /**
  * talloc_vasprintf - vsprintf into a talloc buffer.
@@ -611,7 +614,8 @@ char *talloc_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIB
  * The talloc_vasprintf_append() function is equivalent to
  * talloc_asprintf_append(), except it takes a va_list.
  */
-char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
+char *WARN_UNUSED_RESULT talloc_vasprintf_append(char *s, const char *fmt, va_list ap)
+       PRINTF_ATTRIBUTE(2,0);
 
 /**
  * talloc_set_type - force the name of a pointer to a particular type
@@ -960,7 +964,7 @@ 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);
 
-void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
+void *WARN_UNUSED_RESULT _talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
 void *talloc_parent(const void *ptr);
 const char *talloc_parent_name(const void *ptr);
 void *_talloc_steal(const void *new_ctx, const void *ptr);
@@ -969,7 +973,7 @@ void *_talloc_zero(const void *ctx, size_t size, const char *name);
 void *_talloc_memdup(const void *t, const void *p, size_t size, const char *name);
 void *_talloc_array(const void *ctx, size_t el_size, unsigned count, const char *name);
 void *_talloc_zero_array(const void *ctx, size_t el_size, unsigned count, const char *name);
-void *_talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
+void *WARN_UNUSED_RESULT _talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
 void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
 void talloc_show_parents(const void *context, FILE *file);
 int talloc_is_parent(const void *context, const void *ptr);