From 44f97f08d729fcc77ea5d08e02cd538523dd7157 Mon Sep 17 00:00:00 2001 From: Cosmin Truta Date: Fri, 21 Feb 2025 15:34:09 +0200 Subject: [PATCH] [libpng18] chore: Clean up the `FILE *` formulations in code and in documentation We should use `FILE *` instead of `FILE*` or `(FILE*)`, consistently, as we should for all other pointer types. Moreover, when we refer to standard stdio file objects in comments and in documentation, we should use the term "FILE objects" consistently. Lastly, we clarify in a comment in example.c that `PNG_STDIO_SUPPORTED` is true only when the stdio support is both available in the system and accessible in the user's libpng build. This is a cherry-pick of commit c63c5463903014c904b540216c2784023fb8c1c8 from branch 'libpng18'. Reviewed-by: John Bowler Signed-off-by: Cosmin Truta --- contrib/examples/pngpixel.c | 10 +++++----- contrib/libtests/pngstest.c | 3 ++- example.c | 12 ++++++------ libpng-manual.txt | 4 ++-- libpng.3 | 6 +++--- png.c | 2 +- png.h | 4 ++-- pngread.c | 2 +- pngwrite.c | 2 +- 9 files changed, 23 insertions(+), 22 deletions(-) diff --git a/contrib/examples/pngpixel.c b/contrib/examples/pngpixel.c index 9185d518fb..6486844a47 100644 --- a/contrib/examples/pngpixel.c +++ b/contrib/examples/pngpixel.c @@ -184,11 +184,11 @@ int main(int argc, const char **argv) compression_method, filter_method; png_bytep row_tmp; - /* Now associate the recently opened (FILE*) with the default - * libpng initialization functions. Sometimes libpng is - * compiled without stdio support (it can be difficult to do - * in some environments); in that case you will have to write - * your own read callback to read data from the (FILE*). + /* Now associate the recently opened FILE object with the + * default libpng initialization functions. Sometimes libpng + * is compiled without stdio support (it can be difficult to + * do in some environments); in that case you will have to + * write your own read callback to read data from the stream. */ png_init_io(png_ptr, f); diff --git a/contrib/libtests/pngstest.c b/contrib/libtests/pngstest.c index 1d15421b52..efdcdbfef4 100644 --- a/contrib/libtests/pngstest.c +++ b/contrib/libtests/pngstest.c @@ -595,7 +595,8 @@ newimage(Image *image) memset(image, 0, sizeof *image); } -/* Reset the image to be read again - only needs to rewind the FILE* at present. +/* Reset the image to be read again - only needs to rewind the FILE object at + * present. */ static void resetimage(Image *image) diff --git a/example.c b/example.c index dd53d8a871..8928d30177 100644 --- a/example.c +++ b/example.c @@ -2,7 +2,7 @@ /* example.c - an example of using libpng * - * Maintained 2018-2024 Cosmin Truta + * Maintained 2018-2025 Cosmin Truta * Maintained 1998-2016 Glenn Randers-Pehrson * Maintained 1996-1997 Andreas Dilger * Written 1995-1996 Guy Eric Schalnat, Group 42, Inc. @@ -179,11 +179,11 @@ int main(int argc, const char **argv) * components. * * You do not have to read directly from a file. You can read from memory or, - * on systems that support it, from a FILE*. This is controlled by - * the particular png_image_read_from_ function you call at the start. - * Likewise, on write, you can write to a FILE* if your system supports it. - * Check the macro PNG_STDIO_SUPPORTED to see if stdio support has been - * included in your libpng build. + * on systems that support , from a FILE object. This is controlled + * by the particular png_image_read_from_ function you call at the start. + * Likewise, on write, you can write to a FILE object if your system supports + * . The macro PNG_STDIO_SUPPORTED indicates if stdio is available + * and accessible from your libpng build. * * If you read 16-bit (PNG_FORMAT_FLAG_LINEAR) data, you may need to write it * in the 8-bit format for display. You do this by setting the convert_to_8bit diff --git a/libpng-manual.txt b/libpng-manual.txt index 862fe2c5d0..d364e47de7 100644 --- a/libpng-manual.txt +++ b/libpng-manual.txt @@ -4089,7 +4089,7 @@ READ APIs is filled in from the PNG header in the file. int png_image_begin_read_from_stdio (png_imagep image, - FILE* file) + FILE *file) The PNG header is read from the stdio FILE object. @@ -4164,7 +4164,7 @@ be written: int convert_to_8_bit, const void *buffer, png_int_32 row_stride, const void *colormap) - Write the image to the given (FILE*). + Write the image to the given FILE object. With all write APIs if image is in one of the linear formats with (png_uint_16) data then setting convert_to_8_bit will cause the output to be diff --git a/libpng.3 b/libpng.3 index 923b6772eb..50e389f0c6 100644 --- a/libpng.3 +++ b/libpng.3 @@ -223,7 +223,7 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.6.47 \fBint png_image_begin_read_from_file (png_imagep \fP\fIimage\fP\fB, const char \fI*file_name\fP\fB);\fP -\fBint png_image_begin_read_from_stdio (png_imagep \fP\fIimage\fP\fB, FILE* \fIfile\fP\fB);\fP +\fBint png_image_begin_read_from_stdio (png_imagep \fP\fIimage\fP\fB, FILE *\fIfile\fP\fB);\fP \fBint, png_image_begin_read_from_memory (png_imagep \fP\fIimage\fP\fB, png_const_voidp \fP\fImemory\fP\fB, size_t \fIsize\fP\fB);\fP @@ -4608,7 +4608,7 @@ READ APIs is filled in from the PNG header in the file. int png_image_begin_read_from_stdio (png_imagep image, - FILE* file) + FILE *file) The PNG header is read from the stdio FILE object. @@ -4683,7 +4683,7 @@ be written: int convert_to_8_bit, const void *buffer, png_int_32 row_stride, const void *colormap) - Write the image to the given (FILE*). + Write the image to the given FILE object. With all write APIs if image is in one of the linear formats with (png_uint_16) data then setting convert_to_8_bit will cause the output to be diff --git a/png.c b/png.c index 43104e32a7..90ca03d651 100644 --- a/png.c +++ b/png.c @@ -3969,7 +3969,7 @@ png_image_free_function(png_voidp argument) # ifdef PNG_STDIO_SUPPORTED if (cp->owned_file != 0) { - FILE *fp = png_voidcast(FILE*, cp->png_ptr->io_ptr); + FILE *fp = png_voidcast(FILE *, cp->png_ptr->io_ptr); cp->owned_file = 0; /* Ignore errors here. */ diff --git a/png.h b/png.h index 46f24feffe..a173f89bbf 100644 --- a/png.h +++ b/png.h @@ -3088,7 +3088,7 @@ PNG_EXPORT(234, int, png_image_begin_read_from_file, (png_imagep image, */ PNG_EXPORT(235, int, png_image_begin_read_from_stdio, (png_imagep image, - FILE* file)); + FILE *file)); /* The PNG header is read from the stdio FILE object. */ #endif /* STDIO */ @@ -3163,7 +3163,7 @@ PNG_EXPORT(239, int, png_image_write_to_file, (png_imagep image, PNG_EXPORT(240, int, png_image_write_to_stdio, (png_imagep image, FILE *file, int convert_to_8_bit, const void *buffer, png_int_32 row_stride, const void *colormap)); - /* Write the image to the given (FILE*). */ + /* Write the image to the given FILE object. */ #endif /* SIMPLIFIED_WRITE_STDIO */ /* With all write APIs if image is in one of the linear formats with 16-bit diff --git a/pngread.c b/pngread.c index 0fd364827e..4f55f6408b 100644 --- a/pngread.c +++ b/pngread.c @@ -1328,7 +1328,7 @@ png_image_read_header(png_voidp argument) #ifdef PNG_STDIO_SUPPORTED int PNGAPI -png_image_begin_read_from_stdio(png_imagep image, FILE* file) +png_image_begin_read_from_stdio(png_imagep image, FILE *file) { if (image != NULL && image->version == PNG_IMAGE_VERSION) { diff --git a/pngwrite.c b/pngwrite.c index b7aeff4ce4..35a5d17b60 100644 --- a/pngwrite.c +++ b/pngwrite.c @@ -2333,7 +2333,7 @@ int PNGAPI png_image_write_to_stdio(png_imagep image, FILE *file, int convert_to_8bit, const void *buffer, png_int_32 row_stride, const void *colormap) { - /* Write the image to the given (FILE*). */ + /* Write the image to the given FILE object. */ if (image != NULL && image->version == PNG_IMAGE_VERSION) { if (file != NULL && buffer != NULL)