lockfile.h

   1 #ifndef LOCKFILE_H
   2 #define LOCKFILE_H
   3
   4 /*
   5  * File write-locks as used by Git.
   6  *
   7  * The lockfile API serves two purposes:
   8  *
   9  * * Mutual exclusion and atomic file updates. When we want to change
  10  *   a file, we create a lockfile `<filename>.lock`, write the new
  11  *   file contents into it, and then rename the lockfile to its final
  12  *   destination `<filename>`. We create the `<filename>.lock` file
  13  *   with `O_CREAT|O_EXCL` so that we can notice and fail if somebody
  14  *   else has already locked the file, then atomically rename the
  15  *   lockfile to its final destination to commit the changes and
  16  *   unlock the file.
  17  *
  18  * * Automatic cruft removal. If the program exits after we lock a
  19  *   file but before the changes have been committed, we want to make
  20  *   sure that we remove the lockfile. This is done by remembering the
  21  *   lockfiles we have created in a linked list and setting up an
  22  *   `atexit(3)` handler and a signal handler that clean up the
  23  *   lockfiles. This mechanism ensures that outstanding lockfiles are
  24  *   cleaned up if the program exits (including when `die()` is
  25  *   called) or if the program is terminated by a signal.
  26  *
  27  * Please note that lockfiles only block other writers. Readers do not
  28  * block, but they are guaranteed to see either the old contents of
  29  * the file or the new contents of the file (assuming that the
  30  * filesystem implements `rename(2)` atomically).
  31  *
  32  * Most of the heavy lifting is done by the tempfile module (see
  33  * "tempfile.h").
  34  *
  35  * Calling sequence
  36  * ----------------
  37  *
  38  * The caller:
  39  *
  40  * * Allocates a `struct lock_file` with whatever storage duration you
  41  *   desire. The struct does not have to be initialized before being
  42  *   used, but it is good practice to do so using by setting it to
  43  *   all-zeros (or using the LOCK_INIT macro). This puts the object in a
  44  *   consistent state that allows you to call rollback_lock_file() even
  45  *   if the lock was never taken (in which case it is a noop).
  46  *
  47  * * Attempts to create a lockfile by calling `hold_lock_file_for_update()`.
  48  *
  49  * * Writes new content for the destination file by either:
  50  *
  51  *   * writing to the file descriptor returned by the
  52  *     `hold_lock_file_for_*()` functions (also available via
  53  *     `lock->fd`).
  54  *
  55  *   * calling `fdopen_lock_file()` to get a `FILE` pointer for the
  56  *     open file and writing to the file using stdio.
  57  *
  58  *   Note that the file descriptor returned by hold_lock_file_for_update()
  59  *   is marked O_CLOEXEC, so the new contents must be written by the
  60  *   current process, not a spawned one.
  61  *
  62  * When finished writing, the caller can:
  63  *
  64  * * Close the file descriptor and rename the lockfile to its final
  65  *   destination by calling `commit_lock_file()` or
  66  *   `commit_lock_file_to()`.
  67  *
  68  * * Close the file descriptor and remove the lockfile by calling
  69  *   `rollback_lock_file()`.
  70  *
  71  * * Close the file descriptor without removing or renaming the
  72  *   lockfile by calling `close_lock_file_gently()`, and later call
  73  *   `commit_lock_file()`, `commit_lock_file_to()`,
  74  *   `rollback_lock_file()`, or `reopen_lock_file()`.
  75  *
  76  * After the lockfile is committed or rolled back, the `lock_file`
  77  * object can be discarded or reused.
  78  *
  79  * If the program exits before `commit_lock_file()`,
  80  * `commit_lock_file_to()`, or `rollback_lock_file()` is called, the
  81  * tempfile module will close and remove the lockfile, thereby rolling
  82  * back any uncommitted changes.
  83  *
  84  * If you need to close the file descriptor you obtained from a
  85  * `hold_lock_file_for_*()` function yourself, do so by calling
  86  * `close_lock_file_gently()`. See "tempfile.h" for more information.
  87  *
  88  *
  89  * Under the covers, a lockfile is just a tempfile with a few helper
  90  * functions. In particular, the state diagram and the cleanup
  91  * machinery are all implemented in the tempfile module.
  92  *
  93  *
  94  * Error handling
  95  * --------------
  96  *
  97  * The `hold_lock_file_for_*()` functions return a file descriptor on
  98  * success or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see
  99  * "flags" below). On errors, `errno` describes the reason for
 100  * failure. Errors can be reported by passing `errno` to
 101  * `unable_to_lock_message()` or `unable_to_lock_die()`.
 102  *
 103  * Similarly, `commit_lock_file`, `commit_lock_file_to`, and
 104  * `close_lock_file` return 0 on success. On failure they set `errno`
 105  * appropriately and return -1. The `commit` variants (but not `close`)
 106  * do their best to delete the temporary file before returning.
 107  */
 108
 109 #include "tempfile.h"
 110
 111 struct lock_file {
 112         struct tempfile *tempfile;
 113 };
 114
 115 #define LOCK_INIT { NULL }
 116
 117 /* String appended to a filename to derive the lockfile name: */
 118 #define LOCK_SUFFIX ".lock"
 119 #define LOCK_SUFFIX_LEN 5
 120
 121
 122 /*
 123  * Flags
 124  * -----
 125  *
 126  * The following flags can be passed to `hold_lock_file_for_update()`.
 127  */
 128
 129 /*
 130  * If a lock is already taken for the file, `die()` with an error
 131  * message. If this flag is not specified, trying to lock a file that
 132  * is already locked silently returns -1 to the caller, or ...
 133  */
 134 #define LOCK_DIE_ON_ERROR 1
 135
 136 /*
 137  * ... this flag can be passed instead to return -1 and give the usual
 138  * error message upon an error.
 139  */
 140 #define LOCK_REPORT_ON_ERROR 4
 141
 142 /*
 143  * Usually symbolic links in the destination path are resolved. This
 144  * means that (1) the lockfile is created by adding ".lock" to the
 145  * resolved path, and (2) upon commit, the resolved path is
 146  * overwritten. However, if `LOCK_NO_DEREF` is set, then the lockfile
 147  * is created by adding ".lock" to the path argument itself. This
 148  * option is used, for example, when detaching a symbolic reference,
 149  * which for backwards-compatibility reasons, can be a symbolic link
 150  * containing the name of the referred-to-reference.
 151  */
 152 #define LOCK_NO_DEREF 2
 153
 154 /*
 155  * Attempt to create a lockfile for the file at `path` and return a
 156  * file descriptor for writing to it, or -1 on error. If the file is
 157  * currently locked, retry with quadratic backoff for at least
 158  * timeout_ms milliseconds. If timeout_ms is 0, try exactly once; if
 159  * timeout_ms is -1, retry indefinitely. The flags argument and error
 160  * handling are described above.
 161  */
 162 int hold_lock_file_for_update_timeout(
 163                 struct lock_file *lk, const char *path,
 164                 int flags, long timeout_ms);
 165
 166 /*
 167  * Attempt to create a lockfile for the file at `path` and return a
 168  * file descriptor for writing to it, or -1 on error. The flags
 169  * argument and error handling are described above.
 170  */
 171 static inline int hold_lock_file_for_update(
 172                 struct lock_file *lk, const char *path,
 173                 int flags)
 174 {
 175         return hold_lock_file_for_update_timeout(lk, path, flags, 0);
 176 }
 177
 178 /*
 179  * Return a nonzero value iff `lk` is currently locked.
 180  */
 181 static inline int is_lock_file_locked(struct lock_file *lk)
 182 {
 183         return is_tempfile_active(lk->tempfile);
 184 }
 185
 186 /*
 187  * Append an appropriate error message to `buf` following the failure
 188  * of `hold_lock_file_for_update()` to lock `path`. `err` should be the
 189  * `errno` set by the failing call.
 190  */
 191 void unable_to_lock_message(const char *path, int err,
 192                             struct strbuf *buf);
 193
 194 /*
 195  * Emit an appropriate error message and `die()` following the failure
 196  * of `hold_lock_file_for_update()` to lock `path`. `err` should be the
 197  * `errno` set by the failing
 198  * call.
 199  */
 200 NORETURN void unable_to_lock_die(const char *path, int err);
 201
 202 /*
 203  * Associate a stdio stream with the lockfile (which must still be
 204  * open). Return `NULL` (*without* rolling back the lockfile) on
 205  * error. The stream is closed automatically when
 206  * `close_lock_file_gently()` is called or when the file is committed or
 207  * rolled back.
 208  */
 209 static inline FILE *fdopen_lock_file(struct lock_file *lk, const char *mode)
 210 {
 211         return fdopen_tempfile(lk->tempfile, mode);
 212 }
 213
 214 /*
 215  * Return the path of the lockfile. The return value is a pointer to a
 216  * field within the lock_file object and should not be freed.
 217  */
 218 static inline const char *get_lock_file_path(struct lock_file *lk)
 219 {
 220         return get_tempfile_path(lk->tempfile);
 221 }
 222
 223 static inline int get_lock_file_fd(struct lock_file *lk)
 224 {
 225         return get_tempfile_fd(lk->tempfile);
 226 }
 227
 228 static inline FILE *get_lock_file_fp(struct lock_file *lk)
 229 {
 230         return get_tempfile_fp(lk->tempfile);
 231 }
 232
 233 /*
 234  * Return the path of the file that is locked by the specified
 235  * lock_file object. The caller must free the memory.
 236  */
 237 char *get_locked_file_path(struct lock_file *lk);
 238
 239 /*
 240  * If the lockfile is still open, close it (and the file pointer if it
 241  * has been opened using `fdopen_lock_file()`) without renaming the
 242  * lockfile over the file being locked. Return 0 upon success. On
 243  * failure to `close(2)`, return a negative value (the lockfile is not
 244  * rolled back). Usually `commit_lock_file()`, `commit_lock_file_to()`,
 245  * or `rollback_lock_file()` should eventually be called.
 246  */
 247 static inline int close_lock_file_gently(struct lock_file *lk)
 248 {
 249         return close_tempfile_gently(lk->tempfile);
 250 }
 251
 252 /*
 253  * Re-open a lockfile that has been closed using `close_lock_file_gently()`
 254  * but not yet committed or rolled back. This can be used to implement
 255  * a sequence of operations like the following:
 256  *
 257  * * Lock file.
 258  *
 259  * * Write new contents to lockfile, then `close_lock_file_gently()` to
 260  *   cause the contents to be written to disk.
 261  *
 262  * * Pass the name of the lockfile to another program to allow it (and
 263  *   nobody else) to inspect the contents you wrote, while still
 264  *   holding the lock yourself.
 265  *
 266  * * `reopen_lock_file()` to reopen the lockfile, truncating the existing
 267  *   contents. Write out the new contents.
 268  *
 269  * * `commit_lock_file()` to make the final version permanent.
 270  */
 271 static inline int reopen_lock_file(struct lock_file *lk)
 272 {
 273         return reopen_tempfile(lk->tempfile);
 274 }
 275
 276 /*
 277  * Commit the change represented by `lk`: close the file descriptor
 278  * and/or file pointer if they are still open and rename the lockfile
 279  * to its final destination. Return 0 upon success. On failure, roll
 280  * back the lock file and return -1, with `errno` set to the value
 281  * from the failing call to `close(2)` or `rename(2)`. It is a bug to
 282  * call `commit_lock_file()` for a `lock_file` object that is not
 283  * currently locked.
 284  */
 285 int commit_lock_file(struct lock_file *lk);
 286
 287 /*
 288  * Like `commit_lock_file()`, but rename the lockfile to the provided
 289  * `path`. `path` must be on the same filesystem as the lock file.
 290  */
 291 static inline int commit_lock_file_to(struct lock_file *lk, const char *path)
 292 {
 293         return rename_tempfile(&lk->tempfile, path);
 294 }
 295
 296 /*
 297  * Roll back `lk`: close the file descriptor and/or file pointer and
 298  * remove the lockfile. It is a NOOP to call `rollback_lock_file()`
 299  * for a `lock_file` object that has already been committed or rolled
 300  * back.
 301  */
 302 static inline void rollback_lock_file(struct lock_file *lk)
 303 {
 304         delete_tempfile(&lk->tempfile);
 305 }
 306
 307 #endif /* LOCKFILE_H */