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