lib/clean-temp.h

   1 /* Temporary directories and temporary files with automatic cleanup.
   2    Copyright (C) 2006, 2011-2013 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 <http://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    This module provides support for temporary directories and temporary files
  41    inside these temporary directories.  Temporary files without temporary
  42    directories are not supported here.  The temporary directories and files
  43    are automatically cleaned up (at the latest) when the program exits or
  44    dies from a fatal signal such as SIGINT, SIGTERM, SIGHUP, but not if it
  45    dies from a fatal signal such as SIGQUIT, SIGKILL, or SIGABRT, SIGSEGV,
  46    SIGBUS, SIGILL, SIGFPE.
  47
  48    For the cleanup in the normal case, programs that use this module need to
  49    call 'cleanup_temp_dir' for each successful return of 'create_temp_dir'.
  50    The cleanup in the case of a fatal signal such as SIGINT, SIGTERM, SIGHUP,
  51    is done entirely automatically by the functions of this module.  */
  52
  53 struct temp_dir
  54 {
  55   /* The absolute pathname of the directory.  */
  56   const char * const dir_name;
  57   /* Whether errors during explicit cleanup are reported to standard error.  */
  58   bool cleanup_verbose;
  59   /* More fields are present here, but not public.  */
  60 };
  61
  62 /* Create a temporary directory.
  63    PREFIX is used as a prefix for the name of the temporary directory. It
  64    should be short and still give an indication about the program.
  65    PARENTDIR can be used to specify the parent directory; if NULL, a default
  66    parent directory is used (either $TMPDIR or /tmp or similar).
  67    CLEANUP_VERBOSE determines whether errors during explicit cleanup are
  68    reported to standard error.
  69    Return a fresh 'struct temp_dir' on success.  Upon error, an error message
  70    is shown and NULL is returned.  */
  71 extern struct temp_dir * create_temp_dir (const char *prefix,
  72                                           const char *parentdir,
  73                                           bool cleanup_verbose);
  74
  75 /* Register the given ABSOLUTE_FILE_NAME as being a file inside DIR, that
  76    needs to be removed before DIR can be removed.
  77    Should be called before the file ABSOLUTE_FILE_NAME is created.  */
  78 extern void register_temp_file (struct temp_dir *dir,
  79                                 const char *absolute_file_name);
  80
  81 /* Unregister the given ABSOLUTE_FILE_NAME as being a file inside DIR, that
  82    needs to be removed before DIR can be removed.
  83    Should be called when the file ABSOLUTE_FILE_NAME could not be created.  */
  84 extern void unregister_temp_file (struct temp_dir *dir,
  85                                   const char *absolute_file_name);
  86
  87 /* Register the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR,
  88    that needs to be removed before DIR can be removed.
  89    Should be called before the subdirectory ABSOLUTE_DIR_NAME is created.  */
  90 extern void register_temp_subdir (struct temp_dir *dir,
  91                                   const char *absolute_dir_name);
  92
  93 /* Unregister the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR,
  94    that needs to be removed before DIR can be removed.
  95    Should be called when the subdirectory ABSOLUTE_DIR_NAME could not be
  96    created.  */
  97 extern void unregister_temp_subdir (struct temp_dir *dir,
  98                                     const char *absolute_dir_name);
  99
 100 /* Remove the given ABSOLUTE_FILE_NAME and unregister it.
 101    Return 0 upon success, or -1 if there was some problem.  */
 102 extern int cleanup_temp_file (struct temp_dir *dir,
 103                               const char *absolute_file_name);
 104
 105 /* Remove the given ABSOLUTE_DIR_NAME and unregister it.
 106    Return 0 upon success, or -1 if there was some problem.  */
 107 extern int cleanup_temp_subdir (struct temp_dir *dir,
 108                                 const char *absolute_dir_name);
 109
 110 /* Remove all registered files and subdirectories inside DIR.
 111    Return 0 upon success, or -1 if there was some problem.  */
 112 extern int cleanup_temp_dir_contents (struct temp_dir *dir);
 113
 114 /* Remove all registered files and subdirectories inside DIR and DIR itself.
 115    DIR cannot be used any more after this call.
 116    Return 0 upon success, or -1 if there was some problem.  */
 117 extern int cleanup_temp_dir (struct temp_dir *dir);
 118
 119 /* Open a temporary file in a temporary directory.
 120    Registers the resulting file descriptor to be closed.  */
 121 extern int open_temp (const char *file_name, int flags, mode_t mode);
 122 extern FILE * fopen_temp (const char *file_name, const char *mode);
 123
 124 /* Close a temporary file in a temporary directory.
 125    Unregisters the previously registered file descriptor.  */
 126 extern int close_temp (int fd);
 127 extern int fclose_temp (FILE *fp);
 128
 129 /* Like fwriteerror.
 130    Unregisters the previously registered file descriptor.  */
 131 extern int fwriteerror_temp (FILE *fp);
 132
 133 /* Like close_stream.
 134    Unregisters the previously registered file descriptor.  */
 135 extern int close_stream_temp (FILE *fp);
 136
 137
 138 #ifdef __cplusplus
 139 }
 140 #endif
 141
 142 #endif /* _CLEAN_TEMP_H */