lockfile.hon commit shallow: remove unused #include "sigchain.h" (4b7c50a)
   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` either as a static variable or on
  41 *   the heap, initialized to zeros. Once you use the structure to
  42 *   call the `hold_lock_file_for_*()` family of functions, it belongs
  43 *   to the lockfile subsystem and its storage must remain valid
  44 *   throughout the life of the program (i.e. you cannot use an
  45 *   on-stack variable to hold this structure).
  46 *
  47 * * Attempts to create a lockfile by calling
  48 *   `hold_lock_file_for_update()` or `hold_lock_file_for_append()`.
  49 *
  50 * * Writes new content for the destination file by either:
  51 *
  52 *   * writing to the file descriptor returned by the
  53 *     `hold_lock_file_for_*()` functions (also available via
  54 *     `lock->fd`).
  55 *
  56 *   * calling `fdopen_lock_file()` to get a `FILE` pointer for the
  57 *     open file and writing to the file using stdio.
  58 *
  59 * When finished writing, the caller can:
  60 *
  61 * * Close the file descriptor and rename the lockfile to its final
  62 *   destination by calling `commit_lock_file()` or
  63 *   `commit_lock_file_to()`.
  64 *
  65 * * Close the file descriptor and remove the lockfile by calling
  66 *   `rollback_lock_file()`.
  67 *
  68 * * Close the file descriptor without removing or renaming the
  69 *   lockfile by calling `close_lock_file()`, and later call
  70 *   `commit_lock_file()`, `commit_lock_file_to()`,
  71 *   `rollback_lock_file()`, or `reopen_lock_file()`.
  72 *
  73 * Even after the lockfile is committed or rolled back, the
  74 * `lock_file` object must not be freed or altered by the caller.
  75 * However, it may be reused; just pass it to another call of
  76 * `hold_lock_file_for_update()` or `hold_lock_file_for_append()`.
  77 *
  78 * If the program exits before `commit_lock_file()`,
  79 * `commit_lock_file_to()`, or `rollback_lock_file()` is called, the
  80 * tempfile module will close and remove the lockfile, thereby rolling
  81 * back any uncommitted changes.
  82 *
  83 * If you need to close the file descriptor you obtained from a
  84 * `hold_lock_file_for_*()` function yourself, do so by calling
  85 * `close_lock_file()`. See "tempfile.h" for more information.
  86 *
  87 *
  88 * Under the covers, a lockfile is just a tempfile with a few helper
  89 * functions. In particular, the state diagram and the cleanup
  90 * machinery are all implemented in the tempfile module.
  91 *
  92 *
  93 * Error handling
  94 * --------------
  95 *
  96 * The `hold_lock_file_for_*()` functions return a file descriptor on
  97 * success or -1 on failure (unless `LOCK_DIE_ON_ERROR` is used; see
  98 * "flags" below). On errors, `errno` describes the reason for
  99 * failure. Errors can be reported by passing `errno` to
 100 * `unable_to_lock_message()` or `unable_to_lock_die()`.
 101 *
 102 * Similarly, `commit_lock_file`, `commit_lock_file_to`, and
 103 * `close_lock_file` return 0 on success. On failure they set `errno`
 104 * appropriately, do their best to roll back the lockfile, and return
 105 * -1.
 106 */
 107
 108#include "tempfile.h"
 109
 110struct lock_file {
 111        struct tempfile tempfile;
 112};
 113
 114/* String appended to a filename to derive the lockfile name: */
 115#define LOCK_SUFFIX ".lock"
 116#define LOCK_SUFFIX_LEN 5
 117
 118
 119/*
 120 * Flags
 121 * -----
 122 *
 123 * The following flags can be passed to `hold_lock_file_for_update()`
 124 * or `hold_lock_file_for_append()`.
 125 */
 126
 127/*
 128 * If a lock is already taken for the file, `die()` with an error
 129 * message. If this flag is not specified, trying to lock a file that
 130 * is already locked returns -1 to the caller.
 131 */
 132#define LOCK_DIE_ON_ERROR 1
 133
 134/*
 135 * Usually symbolic links in the destination path are resolved. This
 136 * means that (1) the lockfile is created by adding ".lock" to the
 137 * resolved path, and (2) upon commit, the resolved path is
 138 * overwritten. However, if `LOCK_NO_DEREF` is set, then the lockfile
 139 * is created by adding ".lock" to the path argument itself. This
 140 * option is used, for example, when detaching a symbolic reference,
 141 * which for backwards-compatibility reasons, can be a symbolic link
 142 * containing the name of the referred-to-reference.
 143 */
 144#define LOCK_NO_DEREF 2
 145
 146/*
 147 * Attempt to create a lockfile for the file at `path` and return a
 148 * file descriptor for writing to it, or -1 on error. If the file is
 149 * currently locked, retry with quadratic backoff for at least
 150 * timeout_ms milliseconds. If timeout_ms is 0, try exactly once; if
 151 * timeout_ms is -1, retry indefinitely. The flags argument and error
 152 * handling are described above.
 153 */
 154extern int hold_lock_file_for_update_timeout(
 155                struct lock_file *lk, const char *path,
 156                int flags, long timeout_ms);
 157
 158/*
 159 * Attempt to create a lockfile for the file at `path` and return a
 160 * file descriptor for writing to it, or -1 on error. The flags
 161 * argument and error handling are described above.
 162 */
 163static inline int hold_lock_file_for_update(
 164                struct lock_file *lk, const char *path,
 165                int flags)
 166{
 167        return hold_lock_file_for_update_timeout(lk, path, flags, 0);
 168}
 169
 170/*
 171 * Like `hold_lock_file_for_update()`, but before returning copy the
 172 * existing contents of the file (if any) to the lockfile and position
 173 * its write pointer at the end of the file. The flags argument and
 174 * error handling are described above.
 175 */
 176extern int hold_lock_file_for_append(struct lock_file *lk,
 177                                     const char *path, int flags);
 178
 179/*
 180 * Append an appropriate error message to `buf` following the failure
 181 * of `hold_lock_file_for_update()` or `hold_lock_file_for_append()`
 182 * to lock `path`. `err` should be the `errno` set by the failing
 183 * call.
 184 */
 185extern void unable_to_lock_message(const char *path, int err,
 186                                   struct strbuf *buf);
 187
 188/*
 189 * Emit an appropriate error message and `die()` following the failure
 190 * of `hold_lock_file_for_update()` or `hold_lock_file_for_append()`
 191 * to lock `path`. `err` should be the `errno` set by the failing
 192 * call.
 193 */
 194extern NORETURN void unable_to_lock_die(const char *path, int err);
 195
 196/*
 197 * Associate a stdio stream with the lockfile (which must still be
 198 * open). Return `NULL` (*without* rolling back the lockfile) on
 199 * error. The stream is closed automatically when `close_lock_file()`
 200 * is called or when the file is committed or rolled back.
 201 */
 202static inline FILE *fdopen_lock_file(struct lock_file *lk, const char *mode)
 203{
 204        return fdopen_tempfile(&lk->tempfile, mode);
 205}
 206
 207/*
 208 * Return the path of the lockfile. The return value is a pointer to a
 209 * field within the lock_file object and should not be freed.
 210 */
 211static inline const char *get_lock_file_path(struct lock_file *lk)
 212{
 213        return get_tempfile_path(&lk->tempfile);
 214}
 215
 216static inline int get_lock_file_fd(struct lock_file *lk)
 217{
 218        return get_tempfile_fd(&lk->tempfile);
 219}
 220
 221static inline FILE *get_lock_file_fp(struct lock_file *lk)
 222{
 223        return get_tempfile_fp(&lk->tempfile);
 224}
 225
 226/*
 227 * Return the path of the file that is locked by the specified
 228 * lock_file object. The caller must free the memory.
 229 */
 230extern char *get_locked_file_path(struct lock_file *lk);
 231
 232/*
 233 * If the lockfile is still open, close it (and the file pointer if it
 234 * has been opened using `fdopen_lock_file()`) without renaming the
 235 * lockfile over the file being locked. Return 0 upon success. On
 236 * failure to `close(2)`, return a negative value and roll back the
 237 * lock file. Usually `commit_lock_file()`, `commit_lock_file_to()`,
 238 * or `rollback_lock_file()` should eventually be called if
 239 * `close_lock_file()` succeeds.
 240 */
 241static inline int close_lock_file(struct lock_file *lk)
 242{
 243        return close_tempfile(&lk->tempfile);
 244}
 245
 246/*
 247 * Re-open a lockfile that has been closed using `close_lock_file()`
 248 * but not yet committed or rolled back. This can be used to implement
 249 * a sequence of operations like the following:
 250 *
 251 * * Lock file.
 252 *
 253 * * Write new contents to lockfile, then `close_lock_file()` to
 254 *   cause the contents to be written to disk.
 255 *
 256 * * Pass the name of the lockfile to another program to allow it (and
 257 *   nobody else) to inspect the contents you wrote, while still
 258 *   holding the lock yourself.
 259 *
 260 * * `reopen_lock_file()` to reopen the lockfile. Make further updates
 261 *   to the contents.
 262 *
 263 * * `commit_lock_file()` to make the final version permanent.
 264 */
 265static inline int reopen_lock_file(struct lock_file *lk)
 266{
 267        return reopen_tempfile(&lk->tempfile);
 268}
 269
 270/*
 271 * Commit the change represented by `lk`: close the file descriptor
 272 * and/or file pointer if they are still open and rename the lockfile
 273 * to its final destination. Return 0 upon success. On failure, roll
 274 * back the lock file and return -1, with `errno` set to the value
 275 * from the failing call to `close(2)` or `rename(2)`. It is a bug to
 276 * call `commit_lock_file()` for a `lock_file` object that is not
 277 * currently locked.
 278 */
 279extern int commit_lock_file(struct lock_file *lk);
 280
 281/*
 282 * Like `commit_lock_file()`, but rename the lockfile to the provided
 283 * `path`. `path` must be on the same filesystem as the lock file.
 284 */
 285static inline int commit_lock_file_to(struct lock_file *lk, const char *path)
 286{
 287        return rename_tempfile(&lk->tempfile, path);
 288}
 289
 290/*
 291 * Roll back `lk`: close the file descriptor and/or file pointer and
 292 * remove the lockfile. It is a NOOP to call `rollback_lock_file()`
 293 * for a `lock_file` object that has already been committed or rolled
 294 * back.
 295 */
 296static inline void rollback_lock_file(struct lock_file *lk)
 297{
 298        delete_tempfile(&lk->tempfile);
 299}
 300
 301#endif /* LOCKFILE_H */