fileops.h 12.6 KB
Newer Older
1
/*
Edward Thomson committed
2
 * Copyright (C) the libgit2 contributors. All rights reserved.
3
 *
Vicent Marti committed
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.
6 7 8 9
 */
#ifndef INCLUDE_fileops_h__
#define INCLUDE_fileops_h__

10
#include "common.h"
11
#include "map.h"
Vicent Marti committed
12 13 14 15 16 17 18 19
#include "posix.h"
#include "path.h"

/**
 * Filebuffer methods
 *
 * Read whole files into an in-memory buffer for processing
 */
20
extern int git_futils_readbuffer(git_buf *obj, const char *path);
21 22
extern int git_futils_readbuffer_updated(
	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);
Vicent Marti committed
24 25 26 27 28 29 30

/**
 * File utils
 *
 * These are custom filesystem-related helper methods. They are
 * rather high level, and wrap the underlying POSIX methods
 *
31
 * All these methods return 0 on success,
Vicent Marti committed
32 33 34 35 36 37 38
 * or an error code on failure and an error message is set.
 */

/**
 * Create and open a file, while also
 * creating all the folders in its path
 */
39
extern int git_futils_creat_withpath(const char *path, const mode_t dirmode, const mode_t mode);
Vicent Marti committed
40 41 42 43

/**
 * Create an open a process-locked file
 */
44
extern int git_futils_creat_locked(const char *path, const mode_t mode);
Vicent Marti committed
45 46 47 48 49

/**
 * Create an open a process-locked file, while
 * also creating all the folders in its path
 */
50
extern int git_futils_creat_locked_withpath(const char *path, const mode_t dirmode, const mode_t mode);
Vicent Marti committed
51 52

/**
53 54 55 56
 * Create a path recursively
 *
 * If a base parameter is being passed, it's expected to be valued with a
 * path pointing to an already existing directory.
57
 */
58
extern int git_futils_mkdir_r(const char *path, const char *base, const mode_t mode);
59 60

/**
61
 * Flags to pass to `git_futils_mkdir`.
62
 *
63 64 65 66 67
 * * GIT_MKDIR_EXCL is "exclusive" - i.e. generate an error if dir exists.
 * * GIT_MKDIR_PATH says to make all components in the path.
 * * GIT_MKDIR_CHMOD says to chmod the final directory entry after creation
 * * GIT_MKDIR_CHMOD_PATH says to chmod each directory component in the path
 * * GIT_MKDIR_SKIP_LAST says to leave off the last element of the path
68
 * * GIT_MKDIR_SKIP_LAST2 says to leave off the last 2 elements of the path
69
 * * GIT_MKDIR_VERIFY_DIR says confirm final item is a dir, not just EEXIST
70 71 72
 *
 * Note that the chmod options will be executed even if the directory already
 * exists, unless GIT_MKDIR_EXCL is given.
Vicent Marti committed
73
 */
74 75 76 77 78
typedef enum {
	GIT_MKDIR_EXCL = 1,
	GIT_MKDIR_PATH = 2,
	GIT_MKDIR_CHMOD = 4,
	GIT_MKDIR_CHMOD_PATH = 8,
79
	GIT_MKDIR_SKIP_LAST = 16,
80 81
	GIT_MKDIR_SKIP_LAST2 = 32,
	GIT_MKDIR_VERIFY_DIR = 64,
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
} git_futils_mkdir_flags;

/**
 * Create a directory or entire path.
 *
 * This makes a directory (and the entire path leading up to it if requested),
 * and optionally chmods the directory immediately after (or each part of the
 * path if requested).
 *
 * @param path The path to create.
 * @param base Root for relative path.  These directories will never be made.
 * @param mode The mode to use for created directories.
 * @param flags Combination of the mkdir flags above.
 * @return 0 on success, else error code
 */
extern int git_futils_mkdir(const char *path, const char *base, mode_t mode, uint32_t flags);
Vicent Marti committed
98 99 100 101 102

/**
 * Create all the folders required to contain
 * the full path of a file
 */
