take, tal, tal/path, tal/str, tal/talloc: annotate APIs with TAKES.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

ccan/take/_info

@@ -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) 

ccan/take/take.h

@@ -11,6 +11,17 @@
 #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))

ccan/tal/path/path.c

@@ -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>

ccan/tal/path/path.h

@@ -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.

ccan/tal/str/str.c

@@ -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)
 {

ccan/tal/str/str.h

@@ -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 */

ccan/tal/tal.c

@@ -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>

ccan/tal/tal.h

@@ -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),

ccan/tal/talloc/talloc.c

@@ -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>
 

ccan/tal/talloc/talloc.h

@@ -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>