1 /* Temporary directories and temporary files with automatic cleanup. 2 Copyright (C) 2006, 2011-2021 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 #include <stdbool.h> 22 #include <stdio.h> 23 #include <sys/types.h> 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 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. 35 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. 39 40 There are two modules: 41 - 'clean-temp' provides support for temporary directories and temporary 42 files inside these temporary directories, 43 - 'clean-temp-simple' provides support for temporary files without 44 temporary directories. 45 The temporary directories and files are automatically cleaned up (at the 46 latest) when the program exits or dies from a fatal signal such as SIGINT, 47 SIGTERM, SIGHUP, but not if it dies from a fatal signal such as SIGQUIT, 48 SIGKILL, or SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE. 49 50 For the cleanup in the normal case, programs that use this module need to 51 call 'cleanup_temp_dir' for each successful return of 'create_temp_dir'. 52 The cleanup in the case of a fatal signal such as SIGINT, SIGTERM, SIGHUP, 53 is done entirely automatically by the functions of this module. 54 55 Limitations: Files or directories can still be left over if 56 - the program is dies from a fatal signal such as SIGQUIT, SIGKILL, or 57 SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE, or 58 - in a multithreaded program, the fatal signal handler is already running 59 while another thread of the program creates a new temporary directory 60 or temporary file, or 61 - on native Windows, some temporary files are used by a subprocess while 62 the fatal signal interrupts the program. 63 */ 64 65 66 /* ============= Temporary files without temporary directories ============= */ 67 68 #include "clean-temp-simple.h" 69 70 /* ========= Temporary directories and temporary files inside them ========= */ 71 72 struct temp_dir 73 { 74 /* The absolute pathname of the directory. */ 75 const char * const dir_name; 76 /* Whether errors during explicit cleanup are reported to standard error. */ 77 bool cleanup_verbose; 78 /* More fields are present here, but not public. */ 79 }; 80 81 /* Remove all registered files and subdirectories inside DIR and DIR itself. 82 DIR cannot be used any more after this call. 83 Return 0 upon success, or -1 if there was some problem. */ 84 extern int cleanup_temp_dir (struct temp_dir *dir); 85 86 /* Create a temporary directory. 87 PREFIX is used as a prefix for the name of the temporary directory. It 88 should be short and still give an indication about the program. 89 PARENTDIR can be used to specify the parent directory; if NULL, a default 90 parent directory is used (either $TMPDIR or /tmp or similar). 91 CLEANUP_VERBOSE determines whether errors during explicit cleanup are 92 reported to standard error. 93 Return a fresh 'struct temp_dir' on success. Upon error, an error message 94 is shown and NULL is returned. */ 95 extern struct temp_dir * create_temp_dir (const char *prefix, 96 const char *parentdir, 97 bool cleanup_verbose) 98 _GL_ATTRIBUTE_DEALLOC (cleanup_temp_dir, 1); 99 100 /* Register the given ABSOLUTE_FILE_NAME as being a file inside DIR, that 101 needs to be removed before DIR can be removed. 102 Should be called before the file ABSOLUTE_FILE_NAME is created. */ 103 extern void register_temp_file (struct temp_dir *dir, 104 const char *absolute_file_name); 105 106 /* Unregister the given ABSOLUTE_FILE_NAME as being a file inside DIR, that 107 needs to be removed before DIR can be removed. 108 Should be called when the file ABSOLUTE_FILE_NAME could not be created. */ 109 extern void unregister_temp_file (struct temp_dir *dir, 110 const char *absolute_file_name); 111 112 /* Register the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR, 113 that needs to be removed before DIR can be removed. 114 Should be called before the subdirectory ABSOLUTE_DIR_NAME is created. */ 115 extern void register_temp_subdir (struct temp_dir *dir, 116 const char *absolute_dir_name); 117 118 /* Unregister the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR, 119 that needs to be removed before DIR can be removed. 120 Should be called when the subdirectory ABSOLUTE_DIR_NAME could not be 121 created. */ 122 extern void unregister_temp_subdir (struct temp_dir *dir, 123 const char *absolute_dir_name); 124 125 /* Remove the given ABSOLUTE_FILE_NAME and unregister it. 126 Return 0 upon success, or -1 if there was some problem. */ 127 extern int cleanup_temp_file (struct temp_dir *dir, 128 const char *absolute_file_name); 129 130 /* Remove the given ABSOLUTE_DIR_NAME and unregister it. 131 Return 0 upon success, or -1 if there was some problem. */ 132 extern int cleanup_temp_subdir (struct temp_dir *dir, 133 const char *absolute_dir_name); 134 135 /* Remove all registered files and subdirectories inside DIR. 136 Return 0 upon success, or -1 if there was some problem. */ 137 extern int cleanup_temp_dir_contents (struct temp_dir *dir); 138 139 /* ================== Opening and closing temporary files ================== */ 140 141 /* Open a temporary file in a temporary directory. 142 FILE_NAME must already have been passed to register_temp_file. 143 Registers the resulting file descriptor to be closed. 144 DELETE_ON_CLOSE indicates whether the file can be deleted when the resulting 145 file descriptor or stream is closed. */ 146 extern int open_temp (const char *file_name, int flags, mode_t mode, 147 bool delete_on_close); 148 extern FILE * fopen_temp (const char *file_name, const char *mode, 149 bool delete_on_close); 150 151 /* Open a temporary file, generating its name based on FILE_NAME_TMPL. 152 FILE_NAME_TMPL must match the rules for mk[s]temp (i.e. end in "XXXXXX", 153 possibly with a suffix). The name constructed does not exist at the time 154 of the call. FILE_NAME_TMPL is overwritten with the result. 155 A safe choice for MODE is S_IRUSR | S_IWUSR, a.k.a. 0600. 156 Registers the file for deletion. 157 Opens the file, with the given FLAGS and mode MODE. 158 Registers the resulting file descriptor to be closed. */ 159 extern int gen_register_open_temp (char *file_name_tmpl, int suffixlen, 160 int flags, mode_t mode); 161 162 /* Close a temporary file. 163 FD must have been returned by open_temp or gen_register_open_temp. 164 Unregisters the previously registered file descriptor. */ 165 extern int close_temp (int fd); 166 167 /* Close a temporary file. 168 FP must have been returned by fopen_temp, or by fdopen on a file descriptor 169 returned by open_temp or gen_register_open_temp. 170 Unregisters the previously registered file descriptor. */ 171 extern int fclose_temp (FILE *fp); 172 173 /* Like fwriteerror. 174 FP must have been returned by fopen_temp, or by fdopen on a file descriptor 175 returned by open_temp or gen_register_open_temp. 176 Unregisters the previously registered file descriptor. */ 177 extern int fwriteerror_temp (FILE *fp); 178 179 /* Like close_stream. 180 FP must have been returned by fopen_temp, or by fdopen on a file descriptor 181 returned by open_temp or gen_register_open_temp. 182 Unregisters the previously registered file descriptor. */ 183 extern int close_stream_temp (FILE *fp); 184 185 186 #ifdef __cplusplus 187 } 188 #endif 189 190 #endif /* _CLEAN_TEMP_H */