[libpng18] chore: Clean up the FILE * formulations in code and in d…

…ocumentation 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 c63c546 from branch 'libpng18'. Reviewed-by: John Bowler <[email protected]> Signed-off-by: Cosmin Truta <[email protected]>
ctruta · Feb 26, 2025 · 44f97f0 · 44f97f0
1 parent 044536d
commit 44f97f0
Show file tree

Hide file tree

Showing 9 changed files with 23 additions and 22 deletions.
diff --git 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
@@ -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
@@ -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

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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)