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