103
extern int git_futils_mkpath2file(const char *path, const mode_t mode);
Vicent Marti committed
104

105 106 107 108 109 110 111 112 113
/**
 * Flags to pass to `git_futils_rmdir_r`.
 *
 * * GIT_RMDIR_EMPTY_HIERARCHY - the default; remove hierarchy of empty
 *       dirs and generate error if any files are found.
 * * GIT_RMDIR_REMOVE_FILES    - attempt to remove files in the hierarchy.
 * * GIT_RMDIR_SKIP_NONEMPTY   - skip non-empty directories with no error.
 * * GIT_RMDIR_EMPTY_PARENTS   - remove containing directories up to base
 *       if removing this item leaves them empty
114
 * * GIT_RMDIR_REMOVE_BLOCKERS - remove blocking file that causes ENOTDIR
115 116 117 118 119 120 121
 *
 * The old values translate into the new as follows:
 *
 * * GIT_DIRREMOVAL_EMPTY_HIERARCHY == GIT_RMDIR_EMPTY_HIERARCHY
 * * GIT_DIRREMOVAL_FILES_AND_DIRS  ~= GIT_RMDIR_REMOVE_FILES
 * * GIT_DIRREMOVAL_ONLY_EMPTY_DIRS == GIT_RMDIR_SKIP_NONEMPTY
 */
122
typedef enum {
123 124 125 126
	GIT_RMDIR_EMPTY_HIERARCHY = 0,
	GIT_RMDIR_REMOVE_FILES    = (1 << 0),
	GIT_RMDIR_SKIP_NONEMPTY   = (1 << 1),
	GIT_RMDIR_EMPTY_PARENTS   = (1 << 2),
127
	GIT_RMDIR_REMOVE_BLOCKERS = (1 << 3),
128
} git_futils_rmdir_flags;
129

Vicent Marti committed
130
/**
131
 * Remove path and any files and directories beneath it.
132
 *
133
 * @param path Path to the top level directory to process.
134
 * @param base Root for relative path.
135
 * @param flags Combination of git_futils_rmdir_flags values
136
 * @return 0 on success; -1 on error.
137
 */
138
extern int git_futils_rmdir_r(const char *path, const char *base, uint32_t flags);
139 140

/**
141 142 143 144 145 146 147 148
 * Remove all files and directories beneath the specified path.
 *
 * @param path Path to the top level directory to process.
 * @return 0 on success; -1 on error.
 */
extern int git_futils_cleanupdir_r(const char *path);

/**
149 150 151
 * Create and open a temporary file with a `_git2_` suffix.
 * Writes the filename into path_out.
 * @return On success, an open file descriptor, else an error code < 0.
Vicent Marti committed
152
 */
153
extern int git_futils_mktmp(git_buf *path_out, const char *filename);
Vicent Marti committed
154 155 156 157 158

/**
 * Move a file on the filesystem, create the
 * destination path if it doesn't exist
 */
159
extern int git_futils_mv_withpath(const char *from, const char *to, const mode_t dirmode);
Vicent Marti committed
160 161

/**
162
 * Copy a file
163
 *
164
 * The filemode will be used for the newly created file.
165
 */
166
extern int git_futils_cp(
167 168
	const char *from,
	const char *to,
169
	mode_t filemode);
170 171 172

/**
 * Flags that can be passed to `git_futils_cp_r`.
173 174 175 176 177 178 179 180 181 182 183 184
 *
 * - GIT_CPDIR_CREATE_EMPTY_DIRS: create directories even if there are no
 *   files under them (otherwise directories will only be created lazily
 *   when a file inside them is copied).
 * - GIT_CPDIR_COPY_SYMLINKS: copy symlinks, otherwise they are ignored.
 * - GIT_CPDIR_COPY_DOTFILES: copy files with leading '.', otherwise ignored.
 * - GIT_CPDIR_OVERWRITE: overwrite pre-existing files with source content,
 *   otherwise they are silently skipped.
 * - GIT_CPDIR_CHMOD_DIRS: explicitly chmod directories to `dirmode`
 * - GIT_CPDIR_SIMPLE_TO_MODE: default tries to replicate the mode of the
 *   source file to the target; with this flag, always use 0666 (or 0777 if
 *   source has exec bits set) for target.
185 186
 */
