From c1fb786d149b8a686eda4d2e0efed5f1bc068b0c Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Sat, 4 Jul 2020 14:52:27 +0200 Subject: [PATCH] clean-temp: Improve comments. * lib/clean-temp.h (open_temp, fopen_temp, close_temp, fclose_temp, fwriteerror_temp, close_stream_temp): Clarify intended use. * lib/clean-temp.c: Likewise. --- ChangeLog | 7 +++++++ lib/clean-temp.c | 17 +++++++++++++++-- lib/clean-temp.h | 11 +++++++++++ 3 files changed, 33 insertions(+), 2 deletions(-) diff --git a/ChangeLog b/ChangeLog index d49c9d7a53..aa31cfa4dd 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2020-07-04 Bruno Haible + + clean-temp: Improve comments. + * lib/clean-temp.h (open_temp, fopen_temp, close_temp, fclose_temp, + fwriteerror_temp, close_stream_temp): Clarify intended use. + * lib/clean-temp.c: Likewise. + 2020-07-04 Bruno Haible clean-temp: Make multithread-safe, part 2. diff --git a/lib/clean-temp.c b/lib/clean-temp.c index 5a311decdf..75bd1eedd5 100644 --- a/lib/clean-temp.c +++ b/lib/clean-temp.c @@ -763,7 +763,10 @@ register_fd (int fd) } /* Open a temporary file in a temporary directory. - Registers the resulting file descriptor to be closed. */ + 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. */ int open_temp (const char *file_name, int flags, mode_t mode, bool delete_on_close) { @@ -789,7 +792,10 @@ open_temp (const char *file_name, int flags, mode_t mode, bool delete_on_close) } /* Open a temporary file in a temporary directory. - Registers the resulting file descriptor to be closed. */ + 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. */ FILE * fopen_temp (const char *file_name, const char *mode, bool delete_on_close) { @@ -835,6 +841,7 @@ fopen_temp (const char *file_name, const char *mode, bool delete_on_close) } /* Close a temporary file in a temporary directory. + FD must have been returned by open_temp. Unregisters the previously registered file descriptor. */ int close_temp (int fd) @@ -962,6 +969,8 @@ fclose_variant_temp (FILE *fp, int (*fclose_variant) (FILE *)) } /* Close a temporary file in a temporary directory. + FP must have been returned by fopen_temp, or by fdopen on a file descriptor + returned by open_temp. Unregisters the previously registered file descriptor. */ int fclose_temp (FILE *fp) @@ -971,6 +980,8 @@ fclose_temp (FILE *fp) #if GNULIB_FWRITEERROR /* Like fwriteerror. + FP must have been returned by fopen_temp, or by fdopen on a file descriptor + returned by open_temp. Unregisters the previously registered file descriptor. */ int fwriteerror_temp (FILE *fp) @@ -981,6 +992,8 @@ fwriteerror_temp (FILE *fp) #if GNULIB_CLOSE_STREAM /* Like close_stream. + FP must have been returned by fopen_temp, or by fdopen on a file descriptor + returned by open_temp. Unregisters the previously registered file descriptor. */ int close_stream_temp (FILE *fp) diff --git a/lib/clean-temp.h b/lib/clean-temp.h index 5b663286c8..7848a15570 100644 --- a/lib/clean-temp.h +++ b/lib/clean-temp.h @@ -117,6 +117,7 @@ extern int cleanup_temp_dir_contents (struct temp_dir *dir); extern int cleanup_temp_dir (struct temp_dir *dir); /* 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. */ @@ -126,15 +127,25 @@ extern FILE * fopen_temp (const char *file_name, const char *mode, bool delete_on_close); /* Close a temporary file in a temporary directory. + FD must have been returned by open_temp. Unregisters the previously registered file descriptor. */ extern int close_temp (int fd); + +/* Close a temporary file in a temporary directory. + FP must have been returned by fopen_temp, or by fdopen on a file descriptor + returned by 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. 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. Unregisters the previously registered file descriptor. */ extern int close_stream_temp (FILE *fp); -- 2.39.5