]>
Commit | Line | Data |
---|---|---|
1a9d15db MH |
1 | #ifndef TEMPFILE_H |
2 | #define TEMPFILE_H | |
3 | ||
24d82185 | 4 | #include "list.h" |
ef3ca954 | 5 | #include "strbuf.h" |
24d82185 | 6 | |
1a9d15db MH |
7 | /* |
8 | * Handle temporary files. | |
9 | * | |
10 | * The tempfile API allows temporary files to be created, deleted, and | |
11 | * atomically renamed. Temporary files that are still active when the | |
12 | * program ends are cleaned up automatically. Lockfiles (see | |
13 | * "lockfile.h") are built on top of this API. | |
14 | * | |
15 | * | |
16 | * Calling sequence | |
17 | * ---------------- | |
18 | * | |
19 | * The caller: | |
20 | * | |
1a9d15db | 21 | * * Attempts to create a temporary file by calling |
076aa2cb JK |
22 | * `create_tempfile()`. The resources used for the temporary file are |
23 | * managed by the tempfile API. | |
1a9d15db MH |
24 | * |
25 | * * Writes new content to the file by either: | |
26 | * | |
076aa2cb | 27 | * * writing to the `tempfile->fd` file descriptor |
1a9d15db MH |
28 | * |
29 | * * calling `fdopen_tempfile()` to get a `FILE` pointer for the | |
30 | * open file and writing to the file using stdio. | |
31 | * | |
076aa2cb | 32 | * Note that the file descriptor created by create_tempfile() |
05d1ed61 BW |
33 | * is marked O_CLOEXEC, so the new contents must be written by |
34 | * the current process, not any spawned one. | |
35 | * | |
1a9d15db MH |
36 | * When finished writing, the caller can: |
37 | * | |
38 | * * Close the file descriptor and remove the temporary file by | |
39 | * calling `delete_tempfile()`. | |
40 | * | |
41 | * * Close the temporary file and rename it atomically to a specified | |
42 | * filename by calling `rename_tempfile()`. This relinquishes | |
43 | * control of the file. | |
44 | * | |
45 | * * Close the file descriptor without removing or renaming the | |
49bd0fc2 | 46 | * temporary file by calling `close_tempfile_gently()`, and later call |
1a9d15db MH |
47 | * `delete_tempfile()` or `rename_tempfile()`. |
48 | * | |
422a21c6 | 49 | * After the temporary file is renamed or deleted, the `tempfile` |
076aa2cb | 50 | * object is no longer valid and should not be reused. |
1a9d15db MH |
51 | * |
52 | * If the program exits before `rename_tempfile()` or | |
53 | * `delete_tempfile()` is called, an `atexit(3)` handler will close | |
54 | * and remove the temporary file. | |
55 | * | |
56 | * If you need to close the file descriptor yourself, do so by calling | |
49bd0fc2 | 57 | * `close_tempfile_gently()`. You should never call `close(2)` or `fclose(3)` |
1a9d15db MH |
58 | * yourself, otherwise the `struct tempfile` structure would still |
59 | * think that the file descriptor needs to be closed, and a later | |
60 | * cleanup would result in duplicate calls to `close(2)`. Worse yet, | |
61 | * if you close and then later open another file descriptor for a | |
62 | * completely different purpose, then the unrelated file descriptor | |
63 | * might get closed. | |
64 | * | |
65 | * | |
66 | * Error handling | |
67 | * -------------- | |
68 | * | |
076aa2cb JK |
69 | * `create_tempfile()` returns an allocated tempfile on success or NULL |
70 | * on failure. On errors, `errno` describes the reason for failure. | |
1a9d15db | 71 | * |
5de134ca MÅ |
72 | * `rename_tempfile()` and `close_tempfile_gently()` return 0 on success. |
73 | * On failure they set `errno` appropriately and return -1. | |
74 | * `delete_tempfile()` and `rename` (but not `close`) do their best to | |
75 | * delete the temporary file before returning. | |
1a9d15db MH |
76 | */ |
77 | ||
78 | struct tempfile { | |
24d82185 | 79 | volatile struct volatile_list_head list; |
1a9d15db MH |
80 | volatile sig_atomic_t active; |
81 | volatile int fd; | |
82 | FILE *volatile fp; | |
83 | volatile pid_t owner; | |
1a9d15db | 84 | struct strbuf filename; |
2c2db194 | 85 | size_t directorylen; |
1a9d15db MH |
86 | }; |
87 | ||
88 | /* | |
89 | * Attempt to create a temporary file at the specified `path`. Return | |
076aa2cb JK |
90 | * a tempfile (whose "fd" member can be used for writing to it), or |
91 | * NULL on error. It is an error if a file already exists at that path. | |
bef0413c TB |
92 | * Note that `mode` will be further modified by the umask, and possibly |
93 | * `core.sharedRepository`, so it is not guaranteed to have the given | |
94 | * mode. | |
1a9d15db | 95 | */ |
bef0413c TB |
96 | struct tempfile *create_tempfile_mode(const char *path, int mode); |
97 | ||
98 | static inline struct tempfile *create_tempfile(const char *path) | |
99 | { | |
100 | return create_tempfile_mode(path, 0666); | |
101 | } | |
1a9d15db | 102 | |
99397152 MH |
103 | /* |
104 | * Register an existing file as a tempfile, meaning that it will be | |
105 | * deleted when the program exits. The tempfile is considered closed, | |
106 | * but it can be worked with like any other closed tempfile (for | |
107 | * example, it can be opened using reopen_tempfile()). | |
108 | */ | |
55454427 | 109 | struct tempfile *register_tempfile(const char *path); |
99397152 | 110 | |
354ab112 MH |
111 | |
112 | /* | |
113 | * mks_tempfile functions | |
114 | * | |
115 | * The following functions attempt to create and open temporary files | |
116 | * with names derived automatically from a template, in the manner of | |
117 | * mkstemps(), and arrange for them to be deleted if the program ends | |
118 | * before they are deleted explicitly. There is a whole family of such | |
119 | * functions, named according to the following pattern: | |
120 | * | |
121 | * x?mks_tempfile_t?s?m?() | |
122 | * | |
123 | * The optional letters have the following meanings: | |
124 | * | |
125 | * x - die if the temporary file cannot be created. | |
126 | * | |
127 | * t - create the temporary file under $TMPDIR (as opposed to | |
128 | * relative to the current directory). When these variants are | |
129 | * used, template should be the pattern for the filename alone, | |
130 | * without a path. | |
131 | * | |
132 | * s - template includes a suffix that is suffixlen characters long. | |
133 | * | |
134 | * m - the temporary file should be created with the specified mode | |
135 | * (otherwise, the mode is set to 0600). | |
136 | * | |
137 | * None of these functions modify template. If the caller wants to | |
138 | * know the (absolute) path of the file that was created, it can be | |
139 | * read from tempfile->filename. | |
140 | * | |
076aa2cb JK |
141 | * On success, the functions return a tempfile whose "fd" member is open |
142 | * for writing the temporary file. On errors, they return NULL and set | |
143 | * errno appropriately (except for the "x" variants, which die() on | |
144 | * errors). | |
354ab112 MH |
145 | */ |
146 | ||
147 | /* See "mks_tempfile functions" above. */ | |
55454427 | 148 | struct tempfile *mks_tempfile_sm(const char *filename_template, |
ad6dad09 | 149 | int suffixlen, int mode); |
354ab112 MH |
150 | |
151 | /* See "mks_tempfile functions" above. */ | |
ea8ace4a | 152 | static inline struct tempfile *mks_tempfile_s(const char *filename_template, |
076aa2cb | 153 | int suffixlen) |
354ab112 | 154 | { |
ea8ace4a | 155 | return mks_tempfile_sm(filename_template, suffixlen, 0600); |
354ab112 MH |
156 | } |
157 | ||
158 | /* See "mks_tempfile functions" above. */ | |
ea8ace4a | 159 | static inline struct tempfile *mks_tempfile_m(const char *filename_template, int mode) |
354ab112 | 160 | { |
ea8ace4a | 161 | return mks_tempfile_sm(filename_template, 0, mode); |
354ab112 MH |
162 | } |
163 | ||
164 | /* See "mks_tempfile functions" above. */ | |
ea8ace4a | 165 | static inline struct tempfile *mks_tempfile(const char *filename_template) |
354ab112 | 166 | { |
ea8ace4a | 167 | return mks_tempfile_sm(filename_template, 0, 0600); |
354ab112 MH |
168 | } |
169 | ||
170 | /* See "mks_tempfile functions" above. */ | |
55454427 | 171 | struct tempfile *mks_tempfile_tsm(const char *filename_template, |
ad6dad09 | 172 | int suffixlen, int mode); |
354ab112 MH |
173 | |
174 | /* See "mks_tempfile functions" above. */ | |
ea8ace4a | 175 | static inline struct tempfile *mks_tempfile_ts(const char *filename_template, |
076aa2cb | 176 | int suffixlen) |
354ab112 | 177 | { |
ea8ace4a | 178 | return mks_tempfile_tsm(filename_template, suffixlen, 0600); |
354ab112 MH |
179 | } |
180 | ||
181 | /* See "mks_tempfile functions" above. */ | |
ea8ace4a | 182 | static inline struct tempfile *mks_tempfile_tm(const char *filename_template, int mode) |
354ab112 | 183 | { |
ea8ace4a | 184 | return mks_tempfile_tsm(filename_template, 0, mode); |
354ab112 MH |
185 | } |
186 | ||
187 | /* See "mks_tempfile functions" above. */ | |
ea8ace4a | 188 | static inline struct tempfile *mks_tempfile_t(const char *filename_template) |
354ab112 | 189 | { |
ea8ace4a | 190 | return mks_tempfile_tsm(filename_template, 0, 0600); |
354ab112 MH |
191 | } |
192 | ||
193 | /* See "mks_tempfile functions" above. */ | |
55454427 | 194 | struct tempfile *xmks_tempfile_m(const char *filename_template, int mode); |
354ab112 MH |
195 | |
196 | /* See "mks_tempfile functions" above. */ | |
ea8ace4a | 197 | static inline struct tempfile *xmks_tempfile(const char *filename_template) |
354ab112 | 198 | { |
ea8ace4a | 199 | return xmks_tempfile_m(filename_template, 0600); |
354ab112 MH |
200 | } |
201 | ||
2c2db194 RS |
202 | /* |
203 | * Attempt to create a temporary directory in $TMPDIR and to create and | |
204 | * open a file in that new directory. Derive the directory name from the | |
205 | * template in the manner of mkdtemp(). Arrange for directory and file | |
206 | * to be deleted if the program exits before they are deleted | |
207 | * explicitly. On success return a tempfile whose "filename" member | |
208 | * contains the full path of the file and its "fd" member is open for | |
209 | * writing the file. On error return NULL and set errno appropriately. | |
210 | */ | |
211 | struct tempfile *mks_tempfile_dt(const char *directory_template, | |
212 | const char *filename); | |
213 | ||
1a9d15db MH |
214 | /* |
215 | * Associate a stdio stream with the temporary file (which must still | |
216 | * be open). Return `NULL` (*without* deleting the file) on error. The | |
49bd0fc2 | 217 | * stream is closed automatically when `close_tempfile_gently()` is called or |
1a9d15db MH |
218 | * when the file is deleted or renamed. |
219 | */ | |
55454427 | 220 | FILE *fdopen_tempfile(struct tempfile *tempfile, const char *mode); |
1a9d15db MH |
221 | |
222 | static inline int is_tempfile_active(struct tempfile *tempfile) | |
223 | { | |
f5b4dc76 | 224 | return tempfile && tempfile->active; |
1a9d15db MH |
225 | } |
226 | ||
227 | /* | |
228 | * Return the path of the lockfile. The return value is a pointer to a | |
229 | * field within the lock_file object and should not be freed. | |
230 | */ | |
55454427 | 231 | const char *get_tempfile_path(struct tempfile *tempfile); |
1a9d15db | 232 | |
55454427 DL |
233 | int get_tempfile_fd(struct tempfile *tempfile); |
234 | FILE *get_tempfile_fp(struct tempfile *tempfile); | |
1a9d15db MH |
235 | |
236 | /* | |
237 | * If the temporary file is still open, close it (and the file pointer | |
238 | * too, if it has been opened using `fdopen_tempfile()`) without | |
239 | * deleting the file. Return 0 upon success. On failure to `close(2)`, | |
49bd0fc2 JK |
240 | * return a negative value. Usually `delete_tempfile()` or `rename_tempfile()` |
241 | * should eventually be called regardless of whether `close_tempfile_gently()` | |
242 | * succeeds. | |
1a9d15db | 243 | */ |
55454427 | 244 | int close_tempfile_gently(struct tempfile *tempfile); |
1a9d15db MH |
245 | |
246 | /* | |
247 | * Re-open a temporary file that has been closed using | |
49bd0fc2 | 248 | * `close_tempfile_gently()` but not yet deleted or renamed. This can be used |
1a9d15db MH |
249 | * to implement a sequence of operations like the following: |
250 | * | |
251 | * * Create temporary file. | |
252 | * | |
49bd0fc2 | 253 | * * Write new contents to file, then `close_tempfile_gently()` to cause the |
1a9d15db MH |
254 | * contents to be written to disk. |
255 | * | |
256 | * * Pass the name of the temporary file to another program to allow | |
257 | * it (and nobody else) to inspect or even modify the file's | |
258 | * contents. | |
259 | * | |
6c003d6f JK |
260 | * * `reopen_tempfile()` to reopen the temporary file, truncating the existing |
261 | * contents. Write out the new contents. | |
1a9d15db MH |
262 | * |
263 | * * `rename_tempfile()` to move the file to its permanent location. | |
264 | */ | |
55454427 | 265 | int reopen_tempfile(struct tempfile *tempfile); |
1a9d15db MH |
266 | |
267 | /* | |
268 | * Close the file descriptor and/or file pointer and remove the | |
269 | * temporary file associated with `tempfile`. It is a NOOP to call | |
270 | * `delete_tempfile()` for a `tempfile` object that has already been | |
271 | * deleted or renamed. | |
272 | */ | |
55454427 | 273 | void delete_tempfile(struct tempfile **tempfile_p); |
1a9d15db MH |
274 | |
275 | /* | |
276 | * Close the file descriptor and/or file pointer if they are still | |
277 | * open, and atomically rename the temporary file to `path`. `path` | |
278 | * must be on the same filesystem as the lock file. Return 0 on | |
279 | * success. On failure, delete the temporary file and return -1, with | |
280 | * `errno` set to the value from the failing call to `close(2)` or | |
281 | * `rename(2)`. It is a bug to call `rename_tempfile()` for a | |
282 | * `tempfile` object that is not currently active. | |
283 | */ | |
55454427 | 284 | int rename_tempfile(struct tempfile **tempfile_p, const char *path); |
1a9d15db MH |
285 | |
286 | #endif /* TEMPFILE_H */ |