diff options
| author | Michael Haggerty <mhagger@alum.mit.edu> | 2014-10-01 12:28:24 +0200 |
|---|---|---|
| committer | Junio C Hamano <gitster@pobox.com> | 2014-10-01 13:45:14 -0700 |
| commit | d75145acf6d17eb9b0f9d7d8856e523038081311 (patch) | |
| tree | 30fbc888e9bf8ab371a41ad0b0af927d565b1b20 | |
| parent | 1b1648f46bcb638f558e9cbd2d0e89066c89c44e (diff) | |
| download | git-d75145acf6d17eb9b0f9d7d8856e523038081311.tar.gz | |
api-lockfile: document edge cases
* Document the behavior of commit_lock_file() when it fails, namely
that it rolls back the lock_file object and sets errno
appropriately.
* Document the behavior of rollback_lock_file() when called for a
lock_file object that has already been committed or rolled back,
namely that it is a NOOP.
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
| -rw-r--r-- | Documentation/technical/api-lockfile.txt | 20 |
1 files changed, 14 insertions, 6 deletions
diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt index d3bf940ad4..9805da099d 100644 --- a/Documentation/technical/api-lockfile.txt +++ b/Documentation/technical/api-lockfile.txt @@ -100,6 +100,10 @@ unable_to_lock_die:: Emit an appropriate error message and `die()`. +Similarly, `commit_lock_file` and `close_lock_file` return 0 on +success. On failure they set `errno` appropriately, do their best to +roll back the lockfile, and return -1. + Flags ----- @@ -144,18 +148,22 @@ commit_lock_file:: Take a pointer to the `struct lock_file` initialized with an earlier call to `hold_lock_file_for_update` or - `hold_lock_file_for_append`, close the file descriptor and + `hold_lock_file_for_append`, close the file descriptor, and rename the lockfile to its final destination. Return 0 upon - success or a negative value on failure to `close(2)` or - `rename(2)`. It is a bug to call `commit_lock_file()` for a - `lock_file` object that is not currently locked. + success. On failure, roll back the lock file and return -1, + with `errno` set to the value from the failing call to + `close(2)` or `rename(2)`. It is a bug to call + `commit_lock_file` for a `lock_file` object that is not + currently locked. rollback_lock_file:: Take a pointer to the `struct lock_file` initialized with an earlier call to `hold_lock_file_for_update` or `hold_lock_file_for_append`, close the file descriptor and - remove the lockfile. + remove the lockfile. It is a NOOP to call + `rollback_lock_file()` for a `lock_file` object that has + already been committed or rolled back. close_lock_file:: @@ -163,7 +171,7 @@ close_lock_file:: earlier call to `hold_lock_file_for_update` or `hold_lock_file_for_append`, and close the file descriptor. Return 0 upon success. On failure to `close(2)`, return a - negative value and rollback the lock file. Usually + negative value and roll back the lock file. Usually `commit_lock_file` or `rollback_lock_file` should eventually be called if `close_lock_file` succeeds. |