path.h 19.1 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

12
#include "posix.h"
13
#include "buffer.h"
14
#include "vector.h"
Vicent Marti committed
15

16 17
#include "git2/sys/path.h"

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

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

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

65 66 67 68 69
/* 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
70 71
extern const char *git_path_topdir(const char *path);

72 73 74 75 76 77
/**
 * 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
78
 * returns -1.
79
 */
80
extern int git_path_root(const char *path);
Vicent Marti committed
81

82 83 84
/**
 * Ensure path has a trailing '/'.
 */
85
extern int git_path_to_dir(git_buf *path);
86 87 88 89

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

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

110 111 112
#define git_path_is_absolute(p) \
	(git__isalpha((p)[0]) && (p)[1] == ':' && ((p)[2] == '\\' || (p)[2] == '/'))

113 114 115
#define git_path_is_dirsep(p) \
	((p) == '/' || (p) == '\\')

116 117 118
/**
 * Convert backslashes in path to forward slashes.
 */
Vicent Marti committed
119 120 121 122 123 124 125 126 127 128 129
GIT_INLINE(void) git_path_mkposix(char *path)
{
	while (*path) {
		if (*path == '\\')
			*path = '/';

		path++;
	}
}
#else
#	define git_path_mkposix(p) /* blank */
130 131 132 133

#define git_path_is_absolute(p) \
	((p)[0] == '/')

134 135 136
#define git_path_is_dirsep(p) \
	((p) == '/')

Vicent Marti committed
137 138
#endif

139 140 141 142 143 144 145 146
/**
 * 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] == '/')));
}

147 148 149 150 151 152 153 154
/**
 * 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 == '/';
}

155
extern int git__percent_decode(git_buf *decoded_out, const char *input);
156 157 158 159

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

162 163 164 165 166 167 168 169 170

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

/**
 * Check if a file exists and can be accessed.
171
 * @return true or false
172
 */
173
extern bool git_path_exists(const char *path);
174 175 176

/**
 * Check if the given path points to a directory.
177
 * @return true or false
178
 */
179
extern bool git_path_isdir(const char *path);
180

181
/**
182
 * Check if the given path points to a regular file.
183
 * @return true or false
184
 */
185
extern bool git_path_isfile(const char *path);
186 187

/**
188 189 190 191 192 193
 * Check if the given path points to a symbolic link.
 * @return true or false
 */
extern bool git_path_islink(const char *path);

/**
Ben Straub committed
194 195 196 197 198
 * Check if the given path is a directory, and is empty.
 */
extern bool git_path_is_empty_dir(const char *path);

/**
199 200 201 202 203
 * Stat a file and/or link and set error if needed.
 */
extern int git_path_lstat(const char *path, struct stat *st);

/**
204 205 206 207
 * Check if the parent directory contains the item.
 *
 * @param dir Directory to check.
 * @param item Item that might be in the directory.
208
 * @return 0 if item exists in directory, <0 otherwise.
209
 */
210
extern bool git_path_contains(git_buf *dir, const char *item);
211 212

/**
213 214 215 216
 * 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
217
 * @return true if subdirectory exists, false otherwise.
218
 */
219
extern bool git_path_contains_dir(git_buf *parent, const char *subdir);
220 221

/**
222 223 224 225 226 227 228 229 230 231 232 233
 * Determine the common directory length between two paths, including
 * the final path separator.  For example, given paths 'a/b/c/1.txt
 * and 'a/b/c/d/2.txt', the common directory is 'a/b/c/', and this
 * will return the length of the string 'a/b/c/', which is 6.
 *
 * @param one The first path
 * @param two The second path
 * @return The length of the common directory
 */
extern size_t git_path_common_dirlen(const char *one, const char *two);

/**
234 235 236 237 238 239 240 241 242 243 244
 * 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);

/**
245 246 247 248
 * 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
249
 * @return true if file exists, false otherwise.
250
 */
251
extern bool git_path_contains_file(git_buf *dir, const char *file);
252 253

/**
254 255 256 257 258 259 260 261 262
 * 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);

/**
263 264 265 266 267 268
 * Removes multiple occurrences of '/' in a row, squashing them into a
 * single '/'.
 */
extern void git_path_squash_slashes(git_buf *path);

/**
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290
 * 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);

/**
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312
 * 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);

313 314 315
enum {
	GIT_PATH_DIR_IGNORE_CASE = (1u << 0),
	GIT_PATH_DIR_PRECOMPOSE_UNICODE = (1u << 1),
316
	GIT_PATH_DIR_INCLUDE_DOT_AND_DOTDOT = (1u << 2),
317 318
};

319
/**
320 321
 * Walk each directory entry, except '.' and '..', calling fn(state).
 *
322
 * @param pathbuf Buffer the function reads the initial directory
323
 * 		path from, and updates with each successive entry's name.
324 325 326
 * @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
327 328
 *		safely append text to the pathbuf if needed.  Return non-zero to
 *		cancel iteration (and return value will be propagated back).
329
 * @param payload Passed to callback as first argument.
330
 * @return 0 on success or error code from OS error or from callback
331 332 333
 */
