]>
git.proxmox.com Git - libgit2.git/blob - src/path.h
feefd65d15bc6be7d34f862bdb701c7d79e930bf
2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_path_h__
8 #define INCLUDE_path_h__
15 * Path manipulation utils
17 * These are path utilities that munge paths without actually
18 * looking at the real filesystem.
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.
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 "." .
31 * The `git_path_dirname` implementation is thread safe. The returned
32 * string must be manually free'd.
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).
39 extern char *git_path_dirname(const char *path
);
40 extern int git_path_dirname_r(git_buf
*buffer
, const char *path
);
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.
48 * Trailing slashes and backslashes are significant: the basename of
49 * c:/foo/bar/ is an empty string after the rightmost slash.
51 * The `git_path_basename` implementation is thread safe. The returned
52 * string must be manually free'd.
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).
58 extern char *git_path_basename(const char *path
);
59 extern int git_path_basename_r(git_buf
*buffer
, const char *path
);
61 /* Return the offset of the start of the basename. Unlike the other
62 * basename functions, this returns 0 if the path is empty.
64 extern size_t git_path_basename_offset(git_buf
*buffer
);
66 extern const char *git_path_topdir(const char *path
);
69 * Find offset to root of path if path has one.
71 * This will return a number >= 0 which is the offset to the start of the
72 * path, if the path is rooted (i.e. "/rooted/path" returns 0 and
73 * "c:/windows/rooted/path" returns 2). If the path is not rooted, this
76 extern int git_path_root(const char *path
);
79 * Ensure path has a trailing '/'.
81 extern int git_path_to_dir(git_buf
*path
);
84 * Ensure string has a trailing '/' if there is space for it.
86 extern void git_path_string_to_dir(char* path
, size_t size
);
89 * Taken from git.git; returns nonzero if the given path is "." or "..".
91 GIT_INLINE(int) git_path_is_dot_or_dotdot(const char *name
)
93 return (name
[0] == '.' &&
95 (name
[1] == '.' && name
[2] == '\0')));
99 GIT_INLINE(int) git_path_is_dot_or_dotdotW(const wchar_t *name
)
101 return (name
[0] == L
'.' &&
103 (name
[1] == L
'.' && name
[2] == L
'\0')));
107 * Convert backslashes in path to forward slashes.
109 GIT_INLINE(void) git_path_mkposix(char *path
)
119 # define git_path_mkposix(p) /* blank */
122 extern int git__percent_decode(git_buf
*decoded_out
, const char *input
);
125 * Extract path from file:// URL.
127 extern int git_path_fromurl(git_buf
*local_path_out
, const char *file_url
);
131 * Path filesystem utils
133 * These are path utilities that actually access the filesystem.
137 * Check if a file exists and can be accessed.
138 * @return true or false
140 extern bool git_path_exists(const char *path
);
143 * Check if the given path points to a directory.
144 * @return true or false
146 extern bool git_path_isdir(const char *path
);
149 * Check if the given path points to a regular file.
150 * @return true or false
152 extern bool git_path_isfile(const char *path
);
155 * Check if the given path is a directory, and is empty.
157 extern bool git_path_is_empty_dir(const char *path
);
160 * Stat a file and/or link and set error if needed.
162 extern int git_path_lstat(const char *path
, struct stat
*st
);
165 * Check if the parent directory contains the item.
167 * @param dir Directory to check.
168 * @param item Item that might be in the directory.
169 * @return 0 if item exists in directory, <0 otherwise.
171 extern bool git_path_contains(git_buf
*dir
, const char *item
);
174 * Check if the given path contains the given subdirectory.
176 * @param parent Directory path that might contain subdir
177 * @param subdir Subdirectory name to look for in parent
178 * @param append_if_exists If true, then subdir will be appended to the parent path if it does exist
179 * @return true if subdirectory exists, false otherwise.
181 extern bool git_path_contains_dir(git_buf
*parent
, const char *subdir
);
184 * Check if the given path contains the given file.
186 * @param dir Directory path that might contain file
187 * @param file File name to look for in parent
188 * @param append_if_exists If true, then file will be appended to the path if it does exist
189 * @return true if file exists, false otherwise.
191 extern bool git_path_contains_file(git_buf
*dir
, const char *file
);
194 * Prepend base to unrooted path or just copy path over.
196 * This will optionally return the index into the path where the "root"
197 * is, either the end of the base directory prefix or the path root.
199 extern int git_path_join_unrooted(
200 git_buf
*path_out
, const char *path
, const char *base
, ssize_t
*root_at
);
203 * Clean up path, prepending base if it is not already rooted.
205 extern int git_path_prettify(git_buf
*path_out
, const char *path
, const char *base
);
208 * Clean up path, prepending base if it is not already rooted and
211 extern int git_path_prettify_dir(git_buf
*path_out
, const char *path
, const char *base
);
214 * Get a directory from a path.
216 * If path is a directory, this acts like `git_path_prettify_dir`
217 * (cleaning up path and appending a '/'). If path is a normal file,
218 * this prettifies it, then removed the filename a la dirname and
219 * appends the trailing '/'. If the path does not exist, it is
220 * treated like a regular filename.
222 extern int git_path_find_dir(git_buf
*dir
, const char *path
, const char *base
);
225 * Resolve relative references within a path.
227 * This eliminates "./" and "../" relative references inside a path,
228 * as well as condensing multiple slashes into single ones. It will
229 * not touch the path before the "ceiling" length.
231 * Additionally, this will recognize an "c:/" drive prefix or a "xyz://" URL
232 * prefix and not touch that part of the path.
234 extern int git_path_resolve_relative(git_buf
*path
, size_t ceiling
);
237 * Apply a relative path to base path.
239 * Note that the base path could be a filename or a URL and this
240 * should still work. The relative path is walked segment by segment
241 * with three rules: series of slashes will be condensed to a single
242 * slash, "." will be eaten with no change, and ".." will remove a
243 * segment from the base path.
245 extern int git_path_apply_relative(git_buf
*target
, const char *relpath
);
248 * Walk each directory entry, except '.' and '..', calling fn(state).
250 * @param pathbuf buffer the function reads the initial directory
251 * path from, and updates with each successive entry's name.
252 * @param fn function to invoke with each entry. The first arg is
253 * the input state and the second arg is pathbuf. The function
254 * may modify the pathbuf, but only by appending new text.
255 * @param state to pass to fn as the first arg.
256 * @return 0 on success, GIT_EUSER on non-zero callback, or error code
258 extern int git_path_direach(
260 int (*fn
)(void *, git_buf
*),
264 * Sort function to order two paths
266 extern int git_path_cmp(
267 const char *name1
, size_t len1
, int isdir1
,
268 const char *name2
, size_t len2
, int isdir2
);
270 /** Path sort function that is case insensitive */
271 extern int git_path_icmp(
272 const char *name1
, size_t len1
, int isdir1
,
273 const char *name2
, size_t len2
, int isdir2
);
276 * Invoke callback up path directory by directory until the ceiling is
277 * reached (inclusive of a final call at the root_path).
279 * Returning anything other than 0 from the callback function
280 * will stop the iteration and propogate the error to the caller.
282 * @param pathbuf Buffer the function reads the directory from and
283 * and updates with each successive name.
284 * @param ceiling Prefix of path at which to stop walking up. If NULL,
285 * this will walk all the way up to the root. If not a prefix of
286 * pathbuf, the callback will be invoked a single time on the
287 * original input path.
288 * @param fn Function to invoke on each path. The first arg is the
289 * input satte and the second arg is the pathbuf. The function
290 * should not modify the pathbuf.
291 * @param state Passed to fn as the first ath.
293 extern int git_path_walk_up(
296 int (*fn
)(void *state
, git_buf
*),
300 * Load all directory entries (except '.' and '..') into a vector.
302 * For cases where `git_path_direach()` is not appropriate, this
303 * allows you to load the filenames in a directory into a vector
304 * of strings. That vector can then be sorted, iterated, or whatever.
305 * Remember to free alloc of the allocated strings when you are done.
307 * @param path The directory to read from.
308 * @param prefix_len When inserting entries, the trailing part of path
309 * will be prefixed after this length. I.e. given path "/a/b" and
310 * prefix_len 3, the entries will look like "b/e1", "b/e2", etc.
311 * @param alloc_extra Extra bytes to add to each string allocation in
312 * case you want to append anything funny.
313 * @param contents Vector to fill with directory entry names.
315 extern int git_path_dirload(
319 git_vector
*contents
);
325 char path
[GIT_FLEX_ARRAY
];
326 } git_path_with_stat
;
328 extern int git_path_with_stat_cmp(const void *a
, const void *b
);
329 extern int git_path_with_stat_cmp_icase(const void *a
, const void *b
);
332 * Load all directory entries along with stat info into a vector.
334 * This adds four things on top of plain `git_path_dirload`:
336 * 1. Each entry in the vector is a `git_path_with_stat` struct that
337 * contains both the path and the stat info
338 * 2. The entries will be sorted alphabetically
339 * 3. Entries that are directories will be suffixed with a '/'
340 * 4. Optionally, you can be a start and end prefix and only elements
341 * after the start and before the end (inclusively) will be stat'ed.
343 * @param path The directory to read from
344 * @param prefix_len The trailing part of path to prefix to entry paths
345 * @param ignore_case How to sort and compare paths with start/end limits
346 * @param start_stat As optimization, only stat values after this prefix
347 * @param end_stat As optimization, only stat values before this prefix
348 * @param contents Vector to fill with git_path_with_stat structures
350 extern int git_path_dirload_with_stat(
354 const char *start_stat
,
355 const char *end_stat
,
356 git_vector
*contents
);