1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
/* Temporary directories and temporary files with automatic cleanup.
Copyright (C) 2006, 2011-2020 Free Software Foundation, Inc.
Written by Bruno Haible <bruno@clisp.org>, 2006.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>. */
#ifndef _CLEAN_TEMP_H
#define _CLEAN_TEMP_H
#include <stdbool.h>
#include <stdio.h>
#include <sys/types.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Temporary directories and temporary files should be automatically removed
when the program exits either normally or through a fatal signal. We can't
rely on the "unlink before close" idiom, because it works only on Unix and
also - if no signal blocking is used - leaves a time window where a fatal
signal would not clean up the temporary file.
Also, open file descriptors need to be closed before the temporary files
and the temporary directories can be removed, because only on Unix
(excluding Cygwin) can one remove directories containing open files.
This module provides support for
- temporary directories and temporary files inside these temporary
directories,
- temporary files without temporary directories.
The temporary directories and files are automatically cleaned up (at the
latest) when the program exits or dies from a fatal signal such as SIGINT,
SIGTERM, SIGHUP, but not if it dies from a fatal signal such as SIGQUIT,
SIGKILL, or SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE.
For the cleanup in the normal case, programs that use this module need to
call 'cleanup_temp_dir' for each successful return of 'create_temp_dir'.
The cleanup in the case of a fatal signal such as SIGINT, SIGTERM, SIGHUP,
is done entirely automatically by the functions of this module.
Limitations: Files or directories can still be left over if
- the program is dies from a fatal signal such as SIGQUIT, SIGKILL, or
SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE, or
- in a multithreaded program, the fatal signal handler is already running
while another thread of the program creates a new temporary directory
or temporary file, or
- on native Windows, some temporary files are used by a subprocess while
the fatal signal interrupts the program.
*/
/* ============= Temporary files without temporary directories ============= */
/* Register the given ABSOLUTE_FILE_NAME as being a file that needs to be
removed.
Should be called before the file ABSOLUTE_FILE_NAME is created. */
extern void register_temporary_file (const char *absolute_file_name);
/* Unregister the given ABSOLUTE_FILE_NAME as being a file that needs to be
removed.
Should be called when the file ABSOLUTE_FILE_NAME could not be created. */
extern void unregister_temporary_file (const char *absolute_file_name);
/* Remove the given ABSOLUTE_FILE_NAME and unregister it.
CLEANUP_VERBOSE determines whether errors are reported to standard error.
Return 0 upon success, or -1 if there was some problem. */
extern int cleanup_temporary_file (const char *absolute_file_name,
bool cleanup_verbose);
/* ========= Temporary directories and temporary files inside them ========= */
struct temp_dir
{
/* The absolute pathname of the directory. */
const char * const dir_name;
/* Whether errors during explicit cleanup are reported to standard error. */
bool cleanup_verbose;
/* More fields are present here, but not public. */
};
/* Create a temporary directory.
PREFIX is used as a prefix for the name of the temporary directory. It
should be short and still give an indication about the program.
PARENTDIR can be used to specify the parent directory; if NULL, a default
parent directory is used (either $TMPDIR or /tmp or similar).
CLEANUP_VERBOSE determines whether errors during explicit cleanup are
reported to standard error.
Return a fresh 'struct temp_dir' on success. Upon error, an error message
is shown and NULL is returned. */
extern struct temp_dir * create_temp_dir (const char *prefix,
const char *parentdir,
bool cleanup_verbose);
/* Register the given ABSOLUTE_FILE_NAME as being a file inside DIR, that
needs to be removed before DIR can be removed.
Should be called before the file ABSOLUTE_FILE_NAME is created. */
extern void register_temp_file (struct temp_dir *dir,
const char *absolute_file_name);
/* Unregister the given ABSOLUTE_FILE_NAME as being a file inside DIR, that
needs to be removed before DIR can be removed.
Should be called when the file ABSOLUTE_FILE_NAME could not be created. */
extern void unregister_temp_file (struct temp_dir *dir,
const char *absolute_file_name);
/* Register the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR,
that needs to be removed before DIR can be removed.
Should be called before the subdirectory ABSOLUTE_DIR_NAME is created. */
extern void register_temp_subdir (struct temp_dir *dir,
const char *absolute_dir_name);
/* Unregister the given ABSOLUTE_DIR_NAME as being a subdirectory inside DIR,
that needs to be removed before DIR can be removed.
Should be called when the subdirectory ABSOLUTE_DIR_NAME could not be
created. */
extern void unregister_temp_subdir (struct temp_dir *dir,
const char *absolute_dir_name);
/* Remove the given ABSOLUTE_FILE_NAME and unregister it.
Return 0 upon success, or -1 if there was some problem. */
extern int cleanup_temp_file (struct temp_dir *dir,
const char *absolute_file_name);
/* Remove the given ABSOLUTE_DIR_NAME and unregister it.
Return 0 upon success, or -1 if there was some problem. */
extern int cleanup_temp_subdir (struct temp_dir *dir,
const char *absolute_dir_name);
/* Remove all registered files and subdirectories inside DIR.
Return 0 upon success, or -1 if there was some problem. */
extern int cleanup_temp_dir_contents (struct temp_dir *dir);
/* Remove all registered files and subdirectories inside DIR and DIR itself.
DIR cannot be used any more after this call.
Return 0 upon success, or -1 if there was some problem. */
extern int cleanup_temp_dir (struct temp_dir *dir);
/* ================== Opening and closing temporary files ================== */
/* Open a temporary file in a temporary directory.
FILE_NAME must already have been passed to register_temp_file.
Registers the resulting file descriptor to be closed.
DELETE_ON_CLOSE indicates whether the file can be deleted when the resulting
file descriptor or stream is closed. */
extern int open_temp (const char *file_name, int flags, mode_t mode,
bool delete_on_close);
extern FILE * fopen_temp (const char *file_name, const char *mode,
bool delete_on_close);
/* Open a temporary file, generating its name based on FILE_NAME_TMPL.
FILE_NAME_TMPL must match the rules for mk[s]temp (i.e. end in "XXXXXX",
possibly with a suffix). The name constructed does not exist at the time
of the call. FILE_NAME_TMPL is overwritten with the result.
A safe choice for MODE is S_IRUSR | S_IWUSR, a.k.a. 0600.
Registers the file for deletion.
Opens the file, with the given FLAGS and mode MODE.
Registers the resulting file descriptor to be closed. */
extern int gen_register_open_temp (char *file_name_tmpl, int suffixlen,
int flags, mode_t mode);
/* Close a temporary file.
FD must have been returned by open_temp or gen_register_open_temp.
Unregisters the previously registered file descriptor. */
extern int close_temp (int fd);
/* Close a temporary file.
FP must have been returned by fopen_temp, or by fdopen on a file descriptor
returned by open_temp or gen_register_open_temp.
Unregisters the previously registered file descriptor. */
extern int fclose_temp (FILE *fp);
/* Like fwriteerror.
FP must have been returned by fopen_temp, or by fdopen on a file descriptor
returned by open_temp or gen_register_open_temp.
Unregisters the previously registered file descriptor. */
extern int fwriteerror_temp (FILE *fp);
/* Like close_stream.
FP must have been returned by fopen_temp, or by fdopen on a file descriptor
returned by open_temp or gen_register_open_temp.
Unregisters the previously registered file descriptor. */
extern int close_stream_temp (FILE *fp);
#ifdef __cplusplus
}
#endif
#endif /* _CLEAN_TEMP_H */
|
