futils.h 12.3 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
#ifndef INCLUDE_futils_h__
#define INCLUDE_futils_h__
9

10
#include "common.h"
11

12
#include "map.h"
Vicent Marti committed
13 14
#include "posix.h"
#include "path.h"
15 16
#include "pool.h"
#include "strmap.h"
17
#include "oid.h"
Vicent Marti committed
18 19 20 21 22 23

/**
 * Filebuffer methods
 *
 * Read whole files into an in-memory buffer for processing
 */
24
extern int git_futils_readbuffer(git_buf *obj, const char *path);
25
extern int git_futils_readbuffer_updated(
26
	git_buf *obj, const char *path, git_oid *checksum, int *updated);
27
extern int git_futils_readbuffer_fd(git_buf *obj, git_file fd, size_t len);
Vicent Marti committed
28

29 30 31 32 33 34 35
/* Additional constants for `git_futils_writebuffer`'s `open_flags`.  We
 * support these internally and they will be removed before the `open` call.
 */
#ifndef O_FSYNC
# define O_FSYNC (1 << 31)
#endif

36 37 38
extern int git_futils_writebuffer(
	const git_buf *buf, const char *path, int open_flags, mode_t mode);

Vicent Marti committed
39 40 41 42 43 44
/**
 * File utils
 *
 * These are custom filesystem-related helper methods. They are
 * rather high level, and wrap the underlying POSIX methods
 *
45
 * All these methods return 0 on success,
Vicent Marti committed
46 47 48 49 50 51 52
 * 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
 */
53
extern int git_futils_creat_withpath(const char *path, const mode_t dirmode, const mode_t mode);
Vicent Marti committed
54 55

/**
56
 * Create and open a process-locked file
Vicent Marti committed
57
 */
58
extern int git_futils_creat_locked(const char *path, const mode_t mode);
Vicent Marti committed
59 60

/**
61
 * Create and open a process-locked file, while
Vicent Marti committed
62 63
 * also creating all the folders in its path
 */
64
extern int git_futils_creat_locked_withpath(const char *path, const mode_t dirmode, const mode_t mode);
Vicent Marti committed
65 66

/**
67
 * Create a path recursively.
68
 */
69
extern int git_futils_mkdir_r(const char *path, const mode_t mode);
70 71

/**
72
 * Flags to pass to `git_futils_mkdir`.
73
 *
74 75 76 77 78
 * * 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
79
 * * GIT_MKDIR_SKIP_LAST2 says to leave off the last 2 elements of the path
80
 * * GIT_MKDIR_VERIFY_DIR says confirm final item is a dir, not just EEXIST
81 82
 * * GIT_MKDIR_REMOVE_FILES says to remove files and recreate dirs
 * * GIT_MKDIR_REMOVE_SYMLINKS says to remove symlinks and recreate dirs
83 84 85
 *
 * Note that the chmod options will be executed even if the directory already
 * exists, unless GIT_MKDIR_EXCL is given.
Vicent Marti committed
86
 */
87 88 89 90 91
typedef enum {
	GIT_MKDIR_EXCL = 1,
	GIT_MKDIR_PATH = 2,
	GIT_MKDIR_CHMOD = 4,
	GIT_MKDIR_CHMOD_PATH = 8,
92
	GIT_MKDIR_SKIP_LAST = 16,
93 94
	GIT_MKDIR_SKIP_LAST2 = 32,
	GIT_MKDIR_VERIFY_DIR = 64,
95 96
	GIT_MKDIR_REMOVE_FILES = 128,
	GIT_MKDIR_REMOVE_SYMLINKS = 256,
97 98
} git_futils_mkdir_flags;

99 100 101 102 103 104 105
struct git_futils_mkdir_perfdata
{
	size_t stat_calls;
	size_t mkdir_calls;
	size_t chmod_calls;
};

106 107 108 109 110 111 112
struct git_futils_mkdir_options
{
	git_strmap *dir_map;
	git_pool *pool;
	struct git_futils_mkdir_perfdata perfdata;
};

