[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 <jbowler@acm.org>
Signed-off-by: Cosmin Truta <ctruta@gmail.com>

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);
 

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)

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 <stdio.h> 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 <stdio.h>, 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
+ * <stdio.h>.  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

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

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

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. */

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

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)
    {

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)