summaryrefslogtreecommitdiff
path: root/Documentation/technical
diff options
context:
space:
mode:
authorBrandon Casey <casey@nrlssc.navy.mil>2008-01-16 19:05:32 (GMT)
committerJunio C Hamano <gitster@pobox.com>2008-01-16 23:35:03 (GMT)
commitd6cf61bfd4bccffcc8b095f8469dbe749d70abdf (patch)
tree4f330d67ce37d7319494e8f8a71005f4d733c2e0 /Documentation/technical
parent0c0478cac87991bd555e81715e9332d11eecd881 (diff)
downloadgit-d6cf61bfd4bccffcc8b095f8469dbe749d70abdf.zip
git-d6cf61bfd4bccffcc8b095f8469dbe749d70abdf.tar.gz
git-d6cf61bfd4bccffcc8b095f8469dbe749d70abdf.tar.bz2
close_lock_file(): new function in the lockfile API
The lockfile API is a handy way to obtain a file that is cleaned up if you die(). But sometimes you would need this sequence to work: 1. hold_lock_file_for_update() to get a file descriptor for writing; 2. write the contents out, without being able to decide if the results should be committed or rolled back; 3. do something else that makes the decision --- and this "something else" needs the lockfile not to have an open file descriptor for writing (e.g. Windows do not want a open file to be renamed); 4. call commit_lock_file() or rollback_lock_file() as appropriately. This adds close_lock_file() you can call between step 2 and 3 in the above sequence. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation/technical')
-rw-r--r--Documentation/technical/api-lockfile.txt15
1 files changed, 12 insertions, 3 deletions
diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt
index 5b1553e..dd89404 100644
--- a/Documentation/technical/api-lockfile.txt
+++ b/Documentation/technical/api-lockfile.txt
@@ -37,7 +37,8 @@ commit_lock_file::
Take a pointer to the `struct lock_file` initialized
with an earlier call to `hold_lock_file_for_update()`,
close the file descriptor and rename the lockfile to its
- final destination.
+ final destination. Returns 0 upon success, a negative
+ value on failure to close(2) or rename(2).
rollback_lock_file::
@@ -45,6 +46,12 @@ rollback_lock_file::
with an earlier call to `hold_lock_file_for_update()`,
close the file descriptor and remove the lockfile.
+close_lock_file::
+ Take a pointer to the `struct lock_file` initialized
+ with an earlier call to `hold_lock_file_for_update()`,
+ and close the file descriptor. Returns 0 upon success,
+ a negative value on failure to close(2).
+
Because the structure is used in an `atexit(3)` handler, its
storage has to stay throughout the life of the program. It
cannot be an auto variable allocated on the stack.
@@ -54,8 +61,10 @@ done writing to the file descriptor. If you do not call either
and simply `exit(3)` from the program, an `atexit(3)` handler
will close and remove the lockfile.
-You should not close the file descriptor you obtained from
-`hold_lock_file_for_update` function yourself. The `struct
+If you need to close the file descriptor you obtained from
+`hold_lock_file_for_update` function yourself, do so by calling
+`close_lock_file()`. You should never call `close(2)` yourself!
+Otherwise the `struct
lock_file` structure still remembers that the file descriptor
needs to be closed, and a later call to `commit_lock_file()` or
`rollback_lock_file()` will result in duplicate calls to