git.ozlabs.org Git - ccan/blob - 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);
  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);
  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);
  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, const char *a);
  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);
  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, const char *fromdir, const char *to);
  87
  88 /**
  89  * path_basename - get trailing filename part of path
  90  * @ctx: the context to tal the result from
  91  * @path: the path (can be take())
  92  *
  93  * This follows SUSv2:
  94  *    path         dirname    basename
  95  *    "/usr/lib"    "/usr"    "lib"
  96  *     "/usr/"       "/"       "usr"
  97  *     "usr"         "."       "usr"
  98  *     "/"           "/"       "/"
  99  *     "."           "."       "."
 100  *     ".."          "."       ".."
 101  *
 102  * See Also:
 103  *      path_dirname()
 104  */
 105 char *path_basename(const tal_t *ctx, const char *path);
 106
 107 /**
 108  * path_dirname - get the directory part of path
 109  * @ctx: the context to tal the result from.
 110  * @path: the path (can be take())
 111  *
 112  * This follows SUSv2.
 113  *
 114  * See Also:
 115  *      path_basename()
 116  */
 117 char *path_dirname(const tal_t *ctx, const char *path);
 118
 119 /**
 120  * path_is_abs - is a path absolute?
 121  * @path: the path to examine.
 122  */
 123 bool path_is_abs(const char *path);
 124
 125 /**
 126  * path_is_file - is a path an existing file (or long to one)?
 127  * @path: the path to examine.
 128  */
 129 bool path_is_file(const char *path);
 130
 131 /**
 132  * path_is_file - is a path an existing directory (or long to one)?
 133  * @path: the path to examine.
 134  */
 135 bool path_is_dir(const char *path);
 136
 137 /**
 138  * path_split - split a path into its pathname components
 139  * @ctx: the context to tal the result from
 140  * @path: the path (can be take())
 141  *
 142  * This returns the sections of a path, such that joining them with /
 143  * will restore the original path.  This means that the resulting
 144  * strings will never contain / unless the input path was entirely one
 145  * or more "/" characters.
 146  *
 147  * The final char * in the array will be NULL.
 148  *
 149  * See Also:
 150  *      strjoin()
 151  */
 152 char **path_split(const tal_t *ctx, const char *path);
 153
 154 /**
 155  * path_ext_off - get offset of the extension within a pathname.
 156  * @path: the path
 157  *
 158  * This returns the offset of the final . in the pathname (ie.
 159  * path[path_ext_off(path)] == '.') or the length of the string
 160  * if there is no extension.
 161  *
 162  * Note that if the only . in the basename is at the start
 163  * (eg. /home/person/.bashrc), that is not considered an extension!
 164  */
 165 size_t path_ext_off(const char *path);
 166
 167 #endif /* CCAN_PATH_H */