From d6cf61bfd4bccffcc8b095f8469dbe749d70abdf Mon Sep 17 00:00:00 2001 From: Brandon Casey Date: Wed, 16 Jan 2008 11:05:32 -0800 Subject: 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 --- Documentation/technical/api-lockfile.txt | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt index 5b1553e52c..dd894043ae 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 -- cgit v1.2.1