[thirdparty/git.git] / lockfile.h

#ifndef LOCKFILE_H
#define LOCKFILE_H

/*
 * File write-locks as used by Git.
 *
 * For an overview of how to use the lockfile API, please see
 *
 *     Documentation/technical/api-lockfile.txt
 *
 * This module keeps track of all locked files in lock_file_list for
 * use at cleanup. This list and the lock_file objects that comprise
 * it must be kept in self-consistent states at all time, because the
 * program can be interrupted any time by a signal, in which case the
 * signal handler will walk through the list attempting to clean up
 * any open lock files.
 *
 * A lockfile is owned by the process that created it. The lock_file
 * object has an "owner" field that records its owner. This field is
 * used to prevent a forked process from closing a lockfile created by
 * its parent.
 *
 * The possible states of a lock_file object are as follows:
 *
 * - Uninitialized.  In this state the object's on_list field must be
 *   zero but the rest of its contents need not be initialized.  As
 *   soon as the object is used in any way, it is irrevocably
 *   registered in the lock_file_list, and on_list is set.
 *
 * - Locked, lockfile open (after hold_lock_file_for_update(),
 *   hold_lock_file_for_append(), or reopen_lock_file()). In this
 *   state:
 *   - the lockfile exists
 *   - active is set
 *   - filename holds the filename of the lockfile
 *   - fd holds a file descriptor open for writing to the lockfile
 *   - owner holds the PID of the process that locked the file
 *
 * - Locked, lockfile closed (after successful close_lock_file()).
 *   Same as the previous state, except that the lockfile is closed
 *   and fd is -1.
 *
 * - Unlocked (after commit_lock_file(), commit_lock_file_to(),
 *   rollback_lock_file(), a failed attempt to lock, or a failed
 *   close_lock_file()).  In this state:
 *   - active is unset
 *   - filename is empty (usually, though there are transitory
 *     states in which this condition doesn't hold). Client code should
 *     *not* rely on the filename being empty in this state.
 *   - fd is -1
 *   - the object is left registered in the lock_file_list, and
 *     on_list is set.
 */

struct lock_file {
	struct lock_file *volatile next;
	volatile sig_atomic_t active;
	volatile int fd;
	volatile pid_t owner;
	char on_list;
	struct strbuf filename;
};

/* String appended to a filename to derive the lockfile name: */
#define LOCK_SUFFIX ".lock"
#define LOCK_SUFFIX_LEN 5

#define LOCK_DIE_ON_ERROR 1
#define LOCK_NO_DEREF 2

extern int unable_to_lock_error(const char *path, int err);
extern void unable_to_lock_message(const char *path, int err,
				   struct strbuf *buf);
extern NORETURN void unable_to_lock_die(const char *path, int err);
extern int hold_lock_file_for_update(struct lock_file *, const char *path, int);
extern int hold_lock_file_for_append(struct lock_file *, const char *path, int);
extern char *get_locked_file_path(struct lock_file *);
extern int commit_lock_file_to(struct lock_file *, const char *path);
extern int commit_lock_file(struct lock_file *);
extern int reopen_lock_file(struct lock_file *);
extern int close_lock_file(struct lock_file *);
extern void rollback_lock_file(struct lock_file *);

#endif /* LOCKFILE_H */
Commit	Line	Data
697cc8ef MH	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 */