src/path.h

   1 /*
   2  * Copyright (C) 2009-2012 the libgit2 contributors
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_path_h__
   8 #define INCLUDE_path_h__
   9
  10 #include "common.h"
  11 #include "buffer.h"
  12 #include "vector.h"
  13
  14 /**
  15  * Path manipulation utils
  16  *
  17  * These are path utilities that munge paths without actually
  18  * looking at the real filesystem.
  19  */
  20
  21 /*
  22  * The dirname() function shall take a pointer to a character string
  23  * that contains a pathname, and return a pointer to a string that is a
  24  * pathname of the parent directory of that file. Trailing '/' characters
  25  * in the path are not counted as part of the path.
  26  *
  27  * If path does not contain a '/', then dirname() shall return a pointer to
  28  * the string ".". If path is a null pointer or points to an empty string,
  29  * dirname() shall return a pointer to the string "." .
  30  *
  31  * The `git_path_dirname` implementation is thread safe. The returned
  32  * string must be manually free'd.
  33  *
  34  * The `git_path_dirname_r` implementation writes the dirname to a `git_buf`
  35  * if the buffer pointer is not NULL.
  36  * It returns an error code < 0 if there is an allocation error, otherwise
  37  * the length of the dirname (which will be > 0).
  38  */
  39 extern char *git_path_dirname(const char *path);
  40 extern int git_path_dirname_r(git_buf *buffer, const char *path);
  41
  42 /*
  43  * This function returns the basename of the file, which is the last
  44  * part of its full name given by fname, with the drive letter and
  45  * leading directories stripped off. For example, the basename of
  46  * c:/foo/bar/file.ext is file.ext, and the basename of a:foo is foo.
  47  *
  48  * Trailing slashes and backslashes are significant: the basename of
  49  * c:/foo/bar/ is an empty string after the rightmost slash.
  50  *
  51  * The `git_path_basename` implementation is thread safe. The returned
  52  * string must be manually free'd.
  53  *
  54  * The `git_path_basename_r` implementation writes the basename to a `git_buf`.
  55  * It returns an error code < 0 if there is an allocation error, otherwise
  56  * the length of the basename (which will be >= 0).
  57  */
  58 extern char *git_path_basename(const char *path);
  59 extern int git_path_basename_r(git_buf *buffer, const char *path);
  60
  61 extern const char *git_path_topdir(const char *path);
  62
  63 /**
  64  * Find offset to root of path if path has one.
  65  *
  66  * This will return a number >= 0 which is the offset to the start of the
  67  * path, if the path is rooted (i.e. "/rooted/path" returns 0 and
  68  * "c:/windows/rooted/path" returns 2).  If the path is not rooted, this
  69  * returns < 0.
  70  */
  71 extern int git_path_root(const char *path);
  72
  73 /**
  74  * Ensure path has a trailing '/'.
  75  */
  76 extern int git_path_to_dir(git_buf *path);
  77
  78 /**
  79  * Ensure string has a trailing '/' if there is space for it.
  80  */
  81 extern void git_path_string_to_dir(char* path, size_t size);
  82
  83 /**
  84  * Taken from git.git; returns nonzero if the given path is "." or "..".
  85  */
  86 GIT_INLINE(int) git_path_is_dot_or_dotdot(const char *name)
  87 {
  88         return (name[0] == '.' &&
  89                           (name[1] == '\0' ||
  90                                 (name[1] == '.' && name[2] == '\0')));
  91 }
  92
  93 #ifdef GIT_WIN32
  94 GIT_INLINE(int) git_path_is_dot_or_dotdotW(const wchar_t *name)
  95 {
  96         return (name[0] == L'.' &&
  97                           (name[1] == L'\0' ||
  98                                 (name[1] == L'.' && name[2] == L'\0')));
  99 }
 100
 101 /**
 102  * Convert backslashes in path to forward slashes.
 103  */
 104 GIT_INLINE(void) git_path_mkposix(char *path)
 105 {
 106         while (*path) {
 107                 if (*path == '\\')
 108                         *path = '/';
 109
 110                 path++;
 111         }
 112 }
 113 #else
 114 #       define git_path_mkposix(p) /* blank */
 115 #endif
 116
 117 extern int git__percent_decode(git_buf *decoded_out, const char *input);
 118
 119 /**
 120  * Extract path from file:// URL.
 121  */
 122 extern int git_path_fromurl(git_buf *local_path_out, const char *file_url);
 123
 124
 125 /**
 126  * Path filesystem utils
 127  *
 128  * These are path utilities that actually access the filesystem.
 129  */
 130
 131 /**
 132  * Check if a file exists and can be accessed.
 133  * @return true or false
 134  */
 135 extern bool git_path_exists(const char *path);
 136
 137 /**
 138  * Check if the given path points to a directory.
 139  * @return true or false
 140  */
 141 extern bool git_path_isdir(const char *path);
 142
 143 /**
 144  * Check if the given path points to a regular file.
 145  * @return true or false
 146  */
 147 extern bool git_path_isfile(const char *path);
 148
 149 /**
 150  * Check if the given path is a directory, and is empty.
 151  */
 152 extern bool git_path_is_empty_dir(const char *path);
 153
 154 /**
 155  * Stat a file and/or link and set error if needed.
 156  */
 157 extern int git_path_lstat(const char *path, struct stat *st);
 158
 159 /**
 160  * Check if the parent directory contains the item.
 161  *
 162  * @param dir Directory to check.
 163  * @param item Item that might be in the directory.
 164  * @return 0 if item exists in directory, <0 otherwise.
 165  */
 166 extern bool git_path_contains(git_buf *dir, const char *item);
 167
 168 /**
 169  * Check if the given path contains the given subdirectory.
 170  *
 171  * @param parent Directory path that might contain subdir
 172  * @param subdir Subdirectory name to look for in parent
 173  * @param append_if_exists If true, then subdir will be appended to the parent path if it does exist
 174  * @return true if subdirectory exists, false otherwise.
 175  */
 176 extern bool git_path_contains_dir(git_buf *parent, const char *subdir);
 177
 178 /**
 179  * Check if the given path contains the given file.
 180  *
 181  * @param dir Directory path that might contain file
 182  * @param file File name to look for in parent
 183  * @param append_if_exists If true, then file will be appended to the path if it does exist
 184  * @return true if file exists, false otherwise.
 185  */
 186 extern bool git_path_contains_file(git_buf *dir, const char *file);
 187
 188 /**
 189  * Clean up path, prepending base if it is not already rooted.
 190  */
 191 extern int git_path_prettify(git_buf *path_out, const char *path, const char *base);
 192
 193 /**
 194  * Clean up path, prepending base if it is not already rooted and
 195  * appending a slash.
 196  */
 197 extern int git_path_prettify_dir(git_buf *path_out, const char *path, const char *base);
 198
 199 /**
 200  * Get a directory from a path.
 201  *
 202  * If path is a directory, this acts like `git_path_prettify_dir`
 203  * (cleaning up path and appending a '/').  If path is a normal file,
 204  * this prettifies it, then removed the filename a la dirname and
 205  * appends the trailing '/'.  If the path does not exist, it is
 206  * treated like a regular filename.
 207  */
 208 extern int git_path_find_dir(git_buf *dir, const char *path, const char *base);
 209
 210 /**
 211  * Resolve relative references within a path.
 212  *
 213  * This eliminates "./" and "../" relative references inside a path,
 214  * as well as condensing multiple slashes into single ones.  It will
 215  * not touch the path before the "ceiling" length.
 216  *
 217  * Additionally, this will recognize an "c:/" drive prefix or a "xyz://" URL
 218  * prefix and not touch that part of the path.
 219  */
 220 extern int git_path_resolve_relative(git_buf *path, size_t ceiling);
 221
 222 /**
 223  * Apply a relative path to base path.
 224  *
 225  * Note that the base path could be a filename or a URL and this
 226  * should still work.  The relative path is walked segment by segment
 227  * with three rules: series of slashes will be condensed to a single
 228  * slash, "." will be eaten with no change, and ".." will remove a
 229  * segment from the base path.
 230  */
 231 extern int git_path_apply_relative(git_buf *target, const char *relpath);
 232
 233 /**
 234  * Walk each directory entry, except '.' and '..', calling fn(state).
 235  *
 236  * @param pathbuf buffer the function reads the initial directory
 237  *              path from, and updates with each successive entry's name.
 238  * @param fn function to invoke with each entry. The first arg is
 239  *              the input state and the second arg is pathbuf. The function
 240  *              may modify the pathbuf, but only by appending new text.
 241  * @param state to pass to fn as the first arg.
 242  */
 243 extern int git_path_direach(
 244         git_buf *pathbuf,
 245         int (*fn)(void *, git_buf *),
 246         void *state);
 247
 248 /**
 249  * Sort function to order two paths.
 250  */
 251 extern int git_path_cmp(
 252         const char *name1, size_t len1, int isdir1,
 253         const char *name2, size_t len2, int isdir2);
 254
 255 /**
 256  * Invoke callback up path directory by directory until the ceiling is
 257  * reached (inclusive of a final call at the root_path).
 258  *
 259  * Returning anything other than 0 from the callback function
 260  * will stop the iteration and propogate the error to the caller.
 261  *
 262  * @param pathbuf Buffer the function reads the directory from and
 263  *              and updates with each successive name.
 264  * @param ceiling Prefix of path at which to stop walking up.  If NULL,
 265  *      this will walk all the way up to the root.  If not a prefix of
 266  *      pathbuf, the callback will be invoked a single time on the
 267  *      original input path.
 268  * @param fn Function to invoke on each path.  The first arg is the
 269  *              input satte and the second arg is the pathbuf.  The function
 270  *              should not modify the pathbuf.
 271  * @param state Passed to fn as the first ath.
 272  */
 273 extern int git_path_walk_up(
 274         git_buf *pathbuf,
 275         const char *ceiling,
 276         int (*fn)(void *state, git_buf *),
 277         void *state);
 278
 279 /**
 280  * Load all directory entries (except '.' and '..') into a vector.
 281  *
 282  * For cases where `git_path_direach()` is not appropriate, this
 283  * allows you to load the filenames in a directory into a vector
 284  * of strings. That vector can then be sorted, iterated, or whatever.
 285  * Remember to free alloc of the allocated strings when you are done.
 286  *
 287  * @param path The directory to read from.
 288  * @param prefix_len When inserting entries, the trailing part of path
 289  *              will be prefixed after this length.  I.e. given path "/a/b" and
 290  *              prefix_len 3, the entries will look like "b/e1", "b/e2", etc.
 291  * @param alloc_extra Extra bytes to add to each string allocation in
 292  *              case you want to append anything funny.
 293  * @param contents Vector to fill with directory entry names.
 294  */
 295 extern int git_path_dirload(
 296         const char *path,
 297         size_t prefix_len,
 298         size_t alloc_extra,
 299         git_vector *contents);
 300
 301
 302 typedef struct {
 303         struct stat st;
 304         size_t      path_len;
 305         char        path[GIT_FLEX_ARRAY];
 306 } git_path_with_stat;
 307
 308 extern int git_path_with_stat_cmp(const void *a, const void *b);
 309
 310 /**
 311  * Load all directory entries along with stat info into a vector.
 312  *
 313  * This is just like git_path_dirload except that each entry in the
 314  * vector is a git_path_with_stat structure that contains both the
 315  * path and the stat info, plus directories will have a / suffixed
 316  * to their path name.
 317  */
 318 extern int git_path_dirload_with_stat(
 319         const char *path,
 320         size_t prefix_len,
 321         git_vector *contents);
 322
 323 #endif