take, tal, tal/path, tal/str, tal/talloc: annotate APIs with TAKES.
authorRusty Russell <rusty@rustcorp.com.au>
Wed, 15 Mar 2017 03:55:07 +0000 (14:25 +1030)
committerRusty Russell <rusty@rustcorp.com.au>
Wed, 15 Mar 2017 03:57:38 +0000 (14:27 +1030)
Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
ccan/take/_info
ccan/take/take.h
ccan/tal/path/path.c
ccan/tal/path/path.h
ccan/tal/str/str.c
ccan/tal/str/str.h
ccan/tal/tal.c
ccan/tal/tal.h
ccan/tal/talloc/talloc.c
ccan/tal/talloc/talloc.h

index d013838a14916e76a34ff3353f33740cb9f33b08..c8cc4ac995789fc9f646b82b060a8c48b641ce02 100644 (file)
@@ -18,7 +18,7 @@
  *     #include <string.h>
  *
  *     // Dumb basename program and driver.
- *     static char *base(const char *file)
+ *     static char *base(const char *file TAKES)
  *     {
  *             const char *p = strrchr(file, '/');
  *             if (!p) 
index e0db2902021cff390f46b3330069ecb1b3dd4453..8950c6b5bc91f1c9ed374bb0f60497597efaa019 100644 (file)
 #define TAKE_LABEL(p) NULL
 #endif
 
+/**
+ * TAKES - annotate a formal parameter as being take()-able
+ *
+ * This doesn't do anything, but useful for documentation.
+ *
+ * Example:
+ *     void print_string(const char *str TAKES);
+ *     
+ */
+#define TAKES
+
 /**
  * take - record a pointer to be consumed by the function its handed to.
  * @p: the pointer to mark, or NULL.
@@ -31,7 +42,7 @@
  *
  * Example:
  *     // Silly routine to add 1
- *     static int *add_one(const int *num)
+ *     static int *add_one(const int *num TAKES)
  *     {
  *             int *ret;
  *             if (taken(num))
index 93362c754f599981014916a71482b6997c98686d..362152d29cb261747f60a46d14db60addd6b928b 100644 (file)
@@ -1,7 +1,6 @@
 /* Licensed under BSD-MIT - see LICENSE file for details */
 #include <ccan/tal/path/path.h>
 #include <ccan/str/str.h>
-#include <ccan/take/take.h>
 #include <ccan/tal/str/str.h>
 #include <sys/types.h>
 #include <sys/stat.h>
index 65d539c11c134cc05f680a8b4599da4752122fb0..5678fd1a99e6f87280d1089d089b988704450201 100644 (file)
@@ -20,7 +20,7 @@ char *path_cwd(const tal_t *ctx);
  * Returns NULL and sets errno on error, otherwise returns nul-terminated
  * link contents.
  */
-char *path_readlink(const tal_t *ctx, const char *link);
+char *path_readlink(const tal_t *ctx, const char *link TAKES);
 
 /**
  * path_canon - return the canonical absolute pathname.
@@ -31,7 +31,7 @@ char *path_readlink(const tal_t *ctx, const char *link);
  * path with no symbolic links and no extra separators (ie. as per
  * realpath).
  */
-char *path_canon(const tal_t *ctx, const char *a);
+char *path_canon(const tal_t *ctx, const char *a TAKES);
 
 /**
  * path_simplify - remove double-/, ./ and some ../, plus trailing /.
@@ -42,7 +42,7 @@ char *path_canon(const tal_t *ctx, const char *a);
  * terms or remove symlinks, but it does neaten it by removing extraneous
  * parts.
  */
-char *path_simplify(const tal_t *ctx, const char *a);
+char *path_simplify(const tal_t *ctx, const char *a TAKES);
 
 /**
  * path_join - attach one path to another.
@@ -53,14 +53,14 @@ char *path_simplify(const tal_t *ctx, const char *a);
  * If @a is an absolute path, return a copy of it.  Otherwise, attach
  * @a to @base.
  */
-char *path_join(const tal_t *ctx, const char *base, const char *a);
+char *path_join(const tal_t *ctx, const char *base TAKES, const char *a TAKES);
 
 /**
  * path_pushd - save old dir and change to a new one.
  * @ctx: the context to tal the result from
  * @dir: the directory to return to (can be take())
  */
-struct path_pushd *path_pushd(const tal_t *ctx, const char *dir);
+struct path_pushd *path_pushd(const tal_t *ctx, const char *dir TAKES);
 
 /**
  * path_popd - return to old, path_pushd dir.
@@ -83,7 +83,8 @@ bool path_popd(struct path_pushd *olddir);
  *     char *path = path_rel(NULL, "/tmp", "/");
  *     assert(strcmp(path, "..") == 0);
  */
-char *path_rel(const tal_t *ctx, const char *fromdir, const char *to);
+char *path_rel(const tal_t *ctx,
+              const char *fromdir TAKES, const char *to TAKES);
 
 /**
  * path_basename - get trailing filename part of path
@@ -102,7 +103,7 @@ char *path_rel(const tal_t *ctx, const char *fromdir, const char *to);
  * See Also:
  *     path_dirname()
  */
-char *path_basename(const tal_t *ctx, const char *path);
+char *path_basename(const tal_t *ctx, const char *path TAKES);
 
 /**
  * path_dirname - get the directory part of path
@@ -114,7 +115,7 @@ char *path_basename(const tal_t *ctx, const char *path);
  * See Also:
  *     path_basename()
  */
-char *path_dirname(const tal_t *ctx, const char *path);
+char *path_dirname(const tal_t *ctx, const char *path TAKES);
 
 /**
  * path_is_abs - is a path absolute?
@@ -149,7 +150,7 @@ bool path_is_dir(const char *path);
  * See Also:
  *     strjoin()
  */
-char **path_split(const tal_t *ctx, const char *path);
+char **path_split(const tal_t *ctx, const char *path TAKES);
 
 /**
  * path_ext_off - get offset of the extension within a pathname.
index 7adb9ef5aefbf990067a1dc80569dbba6f679587..4b3b11aa603cf23733ec9aa24251e602c2c7723f 100644 (file)
@@ -11,7 +11,6 @@
 #include <unistd.h>
 #include <stdio.h>
 #include <ccan/str/str.h>
-#include <ccan/take/take.h>
 
 char *tal_strdup(const tal_t *ctx, const char *p)
 {
index 5147ca2d4667fc7cc6997c34c9e6fdc5fc113c85..ec853defccf9804b42a02879070c12faa493d06b 100644 (file)
@@ -14,7 +14,7 @@
  * @ctx: NULL, or tal allocated object to be parent.
  * @p: the string to copy (can be take()).
  */
-char *tal_strdup(const tal_t *ctx, const char *p);
+char *tal_strdup(const tal_t *ctx, const char *p TAKES);
 
 /**
  * tal_strndup - duplicate a limited amount of a string.
@@ -24,14 +24,14 @@ char *tal_strdup(const tal_t *ctx, const char *p);
  *
  * Always gives a nul-terminated string, with strlen() <= @n.
  */
-char *tal_strndup(const tal_t *ctx, const char *p, size_t n);
+char *tal_strndup(const tal_t *ctx, const char *p TAKES, size_t n);
 
 /**
  * tal_fmt - allocate a formatted string
  * @ctx: NULL, or tal allocated object to be parent.
  * @fmt: the printf-style format (can be take()).
  */
-char *tal_fmt(const tal_t *ctx, const char *fmt, ...) PRINTF_FMT(2,3);
+char *tal_fmt(const tal_t *ctx, const char *fmt TAKES, ...) PRINTF_FMT(2,3);
 
 /**
  * tal_vfmt - allocate a formatted string (va_list version)
@@ -39,7 +39,7 @@ char *tal_fmt(const tal_t *ctx, const char *fmt, ...) PRINTF_FMT(2,3);
  * @fmt: the printf-style format (can be take()).
  * @va: the va_list containing the format args.
  */
-char *tal_vfmt(const tal_t *ctx, const char *fmt, va_list ap)
+char *tal_vfmt(const tal_t *ctx, const char *fmt TAKES, va_list ap)
        PRINTF_FMT(2,0);
 
 /**
@@ -49,7 +49,7 @@ char *tal_vfmt(const tal_t *ctx, const char *fmt, va_list ap)
  *
  * Returns false on allocation failure.
  */
-bool tal_append_fmt(char **baseptr, const char *fmt, ...) PRINTF_FMT(2,3);
+bool tal_append_fmt(char **baseptr, const char *fmt TAKES, ...) PRINTF_FMT(2,3);
 
 /**
  * tal_append_vfmt - append a formatted string to a talloc string (va_list)
@@ -59,7 +59,7 @@ bool tal_append_fmt(char **baseptr, const char *fmt, ...) PRINTF_FMT(2,3);
  *
  * Returns false on allocation failure.
  */
-bool tal_append_vfmt(char **baseptr, const char *fmt, va_list ap);
+bool tal_append_vfmt(char **baseptr, const char *fmt TAKES, va_list ap);
 
 /**
  * tal_strcat - join two strings together
@@ -67,7 +67,7 @@ bool tal_append_vfmt(char **baseptr, const char *fmt, va_list ap);
  * @s1: the first string (can be take()).
  * @s2: the second string (can be take()).
  */
-char *tal_strcat(const tal_t *ctx, const char *s1, const char *s2);
+char *tal_strcat(const tal_t *ctx, const char *s1 TAKES, const char *s2 TAKES);
 
 enum strsplit {
        STR_EMPTY_OK,
@@ -110,7 +110,9 @@ enum strsplit {
  *     }
  */
 char **tal_strsplit(const tal_t *ctx,
-                   const char *string, const char *delims, enum strsplit flag);
+                   const char *string TAKES,
+                   const char *delims TAKES,
+                   enum strsplit flag);
 
 enum strjoin {
        STR_TRAIL,
@@ -140,7 +142,9 @@ enum strjoin {
  *             return ret;
  *     }
  */
-char *tal_strjoin(const void *ctx, char *strings[], const char *delim,
+char *tal_strjoin(const void *ctx,
+                 char *strings[] TAKES,
+                 const char *delim TAKES,
                  enum strjoin flags);
 
 /**
@@ -183,5 +187,6 @@ char *tal_strjoin(const void *ctx, char *strings[], const char *delim,
  *             return 0;
  *     }
  */
-bool tal_strreg(const void *ctx, const char *string, const char *regex, ...);
+bool tal_strreg(const void *ctx, const char *string TAKES,
+               const char *regex TAKES, ...);
 #endif /* CCAN_STR_TAL_H */
index 555dd1333d8f7be28ae837b4a4f0d1cba5686d07..331f7ea5ca5bca91fd7249bbdc0ca8f83300b73d 100644 (file)
@@ -2,7 +2,6 @@
 #include <ccan/tal/tal.h>
 #include <ccan/compiler/compiler.h>
 #include <ccan/list/list.h>
-#include <ccan/take/take.h>
 #include <ccan/alignof/alignof.h>
 #include <assert.h>
 #include <stdio.h>
index e525a01d1193144168d52c87ab901a1d9cbc655e..30c8e7bb9207c4daba3cb046e651ff288de21bfe 100644 (file)
@@ -6,6 +6,7 @@
 #include <ccan/likely/likely.h>
 #include <ccan/typesafe_cb/typesafe_cb.h>
 #include <ccan/str/str.h>
+#include <ccan/take/take.h>
 #include <stdlib.h>
 #include <stdbool.h>
 #include <stdarg.h>
@@ -351,7 +352,7 @@ tal_t *tal_parent(const tal_t *ctx);
  * @type: the type (should match type of @p!)
  * @p: the object to copy (or reparented if take())
  */
-#define tal_dup(ctx, type, p)                  \
+#define tal_dup(ctx, type, p)                                  \
        ((type *)tal_dup_((ctx), tal_typechk_(p, type *),       \
                          sizeof(type), 1, 0,                   \
                          false, TAL_LABEL(type, "")))
@@ -487,14 +488,14 @@ void *tal_alloc_(const tal_t *ctx, size_t bytes, bool clear,
 void *tal_alloc_arr_(const tal_t *ctx, size_t bytes, size_t count, bool clear,
                     bool add_length, const char *label);
 
-void *tal_dup_(const tal_t *ctx, const void *p, size_t size,
+void *tal_dup_(const tal_t *ctx, const void *p TAKES, size_t size,
               size_t n, size_t extra, bool add_length,
               const char *label);
 
 tal_t *tal_steal_(const tal_t *new_parent, const tal_t *t);
 
 bool tal_resize_(tal_t **ctxp, size_t size, size_t count, bool clear);
-bool tal_expand_(tal_t **ctxp, const void *src, size_t size, size_t count);
+bool tal_expand_(tal_t **ctxp, const void *src TAKES, size_t size, size_t count);
 
 bool tal_add_destructor_(const tal_t *ctx, void (*destroy)(void *me));
 bool tal_add_destructor2_(const tal_t *ctx, void (*destroy)(void *me, void *arg),
index fbe9b38474e923610bdcfefb39afee113d5ebcdc..ab96ff78a7e878b1c630df847ef27316e501998d 100644 (file)
@@ -1,6 +1,5 @@
 /* Licensed under LGPL - see LICENSE file for details */
 #include <ccan/tal/talloc/talloc.h>
-#include <ccan/take/take.h>
 #include <errno.h>
 #include <assert.h>
 
index 8dfb80e7dd27ea59af20a57cf94966e94a589dd9..ea4de28998a4d220a1330963b41030d5174d7189 100644 (file)
@@ -6,6 +6,7 @@
 #include <ccan/likely/likely.h>
 #include <ccan/typesafe_cb/typesafe_cb.h>
 #include <ccan/str/str.h>
+#include <ccan/take/take.h>
 #include <talloc.h>
 #include <stdlib.h>
 #include <stdbool.h>