1 /* Temporary directories and temporary files with automatic cleanup.
2 Copyright (C) 2006, 2011-2023 Free Software Foundation, Inc.
3 Written by Bruno Haible <bruno@clisp.org>, 2006.
4
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <https://www.gnu.org/licenses/>. */
17
18 #ifndef _CLEAN_TEMP_H
19 #define _CLEAN_TEMP_H
20
21 /* This file uses _GL_ATTRIBUTE_DEALLOC. */
22 #if !_GL_CONFIG_H_INCLUDED
23 #error "Please include config.h first."
24 #endif
25
26 #include <stdio.h>
27 #include <sys/types.h>
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33
34 /* Temporary directories and temporary files should be automatically removed
35 when the program exits either normally or through a fatal signal. We can't
36 rely on the "unlink before close" idiom, because it works only on Unix and
37 also - if no signal blocking is used - leaves a time window where a fatal
38 signal would not clean up the temporary file.
39
40 Also, open file descriptors need to be closed before the temporary files
41 and the temporary directories can be removed, because only on Unix
42 (excluding Cygwin) can one remove directories containing open files.
43
44 There are two modules:
45 - 'clean-temp' provides support for temporary directories and temporary
46 files inside these temporary directories,
47 - 'clean-temp-simple' provides support for temporary files without
48 temporary directories.
49 The temporary directories and files are automatically cleaned up (at the
50 latest) when the program exits or dies from a fatal signal such as SIGINT,
51 SIGTERM, SIGHUP, but not if it dies from a fatal signal such as SIGQUIT,
52 SIGKILL, or SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE.
53
54 For the cleanup in the normal case, programs that use this module need to
55 call 'cleanup_temp_dir' for each successful return of 'create_temp_dir'.
56 The cleanup in the case of a fatal signal such as SIGINT, SIGTERM, SIGHUP,
57 is done entirely automatically by the functions of this module.
58
59 Limitations: Files or directories can still be left over if
60 - the program is dies from a fatal signal such as SIGQUIT, SIGKILL, or
61 SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE, or
62 - in a multithreaded program, the fatal signal handler is already running
63 while another thread of the program creates a new temporary directory
64 or temporary file, or
65 - on native Windows, some temporary files are used by a subprocess while
66 the fatal signal interrupts the program.
67 */
68
69
70 /* ============= Temporary files without temporary directories ============= */
71
72 #include "clean-temp-simple.h"
73
74 /* ========= Temporary directories and temporary files inside them ========= */
75
76 struct temp_dir
77 {
78 /* The absolute pathname of the directory. */
79 const char * const dir_name;
80 /* Whether errors during explicit cleanup are reported to standard error. */
81 bool cleanup_verbose;
82 /* More fields are present here, but not public. */
83 };
84
85 /* Remove all registered files and subdirectories inside DIR and DIR itself.
86 DIR cannot be used any more after this call.
87 Return 0 upon success, or -1 if there was some problem. */
88 extern int cleanup_temp_dir (struct temp_dir *dir);
89
90 /* Create a temporary directory.
91 PREFIX is used as a prefix for the name of the temporary directory. It
92 should be short and still give an indication about the program.
93 PARENTDIR can be used to specify the parent directory; if NULL, a default
94 parent directory is used (either $TMPDIR or /tmp or similar).
95 CLEANUP_VERBOSE determines whether errors during explicit cleanup are
96 reported to standard error.
97 Return a fresh 'struct temp_dir' on success. Upon error, an error message
98 is shown and NULL is returned. */
99 extern struct temp_dir * create_temp_dir (const char *prefix,
100 const char *parentdir,
101 bool cleanup_verbose)
102 _GL_ATTRIBUTE_DEALLOC (cleanup_temp_dir, 1);
103
104 /* Register the given ABSOLUTE_FILE_NAME as being a file inside DIR, that
105 needs to be removed before DIR can be removed.
106 Should be called before the file ABSOLUTE_FILE_NAME is created. */
107 extern void register_temp_file (struct temp_dir *dir,
108 const char *absolute_file_name);
109
110 /* Unregister the given ABSOLUTE_FILE_NAME as being a file inside DIR, that
111 needs to be removed before DIR can be removed.
112 Should be called when the file ABSOLUTE_FILE_NAME could not be created. */
113 extern void unregister_temp_file (struct temp_dir *dir,
114 const char *absolute_file_name);
115
116 /* Register the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR,
117 that needs to be removed before DIR can be removed.
118 Should be called before the subdirectory ABSOLUTE_DIR_NAME is created. */
119 extern void register_temp_subdir (struct temp_dir *dir,
120 const char *absolute_dir_name);
121
122 /* Unregister the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR,
123 that needs to be removed before DIR can be removed.
124 Should be called when the subdirectory ABSOLUTE_DIR_NAME could not be
125 created. */
126 extern void unregister_temp_subdir (struct temp_dir *dir,
127 const char *absolute_dir_name);
128
129 /* Remove the given ABSOLUTE_FILE_NAME and unregister it.
130 Return 0 upon success, or -1 if there was some problem. */
131 extern int cleanup_temp_file (struct temp_dir *dir,
132 const char *absolute_file_name);
133
134 /* Remove the given ABSOLUTE_DIR_NAME and unregister it.
135 Return 0 upon success, or -1 if there was some problem. */
136 extern int cleanup_temp_subdir (struct temp_dir *dir,
137 const char *absolute_dir_name);
138
139 /* Remove all registered files and subdirectories inside DIR.
140 Return 0 upon success, or -1 if there was some problem. */
141 extern int cleanup_temp_dir_contents (struct temp_dir *dir);
142
143 /* ================== Opening and closing temporary files ================== */
144
145 /* Open a temporary file in a temporary directory.
146 FILE_NAME must already have been passed to register_temp_file.
147 Registers the resulting file descriptor to be closed.
148 DELETE_ON_CLOSE indicates whether the file can be deleted when the resulting
149 file descriptor or stream is closed. */
150 extern int open_temp (const char *file_name, int flags, mode_t mode,
151 bool delete_on_close);
152 extern FILE * fopen_temp (const char *file_name, const char *mode,
153 bool delete_on_close);
154
155 /* Open a temporary file, generating its name based on FILE_NAME_TMPL.
156 FILE_NAME_TMPL must match the rules for mk[s]temp (i.e. end in "XXXXXX",
157 possibly with a suffix). The name constructed does not exist at the time
158 of the call. FILE_NAME_TMPL is overwritten with the result.
159 A safe choice for MODE is S_IRUSR | S_IWUSR, a.k.a. 0600.
160 Registers the file for deletion.
161 Opens the file, with the given FLAGS and mode MODE.
162 Registers the resulting file descriptor to be closed. */
163 extern int gen_register_open_temp (char *file_name_tmpl, int suffixlen,
164 int flags, mode_t mode);
165
166 /* Close a temporary file.
167 FD must have been returned by open_temp or gen_register_open_temp.
168 Unregisters the previously registered file descriptor. */
169 extern int close_temp (int fd);
170
171 /* Close a temporary file.
172 FP must have been returned by fopen_temp, or by fdopen on a file descriptor
173 returned by open_temp or gen_register_open_temp.
174 Unregisters the previously registered file descriptor. */
175 extern int fclose_temp (FILE *fp);
176
177 /* Like fwriteerror.
178 FP must have been returned by fopen_temp, or by fdopen on a file descriptor
179 returned by open_temp or gen_register_open_temp.
180 Unregisters the previously registered file descriptor. */
181 extern int fwriteerror_temp (FILE *fp);
182
183 /* Like close_stream.
184 FP must have been returned by fopen_temp, or by fdopen on a file descriptor
185 returned by open_temp or gen_register_open_temp.
186 Unregisters the previously registered file descriptor. */
187 extern int close_stream_temp (FILE *fp);
188
189
190 #ifdef __cplusplus
191 }
192 #endif
193
194 #endif /* _CLEAN_TEMP_H */