include/got_path.h

   1 /*
   2  * Copyright (c) 2018, 2019 Stefan Sperling <stsp@openbsd.org>
   3  *
   4  * Permission to use, copy, modify, and distribute this software for any
   5  * purpose with or without fee is hereby granted, provided that the above
   6  * copyright notice and this permission notice appear in all copies.
   7  *
   8  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 /* Utilities for dealing with filesystem paths. */
  18
  19 #define GOT_DEFAULT_PACK_MODE   (S_IFREG | \
  20         S_IRUSR | S_IRGRP | S_IROTH)
  21 #define GOT_DEFAULT_FILE_MODE   (S_IFREG | \
  22         S_IRUSR|S_IWUSR | S_IRGRP | S_IROTH)
  23 #define GOT_DEFAULT_DIR_MODE    (S_IFDIR | \
  24         S_IRWXU | S_IRGRP|S_IXGRP | S_IROTH|S_IXOTH)
  25
  26 struct dirent;
  27
  28 /* Determine whether a path is an absolute path. */
  29 int got_path_is_absolute(const char *);
  30
  31 /*
  32  * Canonicalize absolute paths by removing redundant path separators
  33  * and resolving references to parent directories ("/../").
  34  * Relative paths are copied from input to buf as-is.
  35  */
  36 const struct got_error *got_canonpath(const char *, char *, size_t);
  37
  38 /*
  39  * Get child part of two absolute paths. The second path must equal the first
  40  * path up to some path component, and must be longer than the first path.
  41  * The result is allocated with malloc(3).
  42  */
  43 const struct got_error *got_path_skip_common_ancestor(char **, const char *,
  44     const char *);
  45
  46 /*
  47  * Remove leading components from path.  It's an error to strip more
  48  * component than present.  The result is allocated dynamically.
  49  */
  50 const struct got_error *got_path_strip(char **, const char *, int);
  51
  52 /* Determine whether a path points to the root directory "/" . */
  53 int got_path_is_root_dir(const char *);
  54
  55 /* Determine whether a path is a path-wise child of another path. */
  56 int got_path_is_child(const char *, const char *, size_t);
  57
  58 /*
  59  * Like strcmp() but orders children in subdirectories directly after
  60  * their parents. String lengths must also be passed in.
  61  */
  62 int got_path_cmp(const char *, const char *, size_t, size_t);
  63
  64 /*
  65  * Path lists allow for predictable concurrent iteration over multiple lists
  66  * of paths obtained from disparate sources which don't all provide the same
  67  * ordering guarantees (e.g. git trees, file index, and on-disk directories).
  68  */
  69 struct got_pathlist_entry {
  70         TAILQ_ENTRY(got_pathlist_entry) entry;
  71         const char *path;
  72         size_t path_len;
  73         void *data; /* data pointer provided to got_pathlist_insert() */
  74 };
  75 TAILQ_HEAD(got_pathlist_head, got_pathlist_entry);
  76
  77 /*
  78  * Insert a path into the list of paths in a predictable order.
  79  * The caller should already have initialized the list head. This list stores
  80  * the pointer to the path as-is, i.e. the path is not copied internally and
  81  * must remain available until the list is freed with got_pathlist_free().
  82  * If the first argument is not NULL, set it to a pointer to the newly inserted
  83  * element, or to a NULL pointer in case the path was already on the list.
  84  */
  85 const struct got_error *got_pathlist_insert(struct got_pathlist_entry **,
  86     struct got_pathlist_head *, const char *, void *);
  87
  88 /*
  89  * Append a path to the list of paths.
  90  * The caller should already have initialized the list head. This list stores
  91  * the pointer to the path as-is, i.e. the path is not copied internally and
  92  * must remain available until the list is freed with got_pathlist_free().
  93  */
  94 const struct got_error *got_pathlist_append(struct got_pathlist_head *,
  95     const char *, void *);
  96
  97 /* Flags passed to got_pathlist_free() to control which pointers are freed. */
  98 #define GOT_PATHLIST_FREE_NONE  0         /* pathlist entry only */
  99 #define GOT_PATHLIST_FREE_PATH  (1 << 0)  /* entry and path pointer */
 100 #define GOT_PATHLIST_FREE_DATA  (1 << 1)  /* entry and data pointer */
 101 #define GOT_PATHLIST_FREE_ALL   (GOT_PATHLIST_FREE_PATH|GOT_PATHLIST_FREE_DATA)
 102
 103 /* Free resources allocated for a path list. */
 104 void got_pathlist_free(struct got_pathlist_head *, int);
 105
 106 /* Attempt to create a directory at a given path. */
 107 const struct got_error *got_path_mkdir(const char *);
 108
 109 /* Determine whether a directory has no files or directories in it. */
 110 int got_path_dir_is_empty(const char *);
 111
 112 /*
 113  * dirname(3) with error handling, dynamically allocated result, and
 114  * unmodified input.
 115  */
 116 const struct got_error *got_path_dirname(char **, const char *);
 117
 118 /*
 119  * Obtain the file type of a given directory entry.
 120  *
 121  * If the entry has some type other than DT_UNKNOWN, resolve to this type.
 122  *
 123  * Otherwise, attempt to resolve the type of a DT_UNKNOWN directory
 124  * entry with lstat(2), though the result may still be DT_UNKNOWN.
 125  * This is a fallback to accommodate filesystems which do not provide
 126  * directory entry type information.
 127  * DT_UNKNOWN directory entries occur on NFS mounts without "readdir plus" RPC.
 128  */
 129 const struct got_error *got_path_dirent_type(int *, const char *,
 130     struct dirent *);
 131
 132 /* basename(3) with dynamically allocated result and unmodified input. */
 133 const struct got_error *got_path_basename(char **, const char *);
 134
 135 /* Strip trailing slashes from a path; path will be modified in-place. */
 136 void got_path_strip_trailing_slashes(char *);
 137
 138 /* Look up the absolute path of a program in $PATH */
 139 const struct got_error *got_path_find_prog(char **, const char *);
 140
 141 /* Create a new file at a specified path, with optional content. */
 142 const struct got_error *got_path_create_file(const char *, const char *);
 143
 144 /*
 145  * Attempt to move an existing file to a new path, creating missing parent
 146  * directories at the destination path if necessary.
 147  * (Cross-mount-point moves are not yet implemented.)
 148  */
 149 const struct got_error *got_path_move_file(const char *, const char *);