summaryrefslogtreecommitdiff
path: root/Documentation/technical/api-lockfile.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/technical/api-lockfile.txt')
-rw-r--r--Documentation/technical/api-lockfile.txt20
1 files changed, 14 insertions, 6 deletions
diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt
index d3bf940..9805da0 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.