cheng/libpng
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
structure in the libpng documentation.
This commit is contained in:
Glenn Randers-Pehrson 2011-04-20 22:20:40 -05:00
parent 99778e17af
commit 20786be695
2 changed files with 58 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
libpng-manual.txt
View File

@ -1,6 +1,6 @@
libpng-manual.txt - A description on how to use and modify libpng 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 Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net> <glennrp at users.sourceforge.net>
Copyright (c) 1998-2011 Glenn Randers-Pehrson 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: 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 Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2011 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); 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, If you want to use your own memory allocation routines,
use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use 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_create_read_struct_2() instead of png_create_read_struct():
png_structp png_ptr = png_create_read_struct_2 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_error_fn, user_warning_fn, (png_voidp)
user_mem_ptr, user_malloc_fn, user_free_fn); user_mem_ptr, user_malloc_fn, user_free_fn);
@ -392,6 +383,9 @@ free any memory.
return (ERROR); 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, If you would rather avoid the complexity of setjmp/longjmp issues,
you can compile libpng with PNG_NO_SETJMP, in which case you can compile libpng with PNG_NO_SETJMP, in which case
errors will result in a call to PNG_ABORT() which defaults to abort(). 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 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 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 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); 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 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 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 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, png_destroy_read_struct(&png_ptr, &info_ptr,
&end_info); &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 It is also possible to individually free the info_ptr members that
point to libpng-allocated storage with the following function: 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 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 Since the PNG Development group is an ad-hoc body, we can't make
an official declaration. an official declaration.

50
libpng.3
View File

@ -1,4 +1,4 @@
.TH LIBPNG 3 "April 20, 2011" .TH LIBPNG 3 "April 21, 2011"
.SH NAME .SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.5.3beta04 libpng \- Portable Network Graphics (PNG) Reference Library 1.5.3beta04
.SH SYNOPSIS .SH SYNOPSIS
@ -943,7 +943,7 @@ Following is a copy of the libpng-manual.txt file that accompanies libpng.
.SH LIBPNG.TXT .SH LIBPNG.TXT
libpng-manual.txt - A description on how to use and modify libpng 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 Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net> <glennrp at users.sourceforge.net>
Copyright (c) 1998-2011 Glenn Randers-Pehrson 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: 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 Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2011 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); 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, If you want to use your own memory allocation routines,
use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use 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_create_read_struct_2() instead of png_create_read_struct():
png_structp png_ptr = png_create_read_struct_2 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_error_fn, user_warning_fn, (png_voidp)
user_mem_ptr, user_malloc_fn, user_free_fn); user_mem_ptr, user_malloc_fn, user_free_fn);
@ -1335,6 +1326,9 @@ free any memory.
return (ERROR); 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, If you would rather avoid the complexity of setjmp/longjmp issues,
you can compile libpng with PNG_NO_SETJMP, in which case you can compile libpng with PNG_NO_SETJMP, in which case
errors will result in a call to PNG_ABORT() which defaults to abort(). 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 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 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 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); 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 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 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 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, png_destroy_read_struct(&png_ptr, &info_ptr,
&end_info); &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 It is also possible to individually free the info_ptr members that
point to libpng-allocated storage with the following function: 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 .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 Since the PNG Development group is an ad-hoc body, we can't make
an official declaration. an official declaration.
@ -5375,7 +5387,7 @@ possible without all of you.
Thanks to Frank J. T. Wojcik for helping with the documentation. 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. Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). 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. 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 Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
distributed according to the same disclaimer and license as libpng-1.2.5 distributed according to the same disclaimer and license as libpng-1.2.5
with the following individual added to the list of Contributing Authors 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 Glenn Randers-Pehrson
glennrp at users.sourceforge.net glennrp at users.sourceforge.net
April 20, 2011 April 21, 2011
.\" end of man page .\" end of man page