path.h 10.6 KB
Newer Older
Vicent Marti committed
1
/*
schu committed
2
 * Copyright (C) 2009-2012 the libgit2 contributors
Vicent Marti committed
3 4 5
 *
 * This file is part of libgit2, distributed under the GNU GPL v2 with
 * a Linking Exception. For full terms see the included COPYING file.
Vicent Marti committed
6 7 8 9 10
 */
#ifndef INCLUDE_path_h__
#define INCLUDE_path_h__

#include "common.h"
11
#include "buffer.h"
12
#include "vector.h"
Vicent Marti committed
13

14 15 16 17 18 19 20
/**
 * Path manipulation utils
 *
 * These are path utilities that munge paths without actually
 * looking at the real filesystem.
 */

Vicent Marti committed
21 22 23 24 25 26 27 28 29 30 31 32 33
/*
 * The dirname() function shall take a pointer to a character string
 * that contains a pathname, and return a pointer to a string that is a
 * pathname of the parent directory of that file. Trailing '/' characters
 * in the path are not counted as part of the path.
 *
 * If path does not contain a '/', then dirname() shall return a pointer to
 * the string ".". If path is a null pointer or points to an empty string,
 * dirname() shall return a pointer to the string "." .
 *
 * The `git_path_dirname` implementation is thread safe. The returned
 * string must be manually free'd.
 *
34 35 36 37
 * The `git_path_dirname_r` implementation writes the dirname to a `git_buf`
 * if the buffer pointer is not NULL.
 * It returns an error code < 0 if there is an allocation error, otherwise
 * the length of the dirname (which will be > 0).
Vicent Marti committed
38 39
 */
extern char *git_path_dirname(const char *path);
40
extern int git_path_dirname_r(git_buf *buffer, const char *path);
Vicent Marti committed
41 42 43 44 45 46 47 48 49 50 51 52 53

/*
 * This function returns the basename of the file, which is the last
 * part of its full name given by fname, with the drive letter and
 * leading directories stripped off. For example, the basename of
 * c:/foo/bar/file.ext is file.ext, and the basename of a:foo is foo.
 *
 * Trailing slashes and backslashes are significant: the basename of
 * c:/foo/bar/ is an empty string after the rightmost slash.
 *
 * The `git_path_basename` implementation is thread safe. The returned
 * string must be manually free'd.
 *
54 55 56
 * The `git_path_basename_r` implementation writes the basename to a `git_buf`.
 * It returns an error code < 0 if there is an allocation error, otherwise
 * the length of the basename (which will be >= 0).
Vicent Marti committed
57 58
 */
extern char *git_path_basename(const char *path);
59
extern int git_path_basename_r(git_buf *buffer, const char *path);
Vicent Marti committed
60

61 62 63 64 65
/* Return the offset of the start of the basename.  Unlike the other
 * basename functions, this returns 0 if the path is empty.
 */
extern size_t git_path_basename_offset(git_buf *buffer);

Vicent Marti committed
66 67
extern const char *git_path_topdir(const char *path);

68 69 70 71 72 73 74 75
/**
 * Find offset to root of path if path has one.
 *
 * This will return a number >= 0 which is the offset to the start of the
 * path, if the path is rooted (i.e. "/rooted/path" returns 0 and
 * "c:/windows/rooted/path" returns 2).  If the path is not rooted, this
 * returns < 0.
 */
76
extern int git_path_root(const char *path);
Vicent Marti committed
77

78 79 80
/**
 * Ensure path has a trailing '/'.
 */
81
extern int git_path_to_dir(git_buf *path);
82 83 84 85

/**
 * Ensure string has a trailing '/' if there is space for it.
 */
86
extern void git_path_string_to_dir(char* path, size_t size);
87

Ben Straub committed
88 89 90
/**
 * Taken from git.git; returns nonzero if the given path is "." or "..".
 */
91 92 93 94 95 96 97
GIT_INLINE(int) git_path_is_dot_or_dotdot(const char *name)
{
	return (name[0] == '.' &&
			  (name[1] == '\0' ||
				(name[1] == '.' && name[2] == '\0')));
}