extern int git_path_direach(
	git_buf *pathbuf,
334 335 336
	uint32_t flags,
	int (*callback)(void *payload, git_buf *path),
	void *payload);
337 338

/**
339
 * Sort function to order two paths
340 341
 */
extern int git_path_cmp(
342
	const char *name1, size_t len1, int isdir1,
343 344
	const char *name2, size_t len2, int isdir2,
	int (*compare)(const char *, const char *, size_t));
345

346 347 348 349
/**
 * Invoke callback up path directory by directory until the ceiling is
 * reached (inclusive of a final call at the root_path).
 *
350
 * Returning anything other than 0 from the callback function
Will Stamper committed
351
 * will stop the iteration and propagate the error to the caller.
352
 *
353 354 355
 * @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,
356 357 358 359 360
 *		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
361
 *		be modified in any way. Return non-zero to stop iteration.
362
 * @param payload Passed to fn as the first ath.
363
 */
364
extern int git_path_walk_up(
365 366
	git_buf *pathbuf,
	const char *ceiling,
367
	int (*callback)(void *payload, const char *path),
368
	void *payload);
369

370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 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 418 419 420 421 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

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,
	ssize_t *prefixlen)
{
	const char *p = parent, *c = child;
	int lastslash = 0;

	while (*p && *c) {
		lastslash = (*p == '/');

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

	if (*p != '\0')
		return GIT_PATH_NOTEQUAL;

	if (*c == '\0') {
		if (prefixlen)
			*prefixlen = p - parent;

		return GIT_PATH_EQUAL;
	}

	if (*c == '/' || lastslash) {
		if (prefixlen)
			*prefixlen = (p - parent) - lastslash;

		return GIT_PATH_PREFIX;
	}

	return GIT_PATH_NOTEQUAL;
}

/* 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);

/* 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.
 */
450
extern int git_path_iconv(git_path_iconv_t *ic, const char **in, size_t *inlen);
451 452 453 454 455 456

#endif /* GIT_USE_ICONV */

extern bool git_path_does_fs_decompose_unicode(const char *root);


457 458
typedef struct git_path_diriter git_path_diriter;

459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480
#if defined(GIT_WIN32) && !defined(__MINGW32__)

struct git_path_diriter
{
	git_win32_path path;
	size_t parent_len;

	git_buf path_utf8;
	size_t parent_utf8_len;

	HANDLE handle;

	unsigned int flags;

	WIN32_FIND_DATAW current;
	unsigned int needs_next;
};

#define GIT_PATH_DIRITER_INIT { {0}, 0, GIT_BUF_INIT, 0, INVALID_HANDLE_VALUE }

#else

481 482 483 484 485 486 487 488
struct git_path_diriter
{
	git_buf path;
	size_t parent_len;

	unsigned int flags;

	DIR *dir;
489 490 491 492

#ifdef GIT_USE_ICONV
	git_path_iconv_t ic;
#endif
493 494
};

495 496 497 498
#define GIT_PATH_DIRITER_INIT { GIT_BUF_INIT }

#endif

499 500 501 502 503 504 505 506
/**
 * Initialize a directory iterator.
 *
 * @param diriter Pointer to a diriter structure that will be setup.
 * @param path The path that will be iterated over
 * @param flags Directory reader flags
 * @return 0 or an error code
 */
507 508 509 510 511
extern int git_path_diriter_init(
	git_path_diriter *diriter,
	const char *path,
	unsigned int flags);

512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529
/**
 * Advance the directory iterator.  Will return GIT_ITEROVER when
 * the iteration has completed successfully.
 *
 * @param diriter The directory iterator
 * @return 0, GIT_ITEROVER, or an error code
 */
extern int git_path_diriter_next(git_path_diriter *diriter);

/**
 * Returns the file name of the current item in the iterator.
 *
 * @param out Pointer to store the path in
 * @param out_len Pointer to store the length of the path in
 * @param diriter The directory iterator
 * @return 0 or an error code
 */
extern int git_path_diriter_filename(
530 531 532 533
	const char **out,
	size_t *out_len,
	git_path_diriter *diriter);

534 535 536 537 538 539 540 541 542 543
/**
 * Returns the full path of the current item in the iterator; that
 * is the current filename plus the path of the directory that the
 * iterator was constructed with.
 *
 * @param out Pointer to store the path in
 * @param out_len Pointer to store the length of the path in
 * @param diriter The directory iterator
 * @return 0 or an error code
 */
544 545 546 547 548
extern int git_path_diriter_fullpath(
	const char **out,
	size_t *out_len,
	git_path_diriter *diriter);

549 550 551 552 553 554 555
/**
 * Performs an `lstat` on the current item in the iterator.
 *
 * @param out Pointer to store the stat data in
 * @param diriter The directory iterator
 * @return 0 or an error code
 */
556 557
extern int git_path_diriter_stat(struct stat *out, git_path_diriter *diriter);

558 559 560 561 562
/**
 * Closes the directory iterator.
 *
 * @param diriter The directory iterator
 */
563 564
extern void git_path_diriter_free(git_path_diriter *diriter);

565 566 567 568 569 570 571 572
/**
 * 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.
 *
573
 * @param contents Vector to fill with directory entry names.
574 575 576 577
 * @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.
578
 * @param flags Combination of GIT_PATH_DIR flags.
579 580
 */
extern int git_path_dirload(
581
	git_vector *contents,
582 583
	const char *path,
	size_t prefix_len,
584
	uint32_t flags);
585

586

587
/* Used for paths to repositories on the filesystem */
588
extern bool git_path_is_local_file_url(const char *file_url);
589 590
extern int git_path_from_url_or_path(git_buf *local_path_out, const char *url_or_path);

591 592 593
/* Flags to determine path validity in `git_path_isvalid` */
#define GIT_PATH_REJECT_TRAVERSAL          (1 << 0)
#define GIT_PATH_REJECT_DOT_GIT            (1 << 1)
594 595 596 597 598
#define GIT_PATH_REJECT_SLASH              (1 << 2)
#define GIT_PATH_REJECT_BACKSLASH          (1 << 3)
#define GIT_PATH_REJECT_TRAILING_DOT       (1 << 4)
#define GIT_PATH_REJECT_TRAILING_SPACE     (1 << 5)
#define GIT_PATH_REJECT_TRAILING_COLON     (1 << 6)
599 600
#define GIT_PATH_REJECT_DOS_PATHS          (1 << 7)
#define GIT_PATH_REJECT_NT_CHARS           (1 << 8)
601 602 603
#define GIT_PATH_REJECT_DOT_GIT_LITERAL    (1 << 9)
#define GIT_PATH_REJECT_DOT_GIT_HFS        (1 << 10)
#define GIT_PATH_REJECT_DOT_GIT_NTFS       (1 << 11)
604

605 606 607 608
/* Default path safety for writing files to disk: since we use the
 * Win32 "File Namespace" APIs ("\\?\") we need to protect from
 * paths that the normal Win32 APIs would not write.
 */
609
#ifdef GIT_WIN32
610
# define GIT_PATH_REJECT_FILESYSTEM_DEFAULTS \
611 612 613 614 615 616 617 618
	GIT_PATH_REJECT_TRAVERSAL | \
	GIT_PATH_REJECT_BACKSLASH | \
	GIT_PATH_REJECT_TRAILING_DOT | \
	GIT_PATH_REJECT_TRAILING_SPACE | \
	GIT_PATH_REJECT_TRAILING_COLON | \
	GIT_PATH_REJECT_DOS_PATHS | \
	GIT_PATH_REJECT_NT_CHARS
#else
619 620
# define GIT_PATH_REJECT_FILESYSTEM_DEFAULTS \
	GIT_PATH_REJECT_TRAVERSAL
621 622
#endif

623 624 625 626 627 628 629 630
 /* Paths that should never be written into the working directory. */
#define GIT_PATH_REJECT_WORKDIR_DEFAULTS \
	GIT_PATH_REJECT_FILESYSTEM_DEFAULTS | GIT_PATH_REJECT_DOT_GIT

/* Paths that should never be written to the index. */
#define GIT_PATH_REJECT_INDEX_DEFAULTS \
	GIT_PATH_REJECT_TRAVERSAL | GIT_PATH_REJECT_DOT_GIT

631 632 633 634 635 636 637 638 639 640 641
/*
 * Determine whether a path is a valid git path or not - this must not contain
 * a '.' or '..' component, or a component that is ".git" (in any case).
 *
 * `repo` is optional.  If specified, it will be used to determine the short
 * path name to reject (if `GIT_PATH_REJECT_DOS_SHORTNAME` is specified),
 * in addition to the default of "git~1".
 */
extern bool git_path_isvalid(
	git_repository *repo,
	const char *path,
642
	uint16_t mode,
643 644
	unsigned int flags);

645 646 647 648 649
/**
 * Convert any backslashes into slashes
 */
int git_path_normalize_slashes(git_buf *out, const char *path);

650 651
bool git_path_supports_symlinks(const char *dir);

652 653 654 655 656 657 658 659 660 661 662 663
/**
 * Validate a system file's ownership
 *
 * Verify that the file in question is owned by an administrator or system
 * account, or at least by the current user.
 *
 * This function returns 0 if successful. If the file is not owned by any of
 * these, or any other if there have been problems determining the file
 * ownership, it returns -1.
 */
int git_path_validate_system_file_ownership(const char *path);

Vicent Marti committed
664
#endif