Document lockfile API
[git/git.git] / Documentation / technical / api-lockfile.txt
CommitLineData
530e741c
JH
1lockfile API
2============
3
0c0478ca 4The lockfile API serves two purposes:
530e741c 5
0c0478ca
JH
6* Mutual exclusion. When we write out a new index file, first
7 we create a new file `$GIT_DIR/index.lock`, write the new
8 contents into it, and rename it to the final destination
9 `$GIT_DIR/index`. We try to create the `$GIT_DIR/index.lock`
10 file with O_EXCL so that we can notice and fail when somebody
11 else is already trying to update the index file.
530e741c 12
0c0478ca
JH
13* Automatic cruft removal. After we create the "lock" file, we
14 may decide to `die()`, and we would want to make sure that we
15 remove the file that has not been committed to its final
16 destination. This is done by remembering the lockfiles we
17 created in a linked list and cleaning them up from an
18 `atexit(3)` handler. Outstanding lockfiles are also removed
19 when the program dies on a signal.
20
21
22The functions
23-------------
24
25hold_lock_file_for_update::
26
27 Take a pointer to `struct lock_file`, the filename of
28 the final destination (e.g. `$GIT_DIR/index`) and a flag
29 `die_on_error`. Attempt to create a lockfile for the
30 destination and return the file descriptor for writing
31 to the file. If `die_on_error` flag is true, it dies if
32 a lock is already taken for the file; otherwise it
33 returns a negative integer to the caller on failure.
34
35commit_lock_file::
36
37 Take a pointer to the `struct lock_file` initialized
38 with an earlier call to `hold_lock_file_for_update()`,
39 close the file descriptor and rename the lockfile to its
40 final destination.
41
42rollback_lock_file::
43
44 Take a pointer to the `struct lock_file` initialized
45 with an earlier call to `hold_lock_file_for_update()`,
46 close the file descriptor and remove the lockfile.
47
48Because the structure is used in an `atexit(3)` handler, its
49storage has to stay throughout the life of the program. It
50cannot be an auto variable allocated on the stack.
51
52Call `commit_lock_file()` or `rollback_lock_file()` when you are
53done writing to the file descriptor. If you do not call either
54and simply `exit(3)` from the program, an `atexit(3)` handler
55will close and remove the lockfile.
56
57You should not close the file descriptor you obtained from
58`hold_lock_file_for_update` function yourself. The `struct
59lock_file` structure still remembers that the file descriptor
60needs to be closed, and a later call to `commit_lock_file()` or
61`rollback_lock_file()` will result in duplicate calls to
62`close(2)`. Worse yet, if you `close(2)`, open another file
63descriptor for completely different purpose, and then call
64`commit_lock_file()` or `rollback_lock_file()`, they may close
65that unrelated file descriptor.