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