[devel] Added more about creating and destroying the optional "end_info"

structure in the libpng documentation.

libpng-manual.txt

@@ -1,6 +1,6 @@
 libpng-manual.txt - A description on how to use and modify libpng
 
- libpng version 1.5.3beta04 - April 20, 2011
+ libpng version 1.5.3beta04 - April 21, 2011
  Updated and distributed by Glenn Randers-Pehrson
  <glennrp at users.sourceforge.net>
  Copyright (c) 1998-2011 Glenn Randers-Pehrson
@@ -11,7 +11,7 @@ libpng-manual.txt - A description on how to use and modify libpng
 
  Based on:
 
- libpng versions 0.97, January 1998, through 1.5.3beta04 - April 20, 2011
+ libpng versions 0.97, January 1998, through 1.5.3beta04 - April 21, 2011
  Updated and distributed by Glenn Randers-Pehrson
  Copyright (c) 1998-2011 Glenn Randers-Pehrson
 
@@ -348,21 +348,12 @@ create the structure, so your application should check for that.
        return (ERROR);
     }
 
-    png_infop end_info = png_create_info_struct(png_ptr);
-
-    if (!end_info)
-    {
-       png_destroy_read_struct(&png_ptr, &info_ptr,
-          (png_infopp)NULL);
-       return (ERROR);
-    }
-
 If you want to use your own memory allocation routines,
 use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
 png_create_read_struct_2() instead of png_create_read_struct():
 
     png_structp png_ptr = png_create_read_struct_2
-       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
+        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
         user_error_fn, user_warning_fn, (png_voidp)
         user_mem_ptr, user_malloc_fn, user_free_fn);
 
@@ -392,6 +383,9 @@ free any memory.
        return (ERROR);
     }
 
+Pass (png_infopp)NULL instead of &end_info if you didn't create
+an end_info structure.
+
 If you would rather avoid the complexity of setjmp/longjmp issues,
 you can compile libpng with PNG_NO_SETJMP, in which case
 errors will result in a call to PNG_ABORT() which defaults to abort().
@@ -1824,11 +1818,24 @@ low-level interface, you can finish reading the file.  If you are
 interested in comments or time, which may be stored either before or
 after the image data, you should pass the separate png_info struct if
 you want to keep the comments from before and after the image
-separate.  If you are not interested, you should still call png_read_end()
+separate.
-but you can pass NULL, avoiding the need to create an end_info structure.
+
+    png_infop end_info = png_create_info_struct(png_ptr);
+
+    if (!end_info)
+    {
+       png_destroy_read_struct(&png_ptr, &info_ptr,
+           (png_infopp)NULL);
+       return (ERROR);
+    }
 
    png_read_end(png_ptr, end_info);
 
+If you are not interested, you should still call png_read_end()
+but you can pass NULL, avoiding the need to create an end_info structure.
+
+   png_read_end(png_ptr, (png_infop)NULL);
+
 If you don't call png_read_end(), then your file pointer will be
 left pointing to the first chunk after the last IDAT, which is probably
 not what you want if you expect to read something beyond the end of
@@ -1839,6 +1846,11 @@ When you are done, you can free all memory allocated by libpng like this:
    png_destroy_read_struct(&png_ptr, &info_ptr,
        &end_info);
 
+or, if you didn't create an end_info structure,
+
+   png_destroy_read_struct(&png_ptr, &info_ptr,
+       (png_infopp)NULL);
+
 It is also possible to individually free the info_ptr members that
 point to libpng-allocated storage with the following function:
 
@@ -4180,7 +4192,7 @@ Other rules can be inferred by inspecting the libpng source.
 
 XIV. Y2K Compliance in libpng
 
-April 20, 2011
+April 21, 2011
 
 Since the PNG Development group is an ad-hoc body, we can't make
 an official declaration.

libpng.3

@@ -1,4 +1,4 @@
-.TH LIBPNG 3 "April 20, 2011"
+.TH LIBPNG 3 "April 21, 2011"
 .SH NAME
 libpng \- Portable Network Graphics (PNG) Reference Library 1.5.3beta04
 .SH SYNOPSIS
@@ -943,7 +943,7 @@ Following is a copy of the libpng-manual.txt file that accompanies libpng.
 .SH LIBPNG.TXT
 libpng-manual.txt - A description on how to use and modify libpng
 