typedef enum {
187 188 189 190
	GIT_CPDIR_CREATE_EMPTY_DIRS = (1u << 0),
	GIT_CPDIR_COPY_SYMLINKS     = (1u << 1),
	GIT_CPDIR_COPY_DOTFILES     = (1u << 2),
	GIT_CPDIR_OVERWRITE         = (1u << 3),
191 192
	GIT_CPDIR_CHMOD_DIRS        = (1u << 4),
	GIT_CPDIR_SIMPLE_TO_MODE    = (1u << 5),
193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
} git_futils_cpdir_flags;

/**
 * Copy a directory tree.
 *
 * This copies directories and files from one root to another.  You can
 * pass a combinationof GIT_CPDIR flags as defined above.
 *
 * If you pass the CHMOD flag, then the dirmode will be applied to all
 * directories that are created during the copy, overiding the natural
 * permissions.  If you do not pass the CHMOD flag, then the dirmode
 * will actually be copied from the source files and the `dirmode` arg
 * will be ignored.
 */
extern int git_futils_cp_r(
	const char *from,
	const char *to,
	uint32_t flags,
	mode_t dirmode);

/**
214
 * Open a file readonly and set error if needed.
215
 */
216
extern int git_futils_open_ro(const char *path);
217 218

/**
Vicent Marti committed
219 220 221
 * Get the filesize in bytes of a file
 */
extern git_off_t git_futils_filesize(git_file fd);
222

223 224 225 226
#define GIT_MODE_PERMS_MASK			0777
#define GIT_CANONICAL_PERMS(MODE)	(((MODE) & 0100) ? 0755 : 0644)
#define GIT_MODE_TYPE(MODE)			((MODE) & ~GIT_MODE_PERMS_MASK)

227
/**
228 229 230 231 232 233
 * Convert a mode_t from the OS to a legal git mode_t value.
 */
extern mode_t git_futils_canonical_mode(mode_t raw_mode);


/**
234 235 236 237 238 239 240 241 242 243 244
 * Read-only map all or part of a file into memory.
 * When possible this function should favor a virtual memory
 * style mapping over some form of malloc()+read(), as the
 * data access will be random and is not likely to touch the
 * majority of the region requested.
 *
 * @param out buffer to populate with the mapping information.
 * @param fd open descriptor to configure the mapping from.
 * @param begin first byte to map, this should be page aligned.
 * @param end number of bytes to map.
 * @return
245 246
 * - 0 on success;
 * - -1 on error.
247
 */
Vicent Marti committed
248
extern int git_futils_mmap_ro(
249
	git_map *out,
250
	git_file fd,
251
	git_off_t begin,
252 253 254
	size_t len);

/**
255 256 257 258 259
 * Read-only map an entire file.
 *
 * @param out buffer to populate with the mapping information.
 * @param path path to file to be opened.
 * @return
260 261 262
 * - 0 on success;
 * - GIT_ENOTFOUND if not found;
 * - -1 on an unspecified OS related error.
263 264 265 266 267 268
 */
extern int git_futils_mmap_ro_file(
	git_map *out,
	const char *path);

/**
269 270 271
 * Release the memory associated with a previous memory mapping.
 * @param map the mapping description previously configured.
 */
Vicent Marti committed
272
extern void git_futils_mmap_free(git_map *map);
273 274

/**
275 276 277 278
 * Find a "global" file (i.e. one in a user's home directory).
 *
 * @param pathbuf buffer to write the full path into
 * @param filename name of file to find in the home directory
279
 * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error
280 281 282 283
 */
extern int git_futils_find_global_file(git_buf *path, const char *filename);

/**
284 285 286 287 288 289 290 291 292
 * Find an "XDG" file (i.e. one in user's XDG config path).
 *
 * @param pathbuf buffer to write the full path into
 * @param filename name of file to find in the home directory
 * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error
 */
