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 extern int git_futils_writebuffer(
  26         const git_buf *buf, const char *path, int open_flags, mode_t mode);
  27
  28 /**
  29  * File utils
  30  *
  31  * These are custom filesystem-related helper methods. They are
  32  * rather high level, and wrap the underlying POSIX methods
  33  *
  34  * All these methods return 0 on success,
  35  * or an error code on failure and an error message is set.
  36  */
  37
  38 /**
  39  * Create and open a file, while also
  40  * creating all the folders in its path
  41  */
  42 extern int git_futils_creat_withpath(const char *path, const mode_t dirmode, const mode_t mode);
  43
  44 /**
  45  * Create an open a process-locked file
  46  */
  47 extern int git_futils_creat_locked(const char *path, const mode_t mode);
  48
  49 /**
  50  * Create an open a process-locked file, while
  51  * also creating all the folders in its path
  52  */
  53 extern int git_futils_creat_locked_withpath(const char *path, const mode_t dirmode, const mode_t mode);
  54
  55 /**
  56  * Create a path recursively
  57  *
  58  * If a base parameter is being passed, it's expected to be valued with a
  59  * path pointing to an already existing directory.
  60  */
  61 extern int git_futils_mkdir_r(const char *path, const char *base, const mode_t mode);
  62
  63 /**
  64  * Flags to pass to `git_futils_mkdir`.
  65  *
  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
  73  *
  74  * Note that the chmod options will be executed even if the directory already
  75  * exists, unless GIT_MKDIR_EXCL is given.
  76  */
  77 typedef enum {
  78         GIT_MKDIR_EXCL = 1,
  79         GIT_MKDIR_PATH = 2,
  80         GIT_MKDIR_CHMOD = 4,
  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;
  86
  87 /**
  88  * Create a directory or entire path.
  89  *
  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
  92  * path if requested).
  93  *
  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
  99  */
 100 extern int git_futils_mkdir(const char *path, const char *base, mode_t mode, uint32_t flags);
 101
 102 /**
 103  * Create all the folders required to contain
 104  * the full path of a file
 105  */
 106 extern int git_futils_mkpath2file(const char *path, const mode_t mode);
 107
 108 /**
 109  * Flags to pass to `git_futils_rmdir_r`.
 110  *
 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
 118  * * GIT_RMDIR_SKIP_ROOT       - don't remove root directory itself
 119  */
 120 typedef enum {
 121         GIT_RMDIR_EMPTY_HIERARCHY = 0,
 122         GIT_RMDIR_REMOVE_FILES    = (1 << 0),
 123         GIT_RMDIR_SKIP_NONEMPTY   = (1 << 1),
 124         GIT_RMDIR_EMPTY_PARENTS   = (1 << 2),
 125         GIT_RMDIR_REMOVE_BLOCKERS = (1 << 3),
 126         GIT_RMDIR_SKIP_ROOT       = (1 << 4),
 127 } git_futils_rmdir_flags;
 128
 129 /**
 130  * Remove path and any files and directories beneath it.
 131  *
 132  * @param path Path to the top level directory to process.
 133  * @param base Root for relative path.
 134  * @param flags Combination of git_futils_rmdir_flags values
 135  * @return 0 on success; -1 on error.
 136  */
 137 extern int git_futils_rmdir_r(const char *path, const char *base, uint32_t flags);
 138
 139 /**
 140  * Create and open a temporary file with a `_git2_` suffix.
 141  * Writes the filename into path_out.
 142  * @return On success, an open file descriptor, else an error code < 0.
 143  */
 144 extern int git_futils_mktmp(git_buf *path_out, const char *filename, mode_t mode);
 145
 146 /**
 147  * Move a file on the filesystem, create the
 148  * destination path if it doesn't exist
 149  */
 150 extern int git_futils_mv_withpath(const char *from, const char *to, const mode_t dirmode);
 151
 152 /**
 153  * Copy a file
 154  *
 155  * The filemode will be used for the newly created file.
 156  */
 157 extern int git_futils_cp(
 158         const char *from,
 159         const char *to,
 160         mode_t filemode);
 161
 162 /**
 163  * Flags that can be passed to `git_futils_cp_r`.
 164  *
 165  * - GIT_CPDIR_CREATE_EMPTY_DIRS: create directories even if there are no
 166  *   files under them (otherwise directories will only be created lazily
 167  *   when a file inside them is copied).
 168  * - GIT_CPDIR_COPY_SYMLINKS: copy symlinks, otherwise they are ignored.
 169  * - GIT_CPDIR_COPY_DOTFILES: copy files with leading '.', otherwise ignored.
 170  * - GIT_CPDIR_OVERWRITE: overwrite pre-existing files with source content,
 171  *   otherwise they are silently skipped.
 172  * - GIT_CPDIR_CHMOD_DIRS: explicitly chmod directories to `dirmode`
 173  * - GIT_CPDIR_SIMPLE_TO_MODE: default tries to replicate the mode of the
 174  *   source file to the target; with this flag, always use 0666 (or 0777 if
 175  *   source has exec bits set) for target.
 176  */
 177 typedef enum {
 178         GIT_CPDIR_CREATE_EMPTY_DIRS = (1u << 0),
 179         GIT_CPDIR_COPY_SYMLINKS     = (1u << 1),
 180         GIT_CPDIR_COPY_DOTFILES     = (1u << 2),
 181         GIT_CPDIR_OVERWRITE         = (1u << 3),
 182         GIT_CPDIR_CHMOD_DIRS        = (1u << 4),
 183         GIT_CPDIR_SIMPLE_TO_MODE    = (1u << 5),
 184 } git_futils_cpdir_flags;
 185
 186 /**
 187  * Copy a directory tree.
 188  *
 189  * This copies directories and files from one root to another.  You can
 190  * pass a combinationof GIT_CPDIR flags as defined above.
 191  *
 192  * If you pass the CHMOD flag, then the dirmode will be applied to all
 193  * directories that are created during the copy, overiding the natural
 194  * permissions.  If you do not pass the CHMOD flag, then the dirmode
 195  * will actually be copied from the source files and the `dirmode` arg
 196  * will be ignored.
 197  */
 198 extern int git_futils_cp_r(
 199         const char *from,
 200         const char *to,
 201         uint32_t flags,
 202         mode_t dirmode);
 203
 204 /**
 205  * Open a file readonly and set error if needed.
 206  */
 207 extern int git_futils_open_ro(const char *path);
 208
 209 /**
 210  * Get the filesize in bytes of a file
 211  */
 212 extern git_off_t git_futils_filesize(git_file fd);
 213
 214 #define GIT_PERMS_IS_EXEC(MODE)         (((MODE) & 0111) != 0)
 215 #define GIT_PERMS_CANONICAL(MODE)       (GIT_PERMS_IS_EXEC(MODE) ? 0755 : 0644)
 216 #define GIT_PERMS_FOR_WRITE(MODE)   (GIT_PERMS_IS_EXEC(MODE) ? 0777 : 0666)
 217
 218 #define GIT_MODE_PERMS_MASK                     0777
 219 #define GIT_MODE_TYPE_MASK                      0170000
 220 #define GIT_MODE_TYPE(MODE)                     ((MODE) & GIT_MODE_TYPE_MASK)
 221 #define GIT_MODE_ISBLOB(MODE)           (GIT_MODE_TYPE(MODE) == GIT_MODE_TYPE(GIT_FILEMODE_BLOB))
 222
 223 /**
 224  * Convert a mode_t from the OS to a legal git mode_t value.
 225  */
 226 extern mode_t git_futils_canonical_mode(mode_t raw_mode);
 227
 228
 229 /**
 230  * Read-only map all or part of a file into memory.
 231  * When possible this function should favor a virtual memory
 232  * style mapping over some form of malloc()+read(), as the
 233  * data access will be random and is not likely to touch the
 234  * majority of the region requested.
 235  *
 236  * @param out buffer to populate with the mapping information.
 237  * @param fd open descriptor to configure the mapping from.
 238  * @param begin first byte to map, this should be page aligned.
 239  * @param len number of bytes to map.
 240  * @return
 241  * - 0 on success;
 242  * - -1 on error.
 243  */
 244 extern int git_futils_mmap_ro(
 245         git_map *out,
 246         git_file fd,
 247         git_off_t begin,
 248         size_t len);
 249
 250 /**
 251  * Read-only map an entire file.
 252  *
 253  * @param out buffer to populate with the mapping information.
 254  * @param path path to file to be opened.
 255  * @return
 256  * - 0 on success;
 257  * - GIT_ENOTFOUND if not found;
 258  * - -1 on an unspecified OS related error.
 259  */
 260 extern int git_futils_mmap_ro_file(
 261         git_map *out,
 262         const char *path);
 263
 264 /**
 265  * Release the memory associated with a previous memory mapping.
 266  * @param map the mapping description previously configured.
 267  */
 268 extern void git_futils_mmap_free(git_map *map);
 269
 270 /**
 271  * Create a "fake" symlink (text file containing the target path).
 272  *
 273  * @param new symlink file to be created
 274  * @param old original symlink target
 275  * @return 0 on success, -1 on error
 276  */
 277 extern int git_futils_fake_symlink(const char *new, const char *old);
 278
 279 /**
 280  * A file stamp represents a snapshot of information about a file that can
 281  * be used to test if the file changes.  This portable implementation is
 282  * based on stat data about that file, but it is possible that OS specific
 283  * versions could be implemented in the future.
 284  */
 285 typedef struct {
 286         git_time_t mtime;
 287         git_off_t  size;
 288         unsigned int ino;
 289 } git_futils_filestamp;
 290
 291 /**
 292  * Compare stat information for file with reference info.
 293  *
 294  * This function updates the file stamp to current data for the given path
 295  * and returns 0 if the file is up-to-date relative to the prior setting or
 296  * 1 if the file has been changed.  (This also may return GIT_ENOTFOUND if
 297  * the file doesn't exist.)
 298  *
 299  * @param stamp File stamp to be checked
 300  * @param path Path to stat and check if changed
 301  * @return 0 if up-to-date, 1 if out-of-date, <0 on error
 302  */
 303 extern int git_futils_filestamp_check(
 304         git_futils_filestamp *stamp, const char *path);
 305
 306 /**
 307  * Set or reset file stamp data
 308  *
 309  * This writes the target file stamp.  If the source is NULL, this will set
 310  * the target stamp to values that will definitely be out of date.  If the
 311  * source is not NULL, this copies the source values to the target.
 312  *
 313  * @param tgt File stamp to write to
 314  * @param src File stamp to copy from or NULL to clear the target
 315  */
 316 extern void git_futils_filestamp_set(
 317         git_futils_filestamp *tgt, const git_futils_filestamp *src);
 318
 319 #endif /* INCLUDE_fileops_h__ */