1 /* Temporary directories and temporary files with automatic cleanup.
2 Copyright (C) 2006, 2011-2020 Free Software Foundation, Inc.
3 Written by Bruno Haible <bruno@clisp.org>, 2006.
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.
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.
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/>. */
23 #include <sys/types.h>
30 /* Temporary directories and temporary files should be automatically removed
31 when the program exits either normally or through a fatal signal. We can't
32 rely on the "unlink before close" idiom, because it works only on Unix and
33 also - if no signal blocking is used - leaves a time window where a fatal
34 signal would not clean up the temporary file.
36 Also, open file descriptors need to be closed before the temporary files
37 and the temporary directories can be removed, because only on Unix
38 (excluding Cygwin) can one remove directories containing open files.
40 This module provides support for
41 - temporary directories and temporary files inside these temporary
43 - temporary files without temporary directories.
44 The temporary directories and files are automatically cleaned up (at the
45 latest) when the program exits or dies from a fatal signal such as SIGINT,
46 SIGTERM, SIGHUP, but not if it dies from a fatal signal such as SIGQUIT,
47 SIGKILL, or SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE.
49 For the cleanup in the normal case, programs that use this module need to
50 call 'cleanup_temp_dir' for each successful return of 'create_temp_dir'.
51 The cleanup in the case of a fatal signal such as SIGINT, SIGTERM, SIGHUP,
52 is done entirely automatically by the functions of this module.
54 Limitations: Files or directories can still be left over if
55 - the program is dies from a fatal signal such as SIGQUIT, SIGKILL, or
56 SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE, or
57 - in a multithreaded program, the fatal signal handler is already running
58 while another thread of the program creates a new temporary directory
60 - on native Windows, some temporary files are used by a subprocess while
61 the fatal signal interrupts the program.
65 /* ============= Temporary files without temporary directories ============= */
67 /* Register the given ABSOLUTE_FILE_NAME as being a file that needs to be
69 Should be called before the file ABSOLUTE_FILE_NAME is created. */
70 extern void register_temporary_file (const char *absolute_file_name
);
72 /* Unregister the given ABSOLUTE_FILE_NAME as being a file that needs to be
74 Should be called when the file ABSOLUTE_FILE_NAME could not be created. */
75 extern void unregister_temporary_file (const char *absolute_file_name
);
77 /* Remove the given ABSOLUTE_FILE_NAME and unregister it.
78 CLEANUP_VERBOSE determines whether errors are reported to standard error.
79 Return 0 upon success, or -1 if there was some problem. */
80 extern int cleanup_temporary_file (const char *absolute_file_name
,
81 bool cleanup_verbose
);
83 /* ========= Temporary directories and temporary files inside them ========= */
87 /* The absolute pathname of the directory. */
88 const char * const dir_name
;
89 /* Whether errors during explicit cleanup are reported to standard error. */
91 /* More fields are present here, but not public. */
94 /* Create a temporary directory.
95 PREFIX is used as a prefix for the name of the temporary directory. It
96 should be short and still give an indication about the program.
97 PARENTDIR can be used to specify the parent directory; if NULL, a default
98 parent directory is used (either $TMPDIR or /tmp or similar).
99 CLEANUP_VERBOSE determines whether errors during explicit cleanup are
100 reported to standard error.
101 Return a fresh 'struct temp_dir' on success. Upon error, an error message
102 is shown and NULL is returned. */
103 extern struct temp_dir
* create_temp_dir (const char *prefix
,
104 const char *parentdir
,
105 bool cleanup_verbose
);
107 /* Register the given ABSOLUTE_FILE_NAME as being a file inside DIR, that
108 needs to be removed before DIR can be removed.
109 Should be called before the file ABSOLUTE_FILE_NAME is created. */
110 extern void register_temp_file (struct temp_dir
*dir
,
111 const char *absolute_file_name
);
113 /* Unregister the given ABSOLUTE_FILE_NAME as being a file inside DIR, that
114 needs to be removed before DIR can be removed.
115 Should be called when the file ABSOLUTE_FILE_NAME could not be created. */
116 extern void unregister_temp_file (struct temp_dir
*dir
,
117 const char *absolute_file_name
);
119 /* Register the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR,
120 that needs to be removed before DIR can be removed.
121 Should be called before the subdirectory ABSOLUTE_DIR_NAME is created. */
122 extern void register_temp_subdir (struct temp_dir
*dir
,
123 const char *absolute_dir_name
);
125 /* Unregister the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR,
126 that needs to be removed before DIR can be removed.
127 Should be called when the subdirectory ABSOLUTE_DIR_NAME could not be
129 extern void unregister_temp_subdir (struct temp_dir
*dir
,
130 const char *absolute_dir_name
);
132 /* Remove the given ABSOLUTE_FILE_NAME and unregister it.
133 Return 0 upon success, or -1 if there was some problem. */
134 extern int cleanup_temp_file (struct temp_dir
*dir
,
135 const char *absolute_file_name
);
137 /* Remove the given ABSOLUTE_DIR_NAME and unregister it.
138 Return 0 upon success, or -1 if there was some problem. */
139 extern int cleanup_temp_subdir (struct temp_dir
*dir
,
140 const char *absolute_dir_name
);
142 /* Remove all registered files and subdirectories inside DIR.
143 Return 0 upon success, or -1 if there was some problem. */
144 extern int cleanup_temp_dir_contents (struct temp_dir
*dir
);
146 /* Remove all registered files and subdirectories inside DIR and DIR itself.
147 DIR cannot be used any more after this call.
148 Return 0 upon success, or -1 if there was some problem. */
149 extern int cleanup_temp_dir (struct temp_dir
*dir
);
151 /* ================== Opening and closing temporary files ================== */
153 /* Open a temporary file in a temporary directory.
154 FILE_NAME must already have been passed to register_temp_file.
155 Registers the resulting file descriptor to be closed.
156 DELETE_ON_CLOSE indicates whether the file can be deleted when the resulting
157 file descriptor or stream is closed. */
158 extern int open_temp (const char *file_name
, int flags
, mode_t mode
,
159 bool delete_on_close
);
160 extern FILE * fopen_temp (const char *file_name
, const char *mode
,
161 bool delete_on_close
);
163 /* Open a temporary file, generating its name based on FILE_NAME_TMPL.
164 FILE_NAME_TMPL must match the rules for mk[s]temp (i.e. end in "XXXXXX",
165 possibly with a suffix). The name constructed does not exist at the time
166 of the call. FILE_NAME_TMPL is overwritten with the result.
167 Registers the file for deletion.
168 Opens the file, with the given FLAGS and mode 0600.
169 Registers the resulting file descriptor to be closed. */
170 extern int gen_register_open_temp (char *file_name_tmpl
, int suffixlen
, int flags
);
172 /* Close a temporary file.
173 FD must have been returned by open_temp or gen_register_open_temp.
174 Unregisters the previously registered file descriptor. */
175 extern int close_temp (int fd
);
177 /* Close a temporary file.
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 fclose_temp (FILE *fp
);
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 fwriteerror_temp (FILE *fp
);
189 /* Like close_stream.
190 FP must have been returned by fopen_temp, or by fdopen on a file descriptor
191 returned by open_temp or gen_register_open_temp.
192 Unregisters the previously registered file descriptor. */
193 extern int close_stream_temp (FILE *fp
);
200 #endif /* _CLEAN_TEMP_H */