lockfile.h

   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  *   - owner holds the PID of the process that locked the file
  38  *
  39  * - Locked, lockfile closed (after successful close_lock_file()).
  40  *   Same as the previous state, except that the lockfile is closed
  41  *   and fd is -1.
  42  *
  43  * - Unlocked (after commit_lock_file(), commit_lock_file_to(),
  44  *   rollback_lock_file(), a failed attempt to lock, or a failed
  45  *   close_lock_file()).  In this state:
  46  *   - active is unset
  47  *   - filename is empty (usually, though there are transitory
  48  *     states in which this condition doesn't hold). Client code should
  49  *     *not* rely on the filename being empty in this state.
  50  *   - fd is -1
  51  *   - the object is left registered in the lock_file_list, and
  52  *     on_list is set.
  53  */
  54
  55 struct lock_file {
  56         struct lock_file *volatile next;
  57         volatile sig_atomic_t active;
  58         volatile int fd;
  59         volatile pid_t owner;
  60         char on_list;
  61         struct strbuf filename;
  62 };
  63
  64 /* String appended to a filename to derive the lockfile name: */
  65 #define LOCK_SUFFIX ".lock"
  66 #define LOCK_SUFFIX_LEN 5
  67
  68 #define LOCK_DIE_ON_ERROR 1
  69 #define LOCK_NO_DEREF 2
  70
  71 extern int unable_to_lock_error(const char *path, int err);
  72 extern void unable_to_lock_message(const char *path, int err,
  73                                    struct strbuf *buf);
  74 extern NORETURN void unable_to_lock_die(const char *path, int err);
  75 extern int hold_lock_file_for_update(struct lock_file *, const char *path, int);
  76 extern int hold_lock_file_for_append(struct lock_file *, const char *path, int);
  77 extern char *get_locked_file_path(struct lock_file *);
  78 extern int commit_lock_file_to(struct lock_file *, const char *path);
  79 extern int commit_lock_file(struct lock_file *);
  80 extern int reopen_lock_file(struct lock_file *);
  81 extern int close_lock_file(struct lock_file *);
  82 extern void rollback_lock_file(struct lock_file *);
  83
  84 #endif /* LOCKFILE_H */