path.h 14.3 KB
Newer Older
Vicent Marti committed
1
/*
Edward Thomson committed
2
 * Copyright (C) the libgit2 contributors. All rights reserved.
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 "posix.h"
12
#include "buffer.h"
13
#include "vector.h"
Vicent Marti committed
14

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

Vicent Marti committed
22 23 24 25 26 27 28 29 30 31 32 33 34
/*
 * 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.
 *
35 36 37 38
 * 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
39 40
 */
extern char *git_path_dirname(const char *path);
41
extern int git_path_dirname_r(git_buf *buffer, const char *path);
Vicent Marti committed
42 43 44 45 46 47 48 49 50 51 52 53 54

/*
 * 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.
 *
55 56 57
 * 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
58 59
 */
extern char *git_path_basename(const char *path);
60
extern int git_path_basename_r(git_buf *buffer, const char *path);
Vicent Marti committed
61

62 63 64 65 66
/* 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
67 68
extern const char *git_path_topdir(const char *path);

69 70 71 72 73 74 75 76
/**
 * 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.
 */
77
extern int git_path_root(const char *path);
Vicent Marti committed
78

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

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

Ben Straub committed
89 90 91
/**
 * Taken from git.git; returns nonzero if the given path is "." or "..".
 */
92 93 94 95 96 97 98
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
99
#ifdef GIT_WIN32
100 101 102 103 104 105 106
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')));
}

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

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

123 124 125 126 127 128 129 130
/**
 * Check if string is a relative path (i.e. starts with "./" or "../")
 */
GIT_INLINE(int) git_path_is_relative(const char *p)
{
	return (p[0] == '.' && (p[1] == '/' || (p[1] == '.' && p[2] == '/')));
}

131 132 133 134 135 136 137 138
/**
 * Check if string is at end of path segment (i.e. looking at '/' or '\0')
 */
GIT_INLINE(int) git_path_at_end_of_segment(const char *p)
{
	return !*p || *p == '/';
}

139
extern int git__percent_decode(git_buf *decoded_out, const char *input);
140 141 142 143

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

146 147 148 149 150 151 152 153 154

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

/**
 * Check if a file exists and can be accessed.
155
 * @return true or false
156
 */
157
extern bool git_path_exists(const char *path);
158 159 160

/**
 * Check if the given path points to a directory.
161
 * @return true or false
162
 */
163
extern bool git_path_isdir(const char *path);
164

165
/**
166
 * Check if the given path points to a regular file.
167
 * @return true or false
168
 */
169
extern bool git_path_isfile(const char *path);
170 171

/**
Ben Straub committed
172 173 174 175 176
 * Check if the given path is a directory, and is empty.
 */
extern bool git_path_is_empty_dir(const char *path);

/**
177 178 179 180 181
 * Stat a file and/or link and set error if needed.
 */
extern int git_path_lstat(const char *path, struct stat *st);

/**
182 183 184 185
 * Check if the parent directory contains the item.
 *
 * @param dir Directory to check.
 * @param item Item that might be in the directory.
186
 * @return 0 if item exists in directory, <0 otherwise.
187
 */
188
extern bool git_path_contains(git_buf *dir, const char *item);
189 190

/**
191 192 193 194
 * 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
195
 * @return true if subdirectory exists, false otherwise.
196
 */
197
extern bool git_path_contains_dir(git_buf *parent, const char *subdir);
198 199

/**
200 201 202 203 204 205 206 207 208 209 210
 * Make the path relative to the given parent path.
 *
 * @param path The path to make relative
 * @param parent The parent path to make path relative to
 * @return 0 if path was made relative, GIT_ENOTFOUND
 *         if there was not common root between the paths,
 *         or <0.
 */
extern int git_path_make_relative(git_buf *path, const char *parent);

/**
211 212 213 214
 * 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
215
 * @return true if file exists, false otherwise.
216
 */
217
extern bool git_path_contains_file(git_buf *dir, const char *file);
218 219

/**
220 221 222 223 224 225 226 227 228
 * 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);

/**
229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
 * 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);

/**
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
 * 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);

273 274 275 276 277
enum {
	GIT_PATH_DIR_IGNORE_CASE = (1u << 0),
	GIT_PATH_DIR_PRECOMPOSE_UNICODE = (1u << 1),
};

278
/**
279 280
 * Walk each directory entry, except '.' and '..', calling fn(state).
 *
281
 * @param pathbuf Buffer the function reads the initial directory
282
 * 		path from, and updates with each successive entry's name.
283 284 285
 * @param flags Combination of GIT_PATH_DIR flags.
 * @param callback Callback for each entry. Passed the `payload` and each
 *		successive path inside the directory as a full path.  This may
286 287
 *		safely append text to the pathbuf if needed.  Return non-zero to
 *		cancel iteration (and return value will be propagated back).
288
 * @param payload Passed to callback as first argument.
289
 * @return 0 on success or error code from OS error or from callback
290 291 292
 */
extern int git_path_direach(
	git_buf *pathbuf,
293 294 295
	uint32_t flags,
	int (*callback)(void *payload, git_buf *path),
	void *payload);
296 297