113 114 115 116 117 118 119
/**
 * 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).
 *
120
 * @param path The path to create, relative to base.
121 122 123
 * @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.
124
 * @param opts Extended options, or null.
125 126
 * @return 0 on success, else error code
 */
127
extern int git_futils_mkdir_relative(const char *path, const char *base, mode_t mode, uint32_t flags, struct git_futils_mkdir_options *opts);
128 129

/**
130
 * Create a directory or entire path.  Similar to `git_futils_mkdir_relative`
131 132
 * without performance data.
 */
133
extern int git_futils_mkdir(const char *path, mode_t mode, uint32_t flags);
Vicent Marti committed
134 135 136 137 138

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

141 142 143 144 145 146 147 148 149
/**
 * 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
150
 * * GIT_RMDIR_REMOVE_BLOCKERS - remove blocking file that causes ENOTDIR
151
 * * GIT_RMDIR_SKIP_ROOT       - don't remove root directory itself
152
 */
153
typedef enum {
154 155 156 157
	GIT_RMDIR_EMPTY_HIERARCHY = 0,
	GIT_RMDIR_REMOVE_FILES    = (1 << 0),
	GIT_RMDIR_SKIP_NONEMPTY   = (1 << 1),
	GIT_RMDIR_EMPTY_PARENTS   = (1 << 2),
158
	GIT_RMDIR_REMOVE_BLOCKERS = (1 << 3),
159
	GIT_RMDIR_SKIP_ROOT       = (1 << 4),
160
} git_futils_rmdir_flags;
161

Vicent Marti committed
162
/**
163
 * Remove path and any files and directories beneath it.
164
 *
165
 * @param path Path to the top level directory to process.
166
 * @param base Root for relative path.
167
 * @param flags Combination of git_futils_rmdir_flags values
168
 * @return 0 on success; -1 on error.
169
 */
170
extern int git_futils_rmdir_r(const char *path, const char *base, uint32_t flags);
171 172

/**
173 174 175
 * 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
176
 */
177
extern int git_futils_mktmp(git_buf *path_out, const char *filename, mode_t mode);
Vicent Marti committed
178 179 180 181 182

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

/**
186
 * Copy a file
187
 *
188
 * The filemode will be used for the newly created file.
189
 */
190
extern int git_futils_cp(
191 192
	const char *from,
	const char *to,
193
	mode_t filemode);
194 195

/**
196 197
 * Set the files atime and mtime to the given time, or the current time
 * if `ts` is NULL.
198
 */
199
extern int git_futils_touch(const char *path, time_t *when);
200 201

/**
202
 * Flags that can be passed to `git_futils_cp_r`.
203 204 205 206 207 208 209 210 211 212 213 214
 *
 * - 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.
215
 * - GIT_CPDIR_LINK_FILES will try to use hardlinks for the files
216 217
 */
typedef enum {
218 219 220 221
	GIT_CPDIR_CREATE_EMPTY_DIRS = (1u << 0),
	GIT_CPDIR_COPY_SYMLINKS     = (1u << 1),
	GIT_CPDIR_COPY_DOTFILES     = (1u << 2),
	GIT_CPDIR_OVERWRITE         = (1u << 3),
222 223
	GIT_CPDIR_CHMOD_DIRS        = (1u << 4),
	GIT_CPDIR_SIMPLE_TO_MODE    = (1u << 5),
224
	GIT_CPDIR_LINK_FILES        = (1u << 6),
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245
} 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);

/**
246
 * Open a file readonly and set error if needed.
247
 */
248
extern int git_futils_open_ro(const char *path);
249 250

/**
251 252 253 254 255
 * Truncate a file, creating it if it doesn't exist.
 */
extern int git_futils_truncate(const char *path, int mode);

/**
Vicent Marti committed
256 257
 * Get the filesize in bytes of a file
 */
258
extern int git_futils_filesize(uint64_t *out, git_file fd);
259

