take, tal, tal/path, tal/str, tal/talloc: annotate APIs with TAKES.
[ccan] / ccan / tal / path / path.h
1 /* Licensed under BSD-MIT - see LICENSE file for details */
2 #ifndef CCAN_PATH_H
3 #define CCAN_PATH_H
4 #include <ccan/tal/tal.h>
5 #include <stdbool.h>
6
7 /**
8  * path_cwd - get current directory.
9  * @ctx: the context to tal from
10  *
11  * Returns NULL and sets errno on error.
12  */
13 char *path_cwd(const tal_t *ctx);
14
15 /**
16  * path_readlink - get a symbolic link contents
17  * @ctx: the context to tal the result from
18  * @link: the link to read (can be take())
19  *
20  * Returns NULL and sets errno on error, otherwise returns nul-terminated
21  * link contents.
22  */
23 char *path_readlink(const tal_t *ctx, const char *link TAKES);
24
25 /**
26  * path_canon - return the canonical absolute pathname.
27  * @ctx: the context to tal the result from.
28  * @a: path to canonicalize (can be take())
29  *
30  * Returns NULL and sets errno on error, otherwise returns an absolute
31  * path with no symbolic links and no extra separators (ie. as per
32  * realpath).
33  */
34 char *path_canon(const tal_t *ctx, const char *a TAKES);
35
36 /**
37  * path_simplify - remove double-/, ./ and some ../, plus trailing /.
38  * @ctx: the context to tal the result from
39  * @a: path to simplify (can be take())
40  *
41  * Unlike path_canon(), this routine does not convert a path to absolute
42  * terms or remove symlinks, but it does neaten it by removing extraneous
43  * parts.
44  */
45 char *path_simplify(const tal_t *ctx, const char *a TAKES);
46
47 /**
48  * path_join - attach one path to another.
49  * @ctx: the context to tal the result from
50  * @base: the path to start at (can be take())
51  * @a: the path to head from there (can be take())
52  *
53  * If @a is an absolute path, return a copy of it.  Otherwise, attach
54  * @a to @base.
55  */
56 char *path_join(const tal_t *ctx, const char *base TAKES, const char *a TAKES);
57
58 /**
59  * path_pushd - save old dir and change to a new one.
60  * @ctx: the context to tal the result from
61  * @dir: the directory to return to (can be take())
62  */
63 struct path_pushd *path_pushd(const tal_t *ctx, const char *dir TAKES);
64
65 /**
66  * path_popd - return to old, path_pushd dir.
67  * @olddir: the return from a previous path_pushd.
68  *
69  * Returns false and sets errno if it fails.
70  */
71 bool path_popd(struct path_pushd *olddir);
72
73 /**
74  * path_rel - get relative path from a to b.
75  * @ctx: the context to tal the result from.
76  * @fromdir: the starting location (can be take())
77  * @to: the destination location (can be take())
78  *
79  * This returns a relative path which leads from @fromdir (assumed to be a
80  * directory) to @to.  If @ctx it TAL_TAKE, frees both @fromdir and @to.
81  *
82  * Example:
83  *      char *path = path_rel(NULL, "/tmp", "/");
84  *      assert(strcmp(path, "..") == 0);
85  */
86 char *path_rel(const tal_t *ctx,
87                const char *fromdir TAKES, const char *to TAKES);
88
89 /**
90  * path_basename - get trailing filename part of path
91  * @ctx: the context to tal the result from
92  * @path: the path (can be take())
93  *
94  * This follows SUSv2:
95  *    path         dirname    basename
96  *    "/usr/lib"    "/usr"    "lib"
97  *     "/usr/"       "/"       "usr"
98  *     "usr"         "."       "usr"
99  *     "/"           "/"       "/"
100  *     "."           "."       "."
101  *     ".."          "."       ".."
102  *
103  * See Also:
104  *      path_dirname()
105  */
106 char *path_basename(const tal_t *ctx, const char *path TAKES);
107
108 /**
109  * path_dirname - get the directory part of path
110  * @ctx: the context to tal the result from.
111  * @path: the path (can be take())
112  *
113  * This follows SUSv2.
114  *
115  * See Also:
116  *      path_basename()
117  */
118 char *path_dirname(const tal_t *ctx, const char *path TAKES);
119
120 /**
121  * path_is_abs - is a path absolute?
122  * @path: the path to examine.
123  */
124 bool path_is_abs(const char *path);
125
126 /**
127  * path_is_file - is a path an existing file (or long to one)?
128  * @path: the path to examine.
129  */
130 bool path_is_file(const char *path);
131
132 /**
133  * path_is_file - is a path an existing directory (or long to one)?
134  * @path: the path to examine.
135  */
136 bool path_is_dir(const char *path);
137
138 /**
139  * path_split - split a path into its pathname components
140  * @ctx: the context to tal the result from
141  * @path: the path (can be take())
142  *
143  * This returns the sections of a path, such that joining them with /
144  * will restore the original path.  This means that the resulting
145  * strings will never contain / unless the input path was entirely one
146  * or more "/" characters.
147  *
148  * The final char * in the array will be NULL.
149  *
150  * See Also:
151  *      strjoin()
152  */
153 char **path_split(const tal_t *ctx, const char *path TAKES);
154
155 /**
156  * path_ext_off - get offset of the extension within a pathname.
157  * @path: the path
158  *
159  * This returns the offset of the final . in the pathname (ie.
160  * path[path_ext_off(path)] == '.') or the length of the string
161  * if there is no extension.
162  *
163  * Note that if the only . in the basename is at the start
164  * (eg. /home/person/.bashrc), that is not considered an extension!
165  */
166 size_t path_ext_off(const char *path);
167
168 #endif /* CCAN_PATH_H */