lib/clean-temp.h

   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 /* Create a temporary directory.
  82    PREFIX is used as a prefix for the name of the temporary directory. It
  83    should be short and still give an indication about the program.
  84    PARENTDIR can be used to specify the parent directory; if NULL, a default
  85    parent directory is used (either $TMPDIR or /tmp or similar).
  86    CLEANUP_VERBOSE determines whether errors during explicit cleanup are
  87    reported to standard error.
  88    Return a fresh 'struct temp_dir' on success.  Upon error, an error message
  89    is shown and NULL is returned.  */
  90 extern struct temp_dir * create_temp_dir (const char *prefix,
  91                                           const char *parentdir,
  92                                           bool cleanup_verbose);
  93
  94 /* Register the given ABSOLUTE_FILE_NAME as being a file inside DIR, that
  95    needs to be removed before DIR can be removed.
  96    Should be called before the file ABSOLUTE_FILE_NAME is created.  */
  97 extern void register_temp_file (struct temp_dir *dir,
  98                                 const char *absolute_file_name);
  99
 100 /* Unregister 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 when the file ABSOLUTE_FILE_NAME could not be created.  */
 103 extern void unregister_temp_file (struct temp_dir *dir,
 104                                   const char *absolute_file_name);
 105
 106 /* Register the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR,
 107    that needs to be removed before DIR can be removed.
 108    Should be called before the subdirectory ABSOLUTE_DIR_NAME is created.  */
 109 extern void register_temp_subdir (struct temp_dir *dir,
 110                                   const char *absolute_dir_name);
 111
 112 /* Unregister 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 when the subdirectory ABSOLUTE_DIR_NAME could not be
 115    created.  */
 116 extern void unregister_temp_subdir (struct temp_dir *dir,
 117                                     const char *absolute_dir_name);
 118
 119 /* Remove the given ABSOLUTE_FILE_NAME and unregister it.
 120    Return 0 upon success, or -1 if there was some problem.  */
 121 extern int cleanup_temp_file (struct temp_dir *dir,
 122                               const char *absolute_file_name);
 123
 124 /* Remove the given ABSOLUTE_DIR_NAME and unregister it.
 125    Return 0 upon success, or -1 if there was some problem.  */
 126 extern int cleanup_temp_subdir (struct temp_dir *dir,
 127                                 const char *absolute_dir_name);
 128
 129 /* Remove all registered files and subdirectories inside DIR.
 130    Return 0 upon success, or -1 if there was some problem.  */
 131 extern int cleanup_temp_dir_contents (struct temp_dir *dir);
 132
 133 /* Remove all registered files and subdirectories inside DIR and DIR itself.
 134    DIR cannot be used any more after this call.
 135    Return 0 upon success, or -1 if there was some problem.  */
 136 extern int cleanup_temp_dir (struct temp_dir *dir);
 137
 138 /* ================== Opening and closing temporary files ================== */
 139
 140 /* Open a temporary file in a temporary directory.
 141    FILE_NAME must already have been passed to register_temp_file.
 142    Registers the resulting file descriptor to be closed.
 143    DELETE_ON_CLOSE indicates whether the file can be deleted when the resulting
 144    file descriptor or stream is closed.  */
 145 extern int open_temp (const char *file_name, int flags, mode_t mode,
 146                       bool delete_on_close);
 147 extern FILE * fopen_temp (const char *file_name, const char *mode,
 148                           bool delete_on_close);
 149
 150 /* Open a temporary file, generating its name based on FILE_NAME_TMPL.
 151    FILE_NAME_TMPL must match the rules for mk[s]temp (i.e. end in "XXXXXX",
 152    possibly with a suffix).  The name constructed does not exist at the time
 153    of the call.  FILE_NAME_TMPL is overwritten with the result.
 154    A safe choice for MODE is S_IRUSR | S_IWUSR, a.k.a. 0600.
 155    Registers the file for deletion.
 156    Opens the file, with the given FLAGS and mode MODE.
 157    Registers the resulting file descriptor to be closed.  */
 158 extern int gen_register_open_temp (char *file_name_tmpl, int suffixlen,
 159                                    int flags, mode_t mode);
 160
 161 /* Close a temporary file.
 162    FD must have been returned by open_temp or gen_register_open_temp.
 163    Unregisters the previously registered file descriptor.  */
 164 extern int close_temp (int fd);
 165
 166 /* Close a temporary file.
 167    FP must have been returned by fopen_temp, or by fdopen on a file descriptor
 168    returned by open_temp or gen_register_open_temp.
 169    Unregisters the previously registered file descriptor.  */
 170 extern int fclose_temp (FILE *fp);
 171
 172 /* Like fwriteerror.
 173    FP must have been returned by fopen_temp, or by fdopen on a file descriptor
 174    returned by open_temp or gen_register_open_temp.
 175    Unregisters the previously registered file descriptor.  */
 176 extern int fwriteerror_temp (FILE *fp);
 177
 178 /* Like close_stream.
 179    FP must have been returned by fopen_temp, or by fdopen on a file descriptor
 180    returned by open_temp or gen_register_open_temp.
 181    Unregisters the previously registered file descriptor.  */
 182 extern int close_stream_temp (FILE *fp);
 183
 184
 185 #ifdef __cplusplus
 186 }
 187 #endif
 188
 189 #endif /* _CLEAN_TEMP_H */