src/util/futils.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   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.
   6  */
   7 #ifndef INCLUDE_futils_h__
   8 #define INCLUDE_futils_h__
   9
  10 #include "git2_util.h"
  11
  12 #include "map.h"
  13 #include "posix.h"
  14 #include "fs_path.h"
  15 #include "pool.h"
  16 #include "strmap.h"
  17 #include "hash.h"
  18
  19 /**
  20  * Filebuffer methods
  21  *
  22  * Read whole files into an in-memory buffer for processing
  23  */
  24 extern int git_futils_readbuffer(git_str *obj, const char *path);
  25 extern int git_futils_readbuffer_updated(
  26         git_str *obj,
  27         const char *path,
  28         unsigned char checksum[GIT_HASH_SHA1_SIZE],
  29         int *updated);
  30 extern int git_futils_readbuffer_fd_full(git_str *obj, git_file fd);
  31 extern int git_futils_readbuffer_fd(git_str *obj, git_file fd, size_t len);
  32
  33 /* Additional constants for `git_futils_writebuffer`'s `open_flags`.  We
  34  * support these internally and they will be removed before the `open` call.
  35  */
  36 #ifndef O_FSYNC
  37 # define O_FSYNC (1 << 31)
  38 #endif
  39
  40 extern int git_futils_writebuffer(
  41         const git_str *buf, const char *path, int open_flags, mode_t mode);
  42
  43 /**
  44  * File utils
  45  *
  46  * These are custom filesystem-related helper methods. They are
  47  * rather high level, and wrap the underlying POSIX methods
  48  *
  49  * All these methods return 0 on success,
  50  * or an error code on failure and an error message is set.
  51  */
  52
  53 /**
  54  * Create and open a file, while also
  55  * creating all the folders in its path
  56  */
  57 extern int git_futils_creat_withpath(const char *path, const mode_t dirmode, const mode_t mode);
  58
  59 /**
  60  * Create and open a process-locked file
  61  */
  62 extern int git_futils_creat_locked(const char *path, const mode_t mode);
  63
  64 /**
  65  * Create and open a process-locked file, while
  66  * also creating all the folders in its path
  67  */
  68 extern int git_futils_creat_locked_withpath(const char *path, const mode_t dirmode, const mode_t mode);
  69
  70 /**
  71  * Create a path recursively.
  72  */
  73 extern int git_futils_mkdir_r(const char *path, const mode_t mode);
  74
  75 /**
  76  * Flags to pass to `git_futils_mkdir`.
  77  *
  78  * * GIT_MKDIR_EXCL is "exclusive" - i.e. generate an error if dir exists.
  79  * * GIT_MKDIR_PATH says to make all components in the path.
  80  * * GIT_MKDIR_CHMOD says to chmod the final directory entry after creation
  81  * * GIT_MKDIR_CHMOD_PATH says to chmod each directory component in the path
  82  * * GIT_MKDIR_SKIP_LAST says to leave off the last element of the path
  83  * * GIT_MKDIR_SKIP_LAST2 says to leave off the last 2 elements of the path
  84  * * GIT_MKDIR_VERIFY_DIR says confirm final item is a dir, not just EEXIST
  85  * * GIT_MKDIR_REMOVE_FILES says to remove files and recreate dirs
  86  * * GIT_MKDIR_REMOVE_SYMLINKS says to remove symlinks and recreate dirs
  87  *
  88  * Note that the chmod options will be executed even if the directory already
  89  * exists, unless GIT_MKDIR_EXCL is given.
  90  */
  91 typedef enum {
  92         GIT_MKDIR_EXCL = 1,
  93         GIT_MKDIR_PATH = 2,
  94         GIT_MKDIR_CHMOD = 4,
  95         GIT_MKDIR_CHMOD_PATH = 8,
  96         GIT_MKDIR_SKIP_LAST = 16,
  97         GIT_MKDIR_SKIP_LAST2 = 32,
  98         GIT_MKDIR_VERIFY_DIR = 64,
  99         GIT_MKDIR_REMOVE_FILES = 128,
 100         GIT_MKDIR_REMOVE_SYMLINKS = 256
 101 } git_futils_mkdir_flags;
 102
 103 struct git_futils_mkdir_perfdata
 104 {
 105         size_t stat_calls;
 106         size_t mkdir_calls;
 107         size_t chmod_calls;
 108 };
 109
 110 struct git_futils_mkdir_options
 111 {
 112         git_strmap *dir_map;
 113         git_pool *pool;
 114         struct git_futils_mkdir_perfdata perfdata;
 115 };
 116
 117 /**
 118  * Create a directory or entire path.
 119  *
 120  * This makes a directory (and the entire path leading up to it if requested),
 121  * and optionally chmods the directory immediately after (or each part of the
 122  * path if requested).
 123  *
 124  * @param path The path to create, relative to base.
 125  * @param base Root for relative path.  These directories will never be made.
 126  * @param mode The mode to use for created directories.
 127  * @param flags Combination of the mkdir flags above.
 128  * @param opts Extended options, or null.
 129  * @return 0 on success, else error code
 130  */
 131 extern int git_futils_mkdir_relative(const char *path, const char *base, mode_t mode, uint32_t flags, struct git_futils_mkdir_options *opts);
 132
 133 /**
 134  * Create a directory or entire path.  Similar to `git_futils_mkdir_relative`
 135  * without performance data.
 136  */
 137 extern int git_futils_mkdir(const char *path, mode_t mode, uint32_t flags);
 138
 139 /**
 140  * Create all the folders required to contain
 141  * the full path of a file
 142  */
 143 extern int git_futils_mkpath2file(const char *path, const mode_t mode);
 144
 145 /**
 146  * Flags to pass to `git_futils_rmdir_r`.
 147  *
 148  * * GIT_RMDIR_EMPTY_HIERARCHY - the default; remove hierarchy of empty
 149  *       dirs and generate error if any files are found.
 150  * * GIT_RMDIR_REMOVE_FILES    - attempt to remove files in the hierarchy.
 151  * * GIT_RMDIR_SKIP_NONEMPTY   - skip non-empty directories with no error.
 152  * * GIT_RMDIR_EMPTY_PARENTS   - remove containing directories up to base
 153  *       if removing this item leaves them empty
 154  * * GIT_RMDIR_REMOVE_BLOCKERS - remove blocking file that causes ENOTDIR
 155  * * GIT_RMDIR_SKIP_ROOT       - don't remove root directory itself
 156  */
 157 typedef enum {
 158         GIT_RMDIR_EMPTY_HIERARCHY = 0,
 159         GIT_RMDIR_REMOVE_FILES    = (1 << 0),
 160         GIT_RMDIR_SKIP_NONEMPTY   = (1 << 1),
 161         GIT_RMDIR_EMPTY_PARENTS   = (1 << 2),
 162         GIT_RMDIR_REMOVE_BLOCKERS = (1 << 3),
 163         GIT_RMDIR_SKIP_ROOT       = (1 << 4)
 164 } git_futils_rmdir_flags;
 165
 166 /**
 167  * Remove path and any files and directories beneath it.
 168  *
 169  * @param path Path to the top level directory to process.
 170  * @param base Root for relative path.
 171  * @param flags Combination of git_futils_rmdir_flags values
 172  * @return 0 on success; -1 on error.
 173  */
 174 extern int git_futils_rmdir_r(const char *path, const char *base, uint32_t flags);
 175
 176 /**
 177  * Create and open a temporary file with a `_git2_` suffix in a
 178  * protected directory; the file created will created will honor
 179  * the current `umask`.  Writes the filename into path_out.
 180  *
 181  * This function uses a high-quality PRNG seeded by the system's
 182  * entropy pool _where available_ and falls back to a simple seed
 183  * (time plus system information) when not.  This is suitable for
 184  * writing within a protected directory, but the system's safe
 185  * temporary file creation functions should be preferred where
 186  * available when writing into world-writable (temp) directories.
 187  *
 188  * @return On success, an open file descriptor, else an error code < 0.
 189  */
 190 extern int git_futils_mktmp(git_str *path_out, const char *filename, mode_t mode);
 191
 192 /**
 193  * Move a file on the filesystem, create the
 194  * destination path if it doesn't exist
 195  */
 196 extern int git_futils_mv_withpath(const char *from, const char *to, const mode_t dirmode);
 197
 198 /**
 199  * Copy a file
 200  *
 201  * The filemode will be used for the newly created file.
 202  */
 203 extern int git_futils_cp(
 204         const char *from,
 205         const char *to,
 206         mode_t filemode);
 207
 208 /**
 209  * Set the files atime and mtime to the given time, or the current time
 210  * if `ts` is NULL.
 211  */
 212 extern int git_futils_touch(const char *path, time_t *when);
 213
 214 /**
 215  * Flags that can be passed to `git_futils_cp_r`.
 216  *
 217  * - GIT_CPDIR_CREATE_EMPTY_DIRS: create directories even if there are no
 218  *   files under them (otherwise directories will only be created lazily
 219  *   when a file inside them is copied).
 220  * - GIT_CPDIR_COPY_SYMLINKS: copy symlinks, otherwise they are ignored.
 221  * - GIT_CPDIR_COPY_DOTFILES: copy files with leading '.', otherwise ignored.
 222  * - GIT_CPDIR_OVERWRITE: overwrite pre-existing files with source content,
 223  *   otherwise they are silently skipped.
 224  * - GIT_CPDIR_CHMOD_DIRS: explicitly chmod directories to `dirmode`
 225  * - GIT_CPDIR_SIMPLE_TO_MODE: default tries to replicate the mode of the
 226  *   source file to the target; with this flag, always use 0666 (or 0777 if
 227  *   source has exec bits set) for target.
 228  * - GIT_CPDIR_LINK_FILES will try to use hardlinks for the files
 229  */
 230 typedef enum {
 231         GIT_CPDIR_CREATE_EMPTY_DIRS = (1u << 0),
 232         GIT_CPDIR_COPY_SYMLINKS     = (1u << 1),
 233         GIT_CPDIR_COPY_DOTFILES     = (1u << 2),
 234         GIT_CPDIR_OVERWRITE         = (1u << 3),
 235         GIT_CPDIR_CHMOD_DIRS        = (1u << 4),
 236         GIT_CPDIR_SIMPLE_TO_MODE    = (1u << 5),
 237         GIT_CPDIR_LINK_FILES        = (1u << 6)
 238 } git_futils_cpdir_flags;
 239
 240 /**
 241  * Copy a directory tree.
 242  *
 243  * This copies directories and files from one root to another.  You can
 244  * pass a combination of GIT_CPDIR flags as defined above.
 245  *
 246  * If you pass the CHMOD flag, then the dirmode will be applied to all
 247  * directories that are created during the copy, overriding the natural
 248  * permissions.  If you do not pass the CHMOD flag, then the dirmode
 249  * will actually be copied from the source files and the `dirmode` arg
 250  * will be ignored.
 251  */
 252 extern int git_futils_cp_r(
 253         const char *from,
 254         const char *to,
 255         uint32_t flags,
 256         mode_t dirmode);
 257
 258 /**
 259  * Open a file readonly and set error if needed.
 260  */
 261 extern int git_futils_open_ro(const char *path);
 262
 263 /**
 264  * Truncate a file, creating it if it doesn't exist.
 265  */
 266 extern int git_futils_truncate(const char *path, int mode);
 267
 268 /**
 269  * Get the filesize in bytes of a file
 270  */
 271 extern int git_futils_filesize(uint64_t *out, git_file fd);
 272
 273 #define GIT_PERMS_IS_EXEC(MODE)         (((MODE) & 0100) != 0)
 274 #define GIT_PERMS_CANONICAL(MODE)       (GIT_PERMS_IS_EXEC(MODE) ? 0755 : 0644)
 275 #define GIT_PERMS_FOR_WRITE(MODE)   (GIT_PERMS_IS_EXEC(MODE) ? 0777 : 0666)
 276
 277 #define GIT_MODE_PERMS_MASK                     0777
 278 #define GIT_MODE_TYPE_MASK                      0170000
 279 #define GIT_MODE_TYPE(MODE)                     ((MODE) & GIT_MODE_TYPE_MASK)
 280 #define GIT_MODE_ISBLOB(MODE)           (GIT_MODE_TYPE(MODE) == GIT_MODE_TYPE(GIT_FILEMODE_BLOB))
 281
 282 /**
 283  * Convert a mode_t from the OS to a legal git mode_t value.
 284  */
 285 extern mode_t git_futils_canonical_mode(mode_t raw_mode);
 286
 287
 288 /**
 289  * Read-only map all or part of a file into memory.
 290  * When possible this function should favor a virtual memory
 291  * style mapping over some form of malloc()+read(), as the
 292  * data access will be random and is not likely to touch the
 293  * majority of the region requested.
 294  *
 295  * @param out buffer to populate with the mapping information.
 296  * @param fd open descriptor to configure the mapping from.
 297  * @param begin first byte to map, this should be page aligned.
 298  * @param len number of bytes to map.
 299  * @return
 300  * - 0 on success;
 301  * - -1 on error.
 302  */
 303 extern int git_futils_mmap_ro(
 304         git_map *out,
 305         git_file fd,
 306         off64_t begin,
 307         size_t len);
 308
 309 /**
 310  * Read-only map an entire file.
 311  *
 312  * @param out buffer to populate with the mapping information.
 313  * @param path path to file to be opened.
 314  * @return
 315  * - 0 on success;
 316  * - GIT_ENOTFOUND if not found;
 317  * - -1 on an unspecified OS related error.
 318  */
 319 extern int git_futils_mmap_ro_file(
 320         git_map *out,
 321         const char *path);
 322
 323 /**
 324  * Release the memory associated with a previous memory mapping.
 325  * @param map the mapping description previously configured.
 326  */
 327 extern void git_futils_mmap_free(git_map *map);
 328
 329 /**
 330  * Create a "fake" symlink (text file containing the target path).
 331  *
 332  * @param target original symlink target
 333  * @param path symlink file to be created
 334  * @return 0 on success, -1 on error
 335  */
 336 extern int git_futils_fake_symlink(const char *target, const char *path);
 337
 338 /**
 339  * A file stamp represents a snapshot of information about a file that can
 340  * be used to test if the file changes.  This portable implementation is
 341  * based on stat data about that file, but it is possible that OS specific
 342  * versions could be implemented in the future.
 343  */
 344 typedef struct {
 345         struct timespec mtime;
 346         uint64_t size;
 347         unsigned int ino;
 348 } git_futils_filestamp;
 349
 350 /**
 351  * Compare stat information for file with reference info.
 352  *
 353  * This function updates the file stamp to current data for the given path
 354  * and returns 0 if the file is up-to-date relative to the prior setting,
 355  * 1 if the file has been changed, or GIT_ENOTFOUND if the file doesn't
 356  * exist.  This will not call git_error_set, so you must set the error if you
 357  * plan to return an error.
 358  *
 359  * @param stamp File stamp to be checked
 360  * @param path Path to stat and check if changed
 361  * @return 0 if up-to-date, 1 if out-of-date, GIT_ENOTFOUND if cannot stat
 362  */
 363 extern int git_futils_filestamp_check(
 364         git_futils_filestamp *stamp, const char *path);
 365
 366 /**
 367  * Set or reset file stamp data
 368  *
 369  * This writes the target file stamp.  If the source is NULL, this will set
 370  * the target stamp to values that will definitely be out of date.  If the
 371  * source is not NULL, this copies the source values to the target.
 372  *
 373  * @param tgt File stamp to write to
 374  * @param src File stamp to copy from or NULL to clear the target
 375  */
 376 extern void git_futils_filestamp_set(
 377         git_futils_filestamp *tgt, const git_futils_filestamp *src);
 378
 379 /**
 380  * Set file stamp data from stat structure
 381  */
 382 extern void git_futils_filestamp_set_from_stat(
 383         git_futils_filestamp *stamp, struct stat *st);
 384
 385 /**
 386  * `fsync` the parent directory of the given path, if `fsync` is
 387  * supported for directories on this platform.
 388  *
 389  * @param path Path of the directory to sync.
 390  * @return 0 on success, -1 on error
 391  */
 392 extern int git_futils_fsync_dir(const char *path);
 393
 394 /**
 395  * `fsync` the parent directory of the given path, if `fsync` is
 396  * supported for directories on this platform.
 397  *
 398  * @param path Path of the file whose parent directory should be synced.
 399  * @return 0 on success, -1 on error
 400  */
 401 extern int git_futils_fsync_parent(const char *path);
 402
 403 #endif