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