Vicent Marti committed
98
#ifdef GIT_WIN32
99 100 101 102 103 104 105
GIT_INLINE(int) git_path_is_dot_or_dotdotW(const wchar_t *name)
{
	return (name[0] == L'.' &&
			  (name[1] == L'\0' ||
				(name[1] == L'.' && name[2] == L'\0')));
}

106 107 108
/**
 * Convert backslashes in path to forward slashes.
 */
Vicent Marti committed
109 110 111 112 113 114 115 116 117 118 119 120 121
GIT_INLINE(void) git_path_mkposix(char *path)
{
	while (*path) {
		if (*path == '\\')
			*path = '/';

		path++;
	}
}
#else
#	define git_path_mkposix(p) /* blank */
#endif

122
extern int git__percent_decode(git_buf *decoded_out, const char *input);
123 124 125 126

/**
 * Extract path from file:// URL.
 */
nulltoken committed
127
extern int git_path_fromurl(git_buf *local_path_out, const char *file_url);
128

129 130 131 132 133 134 135 136 137

/**
 * Path filesystem utils
 *
 * These are path utilities that actually access the filesystem.
 */

/**
 * Check if a file exists and can be accessed.
138
 * @return true or false
139
 */
140
extern bool git_path_exists(const char *path);
141 142 143

/**
 * Check if the given path points to a directory.
144
 * @return true or false
145
 */
146
extern bool git_path_isdir(const char *path);
147

148
/**
149
 * Check if the given path points to a regular file.
150
 * @return true or false
151
 */
152
extern bool git_path_isfile(const char *path);
153 154

/**
Ben Straub committed
155 156 157 158 159
 * Check if the given path is a directory, and is empty.
 */
extern bool git_path_is_empty_dir(const char *path);

/**
160 161 162 163 164
 * Stat a file and/or link and set error if needed.
 */
extern int git_path_lstat(const char *path, struct stat *st);

/**
165 166 167 168
 * Check if the parent directory contains the item.
 *
 * @param dir Directory to check.
 * @param item Item that might be in the directory.
169
 * @return 0 if item exists in directory, <0 otherwise.
170
 */
171
extern bool git_path_contains(git_buf *dir, const char *item);
172 173

/**
174 175 176 177
 * Check if the given path contains the given subdirectory.
 *
 * @param parent Directory path that might contain subdir
 * @param subdir Subdirectory name to look for in parent
178 179
 * @param append_if_exists If true, then subdir will be appended to the parent path if it does exist
 * @return true if subdirectory exists, false otherwise.
180
 */
181
extern bool git_path_contains_dir(git_buf *parent, const char *subdir);
182 183 184 185 186 187

/**
 * Check if the given path contains the given file.
 *
 * @param dir Directory path that might contain file
 * @param file File name to look for in parent
188 189
 * @param append_if_exists If true, then file will be appended to the path if it does exist
 * @return true if file exists, false otherwise.
190
 */
191
extern bool git_path_contains_file(git_buf *dir, const char *file);
192 193

/**
194 195 196 197 198 199 200 201 202
 * Prepend base to unrooted path or just copy path over.
 *
 * This will optionally return the index into the path where the "root"
 * is, either the end of the base directory prefix or the path root.
 */
extern int git_path_join_unrooted(
	git_buf *path_out, const char *path, const char *base, ssize_t *root_at);

/**
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224
 * Clean up path, prepending base if it is not already rooted.
 */
extern int git_path_prettify(git_buf *path_out, const char *path, const char *base);

/**
 * Clean up path, prepending base if it is not already rooted and
 * appending a slash.
 */
extern int git_path_prettify_dir(git_buf *path_out, const char *path, const char *base);

/**
 * Get a directory from a path.
 *
 * If path is a directory, this acts like `git_path_prettify_dir`
 * (cleaning up path and appending a '/').  If path is a normal file,
 * this prettifies it, then removed the filename a la dirname and
 * appends the trailing '/'.  If the path does not exist, it is
 * treated like a regular filename.
 */
extern int git_path_find_dir(git_buf *dir, const char *path, const char *base);