extern int git_futils_find_xdg_file(git_buf *path, const char *filename);

/**
293 294 295 296
 * Find a "system" file (i.e. one shared for all users of the system).
 *
 * @param pathbuf buffer to write the full path into
 * @param filename name of file to find in the home directory
297
 * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error
298 299 300
 */
extern int git_futils_find_system_file(git_buf *path, const char *filename);

301 302 303 304 305 306 307 308
typedef enum {
	GIT_FUTILS_DIR_SYSTEM = 0,
	GIT_FUTILS_DIR_GLOBAL = 1,
	GIT_FUTILS_DIR_XDG    = 2,
	GIT_FUTILS_DIR__MAX   = 3,
} git_futils_dir_t;

/**
309
 * Get the search path for global/system/xdg files
310
 *
311
 * @param out pointer to git_buf containing search path
312
 * @param which which list of paths to return
313 314 315 316 317 318 319 320 321 322 323
 * @return 0 on success, <0 on failure
 */
extern int git_futils_dirs_get(const git_buf **out, git_futils_dir_t which);

/**
 * Get search path into a preallocated buffer
 *
 * @param out String buffer to write into
 * @param outlen Size of string buffer
 * @param which Which search path to return
 * @return 0 on success, GIT_EBUFS if out is too small, <0 on other failure
324
 */
325 326 327

extern int git_futils_dirs_get_str(
	char *out, size_t outlen, git_futils_dir_t which);
328 329

/**
330 331 332 333
 * Set search paths for global/system/xdg files
 *
 * The first occurrence of the magic string "$PATH" in the new value will
 * be replaced with the old value of the search path.
334
 *
335 336
 * @param which Which search path to modify
 * @param paths New search path (separated by GIT_PATH_LIST_SEPARATOR)
337 338
 * @return 0 on success, <0 on failure (allocation error)
 */
339 340 341 342 343 344
extern int git_futils_dirs_set(git_futils_dir_t which, const char *paths);

/**
 * Release / reset all search paths
 */
extern void git_futils_dirs_free(void);
345 346 347 348 349 350 351 352 353 354

/**
 * Create a "fake" symlink (text file containing the target path).
 *
 * @param new symlink file to be created
 * @param old original symlink target
 * @return 0 on success, -1 on error
 */
extern int git_futils_fake_symlink(const char *new, const char *old);

355 356 357 358 359 360
/**
 * A file stamp represents a snapshot of information about a file that can
 * be used to test if the file changes.  This portable implementation is
 * based on stat data about that file, but it is possible that OS specific
 * versions could be implemented in the future.
 */
361
typedef struct {
362
	git_time_t mtime;
363 364
	git_off_t  size;
	unsigned int ino;
Vicent Marti committed
365
} git_futils_filestamp;
366 367 368 369

/**
 * Compare stat information for file with reference info.
 *
370 371 372 373
 * This function updates the file stamp to current data for the given path
 * and returns 0 if the file is up-to-date relative to the prior setting or
 * 1 if the file has been changed.  (This also may return GIT_ENOTFOUND if
 * the file doesn't exist.)
374
 *
375 376
 * @param stamp File stamp to be checked
 * @param path Path to stat and check if changed
377 378
 * @return 0 if up-to-date, 1 if out-of-date, <0 on error
 */
Vicent Marti committed
379 380
extern int git_futils_filestamp_check(
	git_futils_filestamp *stamp, const char *path);
381 382 383 384 385 386 387 388 389 390 391

/**
 * Set or reset file stamp data
 *
 * This writes the target file stamp.  If the source is NULL, this will set
 * the target stamp to values that will definitely be out of date.  If the
 * source is not NULL, this copies the source values to the target.
 *
 * @param tgt File stamp to write to
 * @param src File stamp to copy from or NULL to clear the target
 */
Vicent Marti committed
392 393
extern void git_futils_filestamp_set(
	git_futils_filestamp *tgt, const git_futils_filestamp *src);
394

395
#endif /* INCLUDE_fileops_h__ */