THIS IS A TEST INSTANCE ONLY! REPOSITORIES CAN BE DELETED AT ANY TIME!

Git Source Code Mirror - This is a publish-only repository and all pull requests are ignored. Please follow Documentation/SubmittingPatches procedure for any of your improvements.
git
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

266 lines
9.1KB

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