/**
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247
 * Resolve relative references within a path.
 *
 * This eliminates "./" and "../" relative references inside a path,
 * as well as condensing multiple slashes into single ones.  It will
 * not touch the path before the "ceiling" length.
 *
 * Additionally, this will recognize an "c:/" drive prefix or a "xyz://" URL
 * prefix and not touch that part of the path.
 */
extern int git_path_resolve_relative(git_buf *path, size_t ceiling);

/**
 * Apply a relative path to base path.
 *
 * Note that the base path could be a filename or a URL and this
 * should still work.  The relative path is walked segment by segment
 * with three rules: series of slashes will be condensed to a single
 * slash, "." will be eaten with no change, and ".." will remove a
 * segment from the base path.
 */
extern int git_path_apply_relative(git_buf *target, const char *relpath);

/**
248 249 250 251 252 253 254 255
 * Walk each directory entry, except '.' and '..', calling fn(state).
 *
 * @param pathbuf buffer the function reads the initial directory
 * 		path from, and updates with each successive entry's name.
 * @param fn function to invoke with each entry. The first arg is
 *		the input state and the second arg is pathbuf. The function
 *		may modify the pathbuf, but only by appending new text.
 * @param state to pass to fn as the first arg.
256
 * @return 0 on success, GIT_EUSER on non-zero callback, or error code
257 258 259 260 261 262 263 264 265 266
 */
extern int git_path_direach(
	git_buf *pathbuf,
	int (*fn)(void *, git_buf *),
	void *state);

/**
 * Sort function to order two paths.
 */
extern int git_path_cmp(
267 268
	const char *name1, size_t len1, int isdir1,
	const char *name2, size_t len2, int isdir2);
269 270 271 272 273

/**
 * Invoke callback up path directory by directory until the ceiling is
 * reached (inclusive of a final call at the root_path).
 *
274
 * Returning anything other than 0 from the callback function
275
 * will stop the iteration and propogate the error to the caller.
276
 *
277 278 279 280 281 282 283 284 285 286
 * @param pathbuf Buffer the function reads the directory from and
 *		and updates with each successive name.
 * @param ceiling Prefix of path at which to stop walking up.  If NULL,
 *      this will walk all the way up to the root.  If not a prefix of
 *      pathbuf, the callback will be invoked a single time on the
 *      original input path.
 * @param fn Function to invoke on each path.  The first arg is the
 *		input satte and the second arg is the pathbuf.  The function
 *		should not modify the pathbuf.
 * @param state Passed to fn as the first ath.
287
 */
288
extern int git_path_walk_up(
289 290 291 292
	git_buf *pathbuf,
	const char *ceiling,
	int (*fn)(void *state, git_buf *),
	void *state);
293

294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315
/**
 * Load all directory entries (except '.' and '..') into a vector.
 *
 * For cases where `git_path_direach()` is not appropriate, this
 * allows you to load the filenames in a directory into a vector
 * of strings. That vector can then be sorted, iterated, or whatever.
 * Remember to free alloc of the allocated strings when you are done.
 *
 * @param path The directory to read from.
 * @param prefix_len When inserting entries, the trailing part of path
 * 		will be prefixed after this length.  I.e. given path "/a/b" and
 * 		prefix_len 3, the entries will look like "b/e1", "b/e2", etc.
 * @param alloc_extra Extra bytes to add to each string allocation in
 * 		case you want to append anything funny.
 * @param contents Vector to fill with directory entry names.
 */
extern int git_path_dirload(
	const char *path,
	size_t prefix_len,
	size_t alloc_extra,
	git_vector *contents);

316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337

typedef struct {
	struct stat st;
	size_t      path_len;
	char        path[GIT_FLEX_ARRAY];
} git_path_with_stat;

extern int git_path_with_stat_cmp(const void *a, const void *b);

/**
 * Load all directory entries along with stat info into a vector.
 *
 * This is just like git_path_dirload except that each entry in the
 * vector is a git_path_with_stat structure that contains both the
 * path and the stat info, plus directories will have a / suffixed
 * to their path name.
 */
extern int git_path_dirload_with_stat(
	const char *path,
	size_t prefix_len,
	git_vector *contents);

Vicent Marti committed
338
#endif