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_fileops_h__
8 #define INCLUDE_fileops_h__
18 * Read whole files into an in-memory buffer for processing
20 extern int git_futils_readbuffer(git_buf
*obj
, const char *path
);
21 extern int git_futils_readbuffer_updated(
22 git_buf
*obj
, const char *path
, time_t *mtime
, size_t *size
, int *updated
);
23 extern int git_futils_readbuffer_fd(git_buf
*obj
, git_file fd
, size_t len
);
25 extern int git_futils_writebuffer(
26 const git_buf
*buf
, const char *path
, int open_flags
, mode_t mode
);
31 * These are custom filesystem-related helper methods. They are
32 * rather high level, and wrap the underlying POSIX methods
34 * All these methods return 0 on success,
35 * or an error code on failure and an error message is set.
39 * Create and open a file, while also
40 * creating all the folders in its path
42 extern int git_futils_creat_withpath(const char *path
, const mode_t dirmode
, const mode_t mode
);
45 * Create an open a process-locked file
47 extern int git_futils_creat_locked(const char *path
, const mode_t mode
);
50 * Create an open a process-locked file, while
51 * also creating all the folders in its path
53 extern int git_futils_creat_locked_withpath(const char *path
, const mode_t dirmode
, const mode_t mode
);
56 * Create a path recursively
58 * If a base parameter is being passed, it's expected to be valued with a
59 * path pointing to an already existing directory.
61 extern int git_futils_mkdir_r(const char *path
, const char *base
, const mode_t mode
);
64 * Flags to pass to `git_futils_mkdir`.
66 * * GIT_MKDIR_EXCL is "exclusive" - i.e. generate an error if dir exists.
67 * * GIT_MKDIR_PATH says to make all components in the path.
68 * * GIT_MKDIR_CHMOD says to chmod the final directory entry after creation
69 * * GIT_MKDIR_CHMOD_PATH says to chmod each directory component in the path
70 * * GIT_MKDIR_SKIP_LAST says to leave off the last element of the path
71 * * GIT_MKDIR_SKIP_LAST2 says to leave off the last 2 elements of the path
72 * * GIT_MKDIR_VERIFY_DIR says confirm final item is a dir, not just EEXIST
74 * Note that the chmod options will be executed even if the directory already
75 * exists, unless GIT_MKDIR_EXCL is given.
81 GIT_MKDIR_CHMOD_PATH
= 8,
82 GIT_MKDIR_SKIP_LAST
= 16,
83 GIT_MKDIR_SKIP_LAST2
= 32,
84 GIT_MKDIR_VERIFY_DIR
= 64,
85 } git_futils_mkdir_flags
;
88 * Create a directory or entire path.
90 * This makes a directory (and the entire path leading up to it if requested),
91 * and optionally chmods the directory immediately after (or each part of the
94 * @param path The path to create.
95 * @param base Root for relative path. These directories will never be made.
96 * @param mode The mode to use for created directories.
97 * @param flags Combination of the mkdir flags above.
98 * @return 0 on success, else error code
100 extern int git_futils_mkdir(const char *path
, const char *base
, mode_t mode
, uint32_t flags
);
103 * Create all the folders required to contain
104 * the full path of a file
106 extern int git_futils_mkpath2file(const char *path
, const mode_t mode
);
109 * Flags to pass to `git_futils_rmdir_r`.
111 * * GIT_RMDIR_EMPTY_HIERARCHY - the default; remove hierarchy of empty
112 * dirs and generate error if any files are found.
113 * * GIT_RMDIR_REMOVE_FILES - attempt to remove files in the hierarchy.
114 * * GIT_RMDIR_SKIP_NONEMPTY - skip non-empty directories with no error.
115 * * GIT_RMDIR_EMPTY_PARENTS - remove containing directories up to base
116 * if removing this item leaves them empty
117 * * GIT_RMDIR_REMOVE_BLOCKERS - remove blocking file that causes ENOTDIR
119 * The old values translate into the new as follows:
121 * * GIT_DIRREMOVAL_EMPTY_HIERARCHY == GIT_RMDIR_EMPTY_HIERARCHY
122 * * GIT_DIRREMOVAL_FILES_AND_DIRS ~= GIT_RMDIR_REMOVE_FILES
123 * * GIT_DIRREMOVAL_ONLY_EMPTY_DIRS == GIT_RMDIR_SKIP_NONEMPTY
126 GIT_RMDIR_EMPTY_HIERARCHY
= 0,
127 GIT_RMDIR_REMOVE_FILES
= (1 << 0),
128 GIT_RMDIR_SKIP_NONEMPTY
= (1 << 1),
129 GIT_RMDIR_EMPTY_PARENTS
= (1 << 2),
130 GIT_RMDIR_REMOVE_BLOCKERS
= (1 << 3),
131 } git_futils_rmdir_flags
;
134 * Remove path and any files and directories beneath it.
136 * @param path Path to the top level directory to process.
137 * @param base Root for relative path.
138 * @param flags Combination of git_futils_rmdir_flags values
139 * @return 0 on success; -1 on error.
141 extern int git_futils_rmdir_r(const char *path
, const char *base
, uint32_t flags
);
144 * Remove all files and directories beneath the specified path.
146 * @param path Path to the top level directory to process.
147 * @return 0 on success; -1 on error.
149 extern int git_futils_cleanupdir_r(const char *path
);
152 * Create and open a temporary file with a `_git2_` suffix.
153 * Writes the filename into path_out.
154 * @return On success, an open file descriptor, else an error code < 0.
156 extern int git_futils_mktmp(git_buf
*path_out
, const char *filename
);
159 * Move a file on the filesystem, create the
160 * destination path if it doesn't exist
162 extern int git_futils_mv_withpath(const char *from
, const char *to
, const mode_t dirmode
);
167 * The filemode will be used for the newly created file.
169 extern int git_futils_cp(
175 * Flags that can be passed to `git_futils_cp_r`.
177 * - GIT_CPDIR_CREATE_EMPTY_DIRS: create directories even if there are no
178 * files under them (otherwise directories will only be created lazily
179 * when a file inside them is copied).
180 * - GIT_CPDIR_COPY_SYMLINKS: copy symlinks, otherwise they are ignored.
181 * - GIT_CPDIR_COPY_DOTFILES: copy files with leading '.', otherwise ignored.
182 * - GIT_CPDIR_OVERWRITE: overwrite pre-existing files with source content,
183 * otherwise they are silently skipped.
184 * - GIT_CPDIR_CHMOD_DIRS: explicitly chmod directories to `dirmode`
185 * - GIT_CPDIR_SIMPLE_TO_MODE: default tries to replicate the mode of the
186 * source file to the target; with this flag, always use 0666 (or 0777 if
187 * source has exec bits set) for target.
190 GIT_CPDIR_CREATE_EMPTY_DIRS
= (1u << 0),
191 GIT_CPDIR_COPY_SYMLINKS
= (1u << 1),
192 GIT_CPDIR_COPY_DOTFILES
= (1u << 2),
193 GIT_CPDIR_OVERWRITE
= (1u << 3),
194 GIT_CPDIR_CHMOD_DIRS
= (1u << 4),
195 GIT_CPDIR_SIMPLE_TO_MODE
= (1u << 5),
196 } git_futils_cpdir_flags
;
199 * Copy a directory tree.
201 * This copies directories and files from one root to another. You can
202 * pass a combinationof GIT_CPDIR flags as defined above.
204 * If you pass the CHMOD flag, then the dirmode will be applied to all
205 * directories that are created during the copy, overiding the natural
206 * permissions. If you do not pass the CHMOD flag, then the dirmode
207 * will actually be copied from the source files and the `dirmode` arg
210 extern int git_futils_cp_r(
217 * Open a file readonly and set error if needed.
219 extern int git_futils_open_ro(const char *path
);
222 * Get the filesize in bytes of a file
224 extern git_off_t
git_futils_filesize(git_file fd
);
226 #define GIT_MODE_PERMS_MASK 0777
227 #define GIT_CANONICAL_PERMS(MODE) (((MODE) & 0100) ? 0755 : 0644)
228 #define GIT_MODE_TYPE(MODE) ((MODE) & ~GIT_MODE_PERMS_MASK)
229 #define GIT_MODE_ISBLOB(MODE) (GIT_MODE_TYPE(MODE) == GIT_MODE_TYPE(GIT_FILEMODE_BLOB))
232 * Convert a mode_t from the OS to a legal git mode_t value.
234 extern mode_t
git_futils_canonical_mode(mode_t raw_mode
);
238 * Read-only map all or part of a file into memory.
239 * When possible this function should favor a virtual memory
240 * style mapping over some form of malloc()+read(), as the
241 * data access will be random and is not likely to touch the
242 * majority of the region requested.
244 * @param out buffer to populate with the mapping information.
245 * @param fd open descriptor to configure the mapping from.
246 * @param begin first byte to map, this should be page aligned.
247 * @param len number of bytes to map.
252 extern int git_futils_mmap_ro(
259 * Read-only map an entire file.
261 * @param out buffer to populate with the mapping information.
262 * @param path path to file to be opened.
265 * - GIT_ENOTFOUND if not found;
266 * - -1 on an unspecified OS related error.
268 extern int git_futils_mmap_ro_file(
273 * Release the memory associated with a previous memory mapping.
274 * @param map the mapping description previously configured.
276 extern void git_futils_mmap_free(git_map
*map
);
279 * Find a "global" file (i.e. one in a user's home directory).
281 * @param path buffer to write the full path into
282 * @param filename name of file to find in the home directory
283 * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error
285 extern int git_futils_find_global_file(git_buf
*path
, const char *filename
);
288 * Find an "XDG" file (i.e. one in user's XDG config path).
290 * @param path buffer to write the full path into
291 * @param filename name of file to find in the home directory
292 * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error
294 extern int git_futils_find_xdg_file(git_buf
*path
, const char *filename
);
297 * Find a "system" file (i.e. one shared for all users of the system).
299 * @param path buffer to write the full path into
300 * @param filename name of file to find in the home directory
301 * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error
303 extern int git_futils_find_system_file(git_buf
*path
, const char *filename
);
306 GIT_FUTILS_DIR_SYSTEM
= 0,
307 GIT_FUTILS_DIR_GLOBAL
= 1,
308 GIT_FUTILS_DIR_XDG
= 2,
309 GIT_FUTILS_DIR__MAX
= 3,
313 * Configures global data for configuration file search paths.
315 * @return 0 on success, <0 on failure
317 extern int git_futils_dirs_global_init(void);
320 * Get the search path for global/system/xdg files
322 * @param out pointer to git_buf containing search path
323 * @param which which list of paths to return
324 * @return 0 on success, <0 on failure
326 extern int git_futils_dirs_get(const git_buf
**out
, git_futils_dir_t which
);
329 * Get search path into a preallocated buffer
331 * @param out String buffer to write into
332 * @param outlen Size of string buffer
333 * @param which Which search path to return
334 * @return 0 on success, GIT_EBUFS if out is too small, <0 on other failure
337 extern int git_futils_dirs_get_str(
338 char *out
, size_t outlen
, git_futils_dir_t which
);
341 * Set search paths for global/system/xdg files
343 * The first occurrence of the magic string "$PATH" in the new value will
344 * be replaced with the old value of the search path.
346 * @param which Which search path to modify
347 * @param paths New search path (separated by GIT_PATH_LIST_SEPARATOR)
348 * @return 0 on success, <0 on failure (allocation error)
350 extern int git_futils_dirs_set(git_futils_dir_t which
, const char *paths
);
353 * Release / reset all search paths
355 extern void git_futils_dirs_free(void);
358 * Create a "fake" symlink (text file containing the target path).
360 * @param new symlink file to be created
361 * @param old original symlink target
362 * @return 0 on success, -1 on error
364 extern int git_futils_fake_symlink(const char *new, const char *old
);
367 * A file stamp represents a snapshot of information about a file that can
368 * be used to test if the file changes. This portable implementation is
369 * based on stat data about that file, but it is possible that OS specific
370 * versions could be implemented in the future.
376 } git_futils_filestamp
;
379 * Compare stat information for file with reference info.
381 * This function updates the file stamp to current data for the given path
382 * and returns 0 if the file is up-to-date relative to the prior setting or
383 * 1 if the file has been changed. (This also may return GIT_ENOTFOUND if
384 * the file doesn't exist.)
386 * @param stamp File stamp to be checked
387 * @param path Path to stat and check if changed
388 * @return 0 if up-to-date, 1 if out-of-date, <0 on error
390 extern int git_futils_filestamp_check(
391 git_futils_filestamp
*stamp
, const char *path
);
394 * Set or reset file stamp data
396 * This writes the target file stamp. If the source is NULL, this will set
397 * the target stamp to values that will definitely be out of date. If the
398 * source is not NULL, this copies the source values to the target.
400 * @param tgt File stamp to write to
401 * @param src File stamp to copy from or NULL to clear the target
403 extern void git_futils_filestamp_set(
404 git_futils_filestamp
*tgt
, const git_futils_filestamp
*src
);
406 #endif /* INCLUDE_fileops_h__ */