src/fileops.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_fileops_h__
   8 #define INCLUDE_fileops_h__
   9
  10 #include "common.h"
  11 #include "map.h"
  12 #include "posix.h"
  13 #include "path.h"
  14
  15 /**
  16  * Filebuffer methods
  17  *
  18  * Read whole files into an in-memory buffer for processing
  19  */
  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);
  24
  25 /**
  26  * File utils
  27  *
  28  * These are custom filesystem-related helper methods. They are
  29  * rather high level, and wrap the underlying POSIX methods
  30  *
  31  * All these methods return 0 on success,
  32  * or an error code on failure and an error message is set.
  33  */
  34
  35 /**
  36  * Create and open a file, while also
  37  * creating all the folders in its path
  38  */
  39 extern int git_futils_creat_withpath(const char *path, const mode_t dirmode, const mode_t mode);
  40
  41 /**
  42  * Create an open a process-locked file
  43  */
  44 extern int git_futils_creat_locked(const char *path, const mode_t mode);
  45
  46 /**
  47  * Create an open a process-locked file, while
  48  * also creating all the folders in its path
  49  */
  50 extern int git_futils_creat_locked_withpath(const char *path, const mode_t dirmode, const mode_t mode);
  51
  52 /**
  53  * Create a path recursively
  54  *
  55  * If a base parameter is being passed, it's expected to be valued with a
  56  * 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  * * GIT_MKDIR_EXCL is "exclusive" - i.e. generate an error if dir exists.
  64  * * GIT_MKDIR_PATH says to make all components in the path.
  65  * * GIT_MKDIR_CHMOD says to chmod the final directory entry after creation
  66  * * GIT_MKDIR_CHMOD_PATH says to chmod each directory component in the path
  67  * * 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  * Note that the chmod options will be executed even if the directory already
  72  * exists, unless GIT_MKDIR_EXCL is given.
  73  */
  74 typedef enum {
  75         GIT_MKDIR_EXCL = 1,
  76         GIT_MKDIR_PATH = 2,
  77         GIT_MKDIR_CHMOD = 4,
  78         GIT_MKDIR_CHMOD_PATH = 8,
  79         GIT_MKDIR_SKIP_LAST = 16,
  80         GIT_MKDIR_SKIP_LAST2 = 32,
  81         GIT_MKDIR_VERIFY_DIR = 64,
  82 } git_futils_mkdir_flags;
  83
  84 /**
  85  * Create a directory or entire path.
  86  *
  87  * This makes a directory (and the entire path leading up to it if requested),
  88  * and optionally chmods the directory immediately after (or each part of the
  89  * path if requested).
  90  *
  91  * @param path The path to create.
  92  * @param base Root for relative path.  These directories will never be made.
  93  * @param mode The mode to use for created directories.
  94  * @param flags Combination of the mkdir flags above.
  95  * @return 0 on success, else error code
  96  */
  97 extern int git_futils_mkdir(const char *path, const char *base, mode_t mode, uint32_t flags);
  98
  99 /**
 100  * Create all the folders required to contain
 101  * the full path of a file
 102  */
 103 extern int git_futils_mkpath2file(const char *path, const mode_t mode);
 104
 105 /**
 106  * Flags to pass to `git_futils_rmdir_r`.
 107  *
 108  * * GIT_RMDIR_EMPTY_HIERARCHY - the default; remove hierarchy of empty
 109  *       dirs and generate error if any files are found.
 110  * * GIT_RMDIR_REMOVE_FILES    - attempt to remove files in the hierarchy.
 111  * * GIT_RMDIR_SKIP_NONEMPTY   - skip non-empty directories with no error.
 112  * * GIT_RMDIR_EMPTY_PARENTS   - remove containing directories up to base
 113  *       if removing this item leaves them empty
 114  * * GIT_RMDIR_REMOVE_BLOCKERS - remove blocking file that causes ENOTDIR
 115  *
 116  * The old values translate into the new as follows:
 117  *
 118  * * GIT_DIRREMOVAL_EMPTY_HIERARCHY == GIT_RMDIR_EMPTY_HIERARCHY
 119  * * GIT_DIRREMOVAL_FILES_AND_DIRS  ~= GIT_RMDIR_REMOVE_FILES
 120  * * GIT_DIRREMOVAL_ONLY_EMPTY_DIRS == GIT_RMDIR_SKIP_NONEMPTY
 121  */
 122 typedef enum {
 123         GIT_RMDIR_EMPTY_HIERARCHY = 0,
 124         GIT_RMDIR_REMOVE_FILES    = (1 << 0),
 125         GIT_RMDIR_SKIP_NONEMPTY   = (1 << 1),
 126         GIT_RMDIR_EMPTY_PARENTS   = (1 << 2),
 127         GIT_RMDIR_REMOVE_BLOCKERS = (1 << 3),
 128 } git_futils_rmdir_flags;
 129
 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  * Remove all files and directories beneath the specified path.
 142  *
 143  * @param path Path to the top level directory to process.
 144  * @return 0 on success; -1 on error.
 145  */
 146 extern int git_futils_cleanupdir_r(const char *path);
 147
 148 /**
 149  * Create and open a temporary file with a `_git2_` suffix.
 150  * Writes the filename into path_out.
 151  * @return On success, an open file descriptor, else an error code < 0.
 152  */
 153 extern int git_futils_mktmp(git_buf *path_out, const char *filename);
 154
 155 /**
 156  * Move a file on the filesystem, create the
 157  * destination path if it doesn't exist
 158  */
 159 extern int git_futils_mv_withpath(const char *from, const char *to, const mode_t dirmode);
 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         const char *from,
 168         const char *to,
 169         mode_t filemode);
 170
 171 /**
 172  * Flags that can be passed to `git_futils_cp_r`.
 173  *
 174  * - GIT_CPDIR_CREATE_EMPTY_DIRS: create directories even if there are no
 175  *   files under them (otherwise directories will only be created lazily
 176  *   when a file inside them is copied).
 177  * - GIT_CPDIR_COPY_SYMLINKS: copy symlinks, otherwise they are ignored.
 178  * - GIT_CPDIR_COPY_DOTFILES: copy files with leading '.', otherwise ignored.
 179  * - GIT_CPDIR_OVERWRITE: overwrite pre-existing files with source content,
 180  *   otherwise they are silently skipped.
 181  * - GIT_CPDIR_CHMOD_DIRS: explicitly chmod directories to `dirmode`
 182  * - GIT_CPDIR_SIMPLE_TO_MODE: default tries to replicate the mode of the
 183  *   source file to the target; with this flag, always use 0666 (or 0777 if
 184  *   source has exec bits set) for target.
 185  */
 186 typedef enum {
 187         GIT_CPDIR_CREATE_EMPTY_DIRS = (1u << 0),
 188         GIT_CPDIR_COPY_SYMLINKS     = (1u << 1),
 189         GIT_CPDIR_COPY_DOTFILES     = (1u << 2),
 190         GIT_CPDIR_OVERWRITE         = (1u << 3),
 191         GIT_CPDIR_CHMOD_DIRS        = (1u << 4),
 192         GIT_CPDIR_SIMPLE_TO_MODE    = (1u << 5),
 193 } git_futils_cpdir_flags;
 194
 195 /**
 196  * Copy a directory tree.
 197  *
 198  * This copies directories and files from one root to another.  You can
 199  * pass a combinationof GIT_CPDIR flags as defined above.
 200  *
 201  * If you pass the CHMOD flag, then the dirmode will be applied to all
 202  * directories that are created during the copy, overiding the natural
 203  * permissions.  If you do not pass the CHMOD flag, then the dirmode
 204  * will actually be copied from the source files and the `dirmode` arg
 205  * will be ignored.
 206  */
 207 extern int git_futils_cp_r(
 208         const char *from,
 209         const char *to,
 210         uint32_t flags,
 211         mode_t dirmode);
 212
 213 /**
 214  * Open a file readonly and set error if needed.
 215  */
 216 extern int git_futils_open_ro(const char *path);
 217
 218 /**
 219  * Get the filesize in bytes of a file
 220  */
 221 extern git_off_t git_futils_filesize(git_file fd);
 222
 223 #define GIT_MODE_PERMS_MASK                     0777
 224 #define GIT_CANONICAL_PERMS(MODE)       (((MODE) & 0100) ? 0755 : 0644)
 225 #define GIT_MODE_TYPE(MODE)                     ((MODE) & ~GIT_MODE_PERMS_MASK)
 226
 227 /**
 228  * Convert a mode_t from the OS to a legal git mode_t value.
 229  */
 230 extern mode_t git_futils_canonical_mode(mode_t raw_mode);
 231
 232
 233 /**
 234  * Read-only map all or part of a file into memory.
 235  * When possible this function should favor a virtual memory
 236  * style mapping over some form of malloc()+read(), as the
 237  * data access will be random and is not likely to touch the
 238  * majority of the region requested.
 239  *
 240  * @param out buffer to populate with the mapping information.
 241  * @param fd open descriptor to configure the mapping from.
 242  * @param begin first byte to map, this should be page aligned.
 243  * @param end number of bytes to map.
 244  * @return
 245  * - 0 on success;
 246  * - -1 on error.
 247  */
 248 extern int git_futils_mmap_ro(
 249         git_map *out,
 250         git_file fd,
 251         git_off_t begin,
 252         size_t len);
 253
 254 /**
 255  * Read-only map an entire file.
 256  *
 257  * @param out buffer to populate with the mapping information.
 258  * @param path path to file to be opened.
 259  * @return
 260  * - 0 on success;
 261  * - GIT_ENOTFOUND if not found;
 262  * - -1 on an unspecified OS related error.
 263  */
 264 extern int git_futils_mmap_ro_file(
 265         git_map *out,
 266         const char *path);
 267
 268 /**
 269  * Release the memory associated with a previous memory mapping.
 270  * @param map the mapping description previously configured.
 271  */
 272 extern void git_futils_mmap_free(git_map *map);
 273
 274 /**
 275  * Find a "global" file (i.e. one in a user's home directory).
 276  *
 277  * @param pathbuf buffer to write the full path into
 278  * @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 extern int git_futils_find_global_file(git_buf *path, const char *filename);
 282
 283 /**
 284  * Find an "XDG" file (i.e. one in user's XDG config path).
 285  *
 286  * @param pathbuf buffer to write the full path into
 287  * @param filename name of file to find in the home directory
 288  * @return 0 if found, GIT_ENOTFOUND if not found, or -1 on other OS error
 289  */
 290 extern int git_futils_find_xdg_file(git_buf *path, const char *filename);
 291
 292 /**
 293  * Find a "system" file (i.e. one shared for all users of the system).
 294  *
 295  * @param pathbuf buffer to write the full path into
 296  * @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 extern int git_futils_find_system_file(git_buf *path, const char *filename);
 300
 301 typedef enum {
 302         GIT_FUTILS_DIR_SYSTEM = 0,
 303         GIT_FUTILS_DIR_GLOBAL = 1,
 304         GIT_FUTILS_DIR_XDG    = 2,
 305         GIT_FUTILS_DIR__MAX   = 3,
 306 } git_futils_dir_t;
 307
 308 /**
 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  * @return 0 on success, <0 on failure
 314  */
 315 extern int git_futils_dirs_get(const git_buf **out, git_futils_dir_t which);
 316
 317 /**
 318  * Get search path into a preallocated buffer
 319  *
 320  * @param out String buffer to write into
 321  * @param outlen Size of string buffer
 322  * @param which Which search path to return
 323  * @return 0 on success, GIT_EBUFS if out is too small, <0 on other failure
 324  */
 325
 326 extern int git_futils_dirs_get_str(
 327         char *out, size_t outlen, git_futils_dir_t which);
 328
 329 /**
 330  * Set search paths for global/system/xdg files
 331  *
 332  * The first occurrence of the magic string "$PATH" in the new value will
 333  * be replaced with the old value of the search path.
 334  *
 335  * @param which Which search path to modify
 336  * @param paths New search path (separated by GIT_PATH_LIST_SEPARATOR)
 337  * @return 0 on success, <0 on failure (allocation error)
 338  */
 339 extern int git_futils_dirs_set(git_futils_dir_t which, const char *paths);
 340
 341 /**
 342  * Release / reset all search paths
 343  */
 344 extern void git_futils_dirs_free(void);
 345
 346 /**
 347  * Create a "fake" symlink (text file containing the target path).
 348  *
 349  * @param new symlink file to be created
 350  * @param old original symlink target
 351  * @return 0 on success, -1 on error
 352  */
 353 extern int git_futils_fake_symlink(const char *new, const char *old);
 354
 355 /**
 356  * A file stamp represents a snapshot of information about a file that can
 357  * be used to test if the file changes.  This portable implementation is
 358  * based on stat data about that file, but it is possible that OS specific
 359  * versions could be implemented in the future.
 360  */
 361 typedef struct {
 362         git_time_t mtime;
 363         git_off_t  size;
 364         unsigned int ino;
 365 } git_futils_filestamp;
 366
 367 /**
 368  * Compare stat information for file with reference info.
 369  *
 370  * This function updates the file stamp to current data for the given path
 371  * and returns 0 if the file is up-to-date relative to the prior setting or
 372  * 1 if the file has been changed.  (This also may return GIT_ENOTFOUND if
 373  * the file doesn't exist.)
 374  *
 375  * @param stamp File stamp to be checked
 376  * @param path Path to stat and check if changed
 377  * @return 0 if up-to-date, 1 if out-of-date, <0 on error
 378  */
 379 extern int git_futils_filestamp_check(
 380         git_futils_filestamp *stamp, const char *path);
 381
 382 /**
 383  * Set or reset file stamp data
 384  *
 385  * This writes the target file stamp.  If the source is NULL, this will set
 386  * the target stamp to values that will definitely be out of date.  If the
 387  * source is not NULL, this copies the source values to the target.
 388  *
 389  * @param tgt File stamp to write to
 390  * @param src File stamp to copy from or NULL to clear the target
 391  */
 392 extern void git_futils_filestamp_set(
 393         git_futils_filestamp *tgt, const git_futils_filestamp *src);
 394
 395 #endif /* INCLUDE_fileops_h__ */