- libpng version 1.5.3beta04 - April 20, 2011
+ libpng version 1.5.3beta04 - April 21, 2011
  Updated and distributed by Glenn Randers-Pehrson
  <glennrp at users.sourceforge.net>
  Copyright (c) 1998-2011 Glenn Randers-Pehrson
@@ -954,7 +954,7 @@ libpng-manual.txt - A description on how to use and modify libpng
 
  Based on:
 
- libpng versions 0.97, January 1998, through 1.5.3beta04 - April 20, 2011
+ libpng versions 0.97, January 1998, through 1.5.3beta04 - April 21, 2011
  Updated and distributed by Glenn Randers-Pehrson
  Copyright (c) 1998-2011 Glenn Randers-Pehrson
 
@@ -1291,21 +1291,12 @@ create the structure, so your application should check for that.
        return (ERROR);
     }
 
-    png_infop end_info = png_create_info_struct(png_ptr);
-
-    if (!end_info)
-    {
-       png_destroy_read_struct(&png_ptr, &info_ptr,
-          (png_infopp)NULL);
-       return (ERROR);
-    }
-
 If you want to use your own memory allocation routines,
 use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
 png_create_read_struct_2() instead of png_create_read_struct():
 
     png_structp png_ptr = png_create_read_struct_2
-       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
+        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
         user_error_fn, user_warning_fn, (png_voidp)
         user_mem_ptr, user_malloc_fn, user_free_fn);
 
@@ -1335,6 +1326,9 @@ free any memory.
        return (ERROR);
     }
 
+Pass (png_infopp)NULL instead of &end_info if you didn't create
+an end_info structure.
+
 If you would rather avoid the complexity of setjmp/longjmp issues,
 you can compile libpng with PNG_NO_SETJMP, in which case
 errors will result in a call to PNG_ABORT() which defaults to abort().
@@ -2767,11 +2761,24 @@ low-level interface, you can finish reading the file.  If you are
 interested in comments or time, which may be stored either before or
 after the image data, you should pass the separate png_info struct if
 you want to keep the comments from before and after the image
-separate.  If you are not interested, you should still call png_read_end()
+separate.
-but you can pass NULL, avoiding the need to create an end_info structure.
+
+    png_infop end_info = png_create_info_struct(png_ptr);
+
+    if (!end_info)
+    {
+       png_destroy_read_struct(&png_ptr, &info_ptr,
+           (png_infopp)NULL);
+       return (ERROR);
+    }
 
    png_read_end(png_ptr, end_info);
 
+If you are not interested, you should still call png_read_end()
+but you can pass NULL, avoiding the need to create an end_info structure.
+
+   png_read_end(png_ptr, (png_infop)NULL);
+
 If you don't call png_read_end(), then your file pointer will be
 left pointing to the first chunk after the last IDAT, which is probably
 not what you want if you expect to read something beyond the end of
@@ -2782,6 +2789,11 @@ When you are done, you can free all memory allocated by libpng like this:
    png_destroy_read_struct(&png_ptr, &info_ptr,
        &end_info);
 
+or, if you didn't create an end_info structure,
+
+   png_destroy_read_struct(&png_ptr, &info_ptr,
+       (png_infopp)NULL);
+
 It is also possible to individually free the info_ptr members that
 point to libpng-allocated storage with the following function:
 
@@ -5123,7 +5135,7 @@ Other rules can be inferred by inspecting the libpng source.
 
 .SH XIV. Y2K Compliance in libpng
 
-April 20, 2011
+April 21, 2011
 
 Since the PNG Development group is an ad-hoc body, we can't make
 an official declaration.
@@ -5375,7 +5387,7 @@ possible without all of you.
 
 Thanks to Frank J. T. Wojcik for helping with the documentation.
 
-Libpng version 1.5.3beta04 - April 20, 2011:
+Libpng version 1.5.3beta04 - April 21, 2011:
 Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
 Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
 
@@ -5398,7 +5410,7 @@ this sentence.
 
 This code is released under the libpng license.
 
-libpng versions 1.2.6, August 15, 2004, through 1.5.3beta04, April 20, 2011, are
+libpng versions 1.2.6, August 15, 2004, through 1.5.3beta04, April 21, 2011, are
 Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
 distributed according to the same disclaimer and license as libpng-1.2.5
 with the following individual added to the list of Contributing Authors
@@ -5497,7 +5509,7 @@ certification mark of the Open Source Initiative.
 
 Glenn Randers-Pehrson
 glennrp at users.sourceforge.net
-April 20, 2011
+April 21, 2011
 
 .\" end of man page