From ed6dd33e06c0e8f1c4dd006e0b70d9f2d6ba6c09 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Wed, 15 Mar 2017 14:25:07 +1030 Subject: [PATCH] take, tal, tal/path, tal/str, tal/talloc: annotate APIs with TAKES. Signed-off-by: Rusty Russell --- ccan/take/_info | 2 +- ccan/take/take.h | 13 ++++++++++++- ccan/tal/path/path.c | 1 - ccan/tal/path/path.h | 19 ++++++++++--------- ccan/tal/str/str.c | 1 - ccan/tal/str/str.h | 25 +++++++++++++++---------- ccan/tal/tal.c | 1 - ccan/tal/tal.h | 7 ++++--- ccan/tal/talloc/talloc.c | 1 - ccan/tal/talloc/talloc.h | 1 + 10 files changed, 43 insertions(+), 28 deletions(-) diff --git a/ccan/take/_info b/ccan/take/_info index d013838a..c8cc4ac9 100644 --- a/ccan/take/_info +++ b/ccan/take/_info @@ -18,7 +18,7 @@ * #include * * // 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) diff --git a/ccan/take/take.h b/ccan/take/take.h index e0db2902..8950c6b5 100644 --- a/ccan/take/take.h +++ b/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)) diff --git a/ccan/tal/path/path.c b/ccan/tal/path/path.c index 93362c75..362152d2 100644 --- a/ccan/tal/path/path.c +++ b/ccan/tal/path/path.c @@ -1,7 +1,6 @@ /* Licensed under BSD-MIT - see LICENSE file for details */ #include #include -#include #include #include #include diff --git a/ccan/tal/path/path.h b/ccan/tal/path/path.h index 65d539c1..5678fd1a 100644 --- a/ccan/tal/path/path.h +++ b/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. diff --git a/ccan/tal/str/str.c b/ccan/tal/str/str.c index 7adb9ef5..4b3b11aa 100644 --- a/ccan/tal/str/str.c +++ b/ccan/tal/str/str.c @@ -11,7 +11,6 @@ #include #include #include -#include char *tal_strdup(const tal_t *ctx, const char *p) { diff --git a/ccan/tal/str/str.h b/ccan/tal/str/str.h index 5147ca2d..ec853def 100644 --- a/ccan/tal/str/str.h +++ b/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 */ diff --git a/ccan/tal/tal.c b/ccan/tal/tal.c index 555dd133..331f7ea5 100644 --- a/ccan/tal/tal.c +++ b/ccan/tal/tal.c @@ -2,7 +2,6 @@ #include #include #include -#include #include #include #include diff --git a/ccan/tal/tal.h b/ccan/tal/tal.h index e525a01d..30c8e7bb 100644 --- a/ccan/tal/tal.h +++ b/ccan/tal/tal.h @@ -6,6 +6,7 @@ #include #include #include +#include #include #include #include @@ -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), diff --git a/ccan/tal/talloc/talloc.c b/ccan/tal/talloc/talloc.c index fbe9b384..ab96ff78 100644 --- a/ccan/tal/talloc/talloc.c +++ b/ccan/tal/talloc/talloc.c @@ -1,6 +1,5 @@ /* Licensed under LGPL - see LICENSE file for details */ #include -#include #include #include diff --git a/ccan/tal/talloc/talloc.h b/ccan/tal/talloc/talloc.h index 8dfb80e7..ea4de289 100644 --- a/ccan/tal/talloc/talloc.h +++ b/ccan/tal/talloc/talloc.h @@ -6,6 +6,7 @@ #include #include #include +#include #include #include #include -- 2.39.2