/**
298
 * Sort function to order two paths
299 300
 */
extern int git_path_cmp(
301
	const char *name1, size_t len1, int isdir1,
302 303
	const char *name2, size_t len2, int isdir2,
	int (*compare)(const char *, const char *, size_t));
304

305 306 307 308
/**
 * Invoke callback up path directory by directory until the ceiling is
 * reached (inclusive of a final call at the root_path).
 *
309
 * Returning anything other than 0 from the callback function
310
 * will stop the iteration and propogate the error to the caller.
311
 *
312 313 314
 * @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,
315 316 317 318 319
 *		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 callback Function to invoke on each path.  Passed the `payload`
 *		and the buffer containing the current path.  The path should not
320
 *		be modified in any way. Return non-zero to stop iteration.
321
 * @param state Passed to fn as the first ath.
322
 */
323
extern int git_path_walk_up(
324 325
	git_buf *pathbuf,
	const char *ceiling,
326
	int (*callback)(void *payload, const char *path),
327
	void *payload);
328

329 330 331 332 333 334 335 336 337 338 339 340 341 342
/**
 * 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.
343
 * @param flags Combination of GIT_PATH_DIR flags.
344 345 346 347 348 349
 * @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,
350
	uint32_t flags,
351 352
	git_vector *contents);

353 354 355 356 357 358 359 360

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);
361
extern int git_path_with_stat_cmp_icase(const void *a, const void *b);
362 363 364 365

/**
 * Load all directory entries along with stat info into a vector.
 *
366 367 368 369 370 371 372 373 374 375 376
 * This adds four things on top of plain `git_path_dirload`:
 *
 * 1. Each entry in the vector is a `git_path_with_stat` struct that
 *    contains both the path and the stat info
 * 2. The entries will be sorted alphabetically
 * 3. Entries that are directories will be suffixed with a '/'
 * 4. Optionally, you can be a start and end prefix and only elements
 *    after the start and before the end (inclusively) will be stat'ed.
 *
 * @param path The directory to read from
 * @param prefix_len The trailing part of path to prefix to entry paths
377
 * @param flags GIT_PATH_DIR flags from above
378 379 380
 * @param start_stat As optimization, only stat values after this prefix
 * @param end_stat As optimization, only stat values before this prefix
 * @param contents Vector to fill with git_path_with_stat structures
381 382 383 384
 */
extern int git_path_dirload_with_stat(
	const char *path,
	size_t prefix_len,
385
	uint32_t flags,
386 387
	const char *start_stat,
	const char *end_stat,
388 389
	git_vector *contents);

390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417
enum { GIT_PATH_NOTEQUAL = 0, GIT_PATH_EQUAL = 1, GIT_PATH_PREFIX = 2 };

/*
 * Determines if a path is equal to or potentially a child of another.
 * @param parent The possible parent
 * @param child The possible child
 */
GIT_INLINE(int) git_path_equal_or_prefixed(
	const char *parent,
	const char *child)
{
	const char *p = parent, *c = child;

	while (*p && *c) {
		if (*p++ != *c++)
			return GIT_PATH_NOTEQUAL;
	}

	if (*p != '\0')
		return GIT_PATH_NOTEQUAL;
	if (*c == '\0')
		return GIT_PATH_EQUAL;
	if (*c == '/')
		return GIT_PATH_PREFIX;

	return GIT_PATH_NOTEQUAL;
}

418 419 420 421
/* translate errno to libgit2 error code and set error message */
extern int git_path_set_error(
	int errno_value, const char *path, const char *action);

422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458
/* check if non-ascii characters are present in filename */
extern bool git_path_has_non_ascii(const char *path, size_t pathlen);

#define GIT_PATH_REPO_ENCODING "UTF-8"

#ifdef __APPLE__
#define GIT_PATH_NATIVE_ENCODING "UTF-8-MAC"
#else
#define GIT_PATH_NATIVE_ENCODING "UTF-8"
#endif

#ifdef GIT_USE_ICONV

#include <iconv.h>

typedef struct {
	iconv_t map;
	git_buf buf;
} git_path_iconv_t;

#define GIT_PATH_ICONV_INIT { (iconv_t)-1, GIT_BUF_INIT }

/* Init iconv data for converting decomposed UTF-8 to precomposed */
extern int git_path_iconv_init_precompose(git_path_iconv_t *ic);

/* Clear allocated iconv data */
extern void git_path_iconv_clear(git_path_iconv_t *ic);

/*
 * Rewrite `in` buffer using iconv map if necessary, replacing `in`
 * pointer internal iconv buffer if rewrite happened.  The `in` pointer
 * will be left unchanged if no rewrite was needed.
 */
extern int git_path_iconv(git_path_iconv_t *ic, char **in, size_t *inlen);

#endif /* GIT_USE_ICONV */

459 460
extern bool git_path_does_fs_decompose_unicode(const char *root);

461
/* Used for paths to repositories on the filesystem */
462
extern bool git_path_is_local_file_url(const char *file_url);
463 464
extern int git_path_from_url_or_path(git_buf *local_path_out, const char *url_or_path);

Vicent Marti committed
465
#endif