From 680da02ade3d8f9abcb7bcd3d41e66e8e1187d0a Mon Sep 17 00:00:00 2001 From: Glenn Randers-Pehrson Date: Mon, 21 Nov 2011 17:05:41 -0600 Subject: [PATCH] [libpng15] Updated the documentation of the png_text structure (clarifying that the "lang" and "lang_key" fields can be NULL pointers or might not exist). --- libpng-manual.txt | 29 ++++++++++++++++++----------- libpng.3 | 37 ++++++++++++++++++++++--------------- png.h | 15 +++++++++++---- 3 files changed, 51 insertions(+), 30 deletions(-) diff --git a/libpng-manual.txt b/libpng-manual.txt index 666c88687..4c6e11596 100644 --- a/libpng-manual.txt +++ b/libpng-manual.txt @@ -1,6 +1,6 @@ libpng-manual.txt - A description on how to use and modify libpng - libpng version 1.5.7beta05 - November 18, 2011 + libpng version 1.5.7beta05 - November 21, 2011 Updated and distributed by 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: - libpng versions 0.97, January 1998, through 1.5.7beta05 - November 18, 2011 + libpng versions 0.97, January 1998, through 1.5.7beta05 - November 21, 2011 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2011 Glenn Randers-Pehrson @@ -1265,10 +1265,13 @@ pointer into the info_ptr is returned for any complex types. (empty string for unknown). Note that the itxt_length, lang, and lang_key - members of the text_ptr structure only exist - when the library is built with iTXt chunk support. - Prior to libpng-1.4.0, the default build was - without iTXt chunk support. + members of the text_ptr structure only exist when the + library is built with iTXt chunk support. Prior to + libpng-1.4.0 the library was built by default without + iTXt support. Also note that when iTXt is supported, + they contain NULL pointers when the "compression" + field contains PNG_TEXT_COMPRESSION_NONE or + PNG_TEXT_COMPRESSION_zTXt. num_text - number of comments (same as num_comments; you can put NULL here @@ -2849,11 +2852,15 @@ width, height, bit_depth, and color_type must be the same in each call. empty for unknown). text_ptr[i].translated_keyword - keyword in UTF-8 (NULL or empty for unknown). + Note that the itxt_length, lang, and lang_key - members of the text_ptr structure only exist - when the library is built with iTXt chunk support. - Prior to libpng-1.4.0 the library was built by default - without iTXt support. + members of the text_ptr structure only exist when the + library is built with iTXt chunk support. Prior to + libpng-1.4.0 the library was built by default without + iTXt support. Also note that when iTXt is supported, + they contain NULL pointers when the "compression" + field contains PNG_TEXT_COMPRESSION_NONE or + PNG_TEXT_COMPRESSION_zTXt. num_text - number of comments @@ -4566,7 +4573,7 @@ Other rules can be inferred by inspecting the libpng source. XIV. Y2K Compliance in libpng -November 18, 2011 +November 21, 2011 Since the PNG Development group is an ad-hoc body, we can't make an official declaration. diff --git a/libpng.3 b/libpng.3 index 1324810bc..3375e83f1 100644 --- a/libpng.3 +++ b/libpng.3 @@ -1,4 +1,4 @@ -.TH LIBPNG 3 "November 18, 2011" +.TH LIBPNG 3 "November 21, 2011" .SH NAME libpng \- Portable Network Graphics (PNG) Reference Library 1.5.7beta05 .SH SYNOPSIS @@ -1037,7 +1037,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.7beta05 - November 18, 2011 + libpng version 1.5.7beta05 - November 21, 2011 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2011 Glenn Randers-Pehrson @@ -1048,7 +1048,7 @@ libpng-manual.txt - A description on how to use and modify libpng Based on: - libpng versions 0.97, January 1998, through 1.5.7beta05 - November 18, 2011 + libpng versions 0.97, January 1998, through 1.5.7beta05 - November 21, 2011 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2011 Glenn Randers-Pehrson @@ -2302,10 +2302,13 @@ pointer into the info_ptr is returned for any complex types. (empty string for unknown). Note that the itxt_length, lang, and lang_key - members of the text_ptr structure only exist - when the library is built with iTXt chunk support. - Prior to libpng-1.4.0, the default build was - without iTXt chunk support. + members of the text_ptr structure only exist when the + library is built with iTXt chunk support. Prior to + libpng-1.4.0 the library was built by default without + iTXt support. Also note that when iTXt is supported, + they contain NULL pointers when the "compression" + field contains PNG_TEXT_COMPRESSION_NONE or + PNG_TEXT_COMPRESSION_zTXt. num_text - number of comments (same as num_comments; you can put NULL here @@ -3886,11 +3889,15 @@ width, height, bit_depth, and color_type must be the same in each call. empty for unknown). text_ptr[i].translated_keyword - keyword in UTF-8 (NULL or empty for unknown). + Note that the itxt_length, lang, and lang_key - members of the text_ptr structure only exist - when the library is built with iTXt chunk support. - Prior to libpng-1.4.0 the library was built by default - without iTXt support. + members of the text_ptr structure only exist when the + library is built with iTXt chunk support. Prior to + libpng-1.4.0 the library was built by default without + iTXt support. Also note that when iTXt is supported, + they contain NULL pointers when the "compression" + field contains PNG_TEXT_COMPRESSION_NONE or + PNG_TEXT_COMPRESSION_zTXt. num_text - number of comments @@ -5604,7 +5611,7 @@ Other rules can be inferred by inspecting the libpng source. .SH XIV. Y2K Compliance in libpng -November 18, 2011 +November 21, 2011 Since the PNG Development group is an ad-hoc body, we can't make an official declaration. @@ -5869,7 +5876,7 @@ possible without all of you. Thanks to Frank J. T. Wojcik for helping with the documentation. -Libpng version 1.5.7beta05 - November 18, 2011: +Libpng version 1.5.7beta05 - November 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). @@ -5892,7 +5899,7 @@ this sentence. This code is released under the libpng license. -libpng versions 1.2.6, August 15, 2004, through 1.5.7beta05, November 18, 2011, are +libpng versions 1.2.6, August 15, 2004, through 1.5.7beta05, November 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 @@ -5991,7 +5998,7 @@ certification mark of the Open Source Initiative. Glenn Randers-Pehrson glennrp at users.sourceforge.net -November 18, 2011 +November 21, 2011 .\" end of man page diff --git a/png.h b/png.h index ccee42061..1b0776988 100644 --- a/png.h +++ b/png.h @@ -609,11 +609,18 @@ typedef png_sPLT_t FAR * FAR * png_sPLT_tpp; #ifdef PNG_TEXT_SUPPORTED /* png_text holds the contents of a text/ztxt/itxt chunk in a PNG file, * and whether that contents is compressed or not. The "key" field - * points to a regular zero-terminated C string. The "text", "lang", and - * "lang_key" fields can be regular C strings, empty strings, or NULL pointers. + * points to a regular zero-terminated C string. The "text" fields can be a + * regular C string, an empty string, or a NULL pointer. * However, the structure returned by png_get_text() will always contain - * regular zero-terminated C strings (possibly empty), never NULL pointers, - * so they can be safely used in printf() and other string-handling functions. + * the "text" field as a regular zero-terminated C string (possibly + * empty), never a NULL pointer, so it can be safely used in printf() and + * other string-handling functions. Note that the "itxt_length", "lang", and + * "lang_key" members of the structure only exist when the library is built + * with iTXt chunk support. Prior to libpng-1.4.0 the library was built by + * default without iTXt support. Also note that when iTXt *is* supported, + * the "lang" and "lang_key" fields contain NULL pointers when the + * "compression" field contains * PNG_TEXT_COMPRESSION_NONE or + * PNG_TEXT_COMPRESSION_zTXt. */ typedef struct png_text_struct {