Andrew's git - gitweb.git/blob

   1#ifndef LOCKFILE_H
   2#define LOCKFILE_H
   3
   4/*
   5 * File write-locks as used by Git.
   6 *
   7 * For an overview of how to use the lockfile API, please see
   8 *
   9 *     Documentation/technical/api-lockfile.txt
  10 *
  11 * This module keeps track of all locked files in lock_file_list for
  12 * use at cleanup. This list and the lock_file objects that comprise
  13 * it must be kept in self-consistent states at all time, because the
  14 * program can be interrupted any time by a signal, in which case the
  15 * signal handler will walk through the list attempting to clean up
  16 * any open lock files.
  17 *
  18 * A lockfile is owned by the process that created it. The lock_file
  19 * object has an "owner" field that records its owner. This field is
  20 * used to prevent a forked process from closing a lockfile created by
  21 * its parent.
  22 *
  23 * The possible states of a lock_file object are as follows:
  24 *
  25 * - Uninitialized.  In this state the object's on_list field must be
  26 *   zero but the rest of its contents need not be initialized.  As
  27 *   soon as the object is used in any way, it is irrevocably
  28 *   registered in the lock_file_list, and on_list is set.
  29 *
  30 * - Locked, lockfile open (after hold_lock_file_for_update(),
  31 *   hold_lock_file_for_append(), or reopen_lock_file()). In this
  32 *   state:
  33 *   - the lockfile exists
  34 *   - active is set
  35 *   - filename holds the filename of the lockfile
  36 *   - fd holds a file descriptor open for writing to the lockfile
  37 *   - fp holds a pointer to an open FILE object if and only if
  38 *     fdopen_lock_file() has been called on the object
  39 *   - owner holds the PID of the process that locked the file
  40 *
  41 * - Locked, lockfile closed (after successful close_lock_file()).
  42 *   Same as the previous state, except that the lockfile is closed
  43 *   and fd is -1.
  44 *
  45 * - Unlocked (after commit_lock_file(), commit_lock_file_to(),
  46 *   rollback_lock_file(), a failed attempt to lock, or a failed
  47 *   close_lock_file()).  In this state:
  48 *   - active is unset
  49 *   - filename is empty (usually, though there are transitory
  50 *     states in which this condition doesn't hold). Client code should
  51 *     *not* rely on the filename being empty in this state.
  52 *   - fd is -1
  53 *   - the object is left registered in the lock_file_list, and
  54 *     on_list is set.
  55 */
  56
  57struct lock_file {
  58        struct lock_file *volatile next;
  59        volatile sig_atomic_t active;
  60        volatile int fd;
  61        FILE *volatile fp;
  62        volatile pid_t owner;
  63        char on_list;
  64        struct strbuf filename;
  65};
  66
  67/* String appended to a filename to derive the lockfile name: */
  68#define LOCK_SUFFIX ".lock"
  69#define LOCK_SUFFIX_LEN 5
  70
  71#define LOCK_DIE_ON_ERROR 1
  72#define LOCK_NO_DEREF 2
  73
  74extern void unable_to_lock_message(const char *path, int err,
  75                                   struct strbuf *buf);
  76extern NORETURN void unable_to_lock_die(const char *path, int err);
  77extern int hold_lock_file_for_update_timeout(
  78                struct lock_file *lk, const char *path,
  79                int flags, long timeout_ms);
  80
  81static inline int hold_lock_file_for_update(
  82                struct lock_file *lk, const char *path,
  83                int flags)
  84{
  85        return hold_lock_file_for_update_timeout(lk, path, flags, 0);
  86}
  87
  88extern int hold_lock_file_for_append(struct lock_file *lk, const char *path,
  89                                     int flags);
  90
  91extern FILE *fdopen_lock_file(struct lock_file *, const char *mode);
  92extern char *get_locked_file_path(struct lock_file *);
  93extern int commit_lock_file_to(struct lock_file *, const char *path);
  94extern int commit_lock_file(struct lock_file *);
  95extern int reopen_lock_file(struct lock_file *);
  96extern int close_lock_file(struct lock_file *);
  97extern void rollback_lock_file(struct lock_file *);
  98
  99#endif /* LOCKFILE_H */