260 261 262
#define GIT_PERMS_IS_EXEC(MODE)		(((MODE) & 0111) != 0)
#define GIT_PERMS_CANONICAL(MODE)	(GIT_PERMS_IS_EXEC(MODE) ? 0755 : 0644)
#define GIT_PERMS_FOR_WRITE(MODE)   (GIT_PERMS_IS_EXEC(MODE) ? 0777 : 0666)
263

264
#define GIT_MODE_PERMS_MASK			0777
265 266
#define GIT_MODE_TYPE_MASK			0170000
#define GIT_MODE_TYPE(MODE)			((MODE) & GIT_MODE_TYPE_MASK)
267
#define GIT_MODE_ISBLOB(MODE)		(GIT_MODE_TYPE(MODE) == GIT_MODE_TYPE(GIT_FILEMODE_BLOB))
268

269
/**
270 271 272 273 274 275
 * 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);


/**
276 277 278 279 280 281 282 283 284
 * 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.
285
 * @param len number of bytes to map.
286
 * @return
287 288
 * - 0 on success;
 * - -1 on error.
289
 */
Vicent Marti committed
290
extern int git_futils_mmap_ro(
291
	git_map *out,
292
	git_file fd,
293
	off64_t begin,
294 295 296
	size_t len);

/**
297 298 299 300 301
 * Read-only map an entire file.
 *
 * @param out buffer to populate with the mapping information.
 * @param path path to file to be opened.
 * @return
302 303 304
 * - 0 on success;
 * - GIT_ENOTFOUND if not found;
 * - -1 on an unspecified OS related error.
305 306 307 308 309 310
 */
extern int git_futils_mmap_ro_file(
	git_map *out,
	const char *path);

/**
311 312 313
 * Release the memory associated with a previous memory mapping.
 * @param map the mapping description previously configured.
 */
Vicent Marti committed
314
extern void git_futils_mmap_free(git_map *map);
315 316

/**
317 318
 * Create a "fake" symlink (text file containing the target path).
 *
319 320
 * @param target original symlink target
 * @param path symlink file to be created
321 322
 * @return 0 on success, -1 on error
 */
323
extern int git_futils_fake_symlink(const char *target, const char *path);
324

325 326 327 328 329 330
/**
 * 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.
 */
331
typedef struct {
332
	struct timespec mtime;
333
	uint64_t size;
334
	unsigned int ino;
Vicent Marti committed
335
} git_futils_filestamp;
336 337 338 339

/**
 * Compare stat information for file with reference info.
 *
340
 * This function updates the file stamp to current data for the given path
341 342
 * and returns 0 if the file is up-to-date relative to the prior setting,
 * 1 if the file has been changed, or GIT_ENOTFOUND if the file doesn't
343
 * exist.  This will not call git_error_set, so you must set the error if you
344
 * plan to return an error.
345
 *
346 347
 * @param stamp File stamp to be checked
 * @param path Path to stat and check if changed
348
 * @return 0 if up-to-date, 1 if out-of-date, GIT_ENOTFOUND if cannot stat
349
 */
Vicent Marti committed
350 351
extern int git_futils_filestamp_check(
	git_futils_filestamp *stamp, const char *path);
352 353 354 355 356 357 358 359 360 361 362

/**
 * 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
363 364
extern void git_futils_filestamp_set(
	git_futils_filestamp *tgt, const git_futils_filestamp *src);
365

366 367 368 369 370 371
/**
 * Set file stamp data from stat structure
 */
extern void git_futils_filestamp_set_from_stat(
	git_futils_filestamp *stamp, struct stat *st);

372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389
/**
 * `fsync` the parent directory of the given path, if `fsync` is
 * supported for directories on this platform.
 *
 * @param path Path of the directory to sync.
 * @return 0 on success, -1 on error
 */
extern int git_futils_fsync_dir(const char *path);

/**
 * `fsync` the parent directory of the given path, if `fsync` is
 * supported for directories on this platform.
 *
 * @param path Path of the file whose parent directory should be synced.
 * @return 0 on success, -1 on error
 */
extern int git_futils_fsync_parent(const char *path);

390
#endif