From: Michael Haggerty Date: Tue, 16 Sep 2014 19:33:41 GMT Subject: [PATCH v5 20/35] api-lockfile: document edge cases Message-ID: <1410896036-12750-21-git-send-email-mhagger@alum.mit.edu> In-Reply-To: <1410896036-12750-1-git-send-email-mhagger@alum.mit.edu> * 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 --- Documentation/technical/api-lockfile.txt | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/Documentation/technical/api-lockfile.txt b/Documentation/technical/api-lockfile.txt index 9a94ead..2514559 100644 --- a/Documentation/technical/api-lockfile.txt +++ b/Documentation/technical/api-lockfile.txt @@ -64,19 +64,22 @@ unable_to_lock_die:: 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. Returns 0 upon success, 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 + 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. + Return 0 upon success. On failure, rollback 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()`, - close the file descriptor and remove the lockfile. + close the file descriptor and 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:: Take a pointer to the `struct lock_file` initialized -- 2.1.0