diff options
| author | dartraiden <wowemuh@gmail.com> | 2018-07-19 16:22:00 +0300 |
|---|---|---|
| committer | dartraiden <wowemuh@gmail.com> | 2018-07-19 16:22:00 +0300 |
| commit | f9ea017839ead14169ed49c77edf0d1b4f592963 (patch) | |
| tree | cfdb7940043c43001290c2600a9feb1b69590c12 | |
| parent | 9bc141d8595992785b086299a1d433c32b05c7cd (diff) | |
Remove useless docs
| -rw-r--r-- | libs/freeimage/src/LibPNG/CHANGES | 6051 | ||||
| -rw-r--r-- | libs/freeimage/src/LibPNG/INSTALL | 465 | ||||
| -rw-r--r-- | libs/freeimage/src/LibPNG/README | 222 | ||||
| -rw-r--r-- | libs/freeimage/src/LibPNG/TODO | 30 | ||||
| -rw-r--r-- | libs/freeimage/src/LibPNG/libpng-manual.txt | 5464 | ||||
| -rw-r--r-- | libs/liblua/docs/contents.html | 619 | ||||
| -rw-r--r-- | libs/liblua/docs/index.css | 21 | ||||
| -rw-r--r-- | libs/liblua/docs/manual.css | 21 | ||||
| -rw-r--r-- | libs/liblua/docs/manual.html | 10982 |
9 files changed, 0 insertions, 23875 deletions
diff --git a/libs/freeimage/src/LibPNG/CHANGES b/libs/freeimage/src/LibPNG/CHANGES deleted file mode 100644 index 4b82118910..0000000000 --- a/libs/freeimage/src/LibPNG/CHANGES +++ /dev/null @@ -1,6051 +0,0 @@ -#if 0 -CHANGES - changes for libpng - -version 0.1 [March 29, 1995] - initial work-in-progress release - -version 0.2 [April 1, 1995] - added reader into png.h - fixed small problems in stub file - -version 0.3 [April 8, 1995] - added pull reader - split up pngwrite.c to several files - added pnglib.txt - added example.c - cleaned up writer, adding a few new transformations - fixed some bugs in writer - interfaced with zlib 0.5 - added K&R support - added check for 64 KB blocks for 16 bit machines - -version 0.4 [April 26, 1995] - cleaned up code and commented code - simplified time handling into png_time - created png_color_16 and png_color_8 to handle color needs - cleaned up color type defines - fixed various bugs - made various names more consistent - interfaced with zlib 0.71 - cleaned up zTXt reader and writer (using zlib's Reset functions) - split transformations into pngrtran.c and pngwtran.c - -version 0.5 [April 30, 1995] - interfaced with zlib 0.8 - fixed many reading and writing bugs - saved using 3 spaces instead of tabs - -version 0.6 [May 1, 1995] - first beta release - added png_large_malloc() and png_large_free() - added png_size_t - cleaned up some compiler warnings - added png_start_read_image() - -version 0.7 [June 24, 1995] - cleaned up lots of bugs - finished dithering and other stuff - added test program - changed name from pnglib to libpng - -version 0.71 [June 26, 1995] - changed pngtest.png for zlib 0.93 - fixed error in libpng.txt and example.c - -version 0.8 [August 20, 1995] - cleaned up some bugs - added png_set_filler() - split up pngstub.c into pngmem.c, pngio.c, and pngerror.c - added #define's to remove unwanted code - moved png_info_init() to png.c - added old_size into png_realloc() - added functions to manually set filtering and compression info - changed compression parameters based on image type - optimized filter selection code - added version info - changed external functions passing floats to doubles (k&r problems?) - put all the configurable stuff in pngconf.h - enabled png_set_shift to work with paletted images on read - added png_read_update_info() - updates info structure with transformations - -Version 0.81 [August, 1995] - incorporated Tim Wegner's medium model code (thanks, Tim) - -Version 0.82 [September, 1995] - [unspecified changes] - -Version 0.85 [December, 1995] - added more medium model code (almost everything's a far) - added i/o, error, and memory callback functions - fixed some bugs (16-bit, 4-bit interlaced, etc.) - added first run progressive reader (barely tested) - -Version 0.86 [January, 1996] - fixed bugs - improved documentation - -Version 0.87 [January, 1996] - fixed medium model bugs - fixed other bugs introduced in 0.85 and 0.86 - added some minor documentation - -Version 0.88 [January, 1996] - fixed progressive bugs - replaced tabs with spaces - cleaned up documentation - added callbacks for read/write and warning/error functions - -Version 0.89 [June 5, 1996] - Added new initialization API to make libpng work better with shared libs - we now have png_create_read_struct(), png_create_write_struct(), - png_create_info_struct(), png_destroy_read_struct(), and - png_destroy_write_struct() instead of the separate calls to - malloc and png_read_init(), png_info_init(), and png_write_init() - Changed warning/error callback functions to fix bug - this means you - should use the new initialization API if you were using the old - png_set_message_fn() calls, and that the old API no longer exists - so that people are aware that they need to change their code - Changed filter selection API to allow selection of multiple filters - since it didn't work in previous versions of libpng anyways - Optimized filter selection code - Fixed png_set_background() to allow using an arbitrary RGB color for - paletted images - Fixed gamma and background correction for paletted images, so - png_correct_palette is not needed unless you are correcting an - external palette (you will need to #define PNG_CORRECT_PALETTE_SUPPORTED - in pngconf.h) - if nobody uses this, it may disappear in the future. - Fixed bug with Borland 64K memory allocation (Alexander Lehmann) - Fixed bug in interlace handling (Smarasderagd, I think) - Added more error checking for writing and image to reduce invalid files - Separated read and write functions so that they won't both be linked - into a binary when only reading or writing functionality is used - New pngtest image also has interlacing and zTXt - Updated documentation to reflect new API - -Version 0.89c [June 17, 1996] - Bug fixes. - -Version 0.90 [January, 1997] - Made CRC errors/warnings on critical and ancillary chunks configurable - libpng will use the zlib CRC routines by (compile-time) default - Changed DOS small/medium model memory support - needs zlib 1.04 (Tim Wegner) - Added external C++ wrapper statements to png.h (Gilles Dauphin) - Allow PNG file to be read when some or all of file signature has already - been read from the beginning of the stream. ****This affects the size - of info_struct and invalidates all programs that use a shared libpng**** - Fixed png_filler() declarations - Fixed? background color conversions - Fixed order of error function pointers to match documentation - Current chunk name is now available in png_struct to reduce the number - of nearly identical error messages (will simplify multi-lingual - support when available) - Try to get ready for unknown-chunk callback functions: - - previously read critical chunks are flagged, so the chunk handling - routines can determine if the chunk is in the right place - - all chunk handling routines have the same prototypes, so we will - be able to handle all chunks via a callback mechanism - Try to fix Linux "setjmp" buffer size problems - Removed png_large_malloc, png_large_free, and png_realloc functions. - -Version 0.95 [March, 1997] - Fixed bug in pngwutil.c allocating "up_row" twice and "avg_row" never - Fixed bug in PNG file signature compares when start != 0 - Changed parameter type of png_set_filler(...filler...) from png_byte - to png_uint_32 - Added test for MACOS to ensure that both math.h and fp.h are not #included - Added macros for libpng to be compiled as a Windows DLL (Andreas Kupries) - Added "packswap" transformation, which changes the endianness of - packed-pixel bytes (Kevin Bracey) - Added "strip_alpha" transformation, which removes the alpha channel of - input images without using it (not necessarily a good idea) - Added "swap_alpha" transformation, which puts the alpha channel in front - of the color bytes instead of after - Removed all implicit variable tests which assume NULL == 0 (I think) - Changed several variables to "png_size_t" to show 16/32-bit limitations - Added new pCAL chunk read/write support - Added experimental filter selection weighting (Greg Roelofs) - Removed old png_set_rgbx() and png_set_xrgb() functions that have been - obsolete for about 2 years now (use png_set_filler() instead) - Added macros to read 16- and 32-bit ints directly from buffer, to be - used only on those systems that support it (namely PowerPC and 680x0) - With some testing, this may become the default for MACOS/PPC systems. - Only calculate CRC on data if we are going to use it - Added macros for zTXt compression type PNG_zTXt_COMPRESSION_??? - Added macros for simple libpng debugging output selectable at compile time - Removed PNG_READ_END_MODE in progressive reader (Smarasderagd) - More description of info_struct in libpng.txt and png.h - More instructions in example.c - More chunk types tested in pngtest.c - Renamed pngrcb.c to pngset.c, and all png_read_<chunk> functions to be - png_set_<chunk>. We now have corresponding png_get_<chunk> - functions in pngget.c to get information in info_ptr. This isolates - the application from the internal organization of png_info_struct - (good for shared library implementations). - -Version 0.96 [May, 1997] - Fixed serious bug with < 8bpp images introduced in 0.95 - Fixed 256-color transparency bug (Greg Roelofs) - Fixed up documentation (Greg Roelofs, Laszlo Nyul) - Fixed "error" in pngconf.h for Linux setjmp() behavior - Fixed DOS medium model support (Tim Wegner) - Fixed png_check_keyword() for case with error in static string text - Added read of CRC after IEND chunk for embedded PNGs (Laszlo Nyul) - Added typecasts to quiet compiler errors - Added more debugging info - -Version 0.97 [January, 1998] - Removed PNG_USE_OWN_CRC capability - Relocated png_set_crc_action from pngrutil.c to pngrtran.c - Fixed typecasts of "new_key", etc. (Andreas Dilger) - Added RFC 1152 [sic] date support - Fixed bug in gamma handling of 4-bit grayscale - Added 2-bit grayscale gamma handling (Glenn R-P) - Added more typecasts. 65536L becomes (png_uint_32)65536L, etc. (Glenn R-P) - Minor corrections in libpng.txt - Added simple sRGB support (Glenn R-P) - Easier conditional compiling, e.g., - define PNG_READ/WRITE_NOT_FULLY_SUPPORTED; - all configurable options can be selected from command-line instead - of having to edit pngconf.h (Glenn R-P) - Fixed memory leak in pngwrite.c (free info_ptr->text) (Glenn R-P) - Added more conditions for png_do_background, to avoid changing - black pixels to background when a background is supplied and - no pixels are transparent - Repaired PNG_NO_STDIO behavior - Tested NODIV support and made it default behavior (Greg Roelofs) - Added "-m" option and PNGTEST_DEBUG_MEMORY to pngtest (John Bowler) - Regularized version numbering scheme and bumped shared-library major - version number to 2 to avoid problems with libpng 0.89 apps - (Greg Roelofs) - -Version 0.98 [January, 1998] - Cleaned up some typos in libpng.txt and in code documentation - Fixed memory leaks in pCAL chunk processing (Glenn R-P and John Bowler) - Cosmetic change "display_gamma" to "screen_gamma" in pngrtran.c - Changed recommendation about file_gamma for PC images to .51 from .45, - in example.c and libpng.txt, added comments to distinguish between - screen_gamma, viewing_gamma, and display_gamma. - Changed all references to RFC1152 to read RFC1123 and changed the - PNG_TIME_RFC1152_SUPPORTED macro to PNG_TIME_RFC1123_SUPPORTED - Added png_invert_alpha capability (Glenn R-P -- suggestion by Jon Vincent) - Changed srgb_intent from png_byte to int to avoid compiler bugs - -Version 0.99 [January 30, 1998] - Free info_ptr->text instead of end_info_ptr->text in pngread.c (John Bowler) - Fixed a longstanding "packswap" bug in pngtrans.c - Fixed some inconsistencies in pngconf.h that prevented compiling with - PNG_READ_GAMMA_SUPPORTED and PNG_READ_hIST_SUPPORTED undefined - Fixed some typos and made other minor rearrangement of libpng.txt (Andreas) - Changed recommendation about file_gamma for PC images to .50 from .51 in - example.c and libpng.txt, and changed file_gamma for sRGB images to .45 - Added a number of functions to access information from the png structure - png_get_image_height(), etc. (Glenn R-P, suggestion by Brad Pettit) - Added TARGET_MACOS similar to zlib-1.0.8 - Define PNG_ALWAYS_EXTERN when __MWERKS__ && WIN32 are defined - Added type casting to all png_malloc() function calls - -Version 0.99a [January 31, 1998] - Added type casts and parentheses to all returns that return a value.(Tim W.) - -Version 0.99b [February 4, 1998] - Added type cast png_uint_32 on malloc function calls where needed. - Changed type of num_hist from png_uint_32 to int (same as num_palette). - Added checks for rowbytes overflow, in case png_size_t is less than 32 bits. - Renamed makefile.elf to makefile.lnx. - -Version 0.99c [February 7, 1998] - More type casting. Removed erroneous overflow test in pngmem.c. - Added png_buffered_memcpy() and png_buffered_memset(), apply them to rowbytes. - Added UNIX manual pages libpng.3 (incorporating libpng.txt) and png.5. - -Version 0.99d [February 11, 1998] - Renamed "far_to_near()" "png_far_to_near()" - Revised libpng.3 - Version 99c "buffered" operations didn't work as intended. Replaced them - with png_memcpy_check() and png_memset_check(). - Added many "if (png_ptr == NULL) return" to quell compiler warnings about - unused png_ptr, mostly in pngget.c and pngset.c. - Check for overlength tRNS chunk present when indexed-color PLTE is read. - Cleaned up spelling errors in libpng.3/libpng.txt - Corrected a problem with png_get_tRNS() which returned undefined trans array - -Version 0.99e [February 28, 1998] - Corrected png_get_tRNS() again. - Add parentheses for easier reading of pngget.c, fixed "||" should be "&&". - Touched up example.c to make more of it compileable, although the entire - file still can't be compiled (Willem van Schaik) - Fixed a bug in png_do_shift() (Bryan Tsai) - Added a space in png.h prototype for png_write_chunk_start() - Replaced pngtest.png with one created with zlib 1.1.1 - Changed pngtest to report PASS even when file size is different (Jean-loup G.) - Corrected some logic errors in png_do_invert_alpha() (Chris Patterson) - -Version 0.99f [March 5, 1998] - Corrected a bug in pngpread() introduced in version 99c (Kevin Bracey) - Moved makefiles into a "scripts" directory, and added INSTALL instruction file - Added makefile.os2 and pngos2.def (A. Zabolotny) and makefile.s2x (W. Sebok) - Added pointers to "note on libpng versions" in makefile.lnx and README - Added row callback feature when reading and writing nonprogressive rows - and added a test of this feature in pngtest.c - Added user transform callbacks, with test of the feature in pngtest.c - -Version 0.99g [March 6, 1998, morning] - Minor changes to pngtest.c to suppress compiler warnings. - Removed "beta" language from documentation. - -Version 0.99h [March 6, 1998, evening] - Minor changes to previous minor changes to pngtest.c - Changed PNG_READ_NOT_FULLY_SUPPORTED to PNG_READ_TRANSFORMS_NOT_SUPPORTED - and added PNG_PROGRESSIVE_READ_NOT_SUPPORTED macro - Added user transform capability - -Version 1.00 [March 7, 1998] - Changed several typedefs in pngrutil.c - Added makefile.wat (Pawel Mrochen), updated makefile.tc3 (Willem van Schaik) - Replaced "while(1)" with "for(;;)" - Added PNGARG() to prototypes in pngtest.c and removed some prototypes - Updated some of the makefiles (Tom Lane) - Changed some typedefs (s_start, etc.) in pngrutil.c - Fixed dimensions of "short_months" array in pngwrite.c - Replaced ansi2knr.c with the one from jpeg-v6 - -Version 1.0.0 [March 8, 1998] - Changed name from 1.00 to 1.0.0 (Adam Costello) - Added smakefile.ppc (with SCOPTIONS.ppc) for Amiga PPC (Andreas Kleinert) - -Version 1.0.0a [March 9, 1998] - Fixed three bugs in pngrtran.c to make gamma+background handling consistent - (Greg Roelofs) - Changed format of the PNG_LIBPNG_VER integer to xyyzz instead of xyz - for major, minor, and bugfix releases. This is 10001. (Adam Costello, - Tom Lane) - Make months range from 1-12 in png_convert_to_rfc1123 - -Version 1.0.0b [March 13, 1998] - Quieted compiler complaints about two empty "for" loops in pngrutil.c - Minor changes to makefile.s2x - Removed #ifdef/#endif around a png_free() in pngread.c - -Version 1.0.1 [March 14, 1998] - Changed makefile.s2x to reduce security risk of using a relative pathname - Fixed some typos in the documentation (Greg). - Fixed a problem with value of "channels" returned by png_read_update_info() - -Version 1.0.1a [April 21, 1998] - Optimized Paeth calculations by replacing abs() function calls with intrinsics - plus other loop optimizations. Improves avg decoding speed by about 20%. - Commented out i386istic "align" compiler flags in makefile.lnx. - Reduced the default warning level in some makefiles, to make them consistent. - Removed references to IJG and JPEG in the ansi2knr.c copyright statement. - Fixed a bug in png_do_strip_filler with XXRRGGBB => RRGGBB transformation. - Added grayscale and 16-bit capability to png_do_read_filler(). - Fixed a bug in pngset.c, introduced in version 0.99c, that sets rowbytes - too large when writing an image with bit_depth < 8 (Bob Dellaca). - Corrected some bugs in the experimental weighted filtering heuristics. - Moved a misplaced pngrutil code block that truncates tRNS if it has more - than num_palette entries -- test was done before num_palette was defined. - Fixed a png_convert_to_rfc1123() bug that converts day 31 to 0 (Steve Eddins). - Changed compiler flags in makefile.wat for better optimization - (Pawel Mrochen). - -Version 1.0.1b [May 2, 1998] - Relocated png_do_gray_to_rgb() within png_do_read_transformations() (Greg). - Relocated the png_composite macros from pngrtran.c to png.h (Greg). - Added makefile.sco (contributed by Mike Hopkirk). - Fixed two bugs (missing definitions of "istop") introduced in libpng-1.0.1a. - Fixed a bug in pngrtran.c that would set channels=5 under some circumstances. - More work on the Paeth-filtering, achieving imperceptible speedup - (A Kleinert). - More work on loop optimization which may help when compiled with C++ - compilers. - Added warnings when people try to use transforms they've defined out. - Collapsed 4 "i" and "c" loops into single "i" loops in pngrtran and pngwtran. - Revised paragraph about png_set_expand() in libpng.txt and libpng.3 (Greg) - -Version 1.0.1c [May 11, 1998] - Fixed a bug in pngrtran.c (introduced in libpng-1.0.1a) where the masks for - filler bytes should have been 0xff instead of 0xf. - Added max_pixel_depth=32 in pngrutil.c when using FILLER with palette images. - Moved PNG_WRITE_WEIGHTED_FILTER_SUPPORTED and PNG_WRITE_FLUSH_SUPPORTED - out of the PNG_WRITE_TRANSFORMS_NOT_SUPPORTED block of pngconf.h - Added "PNG_NO_WRITE_TRANSFORMS" etc., as alternatives for *_NOT_SUPPORTED, - for consistency, in pngconf.h - Added individual "ifndef PNG_NO_[CAPABILITY]" in pngconf.h to make it easier - to remove unwanted capabilities via the compile line - Made some corrections to grammar (which, it's) in documentation (Greg). - Corrected example.c, use of row_pointers in png_write_image(). - -Version 1.0.1d [May 24, 1998] - Corrected several statements that used side effects illegally in pngrutil.c - and pngtrans.c, that were introduced in version 1.0.1b - Revised png_read_rows() to avoid repeated if-testing for NULL (A Kleinert) - More corrections to example.c, use of row_pointers in png_write_image() - and png_read_rows(). - Added pngdll.mak and pngdef.pas to scripts directory, contributed by - Bob Dellaca, to make a png32bd.dll with Borland C++ 4.5 - Fixed error in example.c with png_set_text: num_text is 3, not 2 (Guido V.) - Changed several loops from count-down to count-up, for consistency. - -Version 1.0.1e [June 6, 1998] - Revised libpng.txt and libpng.3 description of png_set_read|write_fn(), and - added warnings when people try to set png_read_fn and png_write_fn in - the same structure. - Added a test such that png_do_gamma will be done when num_trans==0 - for truecolor images that have defined a background. This corrects an - error that was introduced in libpng-0.90 that can cause gamma processing - to be skipped. - Added tests in png.h to include "trans" and "trans_values" in structures - when PNG_READ_BACKGROUND_SUPPORTED or PNG_READ_EXPAND_SUPPORTED is defined. - Add png_free(png_ptr->time_buffer) in png_destroy_read_struct() - Moved png_convert_to_rfc_1123() from pngwrite.c to png.c - Added capability for user-provided malloc_fn() and free_fn() functions, - and revised pngtest.c to demonstrate their use, replacing the - PNGTEST_DEBUG_MEM feature. - Added makefile.w32, for Microsoft C++ 4.0 and later (Tim Wegner). - -Version 1.0.2 [June 14, 1998] - Fixed two bugs in makefile.bor . - -Version 1.0.2a [December 30, 1998] - Replaced and extended code that was removed from png_set_filler() in 1.0.1a. - Fixed a bug in png_do_filler() that made it fail to write filler bytes in - the left-most pixel of each row (Kevin Bracey). - Changed "static pngcharp tIME_string" to "static char tIME_string[30]" - in pngtest.c (Duncan Simpson). - Fixed a bug in pngtest.c that caused pngtest to try to write a tIME chunk - even when no tIME chunk was present in the source file. - Fixed a problem in pngrutil.c: gray_to_rgb didn't always work with 16-bit. - Fixed a problem in png_read_push_finish_row(), which would not skip some - passes that it should skip, for images that are less than 3 pixels high. - Interchanged the order of calls to png_do_swap() and png_do_shift() - in pngwtran.c (John Cromer). - Added #ifdef PNG_DEBUG/#endif surrounding use of PNG_DEBUG in png.h . - Changed "bad adaptive filter type" from error to warning in pngrutil.c . - Fixed a documentation error about default filtering with 8-bit indexed-color. - Separated the PNG_NO_STDIO macro into PNG_NO_STDIO and PNG_NO_CONSOLE_IO - (L. Peter Deutsch). - Added png_set_rgb_to_gray() and png_get_rgb_to_gray_status() functions. - Added png_get_copyright() and png_get_header_version() functions. - Revised comments on png_set_progressive_read_fn() in libpng.txt and example.c - Added information about debugging in libpng.txt and libpng.3 . - Changed "ln -sf" to "ln -s -f" in makefile.s2x, makefile.lnx, and - makefile.sco. - Removed lines after Dynamic Dependencies" in makefile.aco . - Revised makefile.dec to make a shared library (Jeremie Petit). - Removed trailing blanks from all files. - -Version 1.0.2a [January 6, 1999] - Removed misplaced #endif and #ifdef PNG_NO_EXTERN near the end of png.h - Added "if" tests to silence complaints about unused png_ptr in png.h and png.c - Changed "check_if_png" function in example.c to return true (nonzero) if PNG. - Changed libpng.txt to demonstrate png_sig_cmp() instead of png_check_sig() - which is obsolete. - -Version 1.0.3 [January 14, 1999] - Added makefile.hux, for Hewlett Packard HPUX 10.20 and 11.00 (Jim Rice) - Added a statement of Y2K compliance in png.h, libpng.3, and Y2KINFO. - -Version 1.0.3a [August 12, 1999] - Added check for PNG_READ_INTERLACE_SUPPORTED in pngread.c; issue a warning - if an attempt is made to read an interlaced image when it's not supported. - Added check if png_ptr->trans is defined before freeing it in pngread.c - Modified the Y2K statement to include versions back to version 0.71 - Fixed a bug in the check for valid IHDR bit_depth/color_types in pngrutil.c - Modified makefile.wat (added -zp8 flag, ".symbolic", changed some comments) - Replaced leading blanks with tab characters in makefile.hux - Changed "dworkin.wustl.edu" to "ccrc.wustl.edu" in various documents. - Changed (float)red and (float)green to (double)red, (double)green - in png_set_rgb_to_gray() to avoid "promotion" problems in AIX. - Fixed a bug in pngconf.h that omitted <stdio.h> when PNG_DEBUG==0 (K Bracey). - Reformatted libpng.3 and libpngpf.3 with proper fonts (script by J. vanZandt). - Updated documentation to refer to the PNG-1.2 specification. - Removed ansi2knr.c and left pointers to the latest source for ansi2knr.c - in makefile.knr, INSTALL, and README (L. Peter Deutsch) - Fixed bugs in calculation of the length of rowbytes when adding alpha - channels to 16-bit images, in pngrtran.c (Chris Nokleberg) - Added function png_set_user_transform_info() to store user_transform_ptr, - user_depth, and user_channels into the png_struct, and a function - png_get_user_transform_ptr() to retrieve the pointer (Chris Nokleberg) - Added function png_set_empty_plte_permitted() to make libpng useable - in MNG applications. - Corrected the typedef for png_free_ptr in png.h (Jesse Jones). - Correct gamma with srgb is 45455 instead of 45000 in pngrutil.c, to be - consistent with PNG-1.2, and allow variance of 500 before complaining. - Added assembler code contributed by Intel in file pngvcrd.c and modified - makefile.w32 to use it (Nirav Chhatrapati, INTEL Corporation, - Gilles Vollant) - Changed "ln -s -f" to "ln -f -s" in the makefiles to make Solaris happy. - Added some aliases for png_set_expand() in pngrtran.c, namely - png_set_expand_PLTE(), png_set_expand_depth(), and png_set_expand_tRNS() - (Greg Roelofs, in "PNG: The Definitive Guide"). - Added makefile.beo for BEOS on X86, contributed by Sander Stok. - -Version 1.0.3b [August 26, 1999] - Replaced 2147483647L several places with PNG_MAX_UINT macro, defined in png.h - Changed leading blanks to tabs in all makefiles. - Define PNG_USE_PNGVCRD in makefile.w32, to get MMX assembler code. - Made alternate versions of png_set_expand() in pngrtran.c, namely - png_set_gray_1_2_4_to_8, png_set_palette_to_rgb, and png_set_tRNS_to_alpha - (Greg Roelofs, in "PNG: The Definitive Guide"). Deleted the 1.0.3a aliases. - Relocated start of 'extern "C"' block in png.h so it doesn't include pngconf.h - Revised calculation of num_blocks in pngmem.c to avoid a potentially - negative shift distance, whose results are undefined in the C language. - Added a check in pngset.c to prevent writing multiple tIME chunks. - Added a check in pngwrite.c to detect invalid small window_bits sizes. - -Version 1.0.3d [September 4, 1999] - Fixed type casting of igamma in pngrutil.c - Added new png_expand functions to scripts/pngdef.pas and pngos2.def - Added a demo read_user_transform_fn that examines the row filters in pngtest.c - -Version 1.0.4 [September 24, 1999, not distributed publicly] - Define PNG_ALWAYS_EXTERN in pngconf.h if __STDC__ is defined - Delete #define PNG_INTERNAL and include "png.h" from pngasmrd.h - Made several minor corrections to pngtest.c - Renamed the makefiles with longer but more user friendly extensions. - Copied the PNG copyright and license to a separate LICENSE file. - Revised documentation, png.h, and example.c to remove reference to - "viewing_gamma" which no longer appears in the PNG specification. - Revised pngvcrd.c to use MMX code for interlacing only on the final pass. - Updated pngvcrd.c to use the faster C filter algorithms from libpng-1.0.1a - Split makefile.win32vc into two versions, makefile.vcawin32 (uses MMX - assembler code) and makefile.vcwin32 (doesn't). - Added a CPU timing report to pngtest.c (enabled by defining PNGTEST_TIMING) - Added a copy of pngnow.png to the distribution. - -Version 1.0.4a [September 25, 1999] - Increase max_pixel_depth in pngrutil.c if a user transform needs it. - Changed several division operations to right-shifts in pngvcrd.c - -Version 1.0.4b [September 30, 1999] - Added parentheses in line 3732 of pngvcrd.c - Added a comment in makefile.linux warning about buggy -O3 in pgcc 2.95.1 - -Version 1.0.4c [October 1, 1999] - Added a "png_check_version" function in png.c and pngtest.c that will generate - a helpful compiler error if an old png.h is found in the search path. - Changed type of png_user_transform_depth|channels from int to png_byte. - Added "Libpng is OSI Certified Open Source Software" statement to png.h - -Version 1.0.4d [October 6, 1999] - Changed 0.45 to 0.45455 in png_set_sRGB() - Removed unused PLTE entries from pngnow.png - Re-enabled some parts of pngvcrd.c (png_combine_row) that work properly. - -Version 1.0.4e [October 10, 1999] - Fixed sign error in pngvcrd.c (Greg Roelofs) - Replaced some instances of memcpy with simple assignments in pngvcrd (GR-P) - -Version 1.0.4f [October 15, 1999] - Surrounded example.c code with #if 0 .. #endif to prevent people from - inadvertently trying to compile it. - Changed png_get_header_version() from a function to a macro in png.h - Added type casting mostly in pngrtran.c and pngwtran.c - Removed some pointless "ptr = NULL" in pngmem.c - Added a "contrib" directory containing the source code from Greg's book. - -Version 1.0.5 [October 15, 1999] - Minor editing of the INSTALL and README files. - -Version 1.0.5a [October 23, 1999] - Added contrib/pngsuite and contrib/pngminus (Willem van Schaik) - Fixed a typo in the png_set_sRGB() function call in example.c (Jan Nijtmans) - Further optimization and bugfix of pngvcrd.c - Revised pngset.c so that it does not allocate or free memory in the user's - text_ptr structure. Instead, it makes its own copy. - Created separate write_end_info_struct in pngtest.c for a more severe test. - Added code in pngwrite.c to free info_ptr->text[i].key to stop a memory leak. - -Version 1.0.5b [November 23, 1999] - Moved PNG_FLAG_HAVE_CHUNK_HEADER, PNG_FLAG_BACKGROUND_IS_GRAY and - PNG_FLAG_WROTE_tIME from flags to mode. - Added png_write_info_before_PLTE() function. - Fixed some typecasting in contrib/gregbook/*.c - Updated scripts/makevms.com and added makevms.com to contrib/gregbook - and contrib/pngminus (Martin Zinser) - -Version 1.0.5c [November 26, 1999] - Moved png_get_header_version from png.h to png.c, to accommodate ansi2knr. - Removed all global arrays (according to PNG_NO_GLOBAL_ARRAYS macro), to - accommodate making DLL's: Moved usr_png_ver from global variable to function - png_get_header_ver() in png.c. Moved png_sig to png_sig_bytes in png.c and - eliminated use of png_sig in pngwutil.c. Moved the various png_CHNK arrays - into pngtypes.h. Eliminated use of global png_pass arrays. Declared the - png_CHNK and png_pass arrays to be "const". Made the global arrays - available to applications (although none are used in libpng itself) when - PNG_NO_GLOBAL_ARRAYS is not defined or when PNG_GLOBAL_ARRAYS is defined. - Removed some extraneous "-I" from contrib/pngminus/makefile.std - Changed the PNG_sRGB_INTENT macros in png.h to be consistent with PNG-1.2. - Change PNG_SRGB_INTENT to PNG_sRGB_INTENT in libpng.txt and libpng.3 - -Version 1.0.5d [November 29, 1999] - Add type cast (png_const_charp) two places in png.c - Eliminated pngtypes.h; use macros instead to declare PNG_CHNK arrays. - Renamed "PNG_GLOBAL_ARRAYS" to "PNG_USE_GLOBAL_ARRAYS" and made available - to applications a macro "PNG_USE_LOCAL_ARRAYS". - comment out (with #ifdef) all the new declarations when - PNG_USE_GLOBAL_ARRAYS is defined. - Added PNG_EXPORT_VAR macro to accommodate making DLL's. - -Version 1.0.5e [November 30, 1999] - Added iCCP, iTXt, and sPLT support; added "lang" member to the png_text - structure; refactored the inflate/deflate support to make adding new chunks - with trailing compressed parts easier in the future, and added new functions - png_free_iCCP, png_free_pCAL, png_free_sPLT, png_free_text, png_get_iCCP, - png_get_spalettes, png_set_iCCP, png_set_spalettes (Eric S. Raymond). - NOTE: Applications that write text chunks MUST define png_text->lang - before calling png_set_text(). It must be set to NULL if you want to - write tEXt or zTXt chunks. If you want your application to be able to - run with older versions of libpng, use - - #ifdef PNG_iTXt_SUPPORTED - png_text[i].lang = NULL; - #endif - - Changed png_get_oFFs() and png_set_oFFs() to use signed rather than unsigned - offsets (Eric S. Raymond). - Combined PNG_READ_cHNK_SUPPORTED and PNG_WRITE_cHNK_SUPPORTED macros into - PNG_cHNK_SUPPORTED and combined the three types of PNG_text_SUPPORTED - macros, leaving the separate macros also available. - Removed comments on #endifs at the end of many short, non-nested #if-blocks. - -Version 1.0.5f [December 6, 1999] - Changed makefile.solaris to issue a warning about potential problems when - the ucb "ld" is in the path ahead of the ccs "ld". - Removed "- [date]" from the "synopsis" line in libpng.3 and libpngpf.3. - Added sCAL chunk support (Eric S. Raymond). - -Version 1.0.5g [December 7, 1999] - Fixed "png_free_spallettes" typo in png.h - Added code to handle new chunks in pngpread.c - Moved PNG_CHNK string macro definitions outside of PNG_NO_EXTERN block - Added "translated_key" to png_text structure and png_write_iTXt(). - Added code in pngwrite.c to work around a newly discovered zlib bug. - -Version 1.0.5h [December 10, 1999] - NOTE: regarding the note for version 1.0.5e, the following must also - be included in your code: - png_text[i].translated_key = NULL; - Unknown chunk handling is now supported. - Option to eliminate all floating point support was added. Some new - fixed-point functions such as png_set_gAMA_fixed() were added. - Expanded tabs and removed trailing blanks in source files. - -Version 1.0.5i [December 13, 1999] - Added some type casts to silence compiler warnings. - Renamed "png_free_spalette" to "png_free_spalettes" for consistency. - Removed leading blanks from a #define in pngvcrd.c - Added some parameters to the new png_set_keep_unknown_chunks() function. - Added a test for up->location != 0 in the first instance of writing - unknown chunks in pngwrite.c - Changed "num" to "i" in png_free_spalettes() and png_free_unknowns() to - prevent recursion. - Added png_free_hIST() function. - Various patches to fix bugs in the sCAL and integer cHRM processing, - and to add some convenience macros for use with sCAL. - -Version 1.0.5j [December 21, 1999] - Changed "unit" parameter of png_write_sCAL from png_byte to int, to work - around buggy compilers. - Added new type "png_fixed_point" for integers that hold float*100000 values - Restored backward compatibility of tEXt/zTXt chunk processing: - Restored the first four members of png_text to the same order as v.1.0.5d. - Added members "lang_key" and "itxt_length" to png_text struct. Set - text_length=0 when "text" contains iTXt data. Use the "compression" - member to distinguish among tEXt/zTXt/iTXt types. Added - PNG_ITXT_COMPRESSION_NONE (1) and PNG_ITXT_COMPRESSION_zTXt(2) macros. - The "Note" above, about backward incompatibility of libpng-1.0.5e, no - longer applies. - Fixed png_read|write_iTXt() to read|write parameters in the right order, - and to write the iTXt chunk after IDAT if it appears in the end_ptr. - Added pnggccrd.c, version of pngvcrd.c Intel assembler for gcc (Greg Roelofs) - Reversed the order of trying to write floating-point and fixed-point gAMA. - -Version 1.0.5k [December 27, 1999] - Added many parentheses, e.g., "if (a && b & c)" becomes "if (a && (b & c))" - Added png_handle_as_unknown() function (Glenn) - Added png_free_chunk_list() function and chunk_list and num_chunk_list members - of png_ptr. - Eliminated erroneous warnings about multiple sPLT chunks and sPLT-after-PLTE. - Fixed a libpng-1.0.5h bug in pngrutil.c that was issuing erroneous warnings - about ignoring incorrect gAMA with sRGB (gAMA was in fact not ignored) - Added png_free_tRNS(); png_set_tRNS() now malloc's its own trans array (ESR). - Define png_get_int_32 when oFFs chunk is supported as well as when pCAL is. - Changed type of proflen from png_int_32 to png_uint_32 in png_get_iCCP(). - -Version 1.0.5l [January 1, 2000] - Added functions png_set_read_user_chunk_fn() and png_get_user_chunk_ptr() - for setting a callback function to handle unknown chunks and for - retrieving the associated user pointer (Glenn). - -Version 1.0.5m [January 7, 2000] - Added high-level functions png_read_png(), png_write_png(), png_free_pixels(). - -Version 1.0.5n [January 9, 2000] - Added png_free_PLTE() function, and modified png_set_PLTE() to malloc its - own memory for info_ptr->palette. This makes it safe for the calling - application to free its copy of the palette any time after it calls - png_set_PLTE(). - -Version 1.0.5o [January 20, 2000] - Cosmetic changes only (removed some trailing blanks and TABs) - -Version 1.0.5p [January 31, 2000] - Renamed pngdll.mak to makefile.bd32 - Cosmetic changes in pngtest.c - -Version 1.0.5q [February 5, 2000] - Relocated the makefile.solaris warning about PATH problems. - Fixed pngvcrd.c bug by pushing/popping registers in mmxsupport (Bruce Oberg) - Revised makefile.gcmmx - Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros - -Version 1.0.5r [February 7, 2000] - Removed superfluous prototype for png_get_itxt from png.h - Fixed a bug in pngrtran.c that improperly expanded the background color. - Return *num_text=0 from png_get_text() when appropriate, and fix documentation - of png_get_text() in libpng.txt/libpng.3. - -Version 1.0.5s [February 18, 2000] - Added "png_jmp_env()" macro to pngconf.h, to help people migrate to the - new error handler that's planned for the next libpng release, and changed - example.c, pngtest.c, and contrib programs to use this macro. - Revised some of the DLL-export macros in pngconf.h (Greg Roelofs) - Fixed a bug in png_read_png() that caused it to fail to expand some images - that it should have expanded. - Fixed some mistakes in the unused and undocumented INCH_CONVERSIONS functions - in pngget.c - Changed the allocation of palette, history, and trans arrays back to - the version 1.0.5 method (linking instead of copying) which restores - backward compatibility with version 1.0.5. Added some remarks about - that in example.c. Added "free_me" member to info_ptr and png_ptr - and added png_free_data() function. - Updated makefile.linux and makefile.gccmmx to make directories conditionally. - Made cosmetic changes to pngasmrd.h - Added png_set_rows() and png_get_rows(), for use with png_read|write_png(). - Modified png_read_png() to allocate info_ptr->row_pointers only if it - hasn't already been allocated. - -Version 1.0.5t [March 4, 2000] - Changed png_jmp_env() migration aiding macro to png_jmpbuf(). - Fixed "interlace" typo (should be "interlaced") in contrib/gregbook/read2-x.c - Fixed bug with use of PNG_BEFORE_IHDR bit in png_ptr->mode, introduced when - PNG_FLAG_HAVE_CHUNK_HEADER was moved into png_ptr->mode in version 1.0.5b - Files in contrib/gregbook were revised to use png_jmpbuf() and to select - a 24-bit visual if one is available, and to allow abbreviated options. - Files in contrib/pngminus were revised to use the png_jmpbuf() macro. - Removed spaces in makefile.linux and makefile.gcmmx, introduced in 1.0.5s - -Version 1.0.5u [March 5, 2000] - Simplified the code that detects old png.h in png.c and pngtest.c - Renamed png_spalette (_p, _pp) to png_sPLT_t (_tp, _tpp) - Increased precision of rgb_to_gray calculations from 8 to 15 bits and - added png_set_rgb_to_gray_fixed() function. - Added makefile.bc32 (32-bit Borland C++, C mode) - -Version 1.0.5v [March 11, 2000] - Added some parentheses to the png_jmpbuf macro definition. - Updated references to the zlib home page, which has moved to freesoftware.com. - Corrected bugs in documentation regarding png_read_row() and png_write_row(). - Updated documentation of png_rgb_to_gray calculations in libpng.3/libpng.txt. - Renamed makefile.borland,turboc3 back to makefile.bor,tc3 as in version 1.0.3, - revised borland makefiles; added makefile.ibmvac3 and makefile.gcc (Cosmin) - -Version 1.0.6 [March 20, 2000] - Minor revisions of makefile.bor, libpng.txt, and gregbook/rpng2-win.c - Added makefile.sggcc (SGI IRIX with gcc) - -Version 1.0.6d [April 7, 2000] - Changed sprintf() to strcpy() in png_write_sCAL_s() to work without STDIO - Added data_length parameter to png_decompress_chunk() function - Revised documentation to remove reference to abandoned png_free_chnk functions - Fixed an error in png_rgb_to_gray_fixed() - Revised example.c, usage of png_destroy_write_struct(). - Renamed makefile.ibmvac3 to makefile.ibmc, added libpng.icc IBM project file - Added a check for info_ptr->free_me&PNG_FREE_TEXT when freeing text in png.c - Simplify png_sig_bytes() function to remove use of non-ISO-C strdup(). - -Version 1.0.6e [April 9, 2000] - Added png_data_freer() function. - In the code that checks for over-length tRNS chunks, added check of - info_ptr->num_trans as well as png_ptr->num_trans (Matthias Benckmann) - Minor revisions of libpng.txt/libpng.3. - Check for existing data and free it if the free_me flag is set, in png_set_*() - and png_handle_*(). - Only define PNG_WEIGHTED_FILTERS_SUPPORTED when PNG_FLOATING_POINT_SUPPORTED - is defined. - Changed several instances of PNG_NO_CONSOLE_ID to PNG_NO_STDIO in pngrutil.c - and mentioned the purposes of the two macros in libpng.txt/libpng.3. - -Version 1.0.6f [April 14, 2000] - Revised png_set_iCCP() and png_set_rows() to avoid prematurely freeing data. - Add checks in png_set_text() for NULL members of the input text structure. - Revised libpng.txt/libpng.3. - Removed superfluous prototype for png_set_iTXt from png.h - Removed "else" from pngread.c, after png_error(), and changed "0" to "length". - Changed several png_errors about malformed ancillary chunks to png_warnings. - -Version 1.0.6g [April 24, 2000] - Added png_pass-* arrays to pnggccrd.c when PNG_USE_LOCAL_ARRAYS is defined. - Relocated paragraph about png_set_background() in libpng.3/libpng.txt - and other revisions (Matthias Benckmann) - Relocated info_ptr->free_me, png_ptr->free_me, and other info_ptr and - png_ptr members to restore binary compatibility with libpng-1.0.5 - (breaks compatibility with libpng-1.0.6). - -Version 1.0.6h [April 24, 2000] - Changed shared library so-number pattern from 2.x.y.z to xy.z (this builds - libpng.so.10 & libpng.so.10.6h instead of libpng.so.2 & libpng.so.2.1.0.6h) - This is a temporary change for test purposes. - -Version 1.0.6i [May 2, 2000] - Rearranged some members at the end of png_info and png_struct, to put - unknown_chunks_num and free_me within the original size of the png_structs - and free_me, png_read_user_fn, and png_free_fn within the original png_info, - because some old applications allocate the structs directly instead of - using png_create_*(). - Added documentation of user memory functions in libpng.txt/libpng.3 - Modified png_read_png so that it will use user_allocated row_pointers - if present, unless free_me directs that it be freed, and added description - of the use of png_set_rows() and png_get_rows() in libpng.txt/libpng.3. - Added PNG_LEGACY_SUPPORTED macro, and #ifdef out all new (since version - 1.00) members of png_struct and png_info, to regain binary compatibility - when you define this macro. Capabilities lost in this event - are user transforms (new in version 1.0.0),the user transform pointer - (new in version 1.0.2), rgb_to_gray (new in 1.0.5), iCCP, sCAL, sPLT, - the high-level interface, and unknown chunks support (all new in 1.0.6). - This was necessary because of old applications that allocate the structs - directly as authors were instructed to do in libpng-0.88 and earlier, - instead of using png_create_*(). - Added modes PNG_CREATED_READ_STRUCT and PNG_CREATED_WRITE_STRUCT which - can be used to detect codes that directly allocate the structs, and - code to check these modes in png_read_init() and png_write_init() and - generate a libpng error if the modes aren't set and PNG_LEGACY_SUPPORTED - was not defined. - Added makefile.intel and updated makefile.watcom (Pawel Mrochen) - -Version 1.0.6j [May 3, 2000] - Overloaded png_read_init() and png_write_init() with macros that convert - calls to png_read_init_2() or png_write_init_2() that check the version - and structure sizes. - -Version 1.0.7beta11 [May 7, 2000] - Removed the new PNG_CREATED_READ_STRUCT and PNG_CREATED_WRITE_STRUCT modes - which are no longer used. - Eliminated the three new members of png_text when PNG_LEGACY_SUPPORTED is - defined or when neither PNG_READ_iTXt_SUPPORTED nor PNG_WRITE_iTXt_SUPPORTED - is defined. - Made PNG_NO_READ|WRITE_iTXt the default setting, to avoid memory - overrun when old applications fill the info_ptr->text structure directly. - Added PNGAPI macro, and added it to the definitions of all exported functions. - Relocated version macro definitions ahead of the includes of zlib.h and - pngconf.h in png.h. - -Version 1.0.7beta12 [May 12, 2000] - Revised pngset.c to avoid a problem with expanding the png_debug macro. - Deleted some extraneous defines from pngconf.h - Made PNG_NO_CONSOLE_IO the default condition when PNG_BUILD_DLL is defined. - Use MSC _RPTn debugging instead of fprintf if _MSC_VER is defined. - Added png_access_version_number() function. - Check for mask&PNG_FREE_CHNK (for TEXT, SCAL, PCAL) in png_free_data(). - Expanded libpng.3/libpng.txt information about png_data_freer(). - -Version 1.0.7beta14 [May 17, 2000] (beta13 was not published) - Changed pnggccrd.c and pngvcrd.c to handle bad adaptive filter types as - warnings instead of errors, as pngrutil.c does. - Set the PNG_INFO_IDAT valid flag in png_set_rows() so png_write_png() - will actually write IDATs. - Made the default PNG_USE_LOCAL_ARRAYS depend on PNG_DLL instead of WIN32. - Make png_free_data() ignore its final parameter except when freeing data - that can have multiple instances (text, sPLT, unknowns). - Fixed a new bug in png_set_rows(). - Removed info_ptr->valid tests from png_free_data(), as in version 1.0.5. - Added png_set_invalid() function. - Fixed incorrect illustrations of png_destroy_write_struct() in example.c. - -Version 1.0.7beta15 [May 30, 2000] - Revised the deliberately erroneous Linux setjmp code in pngconf.h to produce - fewer error messages. - Rearranged checks for Z_OK to check the most likely path first in pngpread.c - and pngwutil.c. - Added checks in pngtest.c for png_create_*() returning NULL, and mentioned - in libpng.txt/libpng.3 the need for applications to check this. - Changed names of png_default_*() functions in pngtest to pngtest_*(). - Changed return type of png_get_x|y_offset_*() from png_uint_32 to png_int_32. - Fixed some bugs in the unused PNG_INCH_CONVERSIONS functions in pngget.c - Set each pointer to NULL after freeing it in png_free_data(). - Worked around a problem in pngconf.h; AIX's strings.h defines an "index" - macro that conflicts with libpng's png_color_16.index. (Dimitri - Papadapoulos) - Added "msvc" directory with MSVC++ project files (Simon-Pierre Cadieux). - -Version 1.0.7beta16 [June 4, 2000] - Revised the workaround of AIX string.h "index" bug. - Added a check for overlength PLTE chunk in pngrutil.c. - Added PNG_NO_POINTER_INDEXING macro to use array-indexing instead of pointer - indexing in pngrutil.c and pngwutil.c to accommodate a buggy compiler. - Added a warning in png_decompress_chunk() when it runs out of data, e.g. - when it tries to read an erroneous PhotoShop iCCP chunk. - Added PNG_USE_DLL macro. - Revised the copyright/disclaimer/license notice. - Added contrib/msvctest directory - -Version 1.0.7rc1 [June 9, 2000] - Corrected the definition of PNG_TRANSFORM_INVERT_ALPHA (0x0400 not 0x0200) - Added contrib/visupng directory (Willem van Schaik) - -Version 1.0.7beta18 [June 23, 2000] - Revised PNGAPI definition, and pngvcrd.c to work with __GCC__ - and do not redefine PNGAPI if it is passed in via a compiler directive. - Revised visupng/PngFile.c to remove returns from within the Try block. - Removed leading underscores from "_PNG_H" and "_PNG_SAVE_BSD_SOURCE" macros. - Updated contrib/visupng/cexcept.h to version 1.0.0. - Fixed bugs in pngwrite.c and pngwutil.c that prevented writing iCCP chunks. - -Version 1.0.7rc2 [June 28, 2000] - Updated license to include disclaimers required by UCITA. - Fixed "DJBPP" typo in pnggccrd.c introduced in beta18. - -Version 1.0.7 [July 1, 2000] - Revised the definition of "trans_values" in libpng.3/libpng.txt - -Version 1.0.8beta1 [July 8, 2000] - Added png_free(png_ptr, key) two places in pngpread.c to stop memory leaks. - Changed PNG_NO_STDIO to PNG_NO_CONSOLE_IO, several places in pngrutil.c and - pngwutil.c. - Changed PNG_EXPORT_VAR to use PNG_IMPEXP, in pngconf.h. - Removed unused "#include <assert.h>" from png.c - Added WindowsCE support. - Revised pnggccrd.c to work with gcc-2.95.2 and in the Cygwin environment. - -Version 1.0.8beta2 [July 10, 2000] - Added project files to the wince directory and made further revisions - of pngtest.c, pngrio.c, and pngwio.c in support of WindowsCE. - -Version 1.0.8beta3 [July 11, 2000] - Only set the PNG_FLAG_FREE_TRNS or PNG_FREE_TRNS flag in png_handle_tRNS() - for indexed-color input files to avoid potential double-freeing trans array - under some unusual conditions; problem was introduced in version 1.0.6f. - Further revisions to pngtest.c and files in the wince subdirectory. - -Version 1.0.8beta4 [July 14, 2000] - Added the files pngbar.png and pngbar.jpg to the distribution. - Added makefile.cygwin, and cygwin support in pngconf.h - Added PNG_NO_ZALLOC_ZERO macro (makes png_zalloc skip zeroing memory) - -Version 1.0.8rc1 [July 16, 2000] - Revised png_debug() macros and statements to eliminate compiler warnings. - -Version 1.0.8 [July 24, 2000] - Added png_flush() in pngwrite.c, after png_write_IEND(). - Updated makefile.hpux to build a shared library. - -Version 1.0.9beta1 [November 10, 2000] - Fixed typo in scripts/makefile.hpux - Updated makevms.com in scripts and contrib/* and contrib/* (Martin Zinser) - Fixed seqence-point bug in contrib/pngminus/png2pnm (Martin Zinser) - Changed "cdrom.com" in documentation to "libpng.org" - Revised pnggccrd.c to get it all working, and updated makefile.gcmmx (Greg). - Changed type of "params" from voidp to png_voidp in png_read|write_png(). - Make sure PNGAPI and PNG_IMPEXP are defined in pngconf.h. - Revised the 3 instances of WRITEFILE in pngtest.c. - Relocated "msvc" and "wince" project subdirectories into "dll" subdirectory. - Updated png.rc in dll/msvc project - Revised makefile.dec to define and use LIBPATH and INCPATH - Increased size of global png_libpng_ver[] array from 12 to 18 chars. - Made global png_libpng_ver[], png_sig[] and png_pass_*[] arrays const. - Removed duplicate png_crc_finish() from png_handle_bKGD() function. - Added a warning when application calls png_read_update_info() multiple times. - Revised makefile.cygwin - Fixed bugs in iCCP support in pngrutil.c and pngwutil.c. - Replaced png_set_empty_plte_permitted() with png_permit_mng_features(). - -Version 1.0.9beta2 [November 19, 2000] - Renamed the "dll" subdirectory "projects". - Added borland project files to "projects" subdirectory. - Set VS_FF_PRERELEASE and VS_FF_PATCHED flags in msvc/png.rc when appropriate. - Add error message in png_set_compression_buffer_size() when malloc fails. - -Version 1.0.9beta3 [November 23, 2000] - Revised PNG_LIBPNG_BUILD_TYPE macro in png.h, used in the msvc project. - Removed the png_flush() in pngwrite.c that crashes some applications - that don't set png_output_flush_fn. - Added makefile.macosx and makefile.aix to scripts directory. - -Version 1.0.9beta4 [December 1, 2000] - Change png_chunk_warning to png_warning in png_check_keyword(). - Increased the first part of msg buffer from 16 to 18 in png_chunk_error(). - -Version 1.0.9beta5 [December 15, 2000] - Added support for filter method 64 (for PNG datastreams embedded in MNG). - -Version 1.0.9beta6 [December 18, 2000] - Revised png_set_filter() to accept filter method 64 when appropriate. - Added new PNG_HAVE_PNG_SIGNATURE bit to png_ptr->mode and use it to - help prevent applications from using MNG features in PNG datastreams. - Added png_permit_mng_features() function. - Revised libpng.3/libpng.txt. Changed "filter type" to "filter method". - -Version 1.0.9rc1 [December 23, 2000] - Revised test for PNG_HAVE_PNG_SIGNATURE in pngrutil.c - Fixed error handling of unknown compression type in png_decompress_chunk(). - In pngconf.h, define __cdecl when _MSC_VER is defined. - -Version 1.0.9beta7 [December 28, 2000] - Changed PNG_TEXT_COMPRESSION_zTXt to PNG_COMPRESSION_TYPE_BASE several places. - Revised memory management in png_set_hIST and png_handle_hIST in a backward - compatible manner. PLTE and tRNS were revised similarly. - Revised the iCCP chunk reader to ignore trailing garbage. - -Version 1.0.9beta8 [January 12, 2001] - Moved pngasmrd.h into pngconf.h. - Improved handling of out-of-spec garbage iCCP chunks generated by PhotoShop. - -Version 1.0.9beta9 [January 15, 2001] - Added png_set_invalid, png_permit_mng_features, and png_mmx_supported to - wince and msvc project module definition files. - Minor revision of makefile.cygwin. - Fixed bug with progressive reading of narrow interlaced images in pngpread.c - -Version 1.0.9beta10 [January 16, 2001] - Do not typedef png_FILE_p in pngconf.h when PNG_NO_STDIO is defined. - Fixed "png_mmx_supported" typo in project definition files. - -Version 1.0.9beta11 [January 19, 2001] - Updated makefile.sgi to make shared library. - Removed png_mmx_support() function and disabled PNG_MNG_FEATURES_SUPPORTED - by default, for the benefit of DLL forward compatibility. These will - be re-enabled in version 1.2.0. - -Version 1.0.9rc2 [January 22, 2001] - Revised cygwin support. - -Version 1.0.9 [January 31, 2001] - Added check of cygwin's ALL_STATIC in pngconf.h - Added "-nommx" parameter to contrib/gregbook/rpng2-win and rpng2-x demos. - -Version 1.0.10beta1 [March 14, 2001] - Revised makefile.dec, makefile.sgi, and makefile.sggcc; added makefile.hpgcc. - Reformatted libpng.3 to eliminate bad line breaks. - Added checks for _mmx_supported in the read_filter_row function of pnggccrd.c - Added prototype for png_mmx_support() near the top of pnggccrd.c - Moved some error checking from png_handle_IHDR to png_set_IHDR. - Added PNG_NO_READ_SUPPORTED and PNG_NO_WRITE_SUPPORTED macros. - Revised png_mmx_support() function in pnggccrd.c - Restored version 1.0.8 PNG_WRITE_EMPTY_PLTE_SUPPORTED behavior in pngwutil.c - Fixed memory leak in contrib/visupng/PngFile.c - Fixed bugs in png_combine_row() in pnggccrd.c and pngvcrd.c (C version) - Added warnings when retrieving or setting gamma=0. - Increased the first part of msg buffer from 16 to 18 in png_chunk_warning(). - -Version 1.0.10rc1 [March 23, 2001] - Changed all instances of memcpy, strcpy, and strlen to png_memcpy, png_strcpy, - and png_strlen. - Revised png_mmx_supported() function in pnggccrd.c to return proper value. - Fixed bug in progressive reading (pngpread.c) with small images (height < 8). - -Version 1.0.10 [March 30, 2001] - Deleted extraneous space (introduced in 1.0.9) from line 42 of makefile.cygwin - Added beos project files (Chris Herborth) - -Version 1.0.11beta1 [April 3, 2001] - Added type casts on several png_malloc() calls (Dimitri Papadapoulos). - Removed a no-longer needed AIX work-around from pngconf.h - Changed several "//" single-line comments to C-style in pnggccrd.c - -Version 1.0.11beta2 [April 11, 2001] - Removed PNGAPI from several functions whose prototypes did not have PNGAPI. - Updated scripts/pngos2.def - -Version 1.0.11beta3 [April 14, 2001] - Added checking the results of many instances of png_malloc() for NULL - -Version 1.0.11beta4 [April 20, 2001] - Undid the changes from version 1.0.11beta3. Added a check for NULL return - from user's malloc_fn(). - Removed some useless type casts of the NULL pointer. - Added makefile.netbsd - -Version 1.0.11 [April 27, 2001] - Revised makefile.netbsd - -Version 1.0.12beta1 [May 14, 2001] - Test for Windows platform in pngconf.h when including malloc.h (Emmanuel Blot) - Updated makefile.cygwin and handling of Cygwin's ALL_STATIC in pngconf.h - Added some never-to-be-executed code in pnggccrd.c to quiet compiler warnings. - Eliminated the png_error about apps using png_read|write_init(). Instead, - libpng will reallocate the png_struct and info_struct if they are too small. - This retains future binary compatibility for old applications written for - libpng-0.88 and earlier. - -Version 1.2.0beta1 [May 6, 2001] - Bumped DLLNUM to 2. - Re-enabled PNG_MNG_FEATURES_SUPPORTED and enabled PNG_ASSEMBLER_CODE_SUPPORTED - by default. - Added runtime selection of MMX features. - Added png_set_strip_error_numbers function and related macros. - -Version 1.2.0beta2 [May 7, 2001] - Finished merging 1.2.0beta1 with version 1.0.11 - Added a check for attempts to read or write PLTE in grayscale PNG datastreams. - -Version 1.2.0beta3 [May 17, 2001] - Enabled user memory function by default. - Modified png_create_struct so it passes user mem_ptr to user memory allocator. - Increased png_mng_features flag from png_byte to png_uint_32. - Bumped shared-library (so-number) and dll-number to 3. - -Version 1.2.0beta4 [June 23, 2001] - Check for missing profile length field in iCCP chunk and free chunk_data - in case of truncated iCCP chunk. - Bumped shared-library number to 3 in makefile.sgi and makefile.sggcc - Bumped dll-number from 2 to 3 in makefile.cygwin - Revised contrib/gregbook/rpng*-x.c to avoid a memory leak and to exit cleanly - if user attempts to run it on an 8-bit display. - Updated contrib/gregbook - Use png_malloc instead of png_zalloc to allocate palette in pngset.c - Updated makefile.ibmc - Added some typecasts to eliminate gcc 3.0 warnings. Changed prototypes - of png_write_oFFS width and height from png_uint_32 to png_int_32. - Updated example.c - Revised prototypes for png_debug_malloc and png_debug_free in pngtest.c - -Version 1.2.0beta5 [August 8, 2001] - Revised contrib/gregbook - Revised makefile.gcmmx - Revised pnggccrd.c to conditionally compile some thread-unsafe code only - when PNG_THREAD_UNSAFE_OK is defined. - Added tests to prevent pngwutil.c from writing a bKGD or tRNS chunk with - value exceeding 2^bit_depth-1 - Revised makefile.sgi and makefile.sggcc - Replaced calls to fprintf(stderr,...) with png_warning() in pnggccrd.c - Removed restriction that do_invert_mono only operate on 1-bit opaque files - -Version 1.2.0 [September 1, 2001] - Changed a png_warning() to png_debug() in pnggccrd.c - Fixed contrib/gregbook/rpng-x.c, rpng2-x.c to avoid crash with XFreeGC(). - -Version 1.2.1beta1 [October 19, 2001] - Revised makefile.std in contrib/pngminus - Include background_1 in png_struct regardless of gamma support. - Revised makefile.netbsd and makefile.macosx, added makefile.darwin. - Revised example.c to provide more details about using row_callback(). - -Version 1.2.1beta2 [October 25, 2001] - Added type cast to each NULL appearing in a function call, except for - WINCE functions. - Added makefile.so9. - -Version 1.2.1beta3 [October 27, 2001] - Removed type casts from all NULLs. - Simplified png_create_struct_2(). - -Version 1.2.1beta4 [November 7, 2001] - Revised png_create_info_struct() and png_creat_struct_2(). - Added error message if png_write_info() was omitted. - Type cast NULLs appearing in function calls when _NO_PROTO or - PNG_TYPECAST_NULL is defined. - -Version 1.2.1rc1 [November 24, 2001] - Type cast NULLs appearing in function calls except when PNG_NO_TYPECAST_NULL - is defined. - Changed typecast of "size" argument to png_size_t in pngmem.c calls to - the user malloc_fn, to agree with the prototype in png.h - Added a pop/push operation to pnggccrd.c, to preserve Eflag (Maxim Sobolev) - Updated makefile.sgi to recognize LIBPATH and INCPATH. - Updated various makefiles so "make clean" does not remove previous major - version of the shared library. - -Version 1.2.1rc2 [December 4, 2001] - Always allocate 256-entry internal palette, hist, and trans arrays, to - avoid out-of-bounds memory reference caused by invalid PNG datastreams. - Added a check for prefix_length > data_length in iCCP chunk handler. - -Version 1.2.1 [December 7, 2001] - None. - -Version 1.2.2beta1 [February 22, 2002] - Fixed a bug with reading the length of iCCP profiles (Larry Reeves). - Revised makefile.linux, makefile.gcmmx, and makefile.sgi to generate - libpng.a, libpng12.so (not libpng.so.3), and libpng12/png.h - Revised makefile.darwin to remove "-undefined suppress" option. - Added checks for gamma and chromaticity values over 21474.83, which exceed - the limit for PNG unsigned 32-bit integers when encoded. - Revised calls to png_create_read_struct() and png_create_write_struct() - for simpler debugging. - Revised png_zalloc() so zlib handles errors (uses PNG_FLAG_MALLOC_NULL_MEM_OK) - -Version 1.2.2beta2 [February 23, 2002] - Check chunk_length and idat_size for invalid (over PNG_MAX_UINT) lengths. - Check for invalid image dimensions in png_get_IHDR. - Added missing "fi;" in the install target of the SGI makefiles. - Added install-static to all makefiles that make shared libraries. - Always do gamma compensation when image is partially transparent. - -Version 1.2.2beta3 [March 7, 2002] - Compute background.gray and background_1.gray even when color_type is RGB - in case image gets reduced to gray later. - Modified shared-library makefiles to install pkgconfig/libpngNN.pc. - Export (with PNGAPI) png_zalloc, png_zfree, and png_handle_as_unknown - Removed unused png_write_destroy_info prototype from png.h - Eliminated incorrect use of width_mmx from pnggccrd.c in pixel_bytes == 8 case - Added install-shared target to all makefiles that make shared libraries. - Stopped a double free of palette, hist, and trans when not using free_me. - Added makefile.32sunu for Sun Ultra 32 and makefile.64sunu for Sun Ultra 64. - -Version 1.2.2beta4 [March 8, 2002] - Compute background.gray and background_1.gray even when color_type is RGB - in case image gets reduced to gray later (Jason Summers). - Relocated a misplaced /bin/rm in the "install-shared" makefile targets - Added PNG_1_0_X macro which can be used to build a 1.0.x-compatible library. - -Version 1.2.2beta5 [March 26, 2002] - Added missing PNGAPI to several function definitions. - Check for invalid bit_depth or color_type in png_get_IHDR(), and - check for missing PLTE or IHDR in png_push_read_chunk() (Matthias Clasen). - Revised iTXt support to accept NULL for lang and lang_key. - Compute gamma for color components of background even when color_type is gray. - Changed "()" to "{}" in scripts/libpng.pc.in. - Revised makefiles to put png.h and pngconf.h only in $prefix/include/libpngNN - Revised makefiles to make symlink to libpng.so.NN in addition to libpngNN.so - -Version 1.2.2beta6 [March 31, 2002] - -Version 1.0.13beta1 [March 31, 2002] - Prevent png_zalloc() from trying to memset memory that it failed to acquire. - Add typecasts of PNG_MAX_UINT in pngset_cHRM_fixed() (Matt Holgate). - Ensure that the right function (user or default) is used to free the - png_struct after an error in png_create_read_struct_2(). - -Version 1.2.2rc1 [April 7, 2002] - -Version 1.0.13rc1 [April 7, 2002] - Save the ebx register in pnggccrd.c (Sami Farin) - Add "mem_ptr = png_ptr->mem_ptr" in png_destroy_write_struct() (Paul Gardner). - Updated makefiles to put headers in include/libpng and remove old include/*.h. - -Version 1.2.2 [April 15, 2002] - -Version 1.0.13 [April 15, 2002] - Revised description of png_set_filter() in libpng.3/libpng.txt. - Revised makefile.netbsd and added makefile.neNNbsd and makefile.freebsd - -Version 1.0.13patch01 [April 17, 2002] - -Version 1.2.2patch01 [April 17, 2002] - Changed ${PNGMAJ}.${PNGVER} bug to ${PNGVER} in makefile.sgi and - makefile.sggcc - Fixed VER -> PNGVER typo in makefile.macosx and added install-static to - install - Added install: target to makefile.32sunu and makefile.64sunu - -Version 1.0.13patch03 [April 18, 2002] - -Version 1.2.2patch03 [April 18, 2002] - Revised 15 makefiles to link libpng.a to libpngNN.a and the include libpng - subdirectory to libpngNN subdirectory without the full pathname. - Moved generation of libpng.pc from "install" to "all" in 15 makefiles. - -Version 1.2.3rc1 [April 28, 2002] - Added install-man target to 15 makefiles (Dimitri Papadopolous-Orfanos). - Added $(DESTDIR) feature to 24 makefiles (Tim Mooney) - Fixed bug with $prefix, should be $(prefix) in makefile.hpux. - Updated cygwin-specific portion of pngconf.h and revised makefile.cygwin - Added a link from libpngNN.pc to libpng.pc in 15 makefiles. - Added links from include/libpngNN/*.h to include/*.h in 24 makefiles. - Revised makefile.darwin to make relative links without full pathname. - Added setjmp() at the end of png_create_*_struct_2() in case user forgets - to put one in their application. - Restored png_zalloc() and png_zfree() prototypes to version 1.2.1 and - removed them from module definition files. - -Version 1.2.3rc2 [May 1, 2002] - Fixed bug in reporting number of channels in pngget.c and pngset.c, - that was introduced in version 1.2.2beta5. - Exported png_zalloc(), png_zfree(), png_default_read(), png_default_write(), - png_default_flush(), and png_push_fill_buffer() and included them in - module definition files. - Added "libpng.pc" dependency to the "install-shared" target in 15 makefiles. - -Version 1.2.3rc3 [May 1, 2002] - Revised prototype for png_default_flush() - Remove old libpng.pc and libpngNN.pc before installing new ones. - -Version 1.2.3rc4 [May 2, 2002] - Typos in *.def files (png_default_read|write -> png_default_read|write_data) - In makefiles, changed rm libpng.NN.pc to rm libpngNN.pc - Added libpng-config and libpngNN-config and modified makefiles to install - them. - Changed $(MANPATH) to $(DESTDIR)$(MANPATH) in makefiles - Added "Win32 DLL VB" configuration to projects/msvc/libpng.dsp - -Version 1.2.3rc5 [May 11, 2002] - Changed "error" and "message" in prototypes to "error_message" and - "warning_message" to avoid namespace conflict. - Revised 15 makefiles to build libpng-config from libpng-config-*.in - Once more restored png_zalloc and png_zfree to regular nonexported form. - Restored png_default_read|write_data, png_default_flush, png_read_fill_buffer - to nonexported form, but with PNGAPI, and removed them from module def - files. - -Version 1.2.3rc6 [May 14, 2002] - Removed "PNGAPI" from png_zalloc() and png_zfree() in png.c - Changed "Gz" to "Gd" in projects/msvc/libpng.dsp and zlib.dsp. - Removed leftover libpng-config "sed" script from four makefiles. - Revised libpng-config creating script in 16 makefiles. - -Version 1.2.3 [May 22, 2002] - Revised libpng-config target in makefile.cygwin. - Removed description of png_set_mem_fn() from documentation. - Revised makefile.freebsd. - Minor cosmetic changes to 15 makefiles, e.g., $(DI) = $(DESTDIR)/$(INCDIR). - Revised projects/msvc/README.txt - Changed -lpng to -lpngNN in LDFLAGS in several makefiles. - -Version 1.2.4beta1 [May 24, 2002] - Added libpng.pc and libpng-config to "all:" target in 16 makefiles. - Fixed bug in 16 makefiles: $(DESTDIR)/$(LIBPATH) to $(DESTDIR)$(LIBPATH) - Added missing "\" before closing double quote in makefile.gcmmx. - Plugged various memory leaks; added png_malloc_warn() and png_set_text_2() - functions. - -Version 1.2.4beta2 [June 25, 2002] - Plugged memory leak of png_ptr->current_text (Matt Holgate). - Check for buffer overflow before reading CRC in pngpread.c (Warwick Allison) - Added -soname to the loader flags in makefile.dec, makefile.sgi, and - makefile.sggcc. - Added "test-installed" target to makefile.linux, makefile.gcmmx, - makefile.sgi, and makefile.sggcc. - -Version 1.2.4beta3 [June 28, 2002] - Plugged memory leak of row_buf in pngtest.c when there is a png_error(). - Detect buffer overflow in pngpread.c when IDAT is corrupted with extra data. - Added "test-installed" target to makefile.32sunu, makefile.64sunu, - makefile.beos, makefile.darwin, makefile.dec, makefile.macosx, - makefile.solaris, makefile.hpux, makefile.hpgcc, and makefile.so9. - -Version 1.2.4rc1 and 1.0.14rc1 [July 2, 2002] - Added "test-installed" target to makefile.cygwin and makefile.sco. - Revised pnggccrd.c to be able to back out version 1.0.x via PNG_1_0_X macro. - -Version 1.2.4 and 1.0.14 [July 8, 2002] - Changed png_warning() to png_error() when width is too large to process. - -Version 1.2.4patch01 [July 20, 2002] - Revised makefile.cygwin to use DLL number 12 instead of 13. - -Version 1.2.5beta1 [August 6, 2002] - Added code to contrib/gregbook/readpng2.c to ignore unused chunks. - Replaced toucan.png in contrib/gregbook (it has been corrupt since 1.0.11) - Removed some stray *.o files from contrib/gregbook. - Changed png_error() to png_warning() about "Too much data" in pngpread.c - and about "Extra compressed data" in pngrutil.c. - Prevent png_ptr->pass from exceeding 7 in png_push_finish_row(). - Updated makefile.hpgcc - Updated png.c and pnggccrd.c handling of return from png_mmx_support() - -Version 1.2.5beta2 [August 15, 2002] - Only issue png_warning() about "Too much data" in pngpread.c when avail_in - is nonzero. - Updated makefiles to install a separate libpng.so.3 with its own rpath. - -Version 1.2.5rc1 and 1.0.15rc1 [August 24, 2002] - Revised makefiles to not remove previous minor versions of shared libraries. - -Version 1.2.5rc2 and 1.0.15rc2 [September 16, 2002] - Revised 13 makefiles to remove "-lz" and "-L$(ZLIBLIB)", etc., from shared - library loader directive. - Added missing "$OBJSDLL" line to makefile.gcmmx. - Added missing "; fi" to makefile.32sunu. - -Version 1.2.5rc3 and 1.0.15rc3 [September 18, 2002] - Revised libpng-config script. - -Version 1.2.5 and 1.0.15 [October 3, 2002] - Revised makefile.macosx, makefile.darwin, makefile.hpgcc, and makefile.hpux, - and makefile.aix. - Relocated two misplaced PNGAPI lines in pngtest.c - -Version 1.2.6beta1 [October 22, 2002] - Commented out warning about uninitialized mmx_support in pnggccrd.c. - Changed "IBMCPP__" flag to "__IBMCPP__" in pngconf.h. - Relocated two more misplaced PNGAPI lines in pngtest.c - Fixed memory overrun bug in png_do_read_filler() with 16-bit datastreams, - introduced in version 1.0.2. - Revised makefile.macosx, makefile.dec, makefile.aix, and makefile.32sunu. - -Version 1.2.6beta2 [November 1, 2002] - Added libpng-config "--ldopts" output. - Added "AR=ar" and "ARFLAGS=rc" and changed "ar rc" to "$(AR) $(ARFLAGS)" - in makefiles. - -Version 1.2.6beta3 [July 18, 2004] - Reverted makefile changes from version 1.2.6beta2 and some of the changes - from version 1.2.6beta1; these will be postponed until version 1.2.7. - Version 1.2.6 is going to be a simple bugfix release. - Changed the one instance of "ln -sf" to "ln -f -s" in each Sun makefile. - Fixed potential overrun in pngerror.c by using strncpy instead of memcpy. - Added "#!/bin/sh" at the top of configure, for recognition of the - 'x' flag under Cygwin (Cosmin). - Optimized vacuous tests that silence compiler warnings, in png.c (Cosmin). - Added support for PNG_USER_CONFIG, in pngconf.h (Cosmin). - Fixed the special memory handler for Borland C under DOS, in pngmem.c - (Cosmin). - Removed some spurious assignments in pngrutil.c (Cosmin). - Replaced 65536 with 65536L, and 0xffff with 0xffffL, to silence warnings - on 16-bit platforms (Cosmin). - Enclosed shift op expressions in parentheses, to silence warnings (Cosmin). - Used proper type png_fixed_point, to avoid problems on 16-bit platforms, - in png_handle_sRGB() (Cosmin). - Added compression_type to png_struct, and optimized the window size - inside the deflate stream (Cosmin). - Fixed definition of isnonalpha(), in pngerror.c and pngrutil.c (Cosmin). - Fixed handling of unknown chunks that come after IDAT (Cosmin). - Allowed png_error() and png_warning() to work even if png_ptr == NULL - (Cosmin). - Replaced row_info->rowbytes with row_bytes in png_write_find_filter() - (Cosmin). - Fixed definition of PNG_LIBPNG_VER_DLLNUM (Simon-Pierre). - Used PNG_LIBPNG_VER and PNG_LIBPNG_VER_STRING instead of the hardcoded - values in png.c (Simon-Pierre, Cosmin). - Initialized png_libpng_ver[] with PNG_LIBPNG_VER_STRING (Simon-Pierre). - Replaced PNG_LIBPNG_VER_MAJOR with PNG_LIBPNG_VER_DLLNUM in png.rc - (Simon-Pierre). - Moved the definition of PNG_HEADER_VERSION_STRING near the definitions - of the other PNG_LIBPNG_VER_... symbols in png.h (Cosmin). - Relocated #ifndef PNGAPI guards in pngconf.h (Simon-Pierre, Cosmin). - Updated scripts/makefile.vc(a)win32 (Cosmin). - Updated the MSVC project (Simon-Pierre, Cosmin). - Updated the Borland C++ Builder project (Cosmin). - Avoided access to asm_flags in pngvcrd.c, if PNG_1_0_X is defined (Cosmin). - Commented out warning about uninitialized mmx_support in pngvcrd.c (Cosmin). - Removed scripts/makefile.bd32 and scripts/pngdef.pas (Cosmin). - Added extra guard around inclusion of Turbo C memory headers, in pngconf.h - (Cosmin). - Renamed projects/msvc/ to projects/visualc6/, and projects/borland/ to - projects/cbuilder5/ (Cosmin). - Moved projects/visualc6/png32ms.def to scripts/pngw32.def, - and projects/visualc6/png.rc to scripts/pngw32.rc (Cosmin). - Added projects/visualc6/pngtest.dsp; removed contrib/msvctest/ (Cosmin). - Changed line endings to DOS style in cbuilder5 and visualc6 files, even - in the tar.* distributions (Cosmin). - Updated contrib/visupng/VisualPng.dsp (Cosmin). - Updated contrib/visupng/cexcept.h to version 2.0.0 (Cosmin). - Added a separate distribution with "configure" and supporting files (Junichi). - -Version 1.2.6beta4 [July 28, 2004] - Added user ability to change png_size_t via a PNG_SIZE_T macro. - Added png_sizeof() and png_convert_size() functions. - Added PNG_SIZE_MAX (maximum value of a png_size_t variable. - Added check in png_malloc_default() for (size_t)size != (png_uint_32)size - which would indicate an overflow. - Changed sPLT failure action from png_error to png_warning and abandon chunk. - Changed sCAL and iCCP failures from png_error to png_warning and abandon. - Added png_get_uint_31(png_ptr, buf) function. - Added PNG_UINT_32_MAX macro. - Renamed PNG_MAX_UINT to PNG_UINT_31_MAX. - Made png_zalloc() issue a png_warning and return NULL on potential - overflow. - Turn on PNG_NO_ZALLOC_ZERO by default in version 1.2.x - Revised "clobber list" in pnggccrd.c so it will compile under gcc-3.4. - Revised Borland portion of png_malloc() to return NULL or issue - png_error() according to setting of PNG_FLAG_MALLOC_NULL_MEM_OK. - Added PNG_NO_SEQUENTIAL_READ_SUPPORTED macro to conditionally remove - sequential read support. - Added some "#if PNG_WRITE_SUPPORTED" blocks. - Added #ifdef to remove some redundancy in png_malloc_default(). - Use png_malloc instead of png_zalloc to allocate the pallete. - -Version 1.0.16rc1 and 1.2.6rc1 [August 4, 2004] - Fixed buffer overflow vulnerability (CVE-2004-0597) in png_handle_tRNS(). - Fixed NULL dereference vulnerability (CVE-2004-0598) in png_handle_iCCP(). - Fixed integer overflow vulnerability (CVE-2004-0599) in png_read_png(). - Fixed some harmless bugs in png_handle_sBIT, etc, that would cause - duplicate chunk types to go undetected. - Fixed some timestamps in the -config version - Rearranged order of processing of color types in png_handle_tRNS(). - Added ROWBYTES macro to calculate rowbytes without integer overflow. - Updated makefile.darwin and removed makefile.macosx from scripts directory. - Imposed default one million column, one-million row limits on the image - dimensions, and added png_set_user_limits() function to override them. - Revised use of PNG_SET_USER_LIMITS_SUPPORTED macro. - Fixed wrong cast of returns from png_get_user_width|height_max(). - Changed some "keep the compiler happy" from empty statements to returns, - Revised libpng.txt to remove 1.2.x stuff from the 1.0.x distribution - -Version 1.0.16rc2 and 1.2.6rc2 [August 7, 2004] - Revised makefile.darwin and makefile.solaris. Removed makefile.macosx. - Revised pngtest's png_debug_malloc() to use png_malloc() instead of - png_malloc_default() which is not supposed to be exported. - Fixed off-by-one error in one of the conversions to PNG_ROWBYTES() in - pngpread.c. Bug was introduced in 1.2.6rc1. - Fixed bug in RGB to RGBX transformation introduced in 1.2.6rc1. - Fixed old bug in RGB to Gray transformation. - Fixed problem with 64-bit compilers by casting arguments to abs() - to png_int_32. - Changed "ln -sf" to "ln -f -s" in three makefiles (solaris, sco, so9). - Changed "HANDLE_CHUNK_*" to "PNG_HANDLE_CHUNK_*" (Cosmin) - Added "-@/bin/rm -f $(DL)/$(LIBNAME).so.$(PNGMAJ)" to 15 *NIX makefiles. - Added code to update the row_info->colortype in png_do_read_filler() (MSB). - -Version 1.0.16rc3 and 1.2.6rc3 [August 9, 2004] - Eliminated use of "abs()" in testing cHRM and gAMA values, to avoid - trouble with some 64-bit compilers. Created PNG_OUT_OF_RANGE() macro. - Revised documentation of png_set_keep_unknown_chunks(). - Check handle_as_unknown status in pngpread.c, as in pngread.c previously. - Moved "PNG_HANDLE_CHUNK_*" macros out of PNG_INTERNAL section of png.h - Added "rim" definitions for CONST4 and CONST6 in pnggccrd.c - -Version 1.0.16rc4 and 1.2.6rc4 [August 10, 2004] - Fixed mistake in pngtest.c introduced in 1.2.6rc2 (declaration of - "pinfo" was out of place). - -Version 1.0.16rc5 and 1.2.6rc5 [August 10, 2004] - Moved "PNG_HANDLE_CHUNK_*" macros out of PNG_ASSEMBLER_CODE_SUPPORTED - section of png.h where they were inadvertently placed in version rc3. - -Version 1.2.6 and 1.0.16 [August 15, 2004] - Revised pngtest so memory allocation testing is only done when PNG_DEBUG==1. - -Version 1.2.7beta1 [August 26, 2004] - Removed unused pngasmrd.h file. - Removed references to uu.net for archived files. Added references to - PNG Spec (second edition) and the PNG ISO/IEC Standard. - Added "test-dd" target in 15 makefiles, to run pngtest in DESTDIR. - Fixed bug with "optimized window size" in the IDAT datastream, that - causes libpng to write PNG files with incorrect zlib header bytes. - -Version 1.2.7beta2 [August 28, 2004] - Fixed bug with sCAL chunk and big-endian machines (David Munro). - Undid new code added in 1.2.6rc2 to update the color_type in - png_set_filler(). - Added png_set_add_alpha() that updates color type. - -Version 1.0.17rc1 and 1.2.7rc1 [September 4, 2004] - Revised png_set_strip_filler() to not remove alpha if color_type has alpha. - -Version 1.2.7 and 1.0.17 [September 12, 2004] - Added makefile.hp64 - Changed projects/msvc/png32ms.def to scripts/png32ms.def in makefile.cygwin - -Version 1.2.8beta1 [November 1, 2004] - Fixed bug in png_text_compress() that would fail to complete a large block. - Fixed bug, introduced in libpng-1.2.7, that overruns a buffer during - strip alpha operation in png_do_strip_filler(). - Added PNG_1_2_X definition in pngconf.h - Use #ifdef to comment out png_info_init in png.c and png_read_init in - pngread.c (as of 1.3.0) - -Version 1.2.8beta2 [November 2, 2004] - Reduce color_type to a nonalpha type after strip alpha operation in - png_do_strip_filler(). - -Version 1.2.8beta3 [November 3, 2004] - Revised definitions of PNG_MAX_UINT_32, PNG_MAX_SIZE, and PNG_MAXSUM - -Version 1.2.8beta4 [November 12, 2004] - Fixed (again) definition of PNG_LIBPNG_VER_DLLNUM in png.h (Cosmin). - Added PNG_LIBPNG_BUILD_PRIVATE in png.h (Cosmin). - Set png_ptr->zstream.data_type to Z_BINARY, to avoid unnecessary detection - of data type in deflate (Cosmin). - Deprecated but continue to support SPECIALBUILD and PRIVATEBUILD in favor of - PNG_LIBPNG_BUILD_SPECIAL_STRING and PNG_LIBPNG_BUILD_PRIVATE_STRING. - -Version 1.2.8beta5 [November 20, 2004] - Use png_ptr->flags instead of png_ptr->transformations to pass - PNG_STRIP_ALPHA info to png_do_strip_filler(), to preserve ABI - compatibility. - Revised handling of SPECIALBUILD, PRIVATEBUILD, - PNG_LIBPNG_BUILD_SPECIAL_STRING and PNG_LIBPNG_BUILD_PRIVATE_STRING. - -Version 1.2.8rc1 [November 24, 2004] - Moved handling of BUILD macros from pngconf.h to png.h - Added definition of PNG_LIBPNG_BASE_TYPE in png.h, inadvertently - omitted from beta5. - Revised scripts/pngw32.rc - Despammed mailing addresses by masking "@" with "at". - Inadvertently installed a supposedly faster test version of pngrutil.c - -Version 1.2.8rc2 [November 26, 2004] - Added two missing "\" in png.h - Change tests in pngread.c and pngpread.c to - if (png_ptr->transformations || (png_ptr->flags&PNG_FLAG_STRIP_ALPHA)) - png_do_read_transformations(png_ptr); - -Version 1.2.8rc3 [November 28, 2004] - Reverted pngrutil.c to version libpng-1.2.8beta5. - Added scripts/makefile.elf with supporting code in pngconf.h for symbol - versioning (John Bowler). - -Version 1.2.8rc4 [November 29, 2004] - Added projects/visualc7 (Simon-pierre). - -Version 1.2.8rc5 [November 29, 2004] - Fixed new typo in scripts/pngw32.rc - -Version 1.2.8 [December 3, 2004] - Removed projects/visualc7, added projects/visualc71. - -Version 1.2.9beta1 [February 21, 2006] - Initialized some structure members in pngwutil.c to avoid gcc-4.0.0 complaints - Revised man page and libpng.txt to make it clear that one should not call - png_read_end or png_write_end after png_read_png or png_write_png. - Updated references to png-mng-implement mailing list. - Fixed an incorrect typecast in pngrutil.c - Added PNG_NO_READ_SUPPORTED conditional for making a write-only library. - Added PNG_NO_WRITE_INTERLACING_SUPPORTED conditional. - Optimized alpha-inversion loops in pngwtran.c - Moved test for nonzero gamma outside of png_build_gamma_table() in pngrtran.c - Make sure num_trans is <= 256 before copying data in png_set_tRNS(). - Make sure num_palette is <= 256 before copying data in png_set_PLTE(). - Interchanged order of write_swap_alpha and write_invert_alpha transforms. - Added parentheses in the definition of PNG_LIBPNG_BUILD_TYPE (Cosmin). - Optimized zlib window flag (CINFO) in contrib/pngsuite/*.png (Cosmin). - Updated scripts/makefile.bc32 for Borland C++ 5.6 (Cosmin). - Exported png_get_uint_32, png_save_uint_32, png_get_uint_16, png_save_uint_16, - png_get_int_32, png_save_int_32, png_get_uint_31 (Cosmin). - Added type cast (png_byte) in png_write_sCAL() (Cosmin). - Fixed scripts/makefile.cygwin (Christian Biesinger, Cosmin). - Default iTXt support was inadvertently enabled. - -Version 1.2.9beta2 [February 21, 2006] - Check for png_rgb_to_gray and png_gray_to_rgb read transformations before - checking for png_read_dither in pngrtran.c - Revised checking of chromaticity limits to accommodate extended RGB - colorspace (John Denker). - Changed line endings in some of the project files to CRLF, even in the - "Unix" tar distributions (Cosmin). - Made png_get_int_32 and png_save_int_32 always available (Cosmin). - Updated scripts/pngos2.def, scripts/pngw32.def and projects/wince/png32ce.def - with the newly exported functions. - Eliminated distributions without the "configure" script. - Updated INSTALL instructions. - -Version 1.2.9beta3 [February 24, 2006] - Fixed CRCRLF line endings in contrib/visupng/VisualPng.dsp - Made libpng.pc respect EXEC_PREFIX (D. P. Kreil, J. Bowler) - Removed reference to pngasmrd.h from Makefile.am - Renamed CHANGES to ChangeLog. - Renamed LICENSE to COPYING. - Renamed ANNOUNCE to NEWS. - Created AUTHORS file. - -Version 1.2.9beta4 [March 3, 2006] - Changed definition of PKGCONFIG from $prefix/lib to $libdir in configure.ac - Reverted to filenames LICENSE and ANNOUNCE; removed AUTHORS and COPYING. - Removed newline from the end of some error and warning messages. - Removed test for sqrt() from configure.ac and configure. - Made swap tables in pngtrans.c PNG_CONST (Carlo Bramix). - Disabled default iTXt support that was inadvertently enabled in - libpng-1.2.9beta1. - Added "OS2" to list of systems that don't need underscores, in pnggccrd.c - Removed libpng version and date from *.c files. - -Version 1.2.9beta5 [March 4, 2006] - Removed trailing blanks from source files. - Put version and date of latest change in each source file, and changed - copyright year accordingly. - More cleanup of configure.ac, Makefile.am, and associated scripts. - Restored scripts/makefile.elf which was inadvertently deleted. - -Version 1.2.9beta6 [March 6, 2006] - Fixed typo (RELEASE) in configuration files. - -Version 1.2.9beta7 [March 7, 2006] - Removed libpng.vers and libpng.sym from libpng12_la_SOURCES in Makefile.am - Fixed inconsistent #ifdef's around png_sig_bytes() and png_set_sCAL_s() - in png.h. - Updated makefile.elf as suggested by debian. - Made cosmetic changes to some makefiles, adding LN_SF and other macros. - Made some makefiles accept "exec_prefix". - -Version 1.2.9beta8 [March 9, 2006] - Fixed some "#if defined (..." which should be "#if defined(..." - Bug introduced in libpng-1.2.8. - Fixed inconsistency in definition of png_default_read_data() - Restored blank that was lost from makefile.sggcc "clean" target in beta7. - Revised calculation of "current" and "major" for irix in ltmain.sh - Changed "mkdir" to "MKDIR_P" in some makefiles. - Separated PNG_EXPAND and PNG_EXPAND_tRNS. - Added png_set_expand_gray_1_2_4_to_8() and deprecated - png_set_gray_1_2_4_to_8() which also expands tRNS to alpha. - -Version 1.2.9beta9 [March 10, 2006] - Include "config.h" in pngconf.h when available. - Added some checks for NULL png_ptr or NULL info_ptr (timeless) - -Version 1.2.9beta10 [March 20, 2006] - Removed extra CR from contrib/visualpng/VisualPng.dsw (Cosmin) - Made pnggccrd.c PIC-compliant (Christian Aichinger). - Added makefile.mingw (Wolfgang Glas). - Revised pngconf.h MMX checking. - -Version 1.2.9beta11 [March 22, 2006] - Fixed out-of-order declaration in pngwrite.c that was introduced in beta9 - Simplified some makefiles by using LIBSO, LIBSOMAJ, and LIBSOVER macros. - -Version 1.2.9rc1 [March 31, 2006] - Defined PNG_USER_PRIVATEBUILD when including "pngusr.h" (Cosmin). - Removed nonsensical assertion check from pngtest.c (Cosmin). - -Version 1.2.9 [April 14, 2006] - Revised makefile.beos and added "none" selector in ltmain.sh - -Version 1.2.10beta1 [April 15, 2006] - Renamed "config.h" to "png_conf.h" and revised Makefile.am to add - -DPNG_BUILDING_LIBPNG to compile directive, and modified pngconf.h - to include png_conf.h only when PNG_BUILDING_LIBPNG is defined. - -Version 1.2.10beta2 [April 15, 2006] - Manually updated Makefile.in and configure. Changed png_conf.h.in - back to config.h. - -Version 1.2.10beta3 [April 15, 2006] - Change png_conf.h back to config.h in pngconf.h. - -Version 1.2.10beta4 [April 16, 2006] - Change PNG_BUILDING_LIBPNG to PNG_CONFIGURE_LIBPNG in config/Makefile*. - -Version 1.2.10beta5 [April 16, 2006] - Added a configure check for compiling assembler code in pnggccrd.c - -Version 1.2.10beta6 [April 17, 2006] - Revised the configure check for pnggccrd.c - Moved -DPNG_CONFIGURE_LIBPNG into @LIBPNG_DEFINES@ - Added @LIBPNG_DEFINES@ to arguments when building libpng.sym - -Version 1.2.10beta7 [April 18, 2006] - Change "exec_prefix=$prefix" to "exec_prefix=$(prefix)" in makefiles. - -Version 1.2.10rc1 [April 19, 2006] - Ensure pngconf.h doesn't define both PNG_USE_PNGGCCRD and PNG_USE_PNGVCRD - Fixed "LN_FS" typo in makefile.sco and makefile.solaris. - -Version 1.2.10rc2 [April 20, 2006] - Added a backslash between -DPNG_CONFIGURE_LIBPNG and -DPNG_NO_ASSEMBLER_CODE - in configure.ac and configure - Made the configure warning about versioned symbols less arrogant. - -Version 1.2.10rc3 [April 21, 2006] - Added a note in libpng.txt that png_set_sig_bytes(8) can be used when - writing an embedded PNG without the 8-byte signature. - Revised makefiles and configure to avoid making links to libpng.so.* - -Version 1.2.10 [April 23, 2006] - Reverted configure to "rc2" state. - -Version 1.2.11beta1 [May 31, 2006] - scripts/libpng.pc.in contained "configure" style version info and would - not work with makefiles. - The shared-library makefiles were linking to libpng.so.0 instead of - libpng.so.3 compatibility as the library. - -Version 1.2.11beta2 [June 2, 2006] - Increased sprintf buffer from 50 to 52 chars in pngrutil.c to avoid - buffer overflow. - Fixed bug in example.c (png_set_palette_rgb -> png_set_palette_to_rgb) - -Version 1.2.11beta3 [June 5, 2006] - Prepended "#! /bin/sh" to ltmail.sh and contrib/pngminus/*.sh (Cosmin). - Removed the accidental leftover Makefile.in~ (Cosmin). - Avoided potential buffer overflow and optimized buffer in - png_write_sCAL(), png_write_sCAL_s() (Cosmin). - Removed the include directories and libraries from CFLAGS and LDFLAGS - in scripts/makefile.gcc (Nelson A. de Oliveira, Cosmin). - -Version 1.2.11beta4 [June 6, 2006] - Allow zero-length IDAT chunks after the entire zlib datastream, but not - after another intervening chunk type. - -Version 1.0.19rc1, 1.2.11rc1 [June 13, 2006] - Deleted extraneous square brackets from [config.h] in configure.ac - -Version 1.0.19rc2, 1.2.11rc2 [June 14, 2006] - Added prototypes for PNG_INCH_CONVERSIONS functions to png.h - Revised INSTALL and autogen.sh - Fixed typo in several makefiles (-W1 should be -Wl) - Added typedef for png_int_32 and png_uint_32 on 64-bit systems. - -Version 1.0.19rc3, 1.2.11rc3 [June 15, 2006] - Removed the new typedefs for 64-bit systems (delay until version 1.4.0) - Added one zero element to png_gamma_shift[] array in pngrtran.c to avoid - reading out of bounds. - -Version 1.0.19rc4, 1.2.11rc4 [June 15, 2006] - Really removed the new typedefs for 64-bit systems. - -Version 1.0.19rc5, 1.2.11rc5 [June 22, 2006] - Removed png_sig_bytes entry from scripts/pngw32.def - -Version 1.0.19, 1.2.11 [June 26, 2006] - None. - -Version 1.0.20, 1.2.12 [June 27, 2006] - Really increased sprintf buffer from 50 to 52 chars in pngrutil.c to avoid - buffer overflow. - -Version 1.2.13beta1 [October 2, 2006] - Removed AC_FUNC_MALLOC from configure.ac - Work around Intel-Mac compiler bug by setting PNG_NO_MMX_CODE in pngconf.h - Change "logical" to "bitwise" throughout documentation. - Detect and fix attempt to write wrong iCCP profile length (CVE-2006-7244) - -Version 1.0.21, 1.2.13 [November 14, 2006] - Fix potential buffer overflow in sPLT chunk handler. - Fix Makefile.am to not try to link to noexistent files. - Check all exported functions for NULL png_ptr. - -Version 1.2.14beta1 [November 17, 2006] - Relocated three misplaced tests for NULL png_ptr. - Built Makefile.in with automake-1.9.6 instead of 1.9.2. - Build configure with autoconf-2.60 instead of 2.59 - -Version 1.2.14beta2 [November 17, 2006] - Added some typecasts in png_zalloc(). - -Version 1.2.14rc1 [November 20, 2006] - Changed "strtod" to "png_strtod" in pngrutil.c - -Version 1.0.22, 1.2.14 [November 27, 2006] - Added missing "$(srcdir)" in Makefile.am and Makefile.in - -Version 1.2.15beta1 [December 3, 2006] - Generated configure with autoconf-2.61 instead of 2.60 - Revised configure.ac to update libpng.pc and libpng-config. - -Version 1.2.15beta2 [December 3, 2006] - Always export MMX asm functions, just stubs if not building pnggccrd.c - -Version 1.2.15beta3 [December 4, 2006] - Add "png_bytep" typecast to profile while calculating length in pngwutil.c - -Version 1.2.15beta4 [December 7, 2006] - Added scripts/CMakeLists.txt - Changed PNG_NO_ASSEMBLER_CODE to PNG_NO_MMX_CODE in scripts, like 1.4.0beta - -Version 1.2.15beta5 [December 7, 2006] - Changed some instances of PNG_ASSEMBLER_* to PNG_MMX_* in pnggccrd.c - Revised scripts/CMakeLists.txt - -Version 1.2.15beta6 [December 13, 2006] - Revised scripts/CMakeLists.txt and configure.ac - -Version 1.2.15rc1 [December 18, 2006] - Revised scripts/CMakeLists.txt - -Version 1.2.15rc2 [December 21, 2006] - Added conditional #undef jmpbuf in pngtest.c to undo #define in AIX headers. - Added scripts/makefile.nommx - -Version 1.2.15rc3 [December 25, 2006] - Fixed shared library numbering error that was introduced in 1.2.15beta6. - -Version 1.2.15rc4 [December 27, 2006] - Fixed handling of rgb_to_gray when png_ptr->color.gray isn't set. - -Version 1.2.15rc5 [December 31, 2006] - Revised handling of rgb_to_gray. - -Version 1.2.15 [January 5, 2007] - Added some (unsigned long) typecasts in pngtest.c to avoid printing errors. - -Version 1.2.16beta1 [January 6, 2007] - Fix bugs in makefile.nommx - -Version 1.2.16beta2 [January 16, 2007] - Revised scripts/CMakeLists.txt - -Version 1.2.16 [January 31, 2007] - No changes. - -Version 1.2.17beta1 [March 6, 2007] - Revised scripts/CMakeLists.txt to install both shared and static libraries. - Deleted a redundant line from pngset.c. - -Version 1.2.17beta2 [April 26, 2007] - Relocated misplaced test for png_ptr == NULL in pngpread.c - Change "==" to "&" for testing PNG_RGB_TO_GRAY_ERR & PNG_RGB_TO_GRAY_WARN - flags. - Changed remaining instances of PNG_ASSEMBLER_* to PNG_MMX_* - Added pngerror() when write_IHDR fails in deflateInit2(). - Added "const" to some array declarations. - Mention examples of libpng usage in the libpng*.txt and libpng.3 documents. - -Version 1.2.17rc1 [May 4, 2007] - No changes. - -Version 1.2.17rc2 [May 8, 2007] - Moved several PNG_HAVE_* macros out of PNG_INTERNAL because applications - calling set_unknown_chunk_location() need them. - Changed transformation flag from PNG_EXPAND_tRNS to PNG_EXPAND in - png_set_expand_gray_1_2_4_to_8(). - Added png_ptr->unknown_chunk to hold working unknown chunk data, so it - can be free'ed in case of error. Revised unknown chunk handling in - pngrutil.c and pngpread.c to use this structure. - -Version 1.2.17rc3 [May 8, 2007] - Revised symbol-handling in configure script. - -Version 1.2.17rc4 [May 10, 2007] - Revised unknown chunk handling to avoid storing unknown critical chunks. - -Version 1.0.25 [May 15, 2007] -Version 1.2.17 [May 15, 2007] - Added "png_ptr->num_trans=0" before error return in png_handle_tRNS, - to eliminate a vulnerability (CVE-2007-2445, CERT VU#684664) - -Version 1.0.26 [May 15, 2007] -Version 1.2.18 [May 15, 2007] - Reverted the libpng-1.2.17rc3 change to symbol-handling in configure script - -Version 1.2.19beta1 [May 18, 2007] - Changed "const static" to "static PNG_CONST" everywhere, mostly undoing - change of libpng-1.2.17beta2. Changed other "const" to "PNG_CONST" - Changed some handling of unused parameters, to avoid compiler warnings. - "if (unused == NULL) return;" becomes "unused = unused". - -Version 1.2.19beta2 [May 18, 2007] - Only use the valid bits of tRNS value in png_do_expand() (Brian Cartier) - -Version 1.2.19beta3 [May 19, 2007] - Add some "png_byte" typecasts in png_check_keyword() and write new_key - instead of key in zTXt chunk (Kevin Ryde). - -Version 1.2.19beta4 [May 21, 2007] - Add png_snprintf() function and use it in place of sprint() for improved - defense against buffer overflows. - -Version 1.2.19beta5 [May 21, 2007] - Fixed png_handle_tRNS() to only use the valid bits of tRNS value. - Changed handling of more unused parameters, to avoid compiler warnings. - Removed some PNG_CONST in pngwutil.c to avoid compiler warnings. - -Version 1.2.19beta6 [May 22, 2007] - Added some #ifdef PNG_MMX_CODE_SUPPORTED where needed in pngvcrd.c - Added a special "_MSC_VER" case that defines png_snprintf to _snprintf - -Version 1.2.19beta7 [May 22, 2007] - Squelched png_squelch_warnings() in pnggccrd.c and added - an #ifdef PNG_MMX_CODE_SUPPORTED block around the declarations that caused - the warnings that png_squelch_warnings was squelching. - -Version 1.2.19beta8 [May 22, 2007] - Removed __MMX__ from test in pngconf.h. - -Version 1.2.19beta9 [May 23, 2007] - Made png_squelch_warnings() available via PNG_SQUELCH_WARNINGS macro. - Revised png_squelch_warnings() so it might work. - Updated makefile.sgcc and makefile.solaris; added makefile.solaris-x86. - -Version 1.2.19beta10 [May 24, 2007] - Resquelched png_squelch_warnings(), use "__attribute__((used))" instead. - -Version 1.4.0beta1 [April 20, 2006] - Enabled iTXt support (changes png_struct, thus requires so-number change). - Cleaned up PNG_ASSEMBLER_CODE_SUPPORTED vs PNG_MMX_CODE_SUPPORTED - Eliminated PNG_1_0_X and PNG_1_2_X macros. - Removed deprecated functions png_read_init, png_write_init, png_info_init, - png_permit_empty_plte, png_set_gray_1_2_4_to_8, png_check_sig, and - removed the deprecated macro PNG_MAX_UINT. - Moved "PNG_INTERNAL" parts of png.h and pngconf.h into pngintrn.h - Removed many WIN32_WCE #ifdefs (Cosmin). - Reduced dependency on C-runtime library when on Windows (Simon-Pierre) - Replaced sprintf() with png_sprintf() (Simon-Pierre) - -Version 1.4.0beta2 [April 20, 2006] - Revised makefiles and configure to avoid making links to libpng.so.* - Moved some leftover MMX-related defines from pngconf.h to pngintrn.h - Updated scripts/pngos2.def, pngw32.def, and projects/wince/png32ce.def - -Version 1.4.0beta3 [May 10, 2006] - Updated scripts/pngw32.def to comment out MMX functions. - Added PNG_NO_GET_INT_32 and PNG_NO_SAVE_INT_32 macros. - Scripts/libpng.pc.in contained "configure" style version info and would - not work with makefiles. - Revised pngconf.h and added pngconf.h.in, so makefiles and configure can - pass defines to libpng and applications. - -Version 1.4.0beta4 [May 11, 2006] - Revised configure.ac, Makefile.am, and many of the makefiles to write - their defines in pngconf.h. - -Version 1.4.0beta5 [May 15, 2006] - Added a missing semicolon in Makefile.am and Makefile.in - Deleted extraneous square brackets from configure.ac - -Version 1.4.0beta6 [June 2, 2006] - Increased sprintf buffer from 50 to 52 chars in pngrutil.c to avoid - buffer overflow. - Changed sonum from 0 to 1. - Removed unused prototype for png_check_sig() from png.h - -Version 1.4.0beta7 [June 16, 2006] - Exported png_write_sig (Cosmin). - Optimized buffer in png_handle_cHRM() (Cosmin). - Set pHYs = 2835 x 2835 pixels per meter, and added - sCAL = 0.352778e-3 x 0.352778e-3 meters, in pngtest.png (Cosmin). - Added png_set_benign_errors(), png_benign_error(), png_chunk_benign_error(). - Added typedef for png_int_32 and png_uint_32 on 64-bit systems. - Added "(unsigned long)" typecast on png_uint_32 variables in printf lists. - -Version 1.4.0beta8 [June 22, 2006] - Added demonstration of user chunk support in pngtest.c, to support the - public sTER chunk and a private vpAg chunk. - -Version 1.4.0beta9 [July 3, 2006] - Removed ordinals from scripts/pngw32.def and removed png_info_int and - png_set_gray_1_2_4_to_8 entries. - Inline call of png_get_uint_32() in png_get_uint_31(). - Use png_get_uint_31() to get vpAg width and height in pngtest.c - Removed WINCE and Netware projects. - Removed standalone Y2KINFO file. - -Version 1.4.0beta10 [July 12, 2006] - Eliminated automatic copy of pngconf.h to pngconf.h.in from configure and - some makefiles, because it was not working reliably. Instead, distribute - pngconf.h.in along with pngconf.h and cause configure and some of the - makefiles to update pngconf.h from pngconf.h.in. - Added pngconf.h to DEPENDENCIES in Makefile.am - -Version 1.4.0beta11 [August 19, 2006] - Removed AC_FUNC_MALLOC from configure.ac. - Added a warning when writing iCCP profile with mismatched profile length. - Patched pnggccrd.c to assemble on x86_64 platforms. - Moved chunk header reading into a separate function png_read_chunk_header() - in pngrutil.c. The chunk header (len+sig) is now serialized in a single - operation (Cosmin). - Implemented support for I/O states. Added png_ptr member io_state, and - functions png_get_io_chunk_name() and png_get_io_state() in pngget.c - (Cosmin). - Added png_get_io_chunk_name and png_get_io_state to scripts/*.def (Cosmin). - Renamed scripts/pngw32.* to scripts/pngwin.* (Cosmin). - Removed the include directories and libraries from CFLAGS and LDFLAGS - in scripts/makefile.gcc (Cosmin). - Used png_save_uint_32() to set vpAg width and height in pngtest.c (Cosmin). - Cast to proper type when getting/setting vpAg units in pngtest.c (Cosmin). - Added pngintrn.h to the Visual C++ projects (Cosmin). - Removed scripts/list (Cosmin). - Updated copyright year in scripts/pngwin.def (Cosmin). - Removed PNG_TYPECAST_NULL and used standard NULL consistently (Cosmin). - Disallowed the user to redefine png_size_t, and enforced a consistent use - of png_size_t across libpng (Cosmin). - Changed the type of png_ptr->rowbytes, PNG_ROWBYTES() and friends - to png_size_t (Cosmin). - Removed png_convert_size() and replaced png_sizeof with sizeof (Cosmin). - Removed some unnecessary type casts (Cosmin). - Changed prototype of png_get_compression_buffer_size() and - png_set_compression_buffer_size() to work with png_size_t instead of - png_uint_32 (Cosmin). - Removed png_memcpy_check() and png_memset_check() (Cosmin). - Fixed a typo (png_byte --> png_bytep) in libpng.3 and libpng.txt (Cosmin). - Clarified that png_zalloc() does not clear the allocated memory, - and png_zalloc() and png_zfree() cannot be PNGAPI (Cosmin). - Renamed png_mem_size_t to png_alloc_size_t, fixed its definition in - pngconf.h, and used it in all memory allocation functions (Cosmin). - Renamed pngintrn.h to pngpriv.h, added a comment at the top of the file - mentioning that the symbols declared in that file are private, and - updated the scripts and the Visual C++ projects accordingly (Cosmin). - Removed circular references between pngconf.h and pngconf.h.in in - scripts/makefile.vc*win32 (Cosmin). - Removing trailing '.' from the warning and error messages (Cosmin). - Added pngdefs.h that is built by makefile or configure, instead of - pngconf.h.in (Glenn). - Detect and fix attempt to write wrong iCCP profile length. - -Version 1.4.0beta12 [October 19, 2006] - Changed "logical" to "bitwise" in the documentation. - Work around Intel-Mac compiler bug by setting PNG_NO_MMX_CODE in pngconf.h - Add a typecast to stifle compiler warning in pngrutil.c - -Version 1.4.0beta13 [November 10, 2006] - Fix potential buffer overflow in sPLT chunk handler. - Fix Makefile.am to not try to link to noexistent files. - -Version 1.4.0beta14 [November 15, 2006] - Check all exported functions for NULL png_ptr. - -Version 1.4.0beta15 [November 17, 2006] - Relocated two misplaced tests for NULL png_ptr. - Built Makefile.in with automake-1.9.6 instead of 1.9.2. - Build configure with autoconf-2.60 instead of 2.59 - Add "install: all" in Makefile.am so "configure; make install" will work. - -Version 1.4.0beta16 [November 17, 2006] - Added a typecast in png_zalloc(). - -Version 1.4.0beta17 [December 4, 2006] - Changed "new_key[79] = '\0';" to "(*new_key)[79] = '\0';" in pngwutil.c - Add "png_bytep" typecast to profile while calculating length in pngwutil.c - -Version 1.4.0beta18 [December 7, 2006] - Added scripts/CMakeLists.txt - -Version 1.4.0beta19 [May 16, 2007] - Revised scripts/CMakeLists.txt - Rebuilt configure and Makefile.in with newer tools. - Added conditional #undef jmpbuf in pngtest.c to undo #define in AIX headers. - Added scripts/makefile.nommx - -Version 1.4.0beta20 [July 9, 2008] - Moved several PNG_HAVE_* macros from pngpriv.h to png.h because applications - calling set_unknown_chunk_location() need them. - Moved several macro definitions from pngpriv.h to pngconf.h - Merge with changes to the 1.2.X branch, as of 1.2.30beta04. - Deleted all use of the MMX assembler code and Intel-licensed optimizations. - Revised makefile.mingw - -Version 1.4.0beta21 [July 21, 2008] - Moved local array "chunkdata" from pngrutil.c to the png_struct, so - it will be freed by png_read_destroy() in case of a read error (Kurt - Christensen). - -Version 1.4.0beta22 [July 21, 2008] - Change "purpose" and "buffer" to png_ptr->chunkdata to avoid memory leaking. - -Version 1.4.0beta23 [July 22, 2008] - Change "chunkdata = NULL" to "png_ptr->chunkdata = NULL" several places in - png_decompress_chunk(). - -Version 1.4.0beta24 [July 25, 2008] - Change all remaining "chunkdata" to "png_ptr->chunkdata" in - png_decompress_chunk(), and remove "chunkdata" from parameter list. - Put a call to png_check_chunk_name() in png_read_chunk_header(). - Revised png_check_chunk_name() to reject a name with a lowercase 3rd byte. - Removed two calls to png_check_chunk_name() occurring later in the process. - Define PNG_NO_ERROR_NUMBERS by default in pngconf.h - -Version 1.4.0beta25 [July 30, 2008] - Added a call to png_check_chunk_name() in pngpread.c - Reverted png_check_chunk_name() to accept a name with a lowercase 3rd byte. - Added png_push_have_buffer() function to pngpread.c - Eliminated PNG_BIG_ENDIAN_SUPPORTED and associated png_get_* macros. - Made inline expansion of png_get_*() optional with PNG_USE_READ_MACROS. - Eliminated all PNG_USELESS_TESTS and PNG_CORRECT_PALETTE_SUPPORTED code. - Synced contrib directory and configure files with libpng-1.2.30beta06. - Eliminated no-longer-used pngdefs.h (but it's still built in the makefiles) - Relocated a misplaced "#endif /* PNG_NO_WRITE_FILTER */" in pngwutil.c - -Version 1.4.0beta26 [August 4, 2008] - Removed png_push_have_buffer() function in pngpread.c. It increased the - compiled library size slightly. - Changed "-Wall" to "-W -Wall" in the CFLAGS in all makefiles (Cosmin Truta) - Declared png_ptr "volatile" in pngread.c and pngwrite.c to avoid warnings. - Updated contrib/visupng/cexcept.h to version 2.0.1 - Added PNG_LITERAL_CHARACTER macros for #, [, and ]. - -Version 1.4.0beta27 [August 5, 2008] - Revised usage of PNG_LITERAL_SHARP in pngerror.c. - Moved newline character from individual png_debug messages into the - png_debug macros. - Allow user to #define their own png_debug, png_debug1, and png_debug2. - -Version 1.4.0beta28 [August 5, 2008] - Revised usage of PNG_LITERAL_SHARP in pngerror.c. - Added PNG_STRING_NEWLINE macro - -Version 1.4.0beta29 [August 9, 2008] - Revised usage of PNG_STRING_NEWLINE to work on non-ISO compilers. - Added PNG_STRING_COPYRIGHT macro. - Added non-ISO versions of png_debug macros. - -Version 1.4.0beta30 [August 14, 2008] - Added premultiplied alpha feature (Volker Wiendl). - -Version 1.4.0beta31 [August 18, 2008] - Moved png_set_premultiply_alpha from pngtrans.c to pngrtran.c - Removed extra crc check at the end of png_handle_cHRM(). Bug introduced - in libpng-1.4.0beta20. - -Version 1.4.0beta32 [August 19, 2008] - Added PNG_WRITE_FLUSH_SUPPORTED block around new png_flush() call. - Revised PNG_NO_STDIO version of png_write_flush() - -Version 1.4.0beta33 [August 20, 2008] - Added png_get|set_chunk_cache_max() to limit the total number of sPLT, - text, and unknown chunks that can be stored. - -Version 1.4.0beta34 [September 6, 2008] - Shortened tIME_string to 29 bytes in pngtest.c - Fixed off-by-one error introduced in png_push_read_zTXt() function in - libpng-1.2.30beta04/pngpread.c (Harald van Dijk) - -Version 1.4.0beta35 [October 6, 2008] - Changed "trans_values" to "trans_color". - Changed so-number from 0 to 14. Some OS do not like 0. - Revised makefile.darwin to fix shared library numbering. - Change png_set_gray_1_2_4_to_8() to png_set_expand_gray_1_2_4_to_8() - in example.c (debian bug report) - -Version 1.4.0beta36 [October 25, 2008] - Sync with tEXt vulnerability fix in libpng-1.2.33rc02. - -Version 1.4.0beta37 [November 13, 2008] - Added png_check_cHRM in png.c and moved checking from pngget.c, pngrutil.c, - and pngwrite.c - -Version 1.4.0beta38 [November 22, 2008] - Added check for zero-area RGB cHRM triangle in png_check_cHRM() and - png_check_cHRM_fixed(). - -Version 1.4.0beta39 [November 23, 2008] - Revised png_warning() to write its message on standard output by default - when warning_fn is NULL. - -Version 1.4.0beta40 [November 24, 2008] - Eliminated png_check_cHRM(). Instead, always use png_check_cHRM_fixed(). - In png_check_cHRM_fixed(), ensure white_y is > 0, and removed redundant - check for all-zero coordinates that is detected by the triangle check. - -Version 1.4.0beta41 [November 26, 2008] - Fixed string vs pointer-to-string error in png_check_keyword(). - Rearranged test expressions in png_check_cHRM_fixed() to avoid internal - overflows. - Added PNG_NO_CHECK_cHRM conditional. - -Version 1.4.0beta42, 43 [December 1, 2008] - Merge png_debug with version 1.2.34beta04. - -Version 1.4.0beta44 [December 6, 2008] - Removed redundant check for key==NULL before calling png_check_keyword() - to ensure that new_key gets initialized and removed extra warning - (Merge with version 1.2.34beta05 -- Arvan Pritchard). - -Version 1.4.0beta45 [December 9, 2008] - In png_write_png(), respect the placement of the filler bytes in an earlier - call to png_set_filler() (Jim Barry). - -Version 1.4.0beta46 [December 10, 2008] - Undid previous change and added PNG_TRANSFORM_STRIP_FILLER_BEFORE and - PNG_TRANSFORM_STRIP_FILLER_AFTER conditionals and deprecated - PNG_TRANSFORM_STRIP_FILLER (Jim Barry). - -Version 1.4.0beta47 [December 15, 2008] - Support for dithering was disabled by default, because it has never - been well tested and doesn't work very well. The code has not - been removed, however, and can be enabled by building libpng with - PNG_READ_DITHER_SUPPORTED defined. - -Version 1.4.0beta48 [February 14, 2009] - Added new exported function png_calloc(). - Combined several instances of png_malloc(); png_memset() into png_calloc(). - Removed prototype for png_freeptr() that was added in libpng-1.4.0beta24 - but was never defined. - -Version 1.4.0beta49 [February 28, 2009] - Added png_fileno() macro to pngconf.h, used in pngwio.c - Corrected order of #ifdef's in png_debug definition in png.h - Fixed bug introduced in libpng-1.4.0beta48 with the memset arguments - for pcal_params. - Fixed order of #ifdef directives in the png_debug defines in png.h - (bug introduced in libpng-1.2.34/1.4.0beta29). - Revised comments in png_set_read_fn() and png_set_write_fn(). - -Version 1.4.0beta50 [March 18, 2009] - Use png_calloc() instead of png_malloc() to allocate big_row_buf when - reading an interlaced file, to avoid a possible UMR. - Undid revision of PNG_NO_STDIO version of png_write_flush(). Users - having trouble with fflush() can build with PNG_NO_WRITE_FLUSH defined - or supply their own flush_fn() replacement. - Revised libpng*.txt and png.h documentation about use of png_write_flush() - and png_set_write_fn(). - Removed fflush() from pngtest.c. - Added "#define PNG_NO_WRITE_FLUSH" to contrib/pngminim/encoder/pngusr.h - -Version 1.4.0beta51 [March 21, 2009] - Removed new png_fileno() macro from pngconf.h . - -Version 1.4.0beta52 [March 27, 2009] - Relocated png_do_chop() ahead of building gamma tables in pngrtran.c - This avoids building 16-bit gamma tables unnecessarily. - Removed fflush() from pngtest.c. - Added "#define PNG_NO_WRITE_FLUSH" to contrib/pngminim/encoder/pngusr.h - Added a section on differences between 1.0.x and 1.2.x to libpng.3/libpng.txt - -Version 1.4.0beta53 [April 1, 2009] - Removed some remaining MMX macros from pngpriv.h - Fixed potential memory leak of "new_name" in png_write_iCCP() (Ralph Giles) - -Version 1.4.0beta54 [April 13, 2009] - Added "ifndef PNG_SKIP_SETJMP_CHECK" block in pngconf.h to allow - application code writers to bypass the check for multiple inclusion - of setjmp.h when they know that it is safe to ignore the situation. - Eliminated internal use of setjmp() in pngread.c and pngwrite.c - Reordered ancillary chunks in pngtest.png to be the same as what - pngtest now produces, and made some cosmetic changes to pngtest output. - Eliminated deprecated png_read_init_3() and png_write_init_3() functions. - -Version 1.4.0beta55 [April 15, 2009] - Simplified error handling in pngread.c and pngwrite.c by putting - the new png_read_cleanup() and png_write_cleanup() functions inline. - -Version 1.4.0beta56 [April 25, 2009] - Renamed "user_chunk_data" to "my_user_chunk_data" in pngtest.c to suppress - "shadowed declaration" warning from gcc-4.3.3. - Renamed "gamma" to "png_gamma" in pngset.c to avoid "shadowed declaration" - warning about a global "gamma" variable in math.h on some platforms. - -Version 1.4.0beta57 [May 2, 2009] - Removed prototype for png_freeptr() that was added in libpng-1.4.0beta24 - but was never defined (again). - Rebuilt configure scripts with autoconf-2.63 instead of 2.62 - Removed pngprefs.h and MMX from makefiles - -Version 1.4.0beta58 [May 14, 2009] - Changed pngw32.def to pngwin.def in makefile.mingw (typo was introduced - in beta57). - Clarified usage of sig_bit versus sig_bit_p in example.c (Vincent Torri) - -Version 1.4.0beta59 [May 15, 2009] - Reformated sources in libpng style (3-space intentation, comment format) - Fixed typo in libpng docs (PNG_FILTER_AVE should be PNG_FILTER_AVG) - Added sections about the git repository and our coding style to the - documentation - Relocated misplaced #endif in pngwrite.c, sCAL chunk handler. - -Version 1.4.0beta60 [May 19, 2009] - Conditionally compile png_read_finish_row() which is not used by - progressive readers. - Added contrib/pngminim/preader to demonstrate building minimal progressive - decoder, based on contrib/gregbook with embedded libpng and zlib. - -Version 1.4.0beta61 [May 20, 2009] - In contrib/pngminim/*, renamed "makefile.std" to "makefile", since there - is only one makefile in those directories, and revised the README files - accordingly. - More reformatting of comments, mostly to capitalize sentences. - -Version 1.4.0beta62 [June 2, 2009] - Added "#define PNG_NO_WRITE_SWAP" to contrib/pngminim/encoder/pngusr.h - and "define PNG_NO_READ_SWAP" to decoder/pngusr.h and preader/pngusr.h - Reformatted several remaining "else statement" into two lines. - Added a section to the libpng documentation about using png_get_io_ptr() - in configure scripts to detect the presence of libpng. - -Version 1.4.0beta63 [June 15, 2009] - Revised libpng*.txt and libpng.3 to mention calling png_set_IHDR() - multiple times and to specify the sample order in the tRNS chunk, - because the ISO PNG specification has a typo in the tRNS table. - Changed several PNG_UNKNOWN_CHUNK_SUPPORTED to - PNG_HANDLE_AS_UNKNOWN_SUPPORTED, to make the png_set_keep mechanism - available for ignoring known chunks even when not saving unknown chunks. - Adopted preference for consistent use of "#ifdef" and "#ifndef" versus - "#if defined()" and "if !defined()" where possible. - -Version 1.4.0beta64 [June 24, 2009] - Eliminated PNG_LEGACY_SUPPORTED code. - Moved the various unknown chunk macro definitions outside of the - PNG_READ|WRITE_ANCILLARY_CHUNK_SUPPORTED blocks. - -Version 1.4.0beta65 [June 26, 2009] - Added a reference to the libpng license in each file. - -Version 1.4.0beta66 [June 27, 2009] - Refer to the libpng license instead of the libpng license in each file. - -Version 1.4.0beta67 [July 6, 2009] - Relocated INVERT_ALPHA within png_read_png() and png_write_png(). - Added high-level API transform PNG_TRANSFORM_GRAY_TO_RGB. - Added an "xcode" project to the projects directory (Alam Arias). - -Version 1.4.0beta68 [July 19, 2009] - Avoid some tests in filter selection in pngwutil.c - -Version 1.4.0beta69 [July 25, 2009] - Simplified the new filter-selection test. This runs faster in the - common "PNG_ALL_FILTERS" and PNG_FILTER_NONE cases. - Removed extraneous declaration from the new call to png_read_gray_to_rgb() - (bug introduced in libpng-1.4.0beta67). - Fixed up xcode project (Alam Arias) - Added a prototype for png_64bit_product() in png.c - -Version 1.4.0beta70 [July 27, 2009] - Avoid a possible NULL dereference in debug build, in png_set_text_2(). - (bug introduced in libpng-0.95, discovered by Evan Rouault) - -Version 1.4.0beta71 [July 29, 2009] - Rebuilt configure scripts with autoconf-2.64. - -Version 1.4.0beta72 [August 1, 2009] - Replaced *.tar.lzma with *.tar.xz in distribution. Get the xz codec - from <http://tukaani.org/xz>. - -Version 1.4.0beta73 [August 1, 2009] - Reject attempt to write iCCP chunk with negative embedded profile length - (JD Chen) (CVE-2009-5063). - -Version 1.4.0beta74 [August 8, 2009] - Changed png_ptr and info_ptr member "trans" to "trans_alpha". - -Version 1.4.0beta75 [August 21, 2009] - Removed an extra png_debug() recently added to png_write_find_filter(). - Fixed incorrect #ifdef in pngset.c regarding unknown chunk support. - -Version 1.4.0beta76 [August 22, 2009] - Moved an incorrectly located test in png_read_row() in pngread.c - -Version 1.4.0beta77 [August 27, 2009] - Removed lpXYZ.tar.bz2 (with CRLF), KNOWNBUG, libpng-x.y.z-KNOWNBUG.txt, - and the "noconfig" files from the distribution. - Moved CMakeLists.txt from scripts into the main libpng directory. - Various bugfixes and improvements to CMakeLists.txt (Philip Lowman) - -Version 1.4.0beta78 [August 31, 2009] - Converted all PNG_NO_* tests to PNG_*_SUPPORTED everywhere except pngconf.h - Eliminated PNG_NO_FREE_ME and PNG_FREE_ME_SUPPORTED macros. - Use png_malloc plus a loop instead of png_calloc() to initialize - row_pointers in png_read_png(). - -Version 1.4.0beta79 [September 1, 2009] - Eliminated PNG_GLOBAL_ARRAYS and PNG_LOCAL_ARRAYS; always use local arrays. - Eliminated PNG_CALLOC_SUPPORTED macro and always provide png_calloc(). - -Version 1.4.0beta80 [September 17, 2009] - Removed scripts/libpng.icc - Changed typecast of filler from png_byte to png_uint_16 in png_set_filler(). - (Dennis Gustafsson) - Fixed typo introduced in beta78 in pngtest.c ("#if def " should be "#ifdef ") - -Version 1.4.0beta81 [September 23, 2009] - Eliminated unused PNG_FLAG_FREE_* defines from pngpriv.h - Expanded TAB characters in pngrtran.c - Removed PNG_CONST from all "PNG_CONST PNG_CHNK" declarations to avoid - compiler complaints about doubly declaring things "const". - Changed all "#if [!]defined(X)" to "if[n]def X" where possible. - Eliminated unused png_ptr->row_buf_size - -Version 1.4.0beta82 [September 25, 2009] - Moved redundant IHDR checking into new png_check_IHDR() in png.c - and report all errors found in the IHDR data. - Eliminated useless call to png_check_cHRM() from pngset.c - -Version 1.4.0beta83 [September 25, 2009] - Revised png_check_IHDR() to eliminate bogus complaint about filter_type. - -Version 1.4.0beta84 [September 30, 2009] - Fixed some inconsistent indentation in pngconf.h - Revised png_check_IHDR() to add a test for width variable less than 32-bit. - -Version 1.4.0beta85 [October 1, 2009] - Revised png_check_IHDR() again, to check info_ptr members instead of - the contents of the returned parameters. - -Version 1.4.0beta86 [October 9, 2009] - Updated the "xcode" project (Alam Arias). - Eliminated a shadowed declaration of "pp" in png_handle_sPLT(). - -Version 1.4.0rc01 [October 19, 2009] - Trivial cosmetic changes. - -Version 1.4.0beta87 [October 30, 2009] - Moved version 1.4.0 back into beta. - -Version 1.4.0beta88 [October 30, 2009] - Revised libpng*.txt section about differences between 1.2.x and 1.4.0 - because most of the new features have now been ported back to 1.2.41 - -Version 1.4.0beta89 [November 1, 2009] - More bugfixes and improvements to CMakeLists.txt (Philip Lowman) - Removed a harmless extra png_set_invert_alpha() from pngwrite.c - Apply png_user_chunk_cache_max within png_decompress_chunk(). - Merged libpng-1.2.41.txt with libpng-1.4.0.txt where appropriate. - -Version 1.4.0beta90 [November 2, 2009] - Removed all remaining WIN32_WCE #ifdefs except those involving the - time.h "tm" structure - -Version 1.4.0beta91 [November 3, 2009] - Updated scripts/pngw32.def and projects/wince/png32ce.def - Copied projects/wince/png32ce.def to the scripts directory. - Added scripts/makefile.wce - Patched ltmain.sh for wince support. - Added PNG_CONVERT_tIME_SUPPORTED macro. - -Version 1.4.0beta92 [November 4, 2009] - Make inclusion of time.h in pngconf.h depend on PNG_CONVERT_tIME_SUPPORTED - Make #define PNG_CONVERT_tIME_SUPPORTED depend on PNG_WRITE_tIME_SUPPORTED - Revised libpng*.txt to describe differences from 1.2.40 to 1.4.0 (instead - of differences from 1.2.41 to 1.4.0) - -Version 1.4.0beta93 [November 7, 2009] - Added PNG_DEPSTRUCT, PNG_DEPRECATED, PNG_USE_RESULT, PNG_NORETURN, and - PNG_ALLOCATED macros to detect deprecated direct access to the - png_struct or info_struct members and other deprecated usage in - applications (John Bowler). - Updated scripts/makefile* to add "-DPNG_CONFIGURE_LIBPNG" to CFLAGS, - to prevent warnings about direct access to png structs by libpng - functions while building libpng. They need to be tested, especially - those using compilers other than gcc. - Updated projects/visualc6 and visualc71 with "/d PNG_CONFIGURE_LIBPNG". - They should work but still need to be updated to remove - references to pnggccrd.c or pngvcrd.c and ASM building. - Added README.txt to the beos, cbuilder5, netware, and xcode projects warning - that they need to be updated, to remove references to pnggccrd.c and - pngvcrd.c and to depend on pngpriv.h - Removed three direct references to read_info_ptr members in pngtest.c - that were detected by the new PNG_DEPSTRUCT macro. - Moved the png_debug macro definitions and the png_read_destroy(), - png_write_destroy() and png_far_to_near() prototypes from png.h - to pngpriv.h (John Bowler) - Moved the synopsis lines for png_read_destroy(), png_write_destroy() - png_debug(), png_debug1(), and png_debug2() from libpng.3 to libpngpf.3. - -Version 1.4.0beta94 [November 9, 2009] - Removed the obsolete, unused pnggccrd.c and pngvcrd.c files. - Updated CMakeLists.txt to add "-DPNG_CONFIGURE_LIBPNG" to the definitions. - Removed dependency of pngtest.o on pngpriv.h in the makefiles. - Only #define PNG_DEPSTRUCT, etc. in pngconf.h if not already defined. - -Version 1.4.0beta95 [November 10, 2009] - Changed png_check_sig() to !png_sig_cmp() in contrib programs. - Added -DPNG_CONFIGURE_LIBPNG to contrib/pngminm/*/makefile - Changed png_check_sig() to !png_sig_cmp() in contrib programs. - Corrected the png_get_IHDR() call in contrib/gregbook/readpng2.c - Changed pngminim/*/gather.sh to stop trying to remove pnggccrd.c and pngvcrd.c - Added dependency on pngpriv.h in contrib/pngminim/*/makefile - -Version 1.4.0beta96 [November 12, 2009] - Renamed scripts/makefile.wce to scripts/makefile.cegcc - Revised Makefile.am to use libpng.sys while building libpng.so - so that only PNG_EXPORT functions are exported. - Removed the deprecated png_check_sig() function/macro. - Removed recently removed function names from scripts/*.def - Revised pngtest.png to put chunks in the same order written by pngtest - (evidently the same change made in libpng-1.0beta54 was lost). - Added PNG_PRIVATE macro definition in pngconf.h for possible future use. - -Version 1.4.0beta97 [November 13, 2009] - Restored pngtest.png to the libpng-1.4.0beta7 version. - Removed projects/beos and netware.txt; no one seems to be supporting them. - Revised Makefile.in - -Version 1.4.0beta98 [November 13, 2009] - Added the "xcode" project to zip distributions, - Fixed a typo in scripts/pngwin.def introduced in beta97. - -Version 1.4.0beta99 [November 14, 2009] - Moved libpng-config.in and libpng.pc-configure.in out of the scripts - directory, to libpng-config.in and libpng-pc.in, respectively, and - modified Makefile.am and configure.ac accordingly. Now "configure" - needs nothing from the "scripts" directory. - Avoid redefining PNG_CONST in pngconf.h - -Version 1.4.0beta100 [November 14, 2009] - Removed ASM builds from projects/visualc6 and projects/visualc71 - Removed scripts/makefile.nommx and makefile.vcawin32 - Revised CMakeLists.txt to account for new location of libpng-config.in - and libpng-pc.in - Updated INSTALL to reflect removal and relocation of files. - -Version 1.4.0beta101 [November 14, 2009] - Restored the binary files (*.jpg, *.png, some project files) that were - accidentally deleted from the zip and 7z distributions when the xcode - project was added. - -Version 1.4.0beta102 [November 18, 2009] - Added libpng-config.in and libpng-pc.in to the zip and 7z distributions. - Fixed a typo in projects/visualc6/pngtest.dsp, introduced in beta100. - Moved descriptions of makefiles and other scripts out of INSTALL into - scripts/README.txt - Updated the copyright year in scripts/pngwin.rc from 2006 to 2009. - -Version 1.4.0beta103 [November 21, 2009] - Removed obsolete comments about ASM from projects/visualc71/README_zlib.txt - Align row_buf on 16-byte boundary in memory. - Restored the PNG_WRITE_FLUSH_AFTER_IEND_SUPPORTED guard around the call - to png_flush() after png_write_IEND(). See 1.4.0beta32, 1.4.0beta50 - changes above and 1.2.30, 1.2.30rc01 and rc03 in 1.2.41 CHANGES. Someone - needs this feature. - Make the 'png_jmpbuf' macro expand to a call that records the correct - longjmp function as well as returning a pointer to the setjmp - jmp_buf buffer, and marked direct access to jmpbuf 'deprecated'. - (John Bowler) - -Version 1.4.0beta104 [November 22, 2009] - Removed png_longjmp_ptr from scripts/*.def and libpng.3 - Rebuilt configure scripts with autoconf-2.65 - -Version 1.4.0beta105 [November 25, 2009] - Use fast integer PNG_DIVIDE_BY_255() or PNG_DIVIDE_BY_65535() - to accomplish alpha premultiplication when - PNG_READ_COMPOSITE_NODIV_SUPPORTED is defined. - Changed "/255" to "/255.0" in background calculations to make it clear - that the 255 is used as a double. - -Version 1.4.0beta106 [November 27, 2009] - Removed premultiplied alpha feature. - -Version 1.4.0beta107 [December 4, 2009] - Updated README - Added "#define PNG_NO_PEDANTIC_WARNINGS" in the libpng source files. - Removed "-DPNG_CONFIGURE_LIBPNG" from the makefiles and projects. - Revised scripts/makefile.netbsd, makefile.openbsd, and makefile.sco - to put png.h and pngconf.h in $prefix/include, like the other scripts, - instead of in $prefix/include/libpng. Also revised makefile.sco - to put them in $prefix/include/libpng15 instead of in - $prefix/include/libpng/libpng15. - -Version 1.4.0beta108 [December 11, 2009] - Removed leftover "-DPNG_CONFIGURE_LIBPNG" from contrib/pngminim/*/makefile - Relocated png_do_chop() to its original position in pngrtran.c; the - change in version 1.2.41beta08 caused transparency to be handled wrong - in some 16-bit datastreams (Yusaku Sugai). - -Version 1.4.0beta109 [December 13, 2009] - Added "bit_depth" parameter to the private png_build_gamma_table() function. - Pass bit_depth=8 to png_build_gamma_table() when bit_depth is 16 but the - PNG_16_TO_8 transform has been set, to avoid unnecessary build of 16-bit - tables. - -Version 1.4.0rc02 [December 20, 2009] - Declared png_cleanup_needed "volatile" in pngread.c and pngwrite.c - -Version 1.4.0rc03 [December 22, 2009] - Renamed libpng-pc.in back to libpng.pc.in and revised CMakeLists.txt - (revising the change in 1.4.0beta99) - -Version 1.4.0rc04 [December 25, 2009] - Swapped PNG_UNKNOWN_CHUNKS_SUPPORTED and PNG_HANDLE_AS_UNKNOWN_SUPPORTED - in pngset.c to be consistent with other changes in version 1.2.38. - -Version 1.4.0rc05 [December 25, 2009] - Changed "libpng-pc.in" to "libpng.pc.in" in configure.ac, configure, and - Makefile.in to be consistent with changes in libpng-1.4.0rc03 - -Version 1.4.0rc06 [December 29, 2009] - Reverted the gamma_table changes from libpng-1.4.0beta109. - Fixed some indentation errors. - -Version 1.4.0rc07 [January 1, 2010] - Revised libpng*.txt and libpng.3 about 1.2.x->1.4.x differences. - Use png_calloc() instead of png_malloc(); png_memset() in pngrutil.c - Update copyright year to 2010. - -Version 1.4.0rc08 [January 2, 2010] - Avoid deprecated references to png_ptr-io_ptr and png_ptr->error_ptr - in pngtest.c - -Version 1.4.0 [January 3, 2010] - No changes. - -Version 1.4.1beta01 [January 8, 2010] - Updated CMakeLists.txt for consistent indentation and to avoid an - unclosed if-statement warning (Philip Lowman). - Revised Makefile.am and Makefile.in to remove references to Y2KINFO, - KNOWNBUG, and libpng.la (Robert Schwebel). - Revised the makefiles to install the same files and symbolic - links as configure, except for libpng.la and libpng14.la. - Make png_set|get_compression_buffer_size() available even when - PNG_WRITE_SUPPORTED is not enabled. - Revised Makefile.am and Makefile.in to simplify their maintenance. - Revised scripts/makefile.linux to install a link to libpng14.so.14.1 - -Version 1.4.1beta02 [January 9, 2010] - Revised the rest of the makefiles to install a link to libpng14.so.14.1 - -Version 1.4.1beta03 [January 10, 2010] - Removed png_set_premultiply_alpha() from scripts/*.def - -Version 1.4.1rc01 [January 16, 2010] - No changes. - -Version 1.4.1beta04 [January 23, 2010] - Revised png_decompress_chunk() to improve speed and memory usage when - decoding large chunks. - Added png_set|get_chunk_malloc_max() functions. - -Version 1.4.1beta05 [January 26, 2010] - Relocated "int k" declaration in pngtest.c to minimize its scope. - -Version 1.4.1beta06 [January 28, 2010] - Revised png_decompress_chunk() to use a two-pass method suggested by - John Bowler. - -Version 1.4.1beta07 [February 6, 2010] - Folded some long lines in the source files. - Added defineable PNG_USER_CHUNK_CACHE_MAX, PNG_USER_CHUNK_MALLOC_MAX, - and a PNG_USER_LIMITS_SUPPORTED flag. - Eliminated use of png_ptr->irowbytes and reused the slot in png_ptr as - png_ptr->png_user_chunk_malloc_max. - Revised png_push_save_buffer() to do fewer but larger png_malloc() calls. - -Version 1.4.1beta08 [February 6, 2010] - Minor cleanup and updating of dates and copyright year. - -Version 1.5.0beta01 [February 7, 2010] - Moved declaration of png_struct into private pngstruct.h and png_info - into pnginfo.h - -Version 1.4.1beta09 and 1.5.0beta02 [February 7, 2010] - Reverted to original png_push_save_buffer() code. - -Version 1.4.1beta10 and 1.5.0beta03 [February 8, 2010] - Return allocated "old_buffer" in png_push_save_buffer() before - calling png_error(), to avoid a potential memory leak. - Updated configure script to use SO number 15. - -Version 1.5.0beta04 [February 9, 2010] - Removed malformed "incomplete struct declaration" of png_info from png.h - -Version 1.5.0beta05 [February 12, 2010] - Removed PNG_DEPSTRUCT markup in pngstruct.h and pnginfo.h, and undid the - linewrapping that it entailed. - Revised comments in pngstruct.h and pnginfo.h and added pointers to - the libpng license. - Changed PNG_INTERNAL to PNG_EXPOSE_INTERNAL_STRUCTURES - Removed the cbuilder5 project, which has not been updated to 1.4.0. - -Version 1.4.1beta12 and 1.5.0beta06 [February 14, 2010] - Fixed type declaration of png_get_chunk_malloc_max() in pngget.c (Daisuke - Nishikawa) - -Version 1.5.0beta07 [omitted] - -Version 1.5.0beta08 [February 19, 2010] - Changed #ifdef PNG_NO_STDIO_SUPPORTED to #ifdef PNG_NO_CONSOLE_IO_SUPPORTED - wherever png_snprintf() is used to construct error and warning messages. - Noted in scripts/makefile.mingw that it expects to be run under MSYS. - Removed obsolete unused MMX-querying support from contrib/gregbook - Added exported png_longjmp() function. - Removed the AIX redefinition of jmpbuf in png.h - Added -D_ALLSOURCE in configure.ac, makefile.aix, and CMakeLists.txt - when building on AIX. - -Version 1.5.0beta09 [February 19, 2010] - Removed -D_ALLSOURCE from configure.ac, makefile.aix, and CMakeLists.txt. - Changed the name of png_ptr->jmpbuf to png_ptr->png_jmpbuf in pngstruct.h - -Version 1.5.0beta10 [February 25, 2010] - Removed unused gzio.c from contrib/pngminim gather and makefile scripts - Removed replacement error handlers from contrib/gregbook. Because of - the new png_longjmp() function they are no longer needed. - -Version 1.5.0beta11 [March 6, 2010] - Removed checking for already-included setjmp.h from pngconf.h - Fixed inconsistent indentations and made numerous cosmetic changes. - Revised the "SEE ALSO" style of libpng.3, libpngpf.3, and png.5 - -Version 1.5.0beta12 [March 9, 2010] - Moved "#include png.h" inside pngpriv.h and removed "#include png.h" from - the source files, along with "#define PNG_EXPOSE_INTERNAL_STRUCTURES" - and "#define PNG_NO_PEDANTIC_WARNINGS" (John Bowler). - Created new pngdebug.h and moved debug definitions there. - -Version 1.5.0beta13 [March 10, 2010] - Protect pngstruct.h, pnginfo.h, and pngdebug.h from being included twice. - Revise the "#ifdef" blocks in png_inflate() so it will compile when neither - PNG_USER_CHUNK_MALLOC_MAX nor PNG_SET_CHUNK_MALLOC_LIMIT_SUPPORTED - is defined. - Removed unused png_measure_compressed_chunk() from pngpriv.h and libpngpf.3 - Moved the 'config.h' support from pngconf.h to pngpriv.h - Removed PNGAPI from the png_longjmp_ptr typedef. - Eliminated dependence of pngtest.c on the private pngdebug.h file. - Make all png_debug macros into *unterminated* statements or - expressions (i.e. a trailing ';' must always be added) and correct - the format statements in various png_debug messages. - -Version 1.5.0beta14 [March 14, 2010] - Removed direct access to png_ptr->io_ptr from the Windows code in pngtest.c - Revised Makefile.am to account for recent additions and replacements. - Corrected CE and OS/2 DEF files (scripts/png*def) for symbols removed and - added ordinal numbers to the Windows DEF file and corrected the duplicated - ordinal numbers on CE symbols that are commented out. - Added back in export symbols that can be present in the Windows build but - are disabled by default. - PNG_EXPORT changed to include an 'ordinal' field for DEF file generation. - PNG_CALLBACK added to make callback definitions uniform. PNGAPI split - into PNGCAPI (base C form), PNGAPI (exports) and PNGCBAPI (callbacks), - and appropriate changes made to all files. Cygwin builds re-hinged to - allow procedure call standard changes and to remove the need for the DEF - file (fixes build on Cygwin). - Enabled 'attribute' warnings that are relevant to library APIs and callbacks. - Changed rules for generation of the various symbol files and added a new - rule for a DEF file (which is also added to the distribution). - Updated the symbol file generation to stop it adding spurious spaces - to EOL (coming from preprocessor macro expansion). Added a facility - to join tokens in the output and rewrite *.dfn to use this. - Eliminated scripts/*.def in favor of libpng.def; updated projects/visualc71 - and removed scripts/makefile.cygwin. - Made PNG_BUILD_DLL safe: it can be set whenever a DLL is being built. - Removed the include of sys/types.h - apparently unnecessary now on the - platforms on which it happened (all but Mac OS and RISC OS). - Moved the Mac OS test into pngpriv.h (the only place it is used.) - -Version 1.5.0beta15 [March 17, 2010] - Added symbols.chk target to Makefile.am to validate the symbols in png.h - against the new DEF file scripts/symbols.def. - Changed the default DEF file back to pngwin.def. - Removed makefile.mingw. - Eliminated PNG_NO_EXTERN and PNG_ALL_EXTERN - -Version 1.5.0beta16 [April 1, 2010] - Make png_text_struct independent of PNG_iTXt_SUPPORTED, so that - fields are initialized in all configurations. The READ/WRITE - macros (PNG_(READ|WRITE)_iTXt_SUPPORTED) still function as - before to disable code to actually read or write iTXt chunks - and iTXt_SUPPORTED can be used to detect presence of either - read or write support (but it is probably better to check for - the one actually required - read or write.) - Combined multiple png_warning() calls for a single error. - Restored the macro definition of png_check_sig(). - -Version 1.5.0beta17 [April 17, 2010] - Added some "(long)" typecasts to printf calls in png_handle_cHRM(). - Documented the fact that png_set_dither() was disabled since libpng-1.4.0. - Reenabled png_set_dither() but renamed it to png_set_quantize() to reflect - more accurately what it actually does. At the same time, renamed - the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros to - PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS. - Added some "(long)" typecasts to printf calls in png_handle_cHRM(). - Freeze build-time only configuration in the build. - In all prior versions of libpng most configuration options - controlled by compiler #defines had to be repeated by the - application code that used libpng. This patch changes this - so that compilation options that can only be changed at build - time are frozen in the build. Options that are compiler - dependent (and those that are system dependent) are evaluated - each time - pngconf.h holds these. Options that can be changed - per-file in the application are in png.h. Frozen options are - in the new installed header file pnglibconf.h (John Bowler) - Removed the xcode project because it has not been updated to work - with libpng-1.5.0. - Removed the ability to include optional pngusr.h - -Version 1.5.0beta18 [April 17, 2010] - Restored the ability to include optional pngusr.h - Moved replacements for png_error() and png_warning() from the - contrib/pngminim project to pngerror.c, for use when warnings or - errors are disabled via PNG_NO_WARN or PNG_NO_ERROR_TEXT, to avoid - storing unneeded error/warning text. - Updated contrib/pngminim project to work with the new pnglibconf.h - Added some PNG_NO_* defines to contrib/pngminim/*/pngusr.h to save space. - -Version 1.5.0beta19 [April 24, 2010] - Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED. This allows the functions - to read and write ints to be disabled independently of PNG_USE_READ_MACROS, - which allows libpng to be built with the functions even though the default - is to use the macros - this allows applications to choose at app build - time whether or not to use macros (previously impossible because the - functions weren't in the default build.) - Changed Windows calling convention back to __cdecl for API functions. - For Windows/x86 platforms only: - __stdcall is no longer needed for Visual Basic, so libpng-1.5.0 uses - __cdecl throughout (both API functions and callbacks) on Windows/x86 - platforms. - Replaced visualc6 and visualc71 projects with new vstudio project - Relaxed the overly-restrictive permissions of some files. - -Version 1.5.0beta20 [April 24, 2010] - Relaxed more overly-restrictive permissions of some files. - -Version 1.5.0beta21 [April 27, 2010] - Removed some unwanted binary bytes and changed CRLF to NEWLINE in the new - vstudio project files, and some trivial editing of some files in the - scripts directory. - Set PNG_NO_READ_BGR, PNG_NO_IO_STATE, and PNG_NO_TIME_RFC1123 in - contrib/pngminim/decoder/pngusr.h to make a smaller decoder application. - -Version 1.5.0beta22 [April 28, 2010] - Fixed dependencies of GET_INT_32 - it does not require READ_INT_FUNCTIONS - because it has a macro equivalent. - Improved the options.awk script; added an "everything off" option. - Revised contrib/pngminim to use the "everything off" option in pngusr.dfa. - -Version 1.5.0beta23 [April 29, 2010] - Corrected PNG_REMOVED macro to take five arguments. - The macro was documented with two arguments (name,ordinal), however - the symbol checking .dfn files assumed five arguments. The five - argument form seems more useful so it is changed to that. - Corrected PNG_UNKNOWN_CHUNKS_SUPPORTED to PNG_HANDLE_AS_UNKNOWN_SUPPORTED - in gregbook/readpng2.c - Corrected protection of png_get_user_transform_ptr. The API declaration in - png.h is removed if both READ and WRITE USER_TRANSFORM are turned off - but was left defined in pngtrans.c - Added logunsupported=1 to cause pnglibconf.h to document disabled options. - This makes the installed pnglibconf.h more readable but causes no - other change. The intention is that users of libpng will find it - easier to understand if an API they need is missing. - Include png_reset_zstream() in png.c only when PNG_READ_SUPPORTED is defined. - Removed dummy_inflate.c from contrib/pngminim/encoder - Removed contrib/pngminim/*/gather.sh; gathering is now done in the makefile. - -Version 1.5.0beta24 [May 7, 2010] - Use bitwise "&" instead of arithmetic mod in pngrutil.c calculation of the - offset of the png_ptr->rowbuf pointer into png_ptr->big_row_buf. - Added more blank lines for readability. - -Version 1.5.0beta25 [June 18, 2010] - In pngpread.c: png_push_have_row() add check for new_row > height - Removed the now-redundant check for out-of-bounds new_row from example.c - -Version 1.5.0beta26 [June 18, 2010] - In pngpread.c: png_push_process_row() add check for too many rows. - -Version 1.5.0beta27 [June 18, 2010] - Removed the check added in beta25 as it is now redundant. - -Version 1.5.0beta28 [June 20, 2010] - Rewrote png_process_IDAT_data to consistently treat extra data as warnings - and handle end conditions more cleanly. - Removed the new (beta26) check in png_push_process_row(). - -Version 1.5.0beta29 [June 21, 2010] - Revised scripts/options.awk to work on Sunos (but still doesn't work) - Added comment to options.awk and contrib/pngminim/*/makefile to try nawk. - -Version 1.5.0beta30 [June 22, 2010] - Stop memory leak when reading a malformed sCAL chunk. - -Version 1.5.0beta31 [June 26, 2010] - Revised pngpread.c patch of beta28 to avoid an endless loop. - Removed some trailing blanks. - -Version 1.5.0beta32 [June 26, 2010] - Removed leftover scripts/options.patch and scripts/options.rej - -Version 1.5.0beta33 [July 6, 3010] - Made FIXED and FLOATING options consistent in the APIs they enable and - disable. Corrected scripts/options.awk to handle both command line - options and options specified in the .dfa files. - Changed char *msg to PNG_CONST char *msg in pngrutil.c - Make png_set_sRGB_gAMA_and_cHRM set values using either the fixed or - floating point APIs, but not both. - Reversed patch to remove error handler when the jmp_buf is stored in the - main program structure, not the png_struct. - The error handler is needed because the default handler in libpng will - always use the jmp_buf in the library control structure; this is never - set. The gregbook code is a useful example because, even though it - uses setjmp/longjmp, it shows how error handling can be implemented - using control mechanisms not directly supported by libpng. The - technique will work correctly with mechanisms such as Microsoft - Structure Exceptions or C++ exceptions (compiler willing - note that gcc - does not by default support interworking of C and C++ error handling.) - Reverted changes to call png_longjmp in contrib/gregbook where it is not - appropriate. If mainprog->jmpbuf is used by setjmp, then png_longjmp - cannot be used. - Changed "extern PNG_EXPORT" to "PNG_EXPORT" in png.h (Jan Nijtmans) - Changed "extern" to "PNG_EXTERN" in pngpriv.h (except for the 'extern "C" {') - -Version 1.5.0beta34 [July 12, 2010] - Put #ifndef PNG_EXTERN, #endif around the define PNG_EXTERN in pngpriv.h - -Version 1.5.0beta35 [July 24, 2010] - Removed some newly-added TAB characters. - Added -DNO_PNG_SNPRINTF to CFLAGS in scripts/makefile.dj2 - Moved the definition of png_snprintf() outside of the enclosing - #ifdef blocks in pngconf.h - -Version 1.5.0beta36 [July 29, 2010] - Patches by John Bowler: - Fixed point APIs are now supported throughout (no missing APIs). - Internal fixed point arithmetic support exists for all internal floating - point operations. - sCAL validates the floating point strings it is passed. - Safe, albeit rudimentary, Watcom support is provided by PNG_API_RULE==2 - Two new APIs exist to get the number of passes without turning on the - PNG_INTERLACE transform and to get the number of rows in the current - pass. - A new test program, pngvalid.c, validates the gamma code. - Errors in the 16-bit gamma correction (overflows) have been corrected. - cHRM chunk testing is done consistently (previously the floating point - API bypassed it, because the test really didn't work on FP, now the test - is performed on the actual values to be stored in the PNG file so it - works in the FP case too.) - Most floating point APIs now simply call the fixed point APIs after - converting the values to the fixed point form used in the PNG file. - The standard headers no longer include zlib.h, which is currently only - required for pngstruct.h and can therefore be internal. - Revised png_get_int_32 to undo the PNG two's complement representation of - negative numbers. - -Version 1.5.0beta37 [July 30, 2010] - Added a typecast in png_get_int_32() in png.h and pngrutil.h to avoid - a compiler warning. - Replaced oFFs 0,0 with oFFs -10,20 in pngtest.png - -Version 1.5.0beta38 [July 31, 2010] - Implemented remaining "_fixed" functions. - Corrected a number of recently introduced warnings mostly resulting from - safe but uncast assignments to shorter integers. Also added a zlib - VStudio release library project because the latest zlib Official Windows - build does not include such a thing. - Revised png_get_int_16() to be similar to png_get_int_32(). - Restored projects/visualc71. - -Version 1.5.0beta39 [August 2, 2010] - VisualC/GCC warning fixes, VisualC build fixes - The changes include support for function attributes in VC in addition to - those already present in GCC - necessary because without these some - warnings are unavoidable. Fixes include signed/unsigned fixes in - pngvalid and checks with gcc -Wall -Wextra -Wunused. - VC requires function attributes on function definitions as well as - declarations, PNG_FUNCTION has been added to enable this and the - relevant function definitions changed. - -Version 1.5.0beta40 [August 6, 2010] - Correct use of _WINDOWS_ in pngconf.h - Removed png_mem_ #defines; they are no longer used. - Added the sRGB chunk to pngtest.png - -Version 1.5.0beta41 [August 11, 2010] - Added the cHRM chunk to pngtest.png - Don't try to use version-script with cygwin/mingw. - Revised contrib/gregbook to work under cygwin/mingw. - -Version 1.5.0beta42 [August 18, 2010] - Add .dll.a to the list of extensions to be symlinked by Makefile.am (Yaakov) - Made all API functions that have const arguments and constant string - literal pointers declare them (John Bowler). - -Version 1.5.0beta43 [August 20, 2010] - Removed spurious tabs, shorten long lines (no source change) - Also added scripts/chkfmt to validate the format of all the files that can - reasonably be validated (it is suggested to run "make distclean" before - checking, because some machine generated files have long lines.) - Reformatted the CHANGES file to be more consistent throughout. - Made changes to address various issues identified by GCC, mostly - signed/unsigned and shortening problems on assignment but also a few - difficult to optimize (for GCC) loops. - Fixed non-GCC fixed point builds. In png.c a declaration was misplaced - in an earlier update. Fixed to declare the auto variables at the head. - Use cexcept.h in pngvalid.c. - -Version 1.5.0beta44 [August 24, 2010] - Updated CMakeLists.txt to use CMAKE_INSTALL_LIBDIR variable; useful for - installing libpng in /usr/lib64 (Funda Wang). - Revised CMakeLists.txt to put the man pages in share/man/man* not man/man* - Revised CMakeLists.txt to make symlinks instead of copies when installing. - Changed PNG_LIB_NAME from pngNN to libpngNN in CMakeLists.txt (Philip Lowman) - Implemented memory checks within pngvalid - Reformatted/rearranged pngvalid.c to assist use of progressive reader. - Check interlaced images in pngvalid - Clarified pngusr.h comments in pnglibconf.dfa - Simplified the pngvalid error-handling code now that cexcept.h is in place. - Implemented progressive reader in pngvalid.c for standard tests - Implemented progressive read in pngvalid.c gamma tests - Turn on progressive reader in pngvalid.c by default and tidy code. - -Version 1.5.0beta45 [August 26, 2010] - Added an explicit make step to projects/vstudio for pnglibconf.h - Also corrected zlib.vcxproj into which Visual Studio had introduced - what it calls an "authoring error". The change to make pnglibconf.h - simply copies the file; in the future it may actually generate the - file from scripts/pnglibconf.dfa as the other build systems do. - Changed pngvalid to work when floating point APIs are disabled - Renamed the prebuilt scripts/pnglibconf.h to scripts/pnglibconf.h.prebuilt - Supply default values for PNG_USER_PRIVATEBUILD and PNG_USER_DLLFNAME_POSTFIX - in pngpriv.h in case the user neglected to define them in their pngusr.h - -Version 1.5.0beta46 [August 28, 2010] - Added new private header files to libpng_sources in CMakeLists.txt - Added PNG_READ_16BIT, PNG_WRITE_16BIT, and PNG_16BIT options. - Added reference to scripts/pnglibconf.h.prebuilt in the visualc71 project. - -Version 1.5.0beta47 [September 11, 2010] - Fixed a number of problems with 64-bit compilation reported by Visual - Studio 2010 (John Bowler). - -Version 1.5.0beta48 [October 4, 2010] - Updated CMakeLists.txt (Philip Lowman). - Revised autogen.sh to recognize and use $AUTOCONF, $AUTOMAKE, $AUTOHEADER, - $AUTOPOINT, $ACLOCAL and $LIBTOOLIZE - Fixed problem with symbols creation in Makefile.am which was assuming that - all versions of ccp write to standard output by default (Martin Banky). The - bug was introduced in libpng-1.2.9beta5. - Removed unused mkinstalldirs. - -Version 1.5.0beta49 [October 8, 2010] - Undid Makefile.am revision of 1.5.0beta48. - -Version 1.5.0beta50 [October 14, 2010] - Revised Makefile.in to account for mkinstalldirs being removed. - Added some "(unsigned long)" typecasts in printf statements in pngvalid.c. - Suppressed a compiler warning in png_handle_sPLT(). - Check for out-of-range text compression mode in png_set_text(). - -Version 1.5.0beta51 [October 15, 2010] - Changed embedded dates to "(PENDING RELEASE) in beta releases (and future - rc releases) to minimize the difference between releases. - -Version 1.5.0beta52 [October 16, 2010] - Restored some of the embedded dates (in png.h, png.c, documentation, etc.) - -Version 1.5.0beta53 [October 18, 2010] - Updated INSTALL to mention using "make maintainer-clean" and to remove - obsolete statement about a custom ltmain.sh - Disabled "color-tests" by default in Makefile.am so it will work with - automake versions earlier than 1.11.1 - Use document name "libpng-manual.txt" instead of "libpng-<version>.txt" - to simplify version differences. - Removed obsolete remarks about setjmp handling from INSTALL. - Revised and renamed the typedef in png.h and png.c that was designed - to catch library and header mismatch. - -Version 1.5.0beta54 [November 10, 2010] - Require 48 bytes, not 64 bytes, for big_row_buf in overflow checks. - Used a consistent structure for the pngget.c functions. - -Version 1.5.0beta55 [November 21, 2010] - Revised png_get_uint_32, png_get_int_32, png_get_uint_16 (Cosmin) - Moved reading of file signature into png_read_sig (Cosmin) - Fixed atomicity of chunk header serialization (Cosmin) - Added test for io_state in pngtest.c (Cosmin) - Added "#!/bin/sh" at the top of contrib/pngminim/*/gather.sh scripts. - Changes to remove gcc warnings (John Bowler) - Certain optional gcc warning flags resulted in warnings in libpng code. - With these changes only -Wconversion and -Wcast-qual cannot be turned on. - Changes are trivial rearrangements of code. -Wconversion is not possible - for pngrutil.c (because of the widespread use of += et al on variables - smaller than (int) or (unsigned int)) and -Wcast-qual is not possible - with pngwio.c and pngwutil.c because the 'write' callback and zlib - compression both fail to declare their input buffers with 'const'. - -Version 1.5.0beta56 [December 7, 2010] - Added the private PNG_UNUSED() macro definition in pngpriv.h. - Added some commentary about PNG_EXPORT in png.h and pngconf.h - Revised PNG_EXPORT() macro and added PNG_EXPORTA() macro, with the - objective of simplifying and improving the cosmetic appearance of png.h. - Fixed some incorrect "=" macro names in pnglibconf.dfa - Included documentation of changes in 1.5.0 from 1.4.x in libpng-manual.txt - -Version 1.5.0beta57 [December 9, 2010] - Documented the pngvalid gamma error summary with additional comments and - print statements. - Improved missing symbol handling in checksym.awk; symbols missing in both - the old and new files can now be optionally ignored, treated as errors - or warnings. - Removed references to pngvcrd.c and pnggccrd.c from the vstudio project. - Updated "libpng14" to "libpng15" in the visualc71 project. - Enabled the strip16 tests in pngvalid.` - Don't display test results (except PASS/FAIL) when running "make test". - Instead put them in pngtest-log.txt - Added "--with-zprefix=<string>" to configure.ac - Updated the prebuilt configuration files to autoconf version 2.68 - -Version 1.5.0beta58 [December 19, 2010] - Fixed interlace image handling and add test cases (John Bowler) - Fixed the clean rule in Makefile.am to remove pngtest-log.txt - Made minor changes to work around warnings in gcc 3.4 - -Version 1.5.0rc01 [December 27, 2010] - No changes. - -Version 1.5.0rc02 [December 27, 2010] - Eliminated references to the scripts/*.def files in project/visualc71. - -Version 1.5.0rc03 [December 28, 2010] - Eliminated scripts/*.def and revised Makefile.am accordingly - -Version 1.5.0rc04 [December 29, 2010] - Fixed bug in background transformation handling in pngrtran.c (it was - looking for the flag in png_ptr->transformations instead of in - png_ptr->flags) (David Raymond). - -Version 1.5.0rc05 [December 31, 2010] - Fixed typo in a comment in CMakeLists.txt (libpng14 => libpng15) (Cosmin) - -Version 1.5.0rc06 [January 4, 2011] - Changed the new configure option "zprefix=string" to "zlib-prefix=string" - -Version 1.5.0rc07 [January 4, 2011] - Updated copyright year. - -Version 1.5.0 [January 6, 2011] - No changes. - -version 1.5.1beta01 [January 8, 2011] - Added description of png_set_crc_action() to the manual. - Added a note in the manual that the type of the iCCP profile was changed - from png_charpp to png_bytepp in png_get_iCCP(). This change happened - in version 1.5.0beta36 but is not noted in the CHANGES. Similarly, - it was changed from png_charpp to png_const_bytepp in png_set_iCCP(). - Ensure that png_rgb_to_gray ignores palette mapped images, if libpng - internally happens to call it with one, and fixed a failure to handle - palette mapped images correctly. This fixes CVE-2690. - -Version 1.5.1beta02 [January 14, 2011] - Fixed a bug in handling of interlaced images (bero at arklinux.org). - Updated CMakeLists.txt (Clifford Yapp) - -Version 1.5.1beta03 [January 14, 2011] - Fixed typecasting of some png_debug() statements (Cosmin) - -Version 1.5.1beta04 [January 16, 2011] - Updated documentation of png_set|get_tRNS() (Thomas Klausner). - Mentioned in the documentation that applications must #include "zlib.h" - if they need access to anything in zlib.h, and that a number of - macros such as png_memset() are no longer accessible by applications. - Corrected pngvalid gamma test "sample" function to access all of the color - samples of each pixel, instead of sampling the red channel three times. - Prefixed variable names index, div, exp, gamma with "png_" to avoid "shadow" - warnings, and (mistakenly) changed png_exp() to exp(). - -Version 1.5.1beta05 [January 16, 2011] - Changed variable names png_index, png_div, png_exp, and png_gamma to - char_index, divisor, exp_b10, and gamma_val, respectively, and - changed exp() back to png_exp(). - -Version 1.5.1beta06 [January 20, 2011] - Prevent png_push_crc_skip() from hanging while reading an unknown chunk - or an over-large compressed zTXt chunk with the progressive reader. - Eliminated more GCC "shadow" warnings. - Revised png_fixed() in png.c to avoid compiler warning about reaching the - end without returning anything. - -Version 1.5.1beta07 [January 22, 2011] - In the manual, describe the png_get_IHDR() arguments in the correct order. - Added const_png_structp and const_png_infop types, and used them in - prototypes for most png_get_*() functions. - -Version 1.5.1beta08 [January 23, 2011] - Added png_get_io_chunk_type() and deprecated png_get_io_chunk_name() - Added synopses for the IO_STATE functions and other missing synopses - to the manual. Removed the synopses from libpngpf.3 because they - were out of date and no longer useful. Better information can be - obtained by reading the prototypes and comments in pngpriv.h - Attempted to fix cpp on Solaris with S. Studio 12 cc, fix build - Added a make macro DFNCPP that is a CPP that will accept the tokens in - a .dfn file and adds configure stuff to test for such a CPP. ./configure - should fail if one is not available. - Corrected const_png_ in png.h to png_const_ to avoid polluting the namespace. - Added png_get_current_row_number and png_get_current_pass_number for the - benefit of the user transform callback. - Added png_process_data_pause and png_process_data_skip for the benefit of - progressive readers that need to stop data processing or want to optimize - skipping of unread data (e.g., if the reader marks a chunk to be skipped.) - -Version 1.5.1beta09 [January 24, 2011] - Enhanced pngvalid, corrected an error in gray_to_rgb, corrected doc error. - pngvalid contains tests of transforms, which tests are currently disabled - because they are incompletely tested. gray_to_rgb was failing to expand - the bit depth for smaller bit depth images; this seems to be a long - standing error and resulted, apparently, in invalid output - (CVE-2011-0408, CERT VU#643140). The documentation did not accurately - describe what libpng really does when converting RGB to gray. - -Version 1.5.1beta10 [January 27, 2010] - Fixed incorrect examples of callback prototypes in the manual, that were - introduced in libpng-1.0.0. - In addition the order of the png_get_uint macros with respect to the - relevant function definitions has been reversed. This helps the - preprocessing of the symbol files be more robust. Furthermore, the - symbol file preprocessing now uses -DPNG_NO_USE_READ_MACROS even when - the library may actually be built with PNG_USE_READ_MACROS; this stops - the read macros interfering with the symbol file format. - Made the manual, synopses, and function prototypes use the function - argument names file_gamma, int_file_gamma, and srgb_intent consistently. - -Version 1.5.1beta11 [January 28, 2011] - Changed PNG_UNUSED from "param=param;" to "{if(param){}}". - Corrected local variable type in new API png_process_data_skip() - The type was self-evidently incorrect but only causes problems on 64-bit - architectures. - Added transform tests to pngvalid and simplified the arguments. - -Version 1.5.1rc01 [January 29, 2011] - No changes. - -Version 1.5.1rc02 [January 31, 2011] - Added a request in the manual that applications do not use "png_" or - "PNG_" to begin any of their own symbols. - Changed PNG_UNUSED to "(void)param;" and updated the commentary in pngpriv.h - -Version 1.5.1 [February 3, 2011] - No changes. - -Version 1.5.2beta01 [February 13, 2011] - More -Wshadow fixes for older gcc compilers. Older gcc versions apparently - check formal parameters names in function declarations (as well as - definitions) to see if they match a name in the global namespace. - Revised PNG_EXPORTA macro to not use an empty parameter, to accommodate the - old VisualC++ preprocessor. - Turned on interlace handling in png_read_png(). - Fixed gcc pendantic warnings. - Handle longjmp in Cygwin. - Fixed png_get_current_row_number() in the interlaced case. - Cleaned up ALPHA flags and transformations. - Implemented expansion to 16 bits. - -Version 1.5.2beta02 [February 19, 2011] - Fixed mistake in the descriptions of user read_transform and write_transform - function prototypes in the manual. The row_info struct is png_row_infop. - Reverted png_get_current_row_number() to previous (1.5.2beta01) behavior. - Corrected png_get_current_row_number documentation - Fixed the read/write row callback documentation. - This documents the current behavior, where the callback is called after - every row with information pertaining to the next row. - -Version 1.5.2beta03 [March 3, 2011] - Fixed scripts/makefile.vcwin32 - Updated contrib/pngsuite/README to add the word "modify". - Define PNG_ALLOCATED to blank when _MSC_VER<1300. - -Version 1.5.2rc01 [March 19, 2011] - Define remaining attributes to blank when MSC_VER<1300. - ifdef out mask arrays in pngread.c when interlacing is not supported. - -Version 1.5.2rc02 [March 22, 2011] - Added a hint to try CPP=/bin/cpp if "cpp -E" fails in scripts/pnglibconf.mak - and in contrib/pngminim/*/makefile, eg., on SunOS 5.10, and removed "strip" - from the makefiles. - Fixed a bug (present since libpng-1.0.7) that makes png_handle_sPLT() fail - to compile when PNG_NO_POINTER_INDEXING is defined (Chubanov Kirill) - -Version 1.5.2rc03 [March 24, 2011] - Don't include standard header files in png.h while building the symbol table, - to avoid cpp failure on SunOS (introduced PNG_BUILDING_SYMBOL_TABLE macro). - -Version 1.5.2 [March 31, 2011] - No changes. - -Version 1.5.3beta01 [April 1, 2011] - Re-initialize the zlib compressor before compressing non-IDAT chunks. - Added API functions (png_set_text_compression_level() and four others) to - set parameters for zlib compression of non-IDAT chunks. - -Version 1.5.3beta02 [April 3, 2011] - Updated scripts/symbols.def with new API functions. - Only compile the new zlib re-initializing code when text or iCCP is - supported, using PNG_WRITE_COMPRESSED_TEXT_SUPPORTED macro. - Improved the optimization of the zlib CMF byte (see libpng-1.2.6beta03). - Optimize the zlib CMF byte in non-IDAT compressed chunks - -Version 1.5.3beta03 [April 16, 2011] - Fixed gcc -ansi -pedantic compile. A strict ANSI system does not have - snprintf, and the "__STRICT_ANSI__" detects that condition more reliably - than __STDC__ (John Bowler). - Removed the PNG_PTR_NORETURN attribute because it too dangerous. It tells - the compiler that a user supplied callback (the error handler) does not - return, yet there is no guarantee in practice that the application code - will correctly implement the error handler because the compiler only - issues a warning if there is a mistake (John Bowler). - Removed the no-longer-used PNG_DEPSTRUCT macro. - Updated the zlib version to 1.2.5 in the VStudio project. - Fixed 64-bit builds where png_uint_32 is smaller than png_size_t in - pngwutil.c (John Bowler). - Fixed bug with stripping the filler or alpha channel when writing, that - was introduced in libpng-1.5.2beta01 (bug report by Andrew Church). - -Version 1.5.3beta04 [April 27, 2011] - Updated pngtest.png with the new zlib CMF optimization. - Cleaned up conditional compilation code and of background/gamma handling - Internal changes only except a new option to avoid compiling the - png_build_grayscale_palette API (which is not used at all internally.) - The main change is to move the transform tests (READ_TRANSFORMS, - WRITE_TRANSFORMS) up one level to the caller of the APIs. This avoids - calls to spurious functions if all transforms are disabled and slightly - simplifies those functions. Pngvalid modified to handle this. - A minor change is to stop the strip_16 and expand_16 interfaces from - disabling each other; this allows the future alpha premultiplication - code to use 16-bit intermediate values while still producing 8-bit output. - png_do_background and png_do_gamma have been simplified to take a single - pointer to the png_struct rather than pointers to every item required - from the png_struct. This makes no practical difference to the internal - code. - A serious bug in the pngvalid internal routine 'standard_display_init' has - been fixed - this failed to initialize the red channel and accidentally - initialized the alpha channel twice. - Changed png_struct jmp_buf member name from png_jmpbuf to tmp_jmpbuf to - avoid a possible clash with the png_jmpbuf macro on some platforms. - -Version 1.5.3beta05 [May 6, 2011] - Added the "_POSIX_SOURCE" feature test macro to ensure libpng sees the - correct API. _POSIX_SOURCE is defined in pngpriv.h, pngtest.c and - pngvalid.c to ensure that POSIX conformant systems disable non-POSIX APIs. - Removed png_snprintf and added formatted warning messages. This change adds - internal APIs to allow png_warning messages to have parameters without - requiring the host OS to implement snprintf. As a side effect the - dependency of the tIME-supporting RFC1132 code on stdio is removed and - PNG_NO_WARNINGS does actually work now. - Pass "" instead of '\0' to png_default_error() in png_err(). This mistake - was introduced in libpng-1.2.20beta01. This fixes CVE-2011-2691. - Added PNG_WRITE_OPTIMIZE_CMF_SUPPORTED macro to make the zlib "CMF" byte - optimization configureable. - IDAT compression failed if preceded by a compressed text chunk (bug - introduced in libpng-1.5.3beta01-02). This was because the attempt to - reset the zlib stream in png_write_IDAT happened after the first IDAT - chunk had been deflated - much too late. In this change internal - functions were added to claim/release the z_stream and, hopefully, make - the code more robust. Also deflateEnd checking is added - previously - libpng would ignore an error at the end of the stream. - -Version 1.5.3beta06 [May 8, 2011] - Removed the -D_ALL_SOURCE from definitions for AIX in CMakeLists.txt - Implemented premultiplied alpha support: png_set_alpha_mode API - -Version 1.5.3beta07 [May 11, 2011] - Added expand_16 support to the high level interface. - Added named value and 'flag' gamma support to png_set_gamma. Made a minor - change from the previous (unreleased) ABI/API to hide the exact value used - for Macs - it's not a good idea to embed this in the ABI! - Moved macro definitions for PNG_HAVE_IHDR, PNG_HAVE_PLTE, and PNG_AFTER_IDAT - from pngpriv.h to png.h because they must be visible to applications - that call png_set_unknown_chunks(). - Check for up->location !PNG_AFTER_IDAT when writing unknown chunks - before IDAT. - -Version 1.5.3beta08 [May 16, 2011] - Improved "pngvalid --speed" to exclude more of pngvalid from the time. - Documented png_set_alpha_mode(), other changes in libpng.3/libpng-manual.txt - The cHRM chunk now sets the defaults for png_set_rgb_to_gray() (when negative - parameters are supplied by the caller), while in the absence of cHRM - sRGB/Rec 709 values are still used. This introduced a divide-by-zero - bug in png_handle_cHRM(). - The bKGD chunk no longer overwrites the background value set by - png_set_background(), allowing the latter to be used before the file - header is read. It never performed any useful function to override - the default anyway. - Added memory overwrite and palette image checks to pngvalid.c - Previously palette image code was poorly checked. Since the transformation - code has a special palette path in most cases this was a severe weakness. - Minor cleanup and some extra checking in pngrutil.c and pngrtran.c. When - expanding an indexed image, always expand to RGBA if transparency is - present. - -Version 1.5.3beta09 [May 17, 2011] - Reversed earlier 1.5.3 change of transformation order; move png_expand_16 - back where it was. The change doesn't work because it requires 16-bit - gamma tables when the code only generates 8-bit ones. This fails - silently; the libpng code just doesn't do any gamma correction. Moving - the tests back leaves the old, inaccurate, 8-bit gamma calculations, but - these are clearly better than none! - -Version 1.5.3beta10 [May 20, 2011] - - png_set_background() and png_expand_16() did not work together correctly. - This problem is present in 1.5.2; if png_set_background is called with - need_expand false and the matching 16 bit color libpng erroneously just - treats it as an 8-bit color because of where png_do_expand_16 is in the - transform list. This simple fix reduces the supplied colour to 8-bits, - so it gets smashed, but this is better than the current behavior. - Added tests for expand16, more fixes for palette image tests to pngvalid. - Corrects the code for palette image tests and disables attempts to - validate palette colors. - -Version 1.5.3rc01 [June 3, 2011] - No changes. - -Version 1.5.3rc02 [June 8, 2011] - Fixed uninitialized memory read in png_format_buffer() (Bug report by - Frank Busse, CVE-2011-2501, related to CVE-2004-0421). - -Version 1.5.3beta11 [June 11, 2011] - Fixed png_handle_sCAL which is broken in 1.5. This fixes CVE 2011-2692. - Added sCAL to pngtest.png - Revised documentation about png_set_user_limits() to say that it also affects - png writing. - Revised handling of png_set_user_limits() so that it can increase the - limit beyond the PNG_USER_WIDTH|HEIGHT_MAX; previously it could only - reduce it. - Make the 16-to-8 scaling accurate. Dividing by 256 with no rounding is - wrong (high by one) 25% of the time. Dividing by 257 with rounding is - wrong in 128 out of 65536 cases. Getting the right answer all the time - without division is easy. - Added "_SUPPORTED" to the PNG_WRITE_CUSTOMIZE_ZTXT_COMPRESSION macro. - Added projects/owatcom, an IDE project for OpenWatcom to replace - scripts/makefile.watcom. This project works with OpenWatcom 1.9. The - IDE autogenerates appropriate makefiles (libpng.mk) for batch processing. - The project is configurable, unlike the Visual Studio project, so long - as the developer has an awk. - Changed png_set_gAMA to limit the gamma value range so that the inverse - of the stored value cannot overflow the fixed point representation, - and changed other things OpenWatcom warns about. - Revised pngvalid.c to test PNG_ALPHA_MODE_SUPPORTED correctly. This allows - pngvalid to build when ALPHA_MODE is not supported, which is required if - it is to build on libpng 1.4. - Removed string/memory macros that are no longer used and are not - necessarily fully supportable, particularly png_strncpy and png_snprintf. - Added log option to pngvalid.c and attempted to improve gamma messages. - -Version 1.5.3 [omitted] - People found the presence of a beta release following an rc release - to be confusing; therefore we bump the version to libpng-1.5.4beta01 - and there will be no libpng-1.5.3 release. - -Version 1.5.4beta01 [June 14, 2011] - Made it possible to undefine PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED - to get the same (inaccurate) output as libpng-1.5.2 and earlier. - Moved definitions of PNG_HAVE_IHDR, PNG_AFTER_IDAT, and PNG_HAVE_PLTE - outside of an unknown-chunk block in png.h because they are also - needed for other uses. - -Version 1.5.4beta02 [June 14, 2011] - Fixed and clarified LEGACY 16-to-8 scaling code. - Added png_set_chop_16() API, to match inaccurate results from previous - libpng versions. - Removed the ACCURATE and LEGACY options (they are no longer useable) - Use the old scaling method for background if png_set_chop_16() was - called. - Made png_set_chop_16() API removeable by disabling PNG_CHOP_16_TO_8_SUPPORTED - -Version 1.5.4beta03 [June 15, 2011] - Fixed a problem in png_do_expand_palette() exposed by optimization in - 1.5.3beta06 - Also removed a spurious and confusing "trans" member ("trans") from png_info. - The palette expand optimization prevented expansion to an intermediate RGBA - form if tRNS was present but alpha was marked to be stripped; this exposed - a check for tRNS in png_do_expand_palette() which is inconsistent with the - code elsewhere in libpng. - Correction to the expand_16 code; removed extra instance of - png_set_scale_16_to_8 from pngpriv.h - -Version 1.5.4beta04 [June 16, 2011] - Added a missing "#ifdef PNG_READ_BACKGROUND_SUPPORTED/#endif" in pngrtran.c - Added PNG_TRANSFORM_CHOP_16 to the high-level read transforms. - Made PNG_READ_16_TO_8_ACCURATE_SCALE configurable again. If this is - not enabled, png_set_strip_16() and png_do_scale_16_to_8() aren't built. - Revised contrib/visupng, gregbook, and pngminim to demonstrate chop_16_to_8 - -Version 1.5.4beta05 [June 16, 2011] - Renamed png_set_strip_16() to png_set_scale_16() and renamed - png_set_chop_16() to png_set_strip(16) in an attempt to minimize the - behavior changes between libpng14 and libpng15. - -Version 1.5.4beta06 [June 18, 2011] - Fixed new bug that was causing both strip_16 and scale_16 to be applied. - -Version 1.5.4beta07 [June 19, 2011] - Fixed pngvalid, simplified macros, added checking for 0 in sCAL. - The ACCURATE scale macro is no longer defined in 1.5 - call the - png_scale_16_to_8 API. Made sure that PNG_READ_16_TO_8 is still defined - if the png_strip_16_to_8 API is present. png_check_fp_number now - maintains some state so that positive, negative and zero values are - identified. sCAL uses these to be strictly spec conformant. - -Version 1.5.4beta08 [June 23, 2011] - Fixed pngvalid if ACCURATE_SCALE is defined. - Updated scripts/pnglibconf.h.prebuilt. - -Version 1.5.4rc01 [June 30, 2011] - Define PNG_ALLOCATED to "restrict" only if MSC_VER >= 1400. - -Version 1.5.4 [July 7, 2011] - No changes. - -Version 1.5.5beta01 [July 13, 2011] - Fixed some typos and made other minor changes in the manual. - Updated contrib/pngminus/makefile.std (Samuli Souminen) - -Version 1.5.5beta02 [July 14, 2011] - Revised Makefile.am and Makefile.in to look in the right directory for - pnglibconf.h.prebuilt - -Version 1.5.5beta03 [July 27, 2011] - Enabled compilation with g++ compiler. This compiler does not recognize - the file extension, so it always compiles with C++ rules. Made minor - changes to pngrutil.c to cast results where C++ expects it but C does not. - Minor editing of libpng.3 and libpng-manual.txt. - -Version 1.5.5beta04 [July 29, 2011] - Revised CMakeLists.txt (Clifford Yapp) - Updated commentary about the png_rgb_to_gray() default coefficients - in the manual and in pngrtran.c - -Version 1.5.5beta05 [August 17, 2011] - Prevent unexpected API exports from non-libpng DLLs on Windows. The "_DLL" - is removed from the test of whether a DLL is being built (this erroneously - caused the libpng APIs to be marked as DLL exports in static builds under - Microsoft Visual Studio). Almost all of the libpng building configuration - is moved from pngconf.h to pngpriv.h, but PNG_DLL_EXPORT remains in - pngconf.h, though, so that it is colocated with the import definition (it - is no longer used anywhere in the installed headers). The VStudio project - definitions have been cleaned up: "_USRDLL" has been removed from the - static library builds (this was incorrect), and PNG_USE_DLL has been added - to pngvalid to test the functionality (pngtest does not supply it, - deliberately). The spurious "_EXPORTS" has been removed from the - libpng build (all these errors were a result of copy/paste between project - configurations.) - Added new types and internal functions for CIE RGB end point handling to - pngpriv.h (functions yet to be implemented). - -Version 1.5.5beta06 [August 26, 2011] - Ensure the CMAKE_LIBRARY_OUTPUT_DIRECTORY is set in CMakeLists.txt - (Clifford Yap) - Fixes to rgb_to_gray and cHRM XYZ APIs (John Bowler): - The rgb_to_gray code had errors when combined with gamma correction. - Some pixels were treated as true grey when they weren't and such pixels - and true grey ones were not gamma corrected (the original value of the - red component was used instead). APIs to get and set cHRM using color - space end points have been added and the rgb_to_gray code that defaults - based on cHRM, and the divide-by-zero bug in png_handle_cHRM (CERT - VU#477046, CVE-2011-3328, introduced in 1.5.4) have been corrected. - A considerable number of tests has been added to pngvalid for the - rgb_to_gray transform. - Arithmetic errors in rgb_to_gray whereby the calculated gray value was - truncated to the bit depth rather than rounded have been fixed except in - the 8-bit non-gamma-corrected case (where consistency seems more important - than correctness.) The code still has considerable inaccuracies in the - 8-bit case because 8-bit linear arithmetic is used. - -Version 1.5.5beta07 [September 7, 2011] - Added "$(ARCH)" option to makefile.darwin - Added SunOS support to configure.ac and Makefile.am - Changed png_chunk_benign_error() to png_warning() in png.c, in - png_XYZ_from_xy_checked(). - -Version 1.5.5beta08 [September 10, 2011] - Fixed 64-bit compilation errors (gcc). The errors fixed relate - to conditions where types that are 32 bits in the GCC 32-bit - world (uLong and png_size_t) become 64 bits in the 64-bit - world. This produces potential truncation errors which the - compiler correctly flags. - Relocated new HAVE_SOLARIS_LD definition in configure.ac - Constant changes for 64-bit compatibility (removal of L suffixes). The - 16-bit cases still use "L" as we don't have a 16-bit test system. - -Version 1.5.5rc01 [September 15, 2011] - Removed "L" suffixes in pngpriv.h - -Version 1.5.5 [September 22, 2011] - No changes. - -Version 1.5.6beta01 [September 22, 2011] - Fixed some 64-bit type conversion warnings in pngrtran.c - Moved row_info from png_struct to a local variable. - The various interlace mask arrays have been made into arrays of - bytes and made PNG_CONST and static (previously some arrays were - marked PNG_CONST and some weren't). - Additional checks have been added to the transform code to validate the - pixel depths after the transforms on both read and write. - Removed some redundant code from pngwrite.c, in png_destroy_write_struct(). - Changed chunk reading/writing code to use png_uint_32 instead of png_byte[4]. - This removes the need to allocate temporary strings for chunk names on - the stack in the read/write code. Unknown chunk handling still uses the - string form because this is exposed in the API. - -Version 1.5.6beta02 [September 26, 2011] - Added a note in the manual the png_read_update_info() must be called only - once with a particular info_ptr. - Fixed a typo in the definition of the new PNG_STRING_FROM_CHUNK(s,c) macro. - -Version 1.5.6beta03 [September 28, 2011] - Revised test-pngtest.sh to report FAIL when pngtest fails. - Added "--strict" option to pngtest, to report FAIL when the failure is - only because the resulting valid files are different. - Revised CMakeLists.txt to work with mingw and removed some material from - CMakeLists.txt that is no longer useful in libpng-1.5. - -Version 1.5.6beta04 [October 5, 2011] - Fixed typo in Makefile.in and Makefile.am ("-M Wl" should be "-M -Wl")." - -Version 1.5.6beta05 [October 12, 2011] - Speed up png_combine_row() for interlaced images. This reduces the generality - of the code, allowing it to be optimized for Adam7 interlace. The masks - passed to png_combine_row() are now generated internally, avoiding - some code duplication and localizing the interlace handling somewhat. - Align png_struct::row_buf - previously it was always unaligned, caused by - a bug in the code that attempted to align it; the code needs to subtract - one from the pointer to take account of the filter byte prepended to - each row. - Optimized png_combine_row() when rows are aligned. This gains a small - percentage for 16-bit and 32-bit pixels in the typical case where the - output row buffers are appropriately aligned. The optimization was not - previously possible because the png_struct buffer was always misaligned. - Fixed bug in png_write_chunk_header() debug print, introduced in 1.5.6beta01. - -Version 1.5.6beta06 [October 17, 2011] - Removed two redundant tests for unitialized row. - Fixed a relatively harmless memory overwrite in compressed text writing - with a 1 byte zlib buffer. - Add ability to call png_read_update_info multiple times to pngvalid.c. - Fixes for multiple calls to png_read_update_info. These fixes attend to - most of the errors revealed in pngvalid, however doing the gamma work - twice results in inaccuracies that can't be easily fixed. There is now - a warning in the code if this is going to happen. - Turned on multiple png_read_update_info in pngvalid transform tests. - Prevent libpng from overwriting unused bits at the end of the image when - it is not byte aligned, while reading. Prior to libpng-1.5.6 libpng would - overwrite the partial byte at the end of each row if the row width was not - an exact multiple of 8 bits and the image is not interlaced. - -Version 1.5.6beta07 [October 21, 2011] - Made png_ptr->prev_row an aligned pointer into png_ptr->big_prev_row - (Mans Rullgard). - -Version 1.5.6rc01 [October 26, 2011] - Changed misleading "Missing PLTE before cHRM" warning to "Out of place cHRM" - -Version 1.5.6rc02 [October 27, 2011] - Added LSR() macro to defend against buggy compilers that evaluate non-taken - code branches and complain about out-of-range shifts. - -Version 1.5.6rc03 [October 28, 2011] - Renamed the LSR() macro to PNG_LSR() and added PNG_LSL() macro. - Fixed compiler warnings with Intel and MSYS compilers. The logical shift - fix for Microsoft Visual C is required by other compilers, so this - enables that fix for all compilers when using compile-time constants. - Under MSYS 'byte' is a name declared in a system header file, so we - changed the name of a local variable to avoid the warnings that result. - Added #define PNG_ALIGN_TYPE PNG_ALIGN_NONE to contrib/pngminim/*/pngusr.h - -Version 1.5.6 [November 3, 2011] - No changes. - -Version 1.5.7beta01 [November 4, 2011] - Added support for ARM processor, when decoding all PNG up-filtered rows - and any other-filtered rows with 3 or 4 bytes per pixel (Mans Rullgard). - Fixed bug in pngvalid on early allocation failure; fixed type cast in - pngmem.c; pngvalid would attempt to call png_error() if the allocation - of a png_struct or png_info failed. This would probably have led to a - crash. The pngmem.c implementation of png_malloc() included a cast - to png_size_t which would fail on large allocations on 16-bit systems. - Fix for the preprocessor of the Intel C compiler. The preprocessor - splits adjacent @ signs with a space; this changes the concatentation - token from @-@-@ to PNG_JOIN; that should work with all compiler - preprocessors. - Paeth filter speed improvements from work by Siarhei Siamashka. This - changes the 'Paeth' reconstruction function to improve the GCC code - generation on x86. The changes are only part of the suggested ones; - just the changes that definitely improve speed and remain simple. - The changes also slightly increase the clarity of the code. - -Version 1.5.7beta02 [November 11, 2011] - Check compression_type parameter in png_get_iCCP and remove spurious - casts. The compression_type parameter is always assigned to, so must - be non-NULL. The cast of the profile length potentially truncated the - value unnecessarily on a 16-bit int system, so the cast of the (byte) - compression type to (int) is specified by ANSI-C anyway. - Fixed FP division by zero in pngvalid.c; the 'test_pixel' code left - the sBIT fields in the test pixel as 0, which resulted in a floating - point division by zero which was irrelevant but causes systems where - FP exceptions cause a crash. Added code to pngvalid to turn on FP - exceptions if the appropriate glibc support is there to ensure this is - tested in the future. - Updated scripts/pnglibconf.mak and scripts/makefile.std to handle the - new PNG_JOIN macro. - Added versioning to pnglibconf.h comments. - Simplified read/write API initial version; basic read/write tested on - a variety of images, limited documentation (in the header file.) - Installed more accurate linear to sRGB conversion tables. The slightly - modified tables reduce the number of 16-bit values that - convert to an off-by-one 8-bit value. The "makesRGB.c" code that was used - to generate the tables is now in a contrib/sRGBtables sub-directory. - -Version 1.5.7beta03 [November 17, 2011] - Removed PNG_CONST from the sRGB table declarations in pngpriv.h and png.c - Added run-time detection of NEON support. - Added contrib/libtests; includes simplified API test and timing test and - a color conversion utility for rapid checking of failed 'pngstest' results. - Multiple transform bug fixes plus a work-round for double gamma correction. - libpng does not support more than one transform that requires linear data - at once - if this is tried typically the results is double gamma - correction. Since the simplified APIs can need rgb to gray combined with - a compose operation it is necessary to do one of these outside the main - libpng transform code. This check-in also contains fixes to various bugs - in the simplified APIs themselves and to some bugs in compose and rgb to - gray (on palette) itself. - Fixes for C++ compilation using g++ When libpng source is compiled - using g++. The compiler imposes C++ rules on the C source; thus it - is desireable to make the source work with either C or C++ rules - without throwing away useful error information. This change adds - png_voidcast to allow C semantic (void*) cases or the corresponding - C++ static_cast operation, as appropriate. - Added --noexecstack to assembler file compilation. GCC does not set - this on assembler compilation, even though it does on C compilation. - This creates security issues if assembler code is enabled; the - work-around is to set it by default in the flags for $(CCAS) - Work around compilers that don't support declaration of const data. Some - compilers fault 'extern const' data declarations (because the data is - not initialized); this turns on const-ness only for compilers where - this is known to work. - -Version 1.5.7beta04 [November 17, 2011] - Since the gcc driver does not recognize the --noexecstack flag, we must - use the -Wa prefix to have it passed through to the assembler. - Also removed a duplicate setting of this flag. - Added files that were omitted from the libpng-1.5.7beta03 zip distribution. - -Version 1.5.7beta05 [November 25, 2011] - Removed "zTXt" from warning in generic chunk decompression function. - Validate time settings passed to png_set_tIME() and png_convert_to_rfc1123() - (Frank Busse). Note: This prevented CVE-2015-7981 from affecting - libpng-1.5.7 and later. - Added MINGW support to CMakeLists.txt - Reject invalid compression flag or method when reading the iTXt chunk. - Backed out 'simplified' API changes. The API seems too complex and there - is a lack of consensus or enthusiasm for the proposals. The API also - reveals significant bugs inside libpng (double gamma correction and the - known bug of being unable to retrieve a corrected palette). It seems - better to wait until the bugs, at least, are corrected. - Moved pngvalid.c into contrib/libtests - Rebuilt Makefile.in, configure, etc., with autoconf-2.68 - -Version 1.5.7rc01 [December 1, 2011] - Replaced an "#if" with "#ifdef" in pngrtran.c - Revised #if PNG_DO_BC block in png.c (use #ifdef and add #else) - -Version 1.5.7rc02 [December 5, 2011] - Revised project files and contrib/pngvalid/pngvalid.c to account for - the relocation of pngvalid into contrib/libtests. - Revised pngconf.h to use " __declspec(restrict)" only when MSC_VER >= 1400, - as in libpng-1.5.4. - Put CRLF line endings in the owatcom project files. - -Version 1.5.7rc03 [December 7, 2011] - Updated CMakeLists.txt to account for the relocation of pngvalid.c - -Version 1.5.7 [December 15, 2011] - Minor fixes to pngvalid.c for gcc 4.6.2 compatibility to remove warnings - reported by earlier versions. - Fixed minor memset/sizeof errors in pngvalid.c. - -Version 1.6.0beta01 [December 15, 2011] - Removed machine-generated configure files from the GIT repository (they will - continue to appear in the tarball distributions and in the libpng15 and - earlier GIT branches). - Restored the new 'simplified' API, which was started in libpng-1.5.7beta02 - but later deleted from libpng-1.5.7beta05. - Added example programs for the new 'simplified' API. - Added ANSI-C (C90) headers and require them, and take advantage of the - change. Also fixed some of the projects/* and contrib/* files that needed - updates for libpng16 and the move of pngvalid.c. - With this change the required ANSI-C header files are assumed to exist: the - implementation must provide float.h, limits.h, stdarg.h and stddef.h and - libpng relies on limits.h and stddef.h existing and behaving as defined - (the other two required headers aren't used). Non-ANSI systems that don't - have stddef.h or limits.h will have to provide an appropriate fake - containing the relevant types and #defines. - Dropped support for 16-bit platforms. The use of FAR/far has been eliminated - and the definition of png_alloc_size_t is now controlled by a flag so - that 'small size_t' systems can select it if necessary. Libpng 1.6 may - not currently work on such systems -- it seems likely that it will - ask 'malloc' for more than 65535 bytes with any image that has a - sufficiently large row size (rather than simply failing to read such - images). - New tools directory containing tools used to generate libpng code. - Fixed race conditions in parallel make builds. With higher degrees of - parallelism during 'make' the use of the same temporary file names such - as 'dfn*' can result in a race where a temporary file from one arm of the - build is deleted or overwritten in another arm. This changes the - temporary files for suffix rules to always use $* and ensures that the - non-suffix rules use unique file names. - -Version 1.6.0beta02 [December 21, 2011] - Correct configure builds where build and source directories are separate. - The include path of 'config.h' was erroneously made relative in pngvalid.c - in libpng 1.5.7. - -Version 1.6.0beta03 [December 22, 2011] - Start-up code size improvements, error handler flexibility. These changes - alter how the tricky allocation of the initial png_struct and png_info - structures are handled. png_info is now handled in pretty much the same - way as everything else, except that the allocations handle NULL return - silently. png_struct is changed in a similar way on allocation and on - deallocation a 'safety' error handler is put in place (which should never - be required). The error handler itself is changed to permit mismatches - in the application and libpng error buffer size; however, this means a - silent change to the API to return the jmp_buf if the size doesn't match - the size from the libpng compilation; libpng now allocates the memory and - this may fail. Overall these changes result in slight code size - reductions; however, this is a reduction in code that is always executed - so is particularly valuable. Overall on a 64-bit system the libpng DLL - decreases in code size by 1733 bytes. pngerror.o increases in size by - about 465 bytes because of the new functionality. - Added png_convert_to_rfc1123_buffer() and deprecated png_convert_to_rfc1123() - to avoid including a spurious buffer in the png_struct. - -Version 1.6.0beta04 [December 30, 2011] - Regenerated configure scripts with automake-1.11.2 - Eliminated png_info_destroy(). It is now used only in png.c and only calls - one other internal function and memset(). - Enabled png_get_sCAL_fixed() if floating point APIs are enabled. Previously - it was disabled whenever internal fixed point arithmetic was selected, - which meant it didn't exist even on systems where FP was available but not - preferred. - Added pngvalid.c compile time checks for const APIs. - Implemented 'restrict' for png_info and png_struct. Because of the way - libpng works both png_info and png_struct are always accessed via a - single pointer. This means adding C99 'restrict' to the pointer gives - the compiler some opportunity to optimize the code. This change allows - that. - Moved AC_MSG_CHECKING([if libraries can be versioned]) later to the proper - location in configure.ac (Gilles Espinasse). - Changed png_memcpy to C assignment where appropriate. Changed all those - uses of png_memcpy that were doing a simple assignment to assignments - (all those cases where the thing being copied is a non-array C L-value). - Added some error checking to png_set_*() routines. - Removed the reference to the non-exported function png_memcpy() from - example.c. - Fixed the Visual C 64-bit build - it requires jmp_buf to be aligned, but - it had become misaligned. - Revised contrib/pngminus/pnm2png.c to avoid warnings when png_uint_32 - and unsigned long are of different sizes. - -Version 1.6.0beta05 [January 15, 2012] - Updated manual with description of the simplified API (copied from png.h) - Fix bug in pngerror.c: some long warnings were being improperly truncated - (CVE-2011-3464, bug introduced in libpng-1.5.3beta05). - -Version 1.6.0beta06 [January 24, 2012] - Added palette support to the simplified APIs. This commit - changes some of the macro definitions in png.h, app code - may need corresponding changes. - Increased the formatted warning buffer to 192 bytes. - Added color-map support to simplified API. This is an initial version for - review; the documentation has not yet been updated. - Fixed Min/GW uninstall to remove libpng.dll.a - -Version 1.6.0beta07 [January 28, 2012] - Eliminated Intel icc/icl compiler warnings. The Intel (GCC derived) - compiler issues slightly different warnings from those issued by the - current vesions of GCC. This eliminates those warnings by - adding/removing casts and small code rewrites. - Updated configure.ac from autoupdate: added --enable-werror option. - Also some layout regularization and removal of introduced tab characters - (replaced with 3-character indentation). Obsolete macros identified by - autoupdate have been removed; the replacements are all in 2.59 so - the pre-req hasn't been changed. --enable-werror checks for support - for -Werror (or the given argument) in the compiler. This mimics the - gcc configure option by allowing -Werror to be turned on safely; without - the option the tests written in configure itself fail compilation because - they cause compiler warnings. - Rewrote autogen.sh to run autoreconf instead of running tools one-by-one. - Conditionalize the install rules for MINGW and CYGWIN in CMakeLists.txt and - set CMAKE_LIBRARY_OUTPUT_DIRECTORY to "lib" on all platforms (C. Yapp). - Freeze libtool files in the 'scripts' directory. This version of autogen.sh - attempts to dissuade people from running it when it is not, or should not, - be necessary. In fact, autogen.sh does not work when run in a libpng - directory extracted from a tar distribution anymore. You must run it in - a GIT clone instead. - Added two images to contrib/pngsuite (1-bit and 2-bit transparent grayscale), - and renamed three whose names were inconsistent with those in - pngsuite/README.txt. - -Version 1.6.0beta08 [February 1, 2012] - Fixed Image::colormap misalignment in pngstest.c - Check libtool/libtoolize version number (2.4.2) in configure.ac - Divide test-pngstest.sh into separate pngstest runs for basic and - transparent images. - Moved automake options to AM_INIT_AUTOMAKE in configure.ac - Added color-tests, silent-rules (Not yet implemented in Makefile.am) and - version checking to configure.ac - Improved pngstest speed by not doing redundant tests and add const to - the background parameter of png_image_finish_read. The --background - option is now done automagically only when required, so that commandline - option no longer exists. - Cleaned up pngpriv.h to consistently declare all functions and data. - Also eliminated PNG_CONST_DATA, which is apparently not needed but we - can't be sure until it is gone. - Added symbol prefixing that allows all the libpng external symbols - to be prefixed (suggested by Reuben Hawkins). - Updated "ftbb*.png" list in the owatcom and vstudio projects. - Fixed 'prefix' builds on clean systems. The generation of pngprefix.h - should not require itself. - Updated INSTALL to explain that autogen.sh must be run in a GIT clone, - not in a libpng directory extracted from a tar distribution. - -Version 1.6.0beta09 [February 1, 2012] - Reverted the prebuilt configure files to libpng-1.6.0beta05 condition. - -Version 1.6.0beta10 [February 3, 2012] - Added Z_SOLO for zlib-1.2.6+ and correct pngstest tests - Updated list of test images in CMakeLists.txt - Updated the prebuilt configure files to current condition. - Revised INSTALL information about autogen.sh; it works in tar distributions. - -Version 1.6.0beta11 [February 16, 2012] - Fix character count in pngstest command in projects/owatcom/pngstest.tgt - Revised test-pngstest.sh to report PASS/FAIL for each image. - Updated documentation about the simplified API. - Corrected estimate of error in libpng png_set_rgb_to_gray API. The API is - extremely inaccurate for sRGB conversions because it uses an 8-bit - intermediate linear value and it does not use the sRGB transform, so it - suffers from the known instability in gamma transforms for values close - to 0 (see Poynton). The net result is that the calculation has a maximum - error of 14.99/255; 0.5/255^(1/2.2). pngstest now uses 15 for the - permitted 8-bit error. This may still not be enough because of arithmetic - error. - Removed some unused arrays (with #ifdef) from png_read_push_finish_row(). - Fixed a memory overwrite bug in simplified read of RGB PNG with - non-linear gamma Also bugs in the error checking in pngread.c and changed - quite a lot of the checks in pngstest.c to be correct; either correctly - written or not over-optimistic. The pngstest changes are insufficient to - allow all possible RGB transforms to be passed; pngstest cmppixel needs - to be rewritten to make it clearer which errors it allows and then changed - to permit known inaccuracies. - Removed tests for no-longer-used *_EMPTY_PLTE_SUPPORTED from pngstruct.h - Fixed fixed/float API export conditionals. 1) If FIXED_POINT or - FLOATING_POINT options were switched off, png.h ended up with lone ';' - characters. This is not valid ANSI-C outside a function. The ';' - characters have been moved inside the definition of PNG_FP_EXPORT and - PNG_FIXED_EXPORT. 2) If either option was switched off, the declaration - of the corresponding functions were completely omitted, even though some - of them are still used internally. The result is still valid, but - produces warnings from gcc with some warning options (including -Wall). The - fix is to cause png.h to declare the functions with PNG_INTERNAL_FUNCTION - when png.h is included from pngpriv.h. - Check for invalid palette index while reading paletted PNG. When one is - found, issue a warning and increase png_ptr->num_palette accordingly. - Apps are responsible for checking to see if that happened. - -Version 1.6.0beta12 [February 18, 2012] - Do not increase num_palette on invalid_index. - Relocated check for invalid palette index to pngrtran.c, after unpacking - the sub-8-bit pixels. - Fixed CVE-2011-3026 buffer overrun bug. This bug was introduced when - iCCP chunk support was added at libpng-1.0.6. Deal more correctly with the - test on iCCP chunk length. Also removed spurious casts that may hide - problems on 16-bit systems. - -Version 1.6.0beta13 [February 24, 2012] - Eliminated redundant png_push_read_tEXt|zTXt|iTXt|unknown code from - pngpread.c and use the sequential png_handle_tEXt, etc., in pngrutil.c; - now that png_ptr->buffer is inaccessible to applications, the special - handling is no longer useful. - Added PNG_SAFE_LIMITS feature to pnglibconf.dfa, pngpriv.h, and new - pngusr.dfa to reset the user limits to safe ones if PNG_SAFE_LIMITS is - defined. To enable, use "CPPFLAGS=-DPNG_SAFE_LIMITS_SUPPORTED=1" on the - configure command or put #define PNG_SAFE_LIMITS_SUPPORTED in - pnglibconf.h.prebuilt and pnglibconf.h. - -Version 1.6.0beta14 [February 27, 2012] - Added information about the new limits in the manual. - Updated Makefile.in - -Version 1.6.0beta15 [March 2, 2012] - Removed unused "current_text" members of png_struct and the png_free() - of png_ptr->current_text from pngread.c - Rewrote pngstest.c for substantial speed improvement. - Fixed transparent pixel and 16-bit rgb tests in pngstest and removed a - spurious check in pngwrite.c - Added PNG_IMAGE_FLAG_FAST for the benefit of applications that store - intermediate files, or intermediate in-memory data, while processing - image data with the simplified API. The option makes the files larger - but faster to write and read. pngstest now uses this by default; this - can be disabled with the --slow option. - Improved pngstest fine tuning of error numbers, new test file generator. - The generator generates images that test the full range of sample values, - allow the error numbers in pngstest to be tuned and checked. makepng - also allows generation of images with extra chunks, although this is - still work-in-progress. - Added check for invalid palette index while reading. - Fixed some bugs in ICC profile writing. The code should now accept - all potentially valid ICC profiles and reject obviously invalid ones. - It now uses png_error() to do so rather than casually writing a PNG - without the necessary color data. - Removed whitespace from the end of lines in all source files and scripts. - -Version 1.6.0beta16 [March 6, 2012] - Relocated palette-index checking function from pngrutil.c to pngtrans.c - Added palette-index checking while writing. - Changed png_inflate() and calling routines to avoid overflow problems. - This is an intermediate check-in that solves the immediate problems and - introduces one performance improvement (avoiding a copy via png_ptr->zbuf.) - Further changes will be made to make ICC profile handling more secure. - Fixed build warnings (MSVC, GCC, GCC v3). Cygwin GCC with default options - declares 'index' as a global, causing a warning if it is used as a local - variable. GCC 64-bit warns about assigning a (size_t) (unsigned 64-bit) - to an (int) (signed 32-bit). MSVC, however, warns about using the - unary '-' operator on an unsigned value (even though it is well defined - by ANSI-C to be ~x+1). The padding calculation was changed to use a - different method. Removed the tests on png_ptr->pass. - Added contrib/libtests/tarith.c to test internal arithmetic functions from - png.c. This is a libpng maintainer program used to validate changes to the - internal arithmetic functions. - Made read 'inflate' handling like write 'deflate' handling. The read - code now claims and releases png_ptr->zstream, like the write code. - The bug whereby the progressive reader failed to release the zstream - is now fixed, all initialization is delayed, and the code checks for - changed parameters on deflate rather than always calling - deflatedEnd/deflateInit. - Validate the zTXt strings in pngvalid. - Added code to validate the windowBits value passed to deflateInit2(). - If the call to deflateInit2() is wrong a png_warning will be issued - (in fact this is harmless, but the PNG data produced may be sub-optimal). - -Version 1.6.0beta17 [March 10, 2012] - Fixed PNG_LIBPNG_BUILD_BASE_TYPE definition. - Reject all iCCP chunks after the first, even if the first one is invalid. - Deflate/inflate was reworked to move common zlib calls into single - functions [rw]util.c. A new shared keyword check routine was also added - and the 'zbuf' is no longer allocated on progressive read. It is now - possible to call png_inflate() incrementally. A warning is no longer - issued if the language tag or translated keyword in the iTXt chunk - has zero length. - If benign errors are disabled use maximum window on ancilliary inflate. - This works round a bug introduced in 1.5.4 where compressed ancillary - chunks could end up with a too-small windowBits value in the deflate - header. - -Version 1.6.0beta18 [March 16, 2012] - Issue a png_benign_error() instead of png_warning() about bad palette index. - In pngtest, treat benign errors as errors if "-strict" is present. - Fixed an off-by-one error in the palette index checking function. - Fixed a compiler warning under Cygwin (Windows-7, 32-bit system) - Revised example.c to put text strings in a temporary character array - instead of directly assigning string constants to png_textp members. - This avoids compiler warnings when -Wwrite-strings is enabled. - Added output flushing to aid debugging under Visual Studio. Unfortunately - this is necessary because the VS2010 output window otherwise simply loses - the error messages on error (they weren't flushed to the window before - the process exited, apparently!) - Added configuration support for benign errors and changed the read - default. Also changed some warnings in the iCCP and sRGB handling - from to benign errors. Configuration now makes read benign - errors warnings and write benign errors to errors by default (thus - changing the behavior on read). The simplified API always forces - read benign errors to warnings (regardless of the system default, unless - this is disabled in which case the simplified API can't be built.) - -Version 1.6.0beta19 [March 18, 2012] - Work around for duplicate row start calls; added warning messages. - This turns on PNG_FLAG_DETECT_UNINITIALIZED to detect app code that - fails to call one of the 'start' routines (not enabled in libpng-1.5 - because it is technically an API change, since it did normally work - before.) It also makes duplicate calls to png_read_start_row (an - internal function called at the start of the image read) benign, as - they were before changes to use png_inflate_claim. Somehow webkit is - causing this to happen; this is probably a mis-feature in the zlib - changes so this commit is only a work-round. - Removed erroneous setting of DETECT_UNINITIALIZED and added more - checks. The code now does a png_error if an attempt is made to do the - row initialization twice; this is an application error and it has - serious consequences because the transform data in png_struct is - changed by each call. - Added application error reporting and added chunk names to read - benign errors; also added --strict to pngstest - not enabled - yet because a warning is produced. - Avoid the double gamma correction warning in the simplified API. - This allows the --strict option to pass in the pngstest checks - -Version 1.6.0beta20 [March 29, 2012] - Changed chunk handler warnings into benign errors, incrementally load iCCP - Added checksum-icc.c to contrib/tools - Prevent PNG_EXPAND+PNG_SHIFT doing the shift twice. - Recognize known sRGB ICC profiles while reading; prefer writing the - iCCP profile over writing the sRGB chunk, controlled by the - PNG_sRGB_PROFILE_CHECKS option. - Revised png_set_text_2() to avoid potential memory corruption (fixes - CVE-2011-3048, also known as CVE-2012-3425). - -Version 1.6.0beta21 [April 27, 2012] - Revised scripts/makefile.darwin: use system zlib; remove quotes around - architecture list; add missing ppc architecture; add architecture options - to shared library link; don't try to create a shared lib based on missing - RELEASE variable. - Enable png_set_check_for_invalid_index() for both read and write. - Removed #ifdef PNG_HANDLE_AS_UNKNOWN_SUPPORTED in pngpriv.h around - declaration of png_handle_unknown(). - Added -lssp_nonshared in a comment in scripts/makefile.freebsd - and changed deprecated NOOBJ and NOPROFILE to NO_OBJ and NO_PROFILE. - -Version 1.6.0beta22 [May 23, 2012] - Removed need for -Wno-cast-align with clang. clang correctly warns on - alignment increasing pointer casts when -Wcast-align is passed. This - fixes the cases that clang warns about either by eliminating the - casts from png_bytep to png_uint_16p (pngread.c), or, for pngrutil.c - where the cast is previously verified or pngstest.c where it is OK, by - introducing new png_aligncast macros to do the cast in a way that clang - accepts. - -Version 1.6.0beta23 [June 6, 2012] - Revised CMakeLists.txt to not attempt to make a symlink under mingw. - Made fixes for new optimization warnings from gcc 4.7.0. The compiler - performs an optimization which is safe; however it then warns about it. - Changing the type of 'palette_number' in pngvalid.c removes the warning. - Do not depend upon a GCC feature macro being available for use in generating - the linker mapfile symbol prefix. - Improved performance of new do_check_palette_indexes() function (only - update the value when it actually increases, move test for whether - the check is wanted out of the function. - -Version 1.6.0beta24 [June 7, 2012] - Don't check palette indexes if num_palette is 0 (as it can be in MNG files). - -Version 1.6.0beta25 [June 16, 2012] - Revised png_set_keep_unknown_chunks() so num_chunks < 0 means ignore all - unknown chunks and all known chunks except for IHDR, PLTE, tRNS, IDAT, - and IEND. Previously it only meant ignore all unknown chunks, the - same as num_chunks == 0. Revised png_image_skip_unused_chunks() to - provide a list of chunks to be processed instead of a list of chunks to - ignore. Revised contrib/gregbook/readpng2.c accordingly. - -Version 1.6.0beta26 [July 10, 2012] - Removed scripts/makefile.cegcc from the *.zip and *.7z distributions; it - depends on configure, which is not included in those archives. - Moved scripts/chkfmt to contrib/tools. - Changed "a+w" to "u+w" in Makefile.in to fix CVE-2012-3386. - -Version 1.6.0beta27 [August 11, 2012] - Do not compile PNG_DEPRECATED, PNG_ALLOC and PNG_PRIVATE when __GNUC__ < 3. - Do not use __restrict when GNUC is <= 3.1 - Removed references to png_zalloc() and png_zfree() from the manual. - Fixed configurations where floating point is completely disabled. Because - of the changes to support symbol prefixing PNG_INTERNAL_FUNCTION declares - floating point APIs during libpng builds even if they are completely - disabled. This requires the png floating point types (png_double*) to be - declared even though the functions are never actually defined. This - change provides a dummy definition so that the declarations work, yet any - implementation will fail to compile because of an incomplete type. - Re-eliminated the use of strcpy() in pngtest.c. An unncessary use of - strcpy() was accidentally re-introduced in libpng16; this change replaces - it with strncpy(). - Eliminated use of png_sizeof(); use sizeof() instead. - Use a consistent style for (sizeof type) and (sizeof (array)) - Cleanup of png_set_filler(). This function does very different things on - read and write. In libpng 1.6 the two cases can be distinguished and - considerable code cleanup, and extra error checking, is possible. This - makes calls on the write side that have no effect be ignored with a - png_app_error(), which can be disabled in the app using - png_set_benign_errors(), and removes the spurious use of usr_channels - on the read side. - Insist on autotools 1.12.1 for git builds because there are security issues - with 1.12 and insisting on anything less would allow 1.12 to be used. - Removed info_ptr->signature[8] from WRITE-only builds. - Add some conditions for compiling png_fixed(). This is a small function - but it requires "-lm" on some platforms. - Cause pngtest --strict to fail on any warning from libpng (not just errors) - and cause it not to fail at the comparison step if libpng lacks support - for writing chunks that it reads from the input (currently only implemented - for compressed text chunks). - Make all three "make check" test programs work without READ or WRITE support. - Now "make check" will succeed even if libpng is compiled with -DPNG_NO_READ - or -DPNG_NO_WRITE. The tests performed are reduced, but the basic reading - and writing of a PNG file is always tested by one or more of the tests. - Consistently use strlen(), memset(), memcpy(), and memcmp() instead of the - png_strlen(), png_memset(), png_memcpy(), and png_memcmp() macros. - Removed the png_sizeof(), png_strlen(), png_memset(), png_memcpy(), and - png_memcmp() macros. - Work around gcc 3.x and Microsoft Visual Studio 2010 complaints. Both object - to the split initialization of num_chunks. - -Version 1.6.0beta28 [August 29, 2012] - Unknown handling fixes and clean up. This adds more correct option - control of the unknown handling, corrects the pre-existing bug where - the per-chunk 'keep' setting is ignored and makes it possible to skip - IDAT chunks in the sequential reader (broken in earlier 1.6 versions). - There is a new test program, test-unknown.c, which is a work in progress - (not currently part of the test suite). Comments in the header files now - explain how the unknown handling works. - Allow fine grain control of unknown chunk APIs. This change allows - png_set_keep_unknown_chunks() to be turned off if not required and causes - both read and write to behave appropriately (on read this is only possible - if the user callback is used to handle unknown chunks). The change - also removes the support for storing unknown chunks in the info_struct - if the only unknown handling enabled is via the callback, allowing libpng - to be configured with callback reading and none of the unnecessary code. - Corrected fix for unknown handling in pngtest. This reinstates the - libpng handling of unknown chunks other than vpAg and sTER (including - unsafe-to-copy chunks which were dropped before) and eliminates the - repositioning of vpAg and sTER in pngtest.png by changing pngtest.png - (so the chunks are where libpng would put them). - Added "tunknown" test and corrected a logic error in png_handle_unknown() - when SAVE support is absent. Moved the shell test scripts for - contrib/libtests from the libpng top directory to contrib/libtests. - png_handle_unknown() must always read or skip the chunk, if - SAVE_UNKNOWN_CHUNKS is turned off *and* the application does not set - a user callback an unknown chunk will not be read, leading to a read - error, which was revealed by the "tunknown" test. - Cleaned up and corrected ICC profile handling. - contrib/libtests/makepng: corrected 'rgb' and 'gray' cases. profile_error - messages could be truncated; made a correct buffer size calculation and - adjusted pngerror.c appropriately. png_icc_check_* checking improved; - changed the functions to receive the correct color type of the PNG on read - or write and check that it matches the color space of the profile (despite - what the comments said before, there is danger in assuming the app will - cope correctly with an RGB profile on a grayscale image and, since it - violates the PNG spec, allowing it is certain to produce inconsistent - app behavior and might even cause app crashes.) Check that profiles - contain the tags needed to process the PNG (tags all required by the ICC - spec). Removed unused PNG_STATIC from pngpriv.h. - -Version 1.6.0beta29 [September 4, 2012] - Fixed the simplified API example programs to add the *colormap parameter - to several of he API and improved the error message if the version field - is not set. - Added contrib/examples/* to the *.zip and *.7z distributions. - Updated simplified API synopses and description of the png_image structure - in the manual. - Made makepng and pngtest produce identical PNGs, add "--relaxed" option - to pngtest. The "--relaxed" option turns off the benign errors that are - enabled by default in pre-RC builds. makepng can now write ICC profiles - where the length has not been extended to a multiple of 4, and pngtest - now intercepts all libpng errors, allowing the previously-introduced - "--strict test" on no warnings to actually work. - Improved ICC profile handling including cHRM chunk generation and fixed - Cygwin+MSVC build errors. The ICC profile handling now includes more - checking. Several errors that caused rejection of the profile are now - handled with a warning in such a way that the invalid profiles will be - read by default in release (but not pre-RC) builds but will not be - written by default. The easy part of handling the cHRM chunk is written, - where the ICC profile contains the required data. The more difficult - part plus guessing a gAMA value requires code to pass selected RGB values - through the profile. - -Version 1.6.0beta30 [October 24, 2012] - Changed ICC profile matrix/vector types to not depend on array type rules. - By the ANSI-C standard the new types should be identical to the previous - versions, and all known versions of gcc tested with the previous versions - except for GCC-4.2.1 work with this version. The change makes the ANSI-C - rule that const applied to an array of elements applies instead to the - elements in the array moot by explicitly applying const to the base - elements of the png_icc_matrix and png_icc_vector types. The accidental - (harmless) 'const' previously applied to the parameters of two of the - functions have also been removed. - Added a work around for GCC 4.2 optimization bug. - Marked the broken (bad white point) original HP sRGB profiles correctly and - correct comments. - Added -DZ_SOLO to contrib/pngminim/*/makefile to work with zlib-1.2.7 - Use /MDd for vstudio debug builds. Also added pngunkown to the vstudio - builds, fixed build errors and corrected a minor exit code error in - pngvalid if the 'touch' file name is invalid. - Add updated WARNING file to projects/vstudio from libpng 1.5/vstudio - Fixed build when using #define PNG_NO_READ_GAMMA in png_do_compose() in - pngrtran.c (Domani Hannes). - -Version 1.6.0beta31 [November 1, 2012] - Undid the erroneous change to vstudio/pngvalid build in libpng-1.6.0beta30. - Made pngvalid so that it will build outside the libpng source tree. - Made builds -DPNG_NO_READ_GAMMA compile (the unit tests still fail). - Made PNG_NO_READ_GAMMA switch off interfaces that depend on READ_GAMMA. - Prior to 1.6.0 switching off READ_GAMMA did unpredictable things to the - interfaces that use it (specifically, png_do_background in 1.4 would - simply display composite for grayscale images but do composition - with the incorrect arithmetic for color ones). In 1.6 the semantic - of -DPNG_NO_READ_GAMMA is changed to simply disable any interface that - depends on it; this obliges people who set it to consider whether they - really want it off if they happen to use any of the interfaces in - question (typically most users who disable it won't). - Fixed GUIDs in projects/vstudio. Some were duplicated or missing, - resulting in VS2010 having to update the files. - Removed non-working ICC profile support code that was mostly added to - libpng-1.6.0beta29 and beta30. There was too much code for too little - gain; implementing full ICC color correction may be desireable but is left - up to applications. - -Version 1.6.0beta32 [November 25, 2012] - Fixed an intermittent SEGV in pngstest due to an uninitialized array element. - Added the ability for contrib/libtests/makepng.c to make a PNG with just one - color. This is useful for debugging pngstest color inaccuracy reports. - Fixed error checking in the simplified write API (Olaf van der Spek) - Made png_user_version_check() ok to use with libpng version 1.10.x and later. - -Version 1.6.0beta33 [December 15, 2012] - Fixed typo in png.c (PNG_SET_CHUNK_MALLOC_MAX should be PNG_CHUNK_MALLOC_MAX) - that causes the MALLOC_MAX limit not to work (John Bowler) - Change png_warning() to png_app_error() in pngwrite.c and comment the - fall-through condition. - Change png_warning() to png_app_warning() in png_write_tRNS(). - Rearranged the ARM-NEON optimizations: Isolated the machine specific code - to the hardware subdirectory and added comments to pngrutil.c so that - implementors of other optimizations know what to do. - Fixed cases of unquoted DESTDIR in Makefile.am - Rebuilt Makefile.in, etc., with autoconf-2.69 and automake-1.12.5. - -Version 1.6.0beta34 [December 19, 2012] - Cleaned up whitespace in the synopsis portion of the manpage "libpng.3" - Disassembled the version number in scripts/options.awk (necessary for - building on SunOs). - -Version 1.6.0beta35 [December 23, 2012] - Made default Zlib compression settings be configurable. This adds #defines to - pnglibconf.h to control the defaults. - Fixed Windows build issues, enabled ARM compilation. Various warnings issued - by earlier versions of GCC fixed for Cygwin and Min/GW (which both use old - GCCs.) ARM support is enabled by default in zlib.props (unsupported by - Microsoft) and ARM compilation is made possible by deleting the check for - x86. The test programs cannot be run because they are not signed. - -Version 1.6.0beta36 [January 2, 2013] - Discontinued distributing libpng-1.x.x.tar.bz2. - Discontinued distributing libpng-1.7.0-1.6.0-diff.txt and similar. - Rebuilt configure with autoconf-2.69 (inadvertently not done in beta33) - Fixed 'make distcheck' on SUN OS - libpng.so was not being removed - -Version 1.6.0beta37 [January 10, 2013] - Fixed conceivable but difficult to repro overflow. Also added two test - programs to generate and test a PNG which should have the problem. - -Version 1.6.0beta39 [January 19, 2013] - Again corrected attempt at overflow detection in png_set_unknown_chunks() - (CVE-2013-7353). Added overflow detection in png_set_sPLT() and - png_set_text_2() (CVE-2013-7354). - -Version 1.6.0beta40 [January 20, 2013] - Use consistent handling of overflows in text, sPLT and unknown png_set_* APIs - -Version 1.6.0rc01 [January 26, 2013] - No changes. - -Version 1.6.0rc02 [February 4, 2013] - Added png_get_palette_max() function. - -Version 1.6.0rc03 [February 5, 2013] - Fixed the png_get_palette_max API. - -Version 1.6.0rc04 [February 7, 2013] - Turn serial tests back on (recently turned off by autotools upgrade). - -Version 1.6.0rc05 [February 8, 2013] - Update manual about png_get_palette_max(). - -Version 1.6.0rc06 [February 9, 2013] - Fixed missing dependency in --prefix builds The intermediate - internal 'prefix.h' file can only be generated correctly after - pnglibconf.h, however the dependency was not in Makefile.am. The - symptoms are unpredictable depending on the order make chooses to - build pngprefix.h and pnglibconf.h, often the error goes unnoticed - because there is a system pnglibconf.h to use instead. - -Version 1.6.0rc07 [February 10, 2013] - Enclosed the new png_get_palette_max in #ifdef PNG_GET_PALETTE_MAX_SUPPORTED - block, and revised pnglibconf.h and pnglibconf.h.prebuilt accordingly. - -Version 1.6.0rc08 [February 10, 2013] - Fix typo in png.h #ifdef - -Version 1.6.0 [February 14, 2013] - No changes. - -Version 1.6.1beta01 [February 16, 2013] - Made symbol prefixing work with the ARM neon optimizations. Also allow - pngpriv.h to be included for preprocessor definitions only, so it can - be used in non-C/C++ files. Back ported from libpng 1.7. - Made sRGB check numbers consistent. - Ported libpng 1.5 options.awk/dfn file handling to 1.6, fixed one bug. - Removed cc -E workround, corrected png_get_palette_max API Tested on - SUN OS cc 5.9, which demonstrates the tokenization problem previously - avoided by using /lib/cpp. Since all .dfn output is now protected in - double quotes unless it is to be macro substituted the fix should - work everywhere. - Enabled parallel tests - back ported from libpng-1.7. - scripts/pnglibconf.dfa formatting improvements back ported from libpng17. - Fixed a race condition in the creation of the build 'scripts' directory - while building with a parallel make. - Use approved/supported Android method to check for NEON, use Linux/POSIX - 1003.1 API to check /proc/self/auxv avoiding buffer allocation and other - library calls (ported from libpng15). - -Version 1.6.1beta02 [February 19, 2013] - Use parentheses more consistently in "#if defined(MACRO)" tests. - Folded long lines. - Reenabled code to allow zero length PLTE chunks for MNG. - -Version 1.6.1beta03 [February 22, 2013] - Fixed ALIGNED_MEMORY support. - Added a new configure option: - --enable-arm-neon=always will stop the run-time checks. New checks - within arm/arm_init.c will cause the code not to be compiled unless - __ARM_NEON__ is set. This should make it fail safe (if someone asks - for it on then the build will fail if it can't be done.) - Updated the INSTALL document. - -Version 1.6.1beta04 [February 27, 2013] - Revised INSTALL to recommend using CPPFLAGS instead of INCLUDES. - Revised scripts/makefile.freebsd to respect ZLIBLIB and ZLIBINC. - Revised scripts/dfn.awk to work with the buggy MSYS awk that has trouble - with CRLF line endings. - -Version 1.6.1beta05 [March 1, 2013] - Avoid a possible memory leak in contrib/gregbook/readpng.c - -Version 1.6.1beta06 [March 4, 2013] - Better documentation of unknown handling API interactions. - Corrected Android builds and corrected libpng.vers with symbol - prefixing. It also makes those tests compile and link on Android. - Added an API png_set_option() to set optimization options externally, - providing an alternative and general solution for the non-portable - run-time tests used by the ARM Neon code, using the PNG_ARM_NEON option. - The order of settings vs options in pnglibconf.h is reversed to allow - settings to depend on options and options can now set (or override) the - defaults for settings. - -Version 1.6.1beta07 [March 7, 2013] - Corrected simplified API default gamma for color-mapped output, added - a flag to change default. In 1.6.0 when the simplified API was used - to produce color-mapped output from an input image with no gamma - information the gamma assumed for the input could be different from - that assumed for non-color-mapped output. In particular 16-bit depth - input files were assumed to be sRGB encoded, whereas in the 'direct' - case they were assumed to have linear data. This was an error. The - fix makes the simplified API treat all input files the same way and - adds a new flag to the png_image::flags member to allow the - application/user to specify that 16-bit files contain sRGB data - rather than the default linear. - Fixed bugs in the pngpixel and makepng test programs. - -Version 1.6.1beta08 [March 7, 2013] - Fixed CMakelists.txt to allow building a single variant of the library - (Claudio Bley): - Introduced a PNG_LIB_TARGETS variable that lists all activated library - targets. It is an error if this variable ends up empty, ie. you have - to build at least one library variant. - Made the *_COPY targets only depend on library targets actually being build. - Use PNG_LIB_TARGETS to unify a code path. - Changed the CREATE_SYMLINK macro to expect the full path to a file as the - first argument. When symlinking the filename component of that path is - determined and used as the link target. - Use copy_if_different in the CREATE_SYMLINK macro. - -Version 1.6.1beta09 [March 13, 2013] - Eliminated two warnings from the Intel C compiler. The warnings are - technically valid, although a reasonable treatment of division would - show it to be incorrect. - -Version 1.6.1rc01 [March 21, 2013] - No changes. - -Version 1.6.1 [March 28, 2013] - No changes. - -Version 1.6.2beta01 [April 14, 2013] - Updated documentation of 1.5.x to 1.6.x changes in iCCP chunk handling. - Fixed incorrect warning of excess deflate data. End condition - the - warning would be produced if the end of the deflate stream wasn't read - in the last row. The warning is harmless. - Corrected the test on user transform changes on read. It was in the - png_set of the transform function, but that doesn't matter unless the - transform function changes the rowbuf size, and that is only valid if - transform_info is called. - Corrected a misplaced closing bracket in contrib/libtests/pngvalid.c - (Flavio Medeiros). - Corrected length written to uncompressed iTXt chunks (Samuli Suominen). - Bug was introduced in libpng-1.6.0. - -Version 1.6.2rc01 [April 18, 2013] - Added contrib/tools/fixitxt.c, to repair the erroneous iTXt chunk length - written by libpng-1.6.0 and 1.6.1. - Disallow storing sRGB information when the sRGB is not supported. - -Version 1.6.2rc02 [April 18, 2013] - Merge pngtest.c with libpng-1.7.0 - -Version 1.6.2rc03 [April 22, 2013] - Trivial spelling cleanup. - -Version 1.6.2rc04 and 1.6.2rc05 [omitted] - -Version 1.6.2rc06 [April 24, 2013] - Reverted to version 1.6.2rc03. Recent changes to arm/neon support - have been ported to libpng-1.7.0beta09 and will reappear in version - 1.6.3beta01. - -Version 1.6.2 [April 25, 2013] - No changes. - -Version 1.6.3beta01 [April 25, 2013] - Revised stack marking in arm/filter_neon.S and configure.ac. - Ensure that NEON filter stuff is completely disabled when switched 'off'. - Previously the ARM NEON specific files were still built if the option - was switched 'off' as opposed to being explicitly disabled. - -Version 1.6.3beta02 [April 26, 2013] - Test for 'arm*' not just 'arm' in the host_cpu configure variable. - Rebuilt the configure scripts. - -Version 1.6.3beta03 [April 30, 2013] - Expanded manual paragraph about writing private chunks, particularly - the need to call png_set_keep_unknown_chunks() when writing them. - Avoid dereferencing NULL pointer possibly returned from - png_create_write_struct() (Andrew Church). - -Version 1.6.3beta05 [May 9, 2013] - Calculate our own zlib windowBits when decoding rather than trusting the - CMF bytes in the PNG datastream. - Added an option to force maximum window size for inflating, which was - the behavior of libpng15 and earlier, via a new PNG_MAXIMUM_INFLATE_WINDOW - option for png_set_options(). - Added png-fix-itxt and png-fix-too-far-back to the built programs and - removed warnings from the source code and timepng that are revealed as - a result. - Detect wrong libpng versions linked to png-fix-too-far-back, which currently - only works with libpng versions that can be made to reliably fail when - the deflate data contains an out-of-window reference. This means only - 1.6 and later. - Fixed gnu issues: g++ needs a static_cast, gcc 4.4.7 has a broken warning - message which it is easier to work round than ignore. - Updated contrib/pngminus/pnm2png.c (Paul Stewart): - Check for EOF - Ignore "#" delimited comments in input file to pnm2png.c. - Fixed whitespace handling - Added a call to png_set_packing() - Initialize dimension values so if sscanf fails at least we have known - invalid values. - Attempt to detect configuration issues with png-fix-too-far-back, which - requires both the correct libpng and the correct zlib to function - correctly. - Check ZLIB_VERNUM for mismatches, enclose #error in quotes - Added information in the documentation about problems with and fixes for - the bad CRC and bad iTXt chunk situations. - -Version 1.6.3beta06 [May 12, 2013] - Allow contrib/pngminus/pnm2png.c to compile without WRITE_INVERT and - WRITE_PACK supported (writes error message that it can't read P1 or - P4 PBM files). - Improved png-fix-too-far-back usage message, added --suffix option. - Revised contrib/pngminim/*/makefile to generate pnglibconf.h with the - right zlib header files. - Separated CPPFLAGS and CFLAGS in contrib/pngminim/*/makefile - -Version 1.6.3beta07 [June 8, 2013] - Removed a redundant test in png_set_IHDR(). - Added set(CMAKE_CONFIGURATION_TYPES ...) to CMakeLists.txt (Andrew Hundt) - Deleted set(CMAKE_BUILD_TYPE) block from CMakeLists.txt - Enclose the prototypes for the simplified write API in - #ifdef PNG_STDIO_SUPPORTED/#endif - Make ARM NEON support work at compile time (not just configure time). - This moves the test on __ARM_NEON__ into pngconf.h to avoid issues when - using a compiler that compiles for multiple architectures at one time. - Removed PNG_FILTER_OPTIMIZATIONS and PNG_ARM_NEON_SUPPORTED from - pnglibconf.h, allowing more of the decisions to be made internally - (pngpriv.h) during the compile. Without this, symbol prefixing is broken - under certain circumstances on ARM platforms. Now only the API parts of - the optimizations ('check' vs 'api') are exposed in the public header files - except that the new setting PNG_ARM_NEON_OPT documents how libpng makes the - decision about whether or not to use the optimizations. - Protect symbol prefixing against CC/CPPFLAGS/CFLAGS useage. - Previous iOS/Xcode fixes for the ARM NEON optimizations moved the test - on __ARM_NEON__ from configure time to compile time. This breaks symbol - prefixing because the definition of the special png_init_filter_functions - call was hidden at configure time if the relevant compiler arguments are - passed in CFLAGS as opposed to CC. This change attempts to avoid all - the confusion that would result by declaring the init function even when - it is not used, so that it will always get prefixed. - -Version 1.6.3beta08 [June 18, 2013] - Revised libpng.3 so that "doclifter" can process it. - -Version 1.6.3beta09 [June 27, 2013] - Revised example.c to illustrate use of PNG_DEFAULT_sRGB and PNG_GAMMA_MAC_18 - as parameters for png_set_gamma(). These have been available since - libpng-1.5.4. - Renamed contrib/tools/png-fix-too-far-back.c to pngfix.c and revised it - to check all compressed chunks known to libpng. - -Version 1.6.3beta10 [July 5, 2013] - Updated documentation to show default behavior of benign errors correctly. - Only compile ARM code when PNG_READ_SUPPORTED is defined. - Fixed undefined behavior in contrib/tools/pngfix.c and added new strip - option. pngfix relied on undefined behavior and even a simple change from - gcc to g++ caused it to fail. The new strip option 'unsafe' has been - implemented and is the default if --max is given. Option names have - been clarified, with --strip=transform now stripping the bKGD chunk, - which was stripped previously with --strip=unused. - Added all documented chunk types to pngpriv.h - Unified pngfix.c source with libpng17. - -Version 1.6.3rc01 [July 11, 2013] - No changes. - -Version 1.6.3 [July 18, 2013] - Revised manual about changes in iTXt chunk handling made in libpng-1.6.0. - Added "/* SAFE */" comments in pngrutil.c and pngrtran.c where warnings - may be erroneously issued by code-checking applications. - -Version 1.6.4beta01 [August 21, 2013] - Added information about png_set_options() to the manual. - Delay calling png_init_filter_functions() until a row with nonzero filter - is found. - -Version 1.6.4beta02 [August 30, 2013] - Fixed inconsistent conditional compilation of png_chunk_unknown_handling() - prototype, definition, and usage. Made it depend on - PNG_HANDLE_AS_UNKNOWN_SUPPORTED everywhere. - -Version 1.6.4rc01 [September 5, 2013] - No changes. - -Version 1.6.4 [September 12, 2013] - No changes. - -Version 1.6.5 [September 14, 2013] - Removed two stray lines of code from arm/arm_init.c. - -Version 1.6.6 [September 16, 2013] - Removed two stray lines of code from arm/arm_init.c, again. - -Version 1.6.7beta01 [September 30, 2013] - Revised unknown chunk code to correct several bugs in the NO_SAVE_/NO_WRITE - combination - Allow HANDLE_AS_UNKNOWN to work when other options are configured off. Also - fixed the pngminim makefiles to work when $(MAKEFLAGS) contains stuff - which terminates the make options (as by default in recent versions of - Gentoo). - Avoid up-cast warnings in pngvalid.c. On ARM the alignment requirements of - png_modifier are greater than that of png_store and as a consequence - compilation of pngvalid.c results in a warning about increased alignment - requirements because of the bare cast to (png_modifier*). The code is safe, - because the pointer is known to point to a stack allocated png_modifier, - but this change avoids the warning. - Fixed default behavior of ARM_NEON_API. If the ARM NEON API option was - compiled without the CHECK option it defaulted to on, not off. - Check user callback behavior in pngunknown.c. Previous versions compiled - if SAVE_UNKNOWN was not available but did nothing since the callback - was never implemented. - Merged pngunknown.c with 1.7 version and back ported 1.7 improvements/fixes - -Version 1.6.7beta02 [October 12, 2013] - Made changes for compatibility with automake 1.14: - 1) Added the 'compile' program to the list of programs that must be cleaned - in autogen.sh - 2) Added 'subdir-objects' which causes .c files in sub-directories to be - compiled such that the corresponding .o files are also in the - sub-directory. This is because automake 1.14 warns that the - current behavior of compiling to the top level directory may be removed - in the future. - 3) Updated dependencies on pnglibconf.h to match the new .o locations and - added all the files in contrib/libtests and contrib/tools that depend - on pnglibconf.h - 4) Added 'BUILD_SOURCES = pnglibconf.h'; this is the automake recommended - way of handling the dependencies of sources that are machine generated; - unfortunately it only works if the user does 'make all' or 'make check', - so the dependencies (3) are still required. - Cleaned up (char*) casts of zlib messages. The latest version of the Intel C - compiler complains about casting a string literal as (char*), so copied the - treatment of z_const from the library code into pngfix.c - Simplified error message code in pngunknown. The simplification has the - useful side effect of avoiding a bogus warning generated by the latest - version of the Intel C compiler (it objects to - condition ? string-literal : string-literal). - Make autogen.sh work with automake 1.13 as well as 1.14. Do this by always - removing the 1.14 'compile' script but never checking for it. - -Version 1.6.7beta03 [October 19, 2013] - Added ARMv8 support (James Yu <james.yu at linaro.org>). Added file - arm/filter_neon_intrinsics.c; enable with -mfpu=neon. - Revised pngvalid to generate size images with as many filters as it can - manage, limited by the number of rows. - Cleaned up ARM NEON compilation handling. The tests are now in pngpriv.h - and detect the broken GCC compilers. - -Version 1.6.7beta04 [October 26, 2013] - Allow clang derived from older GCC versions to use ARM intrinsics. This - causes all clang builds that use -mfpu=neon to use the intrinsics code, - not the assembler code. This has only been tested on iOS 7. It may be - necessary to exclude some earlier clang versions but this seems unlikely. - Changed NEON implementation selection mechanism. This allows assembler - or intrinsics to be turned on at compile time during the build by defining - PNG_ARM_NEON_IMPLEMENTATION to the correct value (2 or 1). This macro - is undefined by default and the build type is selected in pngpriv.h. - -Version 1.6.7rc01 [November 2, 2013] - No changes. - -Version 1.6.7rc02 [November 7, 2013] - Fixed #include in filter_neon_intrinsics.c and ctype macros. The ctype char - checking macros take an unsigned char argument, not a signed char. - -Version 1.6.7 [November 14, 2013] - No changes. - -Version 1.6.8beta01 [November 24, 2013] - Moved prototype for png_handle_unknown() in pngpriv.h outside of - the #ifdef PNG_SET_UNKNOWN_CHUNKS_SUPPORTED/#endif block. - Added "-Wall" to CFLAGS in contrib/pngminim/*/makefile - Conditionally compile some unused functions reported by -Wall in - pngminim. - Fixed 'minimal' builds. Various obviously useful minimal configurations - don't build because of missing contrib/libtests test programs and - overly complex dependencies in scripts/pnglibconf.dfa. This change - adds contrib/conftest/*.dfa files that can be used in automatic build - scripts to ensure that these configurations continue to build. - Enabled WRITE_INVERT and WRITE_PACK in contrib/pngminim/encoder. - Fixed pngvalid 'fail' function declaration on the Intel C Compiler. - This reverts to the previous 'static' implementation and works round - the 'unused static function' warning by using PNG_UNUSED(). - -Version 1.6.8beta02 [November 30, 2013] - Removed or marked PNG_UNUSED some harmless "dead assignments" reported - by clang scan-build. - Changed tabs to 3 spaces in png_debug macros and changed '"%s"m' - to '"%s" m' to improve portability among compilers. - Changed png_free_default() to free() in pngtest.c - -Version 1.6.8rc01 [December 12, 2013] - Tidied up pngfix inits and fixed pngtest no-write builds. - -Version 1.6.8rc02 [December 14, 2013] - Handle zero-length PLTE chunk or NULL palette with png_error() - instead of png_chunk_report(), which by default issues a warning - rather than an error, leading to later reading from a NULL pointer - (png_ptr->palette) in png_do_expand_palette(). This is CVE-2013-6954 - and VU#650142. Libpng-1.6.1 through 1.6.7 are vulnerable. - Libpng-1.6.0 and earlier do not have this bug. - -Version 1.6.8 [December 19, 2013] - No changes. - -Version 1.6.9beta01 [December 26, 2013] - Bookkeeping: Moved functions around (no changes). Moved transform - function definitions before the place where they are called so that - they can be made static. Move the intrapixel functions and the - grayscale palette builder out of the png?tran.c files. The latter - isn't a transform function and is no longer used internally, and the - former MNG specific functions are better placed in pngread/pngwrite.c - Made transform implementation functions static. This makes the internal - functions called by png_do_{read|write}_transformations static. On an - x86-64 DLL build (Gentoo Linux) this reduces the size of the text - segment of the DLL by 1208 bytes, about 0.6%. It also simplifies - maintenance by removing the declarations from pngpriv.h and allowing - easier changes to the internal interfaces. - Rebuilt configure scripts with automake-1.14.1 and autoconf-2.69 - in the tar distributions. - -Version 1.6.9beta02 [January 1, 2014] - Added checks for libpng 1.5 to pngvalid.c. This supports the use of - this version of pngvalid in libpng 1.5 - Merged with pngvalid.c from libpng-1.7 changes to create a single - pngvalid.c - Removed #error macro from contrib/tools/pngfix.c (Thomas Klausner). - Merged pngrio.c, pngtrans.c, pngwio.c, and pngerror.c with libpng-1.7.0 - Merged libpng-1.7.0 changes to make no-interlace configurations work - with test programs. - Revised pngvalid.c to support libpng 1.5, which does not support the - PNG_MAXIMUM_INFLATE_WINDOW option, so #define it out when appropriate in - pngvalid.c - Allow unversioned links created on install to be disabled in configure. - In configure builds 'make install' changes/adds links like png.h - and libpng.a to point to the newly installed, versioned, files (e.g. - libpng17/png.h and libpng17.a). Three new configure options and some - rearrangement of Makefile.am allow creation of these links to be disabled. - -Version 1.6.9beta03 [January 10, 2014] - Removed potentially misleading warning from png_check_IHDR(). - -Version 1.6.9beta04 [January 20, 2014] - Updated scripts/makefile.* to use CPPFLAGS (Cosmin). - Added clang attribute support (Cosmin). - -Version 1.6.9rc01 [January 28, 2014] - No changes. - -Version 1.6.9rc02 [January 30, 2014] - Quiet an uninitialized memory warning from VC2013 in png_get_png(). - -Version 1.6.9 [February 6, 2014] - -Version 1.6.10beta01 [February 9, 2014] - Backported changes from libpng-1.7.0beta30 and beta31: - Fixed a large number of instances where PNGCBAPI was omitted from - function definitions. - Added pngimage test program for png_read_png() and png_write_png() - with two new test scripts. - Removed dependence on !PNG_READ_EXPAND_SUPPORTED for calling - png_set_packing() in png_read_png(). - Fixed combination of ~alpha with shift. On read invert alpha, processing - occurred after shift processing, which causes the final values to be - outside the range that should be produced by the shift. Reversing the - order on read makes the two transforms work together correctly and mirrors - the order used on write. - Do not read invalid sBIT chunks. Previously libpng only checked sBIT - values on write, so a malicious PNG writer could therefore cause - the read code to return an invalid sBIT chunk, which might lead to - application errors or crashes. Such chunks are now skipped (with - chunk_benign_error). - Make png_read_png() and png_write_png() prototypes in png.h depend - upon PNG_READ_SUPPORTED and PNG_WRITE_SUPPORTED. - Support builds with unsupported PNG_TRANSFORM_* values. All of the - PNG_TRANSFORM_* values are always defined in png.h and, because they - are used for both read and write in some cases, it is not reliable - to #if out ones that are totally unsupported. This change adds error - detection in png_read_image() and png_write_image() to do a - png_app_error() if the app requests something that cannot be done - and it adds corresponding code to pngimage.c to handle such options - by not attempting to test them. - -Version 1.6.10beta02 [February 23, 2014] - Moved redefines of png_error(), png_warning(), png_chunk_error(), - and png_chunk_warning() from pngpriv.h to png.h to make them visible - to libpng-calling applications. - Moved OS dependent code from arm/arm_init.c, to allow the included - implementation of the ARM NEON discovery function to be set at - build-time and provide sample implementations from the current code in the - contrib/arm-neon subdirectory. The __linux__ code has also been changed to - compile and link on Android by using /proc/cpuinfo, and the old linux code - is in contrib/arm-neon/linux-auxv.c. The new code avoids POSIX and Linux - dependencies apart from opening /proc/cpuinfo and is C90 compliant. - Check for info_ptr == NULL early in png_read_end() so we don't need to - run all the png_handle_*() and depend on them to return if info_ptr == NULL. - This improves the performance of png_read_end(png_ptr, NULL) and makes - it more robust against future programming errors. - Check for __has_extension before using it in pngconf.h, to - support older Clang versions (Jeremy Sequoia). - Treat CRC error handling with png_set_crc_action(), instead of with - png_set_benign_errors(), which has been the case since libpng-1.6.0beta18. - Use a user warning handler in contrib/gregbook/readpng2.c instead of default, - so warnings will be put on stderr even if libpng has CONSOLE_IO disabled. - Added png_ptr->process_mode = PNG_READ_IDAT_MODE in png_push_read_chunk - after recognizing the IDAT chunk, which avoids an infinite loop while - reading a datastream whose first IDAT chunk is of zero-length. - This fixes CERT VU#684412 and CVE-2014-0333. - Don't recognize known sRGB profiles as sRGB if they have been hacked, - but don't reject them and don't issue a copyright violation warning. - -Version 1.6.10beta03 [February 25, 2014] - Moved some documentation from png.h to libpng.3 and libpng-manual.txt - Minor editing of contrib/arm-neon/README and contrib/examples/*.c - -Version 1.6.10rc01 [February 27, 2014] - Fixed typos in the manual and in scripts/pnglibconf.dfa (CFLAGS -> CPPFLAGS - and PNG_USR_CONFIG -> PNG_USER_CONFIG). - -Version 1.6.10rc02 [February 28, 2014] - Removed unreachable return statement after png_chunk_error() - in pngrutil.c - -Version 1.6.10rc03 [March 4, 2014] - Un-deprecated png_data_freer(). - -Version 1.6.10 [March 6, 2014] - No changes. - -Version 1.6.11beta01 [March 17, 2014] - Use "if (value != 0)" instead of "if (value)" consistently. - Changed ZlibSrcDir from 1.2.5 to 1.2.8 in projects/vstudio. - Moved configuration information from the manual to the INSTALL file. - -Version 1.6.11beta02 [April 6, 2014] - Removed #if/#else/#endif from inside two pow() calls in pngvalid.c because - they were handled improperly by Portland Group's PGI-14.1 - PGI-14.3 - when using its "__builtin_pow()" function. - Silence 'unused parameter' build warnings (Cosmin Truta). - $(CP) is now used alongside $(RM_F). Also, use 'copy' instead of 'cp' - where applicable, and applied other minor makefile changes (Cosmin). - Don't warn about invalid dimensions exceeding user limits (Cosmin). - Allow an easy replacement of the default pre-built configuration - header with a custom header, via the make PNGLIBCONF_H_PREBUILT - macro (Cosmin). - -Version 1.6.11beta03 [April 6, 2014] - Fixed a typo in pngrutil.c, introduced in libpng-1.5.6, that interferes - with "blocky" expansion of sub-8-bit interlaced PNG files (Eric Huss). - Optionally use __builtin_bswap16() in png_do_swap(). - -Version 1.6.11beta04 [April 19, 2014] - Made progressive reading of interlaced images consistent with the - behavior of the sequential reader and consistent with the manual, by - moving some code out of the PNG_READ_INTERLACING_SUPPORTED blocks. The - row_callback now receives the proper pass number and unexpanded rows, when - png_combine_row() isn't built or used, and png_set_interlace_handling() - is not called. - Allow PNG_sRGB_PROFILE_CHECKING = (-1) to mean no sRGB profile checking. - -Version 1.6.11beta05 [April 26, 2014] - Do not reject ICC V2 profiles that lack padding (Kai-Uwe Behrmann). - Relocated closing bracket of the sRGB profile test loop to avoid getting - "Not recognizing known sRGB profile that has been edited" warning for - ICC V2 profiles that lack the MD5 signature in the profile header. - -Version 1.6.11beta06 [May 19, 2014] - Added PNG_SKIP_sRGB_CHECK_PROFILE choice for png_set_option(). - -Version 1.6.11rc01 [May 27, 2014] - No changes. - -Version 1.6.11rc02 [June 3, 2014] - Test ZLIB_VERNUM instead of PNG_ZLIB_VERNUM in contrib/tools/pngfix.c - -Version 1.6.11 [June 5, 2014] - No changes. - -Version 1.6.12rc01 [June 6, 2014] - Relocated new code from 1.6.11beta06 in png.c to a point after the - declarations (Max Stepin). - -Version 1.6.12rc02 [June 7, 2014] - Changed file permissions of contrib/tools/intgamma.sh, - test-driver, and compile from 0644 to 0755 (Cosmin). - -Version 1.6.12rc03 [June 8, 2014] - Ensure "__has_attribute()" macro exists before trying to use it with - old clang compilers (MacPorts Ticket #43939). - -Version 1.6.12 [June 12, 2014] - No changes. - -Version 1.6.13beta01 [July 4, 2014] - Quieted -Wsign-compare and -Wclobber compiler warnings in - contrib/pngminus/*.c - Added "(void) png_ptr;" where needed in contrib/gregbook to quiet - compiler complaints about unused pointers. - Split a long output string in contrib/gregbook/rpng2-x.c. - Added "PNG_SET_OPTION" requirement for sRGB chunk support to pnglibconf.dfa, - Needed for write-only support (John Bowler). - Changed "if defined(__ARM_NEON__)" to - "if (defined(__ARM_NEON__) || defined(__ARM_NEON))" (James Wu). - Fixed clang no-warning builds: png_digit was defined but never used. - -Version 1.6.13beta02 [July 21, 2014] - Fixed an incorrect separator ("/" should be "\") in scripts/makefile.vcwin32 - (bug report from Wolfgang S. Kechel). Bug was introduced in libpng-1.6.11. - Also fixed makefile.bc32, makefile.bor, makefile.msc, makefile.intel, and - makefile.tc3 similarly. - -Version 1.6.13beta03 [August 3, 2014] - Removed scripts/makefile.elf. It has not worked since libpng-1.5.0beta14 - due to elimination of the PNG_FUNCTION_EXPORT and PNG_DATA_EXPORT - definitions from pngconf.h. - Ensure that CMakeLists.txt makes the target "lib" directory before making - symbolic link into it (SourceForge bug report #226 by Rolf Timmermans). - -Version 1.6.13beta04 [August 8, 2014] - Added opinion that the ECCN (Export Control Classification Number) for - libpng is EAR99 to the README file. - Eliminated use of "$<" in makefile explicit rules, when copying - $PNGLIBCONF_H_PREBUILT. This does not work on some versions of make; - bug introduced in libpng version 1.6.11. - -Version 1.6.13rc01 [August 14, 2014] - Made "ccopts" agree with "CFLAGS" in scripts/makefile.hp* and makefile.*sunu - -Version 1.6.13 [August 21, 2014] - No changes. - -Version 1.6.14beta01 [September 14, 2014] - Guard usage of png_ptr->options with #ifdef PNG_SET_OPTION_SUPPORTED. - Do not build contrib/tools/pngfix.c when PNG_SETJMP_NOT_SUPPORTED, - to allow "make" to complete without setjmp support (bug report by - Claudio Fontana) - Add "#include <setjmp.h>" to contrib/tools/pngfix.c (John Bowler) - -Version 1.6.14beta02 [September 18, 2014] - Use nanosleep() instead of usleep() in contrib/gregbook/rpng2-x.c - because usleep() is deprecated. - Define usleep() in contrib/gregbook/rpng2-x.c if not already defined - in unistd.h and nanosleep() is not available; fixes error introduced - in libpng-1.6.13. - Disable floating point exception handling in pngvalid.c when - PNG_FLOATING_ARITHMETIC is not supported (bug report by "zootus - at users.sourceforge.net"). - -Version 1.6.14beta03 [September 19, 2014] - Define FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW in pngvalid.c if not - already defined. Revert floating point exception handling in pngvalid.c - to version 1.6.14beta01 behavior. - -Version 1.6.14beta04 [September 27, 2014] - Fixed incorrect handling of the iTXt compression flag in pngrutil.c - (bug report by Shunsaku Hirata). Bug was introduced in libpng-1.6.0. - -Version 1.6.14beta05 [October 1, 2014] - Added "option READ_iCCP enables READ_COMPRESSED_TEXT" to pnglibconf.dfa - -Version 1.6.14beta06 [October 5, 2014] - Removed unused "text_len" parameter from private function png_write_zTXt(). - Conditionally compile some code in png_deflate_claim(), when - PNG_WARNINGS_SUPPORTED and PNG_ERROR_TEXT_SUPPORTED are disabled. - Replaced repeated code in pngpread.c with PNG_PUSH_SAVE_BUFFER_IF_FULL. - Added "chunk iTXt enables TEXT" and "chunk zTXt enables TEXT" - to pnglibconf.dfa. - Removed "option READ_COMPRESSED_TEXT enables READ_TEXT" from pnglibconf.dfa, - to make it possible to configure a libpng that supports iCCP but not TEXT. - -Version 1.6.14beta07 [October 7, 2014] - Removed "option WRITE_COMPRESSED_TEXT enables WRITE_TEXT" from pnglibconf.dfa - Only mark text chunks as written after successfully writing them. - -Version 1.6.14rc01 [October 15, 2014] - Fixed some typos in comments. - -Version 1.6.14rc02 [October 17, 2014] - Changed png_convert_to_rfc_1123() to png_convert_to_rfc_1123_buffer() - in the manual, to reflect the change made in libpng-1.6.0. - Updated README file to explain that direct access to the png_struct - and info_struct members has not been permitted since libpng-1.5.0. - -Version 1.6.14 [October 23, 2014] - No changes. - -Version 1.6.15beta01 [October 29, 2014] - Changed "if (!x)" to "if (x == 0)" and "if (x)" to "if (x != 0)" - Simplified png_free_data(). - Added missing "ptr = NULL" after some instances of png_free(). - -Version 1.6.15beta02 [November 1, 2014] - Changed remaining "if (!x)" to "if (x == 0)" and "if (x)" to "if (x != 0)" - -Version 1.6.15beta03 [November 3, 2014] - Added PNG_USE_ARM_NEON configuration flag (Marcin Juszkiewicz). - -Version 1.6.15beta04 [November 4, 2014] - Removed new PNG_USE_ARM_NEON configuration flag and made a one-line - revision to configure.ac to support ARM on aarch64 instead (John Bowler). - -Version 1.6.15beta05 [November 5, 2014] - Use png_get_libpng_ver(NULL) instead of PNG_LIBPNG_VER_STRING in - example.c, pngtest.c, and applications in the contrib directory. - Fixed an out-of-range read in png_user_version_check() (Bug report from - Qixue Xiao, CVE-2015-8540). - Simplified and future-proofed png_user_version_check(). - Fixed GCC unsigned int->float warnings. Various versions of GCC - seem to generate warnings when an unsigned value is implicitly - converted to double. This is probably a GCC bug but this change - avoids the issue by explicitly converting to (int) where safe. - Free all allocated memory in pngimage. The file buffer cache was left - allocated at the end of the program, harmless but it causes memory - leak reports from clang. - Fixed array size calculations to avoid warnings. At various points - in the code the number of elements in an array is calculated using - sizeof. This generates a compile time constant of type (size_t) which - is then typically assigned to an (unsigned int) or (int). Some versions - of GCC on 64-bit systems warn about the apparent narrowing, even though - the same compiler does apparently generate the correct, in-range, - numeric constant. This adds appropriate, safe, casts to make the - warnings go away. - -Version 1.6.15beta06 [November 6, 2014] - Reverted use png_get_libpng_ver(NULL) instead of PNG_LIBPNG_VER_STRING - in the manual, example.c, pngtest.c, and applications in the contrib - directory. It was incorrect advice. - -Version 1.6.15beta07 [November 7, 2014] - Removed #ifdef PNG_16BIT_SUPPORTED/#endif around png_product2(); it is - needed by png_reciprocal2(). - Added #ifdef PNG_16BIT_SUPPORTED/#endif around png_log16bit() and - png_do_swap(). - Changed all "#endif /* PNG_FEATURE_SUPPORTED */" to "#endif /* FEATURE */" - -Version 1.6.15beta08 [November 8, 2014] - More housecleaning in *.h - -Version 1.6.15rc01 [November 13, 2014] - -Version 1.6.15rc02 [November 14, 2014] - The macros passed in the command line to Borland make were ignored if - similarly-named macros were already defined in makefiles. This behavior - is different from POSIX make and other make programs. Surround the - macro definitions with ifndef guards (Cosmin). - -Version 1.6.15rc03 [November 16, 2014] - Added "-D_CRT_SECURE_NO_WARNINGS" to CFLAGS in scripts/makefile.vcwin32. - Removed the obsolete $ARCH variable from scripts/makefile.darwin. - -Version 1.6.15 [November 20, 2014] - No changes. - -Version 1.6.16beta01 [December 14, 2014] - Added ".align 2" to arm/filter_neon.S to support old GAS assemblers that - don't do alignment correctly. - Revised Makefile.am and scripts/symbols.dfn to work with MinGW/MSYS - (Bob Friesenhahn). - -Version 1.6.16beta02 [December 15, 2014] - Revised Makefile.am and scripts/*.dfn again to work with MinGW/MSYS; - renamed scripts/*.dfn to scripts/*.c (John Bowler). - -Version 1.6.16beta03 [December 21, 2014] - Quiet a "comparison always true" warning in pngstest.c (John Bowler). - -Version 1.6.16rc01 [December 21, 2014] - Restored a test on width that was removed from png.c at libpng-1.6.9 - (Bug report by Alex Eubanks, CVE-2015-0973). - -Version 1.6.16rc02 [December 21, 2014] - Undid the update to pngrutil.c in 1.6.16rc01. - -Version 1.6.16rc03 [December 21, 2014] - Fixed an overflow in png_combine_row() with very wide interlaced images - (Bug report and fix by John Bowler, CVE-2014-9495). - -Version 1.6.16 [December 22, 2014] - No changes. - -Version 1.6.17beta01 [January 29, 2015] - Removed duplicate PNG_SAFE_LIMITS_SUPPORTED handling from pngconf.h - Corrected the width limit calculation in png_check_IHDR(). - Removed user limits from pngfix. Also pass NULL pointers to - png_read_row to skip the unnecessary row de-interlace stuff. - Added testing of png_set_packing() to pngvalid.c - Regenerated configure scripts in the *.tar distributions with libtool-2.4.4 - Implement previously untested cases of libpng transforms in pngvalid.c - Fixed byte order in png_do_read_filler() with 16-bit input. Previously - the high and low bytes of the filler, from png_set_filler() or from - png_set_add_alpha(), were read in the wrong order. - Made the check for out-of-range values in png_set_tRNS() detect - values that are exactly 2^bit_depth, and work on 16-bit platforms. - Merged some parts of libpng-1.6.17beta01 and libpng-1.7.0beta47. - Added #ifndef __COVERITY__ where needed in png.c, pngrutil.c and - pngset.c to avoid warnings about dead code. - Added "& 0xff" to many instances of expressions that are typecast - to (png_byte), to avoid Coverity warnings. - -Version 1.6.17beta02 [February 7, 2015] - Work around one more Coverity-scan dead-code warning. - Do not build png_product2() when it is unused. - -Version 1.6.17beta03 [February 17, 2015] - Display user limits in the output from pngtest. - Eliminated the PNG_SAFE_LIMITS macro and restored the 1-million-column - and 1-million-row default limits in pnglibconf.dfa, that can be reset - by the user at build time or run time. This provides a more robust - defense against DOS and as-yet undiscovered overflows. - -Version 1.6.17beta04 [February 21, 2015] - Added PNG_WRITE_CUSTOMIZE_COMPRESSION_SUPPORTED macro, on by default. - Allow user to call png_get_IHDR() with NULL arguments (Reuben Hawkins). - Rebuilt configure scripts with automake-1.15 and libtool-2.4.6 - -Version 1.6.17beta05 [February 25, 2015] - Restored compiling of png_reciprocal2 with PNG_NO_16BIT. - -Version 1.6.17beta06 [February 27, 2015] - Moved png_set_filter() prototype into a PNG_WRITE_SUPPORTED block - of png.h. - Avoid runtime checks when converting integer to png_byte with - Visual Studio (Sergey Kosarevsky) - -Version 1.6.17rc01 [March 4, 2015] - No changes. - -Version 1.6.17rc02 [March 9, 2015] - Removed some comments that the configure script did not handle - properly from scripts/pnglibconf.dfa and pnglibconf.h.prebuilt. - Free the unknown_chunks structure even when it contains no data. - -Version 1.6.17rc03 [March 12, 2015] - Updated CMakeLists.txt to add OSX framework, change YES/NO to ON/OFF - for consistency, and remove some useless tests (Alexey Petruchik). - -Version 1.6.17rc04 [March 16, 2015] - Remove pnglibconf.h, pnglibconf.c, and pnglibconf.out instead of - pnglibconf.* in "make clean" (Cosmin). - Fix bug in calculation of maxbits, in png_write_sBIT, introduced - in libpng-1.6.17beta01 (John Bowler). - -Version 1.6.17rc05 [March 21, 2015] - Define PNG_FILTER_* and PNG_FILTER_VALUE_* in png.h even when WRITE - is not supported (John Bowler). This fixes an error introduced in - libpng-1.6.17beta06. - Reverted "& 0xff" additions of version 1.6.17beta01. Libpng passes - the Coverity scan without them. - -Version 1.6.17rc06 [March 23, 2015] - Remove pnglibconf.dfn and pnglibconf.pre with "make clean". - Reformatted some "&0xff" instances to "& 0xff". - Fixed simplified 8-bit-linear to sRGB alpha. The calculated alpha - value was wrong. It's not clear if this affected the final stored - value; in the obvious code path the upper and lower 8-bits of the - alpha value were identical and the alpha was truncated to 8-bits - rather than dividing by 257 (John Bowler). - -Version 1.6.17 [March 26, 2015] - No changes. - -Version 1.6.18beta01 [April 1, 2015] - Removed PNG_SET_CHUNK_[CACHE|MALLOC]_LIMIT_SUPPORTED macros. They - have been combined with PNG_SET_USER_LIMITS_SUPPORTED (resolves - bug report by Andrew Church). - Fixed rgb_to_gray checks and added tRNS checks to pngvalid.c. This - fixes some arithmetic errors that caused some tests to fail on - some 32-bit platforms (Bug reports by Peter Breitenlohner [i686] - and Petr Gajdos [i586]). - -Version 1.6.18beta02 [April 26, 2015] - Suppressed some warnings from the Borland C++ 5.5.1/5.82 compiler - (Bug report by Viktor Szakats). - -Version 1.6.18beta03 [May 6, 2015] - Replaced "unexpected" with an integer (0xabadca11) in pngset.c - where a long was expected, to avoid a compiler warning when PNG_DEBUG > 1. - Added contrib/examples/simpleover.c, to demonstrate how to handle - alpha compositing of multiple images, using the "simplified API" - and an example PNG generation tool, contrib/examples/genpng.c - (John Bowler). - -Version 1.6.18beta04 [May 20, 2015] - PNG_RELEASE_BUILD replaces tests where the code depended on the build base - type and can be defined on the command line, allowing testing in beta - builds (John Bowler). - Avoid Coverity issue 80858 (REVERSE NULL) in pngtest.c PNG_DEBUG builds. - Avoid a harmless potential integer overflow in png_XYZ_from_xy() (Bug - report from Christopher Ferris). - -Version 1.6.18beta05 [May 31, 2015] - Backport filter selection code from libpng-1.7.0beta51, to combine - sub_row, up_row, avg_row, and paeth_row into try_row and tst_row. - Changed png_voidcast(), etc., to voidcast(), etc., in contrib/tools/pngfix.c - to avoid confusion with the libpng private macros. - Fixed old cut&paste bug in the weighted filter selection code in - pngwutil.c, introduced in libpng-0.95, March 1997. - -Version 1.6.18beta06 [June 1, 2015] - Removed WRITE_WEIGHTED_FILTERED code, to save a few kbytes of the - compiled library size. It never worked properly and as far as we can - tell, no one uses it. The png_set_filter_heuristics() and - png_set_filter_heuristics_fixed() APIs are retained but deprecated - and do nothing. - -Version 1.6.18beta07 [June 6, 2015] - Removed non-working progressive reader 'skip' function. This - function has apparently never been used. It was implemented - to support back-door modification of png_struct in libpng-1.4.x - but (because it does nothing and cannot do anything) was apparently - never tested (John Bowler). - Fixed cexcept.h in which GCC 5 now reports that one of the auto - variables in the Try macro needs to be volatile to prevent value - being lost over the setjmp (John Bowler). - Fixed NO_WRITE_FILTER and -Wconversion build breaks (John Bowler). - Fix g++ build breaks (John Bowler). - Quieted some Coverity issues in pngfix.c, png-fix-itxt.c, pngvalid.c, - pngstest.c, and pngimage.c. Most seem harmless, but png-fix-itxt - would only work with iTXt chunks with length 255 or less. - Added #ifdef's to contrib/examples programs so people don't try - to compile them without the minimum required support enabled - (suggested by Flavio Medeiros). - -Version 1.6.18beta08 [June 30, 2015] - Eliminated the final two Coverity defects (insecure temporary file - handling in contrib/libtests/pngstest.c; possible overflow of - unsigned char in contrib/tools/png-fix-itxt.c). To use the "secure" - file handling, define PNG_USE_MKSTEMP, otherwise "tmpfile()" will - be used. - Removed some unused WEIGHTED_FILTER macros from png.h and pngstruct.h - -Version 1.6.18beta09 [July 5, 2015] - Removed some useless typecasts from contrib/tools/png-fix-itxt.c - Fixed a new signed-unsigned comparison in pngrtran.c (Max Stepin). - Replaced arbitrary use of 'extern' with #define PNG_LINKAGE_*. To - preserve API compatibility, the new defines all default to "extern" - (requested by Jan Nijtmans). - -Version 1.6.18rc01 [July 9, 2015] - Belatedly added Mans Rullgard and James Yu to the list of Contributing - Authors. - -Version 1.6.18rc02 [July 12, 2015] - Restored unused FILTER_HEURISTIC macros removed at libpng-1.6.18beta08 - to png.h to avoid compatibility warnings. - -Version 1.6.18rc03 [July 15, 2015] - Minor changes to the man page - -Version 1.6.18 [July 23, 2015] - No changes. - -Version 1.6.19beta01 [July 30, 2015] - Updated obsolete information about the simplified API macros in the - manual pages (Bug report by Arc Riley). - Avoid potentially dereferencing NULL info_ptr in png_info_init_3(). - Rearranged png.h to put the major sections in the same order as - in libpng17. - Eliminated unused PNG_COST_SHIFT, PNG_WEIGHT_SHIFT, PNG_COST_FACTOR, and - PNG_WEIGHT_FACTOR macros. - Suppressed some warnings from the Borland C++ 5.5.1/5.82 compiler - (Bug report by Viktor Szakats). Several warnings remain and are - unavoidable, where we test for overflow. - Fixed potential leak of png_pixels in contrib/pngminus/pnm2png.c - Fixed uninitialized variable in contrib/gregbook/rpng2-x.c - -Version 1.6.19beta02 [August 19, 2015] - Moved config.h.in~ from the "libpng_autotools_files" list to the - "libpng_autotools_extra" list in autogen.sh because it was causing a - false positive for missing files (bug report by Robert C. Seacord). - Removed unreachable "break" statements in png.c, pngread.c, and pngrtran.c - to suppress clang warnings (Bug report by Viktor Szakats). - Fixed some bad links in the man page. - Changed "n bit" to "n-bit" in comments. - Added signed/unsigned 16-bit safety net. This removes the dubious - 0x8000 flag definitions on 16-bit systems. They aren't supported - yet the defs *probably* work, however it seems much safer to do this - and be advised if anyone, contrary to advice, is building libpng 1.6 - on a 16-bit system. It also adds back various switch default clauses - for GCC; GCC errors out if they are not present (with an appropriately - high level of warnings). - Safely convert num_bytes to a png_byte in png_set_sig_bytes() (Robert - Seacord). - Fixed the recently reported 1's complement security issue by replacing - the value that is illegal in the PNG spec, in both signed and unsigned - values, with 0. Illegal unsigned values (anything greater than or equal - to 0x80000000) can still pass through, but since these are not illegal - in ANSI-C (unlike 0x80000000 in the signed case) the checking that - occurs later can catch them (John Bowler). - -Version 1.6.19beta03 [September 26, 2015] - Fixed png_save_int_32 when int is not 2's complement (John Bowler). - Updated libpng16 with all the recent test changes from libpng17, - including changes to pngvalid.c to ensure that the original, - distributed, version of contrib/visupng/cexcept.h can be used - (John Bowler). - pngvalid contains the correction to the use of SAVE/STORE_ - UNKNOWN_CHUNKS; a bug revealed by changes in libpng 1.7. More - tests contain the --strict option to detect warnings and the - pngvalid-standard test has been corrected so that it does not - turn on progressive-read. There is a separate test which does - that. (John Bowler) - Also made some signed/unsigned fixes. - Make pngstest error limits version specific. Splitting the machine - generated error structs out to a file allows the values to be updated - without changing pngstest.c itself. Since libpng 1.6 and 1.7 have - slightly different error limits this simplifies maintenance. The - makepngs.sh script has also been updated to more accurately reflect - current problems in libpng 1.7 (John Bowler). - Incorporated new test PNG files into make check. tests/pngstest-* - are changed so that the new test files are divided into 8 groups by - gamma and alpha channel. These tests have considerably better code - and pixel-value coverage than contrib/pngsuite; however,coverage is - still incomplete (John Bowler). - Removed the '--strict' in 1.6 because of the double-gamma-correction - warning, updated pngstest-errors.h for the errors detected with the - new contrib/testspngs PNG test files (John Bowler). - -Version 1.6.19beta04 [October 15, 2015] - Worked around rgb-to-gray issues in libpng 1.6. The previous - attempts to ignore the errors in the code aren't quite enough to - deal with the 'channel selection' encoding added to libpng 1.7; abort. - pngvalid.c is changed to drop this encoding in prior versions. - Fixed 'pow' macros in pngvalid.c. It is legal for 'pow' to be a - macro, therefore the argument list cannot contain preprocessing - directives. Make sure pow is a function where this happens. This is - a minimal safe fix, the issue only arises in non-performance-critical - code (bug report by Curtis Leach, fix by John Bowler). - Added sPLT support to pngtest.c - -Version 1.6.19rc01 [October 23, 2015] - No changes. - -Version 1.6.19rc02 [October 31, 2015] - Prevent setting or writing over-length PLTE chunk (Cosmin Truta). - Silently truncate over-length PLTE chunk while reading. - Libpng incorrectly calculated the output rowbytes when the application - decreased either the number of channels or the bit depth (or both) in - a user transform. This was safe; libpng overallocated buffer space - (potentially by quite a lot; up to 4 times the amount required) but, - from 1.5.4 on, resulted in a png_error (John Bowler). - -Version 1.6.19rc03 [November 3, 2015] - Fixed some inconsequential cut-and-paste typos in png_set_cHRM_XYZ_fixed(). - Clarified COPYRIGHT information to state explicitly that versions - are derived from previous versions. - Removed much of the long list of previous versions from png.h and - libpng.3. - -Version 1.6.19rc04 [November 5, 2015] - Fixed new bug with CRC error after reading an over-length palette - (bug report by Cosmin Truta) (CVE-2015-8126). - -Version 1.6.19 [November 12, 2015] - Cleaned up coding style in png_handle_PLTE(). - -Version 1.6.20beta01 [November 20, 2015] - Avoid potential pointer overflow/underflow in png_handle_sPLT() and - png_handle_pCAL() (Bug report by John Regehr). - -Version 1.6.20beta02 [November 23, 2015] - Fixed incorrect implementation of png_set_PLTE() that uses png_ptr - not info_ptr, that left png_set_PLTE() open to the CVE-2015-8126 - vulnerability. Fixes CVE-2015-8472. - -Version 1.6.20beta03 [November 24, 2015] - Backported tests from libpng-1.7.0beta69. - -Version 1.6.20rc01 [November 26, 2015] - Fixed an error in handling of bad zlib CMINFO field in pngfix, found by - American Fuzzy Lop, reported by Brian Carpenter. inflate() doesn't - immediately fault a bad CMINFO field; instead a 'too far back' error - happens later (at least some times). pngfix failed to limit CMINFO to - the allowed values but then assumed that window_bits was in range, - triggering an assert. The bug is mostly harmless; the PNG file cannot - be fixed. - -Version 1.6.20rc02 [November 29, 2015] - In libpng 1.6 zlib initialization was changed to use the window size - in the zlib stream, not a fixed value. This causes some invalid images, - where CINFO is too large, to display 'correctly' if the rest of the - data is valid. This provides a workaround for zlib versions where the - error arises (ones that support the API change to use the window size - in the stream). - -Version 1.6.20 [December 3, 2015] - No changes. - -Version 1.6.21beta01 [December 11, 2015] - Fixed syntax "$(command)" in tests/pngstest that some shells other than - bash could not parse (Bug report by Nelson Beebe). Use `command` instead. - -Version 1.6.21beta02 [December 14, 2015] - Moved png_check_keyword() from pngwutil.c to pngset.c - Removed LE/BE dependencies in pngvalid, to 'fix' the current problem - in the BigEndian tests by not testing it, making the BE code the same - as the LE version. - Fixes to pngvalid for various reduced build configurations (eliminate unused - statics) and a fix for the case in rgb_to_gray when the digitize option - reduces graylo to 0, producing a large error. - -Version 1.6.21beta03 [December 18, 2015] - Widened the 'limit' check on the internally calculated error limits in - the 'DIGITIZE' case (the code used prior to 1.7 for rgb_to_gray error - checks) and changed the check to only operate in non-release builds - (base build type not RC or RELEASE.) - Fixed undefined behavior in pngvalid.c, undefined because - (png_byte) << shift is undefined if it changes the signed bit - (because png_byte is promoted to int). The libpng exported functions - png_get_uint_32 and png_get_uint_16 handle this. (Bug reported by - David Drysdale as a result of reports from UBSAN in clang 3.8). - This changes pngvalid to use BE random numbers; this used to produce - errors but these should not be fixed as a result of the previous changes. - -Version 1.6.21rc01 [January 4, 2016] - In projects/vstudio, combined readme.txt and WARNING into README.txt - -Version 1.6.21rc02 [January 7, 2016] - Relocated assert() in contrib/tools/pngfix.c, bug found by American - Fuzzy Lop, reported by Brian Carpenter. - Marked 'limit' UNUSED in transform_range_check(). This only affects - release builds. - -Version 1.6.21 [January 15, 2016] - Worked around a false-positive Coverity issue in pngvalid.c. - -Version 1.6.22beta01 [January 23, 2016] - Changed PNG_USE_MKSTEMP to __COVERITY__ to select alternate - "tmpfile()" implementation in contrib/libtests/pngstest.c - Fixed NO_STDIO build of pngunknown.c to skip calling png_init_io() - if there is no stdio.h support. - Added a png_image_write_to_memory() API and a number of assist macros - to allow an application that uses the simplified API write to bypass - stdio and write directly to memory. - Added some warnings (png.h) and some check code to detect *possible* - overflow in the ROW_STRIDE and simplified image SIZE macros. This - disallows image width/height/format that *might* overflow. This is - a quiet API change that limits in-memory image size (uncompressed) to - less than 4GByte and image row size (stride) to less than 2GByte. - Revised workaround for false-positive Coverity issue in pngvalid.c. - -Version 1.6.22beta02 [February 8, 2016] - Only use exit(77) in configure builds. - Corrected error in PNG_IMAGE_PNG_SIZE_MAX. This new macro underreported - the palette size because it failed to take into account that the memory - palette has to be expanded to full RGB when it is written to PNG. - Updated CMakeLists.txt, added supporting scripts/gen*.cmake.in - and test.cmake.in (Roger Leigh). - Relaxed limit checks on gamma values in pngrtran.c. As suggested in - the comments gamma values outside the range currently permitted - by png_set_alpha_mode are useful for HDR data encoding. These values - are already permitted by png_set_gamma so it is reasonable caution to - extend the png_set_alpha_mode range as HDR imaging systems are starting - to emerge. - -Version 1.6.22beta03 [March 9, 2016] - Added a common-law trademark notice and export control information - to the LICENSE file, png.h, and the man page. - Restored "& 0xff" in png_save_uint_16() and png_save_uint_32() that - were accidentally removed from libpng-1.6.17. - Changed PNG_INFO_cHNK and PNG_FREE_cHNK from 0xnnnn to 0xnnnnU in png.h - (Robert C. Seacord). - Removed dubious "#if INT_MAX" test from png.h that was added to - libpng-1.6.19beta02 (John Bowler). - Add ${INCLUDES} in scripts/genout.cmake.in (Bug report by Nixon Kwok). - Updated LICENSE to say files in the contrib directory are not - necessarily under the libpng license, and that some makefiles have - other copyright owners. - Added INTEL-SSE2 support (Mike Klein and Matt Sarett, Google, Inc.). - Made contrib/libtests/timepng more robust. The code no longer gives - up/fails on invalid PNG data, it just skips it (with error messages). - The code no longer fails on PNG files with data beyond IEND. Options - exist to use png_read_png (reading the whole image, not by row) and, in - that case, to apply any of the supported transforms. This makes for - more realistic testing; the decoded data actually gets used in a - meaningful fashion (John Bowler). - Fixed some misleading indentation (Krishnaraj Bhat). - -Version 1.6.22beta04 [April 5, 2016] - Force GCC compilation to C89 if needed (Dagobert Michelsen). - SSE filter speed improvements for bpp=3: - memcpy-free implementations of load3() / store3(). - call load3() only when needed at the end of a scanline. - -Version 1.6.22beta05 [April 27, 2016] - Added PNG_FAST_FILTERS macro (defined as - PNG_FILTER_NONE|PNG_FILTER_SUB|PNG_FILTER_UP). - Various fixes for contrib/libtests/timepng.c - Moved INTEL-SSE code from pngpriv.h into contrib/intel/intel_sse.patch. - Fixed typo (missing underscore) in #define PNG_READ_16_TO_8_SUPPORTED - (Bug report by Y.Ohashik). - -Version 1.6.22beta06 [May 5, 2016] - Rebased contrib/intel_sse.patch. - Quieted two Coverity issues in contrib/libtests/timepng.c. - Fixed issues with scripts/genout.cmake.in (David Capello, Nixon Kwok): - Added support to use multiple directories in ZLIBINCDIR variable, - Fixed CMAKE_C_FLAGS with multiple values when genout is compiled on MSVC, - Fixed pnglibconf.c compilation on OS X including the sysroot path. - -Version 1.6.22rc01 [May 14, 2016] - No changes. - -Version 1.6.22rc02 [May 16, 2016] - Removed contrib/timepng from default build; it does not build on platforms - that don't supply clock_gettime(). - -Version 1.6.22rc03 [May 17, 2016] - Restored contrib/timepng to default build but check for the presence - of clock_gettime() in configure.ac and Makefile.am. - -Version 1.6.22 [May 26, 2016] - No changes. - -Version 1.6.23beta01 [May 29, 2016] - Stop a potential memory leak in png_set_tRNS() (Bug report by Ted Ying). - Fixed the progressive reader to handle empty first IDAT chunk properly - (patch by Timothy Nikkel). This bug was introduced in libpng-1.6.0 and - only affected the libpng16 branch. - Added tests in pngvalid.c to check zero-length IDAT chunks in various - positions. Fixed the sequential reader to handle these more robustly - (John Bowler). - -Version 1.6.23rc01 [June 2, 2016] - Corrected progressive read input buffer in pngvalid.c. The previous version - the code invariably passed just one byte at a time to libpng. The intent - was to pass a random number of bytes in the range 0..511. - Moved sse2 prototype from pngpriv.h to contrib/intel/intel_sse.patch. - Added missing ")" in pngerror.c (Matt Sarrett). - -Version 1.6.23rc02 [June 4, 2016] - Fixed undefined behavior in png_push_save_buffer(). Do not call - memcpy() with a null source, even if count is zero (Leon Scroggins III). - -Version 1.6.23 [June 9, 2016] - Fixed bad link to RFC2083 in png.5 (Nikola Forro). - -Version 1.6.24beta01 [June 11, 2016] - Avoid potential overflow of the PNG_IMAGE_SIZE macro. This macro - is not used within libpng, but is used in some of the examples. - -Version 1.6.24beta02 [June 23, 2016] - Correct filter heuristic overflow handling. This was broken when the - write filter code was moved out-of-line; if there is a single filter and - the heuristic sum overflows the calculation of the filtered line is not - completed. In versions prior to 1.6 the code was duplicated in-line - and the check not performed, so the filter operation completed; however, - in the multi-filter case where the sum is performed the 'none' filter would - be selected if all the sums overflowed, even if it wasn't in the filter - list. The fix to the first problem is simply to provide PNG_SIZE_MAX as - the current lmins sum value; this means the sum can never exceed it and - overflows silently. A reasonable compiler that does choose to inline - the code will simply eliminate the sum check. - The fix to the second problem is to use high precision arithmetic (this is - implemented in 1.7), however a simple safe fix here is to chose the lowest - numbered filter in the list from png_set_filter (this only works if the - first problem is also fixed) (John Bowler). - Use a more efficient absolute value calculation on SSE2 (Matthieu Darbois). - Fixed the case where PNG_IMAGE_BUFFER_SIZE can overflow in the application - as a result of the application using an increased 'row_stride'; previously - png_image_finish_read only checked for overflow on the base calculation of - components. (I.e. it checked for overflow of a 32-bit number on the total - number of pixel components in the output format, not the possibly padded row - length and not the number of bytes, which for linear formats is twice the - number of components.) - MSVC does not like '-(unsigned)', so replaced it with 0U-(unsigned) - MSVC does not like (uInt) = -(unsigned) (i.e. as an initializer), unless - the conversion is explicitly invoked by a cast. - Put the SKIP definition in the correct place. It needs to come after the - png.h include (see all the other .c files in contrib/libtests) because it - depends on PNG_LIBPNG_VER. - Removed the three compile warning options from the individual project - files into the zlib.props globals. It increases the warning level from 4 - to All and adds a list of the warnings that need to be turned off. This is - semi-documentary; the intent is to tell libpng users which warnings have - been examined and judged non-fixable at present. The warning about - structure padding is fixable, but it would be a signficant change (moving - structure members around). - -Version 1.6.24beta03 [July 4, 2016] - Optimized absolute value calculation in filter selection, similar to - code in the PAETH decoder in pngrutil.c. Build with PNG_USE_ABS to - use this. - Added pngcp to the build together with a pngcp.dfa configuration test. - Added high resolution timing to pngcp. - Added "Common linking failures" section to INSTALL. - Relocated misplaced #endif in png.c sRGB profile checking. - Fixed two Coverity issues in pngcp.c. - -Version 1.6.24beta04 [July 8, 2016] - Avoid filter-selection heuristic sum calculations in cases where only one - filter is a candidate for selection. This trades off code size (added - private png_setup_*_row_only() functions) for speed. - -Version 1.6.24beta05 [July 13, 2016] - Fixed some indentation to comply with our coding style. - Added contrib/tools/reindent. - -Version 1.6.24beta06 [July 18, 2016] - Fixed more indentation to comply with our coding style. - Eliminated unnecessary tests of boolean png_isaligned() vs 0. - -Version 1.6.24rc01 [July 25, 2016] - No changes. - -Version 1.6.24rc02 [August 1, 2016] - Conditionally compile SSE2 headers in contrib/intel/intel_sse.patch - Conditionally compile png_decompress_chunk(). - -Version 1.6.24rc03 [August 2, 2016] - Conditionally compile ARM_NEON headers in pngpriv.h - Updated contrib/intel/intel_sse.patch - -Version 1.6.24[August 4, 2016] - No changes. - -Version 1.6.25beta01 [August 12, 2016] - Reject oversized iCCP profile immediately. - Cleaned up PNG_DEBUG compile of pngtest.c. - Conditionally compile png_inflate(). - -Version 1.6.25beta02 [August 18, 2016] - Don't install pngcp; it conflicts with pngcp in the pngtools package. - Minor editing of INSTALL, (whitespace, added copyright line) - -Version 1.6.25rc01 [August 24, 2016] - No changes. - -Version 1.6.25rc02 [August 29, 2016] - Added MIPS support (Mandar Sahastrabuddhe <Mandar.Sahastrabuddhe@imgtec.com>). - Only the UP filter is currently implemented. - -Version 1.6.25rc03 [August 29, 2016] - Rebased contrib/intel/intel_sse.patch after the MIPS implementation. - -Version 1.6.25rc04 [August 30, 2016] - Added MIPS support for SUB, AVG, and PAETH filters (Mandar Sahastrabuddhe). - -Version 1.6.25rc05 [August 30, 2016] - Rebased contrib/intel/intel_sse.patch after the MIPS implementation update.. - -Version 1.6.25 [September 1, 2016] - No changes. - -Version 1.6.26beta01 [September 26, 2016] - Fixed handling zero length IDAT in pngfix (bug report by Agostino Sarubbo, - bugfix by John Bowler). - Do not issue a png_error() on read in png_set_pCAL() because png_handle_pCAL - has allocated memory that libpng needs to free. - Conditionally compile png_set_benign_errors() in pngread.c and pngtest.c - Issue a png_benign_error instead of a png_error on ADLER32 mismatch - while decoding compressed data chunks. - Changed PNG_ZLIB_VERNUM to ZLIB_VERNUM in pngpriv.h, pngstruct.h, and - pngrutil.c. - If CRC handling of critical chunks has been set to PNG_CRC_QUIET_USE, - ignore the ADLER32 checksum in the IDAT chunk as well as the chunk CRCs. - Issue png_benign_error() on ADLER32 checksum mismatch instead of png_error(). - Add tests/badcrc.png and tests/badadler.png to tests/pngtest. - Merged pngtest.c with libpng-1.7.0beta84/pngtest.c - -Version 1.6.26beta02 [October 1, 2016] - Updated the documentation about CRC and ADLER32 handling. - Quieted 117 warnings from clang-3.8 in pngtrans.c, pngread.c, - pngwrite.c, pngunknown.c, and pngvalid.c. - Quieted 58 (out of 144) -Wconversion compiler warnings by changing - flag definitions in pngpriv.h from 0xnnnn to 0xnnnnU and trivial changes - in png.c, pngread.c, and pngwutil.c. - -Version 1.6.26beta03 [October 2, 2016] - Removed contrib/libtests/*.orig and *.rej that slipped into the tarballs. - Quieted the 86 remaining -Wconversion compiler warnings by - revising the png_isaligned() macro and trivial changes in png.c, - pngerror.c, pngget.c, pngmem.c, pngset.c, pngrtran.c, pngrutil.c, - pngwtran.c, pngwrite.c, and pngwutil.c. - -Version 1.6.26beta04 [October 3, 2016] - Quieted (bogus?) clang warnings about "absolute value has no effect" - when PNG_USE_ABS is defined. - Fixed offsets in contrib/intel/intel_sse.patch - -Version 1.6.26beta05 [October 6, 2016] - Changed integer constant 4294967294 to unsigned 4294967294U in pngconf.h - to avoid a signed/unsigned compare in the preprocessor. - -Version 1.6.26beta06 [October 7, 2016] - Use zlib-1.2.8.1 inflateValidate() instead of inflateReset2() to - optionally avoid ADLER32 evaluation. - -Version 1.6.26rc01 [October 12, 2016] - No changes. - -Version 1.6.26 [October 20, 2016] - Cosmetic change, "ptr != 0" to "ptr != NULL" in png.c and pngrutil.c - Despammed email addresses (replaced "@" with " at "). - -Version 1.6.27beta01 [November 2, 2016] - Restrict the new ADLER32-skipping to IDAT chunks. It broke iCCP chunk - handling: an erroneous iCCP chunk would throw a png_error and reject the - entire PNG image instead of rejecting just the iCCP chunk with a warning, - if built with zlib-1.2.8.1. - -Version 1.6.27rc01 [December 27, 2016] - Control ADLER32 checking with new PNG_IGNORE_ADLER32 option. Fixes - an endless loop when handling erroneous ADLER32 checksums; bug - introduced in libpng-1.6.26. - Removed the use of a macro containing the pre-processor 'defined' - operator. It is unclear whether this is valid; a macro that - "generates" 'defined' is not permitted, but the use of the word - "generates" within the C90 standard seems to imply more than simple - substitution of an expression itself containing a well-formed defined - operation. - Added ARM support to CMakeLists.txt (Andreas Franek). - -Version 1.6.27 [December 29, 2016] - Fixed a potential null pointer dereference in png_set_text_2() (bug report - and patch by Patrick Keshishian, CVE-2016-10087). - -Version 1.6.28rc01 [January 3, 2017] - Fixed arm/aarch64 detection in CMakeLists.txt (Gianfranco Costamagna). - Added option to Cmake build allowing a custom location of zlib to be - specified in a scenario where libpng is being built as a subproject - alongside zlib by another project (Sam Serrels). - Changed png_ptr->options from a png_byte to png_uint_32, to accomodate - up to 16 options. - -Version 1.6.28rc02 [January 4, 2017] - Added "include(GNUInstallDirs)" to CMakeLists.txt (Gianfranco Costamagna). - Moved SSE2 optimization code into the main libpng source directory. - Configure libpng with "configure --enable-intel-sse" or compile - libpng with "-DPNG_INTEL_SSE" in CPPFLAGS to enable it. - -Version 1.6.28rc03 [January 4, 2017] - Backed out the SSE optimization and last CMakeLists.txt to allow time for QA. - -Version 1.6.28 [January 5, 2017] - No changes. - -Version 1.6.29beta01 [January 12, 2017] - Readded "include(GNUInstallDirs)" to CMakeLists.txt (Gianfranco Costamagna). - Moved SSE2 optimization code into the main libpng source directory. - Configure libpng with "configure --enable-intel-sse" or compile - libpng with "-DPNG_INTEL_SSE" in CPPFLAGS to enable it. - Simplified conditional compilation in pngvalid.c, for AIX (Michael Felt). - -Version 1.6.29beta02 [February 22, 2017] - Avoid conditional directives that break statements in pngrutil.c (Romero - Malaquias) - The contrib/examples/pngtopng.c recovery code was in the wrong "if" - branches; the comments were correct. - Added code for PowerPC VSX optimisation (Vadim Barkov). - -Version 1.6.29beta03 [March 1, 2017] - Avoid potential overflow of shift operations in png_do_expand() (Aaron Boxer). - Change test ZLIB_VERNUM >= 0x1281 to ZLIB_VERNUM >= 0x1290 in pngrutil.c - because Solaris 11 distributes zlib-1.2.8.f that is older than 1.2.8.1, - as suggested in zlib FAQ, item 24. - Suppress clang warnings about implicit sign changes in png.c - -Version 1.6.29 [March 16, 2017] - No changes. - -Version 1.6.30beta01 [April 1, 2017] - Added missing "$(CPPFLAGS)" to the compile line for c.pic.o in - makefile.linux and makefile.solaris-x86 (Cosmin). - Revised documentation of png_get_error_ptr() in the libpng manual. - Silence clang -Wcomma and const drop warnings (Viktor Szakats). - Update Sourceforge URLs in documentation (https instead of http). - -Version 1.6.30beta02 [April 22, 2017] - Document need to check for integer overflow when allocating a pixel - buffer for multiple rows in contrib/gregbook, contrib/pngminus, - example.c, and in the manual (suggested by Jaeseung Choi). This - is similar to the bug reported against pngquant in CVE-2016-5735. - Removed reference to the obsolete PNG_SAFE_LIMITS macro in the documentation. - -Version 1.6.30beta03 [May 22, 2017] - Check for integer overflow in contrib/visupng and contrib/tools/genpng. - Do not double evaluate CMAKE_SYSTEM_PROCESSOR in CMakeLists.txt. - Test CMAKE_HOST_WIN32 instead of WIN32 in CMakeLists.txt. - Fix some URL in documentation. - -Version 1.6.30beta04 [June 7, 2017] - Avoid writing an empty IDAT when the last IDAT exactly fills the - compression buffer (bug report by Brian Baird). This bug was - introduced in libpng-1.6.0. - -Version 1.6.30rc01 [June 14, 2017] - No changes. - -Version 1.6.30rc02 [June 25, 2017] - Update copyright year in pnglibconf.h, make ltmain.sh executable. - Add a reference to the libpng.download site in README. - -Version 1.6.30 [June 28, 2017] - No changes. - -Version 1.6.31beta01 [July 5, 2017] - Guard the definition of _POSIX_SOURCE in pngpriv.h (AIX already defines it; - bug report by Michael Felt). - Revised pngpriv.h to work around failure to compile arm/filter_neon.S - ("typedef" directive is unrecognized by the assembler). The problem - was introduced in libpng-1.6.30beta01. - Added "Requires: zlib" to libpng.pc.in (Pieter Neerincx). - Added special case for FreeBSD in arm/filter_neon.S (Maya Rashish). - -Version 1.6.31beta02 [July 8, 2017] - Added instructions for disabling hardware optimizations in INSTALL. - Added "--enable-hardware-optimizations" configuration flag to enable - or disable all hardware optimizations with one flag. - -Version 1.6.31beta03 [July 9, 2017] - Updated CMakeLists.txt to add INTEL_SSE and MIPS_MSA platforms. - Changed "int" to "png_size_t" in intel/filter_sse2.c to prevent - possible integer overflow (Bug report by John Bowler). - Quieted "declaration after statement" warnings in intel/filter_sse2.c. - Added scripts/makefile-linux-opt, which has hardware optimizations enabled. - -Version 1.6.31beta04 [July 11, 2017] - Removed one of the GCC-7.1.0 'strict-overflow' warnings that result when - integers appear on both sides of a compare. Worked around the others by - forcing the strict-overflow setting in the relevant functions to a level - where they are not reported (John Bowler). - Changed "FALL THROUGH" comments to "FALLTHROUGH" because GCC doesn't like - the space. - Worked around some C-style casts from (void*) because g++ 5.4.0 objects - to them. - Increased the buffer size for 'sprint' to pass the gcc 7.1.0 'sprint - overflow' check that is on by default with -Wall -Wextra. - -Version 1.6.31beta05 [July 13, 2017] - Added eXIf chunk support. - -Version 1.6.31beta06 [July 17, 2017] - Added a minimal eXIf chunk (with Orientation and FocalLengthIn35mmFilm - tags) to pngtest.png. - -Version 1.6.31beta07 [July 18, 2017] - Revised the eXIf chunk in pngtest.png to fix "Bad IFD1 Directory" warning. - -Version 1.6.31rc01 [July 19, 2017] - No changes. - -Version 1.6.31rc02 [July 25, 2017] - Fixed typo in example.c (png_free_image should be png_image_free) (Bug - report by John Smith) - -Version 1.6.31 [July 27, 2017] - No changes. - -Version 1.6.32beta01 [July 31, 2017] - Avoid possible NULL dereference in png_handle_eXIf when benign_errors - are allowed. Avoid leaking the input buffer "eXIf_buf". - Eliminated png_ptr->num_exif member from pngstruct.h and added num_exif - to arguments for png_get_eXIf() and png_set_eXIf(). - Added calls to png_handle_eXIf(() in pngread.c and png_write_eXIf() in - pngwrite.c, and made various other fixes to png_write_eXIf(). - Changed name of png_get_eXIF and png_set_eXIf() to png_get_eXIf_1() and - png_set_eXIf_1(), respectively, to avoid breaking API compatibility - with libpng-1.6.31. - -Version 1.6.32beta02 [August 1, 2017] - Updated contrib/libtests/pngunknown.c with eXIf chunk. - -Version 1.6.32beta03 [August 2, 2017] - Initialized btoa[] in pngstest.c - Stop memory leak when returning from png_handle_eXIf() with an error - (Bug report from the OSS-fuzz project). - -Version 1.6.32beta04 [August 2, 2017] - Replaced local eXIf_buf with info_ptr-eXIf_buf in png_handle_eXIf(). - Update libpng.3 and libpng-manual.txt about eXIf functions. - -Version 1.6.32beta05 [August 2, 2017] - Restored png_get_eXIf() and png_set_eXIf() to maintain API compatability. - -Version 1.6.32beta06 [August 2, 2017] - Removed png_get_eXIf_1() and png_set_eXIf_1(). - -Version 1.6.32beta07 [August 3, 2017] - Check length of all chunks except IDAT against user limit to fix an - OSS-fuzz issue (Fixes CVE-2017-12652). - -Version 1.6.32beta08 [August 3, 2017] - Check length of IDAT against maximum possible IDAT size, accounting - for height, rowbytes, interlacing and zlib/deflate overhead. - Restored png_get_eXIf_1() and png_set_eXIf_1(), because strlen(eXIf_buf) - does not work (the eXIf chunk data can contain zeroes). - -Version 1.6.32beta09 [August 3, 2017] - Require cmake-2.8.8 in CMakeLists.txt. Revised symlink creation, - no longer using deprecated cmake LOCATION feature (Clifford Yapp). - Fixed five-byte error in the calculation of IDAT maximum possible size. - -Version 1.6.32beta10 [August 5, 2017] - Moved chunk-length check into a png_check_chunk_length() private - function (Suggested by Max Stepin). - Moved bad pngs from tests to contrib/libtests/crashers - Moved testing of bad pngs into a separate tests/pngtest-badpngs script - Added the --xfail (expected FAIL) option to pngtest.c. It writes XFAIL - in the output but PASS for the libpng test. - Require cmake-3.0.2 in CMakeLists.txt (Clifford Yapp). - Fix "const" declaration info_ptr argument to png_get_eXIf_1() and the - num_exif argument to png_get_eXIf_1() (Github Issue 171). - -Version 1.6.32beta11 [August 7, 2017] - Added "eXIf" to "chunks_to_ignore[]" in png_set_keep_unknown_chunks(). - Added huge_IDAT.png and empty_ancillary_chunks.png to testpngs/crashers. - Make pngtest --strict, --relax, --xfail options imply -m (multiple). - Removed unused chunk_name parameter from png_check_chunk_length(). - Relocated setting free_me for eXIf data, to stop an OSS-fuzz leak. - Initialize profile_header[] in png_handle_iCCP() to fix OSS-fuzz issue. - Initialize png_ptr->row_buf[0] to 255 in png_read_row() to fix OSS-fuzz UMR. - Attempt to fix a UMR in png_set_text_2() to fix OSS-fuzz issue. - Increase minimum zlib stream from 9 to 14 in png_handle_iCCP(), to account - for the minimum 'deflate' stream, and relocate the test to a point - after the keyword has been read. - Check that the eXIf chunk has at least 2 bytes and begins with "II" or "MM". - -Version 1.6.32rc01 [August 18, 2017] - Added a set of "huge_xxxx_chunk.png" files to contrib/testpngs/crashers, - one for each known chunk type, with length = 2GB-1. - Check for 0 return from png_get_rowbytes() and added some (size_t) typecasts - in contrib/pngminus/*.c to stop some Coverity issues (162705, 162706, - and 162707). - Renamed chunks in contrib/testpngs/crashers to avoid having files whose - names differ only in case; this causes problems with some platforms - (github issue #172). - -Version 1.6.32rc02 [August 22, 2017] - Added contrib/oss-fuzz directory which contains files used by the oss-fuzz - project (https://github.com/google/oss-fuzz/tree/master/projects/libpng). - -Version 1.6.32 [August 24, 2017] - No changes. - -Version 1.6.33beta01 [August 28, 2017] - Added PNGMINUS_UNUSED macro to contrib/pngminus/p*.c and added missing - parenthesis in contrib/pngminus/pnm2png.c (bug report by Christian Hesse). - Fixed off-by-one error in png_do_check_palette_indexes() (Bug report - by Mick P., Source Forge Issue #269). - -Version 1.6.33beta02 [September 3, 2017] - Initialize png_handler.row_ptr in contrib/oss-fuzz/libpng_read_fuzzer.cc - to fix shortlived oss-fuzz issue 3234. - Compute a larger limit on IDAT because some applications write a deflate - buffer for each row (Bug report by Andrew Church). - Use current date (DATE) instead of release-date (RDATE) in last - changed date of contrib/oss-fuzz files. - Enabled ARM support in CMakeLists.txt (Bernd Kuhls). - -Version 1.6.33beta03 [September 14, 2017] - Fixed incorrect typecast of some arguments to png_malloc() and - png_calloc() that were png_uint_32 instead of png_alloc_size_t - (Bug report by "irwir" in Github libpng issue #175). - Use pnglibconf.h.prebuilt when building for ANDROID with cmake (Github - issue 162, by rcdailey). - -Version 1.6.33rc01 [September 20, 2017] - Initialize memory allocated by png_inflate to zero, using memset, to - stop an oss-fuzz "use of uninitialized value" detection in png_set_text_2() - due to truncated iTXt or zTXt chunk. - Initialize memory allocated by png_read_buffer to zero, using memset, to - stop an oss-fuzz "use of uninitialized value" detection in - png_icc_check_tag_table() due to truncated iCCP chunk. - Removed a redundant test (suggested by "irwir" in Github issue #180). - -Version 1.6.33rc02 [September 23, 2017] - Added an interlaced version of each file in contrib/pngsuite. - Relocate new memset() call in pngrutil.c. - Removed more redundant tests (suggested by "irwir" in Github issue #180). - Add support for loading images with associated alpha in the Simplified - API (Samuel Williams). - -Version 1.6.33 [September 28, 2017] - Revert contrib/oss-fuzz/libpng_read_fuzzer.cc to libpng-1.6.32 state. - Initialize png_handler.row_ptr in contrib/oss-fuzz/libpng_read_fuzzer.cc - Add end_info structure and png_read_end() to the libpng fuzzer. - -Version 1.6.34 [September 29, 2017] - Removed contrib/pngsuite/i*.png; some of these were incorrect and caused - test failures. - -Send comments/corrections/commendations to png-mng-implement at lists.sf.net -(subscription required; visit -https://lists.sourceforge.net/lists/listinfo/png-mng-implement -to subscribe) -or to glennrp at users.sourceforge.net - -Glenn R-P -#endif diff --git a/libs/freeimage/src/LibPNG/INSTALL b/libs/freeimage/src/LibPNG/INSTALL deleted file mode 100644 index e8edb7240f..0000000000 --- a/libs/freeimage/src/LibPNG/INSTALL +++ /dev/null @@ -1,465 +0,0 @@ - - Installing libpng - -Contents - - I. Simple installation - II. Rebuilding the configure scripts - III. Using scripts/makefile* - IV. Using cmake - V. Directory structure - VI. Building with project files - VII. Building with makefiles - VIII. Configuring libpng for 16-bit platforms - IX. Configuring for DOS - X. Configuring for Medium Model - XI. Prepending a prefix to exported symbols - XII. Configuring for compiler xxx: - XIII. Removing unwanted object code - XIV. Enabling or disabling hardware optimizations - XV. Changes to the build and configuration of libpng in libpng-1.5.x - XVI. Setjmp/longjmp issues - XVII. Common linking failures - XVIII. Other sources of information about libpng - -I. Simple installation - -On Unix/Linux and similar systems, you can simply type - - ./configure [--prefix=/path] - make check - make install - -and ignore the rest of this document. "/path" is the path to the directory -where you want to install the libpng "lib", "include", and "bin" -subdirectories. - -If you downloaded a GIT clone, you will need to run ./autogen.sh before -running ./configure, to create "configure" and "Makefile.in" which are -not included in the GIT repository. - -Note that "configure" is only included in the "*.tar" distributions and not -in the "*.zip" or "*.7z" distributions. If you downloaded one of those -distributions, see "Building with project files" or "Building with makefiles", -below. - -II. Rebuilding the configure scripts - -If configure does not work on your system, or if you have a need to -change configure.ac or Makefile.am, and you have a reasonably -up-to-date set of tools, running ./autogen.sh in a git clone before -running ./configure may fix the problem. To be really sure that you -aren't using any of the included pre-built scripts, especially if you -are building from a tar distribution instead of a git distribution, -do this: - - ./configure --enable-maintainer-mode - make maintainer-clean - ./autogen.sh --maintainer --clean - ./autogen.sh --maintainer - ./configure [--prefix=/path] [other options] - make - make install - make check - -III. Using scripts/makefile* - -Instead, you can use one of the custom-built makefiles in the -"scripts" directory - - cp scripts/pnglibconf.h.prebuilt pnglibconf.h - cp scripts/makefile.system makefile - make test - make install - -The files that are presently available in the scripts directory -are listed and described in scripts/README.txt. - -Or you can use one of the "projects" in the "projects" directory. - -Before installing libpng, you must first install zlib, if it -is not already on your system. zlib can usually be found -wherever you got libpng; otherwise go to https://zlib.net/. You can -place zlib in the same directory as libpng or in another directory. - -If your system already has a preinstalled zlib you will still need -to have access to the zlib.h and zconf.h include files that -correspond to the version of zlib that's installed. - -If you wish to test with a particular zlib that is not first in the -standard library search path, put ZLIBLIB, ZLIBINC, CPPFLAGS, LDFLAGS, -and LD_LIBRARY_PATH in your environment before running "make test" -or "make distcheck": - - ZLIBLIB=/path/to/lib export ZLIBLIB - ZLIBINC=/path/to/include export ZLIBINC - CPPFLAGS="-I$ZLIBINC" export CPPFLAGS - LDFLAGS="-L$ZLIBLIB" export LDFLAGS - LD_LIBRARY_PATH="$ZLIBLIB:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH - -If you are using one of the makefile scripts, put ZLIBLIB and ZLIBINC -in your environment and type - - make ZLIBLIB=$ZLIBLIB ZLIBINC=$ZLIBINC test - -IV. Using cmake - -If you want to use "cmake" (see www.cmake.org), type - - cmake . -DCMAKE_INSTALL_PREFIX=/path - make - make install - -As when using the simple configure method described above, "/path" points to -the installation directory where you want to put the libpng "lib", "include", -and "bin" subdirectories. - -V. Directory structure - -You can rename the directories that you downloaded (they -might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.8" -or "zlib128") so that you have directories called "zlib" and "libpng". - -Your directory structure should look like this: - - .. (the parent directory) - libpng (this directory) - INSTALL (this file) - README - *.h, *.c => libpng source files - CMakeLists.txt => "cmake" script - configuration files: - configure.ac, configure, Makefile.am, Makefile.in, - autogen.sh, config.guess, ltmain.sh, missing, libpng.pc.in, - libpng-config.in, aclocal.m4, config.h.in, config.sub, - depcomp, install-sh, mkinstalldirs, test-pngtest.sh - contrib - arm-neon, conftest, examples, gregbook, libtests, pngminim, - pngminus, pngsuite, tools, visupng - projects - cbuilder5, owatcom, visualc71, vstudio, xcode - scripts - makefile.* - *.def (module definition files) - etc. - pngtest.png - etc. - zlib - README, *.h, *.c contrib, etc. - -If the line endings in the files look funny, you may wish to get the other -distribution of libpng. It is available in both tar.gz (UNIX style line -endings) and zip (DOS style line endings) formats. - -VI. Building with project files - -If you are building libpng with MSVC, you can enter the -libpng projects\visualc71 or vstudio directory and follow the instructions -in README.txt. - -Otherwise enter the zlib directory and follow the instructions in zlib/README, -then come back here and run "configure" or choose the appropriate -makefile.sys in the scripts directory. - -VII. Building with makefiles - -Copy the file (or files) that you need from the -scripts directory into this directory, for example - -MSDOS example: - - copy scripts\makefile.msc makefile - copy scripts\pnglibconf.h.prebuilt pnglibconf.h - -UNIX example: - - cp scripts/makefile.std makefile - cp scripts/pnglibconf.h.prebuilt pnglibconf.h - -Read the makefile to see if you need to change any source or -target directories to match your preferences. - -Then read pnglibconf.dfa to see if you want to make any configuration -changes. - -Then just run "make" which will create the libpng library in -this directory and "make test" which will run a quick test that reads -the "pngtest.png" file and writes a "pngout.png" file that should be -identical to it. Look for "9782 zero samples" in the output of the -test. For more confidence, you can run another test by typing -"pngtest pngnow.png" and looking for "289 zero samples" in the output. -Also, you can run "pngtest -m contrib/pngsuite/*.png" and compare -your output with the result shown in contrib/pngsuite/README. - -Most of the makefiles will allow you to run "make install" to -put the library in its final resting place (if you want to -do that, run "make install" in the zlib directory first if necessary). -Some also allow you to run "make test-installed" after you have -run "make install". - -VIII. Configuring libpng for 16-bit platforms - -You will want to look into zconf.h to tell zlib (and thus libpng) that -it cannot allocate more than 64K at a time. Even if you can, the memory -won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K. - -IX. Configuring for DOS - -For DOS users who only have access to the lower 640K, you will -have to limit zlib's memory usage via a png_set_compression_mem_level() -call. See zlib.h or zconf.h in the zlib library for more information. - -X. Configuring for Medium Model - -Libpng's support for medium model has been tested on most of the popular -compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets -defined, and FAR gets defined to far in pngconf.h, and you should be -all set. Everything in the library (except for zlib's structure) is -expecting far data. You must use the typedefs with the p or pp on -the end for pointers (or at least look at them and be careful). Make -note that the rows of data are defined as png_bytepp, which is -an "unsigned char far * far *". - -XI. Prepending a prefix to exported symbols - -Starting with libpng-1.6.0, you can configure libpng (when using the -"configure" script) to prefix all exported symbols by means of the -configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any -string beginning with a letter and containing only uppercase -and lowercase letters, digits, and the underscore (i.e., a C language -identifier). This creates a set of macros in pnglibconf.h, so this is -transparent to applications; their function calls get transformed by -the macros to use the modified names. - -XII. Configuring for compiler xxx: - -All includes for libpng are in pngconf.h. If you need to add, change -or delete an include, this is the place to do it. -The includes that are not needed outside libpng are placed in pngpriv.h, -which is only used by the routines inside libpng itself. -The files in libpng proper only include pngpriv.h and png.h, which -in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h. -As of libpng-1.5.0, pngpriv.h also includes three other private header -files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material -that previously appeared in the public headers. - -XIII. Removing unwanted object code - -There are a bunch of #define's in pngconf.h that control what parts of -libpng are compiled. All the defines end in _SUPPORTED. If you are -never going to use a capability, you can change the #define to #undef -before recompiling libpng and save yourself code and data space, or -you can turn off individual capabilities with defines that begin with -"PNG_NO_". - -In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead. - -You can also turn all of the transforms and ancillary chunk capabilities -off en masse with compiler directives that define -PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, -or all four, along with directives to turn on any of the capabilities that -you do want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the -extra transformations but still leave the library fully capable of reading -and writing PNG files with all known public chunks. Use of the -PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library -that is incapable of reading or writing ancillary chunks. If you are -not using the progressive reading capability, you can turn that off -with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING -capability, which you'll still have). - -All the reading and writing specific code are in separate files, so the -linker should only grab the files it needs. However, if you want to -make sure, or if you are building a stand alone library, all the -reading files start with "pngr" and all the writing files start with "pngw". -The files that don't match either (like png.c, pngtrans.c, etc.) -are used for both reading and writing, and always need to be included. -The progressive reader is in pngpread.c - -If you are creating or distributing a dynamically linked library (a .so -or DLL file), you should not remove or disable any parts of the library, -as this will cause applications linked with different versions of the -library to fail if they call functions not available in your library. -The size of the library itself should not be an issue, because only -those sections that are actually used will be loaded into memory. - -XIV. Enabling or disabling hardware optimizations - -Certain hardware capabilites, such as the Intel SSE instructions, -are normally detected at run time. Enable them with configure options -such as one of - - --enable-arm-neon=yes - --enable-mips-msa=yes - --enable-intel-sse=yes - --enable-powerpc-vsx=yes - -or enable them all at once with - - --enable-hardware-optimizations=yes - -or, if you are not using "configure", you can use one -or more of - - CPPFLAGS += "-DPNG_ARM_NEON" - CPPFLAGS += "-DPNG_MIPS_MSA" - CPPFLAGS += "-DPNG_INTEL_SSE" - CPPFLAGS += "-DPNG_POWERPC_VSX" - -See for example scripts/makefile.linux-opt - -If you wish to avoid using them, -you can disable them via the configure option - - --disable-hardware-optimizations - -to disable them all, or - - --enable-intel-sse=no - -to disable a particular one, -or via compiler-command options such as - - CPPFLAGS += "-DPNG_ARM_NEON_OPT=0, -DPNG_MIPS_MSA_OPT=0, - -DPNG_INTEL_SSE_OPT=0, -DPNG_POWERPC_VSX_OPT=0" - -If you are using cmake, hardware optimizations are "on" -by default. To disable them, use - - cmake . -DPNG_ARM_NEON=no -DPNG_INTEL_SSE=no \ - -DPNG_MIPS_MSA=no -DPNG_POWERPC_VSX=no - -or disable them all at once with - - cmake . -DPNG_HARDWARE_OPTIMIZATIONS=no - -XV. Changes to the build and configuration of libpng in libpng-1.5.x - -Details of internal changes to the library code can be found in the CHANGES -file and in the GIT repository logs. These will be of no concern to the vast -majority of library users or builders; however, the few who configure libpng -to a non-default feature set may need to change how this is done. - -There should be no need for library builders to alter build scripts if -these use the distributed build support - configure or the makefiles - -however, users of the makefiles may care to update their build scripts -to build pnglibconf.h where the corresponding makefile does not do so. - -Building libpng with a non-default configuration has changed completely. -The old method using pngusr.h should still work correctly even though the -way pngusr.h is used in the build has been changed; however, library -builders will probably want to examine the changes to take advantage of -new capabilities and to simplify their build system. - -A. Specific changes to library configuration capabilities - -The exact mechanism used to control attributes of API functions has -changed. A single set of operating system independent macro definitions -is used and operating system specific directives are defined in -pnglibconf.h - -As part of this the mechanism used to choose procedure call standards on -those systems that allow a choice has been changed. At present this only -affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems -running on Intel processors. As before, PNGAPI is defined where required -to control the exported API functions; however, two new macros, PNGCBAPI -and PNGCAPI, are used instead for callback functions (PNGCBAPI) and -(PNGCAPI) for functions that must match a C library prototype (currently -only png_longjmp_ptr, which must match the C longjmp function.) The new -approach is documented in pngconf.h - -Despite these changes, libpng 1.5.0 only supports the native C function -calling standard on those platforms tested so far ("__cdecl" on Microsoft -Windows). This is because the support requirements for alternative -calling conventions seem to no longer exist. Developers who find it -necessary to set PNG_API_RULE to 1 should advise the mailing list -(png-mng-implement) of this and library builders who use Openwatcom and -therefore set PNG_API_RULE to 2 should also contact the mailing list. - -B. Changes to the configuration mechanism - -Prior to libpng-1.5.0 library builders who needed to configure libpng -had either to modify the exported pngconf.h header file to add system -specific configuration or had to write feature selection macros into -pngusr.h and cause this to be included into pngconf.h by defining -PNG_USER_CONFIG. The latter mechanism had the disadvantage that an -application built without PNG_USER_CONFIG defined would see the -unmodified, default, libpng API and thus would probably fail to link. - -These mechanisms still work in the configure build and in any makefile -build that builds pnglibconf.h, although the feature selection macros -have changed somewhat as described above. In 1.5.0, however, pngusr.h is -processed only once, at the time the exported header file pnglibconf.h is -built. pngconf.h no longer includes pngusr.h; therefore, pngusr.h is ignored -after the build of pnglibconf.h and it is never included in an application -build. - -The formerly used alternative of adding a list of feature macros to the -CPPFLAGS setting in the build also still works; however, the macros will be -copied to pnglibconf.h and this may produce macro redefinition warnings -when the individual C files are compiled. - -All configuration now only works if pnglibconf.h is built from -scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan -(the original author of awk) maintains C source code of that awk and this -and all known later implementations (often called by subtly different -names - nawk and gawk for example) are adequate to build pnglibconf.h. -The Sun Microsystems (now Oracle) program 'awk' is an earlier version -and does not work; this may also apply to other systems that have a -functioning awk called 'nawk'. - -Configuration options are now documented in scripts/pnglibconf.dfa. This -file also includes dependency information that ensures a configuration is -consistent; that is, if a feature is switched off, dependent features are -also switched off. As a recommended alternative to using feature macros in -pngusr.h a system builder may also define equivalent options in pngusr.dfa -(or, indeed, any file) and add that to the configuration by setting -DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate -how to do this, and also illustrate a case where pngusr.h is still required. - -After you have built libpng, the definitions that were recorded in -pnglibconf.h are available to your application (pnglibconf.h is included -in png.h and gets installed alongside png.h and pngconf.h in your -$PREFIX/include directory). Do not edit pnglibconf.h after you have built -libpng, because than the settings would not accurately reflect the settings -that were used to build libpng. - -XVI. Setjmp/longjmp issues - -Libpng uses setjmp()/longjmp() for error handling. Unfortunately setjmp() -is known to be not thread-safe on some platforms and we don't know of -any platform where it is guaranteed to be thread-safe. Therefore, if -your application is going to be using multiple threads, you should -configure libpng with PNG_NO_SETJMP in your pngusr.dfa file, with --DPNG_NO_SETJMP on your compile line, or with - - #undef PNG_SETJMP_SUPPORTED - -in your pnglibconf.h or pngusr.h. - -Starting with libpng-1.6.0, the library included a "simplified API". -This requires setjmp/longjmp, so you must either build the library -with PNG_SETJMP_SUPPORTED defined, or with PNG_SIMPLIFIED_READ_SUPPORTED -and PNG_SIMPLIFIED_WRITE_SUPPORTED undefined. - -XVII. Common linking failures - -If your application fails to find libpng or zlib entries while linking: - - Be sure "-lz" appears after "-lpng" on your linking command. - - Be sure you have built libpng, zlib, and your application for the - same platform (e.g., 32-bit or 64-bit). - - If you are using the vstudio project, observe the WARNING in - project/vstudio/README.txt. - -XVIII. Other sources of information about libpng: - -Further information can be found in the README and libpng-manual.txt -files, in the individual makefiles, in png.h, and the manual pages -libpng.3 and png.5. - -Copyright (c) 1998-2002,2006-2016 Glenn Randers-Pehrson -This document is released under the libpng license. -For conditions of distribution and use, see the disclaimer -and license in png.h. diff --git a/libs/freeimage/src/LibPNG/README b/libs/freeimage/src/LibPNG/README deleted file mode 100644 index 0da5a5ef83..0000000000 --- a/libs/freeimage/src/LibPNG/README +++ /dev/null @@ -1,222 +0,0 @@ -README for libpng version 1.6.34 - September 29, 2017 (shared library 16.0) -See the note about version numbers near the top of png.h - -See INSTALL for instructions on how to install libpng. - -Libpng comes in several distribution formats. Get libpng-*.tar.gz or -libpng-*.tar.xz or if you want UNIX-style line endings in the text files, -or lpng*.7z or lpng*.zip if you want DOS-style line endings. - -Version 0.89 was the first official release of libpng. Don't let the -fact that it's the first release fool you. The libpng library has been in -extensive use and testing since mid-1995. By late 1997 it had -finally gotten to the stage where there hadn't been significant -changes to the API in some time, and people have a bad feeling about -libraries with versions < 1.0. Version 1.0.0 was released in -March 1998. - -**** -Note that some of the changes to the png_info structure render this -version of the library binary incompatible with libpng-0.89 or -earlier versions if you are using a shared library. The type of the -"filler" parameter for png_set_filler() has changed from png_byte to -png_uint_32, which will affect shared-library applications that use -this function. - -To avoid problems with changes to the internals of the png info_struct, -new APIs have been made available in 0.95 to avoid direct application -access to info_ptr. These functions are the png_set_<chunk> and -png_get_<chunk> functions. These functions should be used when -accessing/storing the info_struct data, rather than manipulating it -directly, to avoid such problems in the future. - -It is important to note that the APIs did not make current programs -that access the info struct directly incompatible with the new -library, through libpng-1.2.x. In libpng-1.4.x, which was meant to -be a transitional release, members of the png_struct and the -info_struct can still be accessed, but the compiler will issue a -warning about deprecated usage. Since libpng-1.5.0, direct access -to these structs is not allowed, and the definitions of the structs -reside in private pngstruct.h and pnginfo.h header files that are not -accessible to applications. It is strongly suggested that new -programs use the new APIs (as shown in example.c and pngtest.c), and -older programs be converted to the new format, to facilitate upgrades -in the future. -**** - -Additions since 0.90 include the ability to compile libpng as a -Windows DLL, and new APIs for accessing data in the info struct. -Experimental functions include the ability to set weighting and cost -factors for row filter selection, direct reads of integers from buffers -on big-endian processors that support misaligned data access, faster -methods of doing alpha composition, and more accurate 16->8 bit color -conversion. - -The additions since 0.89 include the ability to read from a PNG stream -which has had some (or all) of the signature bytes read by the calling -application. This also allows the reading of embedded PNG streams that -do not have the PNG file signature. As well, it is now possible to set -the library action on the detection of chunk CRC errors. It is possible -to set different actions based on whether the CRC error occurred in a -critical or an ancillary chunk. - -The changes made to the library, and bugs fixed are based on discussions -on the PNG-implement mailing list and not on material submitted -privately to Guy, Andreas, or Glenn. They will forward any good -suggestions to the list. - -For a detailed description on using libpng, read libpng-manual.txt. For -examples of libpng in a program, see example.c and pngtest.c. For usage -information and restrictions (what little they are) on libpng, see -png.h. For a description on using zlib (the compression library used by -libpng) and zlib's restrictions, see zlib.h - -I have included a general makefile, as well as several machine and -compiler specific ones, but you may have to modify one for your own needs. - -You should use zlib 1.0.4 or later to run this, but it MAY work with -versions as old as zlib 0.95. Even so, there are bugs in older zlib -versions which can cause the output of invalid compression streams for -some images. You will definitely need zlib 1.0.4 or later if you are -taking advantage of the MS-DOS "far" structure allocation for the small -and medium memory models. You should also note that zlib is a -compression library that is useful for more things than just PNG files. -You can use zlib as a drop-in replacement for fread() and fwrite() if -you are so inclined. - -zlib should be available at the same place that libpng is, or at zlib.net. - -You may also want a copy of the PNG specification. It is available -as an RFC, a W3C Recommendation, and an ISO/IEC Standard. You can find -these at http://www.libpng.org/pub/png/pngdocs.html . - -This code is currently being archived at libpng.sourceforge.io in the -[DOWNLOAD] area, and at http://libpng.download/src . If you -can't find it in any of those places, e-mail me, and I'll help you find it. - -I am not a lawyer, but I believe that the Export Control Classification -Number (ECCN) for libpng is EAR99, which means not subject to export -controls or International Traffic in Arms Regulations (ITAR) because it -is open source, publicly available software, that does not contain any -encryption software. See the EAR, paragraphs 734.3(b)(3) and 734.7(b). - -If you have any code changes, requests, problems, etc., please e-mail -them to me. Also, I'd appreciate any make files or project files, -and any modifications you needed to make to get libpng to compile, -along with a #define variable to tell what compiler/system you are on. -If you needed to add transformations to libpng, or wish libpng would -provide the image in a different way, drop me a note (and code, if -possible), so I can consider supporting the transformation. -Finally, if you get any warning messages when compiling libpng -(note: not zlib), and they are easy to fix, I'd appreciate the -fix. Please mention "libpng" somewhere in the subject line. Thanks. - -This release was created and will be supported by myself (of course -based in a large way on Guy's and Andreas' earlier work), and the PNG -development group. - -Send comments/corrections/commendations to png-mng-implement at -lists.sourceforge.net (subscription required; visit -https://lists.sourceforge.net/lists/listinfo/png-mng-implement -to subscribe) or to glennrp at users.sourceforge.net - -You can't reach Guy, the original libpng author, at the addresses -given in previous versions of this document. He and Andreas will -read mail addressed to the png-implement list, however. - -Please do not send general questions about PNG. Send them to -png-mng-misc at lists.sf.net (subscription required; visit -https://lists.sourceforge.net/lists/listinfo/png-mng-misc to -subscribe). If you have a question about something -in the PNG specification that is related to using libpng, send it -to me. Send me any questions that start with "I was using libpng, -and ...". If in doubt, send questions to me. I'll bounce them -to others, if necessary. - -Please do not send suggestions on how to change PNG. We have -been discussing PNG for twenty years now, and it is official and -finished. If you have suggestions for libpng, however, I'll -gladly listen. Even if your suggestion is not used immediately, -it may be used later. - -Files in this distribution: - - ANNOUNCE => Announcement of this version, with recent changes - CHANGES => Description of changes between libpng versions - KNOWNBUG => List of known bugs and deficiencies - LICENSE => License to use and redistribute libpng - README => This file - TODO => Things not implemented in the current library - Y2KINFO => Statement of Y2K compliance - example.c => Example code for using libpng functions - libpng.3 => manual page for libpng (includes libpng-manual.txt) - libpng-manual.txt => Description of libpng and its functions - libpngpf.3 => manual page for libpng's private functions - png.5 => manual page for the PNG format - png.c => Basic interface functions common to library - png.h => Library function and interface declarations (public) - pngpriv.h => Library function and interface declarations (private) - pngconf.h => System specific library configuration (public) - pngstruct.h => png_struct declaration (private) - pnginfo.h => png_info struct declaration (private) - pngdebug.h => debugging macros (private) - pngerror.c => Error/warning message I/O functions - pngget.c => Functions for retrieving info from struct - pngmem.c => Memory handling functions - pngbar.png => PNG logo, 88x31 - pngnow.png => PNG logo, 98x31 - pngpread.c => Progressive reading functions - pngread.c => Read data/helper high-level functions - pngrio.c => Lowest-level data read I/O functions - pngrtran.c => Read data transformation functions - pngrutil.c => Read data utility functions - pngset.c => Functions for storing data into the info_struct - pngtest.c => Library test program - pngtest.png => Library test sample image - pngtrans.c => Common data transformation functions - pngwio.c => Lowest-level write I/O functions - pngwrite.c => High-level write functions - pngwtran.c => Write data transformations - pngwutil.c => Write utility functions - arm => Contains optimized code for the ARM platform - powerpc => Contains optimized code for the PowerPC platform - contrib => Contributions - arm-neon => Optimized code for ARM-NEON platform - powerpc-vsx => Optimized code for POWERPC-VSX platform - examples => Example programs - gregbook => source code for PNG reading and writing, from - Greg Roelofs' "PNG: The Definitive Guide", - O'Reilly, 1999 - libtests => Test programs - mips-msa => Optimized code for MIPS-MSA platform - pngminim => Minimal decoder, encoder, and progressive decoder - programs demonstrating use of pngusr.dfa - pngminus => Simple pnm2png and png2pnm programs - pngsuite => Test images - testpngs - tools => Various tools - visupng => Contains a MSVC workspace for VisualPng - intel => Optimized code for INTEL-SSE2 platform - mips => Optimized code for MIPS platform - projects => Contains project files and workspaces for - building a DLL - owatcom => Contains a WATCOM project for building libpng - visualc71 => Contains a Microsoft Visual C++ (MSVC) - workspace for building libpng and zlib - vstudio => Contains a Microsoft Visual C++ (MSVC) - workspace for building libpng and zlib - scripts => Directory containing scripts for building libpng: - (see scripts/README.txt for the list of scripts) - -Good luck, and happy coding. - --Glenn Randers-Pehrson (current maintainer, since 1998) - Internet: glennrp at users.sourceforge.net - --Andreas Eric Dilger (former maintainer, 1996-1997) - Internet: adilger at enel.ucalgary.ca - Web: http://www-mddsp.enel.ucalgary.ca/People/adilger/ - --Guy Eric Schalnat (original author and former maintainer, 1995-1996) - (formerly of Group 42, Inc) - Internet: gschal at infinet.com diff --git a/libs/freeimage/src/LibPNG/TODO b/libs/freeimage/src/LibPNG/TODO deleted file mode 100644 index 36d6092a2e..0000000000 --- a/libs/freeimage/src/LibPNG/TODO +++ /dev/null @@ -1,30 +0,0 @@ -/* -TODO - list of things to do for libpng: - -Final bug fixes. -Better C++ wrapper/full C++ implementation? -Fix problem with C++ and EXTERN "C". -cHRM transformation. -Remove setjmp/longjmp usage in favor of returning error codes. As a start on - this, minimize the use of png_error(), replacing them with - png_warning(); return(0); or similar. -Palette creation. -Add "grayscale->palette" transformation and "palette->grayscale" detection. -Improved dithering. -Multi-lingual error and warning message support. -Complete sRGB transformation (presently it simply uses gamma=0.45455). -Man pages for function calls. -Better documentation. -Better filter selection - (counting huffman bits/precompression? filter inertia? filter costs?). -Histogram creation. -Text conversion between different code pages (Latin-1 -> Mac and DOS). -Avoid building gamma tables whenever possible. -Use greater precision when changing to linear gamma for compositing against - background and doing rgb-to-gray transformation. -Investigate pre-incremented loop counters and other loop constructions. -Add interpolated method of handling interlacing. -Extend pngvalid.c to validate more of the libpng transformations. -Refactor preprocessor conditionals to compile entire statements - -*/ diff --git a/libs/freeimage/src/LibPNG/libpng-manual.txt b/libs/freeimage/src/LibPNG/libpng-manual.txt deleted file mode 100644 index d4407ef2ea..0000000000 --- a/libs/freeimage/src/LibPNG/libpng-manual.txt +++ /dev/null @@ -1,5464 +0,0 @@ -libpng-manual.txt - A description on how to use and modify libpng - - libpng version 1.6.34 - September 29, 2017 - Updated and distributed by Glenn Randers-Pehrson - <glennrp at users.sourceforge.net> - Copyright (c) 1998-2017 Glenn Randers-Pehrson - - This document is released under the libpng license. - For conditions of distribution and use, see the disclaimer - and license in png.h - - Based on: - - libpng versions 0.97, January 1998, through 1.6.34 - September 29, 2017 - Updated and distributed by Glenn Randers-Pehrson - Copyright (c) 1998-2017 Glenn Randers-Pehrson - - libpng 1.0 beta 6 - version 0.96 - May 28, 1997 - Updated and distributed by Andreas Dilger - Copyright (c) 1996, 1997 Andreas Dilger - - libpng 1.0 beta 2 - version 0.88 - January 26, 1996 - For conditions of distribution and use, see copyright - notice in png.h. Copyright (c) 1995, 1996 Guy Eric - Schalnat, Group 42, Inc. - - Updated/rewritten per request in the libpng FAQ - Copyright (c) 1995, 1996 Frank J. T. Wojcik - December 18, 1995 & January 20, 1996 - - TABLE OF CONTENTS - - I. Introduction - II. Structures - III. Reading - IV. Writing - V. Simplified API - VI. Modifying/Customizing libpng - VII. MNG support - VIII. Changes to Libpng from version 0.88 - IX. Changes to Libpng from version 1.0.x to 1.2.x - X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x - XI. Changes to Libpng from version 1.4.x to 1.5.x - XII. Changes to Libpng from version 1.5.x to 1.6.x - XIII. Detecting libpng - XIV. Source code repository - XV. Coding style - XVI. Y2K Compliance in libpng - -I. Introduction - -This file describes how to use and modify the PNG reference library -(known as libpng) for your own use. In addition to this -file, example.c is a good starting point for using the library, as -it is heavily commented and should include everything most people -will need. We assume that libpng is already installed; see the -INSTALL file for instructions on how to configure and install libpng. - -For examples of libpng usage, see the files "example.c", "pngtest.c", -and the files in the "contrib" directory, all of which are included in -the libpng distribution. - -Libpng was written as a companion to the PNG specification, as a way -of reducing the amount of time and effort it takes to support the PNG -file format in application programs. - -The PNG specification (second edition), November 2003, is available as -a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at -<https://www.w3.org/TR/2003/REC-PNG-20031110/ -The W3C and ISO documents have identical technical content. - -The PNG-1.2 specification is available at -<https://png-mng.sourceforge.io/pub/png/spec/1.2/>. -It is technically equivalent -to the PNG specification (second edition) but has some additional material. - -The PNG-1.0 specification is available as RFC 2083 -<https://png-mng.sourceforge.io/pub/png/spec/1.0/> and as a -W3C Recommendation <https://www.w3.org/TR/REC-png-961001>. - -Some additional chunks are described in the special-purpose public chunks -documents at <http://www.libpng.org/pub/png/spec/register/> - -Other information -about PNG, and the latest version of libpng, can be found at the PNG home -page, <http://www.libpng.org/pub/png/>. - -Most users will not have to modify the library significantly; advanced -users may want to modify it more. All attempts were made to make it as -complete as possible, while keeping the code easy to understand. -Currently, this library only supports C. Support for other languages -is being considered. - -Libpng has been designed to handle multiple sessions at one time, -to be easily modifiable, to be portable to the vast majority of -machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy -to use. The ultimate goal of libpng is to promote the acceptance of -the PNG file format in whatever way possible. While there is still -work to be done (see the TODO file), libpng should cover the -majority of the needs of its users. - -Libpng uses zlib for its compression and decompression of PNG files. -Further information about zlib, and the latest version of zlib, can -be found at the zlib home page, <https://zlib.net/>. -The zlib compression utility is a general purpose utility that is -useful for more than PNG files, and can be used without libpng. -See the documentation delivered with zlib for more details. -You can usually find the source files for the zlib utility wherever you -find the libpng source files. - -Libpng is thread safe, provided the threads are using different -instances of the structures. Each thread should have its own -png_struct and png_info instances, and thus its own image. -Libpng does not protect itself against two threads using the -same instance of a structure. - -II. Structures - -There are two main structures that are important to libpng, png_struct -and png_info. Both are internal structures that are no longer exposed -in the libpng interface (as of libpng 1.5.0). - -The png_info structure is designed to provide information about the -PNG file. At one time, the fields of png_info were intended to be -directly accessible to the user. However, this tended to cause problems -with applications using dynamically loaded libraries, and as a result -a set of interface functions for png_info (the png_get_*() and png_set_*() -functions) was developed, and direct access to the png_info fields was -deprecated.. - -The png_struct structure is the object used by the library to decode a -single image. As of 1.5.0 this structure is also not exposed. - -Almost all libpng APIs require a pointer to a png_struct as the first argument. -Many (in particular the png_set and png_get APIs) also require a pointer -to png_info as the second argument. Some application visible macros -defined in png.h designed for basic data access (reading and writing -integers in the PNG format) don't take a png_info pointer, but it's almost -always safe to assume that a (png_struct*) has to be passed to call an API -function. - -You can have more than one png_info structure associated with an image, -as illustrated in pngtest.c, one for information valid prior to the -IDAT chunks and another (called "end_info" below) for things after them. - -The png.h header file is an invaluable reference for programming with libpng. -And while I'm on the topic, make sure you include the libpng header file: - -#include <png.h> - -and also (as of libpng-1.5.0) the zlib header file, if you need it: - -#include <zlib.h> - -Types - -The png.h header file defines a number of integral types used by the -APIs. Most of these are fairly obvious; for example types corresponding -to integers of particular sizes and types for passing color values. - -One exception is how non-integral numbers are handled. For application -convenience most APIs that take such numbers have C (double) arguments; -however, internally PNG, and libpng, use 32 bit signed integers and encode -the value by multiplying by 100,000. As of libpng 1.5.0 a convenience -macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point) -which is simply (png_int_32). - -All APIs that take (double) arguments also have a matching API that -takes the corresponding fixed point integer arguments. The fixed point -API has the same name as the floating point one with "_fixed" appended. -The actual range of values permitted in the APIs is frequently less than -the full range of (png_fixed_point) (-21474 to +21474). When APIs require -a non-negative argument the type is recorded as png_uint_32 above. Consult -the header file and the text below for more information. - -Special care must be take with sCAL chunk handling because the chunk itself -uses non-integral values encoded as strings containing decimal floating point -numbers. See the comments in the header file. - -Configuration - -The main header file function declarations are frequently protected by C -preprocessing directives of the form: - - #ifdef PNG_feature_SUPPORTED - declare-function - #endif - ... - #ifdef PNG_feature_SUPPORTED - use-function - #endif - -The library can be built without support for these APIs, although a -standard build will have all implemented APIs. Application programs -should check the feature macros before using an API for maximum -portability. From libpng 1.5.0 the feature macros set during the build -of libpng are recorded in the header file "pnglibconf.h" and this file -is always included by png.h. - -If you don't need to change the library configuration from the default, skip to -the next section ("Reading"). - -Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all -of the build project files in the 'projects' directory simply copy -scripts/pnglibconf.h.prebuilt to pnglibconf.h. This means that these build -systems do not permit easy auto-configuration of the library - they only -support the default configuration. - -The easiest way to make minor changes to the libpng configuration when -auto-configuration is supported is to add definitions to the command line -using (typically) CPPFLAGS. For example: - -CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC - -will change the internal libpng math implementation for gamma correction and -other arithmetic calculations to fixed point, avoiding the need for fast -floating point support. The result can be seen in the generated pnglibconf.h - -make sure it contains the changed feature macro setting. - -If you need to make more extensive configuration changes - more than one or two -feature macro settings - you can either add -DPNG_USER_CONFIG to the build -command line and put a list of feature macro settings in pngusr.h or you can set -DFA_XTRA (a makefile variable) to a file containing the same information in the -form of 'option' settings. - -A. Changing pnglibconf.h - -A variety of methods exist to build libpng. Not all of these support -reconfiguration of pnglibconf.h. To reconfigure pnglibconf.h it must either be -rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand. - -Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to -pnglibconf.h and changing the lines defining the supported features, paying -very close attention to the 'option' information in scripts/pnglibconf.dfa -that describes those features and their requirements. This is easy to get -wrong. - -B. Configuration using DFA_XTRA - -Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later -variant such as 'nawk' or 'gawk', is available. The configure build will -automatically find an appropriate awk and build pnglibconf.h. -The scripts/pnglibconf.mak file contains a set of make rules for doing the -same thing if configure is not used, and many of the makefiles in the scripts -directory use this approach. - -When rebuilding simply write a new file containing changed options and set -DFA_XTRA to the name of this file. This causes the build to append the new file -to the end of scripts/pnglibconf.dfa. The pngusr.dfa file should contain lines -of the following forms: - -everything = off - -This turns all optional features off. Include it at the start of pngusr.dfa to -make it easier to build a minimal configuration. You will need to turn at least -some features on afterward to enable either reading or writing code, or both. - -option feature on -option feature off - -Enable or disable a single feature. This will automatically enable other -features required by a feature that is turned on or disable other features that -require a feature which is turned off. Conflicting settings will cause an error -message to be emitted by awk. - -setting feature default value - -Changes the default value of setting 'feature' to 'value'. There are a small -number of settings listed at the top of pnglibconf.h, they are documented in the -source code. Most of these values have performance implications for the library -but most of them have no visible effect on the API. Some can also be overridden -from the API. - -This method of building a customized pnglibconf.h is illustrated in -contrib/pngminim/*. See the "$(PNGCONF):" target in the makefile and -pngusr.dfa in these directories. - -C. Configuration using PNG_USER_CONFIG - -If -DPNG_USER_CONFIG is added to the CPPFLAGS when pnglibconf.h is built, -the file pngusr.h will automatically be included before the options in -scripts/pnglibconf.dfa are processed. Your pngusr.h file should contain only -macro definitions turning features on or off or setting settings. - -Apart from the global setting "everything = off" all the options listed above -can be set using macros in pngusr.h: - -#define PNG_feature_SUPPORTED - -is equivalent to: - -option feature on - -#define PNG_NO_feature - -is equivalent to: - -option feature off - -#define PNG_feature value - -is equivalent to: - -setting feature default value - -Notice that in both cases, pngusr.dfa and pngusr.h, the contents of the -pngusr file you supply override the contents of scripts/pnglibconf.dfa - -If confusing or incomprehensible behavior results it is possible to -examine the intermediate file pnglibconf.dfn to find the full set of -dependency information for each setting and option. Simply locate the -feature in the file and read the C comments that precede it. - -This method is also illustrated in the contrib/pngminim/* makefiles and -pngusr.h. - -III. Reading - -We'll now walk you through the possible functions to call when reading -in a PNG file sequentially, briefly explaining the syntax and purpose -of each one. See example.c and png.h for more detail. While -progressive reading is covered in the next section, you will still -need some of the functions discussed in this section to read a PNG -file. - -Setup - -You will want to do the I/O initialization(*) before you get into libpng, -so if it doesn't work, you don't have much to undo. Of course, you -will also want to insure that you are, in fact, dealing with a PNG -file. Libpng provides a simple check to see if a file is a PNG file. -To use it, pass in the first 1 to 8 bytes of the file to the function -png_sig_cmp(), and it will return 0 (false) if the bytes match the -corresponding bytes of the PNG signature, or nonzero (true) otherwise. -Of course, the more bytes you pass in, the greater the accuracy of the -prediction. - -If you are intending to keep the file pointer open for use in libpng, -you must ensure you don't read more than 8 bytes from the beginning -of the file, and you also have to make a call to png_set_sig_bytes() -with the number of bytes you read from the beginning. Libpng will -then only check the bytes (if any) that your program didn't read. - -(*): If you are not using the standard I/O functions, you will need -to replace them with custom functions. See the discussion under -Customizing libpng. - - FILE *fp = fopen(file_name, "rb"); - if (!fp) - { - return (ERROR); - } - - if (fread(header, 1, number, fp) != number) - { - return (ERROR); - } - - is_png = !png_sig_cmp(header, 0, number); - if (!is_png) - { - return (NOT_PNG); - } - -Next, png_struct and png_info need to be allocated and initialized. In -order to ensure that the size of these structures is correct even with a -dynamically linked libpng, there are functions to initialize and -allocate the structures. We also pass the library version, optional -pointers to error handling functions, and a pointer to a data struct for -use by the error functions, if necessary (the pointer and functions can -be NULL if the default error handlers are to be used). See the section -on Changes to Libpng below regarding the old initialization functions. -The structure allocation functions quietly return NULL if they fail to -create the structure, so your application should check for that. - - png_structp png_ptr = png_create_read_struct - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn); - - if (!png_ptr) - return (ERROR); - - png_infop info_ptr = png_create_info_struct(png_ptr); - - if (!info_ptr) - { - png_destroy_read_struct(&png_ptr, - (png_infopp)NULL, (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, - user_error_fn, user_warning_fn, (png_voidp) - user_mem_ptr, user_malloc_fn, user_free_fn); - -The error handling routines passed to png_create_read_struct() -and the memory alloc/free routines passed to png_create_struct_2() -are only necessary if you are not using the libpng supplied error -handling and memory alloc/free functions. - -When libpng encounters an error, it expects to longjmp back -to your routine. Therefore, you will need to call setjmp and pass -your png_jmpbuf(png_ptr). If you read the file from different -routines, you will need to update the longjmp buffer every time you enter -a new routine that will call a png_*() function. - -See your documentation of setjmp/longjmp for your compiler for more -information on setjmp/longjmp. See the discussion on libpng error -handling in the Customizing Libpng section below for more information -on the libpng error handling. If an error occurs, and libpng longjmp's -back to your setjmp, you will want to call png_destroy_read_struct() to -free any memory. - - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - &end_info); - fclose(fp); - 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(). - -You can #define PNG_ABORT() to a function that does something -more useful than abort(), as long as your function does not -return. - -Now you need to set up the input code. The default for libpng is to -use the C function fread(). If you use this, you will need to pass a -valid FILE * in the function png_init_io(). Be sure that the file is -opened in binary mode. If you wish to handle reading data in another -way, you need not call the png_init_io() function, but you must then -implement the libpng I/O methods discussed in the Customizing Libpng -section below. - - png_init_io(png_ptr, fp); - -If you had previously opened the file and read any of the signature from -the beginning in order to see if this was a PNG file, you need to let -libpng know that there are some bytes missing from the start of the file. - - png_set_sig_bytes(png_ptr, number); - -You can change the zlib compression buffer size to be used while -reading compressed data with - - png_set_compression_buffer_size(png_ptr, buffer_size); - -where the default size is 8192 bytes. Note that the buffer size -is changed immediately and the buffer is reallocated immediately, -instead of setting a flag to be acted upon later. - -If you want CRC errors to be handled in a different manner than -the default, use - - png_set_crc_action(png_ptr, crit_action, ancil_action); - -The values for png_set_crc_action() say how libpng is to handle CRC errors in -ancillary and critical chunks, and whether to use the data contained -therein. Starting with libpng-1.6.26, this also governs how an ADLER32 error -is handled while reading the IDAT chunk. Note that it is impossible to -"discard" data in a critical chunk. - -Choices for (int) crit_action are - PNG_CRC_DEFAULT 0 error/quit - PNG_CRC_ERROR_QUIT 1 error/quit - PNG_CRC_WARN_USE 3 warn/use data - PNG_CRC_QUIET_USE 4 quiet/use data - PNG_CRC_NO_CHANGE 5 use the current value - -Choices for (int) ancil_action are - PNG_CRC_DEFAULT 0 error/quit - PNG_CRC_ERROR_QUIT 1 error/quit - PNG_CRC_WARN_DISCARD 2 warn/discard data - PNG_CRC_WARN_USE 3 warn/use data - PNG_CRC_QUIET_USE 4 quiet/use data - PNG_CRC_NO_CHANGE 5 use the current value - -When the setting for crit_action is PNG_CRC_QUIET_USE, the CRC and ADLER32 -checksums are not only ignored, but they are not evaluated. - -Setting up callback code - -You can set up a callback function to handle any unknown chunks in the -input stream. You must supply the function - - read_chunk_callback(png_structp png_ptr, - png_unknown_chunkp chunk); - { - /* The unknown chunk structure contains your - chunk data, along with similar data for any other - unknown chunks: */ - - png_byte name[5]; - png_byte *data; - png_size_t size; - - /* Note that libpng has already taken care of - the CRC handling */ - - /* put your code here. Search for your chunk in the - unknown chunk structure, process it, and return one - of the following: */ - - return (-n); /* chunk had an error */ - return (0); /* did not recognize */ - return (n); /* success */ - } - -(You can give your function another name that you like instead of -"read_chunk_callback") - -To inform libpng about your function, use - - png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr, - read_chunk_callback); - -This names not only the callback function, but also a user pointer that -you can retrieve with - - png_get_user_chunk_ptr(png_ptr); - -If you call the png_set_read_user_chunk_fn() function, then all unknown -chunks which the callback does not handle will be saved when read. You can -cause them to be discarded by returning '1' ("handled") instead of '0'. This -behavior will change in libpng 1.7 and the default handling set by the -png_set_keep_unknown_chunks() function, described below, will be used when the -callback returns 0. If you want the existing behavior you should set the global -default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current -versions of libpng and with 1.7. Libpng 1.6 issues a warning if you keep the -default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0. - -At this point, you can set up a callback function that will be -called after each row has been read, which you can use to control -a progress meter or the like. It's demonstrated in pngtest.c. -You must supply a function - - void read_row_callback(png_structp png_ptr, - png_uint_32 row, int pass); - { - /* put your code here */ - } - -(You can give it another name that you like instead of "read_row_callback") - -To inform libpng about your function, use - - png_set_read_status_fn(png_ptr, read_row_callback); - -When this function is called the row has already been completely processed and -the 'row' and 'pass' refer to the next row to be handled. For the -non-interlaced case the row that was just handled is simply one less than the -passed in row number, and pass will always be 0. For the interlaced case the -same applies unless the row value is 0, in which case the row just handled was -the last one from one of the preceding passes. Because interlacing may skip a -pass you cannot be sure that the preceding pass is just 'pass-1'; if you really -need to know what the last pass is record (row,pass) from the callback and use -the last recorded value each time. - -As with the user transform you can find the output row using the -PNG_ROW_FROM_PASS_ROW macro. - -Unknown-chunk handling - -Now you get to set the way the library processes unknown chunks in the -input PNG stream. Both known and unknown chunks will be read. Normal -behavior is that known chunks will be parsed into information in -various info_ptr members while unknown chunks will be discarded. This -behavior can be wasteful if your application will never use some known -chunk types. To change this, you can call: - - png_set_keep_unknown_chunks(png_ptr, keep, - chunk_list, num_chunks); - - keep - 0: default unknown chunk handling - 1: ignore; do not keep - 2: keep only if safe-to-copy - 3: keep even if unsafe-to-copy - - You can use these definitions: - PNG_HANDLE_CHUNK_AS_DEFAULT 0 - PNG_HANDLE_CHUNK_NEVER 1 - PNG_HANDLE_CHUNK_IF_SAFE 2 - PNG_HANDLE_CHUNK_ALWAYS 3 - - chunk_list - list of chunks affected (a byte string, - five bytes per chunk, NULL or '\0' if - num_chunks is positive; ignored if - numchunks <= 0). - - num_chunks - number of chunks affected; if 0, all - unknown chunks are affected. If positive, - only the chunks in the list are affected, - and if negative all unknown chunks and - all known chunks except for the IHDR, - PLTE, tRNS, IDAT, and IEND chunks are - affected. - -Unknown chunks declared in this way will be saved as raw data onto a -list of png_unknown_chunk structures. If a chunk that is normally -known to libpng is named in the list, it will be handled as unknown, -according to the "keep" directive. If a chunk is named in successive -instances of png_set_keep_unknown_chunks(), the final instance will -take precedence. The IHDR and IEND chunks should not be named in -chunk_list; if they are, libpng will process them normally anyway. -If you know that your application will never make use of some particular -chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below. - -Here is an example of the usage of png_set_keep_unknown_chunks(), -where the private "vpAg" chunk will later be processed by a user chunk -callback function: - - png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'}; - - #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) - png_byte unused_chunks[]= - { - 104, 73, 83, 84, (png_byte) '\0', /* hIST */ - 105, 84, 88, 116, (png_byte) '\0', /* iTXt */ - 112, 67, 65, 76, (png_byte) '\0', /* pCAL */ - 115, 67, 65, 76, (png_byte) '\0', /* sCAL */ - 115, 80, 76, 84, (png_byte) '\0', /* sPLT */ - 116, 73, 77, 69, (png_byte) '\0', /* tIME */ - }; - #endif - - ... - - #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) - /* ignore all unknown chunks - * (use global setting "2" for libpng16 and earlier): - */ - png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0); - - /* except for vpAg: */ - png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1); - - /* also ignore unused known chunks: */ - png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks, - (int)(sizeof unused_chunks)/5); - #endif - -User limits - -The PNG specification allows the width and height of an image to be as -large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns. -For safety, libpng imposes a default limit of 1 million rows and columns. -Larger images will be rejected immediately with a png_error() call. If -you wish to change these limits, you can use - - png_set_user_limits(png_ptr, width_max, height_max); - -to set your own limits (libpng may reject some very wide images -anyway because of potential buffer overflow conditions). - -You should put this statement after you create the PNG structure and -before calling png_read_info(), png_read_png(), or png_process_data(). - -When writing a PNG datastream, put this statement before calling -png_write_info() or png_write_png(). - -If you need to retrieve the limits that are being applied, use - - width_max = png_get_user_width_max(png_ptr); - height_max = png_get_user_height_max(png_ptr); - -The PNG specification sets no limit on the number of ancillary chunks -allowed in a PNG datastream. By default, libpng imposes a limit of -a total of 1000 sPLT, tEXt, iTXt, zTXt, and unknown chunks to be stored. -If you have set up both info_ptr and end_info_ptr, the limit applies -separately to each. You can change the limit on the total number of such -chunks that will be stored, with - - png_set_chunk_cache_max(png_ptr, user_chunk_cache_max); - -where 0x7fffffffL means unlimited. You can retrieve this limit with - - chunk_cache_max = png_get_chunk_cache_max(png_ptr); - -Libpng imposes a limit of 8 Megabytes (8,000,000 bytes) on the amount of -memory that any chunk other than IDAT can occupy, originally or when -decompressed (prior to libpng-1.6.32 the limit was only applied to compressed -chunks after decompression). You can change this limit with - - png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max); - -and you can retrieve the limit with - - chunk_malloc_max = png_get_chunk_malloc_max(png_ptr); - -Any chunks that would cause either of these limits to be exceeded will -be ignored. - -Information about your system - -If you intend to display the PNG or to incorporate it in other image data you -need to tell libpng information about your display or drawing surface so that -libpng can convert the values in the image to match the display. - -From libpng-1.5.4 this information can be set before reading the PNG file -header. In earlier versions png_set_gamma() existed but behaved incorrectly if -called before the PNG file header had been read and png_set_alpha_mode() did not -exist. - -If you need to support versions prior to libpng-1.5.4 test the version number -as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures -described in the appropriate manual page. - -You give libpng the encoding expected by your system expressed as a 'gamma' -value. You can also specify a default encoding for the PNG file in -case the required information is missing from the file. By default libpng -assumes that the PNG data matches your system, to keep this default call: - - png_set_gamma(png_ptr, screen_gamma, output_gamma); - -or you can use the fixed point equivalent: - - png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma, - PNG_FP_1*output_gamma); - -If you don't know the gamma for your system it is probably 2.2 - a good -approximation to the IEC standard for display systems (sRGB). If images are -too contrasty or washed out you got the value wrong - check your system -documentation! - -Many systems permit the system gamma to be changed via a lookup table in the -display driver, a few systems, including older Macs, change the response by -default. As of 1.5.4 three special values are available to handle common -situations: - - PNG_DEFAULT_sRGB: Indicates that the system conforms to the - IEC 61966-2-1 standard. This matches almost - all systems. - PNG_GAMMA_MAC_18: Indicates that the system is an older - (pre Mac OS 10.6) Apple Macintosh system with - the default settings. - PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates - that the system expects data with no gamma - encoding. - -You would use the linear (unencoded) value if you need to process the pixel -values further because this avoids the need to decode and re-encode each -component value whenever arithmetic is performed. A lot of graphics software -uses linear values for this reason, often with higher precision component values -to preserve overall accuracy. - - -The output_gamma value expresses how to decode the output values, not how -they are encoded. The values used correspond to the normal numbers used to -describe the overall gamma of a computer display system; for example 2.2 for -an sRGB conformant system. The values are scaled by 100000 in the _fixed -version of the API (so 220000 for sRGB.) - -The inverse of the value is always used to provide a default for the PNG file -encoding if it has no gAMA chunk and if png_set_gamma() has not been called -to override the PNG gamma information. - -When the ALPHA_OPTIMIZED mode is selected the output gamma is used to encode -opaque pixels however pixels with lower alpha values are not encoded, -regardless of the output gamma setting. - -When the standard Porter Duff handling is requested with mode 1 the output -encoding is set to be linear and the output_gamma value is only relevant -as a default for input data that has no gamma information. The linear output -encoding will be overridden if png_set_gamma() is called - the results may be -highly unexpected! - -The following numbers are derived from the sRGB standard and the research -behind it. sRGB is defined to be approximated by a PNG gAMA chunk value of -0.45455 (1/2.2) for PNG. The value implicitly includes any viewing -correction required to take account of any differences in the color -environment of the original scene and the intended display environment; the -value expresses how to *decode* the image for display, not how the original -data was *encoded*. - -sRGB provides a peg for the PNG standard by defining a viewing environment. -sRGB itself, and earlier TV standards, actually use a more complex transform -(a linear portion then a gamma 2.4 power law) than PNG can express. (PNG is -limited to simple power laws.) By saying that an image for direct display on -an sRGB conformant system should be stored with a gAMA chunk value of 45455 -(11.3.3.2 and 11.3.3.5 of the ISO PNG specification) the PNG specification -makes it possible to derive values for other display systems and -environments. - -The Mac value is deduced from the sRGB based on an assumption that the actual -extra viewing correction used in early Mac display systems was implemented as -a power 1.45 lookup table. - -Any system where a programmable lookup table is used or where the behavior of -the final display device characteristics can be changed requires system -specific code to obtain the current characteristic. However this can be -difficult and most PNG gamma correction only requires an approximate value. - -By default, if png_set_alpha_mode() is not called, libpng assumes that all -values are unencoded, linear, values and that the output device also has a -linear characteristic. This is only very rarely correct - it is invariably -better to call png_set_alpha_mode() with PNG_DEFAULT_sRGB than rely on the -default if you don't know what the right answer is! - -The special value PNG_GAMMA_MAC_18 indicates an older Mac system (pre Mac OS -10.6) which used a correction table to implement a somewhat lower gamma on an -otherwise sRGB system. - -Both these values are reserved (not simple gamma values) in order to allow -more precise correction internally in the future. - -NOTE: the values can be passed to either the fixed or floating -point APIs, but the floating point API will also accept floating point -values. - -The second thing you may need to tell libpng about is how your system handles -alpha channel information. Some, but not all, PNG files contain an alpha -channel. To display these files correctly you need to compose the data onto a -suitable background, as described in the PNG specification. - -Libpng only supports composing onto a single color (using png_set_background; -see below). Otherwise you must do the composition yourself and, in this case, -you may need to call png_set_alpha_mode: - - #if PNG_LIBPNG_VER >= 10504 - png_set_alpha_mode(png_ptr, mode, screen_gamma); - #else - png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma); - #endif - -The screen_gamma value is the same as the argument to png_set_gamma; however, -how it affects the output depends on the mode. png_set_alpha_mode() sets the -file gamma default to 1/screen_gamma, so normally you don't need to call -png_set_gamma. If you need different defaults call png_set_gamma() before -png_set_alpha_mode() - if you call it after it will override the settings made -by png_set_alpha_mode(). - -The mode is as follows: - - PNG_ALPHA_PNG: The data is encoded according to the PNG -specification. Red, green and blue, or gray, components are -gamma encoded color values and are not premultiplied by the -alpha value. The alpha value is a linear measure of the -contribution of the pixel to the corresponding final output pixel. - -You should normally use this format if you intend to perform -color correction on the color values; most, maybe all, color -correction software has no handling for the alpha channel and, -anyway, the math to handle pre-multiplied component values is -unnecessarily complex. - -Before you do any arithmetic on the component values you need -to remove the gamma encoding and multiply out the alpha -channel. See the PNG specification for more detail. It is -important to note that when an image with an alpha channel is -scaled, linear encoded, pre-multiplied component values must -be used! - -The remaining modes assume you don't need to do any further color correction or -that if you do, your color correction software knows all about alpha (it -probably doesn't!). They 'associate' the alpha with the color information by -storing color channel values that have been scaled by the alpha. The -advantage is that the color channels can be resampled (the image can be -scaled) in this form. The disadvantage is that normal practice is to store -linear, not (gamma) encoded, values and this requires 16-bit channels for -still images rather than the 8-bit channels that are just about sufficient if -gamma encoding is used. In addition all non-transparent pixel values, -including completely opaque ones, must be gamma encoded to produce the final -image. These are the 'STANDARD', 'ASSOCIATED' or 'PREMULTIPLIED' modes -described below (the latter being the two common names for associated alpha -color channels). Note that PNG files always contain non-associated color -channels; png_set_alpha_mode() with one of the modes causes the decoder to -convert the pixels to an associated form before returning them to your -application. - -Since it is not necessary to perform arithmetic on opaque color values so -long as they are not to be resampled and are in the final color space it is -possible to optimize the handling of alpha by storing the opaque pixels in -the PNG format (adjusted for the output color space) while storing partially -opaque pixels in the standard, linear, format. The accuracy required for -standard alpha composition is relatively low, because the pixels are -isolated, therefore typically the accuracy loss in storing 8-bit linear -values is acceptable. (This is not true if the alpha channel is used to -simulate transparency over large areas - use 16 bits or the PNG mode in -this case!) This is the 'OPTIMIZED' mode. For this mode a pixel is -treated as opaque only if the alpha value is equal to the maximum value. - - PNG_ALPHA_STANDARD: The data libpng produces is encoded in the -standard way assumed by most correctly written graphics software. -The gamma encoding will be removed by libpng and the -linear component values will be pre-multiplied by the -alpha channel. - -With this format the final image must be re-encoded to -match the display gamma before the image is displayed. -If your system doesn't do that, yet still seems to -perform arithmetic on the pixels without decoding them, -it is broken - check out the modes below. - -With PNG_ALPHA_STANDARD libpng always produces linear -component values, whatever screen_gamma you supply. The -screen_gamma value is, however, used as a default for -the file gamma if the PNG file has no gamma information. - -If you call png_set_gamma() after png_set_alpha_mode() you -will override the linear encoding. Instead the -pre-multiplied pixel values will be gamma encoded but -the alpha channel will still be linear. This may -actually match the requirements of some broken software, -but it is unlikely. - -While linear 8-bit data is often used it has -insufficient precision for any image with a reasonable -dynamic range. To avoid problems, and if your software -supports it, use png_set_expand_16() to force all -components to 16 bits. - - PNG_ALPHA_OPTIMIZED: This mode is the same as PNG_ALPHA_STANDARD -except that completely opaque pixels are gamma encoded according to -the screen_gamma value. Pixels with alpha less than 1.0 -will still have linear components. - -Use this format if you have control over your -compositing software and so don't do other arithmetic -(such as scaling) on the data you get from libpng. Your -compositing software can simply copy opaque pixels to -the output but still has linear values for the -non-opaque pixels. - -In normal compositing, where the alpha channel encodes -partial pixel coverage (as opposed to broad area -translucency), the inaccuracies of the 8-bit -representation of non-opaque pixels are irrelevant. - -You can also try this format if your software is broken; -it might look better. - - PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD; however, all component -values, including the alpha channel are gamma encoded. This is -broken because, in practice, no implementation that uses this choice -correctly undoes the encoding before handling alpha composition. Use this -choice only if other serious errors in the software or hardware you use -mandate it. In most cases of broken software or hardware the bug in the -final display manifests as a subtle halo around composited parts of the -image. You may not even perceive this as a halo; the composited part of -the image may simply appear separate from the background, as though it had -been cut out of paper and pasted on afterward. - -If you don't have to deal with bugs in software or hardware, or if you can fix -them, there are three recommended ways of using png_set_alpha_mode(): - - png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG, - screen_gamma); - -You can do color correction on the result (libpng does not currently -support color correction internally). When you handle the alpha channel -you need to undo the gamma encoding and multiply out the alpha. - - png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD, - screen_gamma); - png_set_expand_16(png_ptr); - -If you are using the high level interface, don't call png_set_expand_16(); -instead pass PNG_TRANSFORM_EXPAND_16 to the interface. - -With this mode you can't do color correction, but you can do arithmetic, -including composition and scaling, on the data without further processing. - - png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED, - screen_gamma); - -You can avoid the expansion to 16-bit components with this mode, but you -lose the ability to scale the image or perform other linear arithmetic. -All you can do is compose the result onto a matching output. Since this -mode is libpng-specific you also need to write your own composition -software. - -The following are examples of calls to png_set_alpha_mode to achieve the -required overall gamma correction and, where necessary, alpha -premultiplication. - - png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB); - -Choices for the alpha_mode are - - PNG_ALPHA_PNG 0 /* according to the PNG standard */ - PNG_ALPHA_STANDARD 1 /* according to Porter/Duff */ - PNG_ALPHA_ASSOCIATED 1 /* as above; this is the normal practice */ - PNG_ALPHA_PREMULTIPLIED 1 /* as above */ - PNG_ALPHA_OPTIMIZED 2 /* 'PNG' for opaque pixels, else 'STANDARD' */ - PNG_ALPHA_BROKEN 3 /* the alpha channel is gamma encoded */ - -PNG_ALPHA_PNG is the default libpng handling of the alpha channel. It is not -pre-multiplied into the color components. In addition the call states -that the output is for a sRGB system and causes all PNG files without gAMA -chunks to be assumed to be encoded using sRGB. - - png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC); - -In this case the output is assumed to be something like an sRGB conformant -display preceeded by a power-law lookup table of power 1.45. This is how -early Mac systems behaved. - - png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_GAMMA_LINEAR); - -This is the classic Jim Blinn approach and will work in academic -environments where everything is done by the book. It has the shortcoming -of assuming that input PNG data with no gamma information is linear - this -is unlikely to be correct unless the PNG files were generated locally. -Most of the time the output precision will be so low as to show -significant banding in dark areas of the image. - - png_set_expand_16(pp); - png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_DEFAULT_sRGB); - -This is a somewhat more realistic Jim Blinn inspired approach. PNG files -are assumed to have the sRGB encoding if not marked with a gamma value and -the output is always 16 bits per component. This permits accurate scaling -and processing of the data. If you know that your input PNG files were -generated locally you might need to replace PNG_DEFAULT_sRGB with the -correct value for your system. - - png_set_alpha_mode(pp, PNG_ALPHA_OPTIMIZED, PNG_DEFAULT_sRGB); - -If you just need to composite the PNG image onto an existing background -and if you control the code that does this you can use the optimization -setting. In this case you just copy completely opaque pixels to the -output. For pixels that are not completely transparent (you just skip -those) you do the composition math using png_composite or png_composite_16 -below then encode the resultant 8-bit or 16-bit values to match the output -encoding. - - Other cases - -If neither the PNG nor the standard linear encoding work for you because -of the software or hardware you use then you have a big problem. The PNG -case will probably result in halos around the image. The linear encoding -will probably result in a washed out, too bright, image (it's actually too -contrasty.) Try the ALPHA_OPTIMIZED mode above - this will probably -substantially reduce the halos. Alternatively try: - - png_set_alpha_mode(pp, PNG_ALPHA_BROKEN, PNG_DEFAULT_sRGB); - -This option will also reduce the halos, but there will be slight dark -halos round the opaque parts of the image where the background is light. -In the OPTIMIZED mode the halos will be light halos where the background -is dark. Take your pick - the halos are unavoidable unless you can get -your hardware/software fixed! (The OPTIMIZED approach is slightly -faster.) - -When the default gamma of PNG files doesn't match the output gamma. -If you have PNG files with no gamma information png_set_alpha_mode allows -you to provide a default gamma, but it also sets the ouput gamma to the -matching value. If you know your PNG files have a gamma that doesn't -match the output you can take advantage of the fact that -png_set_alpha_mode always sets the output gamma but only sets the PNG -default if it is not already set: - - png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB); - png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC); - -The first call sets both the default and the output gamma values, the -second call overrides the output gamma without changing the default. This -is easier than achieving the same effect with png_set_gamma. You must use -PNG_ALPHA_PNG for the first call - internal checking in png_set_alpha will -fire if more than one call to png_set_alpha_mode and png_set_background is -made in the same read operation, however multiple calls with PNG_ALPHA_PNG -are ignored. - -If you don't need, or can't handle, the alpha channel you can call -png_set_background() to remove it by compositing against a fixed color. Don't -call png_set_strip_alpha() to do this - it will leave spurious pixel values in -transparent parts of this image. - - png_set_background(png_ptr, &background_color, - PNG_BACKGROUND_GAMMA_SCREEN, 0, 1); - -The background_color is an RGB or grayscale value according to the data format -libpng will produce for you. Because you don't yet know the format of the PNG -file, if you call png_set_background at this point you must arrange for the -format produced by libpng to always have 8-bit or 16-bit components and then -store the color as an 8-bit or 16-bit color as appropriate. The color contains -separate gray and RGB component values, so you can let libpng produce gray or -RGB output according to the input format, but low bit depth grayscale images -must always be converted to at least 8-bit format. (Even though low bit depth -grayscale images can't have an alpha channel they can have a transparent -color!) - -You set the transforms you need later, either as flags to the high level -interface or libpng API calls for the low level interface. For reference the -settings and API calls required are: - -8-bit values: - PNG_TRANSFORM_SCALE_16 | PNG_EXPAND - png_set_expand(png_ptr); png_set_scale_16(png_ptr); - - If you must get exactly the same inaccurate results - produced by default in versions prior to libpng-1.5.4, - use PNG_TRANSFORM_STRIP_16 and png_set_strip_16(png_ptr) - instead. - -16-bit values: - PNG_TRANSFORM_EXPAND_16 - png_set_expand_16(png_ptr); - -In either case palette image data will be expanded to RGB. If you just want -color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr) -to the list. - -Calling png_set_background before the PNG file header is read will not work -prior to libpng-1.5.4. Because the failure may result in unexpected warnings or -errors it is therefore much safer to call png_set_background after the head has -been read. Unfortunately this means that prior to libpng-1.5.4 it cannot be -used with the high level interface. - -The high-level read interface - -At this point there are two ways to proceed; through the high-level -read interface, or through a sequence of low-level read operations. -You can use the high-level interface if (a) you are willing to read -the entire image into memory, and (b) the input transformations -you want to do are limited to the following set: - - PNG_TRANSFORM_IDENTITY No transformation - PNG_TRANSFORM_SCALE_16 Strip 16-bit samples to - 8-bit accurately - PNG_TRANSFORM_STRIP_16 Chop 16-bit samples to - 8-bit less accurately - PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel - PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit - samples to bytes - PNG_TRANSFORM_PACKSWAP Change order of packed - pixels to LSB first - PNG_TRANSFORM_EXPAND Perform set_expand() - PNG_TRANSFORM_INVERT_MONO Invert monochrome images - PNG_TRANSFORM_SHIFT Normalize pixels to the - sBIT depth - PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA - to BGRA - PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA - to AG - PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity - to transparency - PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples - PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples - to RGB (or GA to RGBA) - PNG_TRANSFORM_EXPAND_16 Expand samples to 16 bits - -(This excludes setting a background color, doing gamma transformation, -quantizing, and setting filler.) If this is the case, simply do this: - - png_read_png(png_ptr, info_ptr, png_transforms, NULL) - -where png_transforms is an integer containing the bitwise OR of some -set of transformation flags. This call is equivalent to png_read_info(), -followed the set of transformations indicated by the transform mask, -then png_read_image(), and finally png_read_end(). - -(The final parameter of this call is not yet used. Someday it might point -to transformation parameters required by some future input transform.) - -You must use png_transforms and not call any png_set_transform() functions -when you use png_read_png(). - -After you have called png_read_png(), you can retrieve the image data -with - - row_pointers = png_get_rows(png_ptr, info_ptr); - -where row_pointers is an array of pointers to the pixel data for each row: - - png_bytep row_pointers[height]; - -If you know your image size and pixel size ahead of time, you can allocate -row_pointers prior to calling png_read_png() with - - if (height > PNG_UINT_32_MAX/(sizeof (png_byte))) - png_error (png_ptr, - "Image is too tall to process in memory"); - - if (width > PNG_UINT_32_MAX/pixel_size) - png_error (png_ptr, - "Image is too wide to process in memory"); - - row_pointers = png_malloc(png_ptr, - height*(sizeof (png_bytep))); - - for (int i=0; i<height, i++) - row_pointers[i]=NULL; /* security precaution */ - - for (int i=0; i<height, i++) - row_pointers[i]=png_malloc(png_ptr, - width*pixel_size); - - png_set_rows(png_ptr, info_ptr, &row_pointers); - -Alternatively you could allocate your image in one big block and define -row_pointers[i] to point into the proper places in your block, but first -be sure that your platform is able to allocate such a large buffer: - - /* Guard against integer overflow */ - if (height > PNG_SIZE_MAX/(width*pixel_size)) { - png_error(png_ptr,"image_data buffer would be too large"); - } - - png_bytep buffer=png_malloc(png_ptr,height*width*pixel_size); - - for (int i=0; i<height, i++) - row_pointers[i]=buffer+i*width*pixel_size; - - png_set_rows(png_ptr, info_ptr, &row_pointers); - -If you use png_set_rows(), the application is responsible for freeing -row_pointers (and row_pointers[i], if they were separately allocated). - -If you don't allocate row_pointers ahead of time, png_read_png() will -do it, and it'll be free'ed by libpng when you call png_destroy_*(). - -The low-level read interface - -If you are going the low-level route, you are now ready to read all -the file information up to the actual image data. You do this with a -call to png_read_info(). - - png_read_info(png_ptr, info_ptr); - -This will process all chunks up to but not including the image data. - -This also copies some of the data from the PNG file into the decode structure -for use in later transformations. Important information copied in is: - -1) The PNG file gamma from the gAMA chunk. This overwrites the default value -provided by an earlier call to png_set_gamma or png_set_alpha_mode. - -2) Prior to libpng-1.5.4 the background color from a bKGd chunk. This -damages the information provided by an earlier call to png_set_background -resulting in unexpected behavior. Libpng-1.5.4 no longer does this. - -3) The number of significant bits in each component value. Libpng uses this to -optimize gamma handling by reducing the internal lookup table sizes. - -4) The transparent color information from a tRNS chunk. This can be modified by -a later call to png_set_tRNS. - -Querying the info structure - -Functions are used to get the information from the info_ptr once it -has been read. Note that these fields may not be completely filled -in until png_read_end() has read the chunk data following the image. - - png_get_IHDR(png_ptr, info_ptr, &width, &height, - &bit_depth, &color_type, &interlace_type, - &compression_type, &filter_method); - - width - holds the width of the image - in pixels (up to 2^31). - - height - holds the height of the image - in pixels (up to 2^31). - - bit_depth - holds the bit depth of one of the - image channels. (valid values are - 1, 2, 4, 8, 16 and depend also on - the color_type. See also - significant bits (sBIT) below). - - color_type - describes which color/alpha channels - are present. - PNG_COLOR_TYPE_GRAY - (bit depths 1, 2, 4, 8, 16) - PNG_COLOR_TYPE_GRAY_ALPHA - (bit depths 8, 16) - PNG_COLOR_TYPE_PALETTE - (bit depths 1, 2, 4, 8) - PNG_COLOR_TYPE_RGB - (bit_depths 8, 16) - PNG_COLOR_TYPE_RGB_ALPHA - (bit_depths 8, 16) - - PNG_COLOR_MASK_PALETTE - PNG_COLOR_MASK_COLOR - PNG_COLOR_MASK_ALPHA - - interlace_type - (PNG_INTERLACE_NONE or - PNG_INTERLACE_ADAM7) - - compression_type - (must be PNG_COMPRESSION_TYPE_BASE - for PNG 1.0) - - filter_method - (must be PNG_FILTER_TYPE_BASE - for PNG 1.0, and can also be - PNG_INTRAPIXEL_DIFFERENCING if - the PNG datastream is embedded in - a MNG-1.0 datastream) - - Any of width, height, color_type, bit_depth, - interlace_type, compression_type, or filter_method can - be NULL if you are not interested in their values. - - Note that png_get_IHDR() returns 32-bit data into - the application's width and height variables. - This is an unsafe situation if these are not png_uint_32 - variables. In such situations, the - png_get_image_width() and png_get_image_height() - functions described below are safer. - - width = png_get_image_width(png_ptr, - info_ptr); - - height = png_get_image_height(png_ptr, - info_ptr); - - bit_depth = png_get_bit_depth(png_ptr, - info_ptr); - - color_type = png_get_color_type(png_ptr, - info_ptr); - - interlace_type = png_get_interlace_type(png_ptr, - info_ptr); - - compression_type = png_get_compression_type(png_ptr, - info_ptr); - - filter_method = png_get_filter_type(png_ptr, - info_ptr); - - channels = png_get_channels(png_ptr, info_ptr); - - channels - number of channels of info for the - color type (valid values are 1 (GRAY, - PALETTE), 2 (GRAY_ALPHA), 3 (RGB), - 4 (RGB_ALPHA or RGB + filler byte)) - - rowbytes = png_get_rowbytes(png_ptr, info_ptr); - - rowbytes - number of bytes needed to hold a row - This value, the bit_depth, color_type, - and the number of channels can change - if you use transforms such as - png_set_expand(). See - png_read_update_info(), below. - - signature = png_get_signature(png_ptr, info_ptr); - - signature - holds the signature read from the - file (if any). The data is kept in - the same offset it would be if the - whole signature were read (i.e. if an - application had already read in 4 - bytes of signature before starting - libpng, the remaining 4 bytes would - be in signature[4] through signature[7] - (see png_set_sig_bytes())). - -These are also important, but their validity depends on whether the chunk -has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and -png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the -data has been read, or zero if it is missing. The parameters to the -png_get_<chunk> are set directly if they are simple data types, or a -pointer into the info_ptr is returned for any complex types. - -The colorspace data from gAMA, cHRM, sRGB, iCCP, and sBIT chunks -is simply returned to give the application information about how the -image was encoded. Libpng itself only does transformations using the file -gamma when combining semitransparent pixels with the background color, and, -since libpng-1.6.0, when converting between 8-bit sRGB and 16-bit linear pixels -within the simplified API. Libpng also uses the file gamma when converting -RGB to gray, beginning with libpng-1.0.5, if the application calls -png_set_rgb_to_gray()). - - png_get_PLTE(png_ptr, info_ptr, &palette, - &num_palette); - - palette - the palette for the file - (array of png_color) - - num_palette - number of entries in the palette - - png_get_gAMA(png_ptr, info_ptr, &file_gamma); - png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma); - - file_gamma - the gamma at which the file is - written (PNG_INFO_gAMA) - - int_file_gamma - 100,000 times the gamma at which the - file is written - - png_get_cHRM(png_ptr, info_ptr, &white_x, &white_y, &red_x, - &red_y, &green_x, &green_y, &blue_x, &blue_y) - png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z, - &green_X, &green_Y, &green_Z, &blue_X, &blue_Y, - &blue_Z) - png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x, - &int_white_y, &int_red_x, &int_red_y, - &int_green_x, &int_green_y, &int_blue_x, - &int_blue_y) - png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y, - &int_red_Z, &int_green_X, &int_green_Y, - &int_green_Z, &int_blue_X, &int_blue_Y, - &int_blue_Z) - - {white,red,green,blue}_{x,y} - A color space encoding specified using the - chromaticities of the end points and the - white point. (PNG_INFO_cHRM) - - {red,green,blue}_{X,Y,Z} - A color space encoding specified using the - encoding end points - the CIE tristimulus - specification of the intended color of the red, - green and blue channels in the PNG RGB data. - The white point is simply the sum of the three - end points. (PNG_INFO_cHRM) - - png_get_sRGB(png_ptr, info_ptr, &srgb_intent); - - srgb_intent - the rendering intent (PNG_INFO_sRGB) - The presence of the sRGB chunk - means that the pixel data is in the - sRGB color space. This chunk also - implies specific values of gAMA and - cHRM. - - png_get_iCCP(png_ptr, info_ptr, &name, - &compression_type, &profile, &proflen); - - name - The profile name. - - compression_type - The compression type; always - PNG_COMPRESSION_TYPE_BASE for PNG 1.0. - You may give NULL to this argument to - ignore it. - - profile - International Color Consortium color - profile data. May contain NULs. - - proflen - length of profile data in bytes. - - png_get_sBIT(png_ptr, info_ptr, &sig_bit); - - sig_bit - the number of significant bits for - (PNG_INFO_sBIT) each of the gray, - red, green, and blue channels, - whichever are appropriate for the - given color type (png_color_16) - - png_get_tRNS(png_ptr, info_ptr, &trans_alpha, - &num_trans, &trans_color); - - trans_alpha - array of alpha (transparency) - entries for palette (PNG_INFO_tRNS) - - num_trans - number of transparent entries - (PNG_INFO_tRNS) - - trans_color - graylevel or color sample values of - the single transparent color for - non-paletted images (PNG_INFO_tRNS) - - png_get_eXIf_1(png_ptr, info_ptr, &num_exif, &exif); - (PNG_INFO_eXIf) - - exif - Exif profile (array of png_byte) - - png_get_hIST(png_ptr, info_ptr, &hist); - (PNG_INFO_hIST) - - hist - histogram of palette (array of - png_uint_16) - - png_get_tIME(png_ptr, info_ptr, &mod_time); - - mod_time - time image was last modified - (PNG_VALID_tIME) - - png_get_bKGD(png_ptr, info_ptr, &background); - - background - background color (of type - png_color_16p) (PNG_VALID_bKGD) - valid 16-bit red, green and blue - values, regardless of color_type - - num_comments = png_get_text(png_ptr, info_ptr, - &text_ptr, &num_text); - - num_comments - number of comments - - text_ptr - array of png_text holding image - comments - - text_ptr[i].compression - type of compression used - on "text" PNG_TEXT_COMPRESSION_NONE - PNG_TEXT_COMPRESSION_zTXt - PNG_ITXT_COMPRESSION_NONE - PNG_ITXT_COMPRESSION_zTXt - - text_ptr[i].key - keyword for comment. Must contain - 1-79 characters. - - text_ptr[i].text - text comments for current - keyword. Can be empty. - - text_ptr[i].text_length - length of text string, - after decompression, 0 for iTXt - - text_ptr[i].itxt_length - length of itxt string, - after decompression, 0 for tEXt/zTXt - - text_ptr[i].lang - language of comment (empty - string for unknown). - - text_ptr[i].lang_key - keyword in UTF-8 - (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 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 - to avoid the duplication) - - Note while png_set_text() will accept text, language, - and translated keywords that can be NULL pointers, the - structure returned by png_get_text will always contain - regular zero-terminated C strings. They might be - empty strings but they will never be NULL pointers. - - num_spalettes = png_get_sPLT(png_ptr, info_ptr, - &palette_ptr); - - num_spalettes - number of sPLT chunks read. - - palette_ptr - array of palette structures holding - contents of one or more sPLT chunks - read. - - png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y, - &unit_type); - - offset_x - positive offset from the left edge - of the screen (can be negative) - - offset_y - positive offset from the top edge - of the screen (can be negative) - - unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER - - png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y, - &unit_type); - - res_x - pixels/unit physical resolution in - x direction - - res_y - pixels/unit physical resolution in - x direction - - unit_type - PNG_RESOLUTION_UNKNOWN, - PNG_RESOLUTION_METER - - png_get_sCAL(png_ptr, info_ptr, &unit, &width, - &height) - - unit - physical scale units (an integer) - - width - width of a pixel in physical scale units - - height - height of a pixel in physical scale units - (width and height are doubles) - - png_get_sCAL_s(png_ptr, info_ptr, &unit, &width, - &height) - - unit - physical scale units (an integer) - - width - width of a pixel in physical scale units - (expressed as a string) - - height - height of a pixel in physical scale units - (width and height are strings like "2.54") - - num_unknown_chunks = png_get_unknown_chunks(png_ptr, - info_ptr, &unknowns) - - unknowns - array of png_unknown_chunk - structures holding unknown chunks - - unknowns[i].name - name of unknown chunk - - unknowns[i].data - data of unknown chunk - - unknowns[i].size - size of unknown chunk's data - - unknowns[i].location - position of chunk in file - - The value of "i" corresponds to the order in which the - chunks were read from the PNG file or inserted with the - png_set_unknown_chunks() function. - - The value of "location" is a bitwise "or" of - - PNG_HAVE_IHDR (0x01) - PNG_HAVE_PLTE (0x02) - PNG_AFTER_IDAT (0x08) - -The data from the pHYs chunk can be retrieved in several convenient -forms: - - res_x = png_get_x_pixels_per_meter(png_ptr, - info_ptr) - - res_y = png_get_y_pixels_per_meter(png_ptr, - info_ptr) - - res_x_and_y = png_get_pixels_per_meter(png_ptr, - info_ptr) - - res_x = png_get_x_pixels_per_inch(png_ptr, - info_ptr) - - res_y = png_get_y_pixels_per_inch(png_ptr, - info_ptr) - - res_x_and_y = png_get_pixels_per_inch(png_ptr, - info_ptr) - - aspect_ratio = png_get_pixel_aspect_ratio(png_ptr, - info_ptr) - - Each of these returns 0 [signifying "unknown"] if - the data is not present or if res_x is 0; - res_x_and_y is 0 if res_x != res_y - - Note that because of the way the resolutions are - stored internally, the inch conversions won't - come out to exactly even number. For example, - 72 dpi is stored as 0.28346 pixels/meter, and - when this is retrieved it is 71.9988 dpi, so - be sure to round the returned value appropriately - if you want to display a reasonable-looking result. - -The data from the oFFs chunk can be retrieved in several convenient -forms: - - x_offset = png_get_x_offset_microns(png_ptr, info_ptr); - - y_offset = png_get_y_offset_microns(png_ptr, info_ptr); - - x_offset = png_get_x_offset_inches(png_ptr, info_ptr); - - y_offset = png_get_y_offset_inches(png_ptr, info_ptr); - - Each of these returns 0 [signifying "unknown" if both - x and y are 0] if the data is not present or if the - chunk is present but the unit is the pixel. The - remark about inexact inch conversions applies here - as well, because a value in inches can't always be - converted to microns and back without some loss - of precision. - -For more information, see the -PNG specification for chunk contents. Be careful with trusting -rowbytes, as some of the transformations could increase the space -needed to hold a row (expand, filler, gray_to_rgb, etc.). -See png_read_update_info(), below. - -A quick word about text_ptr and num_text. PNG stores comments in -keyword/text pairs, one pair per chunk, with no limit on the number -of text chunks, and a 2^31 byte limit on their size. While there are -suggested keywords, there is no requirement to restrict the use to these -strings. It is strongly suggested that keywords and text be sensible -to humans (that's the point), so don't use abbreviations. Non-printing -symbols are not allowed. See the PNG specification for more details. -There is also no requirement to have text after the keyword. - -Keywords should be limited to 79 Latin-1 characters without leading or -trailing spaces, but non-consecutive spaces are allowed within the -keyword. It is possible to have the same keyword any number of times. -The text_ptr is an array of png_text structures, each holding a -pointer to a language string, a pointer to a keyword and a pointer to -a text string. The text string, language code, and translated -keyword may be empty or NULL pointers. The keyword/text -pairs are put into the array in the order that they are received. -However, some or all of the text chunks may be after the image, so, to -make sure you have read all the text chunks, don't mess with these -until after you read the stuff after the image. This will be -mentioned again below in the discussion that goes with png_read_end(). - -Input transformations - -After you've read the header information, you can set up the library -to handle any special transformations of the image data. The various -ways to transform the data will be described in the order that they -should occur. This is important, as some of these change the color -type and/or bit depth of the data, and some others only work on -certain color types and bit depths. - -Transformations you request are ignored if they don't have any meaning for a -particular input data format. However some transformations can have an effect -as a result of a previous transformation. If you specify a contradictory set of -transformations, for example both adding and removing the alpha channel, you -cannot predict the final result. - -The color used for the transparency values should be supplied in the same -format/depth as the current image data. It is stored in the same format/depth -as the image data in a tRNS chunk, so this is what libpng expects for this data. - -The color used for the background value depends on the need_expand argument as -described below. - -Data will be decoded into the supplied row buffers packed into bytes -unless the library has been told to transform it into another format. -For example, 4 bit/pixel paletted or grayscale data will be returned -2 pixels/byte with the leftmost pixel in the high-order bits of the byte, -unless png_set_packing() is called. 8-bit RGB data will be stored -in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha() -is called to insert filler bytes, either before or after each RGB triplet. - -16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant -byte of the color value first, unless png_set_scale_16() is called to -transform it to regular RGB RGB triplets, or png_set_filler() or -png_set_add alpha() is called to insert two filler bytes, either before -or after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can -be modified with png_set_filler(), png_set_add_alpha(), png_set_strip_16(), -or png_set_scale_16(). - -The following code transforms grayscale images of less than 8 to 8 bits, -changes paletted images to RGB, and adds a full alpha channel if there is -transparency information in a tRNS chunk. This is most useful on -grayscale images with bit depths of 2 or 4 or if there is a multiple-image -viewing application that wishes to treat all images in the same way. - - if (color_type == PNG_COLOR_TYPE_PALETTE) - png_set_palette_to_rgb(png_ptr); - - if (png_get_valid(png_ptr, info_ptr, - PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr); - - if (color_type == PNG_COLOR_TYPE_GRAY && - bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr); - -The first two functions are actually aliases for png_set_expand(), added -in libpng version 1.0.4, with the function names expanded to improve code -readability. In some future version they may actually do different -things. - -As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was -added. It expands the sample depth without changing tRNS to alpha. - -As of libpng version 1.5.2, png_set_expand_16() was added. It behaves as -png_set_expand(); however, the resultant channels have 16 bits rather than 8. -Use this when the output color or gray channels are made linear to avoid fairly -severe accuracy loss. - - if (bit_depth < 16) - png_set_expand_16(png_ptr); - -PNG can have files with 16 bits per channel. If you only can handle -8 bits per channel, this will strip the pixels down to 8-bit. - - if (bit_depth == 16) -#if PNG_LIBPNG_VER >= 10504 - png_set_scale_16(png_ptr); -#else - png_set_strip_16(png_ptr); -#endif - -(The more accurate "png_set_scale_16()" API became available in libpng version -1.5.4). - -If you need to process the alpha channel on the image separately from the image -data (for example if you convert it to a bitmap mask) it is possible to have -libpng strip the channel leaving just RGB or gray data: - - if (color_type & PNG_COLOR_MASK_ALPHA) - png_set_strip_alpha(png_ptr); - -If you strip the alpha channel you need to find some other way of dealing with -the information. If, instead, you want to convert the image to an opaque -version with no alpha channel use png_set_background; see below. - -As of libpng version 1.5.2, almost all useful expansions are supported, the -major ommissions are conversion of grayscale to indexed images (which can be -done trivially in the application) and conversion of indexed to grayscale (which -can be done by a trivial manipulation of the palette.) - -In the following table, the 01 means grayscale with depth<8, 31 means -indexed with depth<8, other numerals represent the color type, "T" means -the tRNS chunk is present, A means an alpha channel is present, and O -means tRNS or alpha is present but all pixels in the image are opaque. - - FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O - TO - 01 - [G] - - - - - - - - - - - - - - 31 [Q] Q [Q] [Q] [Q] Q Q Q Q Q Q [Q] [Q] Q Q - 0 1 G + . . G G G G G G B B GB GB - 0T lt Gt t + . Gt G G Gt G G Bt Bt GBt GBt - 0O lt Gt t . + Gt Gt G Gt Gt G Bt Bt GBt GBt - 2 C P C C C + . . C - - CB CB B B - 2T Ct - Ct C C t + t - - - CBt CBt Bt Bt - 2O Ct - Ct C C t t + - - - CBt CBt Bt Bt - 3 [Q] p [Q] [Q] [Q] Q Q Q + . . [Q] [Q] Q Q - 3T [Qt] p [Qt][Q] [Q] Qt Qt Qt t + t [Qt][Qt] Qt Qt - 3O [Qt] p [Qt][Q] [Q] Qt Qt Qt t t + [Qt][Qt] Qt Qt - 4A lA G A T T GA GT GT GA GT GT + BA G GBA - 4O lA GBA A T T GA GT GT GA GT GT BA + GBA G - 6A CA PA CA C C A T tT PA P P C CBA + BA - 6O CA PBA CA C C A tT T PA P P CBA C BA + - -Within the matrix, - "+" identifies entries where 'from' and 'to' are the same. - "-" means the transformation is not supported. - "." means nothing is necessary (a tRNS chunk can just be ignored). - "t" means the transformation is obtained by png_set_tRNS. - "A" means the transformation is obtained by png_set_add_alpha(). - "X" means the transformation is obtained by png_set_expand(). - "1" means the transformation is obtained by - png_set_expand_gray_1_2_4_to_8() (and by png_set_expand() - if there is no transparency in the original or the final - format). - "C" means the transformation is obtained by png_set_gray_to_rgb(). - "G" means the transformation is obtained by png_set_rgb_to_gray(). - "P" means the transformation is obtained by - png_set_expand_palette_to_rgb(). - "p" means the transformation is obtained by png_set_packing(). - "Q" means the transformation is obtained by png_set_quantize(). - "T" means the transformation is obtained by - png_set_tRNS_to_alpha(). - "B" means the transformation is obtained by - png_set_background(), or png_strip_alpha(). - -When an entry has multiple transforms listed all are required to cause the -right overall transformation. When two transforms are separated by a comma -either will do the job. When transforms are enclosed in [] the transform should -do the job but this is currently unimplemented - a different format will result -if the suggested transformations are used. - -In PNG files, the alpha channel in an image -is the level of opacity. If you need the alpha channel in an image to -be the level of transparency instead of opacity, you can invert the -alpha channel (or the tRNS chunk data) after it's read, so that 0 is -fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit -images) is fully transparent, with - - png_set_invert_alpha(png_ptr); - -PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as -they can, resulting in, for example, 8 pixels per byte for 1 bit -files. This code expands to 1 pixel per byte without changing the -values of the pixels: - - if (bit_depth < 8) - png_set_packing(png_ptr); - -PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels -stored in a PNG image have been "scaled" or "shifted" up to the next -higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] -to 8 bits/sample in the range [0, 255]). However, it is also possible -to convert the PNG pixel data back to the original bit depth of the -image. This call reduces the pixels back down to the original bit depth: - - png_color_8p sig_bit; - - if (png_get_sBIT(png_ptr, info_ptr, &sig_bit)) - png_set_shift(png_ptr, sig_bit); - -PNG files store 3-color pixels in red, green, blue order. This code -changes the storage of the pixels to blue, green, red: - - if (color_type == PNG_COLOR_TYPE_RGB || - color_type == PNG_COLOR_TYPE_RGB_ALPHA) - png_set_bgr(png_ptr); - -PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them -into 4 or 8 bytes for windowing systems that need them in this format: - - if (color_type == PNG_COLOR_TYPE_RGB) - png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE); - -where "filler" is the 8-bit or 16-bit number to fill with, and the location -is either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether -you want the filler before the RGB or after. When filling an 8-bit pixel, -the least significant 8 bits of the number are used, if a 16-bit number is -supplied. This transformation does not affect images that already have full -alpha channels. To add an opaque alpha channel, use filler=0xffff and -PNG_FILLER_AFTER which will generate RGBA pixels. - -Note that png_set_filler() does not change the color type. If you want -to do that, you can add a true alpha channel with - - if (color_type == PNG_COLOR_TYPE_RGB || - color_type == PNG_COLOR_TYPE_GRAY) - png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER); - -where "filler" contains the alpha value to assign to each pixel. -The png_set_add_alpha() function was added in libpng-1.2.7. - -If you are reading an image with an alpha channel, and you need the -data as ARGB instead of the normal PNG format RGBA: - - if (color_type == PNG_COLOR_TYPE_RGB_ALPHA) - png_set_swap_alpha(png_ptr); - -For some uses, you may want a grayscale image to be represented as -RGB. This code will do that conversion: - - if (color_type == PNG_COLOR_TYPE_GRAY || - color_type == PNG_COLOR_TYPE_GRAY_ALPHA) - png_set_gray_to_rgb(png_ptr); - -Conversely, you can convert an RGB or RGBA image to grayscale or grayscale -with alpha. - - if (color_type == PNG_COLOR_TYPE_RGB || - color_type == PNG_COLOR_TYPE_RGB_ALPHA) - png_set_rgb_to_gray(png_ptr, error_action, - double red_weight, double green_weight); - - error_action = 1: silently do the conversion - - error_action = 2: issue a warning if the original - image has any pixel where - red != green or red != blue - - error_action = 3: issue an error and abort the - conversion if the original - image has any pixel where - red != green or red != blue - - red_weight: weight of red component - - green_weight: weight of green component - If either weight is negative, default - weights are used. - -In the corresponding fixed point API the red_weight and green_weight values are -simply scaled by 100,000: - - png_set_rgb_to_gray(png_ptr, error_action, - png_fixed_point red_weight, - png_fixed_point green_weight); - -If you have set error_action = 1 or 2, you can -later check whether the image really was gray, after processing -the image rows, with the png_get_rgb_to_gray_status(png_ptr) function. -It will return a png_byte that is zero if the image was gray or -1 if there were any non-gray pixels. Background and sBIT data -will be silently converted to grayscale, using the green channel -data for sBIT, regardless of the error_action setting. - -The default values come from the PNG file cHRM chunk if present; otherwise, the -defaults correspond to the ITU-R recommendation 709, and also the sRGB color -space, as recommended in the Charles Poynton's Colour FAQ, -Copyright (c) 2006-11-28 Charles Poynton, in section 9: - -<http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html#RTFToC9> - - Y = 0.2126 * R + 0.7152 * G + 0.0722 * B - -Previous versions of this document, 1998 through 2002, recommended a slightly -different formula: - - Y = 0.212671 * R + 0.715160 * G + 0.072169 * B - -Libpng uses an integer approximation: - - Y = (6968 * R + 23434 * G + 2366 * B)/32768 - -The calculation is done in a linear colorspace, if the image gamma -can be determined. - -The png_set_background() function has been described already; it tells libpng to -composite images with alpha or simple transparency against the supplied -background color. For compatibility with versions of libpng earlier than -libpng-1.5.4 it is recommended that you call the function after reading the file -header, even if you don't want to use the color in a bKGD chunk, if one exists. - -If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), -you may use this color, or supply another color more suitable for -the current display (e.g., the background color from a web page). You -need to tell libpng how the color is represented, both the format of the -component values in the color (the number of bits) and the gamma encoding of the -color. The function takes two arguments, background_gamma_mode and need_expand -to convey this information; however, only two combinations are likely to be -useful: - - png_color_16 my_background; - png_color_16p image_background; - - if (png_get_bKGD(png_ptr, info_ptr, &image_background)) - png_set_background(png_ptr, image_background, - PNG_BACKGROUND_GAMMA_FILE, 1/*needs to be expanded*/, 1); - else - png_set_background(png_ptr, &my_background, - PNG_BACKGROUND_GAMMA_SCREEN, 0/*do not expand*/, 1); - -The second call was described above - my_background is in the format of the -final, display, output produced by libpng. Because you now know the format of -the PNG it is possible to avoid the need to choose either 8-bit or 16-bit -output and to retain palette images (the palette colors will be modified -appropriately and the tRNS chunk removed.) However, if you are doing this, -take great care not to ask for transformations without checking first that -they apply! - -In the first call the background color has the original bit depth and color type -of the PNG file. So, for palette images the color is supplied as a palette -index and for low bit greyscale images the color is a reduced bit value in -image_background->gray. - -If you didn't call png_set_gamma() before reading the file header, for example -if you need your code to remain compatible with older versions of libpng prior -to libpng-1.5.4, this is the place to call it. - -Do not call it if you called png_set_alpha_mode(); doing so will damage the -settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is -supported then you can certainly do png_set_gamma() before reading the PNG -header.) - -This API unconditionally sets the screen and file gamma values, so it will -override the value in the PNG file unless it is called before the PNG file -reading starts. For this reason you must always call it with the PNG file -value when you call it in this position: - - if (png_get_gAMA(png_ptr, info_ptr, &file_gamma)) - png_set_gamma(png_ptr, screen_gamma, file_gamma); - - else - png_set_gamma(png_ptr, screen_gamma, 0.45455); - -If you need to reduce an RGB file to a paletted file, or if a paletted -file has more entries than will fit on your screen, png_set_quantize() -will do that. Note that this is a simple match quantization that merely -finds the closest color available. This should work fairly well with -optimized palettes, but fairly badly with linear color cubes. If you -pass a palette that is larger than maximum_colors, the file will -reduce the number of colors in the palette so it will fit into -maximum_colors. If there is a histogram, libpng will use it to make -more intelligent choices when reducing the palette. If there is no -histogram, it may not do as good a job. - - if (color_type & PNG_COLOR_MASK_COLOR) - { - if (png_get_valid(png_ptr, info_ptr, - PNG_INFO_PLTE)) - { - png_uint_16p histogram = NULL; - - png_get_hIST(png_ptr, info_ptr, - &histogram); - png_set_quantize(png_ptr, palette, num_palette, - max_screen_colors, histogram, 1); - } - - else - { - png_color std_color_cube[MAX_SCREEN_COLORS] = - { ... colors ... }; - - png_set_quantize(png_ptr, std_color_cube, - MAX_SCREEN_COLORS, MAX_SCREEN_COLORS, - NULL,0); - } - } - -PNG files describe monochrome as black being zero and white being one. -The following code will reverse this (make black be one and white be -zero): - - if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY) - png_set_invert_mono(png_ptr); - -This function can also be used to invert grayscale and gray-alpha images: - - if (color_type == PNG_COLOR_TYPE_GRAY || - color_type == PNG_COLOR_TYPE_GRAY_ALPHA) - png_set_invert_mono(png_ptr); - -PNG files store 16-bit pixels in network byte order (big-endian, -ie. most significant bits first). This code changes the storage to the -other way (little-endian, i.e. least significant bits first, the -way PCs store them): - - if (bit_depth == 16) - png_set_swap(png_ptr); - -If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you -need to change the order the pixels are packed into bytes, you can use: - - if (bit_depth < 8) - png_set_packswap(png_ptr); - -Finally, you can write your own transformation function if none of -the existing ones meets your needs. This is done by setting a callback -with - - png_set_read_user_transform_fn(png_ptr, - read_transform_fn); - -You must supply the function - - void read_transform_fn(png_structp png_ptr, png_row_infop - row_info, png_bytep data) - -See pngtest.c for a working example. Your function will be called -after all of the other transformations have been processed. Take care with -interlaced images if you do the interlace yourself - the width of the row is the -width in 'row_info', not the overall image width. - -If supported, libpng provides two information routines that you can use to find -where you are in processing the image: - - png_get_current_pass_number(png_structp png_ptr); - png_get_current_row_number(png_structp png_ptr); - -Don't try using these outside a transform callback - firstly they are only -supported if user transforms are supported, secondly they may well return -unexpected results unless the row is actually being processed at the moment they -are called. - -With interlaced -images the value returned is the row in the input sub-image image. Use -PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to -find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass). - -The discussion of interlace handling above contains more information on how to -use these values. - -You can also set up a pointer to a user structure for use by your -callback function, and you can inform libpng that your transform -function will change the number of channels or bit depth with the -function - - png_set_user_transform_info(png_ptr, user_ptr, - user_depth, user_channels); - -The user's application, not libpng, is responsible for allocating and -freeing any memory required for the user structure. - -You can retrieve the pointer via the function -png_get_user_transform_ptr(). For example: - - voidp read_user_transform_ptr = - png_get_user_transform_ptr(png_ptr); - -The last thing to handle is interlacing; this is covered in detail below, -but you must call the function here if you want libpng to handle expansion -of the interlaced image. - - number_of_passes = png_set_interlace_handling(png_ptr); - -After setting the transformations, libpng can update your png_info -structure to reflect any transformations you've requested with this -call. - - png_read_update_info(png_ptr, info_ptr); - -This is most useful to update the info structure's rowbytes -field so you can use it to allocate your image memory. This function -will also update your palette with the correct screen_gamma and -background if these have been given with the calls above. You may -only call png_read_update_info() once with a particular info_ptr. - -After you call png_read_update_info(), you can allocate any -memory you need to hold the image. The row data is simply -raw byte data for all forms of images. As the actual allocation -varies among applications, no example will be given. If you -are allocating one large chunk, you will need to build an -array of pointers to each row, as it will be needed for some -of the functions below. - -Be sure that your platform can allocate the buffer that you'll need. -libpng internally checks for oversize width, but you'll need to -do your own check for number_of_rows*width*pixel_size if you are using -a multiple-row buffer: - - /* Guard against integer overflow */ - if (number_of_rows > PNG_SIZE_MAX/(width*pixel_size)) { - png_error(png_ptr,"image_data buffer would be too large"); - } - -Remember: Before you call png_read_update_info(), the png_get_*() -functions return the values corresponding to the original PNG image. -After you call png_read_update_info the values refer to the image -that libpng will output. Consequently you must call all the png_set_ -functions before you call png_read_update_info(). This is particularly -important for png_set_interlace_handling() - if you are going to call -png_read_update_info() you must call png_set_interlace_handling() before -it unless you want to receive interlaced output. - -Reading image data - -After you've allocated memory, you can read the image data. -The simplest way to do this is in one function call. If you are -allocating enough memory to hold the whole image, you can just -call png_read_image() and libpng will read in all the image data -and put it in the memory area supplied. You will need to pass in -an array of pointers to each row. - -This function automatically handles interlacing, so you don't -need to call png_set_interlace_handling() (unless you call -png_read_update_info()) or call this function multiple times, or any -of that other stuff necessary with png_read_rows(). - - png_read_image(png_ptr, row_pointers); - -where row_pointers is: - - png_bytep row_pointers[height]; - -You can point to void or char or whatever you use for pixels. - -If you don't want to read in the whole image at once, you can -use png_read_rows() instead. If there is no interlacing (check -interlace_type == PNG_INTERLACE_NONE), this is simple: - - png_read_rows(png_ptr, row_pointers, NULL, - number_of_rows); - -where row_pointers is the same as in the png_read_image() call. - -If you are doing this just one row at a time, you can do this with -a single row_pointer instead of an array of row_pointers: - - png_bytep row_pointer = row; - png_read_row(png_ptr, row_pointer, NULL); - -If the file is interlaced (interlace_type != 0 in the IHDR chunk), things -get somewhat harder. The only current (PNG Specification version 1.2) -interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7); -a somewhat complicated 2D interlace scheme, known as Adam7, that -breaks down an image into seven smaller images of varying size, based -on an 8x8 grid. This number is defined (from libpng 1.5) as -PNG_INTERLACE_ADAM7_PASSES in png.h - -libpng can fill out those images or it can give them to you "as is". -It is almost always better to have libpng handle the interlacing for you. -If you want the images filled out, there are two ways to do that. The one -mentioned in the PNG specification is to expand each pixel to cover -those pixels that have not been read yet (the "rectangle" method). -This results in a blocky image for the first pass, which gradually -smooths out as more pixels are read. The other method is the "sparkle" -method, where pixels are drawn only in their final locations, with the -rest of the image remaining whatever colors they were initialized to -before the start of the read. The first method usually looks better, -but tends to be slower, as there are more pixels to put in the rows. - -If, as is likely, you want libpng to expand the images, call this before -calling png_start_read_image() or png_read_update_info(): - - if (interlace_type == PNG_INTERLACE_ADAM7) - number_of_passes - = png_set_interlace_handling(png_ptr); - -This will return the number of passes needed. Currently, this is seven, -but may change if another interlace type is added. This function can be -called even if the file is not interlaced, where it will return one pass. -You then need to read the whole image 'number_of_passes' times. Each time -will distribute the pixels from the current pass to the correct place in -the output image, so you need to supply the same rows to png_read_rows in -each pass. - -If you are not going to display the image after each pass, but are -going to wait until the entire image is read in, use the sparkle -effect. This effect is faster and the end result of either method -is exactly the same. If you are planning on displaying the image -after each pass, the "rectangle" effect is generally considered the -better looking one. - -If you only want the "sparkle" effect, just call png_read_row() or -png_read_rows() as -normal, with the third parameter NULL. Make sure you make pass over -the image number_of_passes times, and you don't change the data in the -rows between calls. You can change the locations of the data, just -not the data. Each pass only writes the pixels appropriate for that -pass, and assumes the data from previous passes is still valid. - - png_read_rows(png_ptr, row_pointers, NULL, - number_of_rows); - or - png_read_row(png_ptr, row_pointers, NULL); - -If you only want the first effect (the rectangles), do the same as -before except pass the row buffer in the third parameter, and leave -the second parameter NULL. - - png_read_rows(png_ptr, NULL, row_pointers, - number_of_rows); - or - png_read_row(png_ptr, NULL, row_pointers); - -If you don't want libpng to handle the interlacing details, just call -png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images. -Each of the images is a valid image by itself; however, you will almost -certainly need to distribute the pixels from each sub-image to the -correct place. This is where everything gets very tricky. - -If you want to retrieve the separate images you must pass the correct -number of rows to each successive call of png_read_rows(). The calculation -gets pretty complicated for small images, where some sub-images may -not even exist because either their width or height ends up zero. -libpng provides two macros to help you in 1.5 and later versions: - - png_uint_32 width = PNG_PASS_COLS(image_width, pass_number); - png_uint_32 height = PNG_PASS_ROWS(image_height, pass_number); - -Respectively these tell you the width and height of the sub-image -corresponding to the numbered pass. 'pass' is in in the range 0 to 6 - -this can be confusing because the specification refers to the same passes -as 1 to 7! Be careful, you must check both the width and height before -calling png_read_rows() and not call it for that pass if either is zero. - -You can, of course, read each sub-image row by row. If you want to -produce optimal code to make a pixel-by-pixel transformation of an -interlaced image this is the best approach; read each row of each pass, -transform it, and write it out to a new interlaced image. - -If you want to de-interlace the image yourself libpng provides further -macros to help that tell you where to place the pixels in the output image. -Because the interlacing scheme is rectangular - sub-image pixels are always -arranged on a rectangular grid - all you need to know for each pass is the -starting column and row in the output image of the first pixel plus the -spacing between each pixel. As of libpng 1.5 there are four macros to -retrieve this information: - - png_uint_32 x = PNG_PASS_START_COL(pass); - png_uint_32 y = PNG_PASS_START_ROW(pass); - png_uint_32 xStep = 1U << PNG_PASS_COL_SHIFT(pass); - png_uint_32 yStep = 1U << PNG_PASS_ROW_SHIFT(pass); - -These allow you to write the obvious loop: - - png_uint_32 input_y = 0; - png_uint_32 output_y = PNG_PASS_START_ROW(pass); - - while (output_y < output_image_height) - { - png_uint_32 input_x = 0; - png_uint_32 output_x = PNG_PASS_START_COL(pass); - - while (output_x < output_image_width) - { - image[output_y][output_x] = - subimage[pass][input_y][input_x++]; - - output_x += xStep; - } - - ++input_y; - output_y += yStep; - } - -Notice that the steps between successive output rows and columns are -returned as shifts. This is possible because the pixels in the subimages -are always a power of 2 apart - 1, 2, 4 or 8 pixels - in the original -image. In practice you may need to directly calculate the output coordinate -given an input coordinate. libpng provides two further macros for this -purpose: - - png_uint_32 output_x = PNG_COL_FROM_PASS_COL(input_x, pass); - png_uint_32 output_y = PNG_ROW_FROM_PASS_ROW(input_y, pass); - -Finally a pair of macros are provided to tell you if a particular image -row or column appears in a given pass: - - int col_in_pass = PNG_COL_IN_INTERLACE_PASS(output_x, pass); - int row_in_pass = PNG_ROW_IN_INTERLACE_PASS(output_y, pass); - -Bear in mind that you will probably also need to check the width and height -of the pass in addition to the above to be sure the pass even exists! - -With any luck you are convinced by now that you don't want to do your own -interlace handling. In reality normally the only good reason for doing this -is if you are processing PNG files on a pixel-by-pixel basis and don't want -to load the whole file into memory when it is interlaced. - -libpng includes a test program, pngvalid, that illustrates reading and -writing of interlaced images. If you can't get interlacing to work in your -code and don't want to leave it to libpng (the recommended approach), see -how pngvalid.c does it. - -Finishing a sequential read - -After you are finished reading the image through the -low-level interface, you can finish reading the file. - -If you want to use a different crc action for handling CRC errors in -chunks after the image data, you can call png_set_crc_action() -again at this point. - -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. - - 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. -If you do this, libpng will not process any chunks after IDAT other than -skipping over them and perhaps (depending on whether you have called -png_set_crc_action) checking their CRCs while looking for the IEND chunk. - - 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 -the PNG datastream. - -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: - - png_free_data(png_ptr, info_ptr, mask, seq) - - mask - identifies data to be freed, a mask - containing the bitwise OR of one or - more of - PNG_FREE_PLTE, PNG_FREE_TRNS, - PNG_FREE_HIST, PNG_FREE_ICCP, - PNG_FREE_PCAL, PNG_FREE_ROWS, - PNG_FREE_SCAL, PNG_FREE_SPLT, - PNG_FREE_TEXT, PNG_FREE_UNKN, - or simply PNG_FREE_ALL - - seq - sequence number of item to be freed - (-1 for all items) - -This function may be safely called when the relevant storage has -already been freed, or has not yet been allocated, or was allocated -by the user and not by libpng, and will in those cases do nothing. -The "seq" parameter is ignored if only one item of the selected data -type, such as PLTE, is allowed. If "seq" is not -1, and multiple items -are allowed for the data type identified in the mask, such as text or -sPLT, only the n'th item in the structure is freed, where n is "seq". - -The default behavior is only to free data that was allocated internally -by libpng. This can be changed, so that libpng will not free the data, -or so that it will free data that was allocated by the user with png_malloc() -or png_calloc() and passed in via a png_set_*() function, with - - png_data_freer(png_ptr, info_ptr, freer, mask) - - freer - one of - PNG_DESTROY_WILL_FREE_DATA - PNG_SET_WILL_FREE_DATA - PNG_USER_WILL_FREE_DATA - - mask - which data elements are affected - same choices as in png_free_data() - -This function only affects data that has already been allocated. -You can call this function after reading the PNG data but before calling -any png_set_*() functions, to control whether the user or the png_set_*() -function is responsible for freeing any existing data that might be present, -and again after the png_set_*() functions to control whether the user -or png_destroy_*() is supposed to free the data. When the user assumes -responsibility for libpng-allocated data, the application must use -png_free() to free it, and when the user transfers responsibility to libpng -for data that the user has allocated, the user must have used png_malloc() -or png_calloc() to allocate it. - -If you allocated your row_pointers in a single block, as suggested above in -the description of the high level read interface, you must not transfer -responsibility for freeing it to the png_set_rows or png_read_destroy function, -because they would also try to free the individual row_pointers[i]. - -If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword -separately, do not transfer responsibility for freeing text_ptr to libpng, -because when libpng fills a png_text structure it combines these members with -the key member, and png_free_data() will free only text_ptr.key. Similarly, -if you transfer responsibility for free'ing text_ptr from libpng to your -application, your application must not separately free those members. - -The png_free_data() function will turn off the "valid" flag for anything -it frees. If you need to turn the flag off for a chunk that was freed by -your application instead of by libpng, you can use - - png_set_invalid(png_ptr, info_ptr, mask); - - mask - identifies the chunks to be made invalid, - containing the bitwise OR of one or - more of - PNG_INFO_gAMA, PNG_INFO_sBIT, - PNG_INFO_cHRM, PNG_INFO_PLTE, - PNG_INFO_tRNS, PNG_INFO_bKGD, - PNG_INFO_eXIf, - PNG_INFO_hIST, PNG_INFO_pHYs, - PNG_INFO_oFFs, PNG_INFO_tIME, - PNG_INFO_pCAL, PNG_INFO_sRGB, - PNG_INFO_iCCP, PNG_INFO_sPLT, - PNG_INFO_sCAL, PNG_INFO_IDAT - -For a more compact example of reading a PNG image, see the file example.c. - -Reading PNG files progressively - -The progressive reader is slightly different from the non-progressive -reader. Instead of calling png_read_info(), png_read_rows(), and -png_read_end(), you make one call to png_process_data(), which calls -callbacks when it has the info, a row, or the end of the image. You -set up these callbacks with png_set_progressive_read_fn(). You don't -have to worry about the input/output functions of libpng, as you are -giving the library the data directly in png_process_data(). I will -assume that you have read the section on reading PNG files above, -so I will only highlight the differences (although I will show -all of the code). - -png_structp png_ptr; -png_infop info_ptr; - - /* An example code fragment of how you would - initialize the progressive reader in your - application. */ - int - initialize_png_reader() - { - png_ptr = png_create_read_struct - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn); - - if (!png_ptr) - return (ERROR); - - info_ptr = png_create_info_struct(png_ptr); - - if (!info_ptr) - { - png_destroy_read_struct(&png_ptr, - (png_infopp)NULL, (png_infopp)NULL); - return (ERROR); - } - - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - return (ERROR); - } - - /* This one's new. You can provide functions - to be called when the header info is valid, - when each row is completed, and when the image - is finished. If you aren't using all functions, - you can specify NULL parameters. Even when all - three functions are NULL, you need to call - png_set_progressive_read_fn(). You can use - any struct as the user_ptr (cast to a void pointer - for the function call), and retrieve the pointer - from inside the callbacks using the function - - png_get_progressive_ptr(png_ptr); - - which will return a void pointer, which you have - to cast appropriately. - */ - png_set_progressive_read_fn(png_ptr, (void *)user_ptr, - info_callback, row_callback, end_callback); - - return 0; - } - - /* A code fragment that you call as you receive blocks - of data */ - int - process_data(png_bytep buffer, png_uint_32 length) - { - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - return (ERROR); - } - - /* This one's new also. Simply give it a chunk - of data from the file stream (in order, of - course). On machines with segmented memory - models machines, don't give it any more than - 64K. The library seems to run fine with sizes - of 4K. Although you can give it much less if - necessary (I assume you can give it chunks of - 1 byte, I haven't tried less than 256 bytes - yet). When this function returns, you may - want to display any rows that were generated - in the row callback if you don't already do - so there. - */ - png_process_data(png_ptr, info_ptr, buffer, length); - - /* At this point you can call png_process_data_skip if - you want to handle data the library will skip yourself; - it simply returns the number of bytes to skip (and stops - libpng skipping that number of bytes on the next - png_process_data call). - return 0; - } - - /* This function is called (as set by - png_set_progressive_read_fn() above) when enough data - has been supplied so all of the header has been - read. - */ - void - info_callback(png_structp png_ptr, png_infop info) - { - /* Do any setup here, including setting any of - the transformations mentioned in the Reading - PNG files section. For now, you _must_ call - either png_start_read_image() or - png_read_update_info() after all the - transformations are set (even if you don't set - any). You may start getting rows before - png_process_data() returns, so this is your - last chance to prepare for that. - - This is where you turn on interlace handling, - assuming you don't want to do it yourself. - - If you need to you can stop the processing of - your original input data at this point by calling - png_process_data_pause. This returns the number - of unprocessed bytes from the last png_process_data - call - it is up to you to ensure that the next call - sees these bytes again. If you don't want to bother - with this you can get libpng to cache the unread - bytes by setting the 'save' parameter (see png.h) but - then libpng will have to copy the data internally. - */ - } - - /* This function is called when each row of image - data is complete */ - void - row_callback(png_structp png_ptr, png_bytep new_row, - png_uint_32 row_num, int pass) - { - /* If the image is interlaced, and you turned - on the interlace handler, this function will - be called for every row in every pass. Some - of these rows will not be changed from the - previous pass. When the row is not changed, - the new_row variable will be NULL. The rows - and passes are called in order, so you don't - really need the row_num and pass, but I'm - supplying them because it may make your life - easier. - - If you did not turn on interlace handling then - the callback is called for each row of each - sub-image when the image is interlaced. In this - case 'row_num' is the row in the sub-image, not - the row in the output image as it is in all other - cases. - - For the non-NULL rows of interlaced images when - you have switched on libpng interlace handling, - you must call png_progressive_combine_row() - passing in the row and the old row. You can - call this function for NULL rows (it will just - return) and for non-interlaced images (it just - does the memcpy for you) if it will make the - code easier. Thus, you can just do this for - all cases if you switch on interlace handling; - */ - - png_progressive_combine_row(png_ptr, old_row, - new_row); - - /* where old_row is what was displayed - previously for the row. Note that the first - pass (pass == 0, really) will completely cover - the old row, so the rows do not have to be - initialized. After the first pass (and only - for interlaced images), you will have to pass - the current row, and the function will combine - the old row and the new row. - - You can also call png_process_data_pause in this - callback - see above. - */ - } - - void - end_callback(png_structp png_ptr, png_infop info) - { - /* This function is called after the whole image - has been read, including any chunks after the - image (up to and including the IEND). You - will usually have the same info chunk as you - had in the header, although some data may have - been added to the comments and time fields. - - Most people won't do much here, perhaps setting - a flag that marks the image as finished. - */ - } - - - -IV. Writing - -Much of this is very similar to reading. However, everything of -importance is repeated here, so you won't have to constantly look -back up in the reading section to understand writing. - -Setup - -You will want to do the I/O initialization before you get into libpng, -so if it doesn't work, you don't have anything to undo. If you are not -using the standard I/O functions, you will need to replace them with -custom writing functions. See the discussion under Customizing libpng. - - FILE *fp = fopen(file_name, "wb"); - - if (!fp) - return (ERROR); - -Next, png_struct and png_info need to be allocated and initialized. -As these can be both relatively large, you may not want to store these -on the stack, unless you have stack space to spare. Of course, you -will want to check if they return NULL. If you are also reading, -you won't want to name your read structure and your write structure -both "png_ptr"; you can call them anything you like, such as -"read_ptr" and "write_ptr". Look at pngtest.c, for example. - - png_structp png_ptr = png_create_write_struct - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn); - - if (!png_ptr) - return (ERROR); - - png_infop info_ptr = png_create_info_struct(png_ptr); - if (!info_ptr) - { - png_destroy_write_struct(&png_ptr, - (png_infopp)NULL); - return (ERROR); - } - -If you want to use your own memory allocation routines, -define PNG_USER_MEM_SUPPORTED and use -png_create_write_struct_2() instead of png_create_write_struct(): - - png_structp png_ptr = png_create_write_struct_2 - (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); - -After you have these structures, you will need to set up the -error handling. When libpng encounters an error, it expects to -longjmp() back to your routine. Therefore, you will need to call -setjmp() and pass the png_jmpbuf(png_ptr). If you -write the file from different routines, you will need to update -the png_jmpbuf(png_ptr) every time you enter a new routine that will -call a png_*() function. See your documentation of setjmp/longjmp -for your compiler for more information on setjmp/longjmp. See -the discussion on libpng error handling in the Customizing Libpng -section below for more information on the libpng error handling. - - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_write_struct(&png_ptr, &info_ptr); - fclose(fp); - return (ERROR); - } - ... - return; - -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(). - -You can #define PNG_ABORT() to a function that does something -more useful than abort(), as long as your function does not -return. - -Checking for invalid palette index on write was added at libpng -1.5.10. If a pixel contains an invalid (out-of-range) index libpng issues -a benign error. This is enabled by default because this condition is an -error according to the PNG specification, Clause 11.3.2, but the error can -be ignored in each png_ptr with - - png_set_check_for_invalid_index(png_ptr, 0); - -If the error is ignored, or if png_benign_error() treats it as a warning, -any invalid pixels are written as-is by the encoder, resulting in an -invalid PNG datastream as output. In this case the application is -responsible for ensuring that the pixel indexes are in range when it writes -a PLTE chunk with fewer entries than the bit depth would allow. - -Now you need to set up the output code. The default for libpng is to -use the C function fwrite(). If you use this, you will need to pass a -valid FILE * in the function png_init_io(). Be sure that the file is -opened in binary mode. Again, if you wish to handle writing data in -another way, see the discussion on libpng I/O handling in the Customizing -Libpng section below. - - png_init_io(png_ptr, fp); - -If you are embedding your PNG into a datastream such as MNG, and don't -want libpng to write the 8-byte signature, or if you have already -written the signature in your application, use - - png_set_sig_bytes(png_ptr, 8); - -to inform libpng that it should not write a signature. - -Write callbacks - -At this point, you can set up a callback function that will be -called after each row has been written, which you can use to control -a progress meter or the like. It's demonstrated in pngtest.c. -You must supply a function - - void write_row_callback(png_structp png_ptr, png_uint_32 row, - int pass); - { - /* put your code here */ - } - -(You can give it another name that you like instead of "write_row_callback") - -To inform libpng about your function, use - - png_set_write_status_fn(png_ptr, write_row_callback); - -When this function is called the row has already been completely processed and -it has also been written out. The 'row' and 'pass' refer to the next row to be -handled. For the -non-interlaced case the row that was just handled is simply one less than the -passed in row number, and pass will always be 0. For the interlaced case the -same applies unless the row value is 0, in which case the row just handled was -the last one from one of the preceding passes. Because interlacing may skip a -pass you cannot be sure that the preceding pass is just 'pass-1', if you really -need to know what the last pass is record (row,pass) from the callback and use -the last recorded value each time. - -As with the user transform you can find the output row using the -PNG_ROW_FROM_PASS_ROW macro. - -You now have the option of modifying how the compression library will -run. The following functions are mainly for testing, but may be useful -in some cases, like if you need to write PNG files extremely fast and -are willing to give up some compression, or if you want to get the -maximum possible compression at the expense of slower writing. If you -have no special needs in this area, let the library do what it wants by -not calling this function at all, as it has been tuned to deliver a good -speed/compression ratio. The second parameter to png_set_filter() is -the filter method, for which the only valid values are 0 (as of the -July 1999 PNG specification, version 1.2) or 64 (if you are writing -a PNG datastream that is to be embedded in a MNG datastream). The third -parameter is a flag that indicates which filter type(s) are to be tested -for each scanline. See the PNG specification for details on the specific -filter types. - - - /* turn on or off filtering, and/or choose - specific filters. You can use either a single - PNG_FILTER_VALUE_NAME or the bitwise OR of one - or more PNG_FILTER_NAME masks. - */ - png_set_filter(png_ptr, 0, - PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE | - PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB | - PNG_FILTER_UP | PNG_FILTER_VALUE_UP | - PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG | - PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH| - PNG_ALL_FILTERS | PNG_FAST_FILTERS); - -If an application wants to start and stop using particular filters during -compression, it should start out with all of the filters (to ensure that -the previous row of pixels will be stored in case it's needed later), -and then add and remove them after the start of compression. - -If you are writing a PNG datastream that is to be embedded in a MNG -datastream, the second parameter can be either 0 or 64. - -The png_set_compression_*() functions interface to the zlib compression -library, and should mostly be ignored unless you really know what you are -doing. The only generally useful call is png_set_compression_level() -which changes how much time zlib spends on trying to compress the image -data. See the Compression Library (zlib.h and algorithm.txt, distributed -with zlib) for details on the compression levels. - - #include zlib.h - - /* Set the zlib compression level */ - png_set_compression_level(png_ptr, - Z_BEST_COMPRESSION); - - /* Set other zlib parameters for compressing IDAT */ - png_set_compression_mem_level(png_ptr, 8); - png_set_compression_strategy(png_ptr, - Z_DEFAULT_STRATEGY); - png_set_compression_window_bits(png_ptr, 15); - png_set_compression_method(png_ptr, 8); - png_set_compression_buffer_size(png_ptr, 8192) - - /* Set zlib parameters for text compression - * If you don't call these, the parameters - * fall back on those defined for IDAT chunks - */ - png_set_text_compression_mem_level(png_ptr, 8); - png_set_text_compression_strategy(png_ptr, - Z_DEFAULT_STRATEGY); - png_set_text_compression_window_bits(png_ptr, 15); - png_set_text_compression_method(png_ptr, 8); - -Setting the contents of info for output - -You now need to fill in the png_info structure with all the data you -wish to write before the actual image. Note that the only thing you -are allowed to write after the image is the text chunks and the time -chunk (as of PNG Specification 1.2, anyway). See png_write_end() and -the latest PNG specification for more information on that. If you -wish to write them before the image, fill them in now, and flag that -data as being valid. If you want to wait until after the data, don't -fill them until png_write_end(). For all the fields in png_info and -their data types, see png.h. For explanations of what the fields -contain, see the PNG specification. - -Some of the more important parts of the png_info are: - - png_set_IHDR(png_ptr, info_ptr, width, height, - bit_depth, color_type, interlace_type, - compression_type, filter_method) - - width - holds the width of the image - in pixels (up to 2^31). - - height - holds the height of the image - in pixels (up to 2^31). - - bit_depth - holds the bit depth of one of the - image channels. - (valid values are 1, 2, 4, 8, 16 - and depend also on the - color_type. See also significant - bits (sBIT) below). - - color_type - describes which color/alpha - channels are present. - PNG_COLOR_TYPE_GRAY - (bit depths 1, 2, 4, 8, 16) - PNG_COLOR_TYPE_GRAY_ALPHA - (bit depths 8, 16) - PNG_COLOR_TYPE_PALETTE - (bit depths 1, 2, 4, 8) - PNG_COLOR_TYPE_RGB - (bit_depths 8, 16) - PNG_COLOR_TYPE_RGB_ALPHA - (bit_depths 8, 16) - - PNG_COLOR_MASK_PALETTE - PNG_COLOR_MASK_COLOR - PNG_COLOR_MASK_ALPHA - - interlace_type - PNG_INTERLACE_NONE or - PNG_INTERLACE_ADAM7 - - compression_type - (must be - PNG_COMPRESSION_TYPE_DEFAULT) - - filter_method - (must be PNG_FILTER_TYPE_DEFAULT - or, if you are writing a PNG to - be embedded in a MNG datastream, - can also be - PNG_INTRAPIXEL_DIFFERENCING) - -If you call png_set_IHDR(), the call must appear before any of the -other png_set_*() functions, because they might require access to some of -the IHDR settings. The remaining png_set_*() functions can be called -in any order. - -If you wish, you can reset the compression_type, interlace_type, or -filter_method later by calling png_set_IHDR() again; if you do this, the -width, height, bit_depth, and color_type must be the same in each call. - - png_set_PLTE(png_ptr, info_ptr, palette, - num_palette); - - palette - the palette for the file - (array of png_color) - num_palette - number of entries in the palette - - - png_set_gAMA(png_ptr, info_ptr, file_gamma); - png_set_gAMA_fixed(png_ptr, info_ptr, int_file_gamma); - - file_gamma - the gamma at which the image was - created (PNG_INFO_gAMA) - - int_file_gamma - 100,000 times the gamma at which - the image was created - - png_set_cHRM(png_ptr, info_ptr, white_x, white_y, red_x, red_y, - green_x, green_y, blue_x, blue_y) - png_set_cHRM_XYZ(png_ptr, info_ptr, red_X, red_Y, red_Z, green_X, - green_Y, green_Z, blue_X, blue_Y, blue_Z) - png_set_cHRM_fixed(png_ptr, info_ptr, int_white_x, int_white_y, - int_red_x, int_red_y, int_green_x, int_green_y, - int_blue_x, int_blue_y) - png_set_cHRM_XYZ_fixed(png_ptr, info_ptr, int_red_X, int_red_Y, - int_red_Z, int_green_X, int_green_Y, int_green_Z, - int_blue_X, int_blue_Y, int_blue_Z) - - {white,red,green,blue}_{x,y} - A color space encoding specified using the chromaticities - of the end points and the white point. - - {red,green,blue}_{X,Y,Z} - A color space encoding specified using the encoding end - points - the CIE tristimulus specification of the intended - color of the red, green and blue channels in the PNG RGB - data. The white point is simply the sum of the three end - points. - - png_set_sRGB(png_ptr, info_ptr, srgb_intent); - - srgb_intent - the rendering intent - (PNG_INFO_sRGB) The presence of - the sRGB chunk means that the pixel - data is in the sRGB color space. - This chunk also implies specific - values of gAMA and cHRM. Rendering - intent is the CSS-1 property that - has been defined by the International - Color Consortium - (http://www.color.org). - It can be one of - PNG_sRGB_INTENT_SATURATION, - PNG_sRGB_INTENT_PERCEPTUAL, - PNG_sRGB_INTENT_ABSOLUTE, or - PNG_sRGB_INTENT_RELATIVE. - - - png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr, - srgb_intent); - - srgb_intent - the rendering intent - (PNG_INFO_sRGB) The presence of the - sRGB chunk means that the pixel - data is in the sRGB color space. - This function also causes gAMA and - cHRM chunks with the specific values - that are consistent with sRGB to be - written. - - png_set_iCCP(png_ptr, info_ptr, name, compression_type, - profile, proflen); - - name - The profile name. - - compression_type - The compression type; always - PNG_COMPRESSION_TYPE_BASE for PNG 1.0. - You may give NULL to this argument to - ignore it. - - profile - International Color Consortium color - profile data. May contain NULs. - - proflen - length of profile data in bytes. - - png_set_sBIT(png_ptr, info_ptr, sig_bit); - - sig_bit - the number of significant bits for - (PNG_INFO_sBIT) each of the gray, red, - green, and blue channels, whichever are - appropriate for the given color type - (png_color_16) - - png_set_tRNS(png_ptr, info_ptr, trans_alpha, - num_trans, trans_color); - - trans_alpha - array of alpha (transparency) - entries for palette (PNG_INFO_tRNS) - - num_trans - number of transparent entries - (PNG_INFO_tRNS) - - trans_color - graylevel or color sample values - (in order red, green, blue) of the - single transparent color for - non-paletted images (PNG_INFO_tRNS) - - png_set_eXIf_1(png_ptr, info_ptr, num_exif, exif); - - exif - Exif profile (array of - png_byte) (PNG_INFO_eXIf) - - png_set_hIST(png_ptr, info_ptr, hist); - - hist - histogram of palette (array of - png_uint_16) (PNG_INFO_hIST) - - png_set_tIME(png_ptr, info_ptr, mod_time); - - mod_time - time image was last modified - (PNG_VALID_tIME) - - png_set_bKGD(png_ptr, info_ptr, background); - - background - background color (of type - png_color_16p) (PNG_VALID_bKGD) - - png_set_text(png_ptr, info_ptr, text_ptr, num_text); - - text_ptr - array of png_text holding image - comments - - text_ptr[i].compression - type of compression used - on "text" PNG_TEXT_COMPRESSION_NONE - PNG_TEXT_COMPRESSION_zTXt - PNG_ITXT_COMPRESSION_NONE - PNG_ITXT_COMPRESSION_zTXt - text_ptr[i].key - keyword for comment. Must contain - 1-79 characters. - text_ptr[i].text - text comments for current - keyword. Can be NULL or empty. - text_ptr[i].text_length - length of text string, - after decompression, 0 for iTXt - text_ptr[i].itxt_length - length of itxt string, - after decompression, 0 for tEXt/zTXt - text_ptr[i].lang - language of comment (NULL or - 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. 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 - - png_set_sPLT(png_ptr, info_ptr, &palette_ptr, - num_spalettes); - - palette_ptr - array of png_sPLT_struct structures - to be added to the list of palettes - in the info structure. - num_spalettes - number of palette structures to be - added. - - png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y, - unit_type); - - offset_x - positive offset from the left - edge of the screen - - offset_y - positive offset from the top - edge of the screen - - unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER - - png_set_pHYs(png_ptr, info_ptr, res_x, res_y, - unit_type); - - res_x - pixels/unit physical resolution - in x direction - - res_y - pixels/unit physical resolution - in y direction - - unit_type - PNG_RESOLUTION_UNKNOWN, - PNG_RESOLUTION_METER - - png_set_sCAL(png_ptr, info_ptr, unit, width, height) - - unit - physical scale units (an integer) - - width - width of a pixel in physical scale units - - height - height of a pixel in physical scale units - (width and height are doubles) - - png_set_sCAL_s(png_ptr, info_ptr, unit, width, height) - - unit - physical scale units (an integer) - - width - width of a pixel in physical scale units - expressed as a string - - height - height of a pixel in physical scale units - (width and height are strings like "2.54") - - png_set_unknown_chunks(png_ptr, info_ptr, &unknowns, - num_unknowns) - - unknowns - array of png_unknown_chunk - structures holding unknown chunks - unknowns[i].name - name of unknown chunk - unknowns[i].data - data of unknown chunk - unknowns[i].size - size of unknown chunk's data - unknowns[i].location - position to write chunk in file - 0: do not write chunk - PNG_HAVE_IHDR: before PLTE - PNG_HAVE_PLTE: before IDAT - PNG_AFTER_IDAT: after IDAT - -The "location" member is set automatically according to -what part of the output file has already been written. -You can change its value after calling png_set_unknown_chunks() -as demonstrated in pngtest.c. Within each of the "locations", -the chunks are sequenced according to their position in the -structure (that is, the value of "i", which is the order in which -the chunk was either read from the input file or defined with -png_set_unknown_chunks). - -A quick word about text and num_text. text is an array of png_text -structures. num_text is the number of valid structures in the array. -Each png_text structure holds a language code, a keyword, a text value, -and a compression type. - -The compression types have the same valid numbers as the compression -types of the image data. Currently, the only valid number is zero. -However, you can store text either compressed or uncompressed, unlike -images, which always have to be compressed. So if you don't want the -text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE. -Because tEXt and zTXt chunks don't have a language field, if you -specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt -any language code or translated keyword will not be written out. - -Until text gets around a few hundred bytes, it is not worth compressing it. -After the text has been written out to the file, the compression type -is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR, -so that it isn't written out again at the end (in case you are calling -png_write_end() with the same struct). - -The keywords that are given in the PNG Specification are: - - Title Short (one line) title or - caption for image - - Author Name of image's creator - - Description Description of image (possibly long) - - Copyright Copyright notice - - Creation Time Time of original image creation - (usually RFC 1123 format, see below) - - Software Software used to create the image - - Disclaimer Legal disclaimer - - Warning Warning of nature of content - - Source Device used to create the image - - Comment Miscellaneous comment; conversion - from other image format - -The keyword-text pairs work like this. Keywords should be short -simple descriptions of what the comment is about. Some typical -keywords are found in the PNG specification, as is some recommendations -on keywords. You can repeat keywords in a file. You can even write -some text before the image and some after. For example, you may want -to put a description of the image before the image, but leave the -disclaimer until after, so viewers working over modem connections -don't have to wait for the disclaimer to go over the modem before -they start seeing the image. Finally, keywords should be full -words, not abbreviations. Keywords and text are in the ISO 8859-1 -(Latin-1) character set (a superset of regular ASCII) and can not -contain NUL characters, and should not contain control or other -unprintable characters. To make the comments widely readable, stick -with basic ASCII, and avoid machine specific character set extensions -like the IBM-PC character set. The keyword must be present, but -you can leave off the text string on non-compressed pairs. -Compressed pairs must have a text string, as only the text string -is compressed anyway, so the compression would be meaningless. - -PNG supports modification time via the png_time structure. Two -conversion routines are provided, png_convert_from_time_t() for -time_t and png_convert_from_struct_tm() for struct tm. The -time_t routine uses gmtime(). You don't have to use either of -these, but if you wish to fill in the png_time structure directly, -you should provide the time in universal time (GMT) if possible -instead of your local time. Note that the year number is the full -year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and -that months start with 1. - -If you want to store the time of the original image creation, you should -use a plain tEXt chunk with the "Creation Time" keyword. This is -necessary because the "creation time" of a PNG image is somewhat vague, -depending on whether you mean the PNG file, the time the image was -created in a non-PNG format, a still photo from which the image was -scanned, or possibly the subject matter itself. In order to facilitate -machine-readable dates, it is recommended that the "Creation Time" -tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"), -although this isn't a requirement. Unlike the tIME chunk, the -"Creation Time" tEXt chunk is not expected to be automatically changed -by the software. To facilitate the use of RFC 1123 dates, a function -png_convert_to_rfc1123_buffer(buffer, png_timep) is provided to -convert from PNG time to an RFC 1123 format string. The caller must provide -a writeable buffer of at least 29 bytes. - -Writing unknown chunks - -You can use the png_set_unknown_chunks function to queue up private chunks -for writing. You give it a chunk name, location, raw data, and a size. You -also must use png_set_keep_unknown_chunks() to ensure that libpng will -handle them. That's all there is to it. The chunks will be written by the -next following png_write_info_before_PLTE, png_write_info, or png_write_end -function, depending upon the specified location. Any chunks previously -read into the info structure's unknown-chunk list will also be written out -in a sequence that satisfies the PNG specification's ordering rules. - -Here is an example of writing two private chunks, prVt and miNE: - - #ifdef PNG_WRITE_UNKNOWN_CHUNKS_SUPPORTED - /* Set unknown chunk data */ - png_unknown_chunk unk_chunk[2]; - strcpy((char *) unk_chunk[0].name, "prVt"; - unk_chunk[0].data = (unsigned char *) "PRIVATE DATA"; - unk_chunk[0].size = strlen(unk_chunk[0].data)+1; - unk_chunk[0].location = PNG_HAVE_IHDR; - strcpy((char *) unk_chunk[1].name, "miNE"; - unk_chunk[1].data = (unsigned char *) "MY CHUNK DATA"; - unk_chunk[1].size = strlen(unk_chunk[0].data)+1; - unk_chunk[1].location = PNG_AFTER_IDAT; - png_set_unknown_chunks(write_ptr, write_info_ptr, - unk_chunk, 2); - /* Needed because miNE is not safe-to-copy */ - png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS, - (png_bytep) "miNE", 1); - # if PNG_LIBPNG_VER < 10600 - /* Deal with unknown chunk location bug in 1.5.x and earlier */ - png_set_unknown_chunk_location(png, info, 0, PNG_HAVE_IHDR); - png_set_unknown_chunk_location(png, info, 1, PNG_AFTER_IDAT); - # endif - # if PNG_LIBPNG_VER < 10500 - /* PNG_AFTER_IDAT writes two copies of the chunk prior to libpng-1.5.0, - * one before IDAT and another after IDAT, so don't use it; only use - * PNG_HAVE_IHDR location. This call resets the location previously - * set by assignment and png_set_unknown_chunk_location() for chunk 1. - */ - png_set_unknown_chunk_location(png, info, 1, PNG_HAVE_IHDR); - # endif - #endif - -The high-level write interface - -At this point there are two ways to proceed; through the high-level -write interface, or through a sequence of low-level write operations. -You can use the high-level interface if your image data is present -in the info structure. All defined output -transformations are permitted, enabled by the following masks. - - PNG_TRANSFORM_IDENTITY No transformation - PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples - PNG_TRANSFORM_PACKSWAP Change order of packed - pixels to LSB first - PNG_TRANSFORM_INVERT_MONO Invert monochrome images - PNG_TRANSFORM_SHIFT Normalize pixels to the - sBIT depth - PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA - to BGRA - PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA - to AG - PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity - to transparency - PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples - PNG_TRANSFORM_STRIP_FILLER Strip out filler - bytes (deprecated). - PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading - filler bytes - PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing - filler bytes - -If you have valid image data in the info structure (you can use -png_set_rows() to put image data in the info structure), simply do this: - - png_write_png(png_ptr, info_ptr, png_transforms, NULL) - -where png_transforms is an integer containing the bitwise OR of some set of -transformation flags. This call is equivalent to png_write_info(), -followed the set of transformations indicated by the transform mask, -then png_write_image(), and finally png_write_end(). - -(The final parameter of this call is not yet used. Someday it might point -to transformation parameters required by some future output transform.) - -You must use png_transforms and not call any png_set_transform() functions -when you use png_write_png(). - -The low-level write interface - -If you are going the low-level route instead, you are now ready to -write all the file information up to the actual image data. You do -this with a call to png_write_info(). - - png_write_info(png_ptr, info_ptr); - -Note that there is one transformation you may need to do before -png_write_info(). In PNG files, the alpha channel in an image is the -level of opacity. If your data is supplied as a level of transparency, -you can invert the alpha channel before you write it, so that 0 is -fully transparent and 255 (in 8-bit or paletted images) or 65535 -(in 16-bit images) is fully opaque, with - - png_set_invert_alpha(png_ptr); - -This must appear before png_write_info() instead of later with the -other transformations because in the case of paletted images the tRNS -chunk data has to be inverted before the tRNS chunk is written. If -your image is not a paletted image, the tRNS data (which in such cases -represents a single color to be rendered as transparent) won't need to -be changed, and you can safely do this transformation after your -png_write_info() call. - -If you need to write a private chunk that you want to appear before -the PLTE chunk when PLTE is present, you can write the PNG info in -two steps, and insert code to write your own chunk between them: - - png_write_info_before_PLTE(png_ptr, info_ptr); - png_set_unknown_chunks(png_ptr, info_ptr, ...); - png_write_info(png_ptr, info_ptr); - -After you've written the file information, you can set up the library -to handle any special transformations of the image data. The various -ways to transform the data will be described in the order that they -should occur. This is important, as some of these change the color -type and/or bit depth of the data, and some others only work on -certain color types and bit depths. Even though each transformation -checks to see if it has data that it can do something with, you should -make sure to only enable a transformation if it will be valid for the -data. For example, don't swap red and blue on grayscale data. - -PNG files store RGB pixels packed into 3 or 6 bytes. This code tells -the library to strip input data that has 4 or 8 bytes per pixel down -to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2 -bytes per pixel). - - png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE); - -where the 0 is unused, and the location is either PNG_FILLER_BEFORE or -PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel -is stored XRGB or RGBX. - -PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as -they can, resulting in, for example, 8 pixels per byte for 1 bit files. -If the data is supplied at 1 pixel per byte, use this code, which will -correctly pack the pixels into a single byte: - - png_set_packing(png_ptr); - -PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your -data is of another bit depth, you can write an sBIT chunk into the -file so that decoders can recover the original data if desired. - - /* Set the true bit depth of the image data */ - if (color_type & PNG_COLOR_MASK_COLOR) - { - sig_bit.red = true_bit_depth; - sig_bit.green = true_bit_depth; - sig_bit.blue = true_bit_depth; - } - - else - { - sig_bit.gray = true_bit_depth; - } - - if (color_type & PNG_COLOR_MASK_ALPHA) - { - sig_bit.alpha = true_bit_depth; - } - - png_set_sBIT(png_ptr, info_ptr, &sig_bit); - -If the data is stored in the row buffer in a bit depth other than -one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG), -this will scale the values to appear to be the correct bit depth as -is required by PNG. - - png_set_shift(png_ptr, &sig_bit); - -PNG files store 16-bit pixels in network byte order (big-endian, -ie. most significant bits first). This code would be used if they are -supplied the other way (little-endian, i.e. least significant bits -first, the way PCs store them): - - if (bit_depth > 8) - png_set_swap(png_ptr); - -If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you -need to change the order the pixels are packed into bytes, you can use: - - if (bit_depth < 8) - png_set_packswap(png_ptr); - -PNG files store 3 color pixels in red, green, blue order. This code -would be used if they are supplied as blue, green, red: - - png_set_bgr(png_ptr); - -PNG files describe monochrome as black being zero and white being -one. This code would be used if the pixels are supplied with this reversed -(black being one and white being zero): - - png_set_invert_mono(png_ptr); - -Finally, you can write your own transformation function if none of -the existing ones meets your needs. This is done by setting a callback -with - - png_set_write_user_transform_fn(png_ptr, - write_transform_fn); - -You must supply the function - - void write_transform_fn(png_structp png_ptr, png_row_infop - row_info, png_bytep data) - -See pngtest.c for a working example. Your function will be called -before any of the other transformations are processed. If supported -libpng also supplies an information routine that may be called from -your callback: - - png_get_current_row_number(png_ptr); - png_get_current_pass_number(png_ptr); - -This returns the current row passed to the transform. With interlaced -images the value returned is the row in the input sub-image image. Use -PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to -find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass). - -The discussion of interlace handling above contains more information on how to -use these values. - -You can also set up a pointer to a user structure for use by your -callback function. - - png_set_user_transform_info(png_ptr, user_ptr, 0, 0); - -The user_channels and user_depth parameters of this function are ignored -when writing; you can set them to zero as shown. - -You can retrieve the pointer via the function png_get_user_transform_ptr(). -For example: - - voidp write_user_transform_ptr = - png_get_user_transform_ptr(png_ptr); - -It is possible to have libpng flush any pending output, either manually, -or automatically after a certain number of lines have been written. To -flush the output stream a single time call: - - png_write_flush(png_ptr); - -and to have libpng flush the output stream periodically after a certain -number of scanlines have been written, call: - - png_set_flush(png_ptr, nrows); - -Note that the distance between rows is from the last time png_write_flush() -was called, or the first row of the image if it has never been called. -So if you write 50 lines, and then png_set_flush 25, it will flush the -output on the next scanline, and every 25 lines thereafter, unless -png_write_flush() is called before 25 more lines have been written. -If nrows is too small (less than about 10 lines for a 640 pixel wide -RGB image) the image compression may decrease noticeably (although this -may be acceptable for real-time applications). Infrequent flushing will -only degrade the compression performance by a few percent over images -that do not use flushing. - -Writing the image data - -That's it for the transformations. Now you can write the image data. -The simplest way to do this is in one function call. If you have the -whole image in memory, you can just call png_write_image() and libpng -will write the image. You will need to pass in an array of pointers to -each row. This function automatically handles interlacing, so you don't -need to call png_set_interlace_handling() or call this function multiple -times, or any of that other stuff necessary with png_write_rows(). - - png_write_image(png_ptr, row_pointers); - -where row_pointers is: - - png_byte *row_pointers[height]; - -You can point to void or char or whatever you use for pixels. - -If you don't want to write the whole image at once, you can -use png_write_rows() instead. If the file is not interlaced, -this is simple: - - png_write_rows(png_ptr, row_pointers, - number_of_rows); - -row_pointers is the same as in the png_write_image() call. - -If you are just writing one row at a time, you can do this with -a single row_pointer instead of an array of row_pointers: - - png_bytep row_pointer = row; - - png_write_row(png_ptr, row_pointer); - -When the file is interlaced, things can get a good deal more complicated. -The only currently (as of the PNG Specification version 1.2, dated July -1999) defined interlacing scheme for PNG files is the "Adam7" interlace -scheme, that breaks down an image into seven smaller images of varying -size. libpng will build these images for you, or you can do them -yourself. If you want to build them yourself, see the PNG specification -for details of which pixels to write when. - -If you don't want libpng to handle the interlacing details, just -use png_set_interlace_handling() and call png_write_rows() the -correct number of times to write all the sub-images -(png_set_interlace_handling() returns the number of sub-images.) - -If you want libpng to build the sub-images, call this before you start -writing any rows: - - number_of_passes = png_set_interlace_handling(png_ptr); - -This will return the number of passes needed. Currently, this is seven, -but may change if another interlace type is added. - -Then write the complete image number_of_passes times. - - png_write_rows(png_ptr, row_pointers, number_of_rows); - -Think carefully before you write an interlaced image. Typically code that -reads such images reads all the image data into memory, uncompressed, before -doing any processing. Only code that can display an image on the fly can -take advantage of the interlacing and even then the image has to be exactly -the correct size for the output device, because scaling an image requires -adjacent pixels and these are not available until all the passes have been -read. - -If you do write an interlaced image you will hardly ever need to handle -the interlacing yourself. Call png_set_interlace_handling() and use the -approach described above. - -The only time it is conceivable that you will really need to write an -interlaced image pass-by-pass is when you have read one pass by pass and -made some pixel-by-pixel transformation to it, as described in the read -code above. In this case use the PNG_PASS_ROWS and PNG_PASS_COLS macros -to determine the size of each sub-image in turn and simply write the rows -you obtained from the read code. - -Finishing a sequential write - -After you are finished writing the image, you should finish writing -the file. If you are interested in writing comments or time, you should -pass an appropriately filled png_info pointer. If you are not interested, -you can pass NULL. - - png_write_end(png_ptr, info_ptr); - -When you are done, you can free all memory used by libpng like this: - - png_destroy_write_struct(&png_ptr, &info_ptr); - -It is also possible to individually free the info_ptr members that -point to libpng-allocated storage with the following function: - - png_free_data(png_ptr, info_ptr, mask, seq) - - mask - identifies data to be freed, a mask - containing the bitwise OR of one or - more of - PNG_FREE_PLTE, PNG_FREE_TRNS, - PNG_FREE_HIST, PNG_FREE_ICCP, - PNG_FREE_PCAL, PNG_FREE_ROWS, - PNG_FREE_SCAL, PNG_FREE_SPLT, - PNG_FREE_TEXT, PNG_FREE_UNKN, - or simply PNG_FREE_ALL - - seq - sequence number of item to be freed - (-1 for all items) - -This function may be safely called when the relevant storage has -already been freed, or has not yet been allocated, or was allocated -by the user and not by libpng, and will in those cases do nothing. -The "seq" parameter is ignored if only one item of the selected data -type, such as PLTE, is allowed. If "seq" is not -1, and multiple items -are allowed for the data type identified in the mask, such as text or -sPLT, only the n'th item in the structure is freed, where n is "seq". - -If you allocated data such as a palette that you passed in to libpng -with png_set_*, you must not free it until just before the call to -png_destroy_write_struct(). - -The default behavior is only to free data that was allocated internally -by libpng. This can be changed, so that libpng will not free the data, -or so that it will free data that was allocated by the user with png_malloc() -or png_calloc() and passed in via a png_set_*() function, with - - png_data_freer(png_ptr, info_ptr, freer, mask) - - freer - one of - PNG_DESTROY_WILL_FREE_DATA - PNG_SET_WILL_FREE_DATA - PNG_USER_WILL_FREE_DATA - - mask - which data elements are affected - same choices as in png_free_data() - -For example, to transfer responsibility for some data from a read structure -to a write structure, you could use - - png_data_freer(read_ptr, read_info_ptr, - PNG_USER_WILL_FREE_DATA, - PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST) - - png_data_freer(write_ptr, write_info_ptr, - PNG_DESTROY_WILL_FREE_DATA, - PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST) - -thereby briefly reassigning responsibility for freeing to the user but -immediately afterwards reassigning it once more to the write_destroy -function. Having done this, it would then be safe to destroy the read -structure and continue to use the PLTE, tRNS, and hIST data in the write -structure. - -This function only affects data that has already been allocated. -You can call this function before calling after the png_set_*() functions -to control whether the user or png_destroy_*() is supposed to free the data. -When the user assumes responsibility for libpng-allocated data, the -application must use -png_free() to free it, and when the user transfers responsibility to libpng -for data that the user has allocated, the user must have used png_malloc() -or png_calloc() to allocate it. - -If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword -separately, do not transfer responsibility for freeing text_ptr to libpng, -because when libpng fills a png_text structure it combines these members with -the key member, and png_free_data() will free only text_ptr.key. Similarly, -if you transfer responsibility for free'ing text_ptr from libpng to your -application, your application must not separately free those members. -For a more compact example of writing a PNG image, see the file example.c. - -V. Simplified API - -The simplified API, which became available in libpng-1.6.0, hides the details -of both libpng and the PNG file format itself. -It allows PNG files to be read into a very limited number of -in-memory bitmap formats or to be written from the same formats. If these -formats do not accommodate your needs then you can, and should, use the more -sophisticated APIs above - these support a wide variety of in-memory formats -and a wide variety of sophisticated transformations to those formats as well -as a wide variety of APIs to manipulate ancilliary information. - -To read a PNG file using the simplified API: - - 1) Declare a 'png_image' structure (see below) on the stack, set the - version field to PNG_IMAGE_VERSION and the 'opaque' pointer to NULL - (this is REQUIRED, your program may crash if you don't do it.) - - 2) Call the appropriate png_image_begin_read... function. - - 3) Set the png_image 'format' member to the required sample format. - - 4) Allocate a buffer for the image and, if required, the color-map. - - 5) Call png_image_finish_read to read the image and, if required, the - color-map into your buffers. - -There are no restrictions on the format of the PNG input itself; all valid -color types, bit depths, and interlace methods are acceptable, and the -input image is transformed as necessary to the requested in-memory format -during the png_image_finish_read() step. The only caveat is that if you -request a color-mapped image from a PNG that is full-color or makes -complex use of an alpha channel the transformation is extremely lossy and the -result may look terrible. - -To write a PNG file using the simplified API: - - 1) Declare a 'png_image' structure on the stack and memset() - it to all zero. - - 2) Initialize the members of the structure that describe the - image, setting the 'format' member to the format of the - image samples. - - 3) Call the appropriate png_image_write... function with a - pointer to the image and, if necessary, the color-map to write - the PNG data. - -png_image is a structure that describes the in-memory format of an image -when it is being read or defines the in-memory format of an image that you -need to write. The "png_image" structure contains the following members: - - png_controlp opaque Initialize to NULL, free with png_image_free - png_uint_32 version Set to PNG_IMAGE_VERSION - png_uint_32 width Image width in pixels (columns) - png_uint_32 height Image height in pixels (rows) - png_uint_32 format Image format as defined below - png_uint_32 flags A bit mask containing informational flags - png_uint_32 colormap_entries; Number of entries in the color-map - png_uint_32 warning_or_error; - char message[64]; - -In the event of an error or warning the "warning_or_error" -field will be set to a non-zero value and the 'message' field will contain -a '\0' terminated string with the libpng error or warning message. If both -warnings and an error were encountered, only the error is recorded. If there -are multiple warnings, only the first one is recorded. - -The upper 30 bits of the "warning_or_error" value are reserved; the low two -bits contain a two bit code such that a value more than 1 indicates a failure -in the API just called: - - 0 - no warning or error - 1 - warning - 2 - error - 3 - error preceded by warning - -The pixels (samples) of the image have one to four channels whose components -have original values in the range 0 to 1.0: - - 1: A single gray or luminance channel (G). - 2: A gray/luminance channel and an alpha channel (GA). - 3: Three red, green, blue color channels (RGB). - 4: Three color channels and an alpha channel (RGBA). - -The channels are encoded in one of two ways: - - a) As a small integer, value 0..255, contained in a single byte. For the -alpha channel the original value is simply value/255. For the color or -luminance channels the value is encoded according to the sRGB specification -and matches the 8-bit format expected by typical display devices. - -The color/gray channels are not scaled (pre-multiplied) by the alpha -channel and are suitable for passing to color management software. - - b) As a value in the range 0..65535, contained in a 2-byte integer, in -the native byte order of the platform on which the application is running. -All channels can be converted to the original value by dividing by 65535; all -channels are linear. Color channels use the RGB encoding (RGB end-points) of -the sRGB specification. This encoding is identified by the -PNG_FORMAT_FLAG_LINEAR flag below. - -When the simplified API needs to convert between sRGB and linear colorspaces, -the actual sRGB transfer curve defined in the sRGB specification (see the -article at https://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2 -approximation used elsewhere in libpng. - -When an alpha channel is present it is expected to denote pixel coverage -of the color or luminance channels and is returned as an associated alpha -channel: the color/gray channels are scaled (pre-multiplied) by the alpha -value. - -The samples are either contained directly in the image data, between 1 and 8 -bytes per pixel according to the encoding, or are held in a color-map indexed -by bytes in the image data. In the case of a color-map the color-map entries -are individual samples, encoded as above, and the image data has one byte per -pixel to select the relevant sample from the color-map. - -PNG_FORMAT_* - -The #defines to be used in png_image::format. Each #define identifies a -particular layout of channel data and, if present, alpha values. There are -separate defines for each of the two component encodings. - -A format is built up using single bit flag values. All combinations are -valid. Formats can be built up from the flag values or you can use one of -the predefined values below. When testing formats always use the FORMAT_FLAG -macros to test for individual features - future versions of the library may -add new flags. - -When reading or writing color-mapped images the format should be set to the -format of the entries in the color-map then png_image_{read,write}_colormap -called to read or write the color-map and set the format correctly for the -image data. Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly! - -NOTE: libpng can be built with particular features disabled. If you see -compiler errors because the definition of one of the following flags has been -compiled out it is because libpng does not have the required support. It is -possible, however, for the libpng configuration to enable the format on just -read or just write; in that case you may see an error at run time. -You can guard against this by checking for the definition of the -appropriate "_SUPPORTED" macro, one of: - - PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED - - PNG_FORMAT_FLAG_ALPHA format with an alpha channel - PNG_FORMAT_FLAG_COLOR color format: otherwise grayscale - PNG_FORMAT_FLAG_LINEAR 2-byte channels else 1-byte - PNG_FORMAT_FLAG_COLORMAP image data is color-mapped - PNG_FORMAT_FLAG_BGR BGR colors, else order is RGB - PNG_FORMAT_FLAG_AFIRST alpha channel comes first - -Supported formats are as follows. Future versions of libpng may support more -formats; for compatibility with older versions simply check if the format -macro is defined using #ifdef. These defines describe the in-memory layout -of the components of the pixels of the image. - -First the single byte (sRGB) formats: - - PNG_FORMAT_GRAY - PNG_FORMAT_GA - PNG_FORMAT_AG - PNG_FORMAT_RGB - PNG_FORMAT_BGR - PNG_FORMAT_RGBA - PNG_FORMAT_ARGB - PNG_FORMAT_BGRA - PNG_FORMAT_ABGR - -Then the linear 2-byte formats. When naming these "Y" is used to -indicate a luminance (gray) channel. The component order within the pixel -is always the same - there is no provision for swapping the order of the -components in the linear format. The components are 16-bit integers in -the native byte order for your platform, and there is no provision for -swapping the bytes to a different endian condition. - - PNG_FORMAT_LINEAR_Y - PNG_FORMAT_LINEAR_Y_ALPHA - PNG_FORMAT_LINEAR_RGB - PNG_FORMAT_LINEAR_RGB_ALPHA - -With color-mapped formats the image data is one byte for each pixel. The byte -is an index into the color-map which is formatted as above. To obtain a -color-mapped format it is sufficient just to add the PNG_FOMAT_FLAG_COLORMAP -to one of the above definitions, or you can use one of the definitions below. - - PNG_FORMAT_RGB_COLORMAP - PNG_FORMAT_BGR_COLORMAP - PNG_FORMAT_RGBA_COLORMAP - PNG_FORMAT_ARGB_COLORMAP - PNG_FORMAT_BGRA_COLORMAP - PNG_FORMAT_ABGR_COLORMAP - -PNG_IMAGE macros - -These are convenience macros to derive information from a png_image -structure. The PNG_IMAGE_SAMPLE_ macros return values appropriate to the -actual image sample values - either the entries in the color-map or the -pixels in the image. The PNG_IMAGE_PIXEL_ macros return corresponding values -for the pixels and will always return 1 for color-mapped formats. The -remaining macros return information about the rows in the image and the -complete image. - -NOTE: All the macros that take a png_image::format parameter are compile time -constants if the format parameter is, itself, a constant. Therefore these -macros can be used in array declarations and case labels where required. -Similarly the macros are also pre-processor constants (sizeof is not used) so -they can be used in #if tests. - - PNG_IMAGE_SAMPLE_CHANNELS(fmt) - Returns the total number of channels in a given format: 1..4 - - PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt) - Returns the size in bytes of a single component of a pixel or color-map - entry (as appropriate) in the image: 1 or 2. - - PNG_IMAGE_SAMPLE_SIZE(fmt) - This is the size of the sample data for one sample. If the image is - color-mapped it is the size of one color-map entry (and image pixels are - one byte in size), otherwise it is the size of one image pixel. - - PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt) - The maximum size of the color-map required by the format expressed in a - count of components. This can be used to compile-time allocate a - color-map: - - png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)]; - - png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)]; - - Alternatively use the PNG_IMAGE_COLORMAP_SIZE macro below to use the - information from one of the png_image_begin_read_ APIs and dynamically - allocate the required memory. - - PNG_IMAGE_COLORMAP_SIZE(fmt) - The size of the color-map required by the format; this is the size of the - color-map buffer passed to the png_image_{read,write}_colormap APIs. It is - a fixed number determined by the format so can easily be allocated on the - stack if necessary. - -Corresponding information about the pixels - - PNG_IMAGE_PIXEL_CHANNELS(fmt) - The number of separate channels (components) in a pixel; 1 for a - color-mapped image. - - PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\ - The size, in bytes, of each component in a pixel; 1 for a color-mapped - image. - - PNG_IMAGE_PIXEL_SIZE(fmt) - The size, in bytes, of a complete pixel; 1 for a color-mapped image. - -Information about the whole row, or whole image - - PNG_IMAGE_ROW_STRIDE(image) - Returns the total number of components in a single row of the image; this - is the minimum 'row stride', the minimum count of components between each - row. For a color-mapped image this is the minimum number of bytes in a - row. - - If you need the stride measured in bytes, row_stride_bytes is - PNG_IMAGE_ROW_STRIDE(image) * PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt) - plus any padding bytes that your application might need, for example - to start the next row on a 4-byte boundary. - - PNG_IMAGE_BUFFER_SIZE(image, row_stride) - Return the size, in bytes, of an image buffer given a png_image and a row - stride - the number of components to leave space for in each row. - - PNG_IMAGE_SIZE(image) - Return the size, in bytes, of the image in memory given just a png_image; - the row stride is the minimum stride required for the image. - - PNG_IMAGE_COLORMAP_SIZE(image) - Return the size, in bytes, of the color-map of this image. If the image - format is not a color-map format this will return a size sufficient for - 256 entries in the given format; check PNG_FORMAT_FLAG_COLORMAP if - you don't want to allocate a color-map in this case. - -PNG_IMAGE_FLAG_* - -Flags containing additional information about the image are held in -the 'flags' field of png_image. - - PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01 - This indicates the the RGB values of the in-memory bitmap do not - correspond to the red, green and blue end-points defined by sRGB. - - PNG_IMAGE_FLAG_FAST == 0x02 - On write emphasise speed over compression; the resultant PNG file will be - larger but will be produced significantly faster, particular for large - images. Do not use this option for images which will be distributed, only - used it when producing intermediate files that will be read back in - repeatedly. For a typical 24-bit image the option will double the read - speed at the cost of increasing the image size by 25%, however for many - more compressible images the PNG file can be 10 times larger with only a - slight speed gain. - - PNG_IMAGE_FLAG_16BIT_sRGB == 0x04 - On read if the image is a 16-bit per component image and there is no gAMA - or sRGB chunk assume that the components are sRGB encoded. Notice that - images output by the simplified API always have gamma information; setting - this flag only affects the interpretation of 16-bit images from an - external source. It is recommended that the application expose this flag - to the user; the user can normally easily recognize the difference between - linear and sRGB encoding. This flag has no effect on write - the data - passed to the write APIs must have the correct encoding (as defined - above.) - - If the flag is not set (the default) input 16-bit per component data is - assumed to be linear. - - NOTE: the flag can only be set after the png_image_begin_read_ call, - because that call initializes the 'flags' field. - -READ APIs - - The png_image passed to the read APIs must have been initialized by setting - the png_controlp field 'opaque' to NULL (or, better, memset the whole thing.) - - int png_image_begin_read_from_file( png_imagep image, - const char *file_name) - - The named file is opened for read and the image header - is filled in from the PNG header in the file. - - int png_image_begin_read_from_stdio (png_imagep image, - FILE* file) - - The PNG header is read from the stdio FILE object. - - int png_image_begin_read_from_memory(png_imagep image, - png_const_voidp memory, png_size_t size) - - The PNG header is read from the given memory buffer. - - int png_image_finish_read(png_imagep image, - png_colorp background, void *buffer, - png_int_32 row_stride, void *colormap)); - - Finish reading the image into the supplied buffer and - clean up the png_image structure. - - row_stride is the step, in png_byte or png_uint_16 units - as appropriate, between adjacent rows. A positive stride - indicates that the top-most row is first in the buffer - - the normal top-down arrangement. A negative stride - indicates that the bottom-most row is first in the buffer. - - background need only be supplied if an alpha channel must - be removed from a png_byte format and the removal is to be - done by compositing on a solid color; otherwise it may be - NULL and any composition will be done directly onto the - buffer. The value is an sRGB color to use for the - background, for grayscale output the green channel is used. - - For linear output removing the alpha channel is always done - by compositing on black. - - void png_image_free(png_imagep image) - - Free any data allocated by libpng in image->opaque, - setting the pointer to NULL. May be called at any time - after the structure is initialized. - -When the simplified API needs to convert between sRGB and linear colorspaces, -the actual sRGB transfer curve defined in the sRGB specification (see the -article at https://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2 -approximation used elsewhere in libpng. - -WRITE APIS - -For write you must initialize a png_image structure to describe the image to -be written: - - version: must be set to PNG_IMAGE_VERSION - opaque: must be initialized to NULL - width: image width in pixels - height: image height in rows - format: the format of the data you wish to write - flags: set to 0 unless one of the defined flags applies; set - PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB for color format images - where the RGB values do not correspond to the colors in sRGB. - colormap_entries: set to the number of entries in the color-map (0 to 256) - - int png_image_write_to_file, (png_imagep image, - const char *file, int convert_to_8bit, const void *buffer, - png_int_32 row_stride, const void *colormap)); - - Write the image to the named file. - - int png_image_write_to_memory (png_imagep image, void *memory, - png_alloc_size_t * PNG_RESTRICT memory_bytes, - int convert_to_8_bit, const void *buffer, ptrdiff_t row_stride, - const void *colormap)); - - Write the image to memory. - - 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*). - -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 -a (png_byte) PNG gamma encoded according to the sRGB specification, otherwise -a 16-bit linear encoded PNG file is written. - -With all APIs row_stride is handled as in the read APIs - it is the spacing -from one row to the next in component sized units (float) and if negative -indicates a bottom-up row layout in the buffer. If you pass zero, libpng will -calculate the row_stride for you from the width and number of channels. - -Note that the write API does not support interlacing, sub-8-bit pixels, -indexed (paletted) images, or most ancillary chunks. - -VI. Modifying/Customizing libpng - -There are two issues here. The first is changing how libpng does -standard things like memory allocation, input/output, and error handling. -The second deals with more complicated things like adding new chunks, -adding new transformations, and generally changing how libpng works. -Both of those are compile-time issues; that is, they are generally -determined at the time the code is written, and there is rarely a need -to provide the user with a means of changing them. - -Memory allocation, input/output, and error handling - -All of the memory allocation, input/output, and error handling in libpng -goes through callbacks that are user-settable. The default routines are -in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change -these functions, call the appropriate png_set_*_fn() function. - -Memory allocation is done through the functions png_malloc(), png_calloc(), -and png_free(). The png_malloc() and png_free() functions currently just -call the standard C functions and png_calloc() calls png_malloc() and then -clears the newly allocated memory to zero; note that png_calloc(png_ptr, size) -is not the same as the calloc(number, size) function provided by stdlib.h. -There is limited support for certain systems with segmented memory -architectures and the types of pointers declared by png.h match this; you -will have to use appropriate pointers in your application. If you prefer -to use a different method of allocating and freeing data, you can use -png_create_read_struct_2() or png_create_write_struct_2() to register your -own functions as described above. These functions also provide a void -pointer that can be retrieved via - - mem_ptr=png_get_mem_ptr(png_ptr); - -Your replacement memory functions must have prototypes as follows: - - png_voidp malloc_fn(png_structp png_ptr, - png_alloc_size_t size); - - void free_fn(png_structp png_ptr, png_voidp ptr); - -Your malloc_fn() must return NULL in case of failure. The png_malloc() -function will normally call png_error() if it receives a NULL from the -system memory allocator or from your replacement malloc_fn(). - -Your free_fn() will never be called with a NULL ptr, since libpng's -png_free() checks for NULL before calling free_fn(). - -Input/Output in libpng is done through png_read() and png_write(), -which currently just call fread() and fwrite(). The FILE * is stored in -png_struct and is initialized via png_init_io(). If you wish to change -the method of I/O, the library supplies callbacks that you can set -through the function png_set_read_fn() and png_set_write_fn() at run -time, instead of calling the png_init_io() function. These functions -also provide a void pointer that can be retrieved via the function -png_get_io_ptr(). For example: - - png_set_read_fn(png_structp read_ptr, - voidp read_io_ptr, png_rw_ptr read_data_fn) - - png_set_write_fn(png_structp write_ptr, - voidp write_io_ptr, png_rw_ptr write_data_fn, - png_flush_ptr output_flush_fn); - - voidp read_io_ptr = png_get_io_ptr(read_ptr); - voidp write_io_ptr = png_get_io_ptr(write_ptr); - -The replacement I/O functions must have prototypes as follows: - - void user_read_data(png_structp png_ptr, - png_bytep data, png_size_t length); - - void user_write_data(png_structp png_ptr, - png_bytep data, png_size_t length); - - void user_flush_data(png_structp png_ptr); - -The user_read_data() function is responsible for detecting and -handling end-of-data errors. - -Supplying NULL for the read, write, or flush functions sets them back -to using the default C stream functions, which expect the io_ptr to -point to a standard *FILE structure. It is probably a mistake -to use NULL for one of write_data_fn and output_flush_fn but not both -of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined. -It is an error to read from a write stream, and vice versa. - -Error handling in libpng is done through png_error() and png_warning(). -Errors handled through png_error() are fatal, meaning that png_error() -should never return to its caller. Currently, this is handled via -setjmp() and longjmp() (unless you have compiled libpng with -PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()), -but you could change this to do things like exit() if you should wish, -as long as your function does not return. - -On non-fatal errors, png_warning() is called -to print a warning message, and then control returns to the calling code. -By default png_error() and png_warning() print a message on stderr via -fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined -(because you don't want the messages) or PNG_NO_STDIO defined (because -fprintf() isn't available). If you wish to change the behavior of the error -functions, you will need to set up your own message callbacks. These -functions are normally supplied at the time that the png_struct is created. -It is also possible to redirect errors and warnings to your own replacement -functions after png_create_*_struct() has been called by calling: - - png_set_error_fn(png_structp png_ptr, - png_voidp error_ptr, png_error_ptr error_fn, - png_error_ptr warning_fn); - -If NULL is supplied for either error_fn or warning_fn, then the libpng -default function will be used, calling fprintf() and/or longjmp() if a -problem is encountered. The replacement error functions should have -parameters as follows: - - void user_error_fn(png_structp png_ptr, - png_const_charp error_msg); - - void user_warning_fn(png_structp png_ptr, - png_const_charp warning_msg); - -Then, within your user_error_fn or user_warning_fn, you can retrieve -the error_ptr if you need it, by calling - - png_voidp error_ptr = png_get_error_ptr(png_ptr); - -The motivation behind using setjmp() and longjmp() is the C++ throw and -catch exception handling methods. This makes the code much easier to write, -as there is no need to check every return code of every function call. -However, there are some uncertainties about the status of local variables -after a longjmp, so the user may want to be careful about doing anything -after setjmp returns non-zero besides returning itself. Consult your -compiler documentation for more details. For an alternative approach, you -may wish to use the "cexcept" facility (see https://cexcept.sourceforge.io/), -which is illustrated in pngvalid.c and in contrib/visupng. - -Beginning in libpng-1.4.0, the png_set_benign_errors() API became available. -You can use this to handle certain errors (normally handled as errors) -as warnings. - - png_set_benign_errors (png_ptr, int allowed); - - allowed: 0: treat png_benign_error() as an error. - 1: treat png_benign_error() as a warning. - -As of libpng-1.6.0, the default condition is to treat benign errors as -warnings while reading and as errors while writing. - -Custom chunks - -If you need to read or write custom chunks, you may need to get deeper -into the libpng code. The library now has mechanisms for storing -and writing chunks of unknown type; you can even declare callbacks -for custom chunks. However, this may not be good enough if the -library code itself needs to know about interactions between your -chunk and existing `intrinsic' chunks. - -If you need to write a new intrinsic chunk, first read the PNG -specification. Acquire a first level of understanding of how it works. -Pay particular attention to the sections that describe chunk names, -and look at how other chunks were designed, so you can do things -similarly. Second, check out the sections of libpng that read and -write chunks. Try to find a chunk that is similar to yours and use -it as a template. More details can be found in the comments inside -the code. It is best to handle private or unknown chunks in a generic method, -via callback functions, instead of by modifying libpng functions. This -is illustrated in pngtest.c, which uses a callback function to handle a -private "vpAg" chunk and the new "sTER" chunk, which are both unknown to -libpng. - -If you wish to write your own transformation for the data, look through -the part of the code that does the transformations, and check out some of -the simpler ones to get an idea of how they work. Try to find a similar -transformation to the one you want to add and copy off of it. More details -can be found in the comments inside the code itself. - -Configuring for gui/windowing platforms: - -You will need to write new error and warning functions that use the GUI -interface, as described previously, and set them to be the error and -warning functions at the time that png_create_*_struct() is called, -in order to have them available during the structure initialization. -They can be changed later via png_set_error_fn(). On some compilers, -you may also have to change the memory allocators (png_malloc, etc.). - -Configuring zlib: - -There are special functions to configure the compression. Perhaps the -most useful one changes the compression level, which currently uses -input compression values in the range 0 - 9. The library normally -uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests -have shown that for a large majority of images, compression values in -the range 3-6 compress nearly as well as higher levels, and do so much -faster. For online applications it may be desirable to have maximum speed -(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also -specify no compression (Z_NO_COMPRESSION = 0), but this would create -files larger than just storing the raw bitmap. You can specify the -compression level by calling: - - #include zlib.h - png_set_compression_level(png_ptr, level); - -Another useful one is to reduce the memory level used by the library. -The memory level defaults to 8, but it can be lowered if you are -short on memory (running DOS, for example, where you only have 640K). -Note that the memory level does have an effect on compression; among -other things, lower levels will result in sections of incompressible -data being emitted in smaller stored blocks, with a correspondingly -larger relative overhead of up to 15% in the worst case. - - #include zlib.h - png_set_compression_mem_level(png_ptr, level); - -The other functions are for configuring zlib. They are not recommended -for normal use and may result in writing an invalid PNG file. See -zlib.h for more information on what these mean. - - #include zlib.h - png_set_compression_strategy(png_ptr, - strategy); - - png_set_compression_window_bits(png_ptr, - window_bits); - - png_set_compression_method(png_ptr, method); - -This controls the size of the IDAT chunks (default 8192): - - png_set_compression_buffer_size(png_ptr, size); - -As of libpng version 1.5.4, additional APIs became -available to set these separately for non-IDAT -compressed chunks such as zTXt, iTXt, and iCCP: - - #include zlib.h - #if PNG_LIBPNG_VER >= 10504 - png_set_text_compression_level(png_ptr, level); - - png_set_text_compression_mem_level(png_ptr, level); - - png_set_text_compression_strategy(png_ptr, - strategy); - - png_set_text_compression_window_bits(png_ptr, - window_bits); - - png_set_text_compression_method(png_ptr, method); - #endif - -Controlling row filtering - -If you want to control whether libpng uses filtering or not, which -filters are used, and how it goes about picking row filters, you -can call one of these functions. The selection and configuration -of row filters can have a significant impact on the size and -encoding speed and a somewhat lesser impact on the decoding speed -of an image. Filtering is enabled by default for RGB and grayscale -images (with and without alpha), but not for paletted images nor -for any images with bit depths less than 8 bits/pixel. - -The 'method' parameter sets the main filtering method, which is -currently only '0' in the PNG 1.2 specification. The 'filters' -parameter sets which filter(s), if any, should be used for each -scanline. Possible values are PNG_ALL_FILTERS, PNG_NO_FILTERS, -or PNG_FAST_FILTERS to turn filtering on and off, or to turn on -just the fast-decoding subset of filters, respectively. - -Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB, -PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise -ORed together with '|' to specify one or more filters to use. -These filters are described in more detail in the PNG specification. -If you intend to change the filter type during the course of writing -the image, you should start with flags set for all of the filters -you intend to use so that libpng can initialize its internal -structures appropriately for all of the filter types. (Note that this -means the first row must always be adaptively filtered, because libpng -currently does not allocate the filter buffers until png_write_row() -is called for the first time.) - - filters = PNG_NO_FILTERS; - filters = PNG_ALL_FILTERS; - filters = PNG_FAST_FILTERS; - - or - - filters = PNG_FILTER_NONE | PNG_FILTER_SUB | - PNG_FILTER_UP | PNG_FILTER_AVG | - PNG_FILTER_PAETH; - - png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE, - filters); - - The second parameter can also be - PNG_INTRAPIXEL_DIFFERENCING if you are - writing a PNG to be embedded in a MNG - datastream. This parameter must be the - same as the value of filter_method used - in png_set_IHDR(). - -Requesting debug printout - -The macro definition PNG_DEBUG can be used to request debugging -printout. Set it to an integer value in the range 0 to 3. Higher -numbers result in increasing amounts of debugging information. The -information is printed to the "stderr" file, unless another file -name is specified in the PNG_DEBUG_FILE macro definition. - -When PNG_DEBUG > 0, the following functions (macros) become available: - - png_debug(level, message) - png_debug1(level, message, p1) - png_debug2(level, message, p1, p2) - -in which "level" is compared to PNG_DEBUG to decide whether to print -the message, "message" is the formatted string to be printed, -and p1 and p2 are parameters that are to be embedded in the string -according to printf-style formatting directives. For example, - - png_debug1(2, "foo=%d", foo); - -is expanded to - - if (PNG_DEBUG > 2) - fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo); - -When PNG_DEBUG is defined but is zero, the macros aren't defined, but you -can still use PNG_DEBUG to control your own debugging: - - #ifdef PNG_DEBUG - fprintf(stderr, ... - #endif - -When PNG_DEBUG = 1, the macros are defined, but only png_debug statements -having level = 0 will be printed. There aren't any such statements in -this version of libpng, but if you insert some they will be printed. - -VII. MNG support - -The MNG specification (available at http://www.libpng.org/pub/mng) allows -certain extensions to PNG for PNG images that are embedded in MNG datastreams. -Libpng can support some of these extensions. To enable them, use the -png_permit_mng_features() function: - - feature_set = png_permit_mng_features(png_ptr, mask) - - mask is a png_uint_32 containing the bitwise OR of the - features you want to enable. These include - PNG_FLAG_MNG_EMPTY_PLTE - PNG_FLAG_MNG_FILTER_64 - PNG_ALL_MNG_FEATURES - - feature_set is a png_uint_32 that is the bitwise AND of - your mask with the set of MNG features that is - supported by the version of libpng that you are using. - -It is an error to use this function when reading or writing a standalone -PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped -in a MNG datastream. As a minimum, it must have the MNG 8-byte signature -and the MHDR and MEND chunks. Libpng does not provide support for these -or any other MNG chunks; your application must provide its own support for -them. You may wish to consider using libmng (available at -https://www.libmng.com/) instead. - -VIII. Changes to Libpng from version 0.88 - -It should be noted that versions of libpng later than 0.96 are not -distributed by the original libpng author, Guy Schalnat, nor by -Andreas Dilger, who had taken over from Guy during 1996 and 1997, and -distributed versions 0.89 through 0.96, but rather by another member -of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are -still alive and well, but they have moved on to other things. - -The old libpng functions png_read_init(), png_write_init(), -png_info_init(), png_read_destroy(), and png_write_destroy() have been -moved to PNG_INTERNAL in version 0.95 to discourage their use. These -functions will be removed from libpng version 1.4.0. - -The preferred method of creating and initializing the libpng structures is -via the png_create_read_struct(), png_create_write_struct(), and -png_create_info_struct() because they isolate the size of the structures -from the application, allow version error checking, and also allow the -use of custom error handling routines during the initialization, which -the old functions do not. The functions png_read_destroy() and -png_write_destroy() do not actually free the memory that libpng -allocated for these structs, but just reset the data structures, so they -can be used instead of png_destroy_read_struct() and -png_destroy_write_struct() if you feel there is too much system overhead -allocating and freeing the png_struct for each image read. - -Setting the error callbacks via png_set_message_fn() before -png_read_init() as was suggested in libpng-0.88 is no longer supported -because this caused applications that do not use custom error functions -to fail if the png_ptr was not initialized to zero. It is still possible -to set the error callbacks AFTER png_read_init(), or to change them with -png_set_error_fn(), which is essentially the same function, but with a new -name to force compilation errors with applications that try to use the old -method. - -Support for the sCAL, iCCP, iTXt, and sPLT chunks was added at libpng-1.0.6; -however, iTXt support was not enabled by default. - -Starting with version 1.0.7, you can find out which version of the library -you are using at run-time: - - png_uint_32 libpng_vn = png_access_version_number(); - -The number libpng_vn is constructed from the major version, minor -version with leading zero, and release number with leading zero, -(e.g., libpng_vn for version 1.0.7 is 10007). - -Note that this function does not take a png_ptr, so you can call it -before you've created one. - -You can also check which version of png.h you used when compiling your -application: - - png_uint_32 application_vn = PNG_LIBPNG_VER; - -IX. Changes to Libpng from version 1.0.x to 1.2.x - -Support for user memory management was enabled by default. To -accomplish this, the functions png_create_read_struct_2(), -png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(), -png_malloc_default(), and png_free_default() were added. - -Support for the iTXt chunk has been enabled by default as of -version 1.2.41. - -Support for certain MNG features was enabled. - -Support for numbered error messages was added. However, we never got -around to actually numbering the error messages. The function -png_set_strip_error_numbers() was added (Note: the prototype for this -function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE -builds of libpng-1.2.15. It was restored in libpng-1.2.36). - -The png_malloc_warn() function was added at libpng-1.2.3. This issues -a png_warning and returns NULL instead of aborting when it fails to -acquire the requested memory allocation. - -Support for setting user limits on image width and height was enabled -by default. The functions png_set_user_limits(), png_get_user_width_max(), -and png_get_user_height_max() were added at libpng-1.2.6. - -The png_set_add_alpha() function was added at libpng-1.2.7. - -The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9. -Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the -tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is -deprecated. - -A number of macro definitions in support of runtime selection of -assembler code features (especially Intel MMX code support) were -added at libpng-1.2.0: - - PNG_ASM_FLAG_MMX_SUPPORT_COMPILED - PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU - PNG_ASM_FLAG_MMX_READ_COMBINE_ROW - PNG_ASM_FLAG_MMX_READ_INTERLACE - PNG_ASM_FLAG_MMX_READ_FILTER_SUB - PNG_ASM_FLAG_MMX_READ_FILTER_UP - PNG_ASM_FLAG_MMX_READ_FILTER_AVG - PNG_ASM_FLAG_MMX_READ_FILTER_PAETH - PNG_ASM_FLAGS_INITIALIZED - PNG_MMX_READ_FLAGS - PNG_MMX_FLAGS - PNG_MMX_WRITE_FLAGS - PNG_MMX_FLAGS - -We added the following functions in support of runtime -selection of assembler code features: - - png_get_mmx_flagmask() - png_set_mmx_thresholds() - png_get_asm_flags() - png_get_mmx_bitdepth_threshold() - png_get_mmx_rowbytes_threshold() - png_set_asm_flags() - -We replaced all of these functions with simple stubs in libpng-1.2.20, -when the Intel assembler code was removed due to a licensing issue. - -These macros are deprecated: - - PNG_READ_TRANSFORMS_NOT_SUPPORTED - PNG_PROGRESSIVE_READ_NOT_SUPPORTED - PNG_NO_SEQUENTIAL_READ_SUPPORTED - PNG_WRITE_TRANSFORMS_NOT_SUPPORTED - PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED - PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED - -They have been replaced, respectively, by: - - PNG_NO_READ_TRANSFORMS - PNG_NO_PROGRESSIVE_READ - PNG_NO_SEQUENTIAL_READ - PNG_NO_WRITE_TRANSFORMS - PNG_NO_READ_ANCILLARY_CHUNKS - PNG_NO_WRITE_ANCILLARY_CHUNKS - -PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been -deprecated since libpng-1.0.16 and libpng-1.2.6. - -The function - png_check_sig(sig, num) -was replaced with - !png_sig_cmp(sig, 0, num) -It has been deprecated since libpng-0.90. - -The function - png_set_gray_1_2_4_to_8() -which also expands tRNS to alpha was replaced with - png_set_expand_gray_1_2_4_to_8() -which does not. It has been deprecated since libpng-1.0.18 and 1.2.9. - -X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x - -Private libpng prototypes and macro definitions were moved from -png.h and pngconf.h into a new pngpriv.h header file. - -Functions png_set_benign_errors(), png_benign_error(), and -png_chunk_benign_error() were added. - -Support for setting the maximum amount of memory that the application -will allocate for reading chunks was added, as a security measure. -The functions png_set_chunk_cache_max() and png_get_chunk_cache_max() -were added to the library. - -We implemented support for I/O states by adding png_ptr member io_state -and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c - -We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level -input transforms. - -Checking for and reporting of errors in the IHDR chunk is more thorough. - -Support for global arrays was removed, to improve thread safety. - -Some obsolete/deprecated macros and functions have been removed. - -Typecasted NULL definitions such as - #define png_voidp_NULL (png_voidp)NULL -were eliminated. If you used these in your application, just use -NULL instead. - -The png_struct and info_struct members "trans" and "trans_values" were -changed to "trans_alpha" and "trans_color", respectively. - -The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles -were removed. - -The PNG_1_0_X and PNG_1_2_X macros were eliminated. - -The PNG_LEGACY_SUPPORTED macro was eliminated. - -Many WIN32_WCE #ifdefs were removed. - -The functions png_read_init(info_ptr), png_write_init(info_ptr), -png_info_init(info_ptr), png_read_destroy(), and png_write_destroy() -have been removed. They have been deprecated since libpng-0.95. - -The png_permit_empty_plte() was removed. It has been deprecated -since libpng-1.0.9. Use png_permit_mng_features() instead. - -We removed the obsolete stub functions png_get_mmx_flagmask(), -png_set_mmx_thresholds(), png_get_asm_flags(), -png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(), -png_set_asm_flags(), and png_mmx_supported() - -We removed the obsolete png_check_sig(), png_memcpy_check(), and -png_memset_check() functions. Instead use !png_sig_cmp(), memcpy(), -and memset(), respectively. - -The function png_set_gray_1_2_4_to_8() was removed. It has been -deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with -png_set_expand_gray_1_2_4_to_8() because the former function also -expanded any tRNS chunk to an alpha channel. - -Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32 -were added and are used by default instead of the corresponding -functions. Unfortunately, -from libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the -function) incorrectly returned a value of type png_uint_32. - -We changed the prototype for png_malloc() from - png_malloc(png_structp png_ptr, png_uint_32 size) -to - png_malloc(png_structp png_ptr, png_alloc_size_t size) - -This also applies to the prototype for the user replacement malloc_fn(). - -The png_calloc() function was added and is used in place of -of "png_malloc(); memset();" except in the case in png_read_png() -where the array consists of pointers; in this case a "for" loop is used -after the png_malloc() to set the pointers to NULL, to give robust. -behavior in case the application runs out of memory part-way through -the process. - -We changed the prototypes of png_get_compression_buffer_size() and -png_set_compression_buffer_size() to work with png_size_t instead of -png_uint_32. - -Support for numbered error messages was removed by default, since we -never got around to actually numbering the error messages. The function -png_set_strip_error_numbers() was removed from the library by default. - -The png_zalloc() and png_zfree() functions are no longer exported. -The png_zalloc() function no longer zeroes out the memory that it -allocates. Applications that called png_zalloc(png_ptr, number, size) -can call png_calloc(png_ptr, number*size) instead, and can call -png_free() instead of png_zfree(). - -Support for dithering was disabled by default in libpng-1.4.0, because -it has not been well tested and doesn't actually "dither". -The code was not -removed, however, and could be enabled by building libpng with -PNG_READ_DITHER_SUPPORTED defined. In libpng-1.4.2, this support -was re-enabled, but the function was renamed png_set_quantize() to -reflect more accurately what it actually does. At the same time, -the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to -PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED -was renamed to PNG_READ_QUANTIZE_SUPPORTED. - -We removed the trailing '.' from the warning and error messages. - -XI. Changes to Libpng from version 1.4.x to 1.5.x - -From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the -function) incorrectly returned a value of type png_uint_32. -The incorrect macro was removed from libpng-1.4.5. - -Checking for invalid palette index on write was added at libpng -1.5.10. If a pixel contains an invalid (out-of-range) index libpng issues -a benign error. This is enabled by default because this condition is an -error according to the PNG specification, Clause 11.3.2, but the error can -be ignored in each png_ptr with - - png_set_check_for_invalid_index(png_ptr, allowed); - - allowed - one of - 0: disable benign error (accept the - invalid data without warning). - 1: enable benign error (treat the - invalid data as an error or a - warning). - -If the error is ignored, or if png_benign_error() treats it as a warning, -any invalid pixels are decoded as opaque black by the decoder and written -as-is by the encoder. - -Retrieving the maximum palette index found was added at libpng-1.5.15. -This statement must appear after png_read_png() or png_read_image() while -reading, and after png_write_png() or png_write_image() while writing. - - int max_palette = png_get_palette_max(png_ptr, info_ptr); - -This will return the maximum palette index found in the image, or "-1" if -the palette was not checked, or "0" if no palette was found. Note that this -does not account for any palette index used by ancillary chunks such as the -bKGD chunk; you must check those separately to determine the maximum -palette index actually used. - -There are no substantial API changes between the non-deprecated parts of -the 1.4.5 API and the 1.5.0 API; however, the ability to directly access -members of the main libpng control structures, png_struct and png_info, -deprecated in earlier versions of libpng, has been completely removed from -libpng 1.5, and new private "pngstruct.h", "pnginfo.h", and "pngdebug.h" -header files were created. - -We no longer include zlib.h in png.h. The include statement has been moved -to pngstruct.h, where it is not accessible by applications. Applications that -need access to information in zlib.h will need to add the '#include "zlib.h"' -directive. It does not matter whether this is placed prior to or after -the '"#include png.h"' directive. - -The png_sprintf(), png_strcpy(), and png_strncpy() macros are no longer used -and were removed. - -We moved the png_strlen(), png_memcpy(), png_memset(), and png_memcmp() -macros into a private header file (pngpriv.h) that is not accessible to -applications. - -In png_get_iCCP, the type of "profile" was changed from png_charpp -to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep. - -There are changes of form in png.h, including new and changed macros to -declare parts of the API. Some API functions with arguments that are -pointers to data not modified within the function have been corrected to -declare these arguments with PNG_CONST. - -Much of the internal use of C macros to control the library build has also -changed and some of this is visible in the exported header files, in -particular the use of macros to control data and API elements visible -during application compilation may require significant revision to -application code. (It is extremely rare for an application to do this.) - -Any program that compiled against libpng 1.4 and did not use deprecated -features or access internal library structures should compile and work -against libpng 1.5, except for the change in the prototype for -png_get_iCCP() and png_set_iCCP() API functions mentioned above. - -libpng 1.5.0 adds PNG_ PASS macros to help in the reading and writing of -interlaced images. The macros return the number of rows and columns in -each pass and information that can be used to de-interlace and (if -absolutely necessary) interlace an image. - -libpng 1.5.0 adds an API png_longjmp(png_ptr, value). This API calls -the application-provided png_longjmp_ptr on the internal, but application -initialized, longjmp buffer. It is provided as a convenience to avoid -the need to use the png_jmpbuf macro, which had the unnecessary side -effect of resetting the internal png_longjmp_ptr value. - -libpng 1.5.0 includes a complete fixed point API. By default this is -present along with the corresponding floating point API. In general the -fixed point API is faster and smaller than the floating point one because -the PNG file format used fixed point, not floating point. This applies -even if the library uses floating point in internal calculations. A new -macro, PNG_FLOATING_ARITHMETIC_SUPPORTED, reveals whether the library -uses floating point arithmetic (the default) or fixed point arithmetic -internally for performance critical calculations such as gamma correction. -In some cases, the gamma calculations may produce slightly different -results. This has changed the results in png_rgb_to_gray and in alpha -composition (png_set_background for example). This applies even if the -original image was already linear (gamma == 1.0) and, therefore, it is -not necessary to linearize the image. This is because libpng has *not* -been changed to optimize that case correctly, yet. - -Fixed point support for the sCAL chunk comes with an important caveat; -the sCAL specification uses a decimal encoding of floating point values -and the accuracy of PNG fixed point values is insufficient for -representation of these values. Consequently a "string" API -(png_get_sCAL_s and png_set_sCAL_s) is the only reliable way of reading -arbitrary sCAL chunks in the absence of either the floating point API or -internal floating point calculations. Starting with libpng-1.5.0, both -of these functions are present when PNG_sCAL_SUPPORTED is defined. Prior -to libpng-1.5.0, their presence also depended upon PNG_FIXED_POINT_SUPPORTED -being defined and PNG_FLOATING_POINT_SUPPORTED not being defined. - -Applications no longer need to include the optional distribution header -file pngusr.h or define the corresponding macros during application -build in order to see the correct variant of the libpng API. From 1.5.0 -application code can check for the corresponding _SUPPORTED macro: - -#ifdef PNG_INCH_CONVERSIONS_SUPPORTED - /* code that uses the inch conversion APIs. */ -#endif - -This macro will only be defined if the inch conversion functions have been -compiled into libpng. The full set of macros, and whether or not support -has been compiled in, are available in the header file pnglibconf.h. -This header file is specific to the libpng build. Notice that prior to -1.5.0 the _SUPPORTED macros would always have the default definition unless -reset by pngusr.h or by explicit settings on the compiler command line. -These settings may produce compiler warnings or errors in 1.5.0 because -of macro redefinition. - -Applications can now choose whether to use these macros or to call the -corresponding function by defining PNG_USE_READ_MACROS or -PNG_NO_USE_READ_MACROS before including png.h. Notice that this is -only supported from 1.5.0; defining PNG_NO_USE_READ_MACROS prior to 1.5.0 -will lead to a link failure. - -Prior to libpng-1.5.4, the zlib compressor used the same set of parameters -when compressing the IDAT data and textual data such as zTXt and iCCP. -In libpng-1.5.4 we reinitialized the zlib stream for each type of data. -We added five png_set_text_*() functions for setting the parameters to -use with textual data. - -Prior to libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED -option was off by default, and slightly inaccurate scaling occurred. -This option can no longer be turned off, and the choice of accurate -or inaccurate 16-to-8 scaling is by using the new png_set_scale_16_to_8() -API for accurate scaling or the old png_set_strip_16_to_8() API for simple -chopping. In libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED -macro became PNG_READ_SCALE_16_TO_8_SUPPORTED, and the PNG_READ_16_TO_8 -macro became PNG_READ_STRIP_16_TO_8_SUPPORTED, to enable the two -png_set_*_16_to_8() functions separately. - -Prior to libpng-1.5.4, the png_set_user_limits() function could only be -used to reduce the width and height limits from the value of -PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said -that it could be used to override them. Now this function will reduce or -increase the limits. - -Starting in libpng-1.5.22, default user limits were established. These -can be overridden by application calls to png_set_user_limits(), -png_set_user_chunk_cache_max(), and/or png_set_user_malloc_max(). -The limits are now - max possible default - png_user_width_max 0x7fffffff 1,000,000 - png_user_height_max 0x7fffffff 1,000,000 - png_user_chunk_cache_max 0 (unlimited) 1000 - png_user_chunk_malloc_max 0 (unlimited) 8,000,000 - -The png_set_option() function (and the "options" member of the png struct) was -added to libpng-1.5.15, with option PNG_ARM_NEON. - -The library now supports a complete fixed point implementation and can -thus be used on systems that have no floating point support or very -limited or slow support. Previously gamma correction, an essential part -of complete PNG support, required reasonably fast floating point. - -As part of this the choice of internal implementation has been made -independent of the choice of fixed versus floating point APIs and all the -missing fixed point APIs have been implemented. - -The exact mechanism used to control attributes of API functions has -changed, as described in the INSTALL file. - -A new test program, pngvalid, is provided in addition to pngtest. -pngvalid validates the arithmetic accuracy of the gamma correction -calculations and includes a number of validations of the file format. -A subset of the full range of tests is run when "make check" is done -(in the 'configure' build.) pngvalid also allows total allocated memory -usage to be evaluated and performs additional memory overwrite validation. - -Many changes to individual feature macros have been made. The following -are the changes most likely to be noticed by library builders who -configure libpng: - -1) All feature macros now have consistent naming: - -#define PNG_NO_feature turns the feature off -#define PNG_feature_SUPPORTED turns the feature on - -pnglibconf.h contains one line for each feature macro which is either: - -#define PNG_feature_SUPPORTED - -if the feature is supported or: - -/*#undef PNG_feature_SUPPORTED*/ - -if it is not. Library code consistently checks for the 'SUPPORTED' macro. -It does not, and libpng applications should not, check for the 'NO' macro -which will not normally be defined even if the feature is not supported. -The 'NO' macros are only used internally for setting or not setting the -corresponding 'SUPPORTED' macros. - -Compatibility with the old names is provided as follows: - -PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED - -And the following definitions disable the corresponding feature: - -PNG_SETJMP_NOT_SUPPORTED disables SETJMP -PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS -PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV -PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS -PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS -PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS - -Library builders should remove use of the above, inconsistent, names. - -2) Warning and error message formatting was previously conditional on -the STDIO feature. The library has been changed to use the -CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled -the library no longer uses the printf(3) functions, even though the -default read/write implementations use (FILE) style stdio.h functions. - -3) Three feature macros now control the fixed/floating point decisions: - -PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs - -PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in -practice these are normally required internally anyway (because the PNG -file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT -merely stops the function from being exported. - -PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating -point implementation or the fixed point one. Typically the fixed point -implementation is larger and slower than the floating point implementation -on a system that supports floating point; however, it may be faster on a -system which lacks floating point hardware and therefore uses a software -emulation. - -4) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED. This allows the -functions to read and write ints to be disabled independently of -PNG_USE_READ_MACROS, which allows libpng to be built with the functions -even though the default is to use the macros - this allows applications -to choose at app buildtime whether or not to use macros (previously -impossible because the functions weren't in the default build.) - -XII. Changes to Libpng from version 1.5.x to 1.6.x - -A "simplified API" has been added (see documentation in png.h and a simple -example in contrib/examples/pngtopng.c). The new publicly visible API -includes the following: - - macros: - PNG_FORMAT_* - PNG_IMAGE_* - structures: - png_control - png_image - read functions - png_image_begin_read_from_file() - png_image_begin_read_from_stdio() - png_image_begin_read_from_memory() - png_image_finish_read() - png_image_free() - write functions - png_image_write_to_file() - png_image_write_to_memory() - png_image_write_to_stdio() - -Starting with libpng-1.6.0, you can configure libpng to prefix all exported -symbols, using the PNG_PREFIX macro. - -We no longer include string.h in png.h. The include statement has been moved -to pngpriv.h, where it is not accessible by applications. Applications that -need access to information in string.h must add an '#include <string.h>' -directive. It does not matter whether this is placed prior to or after -the '#include "png.h"' directive. - -The following API are now DEPRECATED: - png_info_init_3() - png_convert_to_rfc1123() which has been replaced - with png_convert_to_rfc1123_buffer() - png_malloc_default() - png_free_default() - png_reset_zstream() - -The following have been removed: - png_get_io_chunk_name(), which has been replaced - with png_get_io_chunk_type(). The new - function returns a 32-bit integer instead of - a string. - The png_sizeof(), png_strlen(), png_memcpy(), png_memcmp(), and - png_memset() macros are no longer used in the libpng sources and - have been removed. These had already been made invisible to applications - (i.e., defined in the private pngpriv.h header file) since libpng-1.5.0. - -The signatures of many exported functions were changed, such that - png_structp became png_structrp or png_const_structrp - png_infop became png_inforp or png_const_inforp -where "rp" indicates a "restricted pointer". - -Dropped support for 16-bit platforms. The support for FAR/far types has -been eliminated and the definition of png_alloc_size_t is now controlled -by a flag so that 'small size_t' systems can select it if necessary. - -Error detection in some chunks has improved; in particular the iCCP chunk -reader now does pretty complete validation of the basic format. Some bad -profiles that were previously accepted are now accepted with a warning or -rejected, depending upon the png_set_benign_errors() setting, in particular -the very old broken Microsoft/HP 3144-byte sRGB profile. Starting with -libpng-1.6.11, recognizing and checking sRGB profiles can be avoided by -means of - - #if defined(PNG_SKIP_sRGB_CHECK_PROFILE) && \ - defined(PNG_SET_OPTION_SUPPORTED) - png_set_option(png_ptr, PNG_SKIP_sRGB_CHECK_PROFILE, - PNG_OPTION_ON); - #endif - -It's not a good idea to do this if you are using the "simplified API", -which needs to be able to recognize sRGB profiles conveyed via the iCCP -chunk. - -The PNG spec requirement that only grayscale profiles may appear in images -with color type 0 or 4 and that even if the image only contains gray pixels, -only RGB profiles may appear in images with color type 2, 3, or 6, is now -enforced. The sRGB chunk is allowed to appear in images with any color type -and is interpreted by libpng to convey a one-tracer-curve gray profile or a -three-tracer-curve RGB profile as appropriate. - -Libpng 1.5.x erroneously used /MD for Debug DLL builds; if you used the debug -builds in your app and you changed your app to use /MD you will need to -change it back to /MDd for libpng 1.6.x. - -Prior to libpng-1.6.0 a warning would be issued if the iTXt chunk contained -an empty language field or an empty translated keyword. Both of these -are allowed by the PNG specification, so these warnings are no longer issued. - -The library now issues an error if the application attempts to set a -transform after it calls png_read_update_info() or if it attempts to call -both png_read_update_info() and png_start_read_image() or to call either -of them more than once. - -The default condition for benign_errors is now to treat benign errors as -warnings while reading and as errors while writing. - -The library now issues a warning if both background processing and RGB to -gray are used when gamma correction happens. As with previous versions of -the library the results are numerically very incorrect in this case. - -There are some minor arithmetic changes in some transforms such as -png_set_background(), that might be detected by certain regression tests. - -Unknown chunk handling has been improved internally, without any API change. -This adds more correct option control of the unknown handling, corrects -a pre-existing bug where the per-chunk 'keep' setting is ignored, and makes -it possible to skip IDAT chunks in the sequential reader. - -The machine-generated configure files are no longer included in branches -libpng16 and later of the GIT repository. They continue to be included -in the tarball releases, however. - -Libpng-1.6.0 through 1.6.2 used the CMF bytes at the beginning of the IDAT -stream to set the size of the sliding window for reading instead of using the -default 32-kbyte sliding window size. It was discovered that there are -hundreds of PNG files in the wild that have incorrect CMF bytes that caused -zlib to issue the "invalid distance too far back" error and reject the file. -Libpng-1.6.3 and later calculate their own safe CMF from the image dimensions, -provide a way to revert to the libpng-1.5.x behavior (ignoring the CMF bytes -and using a 32-kbyte sliding window), by using - - png_set_option(png_ptr, PNG_MAXIMUM_INFLATE_WINDOW, - PNG_OPTION_ON); - -and provide a tool (contrib/tools/pngfix) for rewriting a PNG file while -optimizing the CMF bytes in its IDAT chunk correctly. - -Libpng-1.6.0 and libpng-1.6.1 wrote uncompressed iTXt chunks with the wrong -length, which resulted in PNG files that cannot be read beyond the bad iTXt -chunk. This error was fixed in libpng-1.6.3, and a tool (called -contrib/tools/png-fix-itxt) has been added to the libpng distribution. - -Starting with libpng-1.6.17, the PNG_SAFE_LIMITS macro was eliminated -and safe limits are used by default (users who need larger limits -can still override them at compile time or run time, as described above). - -The new limits are - default spec limit - png_user_width_max 1,000,000 2,147,483,647 - png_user_height_max 1,000,000 2,147,483,647 - png_user_chunk_cache_max 128 unlimited - png_user_chunk_malloc_max 8,000,000 unlimited - -Starting with libpng-1.6.18, a PNG_RELEASE_BUILD macro was added, which allows -library builders to control compilation for an installed system (a release build). -It can be set for testing debug or beta builds to ensure that they will compile -when the build type is switched to RC or STABLE. In essence this overrides the -PNG_LIBPNG_BUILD_BASE_TYPE definition which is not directly user controllable. - -Starting with libpng-1.6.19, attempting to set an over-length PLTE chunk -is an error. Previously this requirement of the PNG specification was not -enforced, and the palette was always limited to 256 entries. An over-length -PLTE chunk found in an input PNG is silently truncated. - -Starting with libpng-1.6.31, the eXIf chunk is supported. Libpng does not -attempt to decode the Exif profile; it simply returns a byte array -containing the profile to the calling application which must do its own -decoding. - -XIII. Detecting libpng - -The png_get_io_ptr() function has been present since libpng-0.88, has never -changed, and is unaffected by conditional compilation macros. It is the -best choice for use in configure scripts for detecting the presence of any -libpng version since 0.88. In an autoconf "configure.in" you could use - - AC_CHECK_LIB(png, png_get_io_ptr, ... - -XV. Source code repository - -Since about February 2009, version 1.2.34, libpng has been under "git" source -control. The git repository was built from old libpng-x.y.z.tar.gz files -going back to version 0.70. You can access the git repository (read only) -at - - https://github.com/glennrp/libpng or - https://git.code.sf.net/p/libpng/code.git - -or you can browse it with a web browser at - - https://github.com/glennrp/libpng or - https://sourceforge.net/p/libpng/code/ci/libpng16/tree/ - -Patches can be sent to glennrp at users.sourceforge.net or to -png-mng-implement at lists.sourceforge.net or you can upload them to -the libpng bug tracker at - - https://libpng.sourceforge.io/ - -or as a "pull request" to - - https://github.com/glennrp/libpng/pulls - -We also accept patches built from the tar or zip distributions, and -simple verbal discriptions of bug fixes, reported either to the -SourceForge bug tracker, to the png-mng-implement at lists.sf.net -mailing list, as github issues, or directly to glennrp. - -XV. Coding style - -Our coding style is similar to the "Allman" style -(See https://en.wikipedia.org/wiki/Indent_style#Allman_style), with curly -braces on separate lines: - - if (condition) - { - action; - } - - else if (another condition) - { - another action; - } - -The braces can be omitted from simple one-line actions: - - if (condition) - return (0); - -We use 3-space indentation, except for continued statements which -are usually indented the same as the first line of the statement -plus four more spaces. - -For macro definitions we use 2-space indentation, always leaving the "#" -in the first column. - - #ifndef PNG_NO_FEATURE - # ifndef PNG_FEATURE_SUPPORTED - # define PNG_FEATURE_SUPPORTED - # endif - #endif - -Comments appear with the leading "/*" at the same indentation as -the statement that follows the comment: - - /* Single-line comment */ - statement; - - /* This is a multiple-line - * comment. - */ - statement; - -Very short comments can be placed after the end of the statement -to which they pertain: - - statement; /* comment */ - -We don't use C++ style ("//") comments. We have, however, -used them in the past in some now-abandoned MMX assembler -code. - -Functions and their curly braces are not indented, and -exported functions are marked with PNGAPI: - - /* This is a public function that is visible to - * application programmers. It does thus-and-so. - */ - void PNGAPI - png_exported_function(png_ptr, png_info, foo) - { - body; - } - -The return type and decorations are placed on a separate line -ahead of the function name, as illustrated above. - -The prototypes for all exported functions appear in png.h, -above the comment that says - - /* Maintainer: Put new public prototypes here ... */ - -We mark all non-exported functions with "/* PRIVATE */"": - - void /* PRIVATE */ - png_non_exported_function(png_ptr, png_info, foo) - { - body; - } - -The prototypes for non-exported functions (except for those in -pngtest) appear in pngpriv.h above the comment that says - - /* Maintainer: Put new private prototypes here ^ */ - -To avoid polluting the global namespace, the names of all exported -functions and variables begin with "png_", and all publicly visible C -preprocessor macros begin with "PNG". We request that applications that -use libpng *not* begin any of their own symbols with either of these strings. - -We put a space after the "sizeof" operator and we omit the -optional parentheses around its argument when the argument -is an expression, not a type name, and we always enclose the -sizeof operator, with its argument, in parentheses: - - (sizeof (png_uint_32)) - (sizeof array) - -Prior to libpng-1.6.0 we used a "png_sizeof()" macro, formatted as -though it were a function. - -Control keywords if, for, while, and switch are always followed by a space -to distinguish them from function calls, which have no trailing space. - -We put a space after each comma and after each semicolon -in "for" statements, and we put spaces before and after each -C binary operator and after "for" or "while", and before -"?". We don't put a space between a typecast and the expression -being cast, nor do we put one between a function name and the -left parenthesis that follows it: - - for (i = 2; i > 0; --i) - y[i] = a(x) + (int)b; - -We prefer #ifdef and #ifndef to #if defined() and #if !defined() -when there is only one macro being tested. We always use parentheses -with "defined". - -We express integer constants that are used as bit masks in hex format, -with an even number of lower-case hex digits, and to make them unsigned -(e.g., 0x00U, 0xffU, 0x0100U) and long if they are greater than 0x7fff -(e.g., 0xffffUL). - -We prefer to use underscores rather than camelCase in names, except -for a few type names that we inherit from zlib.h. - -We prefer "if (something != 0)" and "if (something == 0)" over -"if (something)" and if "(!something)", respectively, and for pointers -we prefer "if (some_pointer != NULL)" or "if (some_pointer == NULL)". - -We do not use the TAB character for indentation in the C sources. - -Lines do not exceed 80 characters. - -Other rules can be inferred by inspecting the libpng source. - -XVI. Y2K Compliance in libpng - -Since the PNG Development group is an ad-hoc body, we can't make -an official declaration. - -This is your unofficial assurance that libpng from version 0.71 and -upward through 1.6.34 are Y2K compliant. It is my belief that earlier -versions were also Y2K compliant. - -Libpng only has two year fields. One is a 2-byte unsigned integer -that will hold years up to 65535. The other, which is deprecated, -holds the date in text format, and will hold years up to 9999. - -The integer is - "png_uint_16 year" in png_time_struct. - -The string is - "char time_buffer[29]" in png_struct. This is no longer used -in libpng-1.6.x and will be removed from libpng-1.7.0. - -There are seven time-related functions: - - png_convert_to_rfc_1123_buffer() in png.c - (formerly png_convert_to_rfc_1152() in error, and - also formerly png_convert_to_rfc_1123()) - png_convert_from_struct_tm() in pngwrite.c, called - in pngwrite.c - png_convert_from_time_t() in pngwrite.c - png_get_tIME() in pngget.c - png_handle_tIME() in pngrutil.c, called in pngread.c - png_set_tIME() in pngset.c - png_write_tIME() in pngwutil.c, called in pngwrite.c - -All appear to handle dates properly in a Y2K environment. The -png_convert_from_time_t() function calls gmtime() to convert from system -clock time, which returns (year - 1900), which we properly convert to -the full 4-digit year. There is a possibility that applications using -libpng are not passing 4-digit years into the png_convert_to_rfc_1123() -function, or that they are incorrectly passing only a 2-digit year -instead of "year - 1900" into the png_convert_from_struct_tm() function, -but this is not under our control. The libpng documentation has always -stated that it works with 4-digit years, and the APIs have been -documented as such. - -The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned -integer to hold the year, and can hold years as large as 65535. - -zlib, upon which libpng depends, is also Y2K compliant. It contains -no date-related code. - - - Glenn Randers-Pehrson - libpng maintainer - PNG Development Group diff --git a/libs/liblua/docs/contents.html b/libs/liblua/docs/contents.html deleted file mode 100644 index c4eb267790..0000000000 --- a/libs/liblua/docs/contents.html +++ /dev/null @@ -1,619 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<HTML> -<HEAD> -<TITLE>Lua 5.3 Reference Manual - contents</TITLE> -<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> -<LINK REL="stylesheet" TYPE="text/css" HREF="index.css"> -<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> -</HEAD> - -<BODY> - -<H1> -<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> -Lua 5.3 Reference Manual -</H1> - -<P> -The reference manual is the official definition of the Lua language. -<BR> -For a complete introduction to Lua programming, see the book -<A HREF="http://www.lua.org/pil/">Programming in Lua</A>. - -<DIV CLASS="menubar"> -<A HREF="manual.html">start</A> -· -<A HREF="#contents">contents</A> -· -<A HREF="#index">index</A> -· -<A HREF="http://www.lua.org/manual/">other versions</A> -</DIV> - -<P> -<SMALL> -Copyright © 2015–2018 Lua.org, PUC-Rio. -Freely available under the terms of the -<A HREF="http://www.lua.org/license.html">Lua license</A>. -</SMALL> - -<H2><A NAME="contents">Contents</A></H2> -<UL CLASS="contents menubar"> -<LI><A HREF="manual.html">1 – Introduction</A> -<P> -<LI><A HREF="manual.html#2">2 – Basic Concepts</A> -<UL> -<LI><A HREF="manual.html#2.1">2.1 – Values and Types</A> -<LI><A HREF="manual.html#2.2">2.2 – Environments and the Global Environment</A> -<LI><A HREF="manual.html#2.3">2.3 – Error Handling</A> -<LI><A HREF="manual.html#2.4">2.4 – Metatables and Metamethods</A> -<LI><A HREF="manual.html#2.5">2.5 – Garbage Collection</A> -<UL> -<LI><A HREF="manual.html#2.5.1">2.5.1 – Garbage-Collection Metamethods</A> -<LI><A HREF="manual.html#2.5.2">2.5.2 – Weak Tables</A> -</UL> -<LI><A HREF="manual.html#2.6">2.6 – Coroutines</A> -</UL> -<P> -<LI><A HREF="manual.html#3">3 – The Language</A> -<UL> -<LI><A HREF="manual.html#3.1">3.1 – Lexical Conventions</A> -<LI><A HREF="manual.html#3.2">3.2 – Variables</A> -<LI><A HREF="manual.html#3.3">3.3 – Statements</A> -<UL> -<LI><A HREF="manual.html#3.3.1">3.3.1 – Blocks</A> -<LI><A HREF="manual.html#3.3.2">3.3.2 – Chunks</A> -<LI><A HREF="manual.html#3.3.3">3.3.3 – Assignment</A> -<LI><A HREF="manual.html#3.3.4">3.3.4 – Control Structures</A> -<LI><A HREF="manual.html#3.3.5">3.3.5 – For Statement</A> -<LI><A HREF="manual.html#3.3.6">3.3.6 – Function Calls as Statements</A> -<LI><A HREF="manual.html#3.3.7">3.3.7 – Local Declarations</A> -</UL> -<LI><A HREF="manual.html#3.4">3.4 – Expressions</A> -<UL> -<LI><A HREF="manual.html#3.4.1">3.4.1 – Arithmetic Operators</A> -<LI><A HREF="manual.html#3.4.2">3.4.2 – Bitwise Operators</A> -<LI><A HREF="manual.html#3.4.3">3.4.3 – Coercions and Conversions</A> -<LI><A HREF="manual.html#3.4.4">3.4.4 – Relational Operators</A> -<LI><A HREF="manual.html#3.4.5">3.4.5 – Logical Operators</A> -<LI><A HREF="manual.html#3.4.6">3.4.6 – Concatenation</A> -<LI><A HREF="manual.html#3.4.7">3.4.7 – The Length Operator</A> -<LI><A HREF="manual.html#3.4.8">3.4.8 – Precedence</A> -<LI><A HREF="manual.html#3.4.9">3.4.9 – Table Constructors</A> -<LI><A HREF="manual.html#3.4.10">3.4.10 – Function Calls</A> -<LI><A HREF="manual.html#3.4.11">3.4.11 – Function Definitions</A> -</UL> -<LI><A HREF="manual.html#3.5">3.5 – Visibility Rules</A> -</UL> -<P> -<LI><A HREF="manual.html#4">4 – The Application Program Interface</A> -<UL> -<LI><A HREF="manual.html#4.1">4.1 – The Stack</A> -<LI><A HREF="manual.html#4.2">4.2 – Stack Size</A> -<LI><A HREF="manual.html#4.3">4.3 – Valid and Acceptable Indices</A> -<LI><A HREF="manual.html#4.4">4.4 – C Closures</A> -<LI><A HREF="manual.html#4.5">4.5 – Registry</A> -<LI><A HREF="manual.html#4.6">4.6 – Error Handling in C</A> -<LI><A HREF="manual.html#4.7">4.7 – Handling Yields in C</A> -<LI><A HREF="manual.html#4.8">4.8 – Functions and Types</A> -<LI><A HREF="manual.html#4.9">4.9 – The Debug Interface</A> -</UL> -<P> -<LI><A HREF="manual.html#5">5 – The Auxiliary Library</A> -<UL> -<LI><A HREF="manual.html#5.1">5.1 – Functions and Types</A> -</UL> -<P> -<LI><A HREF="manual.html#6">6 – Standard Libraries</A> -<UL> -<LI><A HREF="manual.html#6.1">6.1 – Basic Functions</A> -<LI><A HREF="manual.html#6.2">6.2 – Coroutine Manipulation</A> -<LI><A HREF="manual.html#6.3">6.3 – Modules</A> -<LI><A HREF="manual.html#6.4">6.4 – String Manipulation</A> -<UL> -<LI><A HREF="manual.html#6.4.1">6.4.1 – Patterns</A> -<LI><A HREF="manual.html#6.4.2">6.4.2 – Format Strings for Pack and Unpack</A> -</UL> -<LI><A HREF="manual.html#6.5">6.5 – UTF-8 Support</A> -<LI><A HREF="manual.html#6.6">6.6 – Table Manipulation</A> -<LI><A HREF="manual.html#6.7">6.7 – Mathematical Functions</A> -<LI><A HREF="manual.html#6.8">6.8 – Input and Output Facilities</A> -<LI><A HREF="manual.html#6.9">6.9 – Operating System Facilities</A> -<LI><A HREF="manual.html#6.10">6.10 – The Debug Library</A> -</UL> -<P> -<LI><A HREF="manual.html#7">7 – Lua Standalone</A> -<P> -<LI><A HREF="manual.html#8">8 – Incompatibilities with the Previous Version</A> -<UL> -<LI><A HREF="manual.html#8.1">8.1 – Changes in the Language</A> -<LI><A HREF="manual.html#8.2">8.2 – Changes in the Libraries</A> -<LI><A HREF="manual.html#8.3">8.3 – Changes in the API</A> -</UL> -<P> -<LI><A HREF="manual.html#9">9 – The Complete Syntax of Lua</A> -</UL> - -<H2><A NAME="index">Index</A></H2> -<TABLE CLASS="menubar" WIDTH="100%"> -<TR> -<TD> -<H3><A NAME="functions">Lua functions</A></H3> -<P> -<A HREF="manual.html#6.1">basic</A><BR> -<A HREF="manual.html#pdf-_G">_G</A><BR> -<A HREF="manual.html#pdf-_VERSION">_VERSION</A><BR> -<A HREF="manual.html#pdf-assert">assert</A><BR> -<A HREF="manual.html#pdf-collectgarbage">collectgarbage</A><BR> -<A HREF="manual.html#pdf-dofile">dofile</A><BR> -<A HREF="manual.html#pdf-error">error</A><BR> -<A HREF="manual.html#pdf-getmetatable">getmetatable</A><BR> -<A HREF="manual.html#pdf-ipairs">ipairs</A><BR> -<A HREF="manual.html#pdf-load">load</A><BR> -<A HREF="manual.html#pdf-loadfile">loadfile</A><BR> -<A HREF="manual.html#pdf-next">next</A><BR> -<A HREF="manual.html#pdf-pairs">pairs</A><BR> -<A HREF="manual.html#pdf-pcall">pcall</A><BR> -<A HREF="manual.html#pdf-print">print</A><BR> -<A HREF="manual.html#pdf-rawequal">rawequal</A><BR> -<A HREF="manual.html#pdf-rawget">rawget</A><BR> -<A HREF="manual.html#pdf-rawlen">rawlen</A><BR> -<A HREF="manual.html#pdf-rawset">rawset</A><BR> -<A HREF="manual.html#pdf-require">require</A><BR> -<A HREF="manual.html#pdf-select">select</A><BR> -<A HREF="manual.html#pdf-setmetatable">setmetatable</A><BR> -<A HREF="manual.html#pdf-tonumber">tonumber</A><BR> -<A HREF="manual.html#pdf-tostring">tostring</A><BR> -<A HREF="manual.html#pdf-type">type</A><BR> -<A HREF="manual.html#pdf-xpcall">xpcall</A><BR> - -<P> -<A HREF="manual.html#6.2">coroutine</A><BR> -<A HREF="manual.html#pdf-coroutine.create">coroutine.create</A><BR> -<A HREF="manual.html#pdf-coroutine.isyieldable">coroutine.isyieldable</A><BR> -<A HREF="manual.html#pdf-coroutine.resume">coroutine.resume</A><BR> -<A HREF="manual.html#pdf-coroutine.running">coroutine.running</A><BR> -<A HREF="manual.html#pdf-coroutine.status">coroutine.status</A><BR> -<A HREF="manual.html#pdf-coroutine.wrap">coroutine.wrap</A><BR> -<A HREF="manual.html#pdf-coroutine.yield">coroutine.yield</A><BR> - -<P> -<A HREF="manual.html#6.10">debug</A><BR> -<A HREF="manual.html#pdf-debug.debug">debug.debug</A><BR> -<A HREF="manual.html#pdf-debug.gethook">debug.gethook</A><BR> -<A HREF="manual.html#pdf-debug.getinfo">debug.getinfo</A><BR> -<A HREF="manual.html#pdf-debug.getlocal">debug.getlocal</A><BR> -<A HREF="manual.html#pdf-debug.getmetatable">debug.getmetatable</A><BR> -<A HREF="manual.html#pdf-debug.getregistry">debug.getregistry</A><BR> -<A HREF="manual.html#pdf-debug.getupvalue">debug.getupvalue</A><BR> -<A HREF="manual.html#pdf-debug.getuservalue">debug.getuservalue</A><BR> -<A HREF="manual.html#pdf-debug.sethook">debug.sethook</A><BR> -<A HREF="manual.html#pdf-debug.setlocal">debug.setlocal</A><BR> -<A HREF="manual.html#pdf-debug.setmetatable">debug.setmetatable</A><BR> -<A HREF="manual.html#pdf-debug.setupvalue">debug.setupvalue</A><BR> -<A HREF="manual.html#pdf-debug.setuservalue">debug.setuservalue</A><BR> -<A HREF="manual.html#pdf-debug.traceback">debug.traceback</A><BR> -<A HREF="manual.html#pdf-debug.upvalueid">debug.upvalueid</A><BR> -<A HREF="manual.html#pdf-debug.upvaluejoin">debug.upvaluejoin</A><BR> - -<P> -<A HREF="manual.html#6.8">io</A><BR> -<A HREF="manual.html#pdf-io.close">io.close</A><BR> -<A HREF="manual.html#pdf-io.flush">io.flush</A><BR> -<A HREF="manual.html#pdf-io.input">io.input</A><BR> -<A HREF="manual.html#pdf-io.lines">io.lines</A><BR> -<A HREF="manual.html#pdf-io.open">io.open</A><BR> -<A HREF="manual.html#pdf-io.output">io.output</A><BR> -<A HREF="manual.html#pdf-io.popen">io.popen</A><BR> -<A HREF="manual.html#pdf-io.read">io.read</A><BR> -<A HREF="manual.html#pdf-io.stderr">io.stderr</A><BR> -<A HREF="manual.html#pdf-io.stdin">io.stdin</A><BR> -<A HREF="manual.html#pdf-io.stdout">io.stdout</A><BR> -<A HREF="manual.html#pdf-io.tmpfile">io.tmpfile</A><BR> -<A HREF="manual.html#pdf-io.type">io.type</A><BR> -<A HREF="manual.html#pdf-io.write">io.write</A><BR> - -<A HREF="manual.html#pdf-file:close">file:close</A><BR> -<A HREF="manual.html#pdf-file:flush">file:flush</A><BR> -<A HREF="manual.html#pdf-file:lines">file:lines</A><BR> -<A HREF="manual.html#pdf-file:read">file:read</A><BR> -<A HREF="manual.html#pdf-file:seek">file:seek</A><BR> -<A HREF="manual.html#pdf-file:setvbuf">file:setvbuf</A><BR> -<A HREF="manual.html#pdf-file:write">file:write</A><BR> - -</TD> -<TD> -<H3> </H3> -<P> -<A HREF="manual.html#6.7">math</A><BR> -<A HREF="manual.html#pdf-math.abs">math.abs</A><BR> -<A HREF="manual.html#pdf-math.acos">math.acos</A><BR> -<A HREF="manual.html#pdf-math.asin">math.asin</A><BR> -<A HREF="manual.html#pdf-math.atan">math.atan</A><BR> -<A HREF="manual.html#pdf-math.ceil">math.ceil</A><BR> -<A HREF="manual.html#pdf-math.cos">math.cos</A><BR> -<A HREF="manual.html#pdf-math.deg">math.deg</A><BR> -<A HREF="manual.html#pdf-math.exp">math.exp</A><BR> -<A HREF="manual.html#pdf-math.floor">math.floor</A><BR> -<A HREF="manual.html#pdf-math.fmod">math.fmod</A><BR> -<A HREF="manual.html#pdf-math.huge">math.huge</A><BR> -<A HREF="manual.html#pdf-math.log">math.log</A><BR> -<A HREF="manual.html#pdf-math.max">math.max</A><BR> -<A HREF="manual.html#pdf-math.maxinteger">math.maxinteger</A><BR> -<A HREF="manual.html#pdf-math.min">math.min</A><BR> -<A HREF="manual.html#pdf-math.mininteger">math.mininteger</A><BR> -<A HREF="manual.html#pdf-math.modf">math.modf</A><BR> -<A HREF="manual.html#pdf-math.pi">math.pi</A><BR> -<A HREF="manual.html#pdf-math.rad">math.rad</A><BR> -<A HREF="manual.html#pdf-math.random">math.random</A><BR> -<A HREF="manual.html#pdf-math.randomseed">math.randomseed</A><BR> -<A HREF="manual.html#pdf-math.sin">math.sin</A><BR> -<A HREF="manual.html#pdf-math.sqrt">math.sqrt</A><BR> -<A HREF="manual.html#pdf-math.tan">math.tan</A><BR> -<A HREF="manual.html#pdf-math.tointeger">math.tointeger</A><BR> -<A HREF="manual.html#pdf-math.type">math.type</A><BR> -<A HREF="manual.html#pdf-math.ult">math.ult</A><BR> - -<P> -<A HREF="manual.html#6.9">os</A><BR> -<A HREF="manual.html#pdf-os.clock">os.clock</A><BR> -<A HREF="manual.html#pdf-os.date">os.date</A><BR> -<A HREF="manual.html#pdf-os.difftime">os.difftime</A><BR> -<A HREF="manual.html#pdf-os.execute">os.execute</A><BR> -<A HREF="manual.html#pdf-os.exit">os.exit</A><BR> -<A HREF="manual.html#pdf-os.getenv">os.getenv</A><BR> -<A HREF="manual.html#pdf-os.remove">os.remove</A><BR> -<A HREF="manual.html#pdf-os.rename">os.rename</A><BR> -<A HREF="manual.html#pdf-os.setlocale">os.setlocale</A><BR> -<A HREF="manual.html#pdf-os.time">os.time</A><BR> -<A HREF="manual.html#pdf-os.tmpname">os.tmpname</A><BR> - -<P> -<A HREF="manual.html#6.3">package</A><BR> -<A HREF="manual.html#pdf-package.config">package.config</A><BR> -<A HREF="manual.html#pdf-package.cpath">package.cpath</A><BR> -<A HREF="manual.html#pdf-package.loaded">package.loaded</A><BR> -<A HREF="manual.html#pdf-package.loadlib">package.loadlib</A><BR> -<A HREF="manual.html#pdf-package.path">package.path</A><BR> -<A HREF="manual.html#pdf-package.preload">package.preload</A><BR> -<A HREF="manual.html#pdf-package.searchers">package.searchers</A><BR> -<A HREF="manual.html#pdf-package.searchpath">package.searchpath</A><BR> - -<P> -<A HREF="manual.html#6.4">string</A><BR> -<A HREF="manual.html#pdf-string.byte">string.byte</A><BR> -<A HREF="manual.html#pdf-string.char">string.char</A><BR> -<A HREF="manual.html#pdf-string.dump">string.dump</A><BR> -<A HREF="manual.html#pdf-string.find">string.find</A><BR> -<A HREF="manual.html#pdf-string.format">string.format</A><BR> -<A HREF="manual.html#pdf-string.gmatch">string.gmatch</A><BR> -<A HREF="manual.html#pdf-string.gsub">string.gsub</A><BR> -<A HREF="manual.html#pdf-string.len">string.len</A><BR> -<A HREF="manual.html#pdf-string.lower">string.lower</A><BR> -<A HREF="manual.html#pdf-string.match">string.match</A><BR> -<A HREF="manual.html#pdf-string.pack">string.pack</A><BR> -<A HREF="manual.html#pdf-string.packsize">string.packsize</A><BR> -<A HREF="manual.html#pdf-string.rep">string.rep</A><BR> -<A HREF="manual.html#pdf-string.reverse">string.reverse</A><BR> -<A HREF="manual.html#pdf-string.sub">string.sub</A><BR> -<A HREF="manual.html#pdf-string.unpack">string.unpack</A><BR> -<A HREF="manual.html#pdf-string.upper">string.upper</A><BR> - -<P> -<A HREF="manual.html#6.6">table</A><BR> -<A HREF="manual.html#pdf-table.concat">table.concat</A><BR> -<A HREF="manual.html#pdf-table.insert">table.insert</A><BR> -<A HREF="manual.html#pdf-table.move">table.move</A><BR> -<A HREF="manual.html#pdf-table.pack">table.pack</A><BR> -<A HREF="manual.html#pdf-table.remove">table.remove</A><BR> -<A HREF="manual.html#pdf-table.sort">table.sort</A><BR> -<A HREF="manual.html#pdf-table.unpack">table.unpack</A><BR> - -<P> -<A HREF="manual.html#6.5">utf8</A><BR> -<A HREF="manual.html#pdf-utf8.char">utf8.char</A><BR> -<A HREF="manual.html#pdf-utf8.charpattern">utf8.charpattern</A><BR> -<A HREF="manual.html#pdf-utf8.codepoint">utf8.codepoint</A><BR> -<A HREF="manual.html#pdf-utf8.codes">utf8.codes</A><BR> -<A HREF="manual.html#pdf-utf8.len">utf8.len</A><BR> -<A HREF="manual.html#pdf-utf8.offset">utf8.offset</A><BR> - -<H3><A NAME="env">environment<BR>variables</A></H3> -<P> -<A HREF="manual.html#pdf-LUA_CPATH">LUA_CPATH</A><BR> -<A HREF="manual.html#pdf-LUA_CPATH_5_3">LUA_CPATH_5_3</A><BR> -<A HREF="manual.html#pdf-LUA_INIT">LUA_INIT</A><BR> -<A HREF="manual.html#pdf-LUA_INIT_5_3">LUA_INIT_5_3</A><BR> -<A HREF="manual.html#pdf-LUA_PATH">LUA_PATH</A><BR> -<A HREF="manual.html#pdf-LUA_PATH_5_3">LUA_PATH_5_3</A><BR> - -</TD> -<TD> -<H3><A NAME="api">C API</A></H3> -<P> -<A HREF="manual.html#lua_Alloc">lua_Alloc</A><BR> -<A HREF="manual.html#lua_CFunction">lua_CFunction</A><BR> -<A HREF="manual.html#lua_Debug">lua_Debug</A><BR> -<A HREF="manual.html#lua_Hook">lua_Hook</A><BR> -<A HREF="manual.html#lua_Integer">lua_Integer</A><BR> -<A HREF="manual.html#lua_KContext">lua_KContext</A><BR> -<A HREF="manual.html#lua_KFunction">lua_KFunction</A><BR> -<A HREF="manual.html#lua_Number">lua_Number</A><BR> -<A HREF="manual.html#lua_Reader">lua_Reader</A><BR> -<A HREF="manual.html#lua_State">lua_State</A><BR> -<A HREF="manual.html#lua_Unsigned">lua_Unsigned</A><BR> -<A HREF="manual.html#lua_Writer">lua_Writer</A><BR> - -<P> -<A HREF="manual.html#lua_absindex">lua_absindex</A><BR> -<A HREF="manual.html#lua_arith">lua_arith</A><BR> -<A HREF="manual.html#lua_atpanic">lua_atpanic</A><BR> -<A HREF="manual.html#lua_call">lua_call</A><BR> -<A HREF="manual.html#lua_callk">lua_callk</A><BR> -<A HREF="manual.html#lua_checkstack">lua_checkstack</A><BR> -<A HREF="manual.html#lua_close">lua_close</A><BR> -<A HREF="manual.html#lua_compare">lua_compare</A><BR> -<A HREF="manual.html#lua_concat">lua_concat</A><BR> -<A HREF="manual.html#lua_copy">lua_copy</A><BR> -<A HREF="manual.html#lua_createtable">lua_createtable</A><BR> -<A HREF="manual.html#lua_dump">lua_dump</A><BR> -<A HREF="manual.html#lua_error">lua_error</A><BR> -<A HREF="manual.html#lua_gc">lua_gc</A><BR> -<A HREF="manual.html#lua_getallocf">lua_getallocf</A><BR> -<A HREF="manual.html#lua_getextraspace">lua_getextraspace</A><BR> -<A HREF="manual.html#lua_getfield">lua_getfield</A><BR> -<A HREF="manual.html#lua_getglobal">lua_getglobal</A><BR> -<A HREF="manual.html#lua_gethook">lua_gethook</A><BR> -<A HREF="manual.html#lua_gethookcount">lua_gethookcount</A><BR> -<A HREF="manual.html#lua_gethookmask">lua_gethookmask</A><BR> -<A HREF="manual.html#lua_geti">lua_geti</A><BR> -<A HREF="manual.html#lua_getinfo">lua_getinfo</A><BR> -<A HREF="manual.html#lua_getlocal">lua_getlocal</A><BR> -<A HREF="manual.html#lua_getmetatable">lua_getmetatable</A><BR> -<A HREF="manual.html#lua_getstack">lua_getstack</A><BR> -<A HREF="manual.html#lua_gettable">lua_gettable</A><BR> -<A HREF="manual.html#lua_gettop">lua_gettop</A><BR> -<A HREF="manual.html#lua_getupvalue">lua_getupvalue</A><BR> -<A HREF="manual.html#lua_getuservalue">lua_getuservalue</A><BR> -<A HREF="manual.html#lua_insert">lua_insert</A><BR> -<A HREF="manual.html#lua_isboolean">lua_isboolean</A><BR> -<A HREF="manual.html#lua_iscfunction">lua_iscfunction</A><BR> -<A HREF="manual.html#lua_isfunction">lua_isfunction</A><BR> -<A HREF="manual.html#lua_isinteger">lua_isinteger</A><BR> -<A HREF="manual.html#lua_islightuserdata">lua_islightuserdata</A><BR> -<A HREF="manual.html#lua_isnil">lua_isnil</A><BR> -<A HREF="manual.html#lua_isnone">lua_isnone</A><BR> -<A HREF="manual.html#lua_isnoneornil">lua_isnoneornil</A><BR> -<A HREF="manual.html#lua_isnumber">lua_isnumber</A><BR> -<A HREF="manual.html#lua_isstring">lua_isstring</A><BR> -<A HREF="manual.html#lua_istable">lua_istable</A><BR> -<A HREF="manual.html#lua_isthread">lua_isthread</A><BR> -<A HREF="manual.html#lua_isuserdata">lua_isuserdata</A><BR> -<A HREF="manual.html#lua_isyieldable">lua_isyieldable</A><BR> -<A HREF="manual.html#lua_len">lua_len</A><BR> -<A HREF="manual.html#lua_load">lua_load</A><BR> -<A HREF="manual.html#lua_newstate">lua_newstate</A><BR> -<A HREF="manual.html#lua_newtable">lua_newtable</A><BR> -<A HREF="manual.html#lua_newthread">lua_newthread</A><BR> -<A HREF="manual.html#lua_newuserdata">lua_newuserdata</A><BR> -<A HREF="manual.html#lua_next">lua_next</A><BR> -<A HREF="manual.html#lua_numbertointeger">lua_numbertointeger</A><BR> -<A HREF="manual.html#lua_pcall">lua_pcall</A><BR> -<A HREF="manual.html#lua_pcallk">lua_pcallk</A><BR> -<A HREF="manual.html#lua_pop">lua_pop</A><BR> -<A HREF="manual.html#lua_pushboolean">lua_pushboolean</A><BR> -<A HREF="manual.html#lua_pushcclosure">lua_pushcclosure</A><BR> -<A HREF="manual.html#lua_pushcfunction">lua_pushcfunction</A><BR> -<A HREF="manual.html#lua_pushfstring">lua_pushfstring</A><BR> -<A HREF="manual.html#lua_pushglobaltable">lua_pushglobaltable</A><BR> -<A HREF="manual.html#lua_pushinteger">lua_pushinteger</A><BR> -<A HREF="manual.html#lua_pushlightuserdata">lua_pushlightuserdata</A><BR> -<A HREF="manual.html#lua_pushliteral">lua_pushliteral</A><BR> -<A HREF="manual.html#lua_pushlstring">lua_pushlstring</A><BR> -<A HREF="manual.html#lua_pushnil">lua_pushnil</A><BR> -<A HREF="manual.html#lua_pushnumber">lua_pushnumber</A><BR> -<A HREF="manual.html#lua_pushstring">lua_pushstring</A><BR> -<A HREF="manual.html#lua_pushthread">lua_pushthread</A><BR> -<A HREF="manual.html#lua_pushvalue">lua_pushvalue</A><BR> -<A HREF="manual.html#lua_pushvfstring">lua_pushvfstring</A><BR> -<A HREF="manual.html#lua_rawequal">lua_rawequal</A><BR> -<A HREF="manual.html#lua_rawget">lua_rawget</A><BR> -<A HREF="manual.html#lua_rawgeti">lua_rawgeti</A><BR> -<A HREF="manual.html#lua_rawgetp">lua_rawgetp</A><BR> -<A HREF="manual.html#lua_rawlen">lua_rawlen</A><BR> -<A HREF="manual.html#lua_rawset">lua_rawset</A><BR> -<A HREF="manual.html#lua_rawseti">lua_rawseti</A><BR> -<A HREF="manual.html#lua_rawsetp">lua_rawsetp</A><BR> -<A HREF="manual.html#lua_register">lua_register</A><BR> -<A HREF="manual.html#lua_remove">lua_remove</A><BR> -<A HREF="manual.html#lua_replace">lua_replace</A><BR> -<A HREF="manual.html#lua_resume">lua_resume</A><BR> -<A HREF="manual.html#lua_rotate">lua_rotate</A><BR> -<A HREF="manual.html#lua_setallocf">lua_setallocf</A><BR> -<A HREF="manual.html#lua_setfield">lua_setfield</A><BR> -<A HREF="manual.html#lua_setglobal">lua_setglobal</A><BR> -<A HREF="manual.html#lua_sethook">lua_sethook</A><BR> -<A HREF="manual.html#lua_seti">lua_seti</A><BR> -<A HREF="manual.html#lua_setlocal">lua_setlocal</A><BR> -<A HREF="manual.html#lua_setmetatable">lua_setmetatable</A><BR> -<A HREF="manual.html#lua_settable">lua_settable</A><BR> -<A HREF="manual.html#lua_settop">lua_settop</A><BR> -<A HREF="manual.html#lua_setupvalue">lua_setupvalue</A><BR> -<A HREF="manual.html#lua_setuservalue">lua_setuservalue</A><BR> -<A HREF="manual.html#lua_status">lua_status</A><BR> -<A HREF="manual.html#lua_stringtonumber">lua_stringtonumber</A><BR> -<A HREF="manual.html#lua_toboolean">lua_toboolean</A><BR> -<A HREF="manual.html#lua_tocfunction">lua_tocfunction</A><BR> -<A HREF="manual.html#lua_tointeger">lua_tointeger</A><BR> -<A HREF="manual.html#lua_tointegerx">lua_tointegerx</A><BR> -<A HREF="manual.html#lua_tolstring">lua_tolstring</A><BR> -<A HREF="manual.html#lua_tonumber">lua_tonumber</A><BR> -<A HREF="manual.html#lua_tonumberx">lua_tonumberx</A><BR> -<A HREF="manual.html#lua_topointer">lua_topointer</A><BR> -<A HREF="manual.html#lua_tostring">lua_tostring</A><BR> -<A HREF="manual.html#lua_tothread">lua_tothread</A><BR> -<A HREF="manual.html#lua_touserdata">lua_touserdata</A><BR> -<A HREF="manual.html#lua_type">lua_type</A><BR> -<A HREF="manual.html#lua_typename">lua_typename</A><BR> -<A HREF="manual.html#lua_upvalueid">lua_upvalueid</A><BR> -<A HREF="manual.html#lua_upvalueindex">lua_upvalueindex</A><BR> -<A HREF="manual.html#lua_upvaluejoin">lua_upvaluejoin</A><BR> -<A HREF="manual.html#lua_version">lua_version</A><BR> -<A HREF="manual.html#lua_xmove">lua_xmove</A><BR> -<A HREF="manual.html#lua_yield">lua_yield</A><BR> -<A HREF="manual.html#lua_yieldk">lua_yieldk</A><BR> - -</TD> -<TD> -<H3><A NAME="auxlib">auxiliary library</A></H3> -<P> -<A HREF="manual.html#luaL_Buffer">luaL_Buffer</A><BR> -<A HREF="manual.html#luaL_Reg">luaL_Reg</A><BR> -<A HREF="manual.html#luaL_Stream">luaL_Stream</A><BR> - -<P> -<A HREF="manual.html#luaL_addchar">luaL_addchar</A><BR> -<A HREF="manual.html#luaL_addlstring">luaL_addlstring</A><BR> -<A HREF="manual.html#luaL_addsize">luaL_addsize</A><BR> -<A HREF="manual.html#luaL_addstring">luaL_addstring</A><BR> -<A HREF="manual.html#luaL_addvalue">luaL_addvalue</A><BR> -<A HREF="manual.html#luaL_argcheck">luaL_argcheck</A><BR> -<A HREF="manual.html#luaL_argerror">luaL_argerror</A><BR> -<A HREF="manual.html#luaL_buffinit">luaL_buffinit</A><BR> -<A HREF="manual.html#luaL_buffinitsize">luaL_buffinitsize</A><BR> -<A HREF="manual.html#luaL_callmeta">luaL_callmeta</A><BR> -<A HREF="manual.html#luaL_checkany">luaL_checkany</A><BR> -<A HREF="manual.html#luaL_checkinteger">luaL_checkinteger</A><BR> -<A HREF="manual.html#luaL_checklstring">luaL_checklstring</A><BR> -<A HREF="manual.html#luaL_checknumber">luaL_checknumber</A><BR> -<A HREF="manual.html#luaL_checkoption">luaL_checkoption</A><BR> -<A HREF="manual.html#luaL_checkstack">luaL_checkstack</A><BR> -<A HREF="manual.html#luaL_checkstring">luaL_checkstring</A><BR> -<A HREF="manual.html#luaL_checktype">luaL_checktype</A><BR> -<A HREF="manual.html#luaL_checkudata">luaL_checkudata</A><BR> -<A HREF="manual.html#luaL_checkversion">luaL_checkversion</A><BR> -<A HREF="manual.html#luaL_dofile">luaL_dofile</A><BR> -<A HREF="manual.html#luaL_dostring">luaL_dostring</A><BR> -<A HREF="manual.html#luaL_error">luaL_error</A><BR> -<A HREF="manual.html#luaL_execresult">luaL_execresult</A><BR> -<A HREF="manual.html#luaL_fileresult">luaL_fileresult</A><BR> -<A HREF="manual.html#luaL_getmetafield">luaL_getmetafield</A><BR> -<A HREF="manual.html#luaL_getmetatable">luaL_getmetatable</A><BR> -<A HREF="manual.html#luaL_getsubtable">luaL_getsubtable</A><BR> -<A HREF="manual.html#luaL_gsub">luaL_gsub</A><BR> -<A HREF="manual.html#luaL_len">luaL_len</A><BR> -<A HREF="manual.html#luaL_loadbuffer">luaL_loadbuffer</A><BR> -<A HREF="manual.html#luaL_loadbufferx">luaL_loadbufferx</A><BR> -<A HREF="manual.html#luaL_loadfile">luaL_loadfile</A><BR> -<A HREF="manual.html#luaL_loadfilex">luaL_loadfilex</A><BR> -<A HREF="manual.html#luaL_loadstring">luaL_loadstring</A><BR> -<A HREF="manual.html#luaL_newlib">luaL_newlib</A><BR> -<A HREF="manual.html#luaL_newlibtable">luaL_newlibtable</A><BR> -<A HREF="manual.html#luaL_newmetatable">luaL_newmetatable</A><BR> -<A HREF="manual.html#luaL_newstate">luaL_newstate</A><BR> -<A HREF="manual.html#luaL_openlibs">luaL_openlibs</A><BR> -<A HREF="manual.html#luaL_opt">luaL_opt</A><BR> -<A HREF="manual.html#luaL_optinteger">luaL_optinteger</A><BR> -<A HREF="manual.html#luaL_optlstring">luaL_optlstring</A><BR> -<A HREF="manual.html#luaL_optnumber">luaL_optnumber</A><BR> -<A HREF="manual.html#luaL_optstring">luaL_optstring</A><BR> -<A HREF="manual.html#luaL_prepbuffer">luaL_prepbuffer</A><BR> -<A HREF="manual.html#luaL_prepbuffsize">luaL_prepbuffsize</A><BR> -<A HREF="manual.html#luaL_pushresult">luaL_pushresult</A><BR> -<A HREF="manual.html#luaL_pushresultsize">luaL_pushresultsize</A><BR> -<A HREF="manual.html#luaL_ref">luaL_ref</A><BR> -<A HREF="manual.html#luaL_requiref">luaL_requiref</A><BR> -<A HREF="manual.html#luaL_setfuncs">luaL_setfuncs</A><BR> -<A HREF="manual.html#luaL_setmetatable">luaL_setmetatable</A><BR> -<A HREF="manual.html#luaL_testudata">luaL_testudata</A><BR> -<A HREF="manual.html#luaL_tolstring">luaL_tolstring</A><BR> -<A HREF="manual.html#luaL_traceback">luaL_traceback</A><BR> -<A HREF="manual.html#luaL_typename">luaL_typename</A><BR> -<A HREF="manual.html#luaL_unref">luaL_unref</A><BR> -<A HREF="manual.html#luaL_where">luaL_where</A><BR> - -<H3><A NAME="library">standard library</A></H3> -<P> -<A HREF="manual.html#pdf-luaopen_base">luaopen_base</A><BR> -<A HREF="manual.html#pdf-luaopen_coroutine">luaopen_coroutine</A><BR> -<A HREF="manual.html#pdf-luaopen_debug">luaopen_debug</A><BR> -<A HREF="manual.html#pdf-luaopen_io">luaopen_io</A><BR> -<A HREF="manual.html#pdf-luaopen_math">luaopen_math</A><BR> -<A HREF="manual.html#pdf-luaopen_os">luaopen_os</A><BR> -<A HREF="manual.html#pdf-luaopen_package">luaopen_package</A><BR> -<A HREF="manual.html#pdf-luaopen_string">luaopen_string</A><BR> -<A HREF="manual.html#pdf-luaopen_table">luaopen_table</A><BR> -<A HREF="manual.html#pdf-luaopen_utf8">luaopen_utf8</A><BR> - -<H3><A NAME="constants">constants</A></H3> -<P> -<A HREF="manual.html#pdf-LUA_ERRERR">LUA_ERRERR</A><BR> -<A HREF="manual.html#pdf-LUA_ERRFILE">LUA_ERRFILE</A><BR> -<A HREF="manual.html#pdf-LUA_ERRGCMM">LUA_ERRGCMM</A><BR> -<A HREF="manual.html#pdf-LUA_ERRMEM">LUA_ERRMEM</A><BR> -<A HREF="manual.html#pdf-LUA_ERRRUN">LUA_ERRRUN</A><BR> -<A HREF="manual.html#pdf-LUA_ERRSYNTAX">LUA_ERRSYNTAX</A><BR> -<A HREF="manual.html#pdf-LUA_HOOKCALL">LUA_HOOKCALL</A><BR> -<A HREF="manual.html#pdf-LUA_HOOKCOUNT">LUA_HOOKCOUNT</A><BR> -<A HREF="manual.html#pdf-LUA_HOOKLINE">LUA_HOOKLINE</A><BR> -<A HREF="manual.html#pdf-LUA_HOOKRET">LUA_HOOKRET</A><BR> -<A HREF="manual.html#pdf-LUA_HOOKTAILCALL">LUA_HOOKTAILCALL</A><BR> -<A HREF="manual.html#pdf-LUA_MASKCALL">LUA_MASKCALL</A><BR> -<A HREF="manual.html#pdf-LUA_MASKCOUNT">LUA_MASKCOUNT</A><BR> -<A HREF="manual.html#pdf-LUA_MASKLINE">LUA_MASKLINE</A><BR> -<A HREF="manual.html#pdf-LUA_MASKRET">LUA_MASKRET</A><BR> -<A HREF="manual.html#pdf-LUA_MAXINTEGER">LUA_MAXINTEGER</A><BR> -<A HREF="manual.html#pdf-LUA_MININTEGER">LUA_MININTEGER</A><BR> -<A HREF="manual.html#pdf-LUA_MINSTACK">LUA_MINSTACK</A><BR> -<A HREF="manual.html#pdf-LUA_MULTRET">LUA_MULTRET</A><BR> -<A HREF="manual.html#pdf-LUA_NOREF">LUA_NOREF</A><BR> -<A HREF="manual.html#pdf-LUA_OK">LUA_OK</A><BR> -<A HREF="manual.html#pdf-LUA_OPADD">LUA_OPADD</A><BR> -<A HREF="manual.html#pdf-LUA_OPBAND">LUA_OPBAND</A><BR> -<A HREF="manual.html#pdf-LUA_OPBNOT">LUA_OPBNOT</A><BR> -<A HREF="manual.html#pdf-LUA_OPBOR">LUA_OPBOR</A><BR> -<A HREF="manual.html#pdf-LUA_OPBXOR">LUA_OPBXOR</A><BR> -<A HREF="manual.html#pdf-LUA_OPDIV">LUA_OPDIV</A><BR> -<A HREF="manual.html#pdf-LUA_OPEQ">LUA_OPEQ</A><BR> -<A HREF="manual.html#pdf-LUA_OPIDIV">LUA_OPIDIV</A><BR> -<A HREF="manual.html#pdf-LUA_OPLE">LUA_OPLE</A><BR> -<A HREF="manual.html#pdf-LUA_OPLT">LUA_OPLT</A><BR> -<A HREF="manual.html#pdf-LUA_OPMOD">LUA_OPMOD</A><BR> -<A HREF="manual.html#pdf-LUA_OPMUL">LUA_OPMUL</A><BR> -<A HREF="manual.html#pdf-LUA_OPPOW">LUA_OPPOW</A><BR> -<A HREF="manual.html#pdf-LUA_OPSHL">LUA_OPSHL</A><BR> -<A HREF="manual.html#pdf-LUA_OPSHR">LUA_OPSHR</A><BR> -<A HREF="manual.html#pdf-LUA_OPSUB">LUA_OPSUB</A><BR> -<A HREF="manual.html#pdf-LUA_OPUNM">LUA_OPUNM</A><BR> -<A HREF="manual.html#pdf-LUA_REFNIL">LUA_REFNIL</A><BR> -<A HREF="manual.html#pdf-LUA_REGISTRYINDEX">LUA_REGISTRYINDEX</A><BR> -<A HREF="manual.html#pdf-LUA_RIDX_GLOBALS">LUA_RIDX_GLOBALS</A><BR> -<A HREF="manual.html#pdf-LUA_RIDX_MAINTHREAD">LUA_RIDX_MAINTHREAD</A><BR> -<A HREF="manual.html#pdf-LUA_TBOOLEAN">LUA_TBOOLEAN</A><BR> -<A HREF="manual.html#pdf-LUA_TFUNCTION">LUA_TFUNCTION</A><BR> -<A HREF="manual.html#pdf-LUA_TLIGHTUSERDATA">LUA_TLIGHTUSERDATA</A><BR> -<A HREF="manual.html#pdf-LUA_TNIL">LUA_TNIL</A><BR> -<A HREF="manual.html#pdf-LUA_TNONE">LUA_TNONE</A><BR> -<A HREF="manual.html#pdf-LUA_TNUMBER">LUA_TNUMBER</A><BR> -<A HREF="manual.html#pdf-LUA_TSTRING">LUA_TSTRING</A><BR> -<A HREF="manual.html#pdf-LUA_TTABLE">LUA_TTABLE</A><BR> -<A HREF="manual.html#pdf-LUA_TTHREAD">LUA_TTHREAD</A><BR> -<A HREF="manual.html#pdf-LUA_TUSERDATA">LUA_TUSERDATA</A><BR> -<A HREF="manual.html#pdf-LUA_USE_APICHECK">LUA_USE_APICHECK</A><BR> -<A HREF="manual.html#pdf-LUA_YIELD">LUA_YIELD</A><BR> -<A HREF="manual.html#pdf-LUAL_BUFFERSIZE">LUAL_BUFFERSIZE</A><BR> - -</TD> -</TR> -</TABLE> - -<P CLASS="footer"> -Last update: -Mon Jun 18 22:56:06 -03 2018 -</P> -<!-- -Last change: revised for Lua 5.3.5 ---> - -</BODY> -</HTML> diff --git a/libs/liblua/docs/index.css b/libs/liblua/docs/index.css deleted file mode 100644 index c961835731..0000000000 --- a/libs/liblua/docs/index.css +++ /dev/null @@ -1,21 +0,0 @@ -ul { - list-style-type: none ; -} - -ul.contents { - padding: 0 ; -} - -table { - border: none ; - border-spacing: 0 ; - border-collapse: collapse ; -} - -td { - vertical-align: top ; - padding: 0 ; - text-align: left ; - line-height: 1.25 ; - width: 15% ; -} diff --git a/libs/liblua/docs/manual.css b/libs/liblua/docs/manual.css deleted file mode 100644 index aa0e677dd5..0000000000 --- a/libs/liblua/docs/manual.css +++ /dev/null @@ -1,21 +0,0 @@ -h3 code { - font-family: inherit ; - font-size: inherit ; -} - -pre, code { - font-size: 12pt ; -} - -span.apii { - color: gray ; - float: right ; - font-family: inherit ; - font-style: normal ; - font-size: small ; -} - -h2:before { - content: "" ; - padding-right: 0em ; -} diff --git a/libs/liblua/docs/manual.html b/libs/liblua/docs/manual.html deleted file mode 100644 index 89a642a45d..0000000000 --- a/libs/liblua/docs/manual.html +++ /dev/null @@ -1,10982 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<HTML> -<HEAD> -<TITLE>Lua 5.3 Reference Manual</TITLE> -<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css"> -<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css"> -<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1"> -</HEAD> - -<BODY> - -<H1> -<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A> -Lua 5.3 Reference Manual -</H1> - -<P> -by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes - -<P> -<SMALL> -Copyright © 2015–2018 Lua.org, PUC-Rio. -Freely available under the terms of the -<a href="http://www.lua.org/license.html">Lua license</a>. -</SMALL> - -<DIV CLASS="menubar"> -<A HREF="contents.html#contents">contents</A> -· -<A HREF="contents.html#index">index</A> -· -<A HREF="http://www.lua.org/manual/">other versions</A> -</DIV> - -<!-- ====================================================================== --> -<p> - -<!-- $Id: manual.of,v 1.167.1.2 2018/06/26 15:49:07 roberto Exp $ --> - - - - -<h1>1 – <a name="1">Introduction</a></h1> - -<p> -Lua is a powerful, efficient, lightweight, embeddable scripting language. -It supports procedural programming, -object-oriented programming, functional programming, -data-driven programming, and data description. - - -<p> -Lua combines simple procedural syntax with powerful data description -constructs based on associative arrays and extensible semantics. -Lua is dynamically typed, -runs by interpreting bytecode with a register-based -virtual machine, -and has automatic memory management with -incremental garbage collection, -making it ideal for configuration, scripting, -and rapid prototyping. - - -<p> -Lua is implemented as a library, written in <em>clean C</em>, -the common subset of Standard C and C++. -The Lua distribution includes a host program called <code>lua</code>, -which uses the Lua library to offer a complete, -standalone Lua interpreter, -for interactive or batch use. -Lua is intended to be used both as a powerful, lightweight, -embeddable scripting language for any program that needs one, -and as a powerful but lightweight and efficient stand-alone language. - - -<p> -As an extension language, Lua has no notion of a "main" program: -it works <em>embedded</em> in a host client, -called the <em>embedding program</em> or simply the <em>host</em>. -(Frequently, this host is the stand-alone <code>lua</code> program.) -The host program can invoke functions to execute a piece of Lua code, -can write and read Lua variables, -and can register C functions to be called by Lua code. -Through the use of C functions, Lua can be augmented to cope with -a wide range of different domains, -thus creating customized programming languages sharing a syntactical framework. - - -<p> -Lua is free software, -and is provided as usual with no guarantees, -as stated in its license. -The implementation described in this manual is available -at Lua's official web site, <code>www.lua.org</code>. - - -<p> -Like any other reference manual, -this document is dry in places. -For a discussion of the decisions behind the design of Lua, -see the technical papers available at Lua's web site. -For a detailed introduction to programming in Lua, -see Roberto's book, <em>Programming in Lua</em>. - - - -<h1>2 – <a name="2">Basic Concepts</a></h1> - -<p> -This section describes the basic concepts of the language. - - - -<h2>2.1 – <a name="2.1">Values and Types</a></h2> - -<p> -Lua is a <em>dynamically typed language</em>. -This means that -variables do not have types; only values do. -There are no type definitions in the language. -All values carry their own type. - - -<p> -All values in Lua are <em>first-class values</em>. -This means that all values can be stored in variables, -passed as arguments to other functions, and returned as results. - - -<p> -There are eight basic types in Lua: -<em>nil</em>, <em>boolean</em>, <em>number</em>, -<em>string</em>, <em>function</em>, <em>userdata</em>, -<em>thread</em>, and <em>table</em>. -The type <em>nil</em> has one single value, <b>nil</b>, -whose main property is to be different from any other value; -it usually represents the absence of a useful value. -The type <em>boolean</em> has two values, <b>false</b> and <b>true</b>. -Both <b>nil</b> and <b>false</b> make a condition false; -any other value makes it true. -The type <em>number</em> represents both -integer numbers and real (floating-point) numbers. -The type <em>string</em> represents immutable sequences of bytes. - -Lua is 8-bit clean: -strings can contain any 8-bit value, -including embedded zeros ('<code>\0</code>'). -Lua is also encoding-agnostic; -it makes no assumptions about the contents of a string. - - -<p> -The type <em>number</em> uses two internal representations, -or two subtypes, -one called <em>integer</em> and the other called <em>float</em>. -Lua has explicit rules about when each representation is used, -but it also converts between them automatically as needed (see <a href="#3.4.3">§3.4.3</a>). -Therefore, -the programmer may choose to mostly ignore the difference -between integers and floats -or to assume complete control over the representation of each number. -Standard Lua uses 64-bit integers and double-precision (64-bit) floats, -but you can also compile Lua so that it -uses 32-bit integers and/or single-precision (32-bit) floats. -The option with 32 bits for both integers and floats -is particularly attractive -for small machines and embedded systems. -(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.) - - -<p> -Lua can call (and manipulate) functions written in Lua and -functions written in C (see <a href="#3.4.10">§3.4.10</a>). -Both are represented by the type <em>function</em>. - - -<p> -The type <em>userdata</em> is provided to allow arbitrary C data to -be stored in Lua variables. -A userdata value represents a block of raw memory. -There are two kinds of userdata: -<em>full userdata</em>, -which is an object with a block of memory managed by Lua, -and <em>light userdata</em>, -which is simply a C pointer value. -Userdata has no predefined operations in Lua, -except assignment and identity test. -By using <em>metatables</em>, -the programmer can define operations for full userdata values -(see <a href="#2.4">§2.4</a>). -Userdata values cannot be created or modified in Lua, -only through the C API. -This guarantees the integrity of data owned by the host program. - - -<p> -The type <em>thread</em> represents independent threads of execution -and it is used to implement coroutines (see <a href="#2.6">§2.6</a>). -Lua threads are not related to operating-system threads. -Lua supports coroutines on all systems, -even those that do not support threads natively. - - -<p> -The type <em>table</em> implements associative arrays, -that is, arrays that can have as indices not only numbers, -but any Lua value except <b>nil</b> and NaN. -(<em>Not a Number</em> is a special value used to represent -undefined or unrepresentable numerical results, such as <code>0/0</code>.) -Tables can be <em>heterogeneous</em>; -that is, they can contain values of all types (except <b>nil</b>). -Any key with value <b>nil</b> is not considered part of the table. -Conversely, any key that is not part of a table has -an associated value <b>nil</b>. - - -<p> -Tables are the sole data-structuring mechanism in Lua; -they can be used to represent ordinary arrays, lists, -symbol tables, sets, records, graphs, trees, etc. -To represent records, Lua uses the field name as an index. -The language supports this representation by -providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. -There are several convenient ways to create tables in Lua -(see <a href="#3.4.9">§3.4.9</a>). - - -<p> -Like indices, -the values of table fields can be of any type. -In particular, -because functions are first-class values, -table fields can contain functions. -Thus tables can also carry <em>methods</em> (see <a href="#3.4.11">§3.4.11</a>). - - -<p> -The indexing of tables follows -the definition of raw equality in the language. -The expressions <code>a[i]</code> and <code>a[j]</code> -denote the same table element -if and only if <code>i</code> and <code>j</code> are raw equal -(that is, equal without metamethods). -In particular, floats with integral values -are equal to their respective integers -(e.g., <code>1.0 == 1</code>). -To avoid ambiguities, -any float with integral value used as a key -is converted to its respective integer. -For instance, if you write <code>a[2.0] = true</code>, -the actual key inserted into the table will be the -integer <code>2</code>. -(On the other hand, -2 and "<code>2</code>" are different Lua values and therefore -denote different table entries.) - - -<p> -Tables, functions, threads, and (full) userdata values are <em>objects</em>: -variables do not actually <em>contain</em> these values, -only <em>references</em> to them. -Assignment, parameter passing, and function returns -always manipulate references to such values; -these operations do not imply any kind of copy. - - -<p> -The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type -of a given value (see <a href="#6.1">§6.1</a>). - - - - - -<h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2> - -<p> -As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>, -any reference to a free name -(that is, a name not bound to any declaration) <code>var</code> -is syntactically translated to <code>_ENV.var</code>. -Moreover, every chunk is compiled in the scope of -an external local variable named <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>), -so <code>_ENV</code> itself is never a free name in a chunk. - - -<p> -Despite the existence of this external <code>_ENV</code> variable and -the translation of free names, -<code>_ENV</code> is a completely regular name. -In particular, -you can define new variables and parameters with that name. -Each reference to a free name uses the <code>_ENV</code> that is -visible at that point in the program, -following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>). - - -<p> -Any table used as the value of <code>_ENV</code> is called an <em>environment</em>. - - -<p> -Lua keeps a distinguished environment called the <em>global environment</em>. -This value is kept at a special index in the C registry (see <a href="#4.5">§4.5</a>). -In Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value. -(<a href="#pdf-_G"><code>_G</code></a> is never used internally.) - - -<p> -When Lua loads a chunk, -the default value for its <code>_ENV</code> upvalue -is the global environment (see <a href="#pdf-load"><code>load</code></a>). -Therefore, by default, -free names in Lua code refer to entries in the global environment -(and, therefore, they are also called <em>global variables</em>). -Moreover, all standard libraries are loaded in the global environment -and some functions there operate on that environment. -You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>) -to load a chunk with a different environment. -(In C, you have to load the chunk and then change the value -of its first upvalue.) - - - - - -<h2>2.3 – <a name="2.3">Error Handling</a></h2> - -<p> -Because Lua is an embedded extension language, -all Lua actions start from C code in the host program -calling a function from the Lua library. -(When you use Lua standalone, -the <code>lua</code> application is the host program.) -Whenever an error occurs during -the compilation or execution of a Lua chunk, -control returns to the host, -which can take appropriate measures -(such as printing an error message). - - -<p> -Lua code can explicitly generate an error by calling the -<a href="#pdf-error"><code>error</code></a> function. -If you need to catch errors in Lua, -you can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a> -to call a given function in <em>protected mode</em>. - - -<p> -Whenever there is an error, -an <em>error object</em> (also called an <em>error message</em>) -is propagated with information about the error. -Lua itself only generates errors whose error object is a string, -but programs may generate errors with -any value as the error object. -It is up to the Lua program or its host to handle such error objects. - - -<p> -When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>, -you may give a <em>message handler</em> -to be called in case of errors. -This function is called with the original error object -and returns a new error object. -It is called before the error unwinds the stack, -so that it can gather more information about the error, -for instance by inspecting the stack and creating a stack traceback. -This message handler is still protected by the protected call; -so, an error inside the message handler -will call the message handler again. -If this loop goes on for too long, -Lua breaks it and returns an appropriate message. -(The message handler is called only for regular runtime errors. -It is not called for memory-allocation errors -nor for errors while running finalizers.) - - - - - -<h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2> - -<p> -Every value in Lua can have a <em>metatable</em>. -This <em>metatable</em> is an ordinary Lua table -that defines the behavior of the original value -under certain special operations. -You can change several aspects of the behavior -of operations over a value by setting specific fields in its metatable. -For instance, when a non-numeric value is the operand of an addition, -Lua checks for a function in the field "<code>__add</code>" of the value's metatable. -If it finds one, -Lua calls this function to perform the addition. - - -<p> -The key for each event in a metatable is a string -with the event name prefixed by two underscores; -the corresponding values are called <em>metamethods</em>. -In the previous example, the key is "<code>__add</code>" -and the metamethod is the function that performs the addition. -Unless stated otherwise, -metamethods should be function values. - - -<p> -You can query the metatable of any value -using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function. -Lua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>). -So, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>, -Lua does the equivalent to the following code: - -<pre> - rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>") -</pre> - -<p> -You can replace the metatable of tables -using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function. -You cannot change the metatable of other types from Lua code -(except by using the debug library (<a href="#6.10">§6.10</a>)); -you should use the C API for that. - - -<p> -Tables and full userdata have individual metatables -(although multiple tables and userdata can share their metatables). -Values of all other types share one single metatable per type; -that is, there is one single metatable for all numbers, -one for all strings, etc. -By default, a value has no metatable, -but the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>). - - -<p> -A metatable controls how an object behaves in -arithmetic operations, bitwise operations, -order comparisons, concatenation, length operation, calls, and indexing. -A metatable also can define a function to be called -when a userdata or a table is garbage collected (<a href="#2.5">§2.5</a>). - - -<p> -For the unary operators (negation, length, and bitwise NOT), -the metamethod is computed and called with a dummy second operand, -equal to the first one. -This extra operand is only to simplify Lua's internals -(by making these operators behave like a binary operation) -and may be removed in future versions. -(For most uses this extra operand is irrelevant.) - - -<p> -A detailed list of events controlled by metatables is given next. -Each operation is identified by its corresponding key. - - - -<ul> - -<li><b><code>__add</code>: </b> -the addition (<code>+</code>) operation. -If any operand for an addition is not a number -(nor a string coercible to a number), -Lua will try to call a metamethod. -First, Lua will check the first operand (even if it is valid). -If that operand does not define a metamethod for <code>__add</code>, -then Lua will check the second operand. -If Lua can find a metamethod, -it calls the metamethod with the two operands as arguments, -and the result of the call -(adjusted to one value) -is the result of the operation. -Otherwise, -it raises an error. -</li> - -<li><b><code>__sub</code>: </b> -the subtraction (<code>-</code>) operation. -Behavior similar to the addition operation. -</li> - -<li><b><code>__mul</code>: </b> -the multiplication (<code>*</code>) operation. -Behavior similar to the addition operation. -</li> - -<li><b><code>__div</code>: </b> -the division (<code>/</code>) operation. -Behavior similar to the addition operation. -</li> - -<li><b><code>__mod</code>: </b> -the modulo (<code>%</code>) operation. -Behavior similar to the addition operation. -</li> - -<li><b><code>__pow</code>: </b> -the exponentiation (<code>^</code>) operation. -Behavior similar to the addition operation. -</li> - -<li><b><code>__unm</code>: </b> -the negation (unary <code>-</code>) operation. -Behavior similar to the addition operation. -</li> - -<li><b><code>__idiv</code>: </b> -the floor division (<code>//</code>) operation. -Behavior similar to the addition operation. -</li> - -<li><b><code>__band</code>: </b> -the bitwise AND (<code>&</code>) operation. -Behavior similar to the addition operation, -except that Lua will try a metamethod -if any operand is neither an integer -nor a value coercible to an integer (see <a href="#3.4.3">§3.4.3</a>). -</li> - -<li><b><code>__bor</code>: </b> -the bitwise OR (<code>|</code>) operation. -Behavior similar to the bitwise AND operation. -</li> - -<li><b><code>__bxor</code>: </b> -the bitwise exclusive OR (binary <code>~</code>) operation. -Behavior similar to the bitwise AND operation. -</li> - -<li><b><code>__bnot</code>: </b> -the bitwise NOT (unary <code>~</code>) operation. -Behavior similar to the bitwise AND operation. -</li> - -<li><b><code>__shl</code>: </b> -the bitwise left shift (<code><<</code>) operation. -Behavior similar to the bitwise AND operation. -</li> - -<li><b><code>__shr</code>: </b> -the bitwise right shift (<code>>></code>) operation. -Behavior similar to the bitwise AND operation. -</li> - -<li><b><code>__concat</code>: </b> -the concatenation (<code>..</code>) operation. -Behavior similar to the addition operation, -except that Lua will try a metamethod -if any operand is neither a string nor a number -(which is always coercible to a string). -</li> - -<li><b><code>__len</code>: </b> -the length (<code>#</code>) operation. -If the object is not a string, -Lua will try its metamethod. -If there is a metamethod, -Lua calls it with the object as argument, -and the result of the call -(always adjusted to one value) -is the result of the operation. -If there is no metamethod but the object is a table, -then Lua uses the table length operation (see <a href="#3.4.7">§3.4.7</a>). -Otherwise, Lua raises an error. -</li> - -<li><b><code>__eq</code>: </b> -the equal (<code>==</code>) operation. -Behavior similar to the addition operation, -except that Lua will try a metamethod only when the values -being compared are either both tables or both full userdata -and they are not primitively equal. -The result of the call is always converted to a boolean. -</li> - -<li><b><code>__lt</code>: </b> -the less than (<code><</code>) operation. -Behavior similar to the addition operation, -except that Lua will try a metamethod only when the values -being compared are neither both numbers nor both strings. -The result of the call is always converted to a boolean. -</li> - -<li><b><code>__le</code>: </b> -the less equal (<code><=</code>) operation. -Unlike other operations, -the less-equal operation can use two different events. -First, Lua looks for the <code>__le</code> metamethod in both operands, -like in the less than operation. -If it cannot find such a metamethod, -then it will try the <code>__lt</code> metamethod, -assuming that <code>a <= b</code> is equivalent to <code>not (b < a)</code>. -As with the other comparison operators, -the result is always a boolean. -(This use of the <code>__lt</code> event can be removed in future versions; -it is also slower than a real <code>__le</code> metamethod.) -</li> - -<li><b><code>__index</code>: </b> -The indexing access operation <code>table[key]</code>. -This event happens when <code>table</code> is not a table or -when <code>key</code> is not present in <code>table</code>. -The metamethod is looked up in <code>table</code>. - - -<p> -Despite the name, -the metamethod for this event can be either a function or a table. -If it is a function, -it is called with <code>table</code> and <code>key</code> as arguments, -and the result of the call -(adjusted to one value) -is the result of the operation. -If it is a table, -the final result is the result of indexing this table with <code>key</code>. -(This indexing is regular, not raw, -and therefore can trigger another metamethod.) -</li> - -<li><b><code>__newindex</code>: </b> -The indexing assignment <code>table[key] = value</code>. -Like the index event, -this event happens when <code>table</code> is not a table or -when <code>key</code> is not present in <code>table</code>. -The metamethod is looked up in <code>table</code>. - - -<p> -Like with indexing, -the metamethod for this event can be either a function or a table. -If it is a function, -it is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments. -If it is a table, -Lua does an indexing assignment to this table with the same key and value. -(This assignment is regular, not raw, -and therefore can trigger another metamethod.) - - -<p> -Whenever there is a <code>__newindex</code> metamethod, -Lua does not perform the primitive assignment. -(If necessary, -the metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a> -to do the assignment.) -</li> - -<li><b><code>__call</code>: </b> -The call operation <code>func(args)</code>. -This event happens when Lua tries to call a non-function value -(that is, <code>func</code> is not a function). -The metamethod is looked up in <code>func</code>. -If present, -the metamethod is called with <code>func</code> as its first argument, -followed by the arguments of the original call (<code>args</code>). -All results of the call -are the result of the operation. -(This is the only metamethod that allows multiple results.) -</li> - -</ul> - -<p> -It is a good practice to add all needed metamethods to a table -before setting it as a metatable of some object. -In particular, the <code>__gc</code> metamethod works only when this order -is followed (see <a href="#2.5.1">§2.5.1</a>). - - -<p> -Because metatables are regular tables, -they can contain arbitrary fields, -not only the event names defined above. -Some functions in the standard library -(e.g., <a href="#pdf-tostring"><code>tostring</code></a>) -use other fields in metatables for their own purposes. - - - - - -<h2>2.5 – <a name="2.5">Garbage Collection</a></h2> - -<p> -Lua performs automatic memory management. -This means that -you do not have to worry about allocating memory for new objects -or freeing it when the objects are no longer needed. -Lua manages memory automatically by running -a <em>garbage collector</em> to collect all <em>dead objects</em> -(that is, objects that are no longer accessible from Lua). -All memory used by Lua is subject to automatic management: -strings, tables, userdata, functions, threads, internal structures, etc. - - -<p> -Lua implements an incremental mark-and-sweep collector. -It uses two numbers to control its garbage-collection cycles: -the <em>garbage-collector pause</em> and -the <em>garbage-collector step multiplier</em>. -Both use percentage points as units -(e.g., a value of 100 means an internal value of 1). - - -<p> -The garbage-collector pause -controls how long the collector waits before starting a new cycle. -Larger values make the collector less aggressive. -Values smaller than 100 mean the collector will not wait to -start a new cycle. -A value of 200 means that the collector waits for the total memory in use -to double before starting a new cycle. - - -<p> -The garbage-collector step multiplier -controls the relative speed of the collector relative to -memory allocation. -Larger values make the collector more aggressive but also increase -the size of each incremental step. -You should not use values smaller than 100, -because they make the collector too slow and -can result in the collector never finishing a cycle. -The default is 200, -which means that the collector runs at "twice" -the speed of memory allocation. - - -<p> -If you set the step multiplier to a very large number -(larger than 10% of the maximum number of -bytes that the program may use), -the collector behaves like a stop-the-world collector. -If you then set the pause to 200, -the collector behaves as in old Lua versions, -doing a complete collection every time Lua doubles its -memory usage. - - -<p> -You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C -or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua. -You can also use these functions to control -the collector directly (e.g., stop and restart it). - - - -<h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3> - -<p> -You can set garbage-collector metamethods for tables -and, using the C API, -for full userdata (see <a href="#2.4">§2.4</a>). -These metamethods are also called <em>finalizers</em>. -Finalizers allow you to coordinate Lua's garbage collection -with external resource management -(such as closing files, network or database connections, -or freeing your own memory). - - -<p> -For an object (table or userdata) to be finalized when collected, -you must <em>mark</em> it for finalization. - -You mark an object for finalization when you set its metatable -and the metatable has a field indexed by the string "<code>__gc</code>". -Note that if you set a metatable without a <code>__gc</code> field -and later create that field in the metatable, -the object will not be marked for finalization. - - -<p> -When a marked object becomes garbage, -it is not collected immediately by the garbage collector. -Instead, Lua puts it in a list. -After the collection, -Lua goes through that list. -For each object in the list, -it checks the object's <code>__gc</code> metamethod: -If it is a function, -Lua calls it with the object as its single argument; -if the metamethod is not a function, -Lua simply ignores it. - - -<p> -At the end of each garbage-collection cycle, -the finalizers for objects are called in -the reverse order that the objects were marked for finalization, -among those collected in that cycle; -that is, the first finalizer to be called is the one associated -with the object marked last in the program. -The execution of each finalizer may occur at any point during -the execution of the regular code. - - -<p> -Because the object being collected must still be used by the finalizer, -that object (and other objects accessible only through it) -must be <em>resurrected</em> by Lua. -Usually, this resurrection is transient, -and the object memory is freed in the next garbage-collection cycle. -However, if the finalizer stores the object in some global place -(e.g., a global variable), -then the resurrection is permanent. -Moreover, if the finalizer marks a finalizing object for finalization again, -its finalizer will be called again in the next cycle where the -object is unreachable. -In any case, -the object memory is freed only in a GC cycle where -the object is unreachable and not marked for finalization. - - -<p> -When you close a state (see <a href="#lua_close"><code>lua_close</code></a>), -Lua calls the finalizers of all objects marked for finalization, -following the reverse order that they were marked. -If any finalizer marks objects for collection during that phase, -these marks have no effect. - - - - - -<h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3> - -<p> -A <em>weak table</em> is a table whose elements are -<em>weak references</em>. -A weak reference is ignored by the garbage collector. -In other words, -if the only references to an object are weak references, -then the garbage collector will collect that object. - - -<p> -A weak table can have weak keys, weak values, or both. -A table with weak values allows the collection of its values, -but prevents the collection of its keys. -A table with both weak keys and weak values allows the collection of -both keys and values. -In any case, if either the key or the value is collected, -the whole pair is removed from the table. -The weakness of a table is controlled by the -<code>__mode</code> field of its metatable. -If the <code>__mode</code> field is a string containing the character '<code>k</code>', -the keys in the table are weak. -If <code>__mode</code> contains '<code>v</code>', -the values in the table are weak. - - -<p> -A table with weak keys and strong values -is also called an <em>ephemeron table</em>. -In an ephemeron table, -a value is considered reachable only if its key is reachable. -In particular, -if the only reference to a key comes through its value, -the pair is removed. - - -<p> -Any change in the weakness of a table may take effect only -at the next collect cycle. -In particular, if you change the weakness to a stronger mode, -Lua may still collect some items from that table -before the change takes effect. - - -<p> -Only objects that have an explicit construction -are removed from weak tables. -Values, such as numbers and light C functions, -are not subject to garbage collection, -and therefore are not removed from weak tables -(unless their associated values are collected). -Although strings are subject to garbage collection, -they do not have an explicit construction, -and therefore are not removed from weak tables. - - -<p> -Resurrected objects -(that is, objects being finalized -and objects accessible only through objects being finalized) -have a special behavior in weak tables. -They are removed from weak values before running their finalizers, -but are removed from weak keys only in the next collection -after running their finalizers, when such objects are actually freed. -This behavior allows the finalizer to access properties -associated with the object through weak tables. - - -<p> -If a weak table is among the resurrected objects in a collection cycle, -it may not be properly cleared until the next cycle. - - - - - - - -<h2>2.6 – <a name="2.6">Coroutines</a></h2> - -<p> -Lua supports coroutines, -also called <em>collaborative multithreading</em>. -A coroutine in Lua represents an independent thread of execution. -Unlike threads in multithread systems, however, -a coroutine only suspends its execution by explicitly calling -a yield function. - - -<p> -You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>. -Its sole argument is a function -that is the main function of the coroutine. -The <code>create</code> function only creates a new coroutine and -returns a handle to it (an object of type <em>thread</em>); -it does not start the coroutine. - - -<p> -You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. -When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, -passing as its first argument -a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, -the coroutine starts its execution by -calling its main function. -Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed -as arguments to that function. -After the coroutine starts running, -it runs until it terminates or <em>yields</em>. - - -<p> -A coroutine can terminate its execution in two ways: -normally, when its main function returns -(explicitly or implicitly, after the last instruction); -and abnormally, if there is an unprotected error. -In case of normal termination, -<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>, -plus any values returned by the coroutine main function. -In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b> -plus an error object. - - -<p> -A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. -When a coroutine yields, -the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately, -even if the yield happens inside nested function calls -(that is, not in the main function, -but in a function directly or indirectly called by the main function). -In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>, -plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>. -The next time you resume the same coroutine, -it continues its execution from the point where it yielded, -with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra -arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. - - -<p> -Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>, -the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine, -but instead of returning the coroutine itself, -it returns a function that, when called, resumes the coroutine. -Any arguments passed to this function -go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>. -<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, -except the first one (the boolean error code). -Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>, -<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors; -any error is propagated to the caller. - - -<p> -As an example of how coroutines work, -consider the following code: - -<pre> - function foo (a) - print("foo", a) - return coroutine.yield(2*a) - end - - co = coroutine.create(function (a,b) - print("co-body", a, b) - local r = foo(a+1) - print("co-body", r) - local r, s = coroutine.yield(a+b, a-b) - print("co-body", r, s) - return b, "end" - end) - - print("main", coroutine.resume(co, 1, 10)) - print("main", coroutine.resume(co, "r")) - print("main", coroutine.resume(co, "x", "y")) - print("main", coroutine.resume(co, "x", "y")) -</pre><p> -When you run it, it produces the following output: - -<pre> - co-body 1 10 - foo 2 - main true 4 - co-body r - main true 11 -9 - co-body x y - main true 10 end - main false cannot resume dead coroutine -</pre> - -<p> -You can also create and manipulate coroutines through the C API: -see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>, -and <a href="#lua_yield"><code>lua_yield</code></a>. - - - - - -<h1>3 – <a name="3">The Language</a></h1> - -<p> -This section describes the lexis, the syntax, and the semantics of Lua. -In other words, -this section describes -which tokens are valid, -how they can be combined, -and what their combinations mean. - - -<p> -Language constructs will be explained using the usual extended BNF notation, -in which -{<em>a</em>} means 0 or more <em>a</em>'s, and -[<em>a</em>] means an optional <em>a</em>. -Non-terminals are shown like non-terminal, -keywords are shown like <b>kword</b>, -and other terminal symbols are shown like ‘<b>=</b>’. -The complete syntax of Lua can be found in <a href="#9">§9</a> -at the end of this manual. - - - -<h2>3.1 – <a name="3.1">Lexical Conventions</a></h2> - -<p> -Lua is a free-form language. -It ignores spaces (including new lines) and comments -between lexical elements (tokens), -except as delimiters between names and keywords. - - -<p> -<em>Names</em> -(also called <em>identifiers</em>) -in Lua can be any string of letters, -digits, and underscores, -not beginning with a digit and -not being a reserved word. -Identifiers are used to name variables, table fields, and labels. - - -<p> -The following <em>keywords</em> are reserved -and cannot be used as names: - - -<pre> - and break do else elseif end - false for function goto if in - local nil not or repeat return - then true until while -</pre> - -<p> -Lua is a case-sensitive language: -<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> -are two different, valid names. -As a convention, -programs should avoid creating -names that start with an underscore followed by -one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>). - - -<p> -The following strings denote other tokens: - -<pre> - + - * / % ^ # - & ~ | << >> // - == ~= <= >= < > = - ( ) { } [ ] :: - ; : , . .. ... -</pre> - -<p> -A <em>short literal string</em> -can be delimited by matching single or double quotes, -and can contain the following C-like escape sequences: -'<code>\a</code>' (bell), -'<code>\b</code>' (backspace), -'<code>\f</code>' (form feed), -'<code>\n</code>' (newline), -'<code>\r</code>' (carriage return), -'<code>\t</code>' (horizontal tab), -'<code>\v</code>' (vertical tab), -'<code>\\</code>' (backslash), -'<code>\"</code>' (quotation mark [double quote]), -and '<code>\'</code>' (apostrophe [single quote]). -A backslash followed by a line break -results in a newline in the string. -The escape sequence '<code>\z</code>' skips the following span -of white-space characters, -including line breaks; -it is particularly useful to break and indent a long literal string -into multiple lines without adding the newlines and spaces -into the string contents. -A short literal string cannot contain unescaped line breaks -nor escapes not forming a valid escape sequence. - - -<p> -We can specify any byte in a short literal string by its numeric value -(including embedded zeros). -This can be done -with the escape sequence <code>\x<em>XX</em></code>, -where <em>XX</em> is a sequence of exactly two hexadecimal digits, -or with the escape sequence <code>\<em>ddd</em></code>, -where <em>ddd</em> is a sequence of up to three decimal digits. -(Note that if a decimal escape sequence is to be followed by a digit, -it must be expressed using exactly three digits.) - - -<p> -The UTF-8 encoding of a Unicode character -can be inserted in a literal string with -the escape sequence <code>\u{<em>XXX</em>}</code> -(note the mandatory enclosing brackets), -where <em>XXX</em> is a sequence of one or more hexadecimal digits -representing the character code point. - - -<p> -Literal strings can also be defined using a long format -enclosed by <em>long brackets</em>. -We define an <em>opening long bracket of level <em>n</em></em> as an opening -square bracket followed by <em>n</em> equal signs followed by another -opening square bracket. -So, an opening long bracket of level 0 is written as <code>[[</code>, -an opening long bracket of level 1 is written as <code>[=[</code>, -and so on. -A <em>closing long bracket</em> is defined similarly; -for instance, -a closing long bracket of level 4 is written as <code>]====]</code>. -A <em>long literal</em> starts with an opening long bracket of any level and -ends at the first closing long bracket of the same level. -It can contain any text except a closing bracket of the same level. -Literals in this bracketed form can run for several lines, -do not interpret any escape sequences, -and ignore long brackets of any other level. -Any kind of end-of-line sequence -(carriage return, newline, carriage return followed by newline, -or newline followed by carriage return) -is converted to a simple newline. - - -<p> -For convenience, -when the opening long bracket is immediately followed by a newline, -the newline is not included in the string. -As an example, in a system using ASCII -(in which '<code>a</code>' is coded as 97, -newline is coded as 10, and '<code>1</code>' is coded as 49), -the five literal strings below denote the same string: - -<pre> - a = 'alo\n123"' - a = "alo\n123\"" - a = '\97lo\10\04923"' - a = [[alo - 123"]] - a = [==[ - alo - 123"]==] -</pre> - -<p> -Any byte in a literal string not -explicitly affected by the previous rules represents itself. -However, Lua opens files for parsing in text mode, -and the system file functions may have problems with -some control characters. -So, it is safer to represent -non-text data as a quoted literal with -explicit escape sequences for the non-text characters. - - -<p> -A <em>numeric constant</em> (or <em>numeral</em>) -can be written with an optional fractional part -and an optional decimal exponent, -marked by a letter '<code>e</code>' or '<code>E</code>'. -Lua also accepts hexadecimal constants, -which start with <code>0x</code> or <code>0X</code>. -Hexadecimal constants also accept an optional fractional part -plus an optional binary exponent, -marked by a letter '<code>p</code>' or '<code>P</code>'. -A numeric constant with a radix point or an exponent -denotes a float; -otherwise, -if its value fits in an integer, -it denotes an integer. -Examples of valid integer constants are - -<pre> - 3 345 0xff 0xBEBADA -</pre><p> -Examples of valid float constants are - -<pre> - 3.0 3.1416 314.16e-2 0.31416E1 34e1 - 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1 -</pre> - -<p> -A <em>comment</em> starts with a double hyphen (<code>--</code>) -anywhere outside a string. -If the text immediately after <code>--</code> is not an opening long bracket, -the comment is a <em>short comment</em>, -which runs until the end of the line. -Otherwise, it is a <em>long comment</em>, -which runs until the corresponding closing long bracket. -Long comments are frequently used to disable code temporarily. - - - - - -<h2>3.2 – <a name="3.2">Variables</a></h2> - -<p> -Variables are places that store values. -There are three kinds of variables in Lua: -global variables, local variables, and table fields. - - -<p> -A single name can denote a global variable or a local variable -(or a function's formal parameter, -which is a particular kind of local variable): - -<pre> - var ::= Name -</pre><p> -Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>. - - -<p> -Any variable name is assumed to be global unless explicitly declared -as a local (see <a href="#3.3.7">§3.3.7</a>). -Local variables are <em>lexically scoped</em>: -local variables can be freely accessed by functions -defined inside their scope (see <a href="#3.5">§3.5</a>). - - -<p> -Before the first assignment to a variable, its value is <b>nil</b>. - - -<p> -Square brackets are used to index a table: - -<pre> - var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ -</pre><p> -The meaning of accesses to table fields can be changed via metatables -(see <a href="#2.4">§2.4</a>). - - -<p> -The syntax <code>var.Name</code> is just syntactic sugar for -<code>var["Name"]</code>: - -<pre> - var ::= prefixexp ‘<b>.</b>’ Name -</pre> - -<p> -An access to a global variable <code>x</code> -is equivalent to <code>_ENV.x</code>. -Due to the way that chunks are compiled, -<code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>). - - - - - -<h2>3.3 – <a name="3.3">Statements</a></h2> - -<p> -Lua supports an almost conventional set of statements, -similar to those in Pascal or C. -This set includes -assignments, control structures, function calls, -and variable declarations. - - - -<h3>3.3.1 – <a name="3.3.1">Blocks</a></h3> - -<p> -A block is a list of statements, -which are executed sequentially: - -<pre> - block ::= {stat} -</pre><p> -Lua has <em>empty statements</em> -that allow you to separate statements with semicolons, -start a block with a semicolon -or write two semicolons in sequence: - -<pre> - stat ::= ‘<b>;</b>’ -</pre> - -<p> -Function calls and assignments -can start with an open parenthesis. -This possibility leads to an ambiguity in Lua's grammar. -Consider the following fragment: - -<pre> - a = b + c - (print or io.write)('done') -</pre><p> -The grammar could see it in two ways: - -<pre> - a = b + c(print or io.write)('done') - - a = b + c; (print or io.write)('done') -</pre><p> -The current parser always sees such constructions -in the first way, -interpreting the open parenthesis -as the start of the arguments to a call. -To avoid this ambiguity, -it is a good practice to always precede with a semicolon -statements that start with a parenthesis: - -<pre> - ;(print or io.write)('done') -</pre> - -<p> -A block can be explicitly delimited to produce a single statement: - -<pre> - stat ::= <b>do</b> block <b>end</b> -</pre><p> -Explicit blocks are useful -to control the scope of variable declarations. -Explicit blocks are also sometimes used to -add a <b>return</b> statement in the middle -of another block (see <a href="#3.3.4">§3.3.4</a>). - - - - - -<h3>3.3.2 – <a name="3.3.2">Chunks</a></h3> - -<p> -The unit of compilation of Lua is called a <em>chunk</em>. -Syntactically, -a chunk is simply a block: - -<pre> - chunk ::= block -</pre> - -<p> -Lua handles a chunk as the body of an anonymous function -with a variable number of arguments -(see <a href="#3.4.11">§3.4.11</a>). -As such, chunks can define local variables, -receive arguments, and return values. -Moreover, such anonymous function is compiled as in the -scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>). -The resulting function always has <code>_ENV</code> as its only upvalue, -even if it does not use that variable. - - -<p> -A chunk can be stored in a file or in a string inside the host program. -To execute a chunk, -Lua first <em>loads</em> it, -precompiling the chunk's code into instructions for a virtual machine, -and then Lua executes the compiled code -with an interpreter for the virtual machine. - - -<p> -Chunks can also be precompiled into binary form; -see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details. -Programs in source and compiled forms are interchangeable; -Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>). - - - - - -<h3>3.3.3 – <a name="3.3.3">Assignment</a></h3> - -<p> -Lua allows multiple assignments. -Therefore, the syntax for assignment -defines a list of variables on the left side -and a list of expressions on the right side. -The elements in both lists are separated by commas: - -<pre> - stat ::= varlist ‘<b>=</b>’ explist - varlist ::= var {‘<b>,</b>’ var} - explist ::= exp {‘<b>,</b>’ exp} -</pre><p> -Expressions are discussed in <a href="#3.4">§3.4</a>. - - -<p> -Before the assignment, -the list of values is <em>adjusted</em> to the length of -the list of variables. -If there are more values than needed, -the excess values are thrown away. -If there are fewer values than needed, -the list is extended with as many <b>nil</b>'s as needed. -If the list of expressions ends with a function call, -then all values returned by that call enter the list of values, -before the adjustment -(except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>). - - -<p> -The assignment statement first evaluates all its expressions -and only then the assignments are performed. -Thus the code - -<pre> - i = 3 - i, a[i] = i+1, 20 -</pre><p> -sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> -because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) -before it is assigned 4. -Similarly, the line - -<pre> - x, y = y, x -</pre><p> -exchanges the values of <code>x</code> and <code>y</code>, -and - -<pre> - x, y, z = y, z, x -</pre><p> -cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>. - - -<p> -An assignment to a global name <code>x = val</code> -is equivalent to the assignment -<code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>). - - -<p> -The meaning of assignments to table fields and -global variables (which are actually table fields, too) -can be changed via metatables (see <a href="#2.4">§2.4</a>). - - - - - -<h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p> -The control structures -<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and -familiar syntax: - - - - -<pre> - stat ::= <b>while</b> exp <b>do</b> block <b>end</b> - stat ::= <b>repeat</b> block <b>until</b> exp - stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> -</pre><p> -Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>). - - -<p> -The condition expression of a -control structure can return any value. -Both <b>false</b> and <b>nil</b> are considered false. -All values different from <b>nil</b> and <b>false</b> are considered true -(in particular, the number 0 and the empty string are also true). - - -<p> -In the <b>repeat</b>–<b>until</b> loop, -the inner block does not end at the <b>until</b> keyword, -but only after the condition. -So, the condition can refer to local variables -declared inside the loop block. - - -<p> -The <b>goto</b> statement transfers the program control to a label. -For syntactical reasons, -labels in Lua are considered statements too: - - - -<pre> - stat ::= <b>goto</b> Name - stat ::= label - label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ -</pre> - -<p> -A label is visible in the entire block where it is defined, -except -inside nested blocks where a label with the same name is defined and -inside nested functions. -A goto may jump to any visible label as long as it does not -enter into the scope of a local variable. - - -<p> -Labels and empty statements are called <em>void statements</em>, -as they perform no actions. - - -<p> -The <b>break</b> statement terminates the execution of a -<b>while</b>, <b>repeat</b>, or <b>for</b> loop, -skipping to the next statement after the loop: - - -<pre> - stat ::= <b>break</b> -</pre><p> -A <b>break</b> ends the innermost enclosing loop. - - -<p> -The <b>return</b> statement is used to return values -from a function or a chunk -(which is an anonymous function). - -Functions can return more than one value, -so the syntax for the <b>return</b> statement is - -<pre> - stat ::= <b>return</b> [explist] [‘<b>;</b>’] -</pre> - -<p> -The <b>return</b> statement can only be written -as the last statement of a block. -If it is really necessary to <b>return</b> in the middle of a block, -then an explicit inner block can be used, -as in the idiom <code>do return end</code>, -because now <b>return</b> is the last statement in its (inner) block. - - - - - -<h3>3.3.5 – <a name="3.3.5">For Statement</a></h3> - -<p> - -The <b>for</b> statement has two forms: -one numerical and one generic. - - -<p> -The numerical <b>for</b> loop repeats a block of code while a -control variable runs through an arithmetic progression. -It has the following syntax: - -<pre> - stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> -</pre><p> -The <em>block</em> is repeated for <em>name</em> starting at the value of -the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the -third <em>exp</em>. -More precisely, a <b>for</b> statement like - -<pre> - for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end -</pre><p> -is equivalent to the code: - -<pre> - do - local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>) - if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end - <em>var</em> = <em>var</em> - <em>step</em> - while true do - <em>var</em> = <em>var</em> + <em>step</em> - if (<em>step</em> >= 0 and <em>var</em> > <em>limit</em>) or (<em>step</em> < 0 and <em>var</em> < <em>limit</em>) then - break - end - local v = <em>var</em> - <em>block</em> - end - end -</pre> - -<p> -Note the following: - -<ul> - -<li> -All three control expressions are evaluated only once, -before the loop starts. -They must all result in numbers. -</li> - -<li> -<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables. -The names shown here are for explanatory purposes only. -</li> - -<li> -If the third expression (the step) is absent, -then a step of 1 is used. -</li> - -<li> -You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop. -</li> - -<li> -The loop variable <code>v</code> is local to the loop body. -If you need its value after the loop, -assign it to another variable before exiting the loop. -</li> - -</ul> - -<p> -The generic <b>for</b> statement works over functions, -called <em>iterators</em>. -On each iteration, the iterator function is called to produce a new value, -stopping when this new value is <b>nil</b>. -The generic <b>for</b> loop has the following syntax: - -<pre> - stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> - namelist ::= Name {‘<b>,</b>’ Name} -</pre><p> -A <b>for</b> statement like - -<pre> - for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end -</pre><p> -is equivalent to the code: - -<pre> - do - local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em> - while true do - local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>) - if <em>var_1</em> == nil then break end - <em>var</em> = <em>var_1</em> - <em>block</em> - end - end -</pre><p> -Note the following: - -<ul> - -<li> -<code><em>explist</em></code> is evaluated only once. -Its results are an <em>iterator</em> function, -a <em>state</em>, -and an initial value for the first <em>iterator variable</em>. -</li> - -<li> -<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables. -The names are here for explanatory purposes only. -</li> - -<li> -You can use <b>break</b> to exit a <b>for</b> loop. -</li> - -<li> -The loop variables <code><em>var_i</em></code> are local to the loop; -you cannot use their values after the <b>for</b> ends. -If you need these values, -then assign them to other variables before breaking or exiting the loop. -</li> - -</ul> - - - - -<h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p> -To allow possible side-effects, -function calls can be executed as statements: - -<pre> - stat ::= functioncall -</pre><p> -In this case, all returned values are thrown away. -Function calls are explained in <a href="#3.4.10">§3.4.10</a>. - - - - - -<h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p> -Local variables can be declared anywhere inside a block. -The declaration can include an initial assignment: - -<pre> - stat ::= <b>local</b> namelist [‘<b>=</b>’ explist] -</pre><p> -If present, an initial assignment has the same semantics -of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>). -Otherwise, all variables are initialized with <b>nil</b>. - - -<p> -A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>), -and so local variables can be declared in a chunk outside any explicit block. - - -<p> -The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>. - - - - - - - -<h2>3.4 – <a name="3.4">Expressions</a></h2> - -<p> -The basic expressions in Lua are the following: - -<pre> - exp ::= prefixexp - exp ::= <b>nil</b> | <b>false</b> | <b>true</b> - exp ::= Numeral - exp ::= LiteralString - exp ::= functiondef - exp ::= tableconstructor - exp ::= ‘<b>...</b>’ - exp ::= exp binop exp - exp ::= unop exp - prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ -</pre> - -<p> -Numerals and literal strings are explained in <a href="#3.1">§3.1</a>; -variables are explained in <a href="#3.2">§3.2</a>; -function definitions are explained in <a href="#3.4.11">§3.4.11</a>; -function calls are explained in <a href="#3.4.10">§3.4.10</a>; -table constructors are explained in <a href="#3.4.9">§3.4.9</a>. -Vararg expressions, -denoted by three dots ('<code>...</code>'), can only be used when -directly inside a vararg function; -they are explained in <a href="#3.4.11">§3.4.11</a>. - - -<p> -Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>), -bitwise operators (see <a href="#3.4.2">§3.4.2</a>), -relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>), -and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>). -Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>), -the unary bitwise NOT (see <a href="#3.4.2">§3.4.2</a>), -the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>), -and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>). - - -<p> -Both function calls and vararg expressions can result in multiple values. -If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>), -then its return list is adjusted to zero elements, -thus discarding all returned values. -If an expression is used as the last (or the only) element -of a list of expressions, -then no adjustment is made -(unless the expression is enclosed in parentheses). -In all other contexts, -Lua adjusts the result list to one element, -either discarding all values except the first one -or adding a single <b>nil</b> if there are no values. - - -<p> -Here are some examples: - -<pre> - f() -- adjusted to 0 results - g(f(), x) -- f() is adjusted to 1 result - g(x, f()) -- g gets x plus all results from f() - a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) - a,b = ... -- a gets the first vararg argument, b gets - -- the second (both a and b can get nil if there - -- is no corresponding vararg argument) - - a,b,c = x, f() -- f() is adjusted to 2 results - a,b,c = f() -- f() is adjusted to 3 results - return f() -- returns all results from f() - return ... -- returns all received vararg arguments - return x,y,f() -- returns x, y, and all results from f() - {f()} -- creates a list with all results from f() - {...} -- creates a list with all vararg arguments - {f(), nil} -- f() is adjusted to 1 result -</pre> - -<p> -Any expression enclosed in parentheses always results in only one value. -Thus, -<code>(f(x,y,z))</code> is always a single value, -even if <code>f</code> returns several values. -(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> -or <b>nil</b> if <code>f</code> does not return any values.) - - - -<h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p> -Lua supports the following arithmetic operators: - -<ul> -<li><b><code>+</code>: </b>addition</li> -<li><b><code>-</code>: </b>subtraction</li> -<li><b><code>*</code>: </b>multiplication</li> -<li><b><code>/</code>: </b>float division</li> -<li><b><code>//</code>: </b>floor division</li> -<li><b><code>%</code>: </b>modulo</li> -<li><b><code>^</code>: </b>exponentiation</li> -<li><b><code>-</code>: </b>unary minus</li> -</ul> - -<p> -With the exception of exponentiation and float division, -the arithmetic operators work as follows: -If both operands are integers, -the operation is performed over integers and the result is an integer. -Otherwise, if both operands are numbers -or strings that can be converted to -numbers (see <a href="#3.4.3">§3.4.3</a>), -then they are converted to floats, -the operation is performed following the usual rules -for floating-point arithmetic -(usually the IEEE 754 standard), -and the result is a float. - - -<p> -Exponentiation and float division (<code>/</code>) -always convert their operands to floats -and the result is always a float. -Exponentiation uses the ISO C function <code>pow</code>, -so that it works for non-integer exponents too. - - -<p> -Floor division (<code>//</code>) is a division -that rounds the quotient towards minus infinity, -that is, the floor of the division of its operands. - - -<p> -Modulo is defined as the remainder of a division -that rounds the quotient towards minus infinity (floor division). - - -<p> -In case of overflows in integer arithmetic, -all operations <em>wrap around</em>, -according to the usual rules of two-complement arithmetic. -(In other words, -they return the unique representable integer -that is equal modulo <em>2<sup>64</sup></em> to the mathematical result.) - - - -<h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p> -Lua supports the following bitwise operators: - -<ul> -<li><b><code>&</code>: </b>bitwise AND</li> -<li><b><code>|</code>: </b>bitwise OR</li> -<li><b><code>~</code>: </b>bitwise exclusive OR</li> -<li><b><code>>></code>: </b>right shift</li> -<li><b><code><<</code>: </b>left shift</li> -<li><b><code>~</code>: </b>unary bitwise NOT</li> -</ul> - -<p> -All bitwise operations convert its operands to integers -(see <a href="#3.4.3">§3.4.3</a>), -operate on all bits of those integers, -and result in an integer. - - -<p> -Both right and left shifts fill the vacant bits with zeros. -Negative displacements shift to the other direction; -displacements with absolute values equal to or higher than -the number of bits in an integer -result in zero (as all bits are shifted out). - - - - - -<h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p> -Lua provides some automatic conversions between some -types and representations at run time. -Bitwise operators always convert float operands to integers. -Exponentiation and float division -always convert integer operands to floats. -All other arithmetic operations applied to mixed numbers -(integers and floats) convert the integer operand to a float; -this is called the <em>usual rule</em>. -The C API also converts both integers to floats and -floats to integers, as needed. -Moreover, string concatenation accepts numbers as arguments, -besides strings. - - -<p> -Lua also converts strings to numbers, -whenever a number is expected. - - -<p> -In a conversion from integer to float, -if the integer value has an exact representation as a float, -that is the result. -Otherwise, -the conversion gets the nearest higher or -the nearest lower representable value. -This kind of conversion never fails. - - -<p> -The conversion from float to integer -checks whether the float has an exact representation as an integer -(that is, the float has an integral value and -it is in the range of integer representation). -If it does, that representation is the result. -Otherwise, the conversion fails. - - -<p> -The conversion from strings to numbers goes as follows: -First, the string is converted to an integer or a float, -following its syntax and the rules of the Lua lexer. -(The string may have also leading and trailing spaces and a sign.) -Then, the resulting number (float or integer) -is converted to the type (float or integer) required by the context -(e.g., the operation that forced the conversion). - - -<p> -All conversions from strings to numbers -accept both a dot and the current locale mark -as the radix character. -(The Lua lexer, however, accepts only a dot.) - - -<p> -The conversion from numbers to strings uses a -non-specified human-readable format. -For complete control over how numbers are converted to strings, -use the <code>format</code> function from the string library -(see <a href="#pdf-string.format"><code>string.format</code></a>). - - - - - -<h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p> -Lua supports the following relational operators: - -<ul> -<li><b><code>==</code>: </b>equality</li> -<li><b><code>~=</code>: </b>inequality</li> -<li><b><code><</code>: </b>less than</li> -<li><b><code>></code>: </b>greater than</li> -<li><b><code><=</code>: </b>less or equal</li> -<li><b><code>>=</code>: </b>greater or equal</li> -</ul><p> -These operators always result in <b>false</b> or <b>true</b>. - - -<p> -Equality (<code>==</code>) first compares the type of its operands. -If the types are different, then the result is <b>false</b>. -Otherwise, the values of the operands are compared. -Strings are compared in the obvious way. -Numbers are equal if they denote the same mathematical value. - - -<p> -Tables, userdata, and threads -are compared by reference: -two objects are considered equal only if they are the same object. -Every time you create a new object -(a table, userdata, or thread), -this new object is different from any previously existing object. -A closure is always equal to itself. -Closures with any detectable difference -(different behavior, different definition) are always different. -Closures created at different times but with no detectable differences -may be classified as equal or not -(depending on internal caching details). - - -<p> -You can change the way that Lua compares tables and userdata -by using the "eq" metamethod (see <a href="#2.4">§2.4</a>). - - -<p> -Equality comparisons do not convert strings to numbers -or vice versa. -Thus, <code>"0"==0</code> evaluates to <b>false</b>, -and <code>t[0]</code> and <code>t["0"]</code> denote different -entries in a table. - - -<p> -The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). - - -<p> -The order operators work as follows. -If both arguments are numbers, -then they are compared according to their mathematical values -(regardless of their subtypes). -Otherwise, if both arguments are strings, -then their values are compared according to the current locale. -Otherwise, Lua tries to call the "lt" or the "le" -metamethod (see <a href="#2.4">§2.4</a>). -A comparison <code>a > b</code> is translated to <code>b < a</code> -and <code>a >= b</code> is translated to <code>b <= a</code>. - - -<p> -Following the IEEE 754 standard, -NaN is considered neither smaller than, -nor equal to, nor greater than any value (including itself). - - - - - -<h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p> -The logical operators in Lua are -<b>and</b>, <b>or</b>, and <b>not</b>. -Like the control structures (see <a href="#3.3.4">§3.3.4</a>), -all logical operators consider both <b>false</b> and <b>nil</b> as false -and anything else as true. - - -<p> -The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>. -The conjunction operator <b>and</b> returns its first argument -if this value is <b>false</b> or <b>nil</b>; -otherwise, <b>and</b> returns its second argument. -The disjunction operator <b>or</b> returns its first argument -if this value is different from <b>nil</b> and <b>false</b>; -otherwise, <b>or</b> returns its second argument. -Both <b>and</b> and <b>or</b> use short-circuit evaluation; -that is, -the second operand is evaluated only if necessary. -Here are some examples: - -<pre> - 10 or 20 --> 10 - 10 or error() --> 10 - nil or "a" --> "a" - nil and 10 --> nil - false and error() --> false - false and nil --> false - false or nil --> nil - 10 and 20 --> 20 -</pre><p> -(In this manual, -<code>--></code> indicates the result of the preceding expression.) - - - - - -<h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p> -The string concatenation operator in Lua is -denoted by two dots ('<code>..</code>'). -If both operands are strings or numbers, then they are converted to -strings according to the rules described in <a href="#3.4.3">§3.4.3</a>. -Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>). - - - - - -<h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3> - -<p> -The length operator is denoted by the unary prefix operator <code>#</code>. - - -<p> -The length of a string is its number of bytes -(that is, the usual meaning of string length when each -character is one byte). - - -<p> -The length operator applied on a table -returns a border in that table. -A <em>border</em> in a table <code>t</code> is any natural number -that satisfies the following condition: - -<pre> - (border == 0 or t[border] ~= nil) and t[border + 1] == nil -</pre><p> -In words, -a border is any (natural) index in a table -where a non-nil value is followed by a nil value -(or zero, when index 1 is nil). - - -<p> -A table with exactly one border is called a <em>sequence</em>. -For instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence, -as it has only one border (5). -The table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5), -and therefore it is not a sequence. -The table <code>{nil, 20, 30, nil, nil, 60, nil}</code> -has three borders (0, 3, and 6), -so it is not a sequence, too. -The table <code>{}</code> is a sequence with border 0. -Note that non-natural keys do not interfere -with whether a table is a sequence. - - -<p> -When <code>t</code> is a sequence, -<code>#t</code> returns its only border, -which corresponds to the intuitive notion of the length of the sequence. -When <code>t</code> is not a sequence, -<code>#t</code> can return any of its borders. -(The exact one depends on details of -the internal representation of the table, -which in turn can depend on how the table was populated and -the memory addresses of its non-numeric keys.) - - -<p> -The computation of the length of a table -has a guaranteed worst time of <em>O(log n)</em>, -where <em>n</em> is the largest natural key in the table. - - -<p> -A program can modify the behavior of the length operator for -any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>). - - - - - -<h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p> -Operator precedence in Lua follows the table below, -from lower to higher priority: - -<pre> - or - and - < > <= >= ~= == - | - ~ - & - << >> - .. - + - - * / // % - unary operators (not # - ~) - ^ -</pre><p> -As usual, -you can use parentheses to change the precedences of an expression. -The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>') -operators are right associative. -All other binary operators are left associative. - - - - - -<h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p> -Table constructors are expressions that create tables. -Every time a constructor is evaluated, a new table is created. -A constructor can be used to create an empty table -or to create a table and initialize some of its fields. -The general syntax for constructors is - -<pre> - tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ - fieldlist ::= field {fieldsep field} [fieldsep] - field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp - fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ -</pre> - -<p> -Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry -with key <code>exp1</code> and value <code>exp2</code>. -A field of the form <code>name = exp</code> is equivalent to -<code>["name"] = exp</code>. -Finally, fields of the form <code>exp</code> are equivalent to -<code>[i] = exp</code>, where <code>i</code> are consecutive integers -starting with 1. -Fields in the other formats do not affect this counting. -For example, - -<pre> - a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } -</pre><p> -is equivalent to - -<pre> - do - local t = {} - t[f(1)] = g - t[1] = "x" -- 1st exp - t[2] = "y" -- 2nd exp - t.x = 1 -- t["x"] = 1 - t[3] = f(x) -- 3rd exp - t[30] = 23 - t[4] = 45 -- 4th exp - a = t - end -</pre> - -<p> -The order of the assignments in a constructor is undefined. -(This order would be relevant only when there are repeated keys.) - - -<p> -If the last field in the list has the form <code>exp</code> -and the expression is a function call or a vararg expression, -then all values returned by this expression enter the list consecutively -(see <a href="#3.4.10">§3.4.10</a>). - - -<p> -The field list can have an optional trailing separator, -as a convenience for machine-generated code. - - - - - -<h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p> -A function call in Lua has the following syntax: - -<pre> - functioncall ::= prefixexp args -</pre><p> -In a function call, -first prefixexp and args are evaluated. -If the value of prefixexp has type <em>function</em>, -then this function is called -with the given arguments. -Otherwise, the prefixexp "call" metamethod is called, -having as first argument the value of prefixexp, -followed by the original call arguments -(see <a href="#2.4">§2.4</a>). - - -<p> -The form - -<pre> - functioncall ::= prefixexp ‘<b>:</b>’ Name args -</pre><p> -can be used to call "methods". -A call <code>v:name(<em>args</em>)</code> -is syntactic sugar for <code>v.name(v,<em>args</em>)</code>, -except that <code>v</code> is evaluated only once. - - -<p> -Arguments have the following syntax: - -<pre> - args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ - args ::= tableconstructor - args ::= LiteralString -</pre><p> -All argument expressions are evaluated before the call. -A call of the form <code>f{<em>fields</em>}</code> is -syntactic sugar for <code>f({<em>fields</em>})</code>; -that is, the argument list is a single new table. -A call of the form <code>f'<em>string</em>'</code> -(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>) -is syntactic sugar for <code>f('<em>string</em>')</code>; -that is, the argument list is a single literal string. - - -<p> -A call of the form <code>return <em>functioncall</em></code> is called -a <em>tail call</em>. -Lua implements <em>proper tail calls</em> -(or <em>proper tail recursion</em>): -in a tail call, -the called function reuses the stack entry of the calling function. -Therefore, there is no limit on the number of nested tail calls that -a program can execute. -However, a tail call erases any debug information about the -calling function. -Note that a tail call only happens with a particular syntax, -where the <b>return</b> has one single function call as argument; -this syntax makes the calling function return exactly -the returns of the called function. -So, none of the following examples are tail calls: - -<pre> - return (f(x)) -- results adjusted to 1 - return 2 * f(x) - return x, f(x) -- additional results - f(x); return -- results discarded - return x or f(x) -- results adjusted to 1 -</pre> - - - - -<h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3> - -<p> -The syntax for function definition is - -<pre> - functiondef ::= <b>function</b> funcbody - funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> -</pre> - -<p> -The following syntactic sugar simplifies function definitions: - -<pre> - stat ::= <b>function</b> funcname funcbody - stat ::= <b>local</b> <b>function</b> Name funcbody - funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] -</pre><p> -The statement - -<pre> - function f () <em>body</em> end -</pre><p> -translates to - -<pre> - f = function () <em>body</em> end -</pre><p> -The statement - -<pre> - function t.a.b.c.f () <em>body</em> end -</pre><p> -translates to - -<pre> - t.a.b.c.f = function () <em>body</em> end -</pre><p> -The statement - -<pre> - local function f () <em>body</em> end -</pre><p> -translates to - -<pre> - local f; f = function () <em>body</em> end -</pre><p> -not to - -<pre> - local f = function () <em>body</em> end -</pre><p> -(This only makes a difference when the body of the function -contains references to <code>f</code>.) - - -<p> -A function definition is an executable expression, -whose value has type <em>function</em>. -When Lua precompiles a chunk, -all its function bodies are precompiled too. -Then, whenever Lua executes the function definition, -the function is <em>instantiated</em> (or <em>closed</em>). -This function instance (or <em>closure</em>) -is the final value of the expression. - - -<p> -Parameters act as local variables that are -initialized with the argument values: - -<pre> - parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ -</pre><p> -When a function is called, -the list of arguments is adjusted to -the length of the list of parameters, -unless the function is a <em>vararg function</em>, -which is indicated by three dots ('<code>...</code>') -at the end of its parameter list. -A vararg function does not adjust its argument list; -instead, it collects all extra arguments and supplies them -to the function through a <em>vararg expression</em>, -which is also written as three dots. -The value of this expression is a list of all actual extra arguments, -similar to a function with multiple results. -If a vararg expression is used inside another expression -or in the middle of a list of expressions, -then its return list is adjusted to one element. -If the expression is used as the last element of a list of expressions, -then no adjustment is made -(unless that last expression is enclosed in parentheses). - - -<p> -As an example, consider the following definitions: - -<pre> - function f(a, b) end - function g(a, b, ...) end - function r() return 1,2,3 end -</pre><p> -Then, we have the following mapping from arguments to parameters and -to the vararg expression: - -<pre> - CALL PARAMETERS - - f(3) a=3, b=nil - f(3, 4) a=3, b=4 - f(3, 4, 5) a=3, b=4 - f(r(), 10) a=1, b=10 - f(r()) a=1, b=2 - - g(3) a=3, b=nil, ... --> (nothing) - g(3, 4) a=3, b=4, ... --> (nothing) - g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 - g(5, r()) a=5, b=1, ... --> 2 3 -</pre> - -<p> -Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>). -If control reaches the end of a function -without encountering a <b>return</b> statement, -then the function returns with no results. - - -<p> - -There is a system-dependent limit on the number of values -that a function may return. -This limit is guaranteed to be larger than 1000. - - -<p> -The <em>colon</em> syntax -is used for defining <em>methods</em>, -that is, functions that have an implicit extra parameter <code>self</code>. -Thus, the statement - -<pre> - function t.a.b.c:f (<em>params</em>) <em>body</em> end -</pre><p> -is syntactic sugar for - -<pre> - t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end -</pre> - - - - - - -<h2>3.5 – <a name="3.5">Visibility Rules</a></h2> - -<p> - -Lua is a lexically scoped language. -The scope of a local variable begins at the first statement after -its declaration and lasts until the last non-void statement -of the innermost block that includes the declaration. -Consider the following example: - -<pre> - x = 10 -- global variable - do -- new block - local x = x -- new 'x', with value 10 - print(x) --> 10 - x = x+1 - do -- another block - local x = x+1 -- another 'x' - print(x) --> 12 - end - print(x) --> 11 - end - print(x) --> 10 (the global one) -</pre> - -<p> -Notice that, in a declaration like <code>local x = x</code>, -the new <code>x</code> being declared is not in scope yet, -and so the second <code>x</code> refers to the outside variable. - - -<p> -Because of the lexical scoping rules, -local variables can be freely accessed by functions -defined inside their scope. -A local variable used by an inner function is called -an <em>upvalue</em>, or <em>external local variable</em>, -inside the inner function. - - -<p> -Notice that each execution of a <b>local</b> statement -defines new local variables. -Consider the following example: - -<pre> - a = {} - local x = 20 - for i=1,10 do - local y = 0 - a[i] = function () y=y+1; return x+y end - end -</pre><p> -The loop creates ten closures -(that is, ten instances of the anonymous function). -Each of these closures uses a different <code>y</code> variable, -while all of them share the same <code>x</code>. - - - - - -<h1>4 – <a name="4">The Application Program Interface</a></h1> - -<p> - -This section describes the C API for Lua, that is, -the set of C functions available to the host program to communicate -with Lua. -All API functions and related types and constants -are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>. - - -<p> -Even when we use the term "function", -any facility in the API may be provided as a macro instead. -Except where stated otherwise, -all such macros use each of their arguments exactly once -(except for the first argument, which is always a Lua state), -and so do not generate any hidden side-effects. - - -<p> -As in most C libraries, -the Lua API functions do not check their arguments for validity or consistency. -However, you can change this behavior by compiling Lua -with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined. - - -<p> -The Lua library is fully reentrant: -it has no global variables. -It keeps all information it needs in a dynamic structure, -called the <em>Lua state</em>. - - -<p> -Each Lua state has one or more threads, -which correspond to independent, cooperative lines of execution. -The type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread. -(Indirectly, through the thread, it also refers to the -Lua state associated to the thread.) - - -<p> -A pointer to a thread must be passed as the first argument to -every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, -which creates a Lua state from scratch and returns a pointer -to the <em>main thread</em> in the new state. - - - -<h2>4.1 – <a name="4.1">The Stack</a></h2> - -<p> -Lua uses a <em>virtual stack</em> to pass values to and from C. -Each element in this stack represents a Lua value -(<b>nil</b>, number, string, etc.). -Functions in the API can access this stack through the -Lua state parameter that they receive. - - -<p> -Whenever Lua calls C, the called function gets a new stack, -which is independent of previous stacks and of stacks of -C functions that are still active. -This stack initially contains any arguments to the C function -and it is where the C function can store temporary -Lua values and must push its results -to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). - - -<p> -For convenience, -most query operations in the API do not follow a strict stack discipline. -Instead, they can refer to any element in the stack -by using an <em>index</em>: -A positive index represents an absolute stack position -(starting at 1); -a negative index represents an offset relative to the top of the stack. -More specifically, if the stack has <em>n</em> elements, -then index 1 represents the first element -(that is, the element that was pushed onto the stack first) -and -index <em>n</em> represents the last element; -index -1 also represents the last element -(that is, the element at the top) -and index <em>-n</em> represents the first element. - - - - - -<h2>4.2 – <a name="4.2">Stack Size</a></h2> - -<p> -When you interact with the Lua API, -you are responsible for ensuring consistency. -In particular, -<em>you are responsible for controlling stack overflow</em>. -You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a> -to ensure that the stack has enough space for pushing new elements. - - -<p> -Whenever Lua calls C, -it ensures that the stack has space for -at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots. -<code>LUA_MINSTACK</code> is defined as 20, -so that usually you do not have to worry about stack space -unless your code has loops pushing elements onto the stack. - - -<p> -When you call a Lua function -without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>), -Lua ensures that the stack has enough space for all results, -but it does not ensure any extra space. -So, before pushing anything in the stack after such a call -you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>. - - - - - -<h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2> - -<p> -Any function in the API that receives stack indices -works only with <em>valid indices</em> or <em>acceptable indices</em>. - - -<p> -A <em>valid index</em> is an index that refers to a -position that stores a modifiable Lua value. -It comprises stack indices between 1 and the stack top -(<code>1 ≤ abs(index) ≤ top</code>) - -plus <em>pseudo-indices</em>, -which represent some positions that are accessible to C code -but that are not in the stack. -Pseudo-indices are used to access the registry (see <a href="#4.5">§4.5</a>) -and the upvalues of a C function (see <a href="#4.4">§4.4</a>). - - -<p> -Functions that do not need a specific mutable position, -but only a value (e.g., query functions), -can be called with acceptable indices. -An <em>acceptable index</em> can be any valid index, -but it also can be any positive index after the stack top -within the space allocated for the stack, -that is, indices up to the stack size. -(Note that 0 is never an acceptable index.) -Except when noted otherwise, -functions in the API work with acceptable indices. - - -<p> -Acceptable indices serve to avoid extra tests -against the stack top when querying the stack. -For instance, a C function can query its third argument -without the need to first check whether there is a third argument, -that is, without the need to check whether 3 is a valid index. - - -<p> -For functions that can be called with acceptable indices, -any non-valid index is treated as if it -contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>, -which behaves like a nil value. - - - - - -<h2>4.4 – <a name="4.4">C Closures</a></h2> - -<p> -When a C function is created, -it is possible to associate some values with it, -thus creating a <em>C closure</em> -(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>); -these values are called <em>upvalues</em> and are -accessible to the function whenever it is called. - - -<p> -Whenever a C function is called, -its upvalues are located at specific pseudo-indices. -These pseudo-indices are produced by the macro -<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>. -The first upvalue associated with a function is at index -<code>lua_upvalueindex(1)</code>, and so on. -Any access to <code>lua_upvalueindex(<em>n</em>)</code>, -where <em>n</em> is greater than the number of upvalues of the -current function -(but not greater than 256, -which is one plus the maximum number of upvalues in a closure), -produces an acceptable but invalid index. - - - - - -<h2>4.5 – <a name="4.5">Registry</a></h2> - -<p> -Lua provides a <em>registry</em>, -a predefined table that can be used by any C code to -store whatever Lua values it needs to store. -The registry table is always located at pseudo-index -<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>. -Any C library can store data into this table, -but it must take care to choose keys -that are different from those used -by other libraries, to avoid collisions. -Typically, you should use as key a string containing your library name, -or a light userdata with the address of a C object in your code, -or any Lua object created by your code. -As with variable names, -string keys starting with an underscore followed by -uppercase letters are reserved for Lua. - - -<p> -The integer keys in the registry are used -by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>) -and by some predefined values. -Therefore, integer keys must not be used for other purposes. - - -<p> -When you create a new Lua state, -its registry comes with some predefined values. -These predefined values are indexed with integer keys -defined as constants in <code>lua.h</code>. -The following constants are defined: - -<ul> -<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has -the main thread of the state. -(The main thread is the one created together with the state.) -</li> - -<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has -the global environment. -</li> -</ul> - - - - -<h2>4.6 – <a name="4.6">Error Handling in C</a></h2> - -<p> -Internally, Lua uses the C <code>longjmp</code> facility to handle errors. -(Lua will use exceptions if you compile it as C++; -search for <code>LUAI_THROW</code> in the source code for details.) -When Lua faces any error -(such as a memory allocation error or a type error) -it <em>raises</em> an error; -that is, it does a long jump. -A <em>protected environment</em> uses <code>setjmp</code> -to set a recovery point; -any error jumps to the most recent active recovery point. - - -<p> -Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>. - - -<p> -Most functions in the API can raise an error, -for instance due to a memory allocation error. -The documentation for each function indicates whether -it can raise errors. - - -<p> -If an error happens outside any protected environment, -Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) -and then calls <code>abort</code>, -thus exiting the host application. -Your panic function can avoid this exit by -never returning -(e.g., doing a long jump to your own recovery point outside Lua). - - -<p> -The panic function, -as its name implies, -is a mechanism of last resort. -Programs should avoid it. -As a general rule, -when a C function is called by Lua with a Lua state, -it can do whatever it wants on that Lua state, -as it should be already protected. -However, -when C code operates on other Lua states -(e.g., a Lua argument to the function, -a Lua state stored in the registry, or -the result of <a href="#lua_newthread"><code>lua_newthread</code></a>), -it should use them only in API calls that cannot raise errors. - - -<p> -The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>); -in particular, the error object is at the top of the stack. -However, there is no guarantee about stack space. -To push anything on the stack, -the panic function must first check the available space (see <a href="#4.2">§4.2</a>). - - - - - -<h2>4.7 – <a name="4.7">Handling Yields in C</a></h2> - -<p> -Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine. -Therefore, if a C function <code>foo</code> calls an API function -and this API function yields -(directly or indirectly by calling another function that yields), -Lua cannot return to <code>foo</code> any more, -because the <code>longjmp</code> removes its frame from the C stack. - - -<p> -To avoid this kind of problem, -Lua raises an error whenever it tries to yield across an API call, -except for three functions: -<a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>. -All those functions receive a <em>continuation function</em> -(as a parameter named <code>k</code>) to continue execution after a yield. - - -<p> -We need to set some terminology to explain continuations. -We have a C function called from Lua which we will call -the <em>original function</em>. -This original function then calls one of those three functions in the C API, -which we will call the <em>callee function</em>, -that then yields the current thread. -(This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>, -or when the callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"><code>lua_pcallk</code></a> -and the function called by them yields.) - - -<p> -Suppose the running thread yields while executing the callee function. -After the thread resumes, -it eventually will finish running the callee function. -However, -the callee function cannot return to the original function, -because its frame in the C stack was destroyed by the yield. -Instead, Lua calls a <em>continuation function</em>, -which was given as an argument to the callee function. -As the name implies, -the continuation function should continue the task -of the original function. - - -<p> -As an illustration, consider the following function: - -<pre> - int original_function (lua_State *L) { - ... /* code 1 */ - status = lua_pcall(L, n, m, h); /* calls Lua */ - ... /* code 2 */ - } -</pre><p> -Now we want to allow -the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield. -First, we can rewrite our function like here: - -<pre> - int k (lua_State *L, int status, lua_KContext ctx) { - ... /* code 2 */ - } - - int original_function (lua_State *L) { - ... /* code 1 */ - return k(L, lua_pcall(L, n, m, h), ctx); - } -</pre><p> -In the above code, -the new function <code>k</code> is a -<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>), -which should do all the work that the original function -was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>. -Now, we must inform Lua that it must call <code>k</code> if the Lua code -being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way -(errors or yielding), -so we rewrite the code as here, -replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>: - -<pre> - int original_function (lua_State *L) { - ... /* code 1 */ - return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1); - } -</pre><p> -Note the external, explicit call to the continuation: -Lua will call the continuation only if needed, that is, -in case of errors or resuming after a yield. -If the called function returns normally without ever yielding, -<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally. -(Of course, instead of calling the continuation in that case, -you can do the equivalent work directly inside the original function.) - - -<p> -Besides the Lua state, -the continuation function has two other parameters: -the final status of the call plus the context value (<code>ctx</code>) that -was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>. -(Lua does not use this context value; -it only passes this value from the original function to the -continuation function.) -For <a href="#lua_pcallk"><code>lua_pcallk</code></a>, -the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>, -except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield -(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>). -For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>, -the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation. -(For these two functions, -Lua will not call the continuation in case of errors, -because they do not handle errors.) -Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>, -you should call the continuation function -with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status. -(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling -directly the continuation function, -because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.) - - -<p> -Lua treats the continuation function as if it were the original function. -The continuation function receives the same Lua stack -from the original function, -in the same state it would be if the callee function had returned. -(For instance, -after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are -removed from the stack and replaced by the results from the call.) -It also has the same upvalues. -Whatever it returns is handled by Lua as if it were the return -of the original function. - - - - - -<h2>4.8 – <a name="4.8">Functions and Types</a></h2> - -<p> -Here we list all functions and types from the C API in -alphabetical order. -Each function has an indicator like this: -<span class="apii">[-o, +p, <em>x</em>]</span> - - -<p> -The first field, <code>o</code>, -is how many elements the function pops from the stack. -The second field, <code>p</code>, -is how many elements the function pushes onto the stack. -(Any function always pushes its results after popping its arguments.) -A field in the form <code>x|y</code> means the function can push (or pop) -<code>x</code> or <code>y</code> elements, -depending on the situation; -an interrogation mark '<code>?</code>' means that -we cannot know how many elements the function pops/pushes -by looking only at its arguments -(e.g., they may depend on what is on the stack). -The third field, <code>x</code>, -tells whether the function may raise errors: -'<code>-</code>' means the function never raises any error; -'<code>m</code>' means the function may raise out-of-memory errors -and errors running a <code>__gc</code> metamethod; -'<code>e</code>' means the function may raise any errors -(it can run arbitrary Lua code, -either directly or through metamethods); -'<code>v</code>' means the function may raise an error on purpose. - - - -<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_absindex (lua_State *L, int idx);</pre> - -<p> -Converts the acceptable index <code>idx</code> -into an equivalent absolute index -(that is, one that does not depend on the stack top). - - - - - -<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3> -<pre>typedef void * (*lua_Alloc) (void *ud, - void *ptr, - size_t osize, - size_t nsize);</pre> - -<p> -The type of the memory-allocation function used by Lua states. -The allocator function must provide a -functionality similar to <code>realloc</code>, -but not exactly the same. -Its arguments are -<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>; -<code>ptr</code>, a pointer to the block being allocated/reallocated/freed; -<code>osize</code>, the original size of the block or some code about what -is being allocated; -and <code>nsize</code>, the new size of the block. - - -<p> -When <code>ptr</code> is not <code>NULL</code>, -<code>osize</code> is the size of the block pointed by <code>ptr</code>, -that is, the size given when it was allocated or reallocated. - - -<p> -When <code>ptr</code> is <code>NULL</code>, -<code>osize</code> encodes the kind of object that Lua is allocating. -<code>osize</code> is any of -<a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, -<a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when) -Lua is creating a new object of that type. -When <code>osize</code> is some other value, -Lua is allocating memory for something else. - - -<p> -Lua assumes the following behavior from the allocator function: - - -<p> -When <code>nsize</code> is zero, -the allocator must behave like <code>free</code> -and return <code>NULL</code>. - - -<p> -When <code>nsize</code> is not zero, -the allocator must behave like <code>realloc</code>. -The allocator returns <code>NULL</code> -if and only if it cannot fulfill the request. -Lua assumes that the allocator never fails when -<code>osize >= nsize</code>. - - -<p> -Here is a simple implementation for the allocator function. -It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>. - -<pre> - static void *l_alloc (void *ud, void *ptr, size_t osize, - size_t nsize) { - (void)ud; (void)osize; /* not used */ - if (nsize == 0) { - free(ptr); - return NULL; - } - else - return realloc(ptr, nsize); - } -</pre><p> -Note that Standard C ensures -that <code>free(NULL)</code> has no effect and that -<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>. -This code assumes that <code>realloc</code> does not fail when shrinking a block. -(Although Standard C does not ensure this behavior, -it seems to be a safe assumption.) - - - - - -<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p> -<span class="apii">[-(2|1), +1, <em>e</em>]</span> -<pre>void lua_arith (lua_State *L, int op);</pre> - -<p> -Performs an arithmetic or bitwise operation over the two values -(or one, in the case of negations) -at the top of the stack, -with the value at the top being the second operand, -pops these values, and pushes the result of the operation. -The function follows the semantics of the corresponding Lua operator -(that is, it may call metamethods). - - -<p> -The value of <code>op</code> must be one of the following constants: - -<ul> - -<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li> -<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li> -<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li> -<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li> -<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li> -<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li> -<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li> -<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li> -<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li> -<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&</code>)</li> -<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li> -<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li> -<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li> -<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li> - -</ul> - - - - -<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre> - -<p> -Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>). - - - - - -<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p> -<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span> -<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre> - -<p> -Calls a function. - - -<p> -To call a function you must use the following protocol: -first, the function to be called is pushed onto the stack; -then, the arguments to the function are pushed -in direct order; -that is, the first argument is pushed first. -Finally you call <a href="#lua_call"><code>lua_call</code></a>; -<code>nargs</code> is the number of arguments that you pushed onto the stack. -All arguments and the function value are popped from the stack -when the function is called. -The function results are pushed onto the stack when the function returns. -The number of results is adjusted to <code>nresults</code>, -unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>. -In this case, all results from the function are pushed; -Lua takes care that the returned values fit into the stack space, -but it does not ensure any extra space in the stack. -The function results are pushed onto the stack in direct order -(the first result is pushed first), -so that after the call the last result is on the top of the stack. - - -<p> -Any error inside the called function is propagated upwards -(with a <code>longjmp</code>). - - -<p> -The following example shows how the host program can do the -equivalent to this Lua code: - -<pre> - a = f("how", t.x, 14) -</pre><p> -Here it is in C: - -<pre> - lua_getglobal(L, "f"); /* function to be called */ - lua_pushliteral(L, "how"); /* 1st argument */ - lua_getglobal(L, "t"); /* table to be indexed */ - lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ - lua_remove(L, -2); /* remove 't' from the stack */ - lua_pushinteger(L, 14); /* 3rd argument */ - lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ - lua_setglobal(L, "a"); /* set global 'a' */ -</pre><p> -Note that the code above is <em>balanced</em>: -at its end, the stack is back to its original configuration. -This is considered good programming practice. - - - - - -<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p> -<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span> -<pre>void lua_callk (lua_State *L, - int nargs, - int nresults, - lua_KContext ctx, - lua_KFunction k);</pre> - -<p> -This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>, -but allows the called function to yield (see <a href="#4.7">§4.7</a>). - - - - - -<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3> -<pre>typedef int (*lua_CFunction) (lua_State *L);</pre> - -<p> -Type for C functions. - - -<p> -In order to communicate properly with Lua, -a C function must use the following protocol, -which defines the way parameters and results are passed: -a C function receives its arguments from Lua in its stack -in direct order (the first argument is pushed first). -So, when the function starts, -<code>lua_gettop(L)</code> returns the number of arguments received by the function. -The first argument (if any) is at index 1 -and its last argument is at index <code>lua_gettop(L)</code>. -To return values to Lua, a C function just pushes them onto the stack, -in direct order (the first result is pushed first), -and returns the number of results. -Any other value in the stack below the results will be properly -discarded by Lua. -Like a Lua function, a C function called by Lua can also return -many results. - - -<p> -As an example, the following function receives a variable number -of numeric arguments and returns their average and their sum: - -<pre> - static int foo (lua_State *L) { - int n = lua_gettop(L); /* number of arguments */ - lua_Number sum = 0.0; - int i; - for (i = 1; i <= n; i++) { - if (!lua_isnumber(L, i)) { - lua_pushliteral(L, "incorrect argument"); - lua_error(L); - } - sum += lua_tonumber(L, i); - } - lua_pushnumber(L, sum/n); /* first result */ - lua_pushnumber(L, sum); /* second result */ - return 2; /* number of results */ - } -</pre> - - - - -<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_checkstack (lua_State *L, int n);</pre> - -<p> -Ensures that the stack has space for at least <code>n</code> extra slots -(that is, that you can safely push up to <code>n</code> values into it). -It returns false if it cannot fulfill the request, -either because it would cause the stack -to be larger than a fixed maximum size -(typically at least several thousand elements) or -because it cannot allocate memory for the extra space. -This function never shrinks the stack; -if the stack already has space for the extra slots, -it is left unchanged. - - - - - -<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void lua_close (lua_State *L);</pre> - -<p> -Destroys all objects in the given Lua state -(calling the corresponding garbage-collection metamethods, if any) -and frees all dynamic memory used by this state. -In several platforms, you may not need to call this function, -because all resources are naturally released when the host program ends. -On the other hand, long-running programs that create multiple states, -such as daemons or web servers, -will probably need to close states as soon as they are not needed. - - - - - -<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p> -<span class="apii">[-0, +0, <em>e</em>]</span> -<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre> - -<p> -Compares two Lua values. -Returns 1 if the value at index <code>index1</code> satisfies <code>op</code> -when compared with the value at index <code>index2</code>, -following the semantics of the corresponding Lua operator -(that is, it may call metamethods). -Otherwise returns 0. -Also returns 0 if any of the indices is not valid. - - -<p> -The value of <code>op</code> must be one of the following constants: - -<ul> - -<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li> -<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li> -<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li> - -</ul> - - - - -<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p> -<span class="apii">[-n, +1, <em>e</em>]</span> -<pre>void lua_concat (lua_State *L, int n);</pre> - -<p> -Concatenates the <code>n</code> values at the top of the stack, -pops them, and leaves the result at the top. -If <code>n</code> is 1, the result is the single value on the stack -(that is, the function does nothing); -if <code>n</code> is 0, the result is the empty string. -Concatenation is performed following the usual semantics of Lua -(see <a href="#3.4.6">§3.4.6</a>). - - - - - -<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre> - -<p> -Copies the element at index <code>fromidx</code> -into the valid index <code>toidx</code>, -replacing the value at that position. -Values at other positions are not affected. - - - - - -<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre> - -<p> -Creates a new empty table and pushes it onto the stack. -Parameter <code>narr</code> is a hint for how many elements the table -will have as a sequence; -parameter <code>nrec</code> is a hint for how many other elements -the table will have. -Lua may use these hints to preallocate memory for the new table. -This preallocation is useful for performance when you know in advance -how many elements the table will have. -Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>. - - - - - -<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_dump (lua_State *L, - lua_Writer writer, - void *data, - int strip);</pre> - -<p> -Dumps a function as a binary chunk. -Receives a Lua function on the top of the stack -and produces a binary chunk that, -if loaded again, -results in a function equivalent to the one dumped. -As it produces parts of the chunk, -<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>) -with the given <code>data</code> -to write them. - - -<p> -If <code>strip</code> is true, -the binary representation may not include all debug information -about the function, -to save space. - - -<p> -The value returned is the error code returned by the last -call to the writer; -0 means no errors. - - -<p> -This function does not pop the Lua function from the stack. - - - - - -<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p> -<span class="apii">[-1, +0, <em>v</em>]</span> -<pre>int lua_error (lua_State *L);</pre> - -<p> -Generates a Lua error, -using the value at the top of the stack as the error object. -This function does a long jump, -and therefore never returns -(see <a href="#luaL_error"><code>luaL_error</code></a>). - - - - - -<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p> -<span class="apii">[-0, +0, <em>m</em>]</span> -<pre>int lua_gc (lua_State *L, int what, int data);</pre> - -<p> -Controls the garbage collector. - - -<p> -This function performs several tasks, -according to the value of the parameter <code>what</code>: - -<ul> - -<li><b><code>LUA_GCSTOP</code>: </b> -stops the garbage collector. -</li> - -<li><b><code>LUA_GCRESTART</code>: </b> -restarts the garbage collector. -</li> - -<li><b><code>LUA_GCCOLLECT</code>: </b> -performs a full garbage-collection cycle. -</li> - -<li><b><code>LUA_GCCOUNT</code>: </b> -returns the current amount of memory (in Kbytes) in use by Lua. -</li> - -<li><b><code>LUA_GCCOUNTB</code>: </b> -returns the remainder of dividing the current amount of bytes of -memory in use by Lua by 1024. -</li> - -<li><b><code>LUA_GCSTEP</code>: </b> -performs an incremental step of garbage collection. -</li> - -<li><b><code>LUA_GCSETPAUSE</code>: </b> -sets <code>data</code> as the new value -for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>) -and returns the previous value of the pause. -</li> - -<li><b><code>LUA_GCSETSTEPMUL</code>: </b> -sets <code>data</code> as the new value for the <em>step multiplier</em> of -the collector (see <a href="#2.5">§2.5</a>) -and returns the previous value of the step multiplier. -</li> - -<li><b><code>LUA_GCISRUNNING</code>: </b> -returns a boolean that tells whether the collector is running -(i.e., not stopped). -</li> - -</ul> - -<p> -For more details about these options, -see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>. - - - - - -<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre> - -<p> -Returns the memory-allocation function of a given state. -If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the -opaque pointer given when the memory-allocator function was set. - - - - - -<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p> -<span class="apii">[-0, +1, <em>e</em>]</span> -<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre> - -<p> -Pushes onto the stack the value <code>t[k]</code>, -where <code>t</code> is the value at the given index. -As in Lua, this function may trigger a metamethod -for the "index" event (see <a href="#2.4">§2.4</a>). - - -<p> -Returns the type of the pushed value. - - - - - -<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void *lua_getextraspace (lua_State *L);</pre> - -<p> -Returns a pointer to a raw memory area associated with the -given Lua state. -The application can use this area for any purpose; -Lua does not use it for anything. - - -<p> -Each new thread has this area initialized with a copy -of the area of the main thread. - - -<p> -By default, this area has the size of a pointer to void, -but you can recompile Lua with a different size for this area. -(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.) - - - - - -<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p> -<span class="apii">[-0, +1, <em>e</em>]</span> -<pre>int lua_getglobal (lua_State *L, const char *name);</pre> - -<p> -Pushes onto the stack the value of the global <code>name</code>. -Returns the type of that value. - - - - - -<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p> -<span class="apii">[-0, +1, <em>e</em>]</span> -<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre> - -<p> -Pushes onto the stack the value <code>t[i]</code>, -where <code>t</code> is the value at the given index. -As in Lua, this function may trigger a metamethod -for the "index" event (see <a href="#2.4">§2.4</a>). - - -<p> -Returns the type of the pushed value. - - - - - -<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p> -<span class="apii">[-0, +(0|1), –]</span> -<pre>int lua_getmetatable (lua_State *L, int index);</pre> - -<p> -If the value at the given index has a metatable, -the function pushes that metatable onto the stack and returns 1. -Otherwise, -the function returns 0 and pushes nothing on the stack. - - - - - -<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p> -<span class="apii">[-1, +1, <em>e</em>]</span> -<pre>int lua_gettable (lua_State *L, int index);</pre> - -<p> -Pushes onto the stack the value <code>t[k]</code>, -where <code>t</code> is the value at the given index -and <code>k</code> is the value at the top of the stack. - - -<p> -This function pops the key from the stack, -pushing the resulting value in its place. -As in Lua, this function may trigger a metamethod -for the "index" event (see <a href="#2.4">§2.4</a>). - - -<p> -Returns the type of the pushed value. - - - - - -<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_gettop (lua_State *L);</pre> - -<p> -Returns the index of the top element in the stack. -Because indices start at 1, -this result is equal to the number of elements in the stack; -in particular, 0 means an empty stack. - - - - - -<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>int lua_getuservalue (lua_State *L, int index);</pre> - -<p> -Pushes onto the stack the Lua value associated with the full userdata -at the given index. - - -<p> -Returns the type of the pushed value. - - - - - -<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p> -<span class="apii">[-1, +1, –]</span> -<pre>void lua_insert (lua_State *L, int index);</pre> - -<p> -Moves the top element into the given valid index, -shifting up the elements above this index to open space. -This function cannot be called with a pseudo-index, -because a pseudo-index is not an actual stack position. - - - - - -<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3> -<pre>typedef ... lua_Integer;</pre> - -<p> -The type of integers in Lua. - - -<p> -By default this type is <code>long long</code>, -(usually a 64-bit two-complement integer), -but that can be changed to <code>long</code> or <code>int</code> -(usually a 32-bit two-complement integer). -(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.) - - -<p> -Lua also defines the constants -<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>, -with the minimum and the maximum values that fit in this type. - - - - - -<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isboolean (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is a boolean, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_iscfunction (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is a C function, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isfunction (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is a function -(either C or Lua), and 0 otherwise. - - - - - -<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isinteger (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is an integer -(that is, the value is a number and is represented as an integer), -and 0 otherwise. - - - - - -<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_islightuserdata (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is a light userdata, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isnil (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is <b>nil</b>, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isnone (lua_State *L, int index);</pre> - -<p> -Returns 1 if the given index is not valid, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isnoneornil (lua_State *L, int index);</pre> - -<p> -Returns 1 if the given index is not valid -or if the value at this index is <b>nil</b>, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isnumber (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is a number -or a string convertible to a number, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isstring (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is a string -or a number (which is always convertible to a string), -and 0 otherwise. - - - - - -<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_istable (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is a table, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isthread (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is a thread, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isuserdata (lua_State *L, int index);</pre> - -<p> -Returns 1 if the value at the given index is a userdata -(either full or light), and 0 otherwise. - - - - - -<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_isyieldable (lua_State *L);</pre> - -<p> -Returns 1 if the given coroutine can yield, -and 0 otherwise. - - - - - -<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3> -<pre>typedef ... lua_KContext;</pre> - -<p> -The type for continuation-function contexts. -It must be a numeric type. -This type is defined as <code>intptr_t</code> -when <code>intptr_t</code> is available, -so that it can store pointers too. -Otherwise, it is defined as <code>ptrdiff_t</code>. - - - - - -<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3> -<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre> - -<p> -Type for continuation functions (see <a href="#4.7">§4.7</a>). - - - - - -<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p> -<span class="apii">[-0, +1, <em>e</em>]</span> -<pre>void lua_len (lua_State *L, int index);</pre> - -<p> -Returns the length of the value at the given index. -It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and -may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>). -The result is pushed on the stack. - - - - - -<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>int lua_load (lua_State *L, - lua_Reader reader, - void *data, - const char *chunkname, - const char *mode);</pre> - -<p> -Loads a Lua chunk without running it. -If there are no errors, -<code>lua_load</code> pushes the compiled chunk as a Lua -function on top of the stack. -Otherwise, it pushes an error message. - - -<p> -The return values of <code>lua_load</code> are: - -<ul> - -<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li> - -<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b> -syntax error during precompilation;</li> - -<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> -memory allocation (out-of-memory) error;</li> - -<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> -error while running a <code>__gc</code> metamethod. -(This error has no relation with the chunk being loaded. -It is generated by the garbage collector.) -</li> - -</ul> - -<p> -The <code>lua_load</code> function uses a user-supplied <code>reader</code> function -to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>). -The <code>data</code> argument is an opaque value passed to the reader function. - - -<p> -The <code>chunkname</code> argument gives a name to the chunk, -which is used for error messages and in debug information (see <a href="#4.9">§4.9</a>). - - -<p> -<code>lua_load</code> automatically detects whether the chunk is text or binary -and loads it accordingly (see program <code>luac</code>). -The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>, -with the addition that -a <code>NULL</code> value is equivalent to the string "<code>bt</code>". - - -<p> -<code>lua_load</code> uses the stack internally, -so the reader function must always leave the stack -unmodified when returning. - - -<p> -If the resulting function has upvalues, -its first upvalue is set to the value of the global environment -stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>). -When loading main chunks, -this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). -Other upvalues are initialized with <b>nil</b>. - - - - - -<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre> - -<p> -Creates a new thread running in a new, independent state. -Returns <code>NULL</code> if it cannot create the thread or the state -(due to lack of memory). -The argument <code>f</code> is the allocator function; -Lua does all memory allocation for this state -through this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>). -The second argument, <code>ud</code>, is an opaque pointer that Lua -passes to the allocator in every call. - - - - - -<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>void lua_newtable (lua_State *L);</pre> - -<p> -Creates a new empty table and pushes it onto the stack. -It is equivalent to <code>lua_createtable(L, 0, 0)</code>. - - - - - -<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>lua_State *lua_newthread (lua_State *L);</pre> - -<p> -Creates a new thread, pushes it on the stack, -and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread. -The new thread returned by this function shares with the original thread -its global environment, -but has an independent execution stack. - - -<p> -There is no explicit function to close or to destroy a thread. -Threads are subject to garbage collection, -like any Lua object. - - - - - -<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre> - -<p> -This function allocates a new block of memory with the given size, -pushes onto the stack a new full userdata with the block address, -and returns this address. -The host program can freely use this memory. - - - - - -<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p> -<span class="apii">[-1, +(2|0), <em>e</em>]</span> -<pre>int lua_next (lua_State *L, int index);</pre> - -<p> -Pops a key from the stack, -and pushes a key–value pair from the table at the given index -(the "next" pair after the given key). -If there are no more elements in the table, -then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing). - - -<p> -A typical traversal looks like this: - -<pre> - /* table is in the stack at index 't' */ - lua_pushnil(L); /* first key */ - while (lua_next(L, t) != 0) { - /* uses 'key' (at index -2) and 'value' (at index -1) */ - printf("%s - %s\n", - lua_typename(L, lua_type(L, -2)), - lua_typename(L, lua_type(L, -1))); - /* removes 'value'; keeps 'key' for next iteration */ - lua_pop(L, 1); - } -</pre> - -<p> -While traversing a table, -do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key, -unless you know that the key is actually a string. -Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change -the value at the given index; -this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>. - - -<p> -See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying -the table during its traversal. - - - - - -<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3> -<pre>typedef ... lua_Number;</pre> - -<p> -The type of floats in Lua. - - -<p> -By default this type is double, -but that can be changed to a single float or a long double. -(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.) - - - - - -<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3> -<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre> - -<p> -Converts a Lua float to a Lua integer. -This macro assumes that <code>n</code> has an integral value. -If that value is within the range of Lua integers, -it is converted to an integer and assigned to <code>*p</code>. -The macro results in a boolean indicating whether the -conversion was successful. -(Note that this range test can be tricky to do -correctly without this macro, -due to roundings.) - - -<p> -This macro may evaluate its arguments more than once. - - - - - -<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p> -<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> -<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre> - -<p> -Calls a function in protected mode. - - -<p> -Both <code>nargs</code> and <code>nresults</code> have the same meaning as -in <a href="#lua_call"><code>lua_call</code></a>. -If there are no errors during the call, -<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>. -However, if there is any error, -<a href="#lua_pcall"><code>lua_pcall</code></a> catches it, -pushes a single value on the stack (the error object), -and returns an error code. -Like <a href="#lua_call"><code>lua_call</code></a>, -<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function -and its arguments from the stack. - - -<p> -If <code>msgh</code> is 0, -then the error object returned on the stack -is exactly the original error object. -Otherwise, <code>msgh</code> is the stack index of a -<em>message handler</em>. -(This index cannot be a pseudo-index.) -In case of runtime errors, -this function will be called with the error object -and its return value will be the object -returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>. - - -<p> -Typically, the message handler is used to add more debug -information to the error object, such as a stack traceback. -Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>, -since by then the stack has unwound. - - -<p> -The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants -(defined in <code>lua.h</code>): - -<ul> - -<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b> -success.</li> - -<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b> -a runtime error. -</li> - -<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b> -memory allocation error. -For such errors, Lua does not call the message handler. -</li> - -<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b> -error while running the message handler. -</li> - -<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b> -error while running a <code>__gc</code> metamethod. -For such errors, Lua does not call the message handler -(as this kind of error typically has no relation -with the function being called). -</li> - -</ul> - - - - -<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p> -<span class="apii">[-(nargs + 1), +(nresults|1), –]</span> -<pre>int lua_pcallk (lua_State *L, - int nargs, - int nresults, - int msgh, - lua_KContext ctx, - lua_KFunction k);</pre> - -<p> -This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>, -but allows the called function to yield (see <a href="#4.7">§4.7</a>). - - - - - -<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p> -<span class="apii">[-n, +0, –]</span> -<pre>void lua_pop (lua_State *L, int n);</pre> - -<p> -Pops <code>n</code> elements from the stack. - - - - - -<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>void lua_pushboolean (lua_State *L, int b);</pre> - -<p> -Pushes a boolean value with value <code>b</code> onto the stack. - - - - - -<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p> -<span class="apii">[-n, +1, <em>m</em>]</span> -<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre> - -<p> -Pushes a new C closure onto the stack. - - -<p> -When a C function is created, -it is possible to associate some values with it, -thus creating a C closure (see <a href="#4.4">§4.4</a>); -these values are then accessible to the function whenever it is called. -To associate values with a C function, -first these values must be pushed onto the stack -(when there are multiple values, the first value is pushed first). -Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> -is called to create and push the C function onto the stack, -with the argument <code>n</code> telling how many values will be -associated with the function. -<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack. - - -<p> -The maximum value for <code>n</code> is 255. - - -<p> -When <code>n</code> is zero, -this function creates a <em>light C function</em>, -which is just a pointer to the C function. -In that case, it never raises a memory error. - - - - - -<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre> - -<p> -Pushes a C function onto the stack. -This function receives a pointer to a C function -and pushes onto the stack a Lua value of type <code>function</code> that, -when called, invokes the corresponding C function. - - -<p> -Any function to be callable by Lua must -follow the correct protocol to receive its parameters -and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). - - - - - -<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>e</em>]</span> -<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre> - -<p> -Pushes onto the stack a formatted string -and returns a pointer to this string. -It is similar to the ISO C function <code>sprintf</code>, -but has some important differences: - -<ul> - -<li> -You do not have to allocate space for the result: -the result is a Lua string and Lua takes care of memory allocation -(and deallocation, through garbage collection). -</li> - -<li> -The conversion specifiers are quite restricted. -There are no flags, widths, or precisions. -The conversion specifiers can only be -'<code>%%</code>' (inserts the character '<code>%</code>'), -'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions), -'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>), -'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>), -'<code>%p</code>' (inserts a pointer as a hexadecimal numeral), -'<code>%d</code>' (inserts an <code>int</code>), -'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and -'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence). -</li> - -</ul> - -<p> -Unlike other push functions, -this function checks for the stack space it needs, -including the slot for its result. - - - - - -<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>void lua_pushglobaltable (lua_State *L);</pre> - -<p> -Pushes the global environment onto the stack. - - - - - -<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre> - -<p> -Pushes an integer with value <code>n</code> onto the stack. - - - - - -<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre> - -<p> -Pushes a light userdata onto the stack. - - -<p> -Userdata represent C values in Lua. -A <em>light userdata</em> represents a pointer, a <code>void*</code>. -It is a value (like a number): -you do not create it, it has no individual metatable, -and it is not collected (as it was never created). -A light userdata is equal to "any" -light userdata with the same C address. - - - - - -<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre> - -<p> -This macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>, -but should be used only when <code>s</code> is a literal string. - - - - - -<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre> - -<p> -Pushes the string pointed to by <code>s</code> with size <code>len</code> -onto the stack. -Lua makes (or reuses) an internal copy of the given string, -so the memory at <code>s</code> can be freed or reused immediately after -the function returns. -The string can contain any binary data, -including embedded zeros. - - -<p> -Returns a pointer to the internal copy of the string. - - - - - -<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>void lua_pushnil (lua_State *L);</pre> - -<p> -Pushes a nil value onto the stack. - - - - - -<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre> - -<p> -Pushes a float with value <code>n</code> onto the stack. - - - - - -<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre> - -<p> -Pushes the zero-terminated string pointed to by <code>s</code> -onto the stack. -Lua makes (or reuses) an internal copy of the given string, -so the memory at <code>s</code> can be freed or reused immediately after -the function returns. - - -<p> -Returns a pointer to the internal copy of the string. - - -<p> -If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>. - - - - - -<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>int lua_pushthread (lua_State *L);</pre> - -<p> -Pushes the thread represented by <code>L</code> onto the stack. -Returns 1 if this thread is the main thread of its state. - - - - - -<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>void lua_pushvalue (lua_State *L, int index);</pre> - -<p> -Pushes a copy of the element at the given index -onto the stack. - - - - - -<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>const char *lua_pushvfstring (lua_State *L, - const char *fmt, - va_list argp);</pre> - -<p> -Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code> -instead of a variable number of arguments. - - - - - -<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre> - -<p> -Returns 1 if the two values in indices <code>index1</code> and -<code>index2</code> are primitively equal -(that is, without calling the <code>__eq</code> metamethod). -Otherwise returns 0. -Also returns 0 if any of the indices are not valid. - - - - - -<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p> -<span class="apii">[-1, +1, –]</span> -<pre>int lua_rawget (lua_State *L, int index);</pre> - -<p> -Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access -(i.e., without metamethods). - - - - - -<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre> - -<p> -Pushes onto the stack the value <code>t[n]</code>, -where <code>t</code> is the table at the given index. -The access is raw, -that is, it does not invoke the <code>__index</code> metamethod. - - -<p> -Returns the type of the pushed value. - - - - - -<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre> - -<p> -Pushes onto the stack the value <code>t[k]</code>, -where <code>t</code> is the table at the given index and -<code>k</code> is the pointer <code>p</code> represented as a light userdata. -The access is raw; -that is, it does not invoke the <code>__index</code> metamethod. - - -<p> -Returns the type of the pushed value. - - - - - -<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>size_t lua_rawlen (lua_State *L, int index);</pre> - -<p> -Returns the raw "length" of the value at the given index: -for strings, this is the string length; -for tables, this is the result of the length operator ('<code>#</code>') -with no metamethods; -for userdata, this is the size of the block of memory allocated -for the userdata; -for other values, it is 0. - - - - - -<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p> -<span class="apii">[-2, +0, <em>m</em>]</span> -<pre>void lua_rawset (lua_State *L, int index);</pre> - -<p> -Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment -(i.e., without metamethods). - - - - - -<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p> -<span class="apii">[-1, +0, <em>m</em>]</span> -<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre> - -<p> -Does the equivalent of <code>t[i] = v</code>, -where <code>t</code> is the table at the given index -and <code>v</code> is the value at the top of the stack. - - -<p> -This function pops the value from the stack. -The assignment is raw, -that is, it does not invoke the <code>__newindex</code> metamethod. - - - - - -<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p> -<span class="apii">[-1, +0, <em>m</em>]</span> -<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre> - -<p> -Does the equivalent of <code>t[p] = v</code>, -where <code>t</code> is the table at the given index, -<code>p</code> is encoded as a light userdata, -and <code>v</code> is the value at the top of the stack. - - -<p> -This function pops the value from the stack. -The assignment is raw, -that is, it does not invoke <code>__newindex</code> metamethod. - - - - - -<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3> -<pre>typedef const char * (*lua_Reader) (lua_State *L, - void *data, - size_t *size);</pre> - -<p> -The reader function used by <a href="#lua_load"><code>lua_load</code></a>. -Every time it needs another piece of the chunk, -<a href="#lua_load"><code>lua_load</code></a> calls the reader, -passing along its <code>data</code> parameter. -The reader must return a pointer to a block of memory -with a new piece of the chunk -and set <code>size</code> to the block size. -The block must exist until the reader function is called again. -To signal the end of the chunk, -the reader must return <code>NULL</code> or set <code>size</code> to zero. -The reader function may return pieces of any size greater than zero. - - - - - -<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p> -<span class="apii">[-0, +0, <em>e</em>]</span> -<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre> - -<p> -Sets the C function <code>f</code> as the new value of global <code>name</code>. -It is defined as a macro: - -<pre> - #define lua_register(L,n,f) \ - (lua_pushcfunction(L, f), lua_setglobal(L, n)) -</pre> - - - - -<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p> -<span class="apii">[-1, +0, –]</span> -<pre>void lua_remove (lua_State *L, int index);</pre> - -<p> -Removes the element at the given valid index, -shifting down the elements above this index to fill the gap. -This function cannot be called with a pseudo-index, -because a pseudo-index is not an actual stack position. - - - - - -<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p> -<span class="apii">[-1, +0, –]</span> -<pre>void lua_replace (lua_State *L, int index);</pre> - -<p> -Moves the top element into the given valid index -without shifting any element -(therefore replacing the value at that given index), -and then pops the top element. - - - - - -<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p> -<span class="apii">[-?, +?, –]</span> -<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre> - -<p> -Starts and resumes a coroutine in the given thread <code>L</code>. - - -<p> -To start a coroutine, -you push onto the thread stack the main function plus any arguments; -then you call <a href="#lua_resume"><code>lua_resume</code></a>, -with <code>nargs</code> being the number of arguments. -This call returns when the coroutine suspends or finishes its execution. -When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>, -or all values returned by the body function. -<a href="#lua_resume"><code>lua_resume</code></a> returns -<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields, -<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution -without errors, -or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>). - - -<p> -In case of errors, -the stack is not unwound, -so you can use the debug API over it. -The error object is on the top of the stack. - - -<p> -To resume a coroutine, -you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>, -put on its stack only the values to -be passed as results from <code>yield</code>, -and then call <a href="#lua_resume"><code>lua_resume</code></a>. - - -<p> -The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>. -If there is no such coroutine, -this parameter can be <code>NULL</code>. - - - - - -<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void lua_rotate (lua_State *L, int idx, int n);</pre> - -<p> -Rotates the stack elements between the valid index <code>idx</code> -and the top of the stack. -The elements are rotated <code>n</code> positions in the direction of the top, -for a positive <code>n</code>, -or <code>-n</code> positions in the direction of the bottom, -for a negative <code>n</code>. -The absolute value of <code>n</code> must not be greater than the size -of the slice being rotated. -This function cannot be called with a pseudo-index, -because a pseudo-index is not an actual stack position. - - - - - -<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre> - -<p> -Changes the allocator function of a given state to <code>f</code> -with user data <code>ud</code>. - - - - - -<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p> -<span class="apii">[-1, +0, <em>e</em>]</span> -<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre> - -<p> -Does the equivalent to <code>t[k] = v</code>, -where <code>t</code> is the value at the given index -and <code>v</code> is the value at the top of the stack. - - -<p> -This function pops the value from the stack. -As in Lua, this function may trigger a metamethod -for the "newindex" event (see <a href="#2.4">§2.4</a>). - - - - - -<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p> -<span class="apii">[-1, +0, <em>e</em>]</span> -<pre>void lua_setglobal (lua_State *L, const char *name);</pre> - -<p> -Pops a value from the stack and -sets it as the new value of global <code>name</code>. - - - - - -<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p> -<span class="apii">[-1, +0, <em>e</em>]</span> -<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre> - -<p> -Does the equivalent to <code>t[n] = v</code>, -where <code>t</code> is the value at the given index -and <code>v</code> is the value at the top of the stack. - - -<p> -This function pops the value from the stack. -As in Lua, this function may trigger a metamethod -for the "newindex" event (see <a href="#2.4">§2.4</a>). - - - - - -<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p> -<span class="apii">[-1, +0, –]</span> -<pre>void lua_setmetatable (lua_State *L, int index);</pre> - -<p> -Pops a table from the stack and -sets it as the new metatable for the value at the given index. - - - - - -<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p> -<span class="apii">[-2, +0, <em>e</em>]</span> -<pre>void lua_settable (lua_State *L, int index);</pre> - -<p> -Does the equivalent to <code>t[k] = v</code>, -where <code>t</code> is the value at the given index, -<code>v</code> is the value at the top of the stack, -and <code>k</code> is the value just below the top. - - -<p> -This function pops both the key and the value from the stack. -As in Lua, this function may trigger a metamethod -for the "newindex" event (see <a href="#2.4">§2.4</a>). - - - - - -<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p> -<span class="apii">[-?, +?, –]</span> -<pre>void lua_settop (lua_State *L, int index);</pre> - -<p> -Accepts any index, or 0, -and sets the stack top to this index. -If the new top is larger than the old one, -then the new elements are filled with <b>nil</b>. -If <code>index</code> is 0, then all stack elements are removed. - - - - - -<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p> -<span class="apii">[-1, +0, –]</span> -<pre>void lua_setuservalue (lua_State *L, int index);</pre> - -<p> -Pops a value from the stack and sets it as -the new value associated to the full userdata at the given index. - - - - - -<hr><h3><a name="lua_State"><code>lua_State</code></a></h3> -<pre>typedef struct lua_State lua_State;</pre> - -<p> -An opaque structure that points to a thread and indirectly -(through the thread) to the whole state of a Lua interpreter. -The Lua library is fully reentrant: -it has no global variables. -All information about a state is accessible through this structure. - - -<p> -A pointer to this structure must be passed as the first argument to -every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>, -which creates a Lua state from scratch. - - - - - -<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_status (lua_State *L);</pre> - -<p> -Returns the status of the thread <code>L</code>. - - -<p> -The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread, -an error code if the thread finished the execution -of a <a href="#lua_resume"><code>lua_resume</code></a> with an error, -or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended. - - -<p> -You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>. -You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> -(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> -(to resume a coroutine). - - - - - -<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre> - -<p> -Converts the zero-terminated string <code>s</code> to a number, -pushes that number into the stack, -and returns the total size of the string, -that is, its length plus one. -The conversion can result in an integer or a float, -according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). -The string may have leading and trailing spaces and a sign. -If the string is not a valid numeral, -returns 0 and pushes nothing. -(Note that the result can be used as a boolean, -true if the conversion succeeds.) - - - - - -<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_toboolean (lua_State *L, int index);</pre> - -<p> -Converts the Lua value at the given index to a C boolean -value (0 or 1). -Like all tests in Lua, -<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value -different from <b>false</b> and <b>nil</b>; -otherwise it returns false. -(If you want to accept only actual boolean values, -use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.) - - - - - -<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre> - -<p> -Converts a value at the given index to a C function. -That value must be a C function; -otherwise, returns <code>NULL</code>. - - - - - -<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre> - -<p> -Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>. - - - - - -<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre> - -<p> -Converts the Lua value at the given index -to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>. -The Lua value must be an integer, -or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>); -otherwise, <code>lua_tointegerx</code> returns 0. - - -<p> -If <code>isnum</code> is not <code>NULL</code>, -its referent is assigned a boolean value that -indicates whether the operation succeeded. - - - - - -<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p> -<span class="apii">[-0, +0, <em>m</em>]</span> -<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre> - -<p> -Converts the Lua value at the given index to a C string. -If <code>len</code> is not <code>NULL</code>, -it sets <code>*len</code> with the string length. -The Lua value must be a string or a number; -otherwise, the function returns <code>NULL</code>. -If the value is a number, -then <code>lua_tolstring</code> also -<em>changes the actual value in the stack to a string</em>. -(This change confuses <a href="#lua_next"><code>lua_next</code></a> -when <code>lua_tolstring</code> is applied to keys during a table traversal.) - - -<p> -<code>lua_tolstring</code> returns a pointer -to a string inside the Lua state. -This string always has a zero ('<code>\0</code>') -after its last character (as in C), -but can contain other zeros in its body. - - -<p> -Because Lua has garbage collection, -there is no guarantee that the pointer returned by <code>lua_tolstring</code> -will be valid after the corresponding Lua value is removed from the stack. - - - - - -<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre> - -<p> -Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>. - - - - - -<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre> - -<p> -Converts the Lua value at the given index -to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>). -The Lua value must be a number or a string convertible to a number -(see <a href="#3.4.3">§3.4.3</a>); -otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0. - - -<p> -If <code>isnum</code> is not <code>NULL</code>, -its referent is assigned a boolean value that -indicates whether the operation succeeded. - - - - - -<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>const void *lua_topointer (lua_State *L, int index);</pre> - -<p> -Converts the value at the given index to a generic -C pointer (<code>void*</code>). -The value can be a userdata, a table, a thread, or a function; -otherwise, <code>lua_topointer</code> returns <code>NULL</code>. -Different objects will give different pointers. -There is no way to convert the pointer back to its original value. - - -<p> -Typically this function is used only for hashing and debug information. - - - - - -<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p> -<span class="apii">[-0, +0, <em>m</em>]</span> -<pre>const char *lua_tostring (lua_State *L, int index);</pre> - -<p> -Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>. - - - - - -<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_State *lua_tothread (lua_State *L, int index);</pre> - -<p> -Converts the value at the given index to a Lua thread -(represented as <code>lua_State*</code>). -This value must be a thread; -otherwise, the function returns <code>NULL</code>. - - - - - -<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void *lua_touserdata (lua_State *L, int index);</pre> - -<p> -If the value at the given index is a full userdata, -returns its block address. -If the value is a light userdata, -returns its pointer. -Otherwise, returns <code>NULL</code>. - - - - - -<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_type (lua_State *L, int index);</pre> - -<p> -Returns the type of the value in the given valid index, -or <code>LUA_TNONE</code> for a non-valid (but acceptable) index. -The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants -defined in <code>lua.h</code>: -<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0), -<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>, -<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>, -<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, -<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, -<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>, -<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, -<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>, -and -<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>. - - - - - -<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>const char *lua_typename (lua_State *L, int tp);</pre> - -<p> -Returns the name of the type encoded by the value <code>tp</code>, -which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>. - - - - - -<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3> -<pre>typedef ... lua_Unsigned;</pre> - -<p> -The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>. - - - - - -<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_upvalueindex (int i);</pre> - -<p> -Returns the pseudo-index that represents the <code>i</code>-th upvalue of -the running function (see <a href="#4.4">§4.4</a>). - - - - - -<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>const lua_Number *lua_version (lua_State *L);</pre> - -<p> -Returns the address of the version number -(a C static variable) -stored in the Lua core. -When called with a valid <a href="#lua_State"><code>lua_State</code></a>, -returns the address of the version used to create that state. -When called with <code>NULL</code>, -returns the address of the version running the call. - - - - - -<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3> -<pre>typedef int (*lua_Writer) (lua_State *L, - const void* p, - size_t sz, - void* ud);</pre> - -<p> -The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>. -Every time it produces another piece of chunk, -<a href="#lua_dump"><code>lua_dump</code></a> calls the writer, -passing along the buffer to be written (<code>p</code>), -its size (<code>sz</code>), -and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>. - - -<p> -The writer returns an error code: -0 means no errors; -any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from -calling the writer again. - - - - - -<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p> -<span class="apii">[-?, +?, –]</span> -<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre> - -<p> -Exchange values between different threads of the same state. - - -<p> -This function pops <code>n</code> values from the stack <code>from</code>, -and pushes them onto the stack <code>to</code>. - - - - - -<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p> -<span class="apii">[-?, +?, <em>e</em>]</span> -<pre>int lua_yield (lua_State *L, int nresults);</pre> - -<p> -This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>, -but it has no continuation (see <a href="#4.7">§4.7</a>). -Therefore, when the thread resumes, -it continues the function that called -the function calling <code>lua_yield</code>. - - - - - -<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p> -<span class="apii">[-?, +?, <em>e</em>]</span> -<pre>int lua_yieldk (lua_State *L, - int nresults, - lua_KContext ctx, - lua_KFunction k);</pre> - -<p> -Yields a coroutine (thread). - - -<p> -When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>, -the running coroutine suspends its execution, -and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns. -The parameter <code>nresults</code> is the number of values from the stack -that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>. - - -<p> -When the coroutine is resumed again, -Lua calls the given continuation function <code>k</code> to continue -the execution of the C function that yielded (see <a href="#4.7">§4.7</a>). -This continuation function receives the same stack -from the previous function, -with the <code>n</code> results removed and -replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>. -Moreover, -the continuation function receives the value <code>ctx</code> -that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>. - - -<p> -Usually, this function does not return; -when the coroutine eventually resumes, -it continues executing the continuation function. -However, there is one special case, -which is when this function is called -from inside a line or a count hook (see <a href="#4.9">§4.9</a>). -In that case, <code>lua_yieldk</code> should be called with no continuation -(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results, -and the hook should return immediately after the call. -Lua will yield and, -when the coroutine resumes again, -it will continue the normal execution -of the (Lua) function that triggered the hook. - - -<p> -This function can raise an error if it is called from a thread -with a pending C call with no continuation function, -or it is called from a thread that is not running inside a resume -(e.g., the main thread). - - - - - - - -<h2>4.9 – <a name="4.9">The Debug Interface</a></h2> - -<p> -Lua has no built-in debugging facilities. -Instead, it offers a special interface -by means of functions and <em>hooks</em>. -This interface allows the construction of different -kinds of debuggers, profilers, and other tools -that need "inside information" from the interpreter. - - - -<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3> -<pre>typedef struct lua_Debug { - int event; - const char *name; /* (n) */ - const char *namewhat; /* (n) */ - const char *what; /* (S) */ - const char *source; /* (S) */ - int currentline; /* (l) */ - int linedefined; /* (S) */ - int lastlinedefined; /* (S) */ - unsigned char nups; /* (u) number of upvalues */ - unsigned char nparams; /* (u) number of parameters */ - char isvararg; /* (u) */ - char istailcall; /* (t) */ - char short_src[LUA_IDSIZE]; /* (S) */ - /* private part */ - <em>other fields</em> -} lua_Debug;</pre> - -<p> -A structure used to carry different pieces of -information about a function or an activation record. -<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part -of this structure, for later use. -To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information, -call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. - - -<p> -The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning: - -<ul> - -<li><b><code>source</code>: </b> -the name of the chunk that created the function. -If <code>source</code> starts with a '<code>@</code>', -it means that the function was defined in a file where -the file name follows the '<code>@</code>'. -If <code>source</code> starts with a '<code>=</code>', -the remainder of its contents describe the source in a user-dependent manner. -Otherwise, -the function was defined in a string where -<code>source</code> is that string. -</li> - -<li><b><code>short_src</code>: </b> -a "printable" version of <code>source</code>, to be used in error messages. -</li> - -<li><b><code>linedefined</code>: </b> -the line number where the definition of the function starts. -</li> - -<li><b><code>lastlinedefined</code>: </b> -the line number where the definition of the function ends. -</li> - -<li><b><code>what</code>: </b> -the string <code>"Lua"</code> if the function is a Lua function, -<code>"C"</code> if it is a C function, -<code>"main"</code> if it is the main part of a chunk. -</li> - -<li><b><code>currentline</code>: </b> -the current line where the given function is executing. -When no line information is available, -<code>currentline</code> is set to -1. -</li> - -<li><b><code>name</code>: </b> -a reasonable name for the given function. -Because functions in Lua are first-class values, -they do not have a fixed name: -some functions can be the value of multiple global variables, -while others can be stored only in a table field. -The <code>lua_getinfo</code> function checks how the function was -called to find a suitable name. -If it cannot find a name, -then <code>name</code> is set to <code>NULL</code>. -</li> - -<li><b><code>namewhat</code>: </b> -explains the <code>name</code> field. -The value of <code>namewhat</code> can be -<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, -<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string), -according to how the function was called. -(Lua uses the empty string when no other option seems to apply.) -</li> - -<li><b><code>istailcall</code>: </b> -true if this function invocation was called by a tail call. -In this case, the caller of this level is not in the stack. -</li> - -<li><b><code>nups</code>: </b> -the number of upvalues of the function. -</li> - -<li><b><code>nparams</code>: </b> -the number of fixed parameters of the function -(always 0 for C functions). -</li> - -<li><b><code>isvararg</code>: </b> -true if the function is a vararg function -(always true for C functions). -</li> - -</ul> - - - - -<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_Hook lua_gethook (lua_State *L);</pre> - -<p> -Returns the current hook function. - - - - - -<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_gethookcount (lua_State *L);</pre> - -<p> -Returns the current hook count. - - - - - -<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_gethookmask (lua_State *L);</pre> - -<p> -Returns the current hook mask. - - - - - -<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p> -<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span> -<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre> - -<p> -Gets information about a specific function or function invocation. - - -<p> -To get information about a function invocation, -the parameter <code>ar</code> must be a valid activation record that was -filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or -given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). - - -<p> -To get information about a function, you push it onto the stack -and start the <code>what</code> string with the character '<code>></code>'. -(In that case, -<code>lua_getinfo</code> pops the function from the top of the stack.) -For instance, to know in which line a function <code>f</code> was defined, -you can write the following code: - -<pre> - lua_Debug ar; - lua_getglobal(L, "f"); /* get global 'f' */ - lua_getinfo(L, ">S", &ar); - printf("%d\n", ar.linedefined); -</pre> - -<p> -Each character in the string <code>what</code> -selects some fields of the structure <code>ar</code> to be filled or -a value to be pushed on the stack: - -<ul> - -<li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>; -</li> - -<li><b>'<code>S</code>': </b> -fills in the fields <code>source</code>, <code>short_src</code>, -<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>; -</li> - -<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>; -</li> - -<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>; -</li> - -<li><b>'<code>u</code>': </b> fills in the fields -<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>; -</li> - -<li><b>'<code>f</code>': </b> -pushes onto the stack the function that is -running at the given level; -</li> - -<li><b>'<code>L</code>': </b> -pushes onto the stack a table whose indices are the -numbers of the lines that are valid on the function. -(A <em>valid line</em> is a line with some associated code, -that is, a line where you can put a break point. -Non-valid lines include empty lines and comments.) - - -<p> -If this option is given together with option '<code>f</code>', -its table is pushed after the function. -</li> - -</ul> - -<p> -This function returns 0 on error -(for instance, an invalid option in <code>what</code>). - - - - - -<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p> -<span class="apii">[-0, +(0|1), –]</span> -<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre> - -<p> -Gets information about a local variable of -a given activation record or a given function. - - -<p> -In the first case, -the parameter <code>ar</code> must be a valid activation record that was -filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or -given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>). -The index <code>n</code> selects which local variable to inspect; -see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices -and names. - - -<p> -<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack -and returns its name. - - -<p> -In the second case, <code>ar</code> must be <code>NULL</code> and the function -to be inspected must be at the top of the stack. -In this case, only parameters of Lua functions are visible -(as there is no information about what variables are active) -and no values are pushed onto the stack. - - -<p> -Returns <code>NULL</code> (and pushes nothing) -when the index is greater than -the number of active local variables. - - - - - -<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre> - -<p> -Gets information about the interpreter runtime stack. - - -<p> -This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with -an identification of the <em>activation record</em> -of the function executing at a given level. -Level 0 is the current running function, -whereas level <em>n+1</em> is the function that has called level <em>n</em> -(except for tail calls, which do not count on the stack). -When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1; -when called with a level greater than the stack depth, -it returns 0. - - - - - -<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p> -<span class="apii">[-0, +(0|1), –]</span> -<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre> - -<p> -Gets information about the <code>n</code>-th upvalue -of the closure at index <code>funcindex</code>. -It pushes the upvalue's value onto the stack -and returns its name. -Returns <code>NULL</code> (and pushes nothing) -when the index <code>n</code> is greater than the number of upvalues. - - -<p> -For C functions, this function uses the empty string <code>""</code> -as a name for all upvalues. -(For Lua functions, -upvalues are the external local variables that the function uses, -and that are consequently included in its closure.) - - -<p> -Upvalues have no particular order, -as they are active through the whole function. -They are numbered in an arbitrary order. - - - - - -<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3> -<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre> - -<p> -Type for debugging hook functions. - - -<p> -Whenever a hook is called, its <code>ar</code> argument has its field -<code>event</code> set to the specific event that triggered the hook. -Lua identifies these events with the following constants: -<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>, -<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>, -and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>. -Moreover, for line events, the field <code>currentline</code> is also set. -To get the value of any other field in <code>ar</code>, -the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>. - - -<p> -For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>, -the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call; -in this case, there will be no corresponding return event. - - -<p> -While Lua is running a hook, it disables other calls to hooks. -Therefore, if a hook calls back Lua to execute a function or a chunk, -this execution occurs without any calls to hooks. - - -<p> -Hook functions cannot have continuations, -that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>, -<a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>. - - -<p> -Hook functions can yield under the following conditions: -Only count and line events can yield; -to yield, a hook function must finish its execution -calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero -(that is, with no values). - - - - - -<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre> - -<p> -Sets the debugging hook function. - - -<p> -Argument <code>f</code> is the hook function. -<code>mask</code> specifies on which events the hook will be called: -it is formed by a bitwise OR of the constants -<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>, -<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>, -<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>, -and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>. -The <code>count</code> argument is only meaningful when the mask -includes <code>LUA_MASKCOUNT</code>. -For each event, the hook is called as explained below: - -<ul> - -<li><b>The call hook: </b> is called when the interpreter calls a function. -The hook is called just after Lua enters the new function, -before the function gets its arguments. -</li> - -<li><b>The return hook: </b> is called when the interpreter returns from a function. -The hook is called just before Lua leaves the function. -There is no standard way to access the values -to be returned by the function. -</li> - -<li><b>The line hook: </b> is called when the interpreter is about to -start the execution of a new line of code, -or when it jumps back in the code (even to the same line). -(This event only happens while Lua is executing a Lua function.) -</li> - -<li><b>The count hook: </b> is called after the interpreter executes every -<code>count</code> instructions. -(This event only happens while Lua is executing a Lua function.) -</li> - -</ul> - -<p> -A hook is disabled by setting <code>mask</code> to zero. - - - - - -<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p> -<span class="apii">[-(0|1), +0, –]</span> -<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre> - -<p> -Sets the value of a local variable of a given activation record. -It assigns the value at the top of the stack -to the variable and returns its name. -It also pops the value from the stack. - - -<p> -Returns <code>NULL</code> (and pops nothing) -when the index is greater than -the number of active local variables. - - -<p> -Parameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>. - - - - - -<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p> -<span class="apii">[-(0|1), +0, –]</span> -<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre> - -<p> -Sets the value of a closure's upvalue. -It assigns the value at the top of the stack -to the upvalue and returns its name. -It also pops the value from the stack. - - -<p> -Returns <code>NULL</code> (and pops nothing) -when the index <code>n</code> is greater than the number of upvalues. - - -<p> -Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>. - - - - - -<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre> - -<p> -Returns a unique identifier for the upvalue numbered <code>n</code> -from the closure at index <code>funcindex</code>. - - -<p> -These unique identifiers allow a program to check whether different -closures share upvalues. -Lua closures that share an upvalue -(that is, that access a same external local variable) -will return identical ids for those upvalue indices. - - -<p> -Parameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>, -but <code>n</code> cannot be greater than the number of upvalues. - - - - - -<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, - int funcindex2, int n2);</pre> - -<p> -Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code> -refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>. - - - - - - - -<h1>5 – <a name="5">The Auxiliary Library</a></h1> - -<p> - -The <em>auxiliary library</em> provides several convenient functions -to interface C with Lua. -While the basic API provides the primitive functions for all -interactions between C and Lua, -the auxiliary library provides higher-level functions for some -common tasks. - - -<p> -All functions and types from the auxiliary library -are defined in header file <code>lauxlib.h</code> and -have a prefix <code>luaL_</code>. - - -<p> -All functions in the auxiliary library are built on -top of the basic API, -and so they provide nothing that cannot be done with that API. -Nevertheless, the use of the auxiliary library ensures -more consistency to your code. - - -<p> -Several functions in the auxiliary library use internally some -extra stack slots. -When a function in the auxiliary library uses less than five slots, -it does not check the stack size; -it simply assumes that there are enough slots. - - -<p> -Several functions in the auxiliary library are used to -check C function arguments. -Because the error message is formatted for arguments -(e.g., "<code>bad argument #1</code>"), -you should not use these functions for other stack values. - - -<p> -Functions called <code>luaL_check*</code> -always raise an error if the check is not satisfied. - - - -<h2>5.1 – <a name="5.1">Functions and Types</a></h2> - -<p> -Here we list all functions and types from the auxiliary library -in alphabetical order. - - - -<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> -<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre> - -<p> -Adds the byte <code>c</code> to the buffer <code>B</code> -(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). - - - - - -<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> -<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre> - -<p> -Adds the string pointed to by <code>s</code> with length <code>l</code> to -the buffer <code>B</code> -(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). -The string can contain embedded zeros. - - - - - -<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p> -<span class="apii">[-?, +?, –]</span> -<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre> - -<p> -Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>) -a string of length <code>n</code> previously copied to the -buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>). - - - - - -<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> -<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre> - -<p> -Adds the zero-terminated string pointed to by <code>s</code> -to the buffer <code>B</code> -(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). - - - - - -<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p> -<span class="apii">[-1, +?, <em>m</em>]</span> -<pre>void luaL_addvalue (luaL_Buffer *B);</pre> - -<p> -Adds the value at the top of the stack -to the buffer <code>B</code> -(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). -Pops the value. - - -<p> -This is the only function on string buffers that can (and must) -be called with an extra element on the stack, -which is the value to be added to the buffer. - - - - - -<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>void luaL_argcheck (lua_State *L, - int cond, - int arg, - const char *extramsg);</pre> - -<p> -Checks whether <code>cond</code> is true. -If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>). - - - - - -<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre> - -<p> -Raises an error reporting a problem with argument <code>arg</code> -of the C function that called it, -using a standard message -that includes <code>extramsg</code> as a comment: - -<pre> - bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>) -</pre><p> -This function never returns. - - - - - -<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3> -<pre>typedef struct luaL_Buffer luaL_Buffer;</pre> - -<p> -Type for a <em>string buffer</em>. - - -<p> -A string buffer allows C code to build Lua strings piecemeal. -Its pattern of use is as follows: - -<ul> - -<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> - -<li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li> - -<li> -Then add string pieces to the buffer calling any of -the <code>luaL_add*</code> functions. -</li> - -<li> -Finish by calling <code>luaL_pushresult(&b)</code>. -This call leaves the final string on the top of the stack. -</li> - -</ul> - -<p> -If you know beforehand the total size of the resulting string, -you can use the buffer like this: - -<ul> - -<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li> - -<li>Then initialize it and preallocate a space of -size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li> - -<li>Then copy the string into that space.</li> - -<li> -Finish by calling <code>luaL_pushresultsize(&b, sz)</code>, -where <code>sz</code> is the total size of the resulting string -copied into that space. -</li> - -</ul> - -<p> -During its normal operation, -a string buffer uses a variable number of stack slots. -So, while using a buffer, you cannot assume that you know where -the top of the stack is. -You can use the stack between successive calls to buffer operations -as long as that use is balanced; -that is, -when you call a buffer operation, -the stack is at the same level -it was immediately after the previous buffer operation. -(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.) -After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its -level when the buffer was initialized, -plus the final string on its top. - - - - - -<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre> - -<p> -Initializes a buffer <code>B</code>. -This function does not allocate any space; -the buffer must be declared as a variable -(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). - - - - - -<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> -<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre> - -<p> -Equivalent to the sequence -<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>. - - - - - -<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p> -<span class="apii">[-0, +(0|1), <em>e</em>]</span> -<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre> - -<p> -Calls a metamethod. - - -<p> -If the object at index <code>obj</code> has a metatable and this -metatable has a field <code>e</code>, -this function calls this field passing the object as its only argument. -In this case this function returns true and pushes onto the -stack the value returned by the call. -If there is no metatable or no metamethod, -this function returns false (without pushing any value on the stack). - - - - - -<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>void luaL_checkany (lua_State *L, int arg);</pre> - -<p> -Checks whether the function has an argument -of any type (including <b>nil</b>) at position <code>arg</code>. - - - - - -<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre> - -<p> -Checks whether the function argument <code>arg</code> is an integer -(or can be converted to an integer) -and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>. - - - - - -<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre> - -<p> -Checks whether the function argument <code>arg</code> is a string -and returns this string; -if <code>l</code> is not <code>NULL</code> fills <code>*l</code> -with the string's length. - - -<p> -This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, -so all conversions and caveats of that function apply here. - - - - - -<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre> - -<p> -Checks whether the function argument <code>arg</code> is a number -and returns this number. - - - - - -<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>int luaL_checkoption (lua_State *L, - int arg, - const char *def, - const char *const lst[]);</pre> - -<p> -Checks whether the function argument <code>arg</code> is a string and -searches for this string in the array <code>lst</code> -(which must be NULL-terminated). -Returns the index in the array where the string was found. -Raises an error if the argument is not a string or -if the string cannot be found. - - -<p> -If <code>def</code> is not <code>NULL</code>, -the function uses <code>def</code> as a default value when -there is no argument <code>arg</code> or when this argument is <b>nil</b>. - - -<p> -This is a useful function for mapping strings to C enums. -(The usual convention in Lua libraries is -to use strings instead of numbers to select options.) - - - - - -<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre> - -<p> -Grows the stack size to <code>top + sz</code> elements, -raising an error if the stack cannot grow to that size. -<code>msg</code> is an additional text to go into the error message -(or <code>NULL</code> for no additional text). - - - - - -<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre> - -<p> -Checks whether the function argument <code>arg</code> is a string -and returns this string. - - -<p> -This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, -so all conversions and caveats of that function apply here. - - - - - -<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre> - -<p> -Checks whether the function argument <code>arg</code> has type <code>t</code>. -See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>. - - - - - -<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre> - -<p> -Checks whether the function argument <code>arg</code> is a userdata -of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and -returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>). - - - - - -<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>void luaL_checkversion (lua_State *L);</pre> - -<p> -Checks whether the core running the call, -the core that created the Lua state, -and the code making the call are all using the same version of Lua. -Also checks whether the core running the call -and the core that created the Lua state -are using the same address space. - - - - - -<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p> -<span class="apii">[-0, +?, <em>e</em>]</span> -<pre>int luaL_dofile (lua_State *L, const char *filename);</pre> - -<p> -Loads and runs the given file. -It is defined as the following macro: - -<pre> - (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) -</pre><p> -It returns false if there are no errors -or true in case of errors. - - - - - -<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p> -<span class="apii">[-0, +?, –]</span> -<pre>int luaL_dostring (lua_State *L, const char *str);</pre> - -<p> -Loads and runs the given string. -It is defined as the following macro: - -<pre> - (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) -</pre><p> -It returns false if there are no errors -or true in case of errors. - - - - - -<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre> - -<p> -Raises an error. -The error message format is given by <code>fmt</code> -plus any extra arguments, -following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>. -It also adds at the beginning of the message the file name and -the line number where the error occurred, -if this information is available. - - -<p> -This function never returns, -but it is an idiom to use it in C functions -as <code>return luaL_error(<em>args</em>)</code>. - - - - - -<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p> -<span class="apii">[-0, +3, <em>m</em>]</span> -<pre>int luaL_execresult (lua_State *L, int stat);</pre> - -<p> -This function produces the return values for -process-related functions in the standard library -(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>). - - - - - -<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p> -<span class="apii">[-0, +(1|3), <em>m</em>]</span> -<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre> - -<p> -This function produces the return values for -file-related functions in the standard library -(<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></a>, <a href="#pdf-file:seek"><code>file:seek</code></a>, etc.). - - - - - -<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p> -<span class="apii">[-0, +(0|1), <em>m</em>]</span> -<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre> - -<p> -Pushes onto the stack the field <code>e</code> from the metatable -of the object at index <code>obj</code> and returns the type of the pushed value. -If the object does not have a metatable, -or if the metatable does not have this field, -pushes nothing and returns <code>LUA_TNIL</code>. - - - - - -<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre> - -<p> -Pushes onto the stack the metatable associated with name <code>tname</code> -in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) -(<b>nil</b> if there is no metatable associated with that name). -Returns the type of the pushed value. - - - - - -<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p> -<span class="apii">[-0, +1, <em>e</em>]</span> -<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre> - -<p> -Ensures that the value <code>t[fname]</code>, -where <code>t</code> is the value at index <code>idx</code>, -is a table, -and pushes that table onto the stack. -Returns true if it finds a previous table there -and false if it creates a new table. - - - - - -<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>const char *luaL_gsub (lua_State *L, - const char *s, - const char *p, - const char *r);</pre> - -<p> -Creates a copy of string <code>s</code> by replacing -any occurrence of the string <code>p</code> -with the string <code>r</code>. -Pushes the resulting string on the stack and returns it. - - - - - -<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p> -<span class="apii">[-0, +0, <em>e</em>]</span> -<pre>lua_Integer luaL_len (lua_State *L, int index);</pre> - -<p> -Returns the "length" of the value at the given index -as a number; -it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>). -Raises an error if the result of the operation is not an integer. -(This case only can happen through metamethods.) - - - - - -<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>int luaL_loadbuffer (lua_State *L, - const char *buff, - size_t sz, - const char *name);</pre> - -<p> -Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>. - - - - - -<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>int luaL_loadbufferx (lua_State *L, - const char *buff, - size_t sz, - const char *name, - const char *mode);</pre> - -<p> -Loads a buffer as a Lua chunk. -This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the -buffer pointed to by <code>buff</code> with size <code>sz</code>. - - -<p> -This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. -<code>name</code> is the chunk name, -used for debug information and error messages. -The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. - - - - - -<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre> - -<p> -Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>. - - - - - -<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>int luaL_loadfilex (lua_State *L, const char *filename, - const char *mode);</pre> - -<p> -Loads a file as a Lua chunk. -This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file -named <code>filename</code>. -If <code>filename</code> is <code>NULL</code>, -then it loads from the standard input. -The first line in the file is ignored if it starts with a <code>#</code>. - - -<p> -The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>. - - -<p> -This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>, -but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a> -for file-related errors -(e.g., it cannot open or read the file). - - -<p> -As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; -it does not run it. - - - - - -<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p> -<span class="apii">[-0, +1, –]</span> -<pre>int luaL_loadstring (lua_State *L, const char *s);</pre> - -<p> -Loads a string as a Lua chunk. -This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in -the zero-terminated string <code>s</code>. - - -<p> -This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>. - - -<p> -Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk; -it does not run it. - - - - - -<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre> - -<p> -Creates a new table and registers there -the functions in list <code>l</code>. - - -<p> -It is implemented as the following macro: - -<pre> - (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0)) -</pre><p> -The array <code>l</code> must be the actual array, -not a pointer to it. - - - - - -<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre> - -<p> -Creates a new table with a size optimized -to store all entries in the array <code>l</code> -(but does not actually store them). -It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> -(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>). - - -<p> -It is implemented as a macro. -The array <code>l</code> must be the actual array, -not a pointer to it. - - - - - -<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre> - -<p> -If the registry already has the key <code>tname</code>, -returns 0. -Otherwise, -creates a new table to be used as a metatable for userdata, -adds to this new table the pair <code>__name = tname</code>, -adds to the registry the pair <code>[tname] = new table</code>, -and returns 1. -(The entry <code>__name</code> is used by some error-reporting functions.) - - -<p> -In both cases pushes onto the stack the final value associated -with <code>tname</code> in the registry. - - - - - -<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>lua_State *luaL_newstate (void);</pre> - -<p> -Creates a new Lua state. -It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an -allocator based on the standard C <code>realloc</code> function -and then sets a panic function (see <a href="#4.6">§4.6</a>) that prints -an error message to the standard error output in case of fatal -errors. - - -<p> -Returns the new state, -or <code>NULL</code> if there is a memory allocation error. - - - - - -<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p> -<span class="apii">[-0, +0, <em>e</em>]</span> -<pre>void luaL_openlibs (lua_State *L);</pre> - -<p> -Opens all standard Lua libraries into the given state. - - - - - -<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p> -<span class="apii">[-0, +0, <em>e</em>]</span> -<pre>T luaL_opt (L, func, arg, dflt);</pre> - -<p> -This macro is defined as follows: - -<pre> - (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg))) -</pre><p> -In words, if the argument <code>arg</code> is nil or absent, -the macro results in the default <code>dflt</code>. -Otherwise, it results in the result of calling <code>func</code> -with the state <code>L</code> and the argument index <code>arg</code> as -arguments. -Note that it evaluates the expression <code>dflt</code> only if needed. - - - - - -<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>lua_Integer luaL_optinteger (lua_State *L, - int arg, - lua_Integer d);</pre> - -<p> -If the function argument <code>arg</code> is an integer -(or convertible to an integer), -returns this integer. -If this argument is absent or is <b>nil</b>, -returns <code>d</code>. -Otherwise, raises an error. - - - - - -<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>const char *luaL_optlstring (lua_State *L, - int arg, - const char *d, - size_t *l);</pre> - -<p> -If the function argument <code>arg</code> is a string, -returns this string. -If this argument is absent or is <b>nil</b>, -returns <code>d</code>. -Otherwise, raises an error. - - -<p> -If <code>l</code> is not <code>NULL</code>, -fills the position <code>*l</code> with the result's length. -If the result is <code>NULL</code> -(only possible when returning <code>d</code> and <code>d == NULL</code>), -its length is considered zero. - - -<p> -This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result, -so all conversions and caveats of that function apply here. - - - - - -<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre> - -<p> -If the function argument <code>arg</code> is a number, -returns this number. -If this argument is absent or is <b>nil</b>, -returns <code>d</code>. -Otherwise, raises an error. - - - - - -<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p> -<span class="apii">[-0, +0, <em>v</em>]</span> -<pre>const char *luaL_optstring (lua_State *L, - int arg, - const char *d);</pre> - -<p> -If the function argument <code>arg</code> is a string, -returns this string. -If this argument is absent or is <b>nil</b>, -returns <code>d</code>. -Otherwise, raises an error. - - - - - -<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> -<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre> - -<p> -Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a> -with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>. - - - - - -<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p> -<span class="apii">[-?, +?, <em>m</em>]</span> -<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre> - -<p> -Returns an address to a space of size <code>sz</code> -where you can copy a string to be added to buffer <code>B</code> -(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>). -After copying the string into this space you must call -<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add -it to the buffer. - - - - - -<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p> -<span class="apii">[-?, +1, <em>m</em>]</span> -<pre>void luaL_pushresult (luaL_Buffer *B);</pre> - -<p> -Finishes the use of buffer <code>B</code> leaving the final string on -the top of the stack. - - - - - -<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p> -<span class="apii">[-?, +1, <em>m</em>]</span> -<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre> - -<p> -Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>. - - - - - -<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p> -<span class="apii">[-1, +0, <em>m</em>]</span> -<pre>int luaL_ref (lua_State *L, int t);</pre> - -<p> -Creates and returns a <em>reference</em>, -in the table at index <code>t</code>, -for the object at the top of the stack (and pops the object). - - -<p> -A reference is a unique integer key. -As long as you do not manually add integer keys into table <code>t</code>, -<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns. -You can retrieve an object referred by reference <code>r</code> -by calling <code>lua_rawgeti(L, t, r)</code>. -Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object. - - -<p> -If the object at the top of the stack is <b>nil</b>, -<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>. -The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different -from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>. - - - - - -<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3> -<pre>typedef struct luaL_Reg { - const char *name; - lua_CFunction func; -} luaL_Reg;</pre> - -<p> -Type for arrays of functions to be registered by -<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>. -<code>name</code> is the function name and <code>func</code> is a pointer to -the function. -Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry -in which both <code>name</code> and <code>func</code> are <code>NULL</code>. - - - - - -<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p> -<span class="apii">[-0, +1, <em>e</em>]</span> -<pre>void luaL_requiref (lua_State *L, const char *modname, - lua_CFunction openf, int glb);</pre> - -<p> -If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>, -calls function <code>openf</code> with string <code>modname</code> as an argument -and sets the call result in <code>package.loaded[modname]</code>, -as if that function has been called through <a href="#pdf-require"><code>require</code></a>. - - -<p> -If <code>glb</code> is true, -also stores the module into global <code>modname</code>. - - -<p> -Leaves a copy of the module on the stack. - - - - - -<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p> -<span class="apii">[-nup, +0, <em>m</em>]</span> -<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre> - -<p> -Registers all functions in the array <code>l</code> -(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack -(below optional upvalues, see next). - - -<p> -When <code>nup</code> is not zero, -all functions are created sharing <code>nup</code> upvalues, -which must be previously pushed on the stack -on top of the library table. -These values are popped from the stack after the registration. - - - - - -<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre> - -<p> -Sets the metatable of the object at the top of the stack -as the metatable associated with name <code>tname</code> -in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). - - - - - -<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3> -<pre>typedef struct luaL_Stream { - FILE *f; - lua_CFunction closef; -} luaL_Stream;</pre> - -<p> -The standard representation for file handles, -which is used by the standard I/O library. - - -<p> -A file handle is implemented as a full userdata, -with a metatable called <code>LUA_FILEHANDLE</code> -(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name). -The metatable is created by the I/O library -(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>). - - -<p> -This userdata must start with the structure <code>luaL_Stream</code>; -it can contain other data after this initial structure. -Field <code>f</code> points to the corresponding C stream -(or it can be <code>NULL</code> to indicate an incompletely created handle). -Field <code>closef</code> points to a Lua function -that will be called to close the stream -when the handle is closed or collected; -this function receives the file handle as its sole argument and -must return either <b>true</b> (in case of success) -or <b>nil</b> plus an error message (in case of error). -Once Lua calls this field, -it changes the field value to <code>NULL</code> -to signal that the handle is closed. - - - - - -<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p> -<span class="apii">[-0, +0, <em>m</em>]</span> -<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre> - -<p> -This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>, -except that, when the test fails, -it returns <code>NULL</code> instead of raising an error. - - - - - -<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p> -<span class="apii">[-0, +1, <em>e</em>]</span> -<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre> - -<p> -Converts any Lua value at the given index to a C string -in a reasonable format. -The resulting string is pushed onto the stack and also -returned by the function. -If <code>len</code> is not <code>NULL</code>, -the function also sets <code>*len</code> with the string length. - - -<p> -If the value has a metatable with a <code>__tostring</code> field, -then <code>luaL_tolstring</code> calls the corresponding metamethod -with the value as argument, -and uses the result of the call as its result. - - - - - -<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, - int level);</pre> - -<p> -Creates and pushes a traceback of the stack <code>L1</code>. -If <code>msg</code> is not <code>NULL</code> it is appended -at the beginning of the traceback. -The <code>level</code> parameter tells at which level -to start the traceback. - - - - - -<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>const char *luaL_typename (lua_State *L, int index);</pre> - -<p> -Returns the name of the type of the value at the given index. - - - - - -<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p> -<span class="apii">[-0, +0, –]</span> -<pre>void luaL_unref (lua_State *L, int t, int ref);</pre> - -<p> -Releases reference <code>ref</code> from the table at index <code>t</code> -(see <a href="#luaL_ref"><code>luaL_ref</code></a>). -The entry is removed from the table, -so that the referred object can be collected. -The reference <code>ref</code> is also freed to be used again. - - -<p> -If <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>, -<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing. - - - - - -<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p> -<span class="apii">[-0, +1, <em>m</em>]</span> -<pre>void luaL_where (lua_State *L, int lvl);</pre> - -<p> -Pushes onto the stack a string identifying the current position -of the control at level <code>lvl</code> in the call stack. -Typically this string has the following format: - -<pre> - <em>chunkname</em>:<em>currentline</em>: -</pre><p> -Level 0 is the running function, -level 1 is the function that called the running function, -etc. - - -<p> -This function is used to build a prefix for error messages. - - - - - - - -<h1>6 – <a name="6">Standard Libraries</a></h1> - -<p> -The standard Lua libraries provide useful functions -that are implemented directly through the C API. -Some of these functions provide essential services to the language -(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>); -others provide access to "outside" services (e.g., I/O); -and others could be implemented in Lua itself, -but are quite useful or have critical performance requirements that -deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>). - - -<p> -All libraries are implemented through the official C API -and are provided as separate C modules. -Currently, Lua has the following standard libraries: - -<ul> - -<li>basic library (<a href="#6.1">§6.1</a>);</li> - -<li>coroutine library (<a href="#6.2">§6.2</a>);</li> - -<li>package library (<a href="#6.3">§6.3</a>);</li> - -<li>string manipulation (<a href="#6.4">§6.4</a>);</li> - -<li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li> - -<li>table manipulation (<a href="#6.6">§6.6</a>);</li> - -<li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li> - -<li>input and output (<a href="#6.8">§6.8</a>);</li> - -<li>operating system facilities (<a href="#6.9">§6.9</a>);</li> - -<li>debug facilities (<a href="#6.10">§6.10</a>).</li> - -</ul><p> -Except for the basic and the package libraries, -each library provides all its functions as fields of a global table -or as methods of its objects. - - -<p> -To have access to these libraries, -the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function, -which opens all standard libraries. -Alternatively, -the host program can open them individually by using -<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call -<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library), -<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library), -<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library), -<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library), -<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library), -<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library), -<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library), -<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library), -<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library), -and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library). -These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>. - - - -<h2>6.1 – <a name="6.1">Basic Functions</a></h2> - -<p> -The basic library provides core functions to Lua. -If you do not include this library in your application, -you should check carefully whether you need to provide -implementations for some of its facilities. - - -<p> -<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3> - - -<p> -Calls <a href="#pdf-error"><code>error</code></a> if -the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>); -otherwise, returns all its arguments. -In case of error, -<code>message</code> is the error object; -when absent, it defaults to "<code>assertion failed!</code>" - - - - -<p> -<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3> - - -<p> -This function is a generic interface to the garbage collector. -It performs different functions according to its first argument, <code>opt</code>: - -<ul> - -<li><b>"<code>collect</code>": </b> -performs a full garbage-collection cycle. -This is the default option. -</li> - -<li><b>"<code>stop</code>": </b> -stops automatic execution of the garbage collector. -The collector will run only when explicitly invoked, -until a call to restart it. -</li> - -<li><b>"<code>restart</code>": </b> -restarts automatic execution of the garbage collector. -</li> - -<li><b>"<code>count</code>": </b> -returns the total memory in use by Lua in Kbytes. -The value has a fractional part, -so that it multiplied by 1024 -gives the exact number of bytes in use by Lua -(except for overflows). -</li> - -<li><b>"<code>step</code>": </b> -performs a garbage-collection step. -The step "size" is controlled by <code>arg</code>. -With a zero value, -the collector will perform one basic (indivisible) step. -For non-zero values, -the collector will perform as if that amount of memory -(in KBytes) had been allocated by Lua. -Returns <b>true</b> if the step finished a collection cycle. -</li> - -<li><b>"<code>setpause</code>": </b> -sets <code>arg</code> as the new value for the <em>pause</em> of -the collector (see <a href="#2.5">§2.5</a>). -Returns the previous value for <em>pause</em>. -</li> - -<li><b>"<code>setstepmul</code>": </b> -sets <code>arg</code> as the new value for the <em>step multiplier</em> of -the collector (see <a href="#2.5">§2.5</a>). -Returns the previous value for <em>step</em>. -</li> - -<li><b>"<code>isrunning</code>": </b> -returns a boolean that tells whether the collector is running -(i.e., not stopped). -</li> - -</ul> - - - -<p> -<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3> -Opens the named file and executes its contents as a Lua chunk. -When called without arguments, -<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). -Returns all values returned by the chunk. -In case of errors, <code>dofile</code> propagates the error -to its caller (that is, <code>dofile</code> does not run in protected mode). - - - - -<p> -<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3> -Terminates the last protected function called -and returns <code>message</code> as the error object. -Function <code>error</code> never returns. - - -<p> -Usually, <code>error</code> adds some information about the error position -at the beginning of the message, if the message is a string. -The <code>level</code> argument specifies how to get the error position. -With level 1 (the default), the error position is where the -<code>error</code> function was called. -Level 2 points the error to where the function -that called <code>error</code> was called; and so on. -Passing a level 0 avoids the addition of error position information -to the message. - - - - -<p> -<hr><h3><a name="pdf-_G"><code>_G</code></a></h3> -A global variable (not a function) that -holds the global environment (see <a href="#2.2">§2.2</a>). -Lua itself does not use this variable; -changing its value does not affect any environment, -nor vice versa. - - - - -<p> -<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3> - - -<p> -If <code>object</code> does not have a metatable, returns <b>nil</b>. -Otherwise, -if the object's metatable has a <code>__metatable</code> field, -returns the associated value. -Otherwise, returns the metatable of the given object. - - - - -<p> -<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3> - - -<p> -Returns three values (an iterator function, the table <code>t</code>, and 0) -so that the construction - -<pre> - for i,v in ipairs(t) do <em>body</em> end -</pre><p> -will iterate over the key–value pairs -(<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., -up to the first nil value. - - - - -<p> -<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3> - - -<p> -Loads a chunk. - - -<p> -If <code>chunk</code> is a string, the chunk is this string. -If <code>chunk</code> is a function, -<code>load</code> calls it repeatedly to get the chunk pieces. -Each call to <code>chunk</code> must return a string that concatenates -with previous results. -A return of an empty string, <b>nil</b>, or no value signals the end of the chunk. - - -<p> -If there are no syntactic errors, -returns the compiled chunk as a function; -otherwise, returns <b>nil</b> plus the error message. - - -<p> -If the resulting function has upvalues, -the first upvalue is set to the value of <code>env</code>, -if that parameter is given, -or to the value of the global environment. -Other upvalues are initialized with <b>nil</b>. -(When you load a main chunk, -the resulting function will always have exactly one upvalue, -the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>). -However, -when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>), -the resulting function can have an arbitrary number of upvalues.) -All upvalues are fresh, that is, -they are not shared with any other function. - - -<p> -<code>chunkname</code> is used as the name of the chunk for error messages -and debug information (see <a href="#4.9">§4.9</a>). -When absent, -it defaults to <code>chunk</code>, if <code>chunk</code> is a string, -or to "<code>=(load)</code>" otherwise. - - -<p> -The string <code>mode</code> controls whether the chunk can be text or binary -(that is, a precompiled chunk). -It may be the string "<code>b</code>" (only binary chunks), -"<code>t</code>" (only text chunks), -or "<code>bt</code>" (both binary and text). -The default is "<code>bt</code>". - - -<p> -Lua does not check the consistency of binary chunks. -Maliciously crafted binary chunks can crash -the interpreter. - - - - -<p> -<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3> - - -<p> -Similar to <a href="#pdf-load"><code>load</code></a>, -but gets the chunk from file <code>filename</code> -or from the standard input, -if no file name is given. - - - - -<p> -<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3> - - -<p> -Allows a program to traverse all fields of a table. -Its first argument is a table and its second argument -is an index in this table. -<code>next</code> returns the next index of the table -and its associated value. -When called with <b>nil</b> as its second argument, -<code>next</code> returns an initial index -and its associated value. -When called with the last index, -or with <b>nil</b> in an empty table, -<code>next</code> returns <b>nil</b>. -If the second argument is absent, then it is interpreted as <b>nil</b>. -In particular, -you can use <code>next(t)</code> to check whether a table is empty. - - -<p> -The order in which the indices are enumerated is not specified, -<em>even for numeric indices</em>. -(To traverse a table in numerical order, -use a numerical <b>for</b>.) - - -<p> -The behavior of <code>next</code> is undefined if, -during the traversal, -you assign any value to a non-existent field in the table. -You may however modify existing fields. -In particular, you may clear existing fields. - - - - -<p> -<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3> - - -<p> -If <code>t</code> has a metamethod <code>__pairs</code>, -calls it with <code>t</code> as argument and returns the first three -results from the call. - - -<p> -Otherwise, -returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>, -so that the construction - -<pre> - for k,v in pairs(t) do <em>body</em> end -</pre><p> -will iterate over all key–value pairs of table <code>t</code>. - - -<p> -See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying -the table during its traversal. - - - - -<p> -<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3> - - -<p> -Calls function <code>f</code> with -the given arguments in <em>protected mode</em>. -This means that any error inside <code>f</code> is not propagated; -instead, <code>pcall</code> catches the error -and returns a status code. -Its first result is the status code (a boolean), -which is true if the call succeeds without errors. -In such case, <code>pcall</code> also returns all results from the call, -after this first result. -In case of any error, <code>pcall</code> returns <b>false</b> plus the error message. - - - - -<p> -<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3> -Receives any number of arguments -and prints their values to <code>stdout</code>, -using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string. -<code>print</code> is not intended for formatted output, -but only as a quick way to show a value, -for instance for debugging. -For complete control over the output, -use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>. - - - - -<p> -<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3> -Checks whether <code>v1</code> is equal to <code>v2</code>, -without invoking the <code>__eq</code> metamethod. -Returns a boolean. - - - - -<p> -<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3> -Gets the real value of <code>table[index]</code>, -without invoking the <code>__index</code> metamethod. -<code>table</code> must be a table; -<code>index</code> may be any value. - - - - -<p> -<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3> -Returns the length of the object <code>v</code>, -which must be a table or a string, -without invoking the <code>__len</code> metamethod. -Returns an integer. - - - - -<p> -<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3> -Sets the real value of <code>table[index]</code> to <code>value</code>, -without invoking the <code>__newindex</code> metamethod. -<code>table</code> must be a table, -<code>index</code> any value different from <b>nil</b> and NaN, -and <code>value</code> any Lua value. - - -<p> -This function returns <code>table</code>. - - - - -<p> -<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3> - - -<p> -If <code>index</code> is a number, -returns all arguments after argument number <code>index</code>; -a negative number indexes from the end (-1 is the last argument). -Otherwise, <code>index</code> must be the string <code>"#"</code>, -and <code>select</code> returns the total number of extra arguments it received. - - - - -<p> -<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3> - - -<p> -Sets the metatable for the given table. -(To change the metatable of other types from Lua code, -you must use the debug library (<a href="#6.10">§6.10</a>).) -If <code>metatable</code> is <b>nil</b>, -removes the metatable of the given table. -If the original metatable has a <code>__metatable</code> field, -raises an error. - - -<p> -This function returns <code>table</code>. - - - - -<p> -<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3> - - -<p> -When called with no <code>base</code>, -<code>tonumber</code> tries to convert its argument to a number. -If the argument is already a number or -a string convertible to a number, -then <code>tonumber</code> returns this number; -otherwise, it returns <b>nil</b>. - - -<p> -The conversion of strings can result in integers or floats, -according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>). -(The string may have leading and trailing spaces and a sign.) - - -<p> -When called with <code>base</code>, -then <code>e</code> must be a string to be interpreted as -an integer numeral in that base. -The base may be any integer between 2 and 36, inclusive. -In bases above 10, the letter '<code>A</code>' (in either upper or lower case) -represents 10, '<code>B</code>' represents 11, and so forth, -with '<code>Z</code>' representing 35. -If the string <code>e</code> is not a valid numeral in the given base, -the function returns <b>nil</b>. - - - - -<p> -<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3> -Receives a value of any type and -converts it to a string in a human-readable format. -(For complete control of how numbers are converted, -use <a href="#pdf-string.format"><code>string.format</code></a>.) - - -<p> -If the metatable of <code>v</code> has a <code>__tostring</code> field, -then <code>tostring</code> calls the corresponding value -with <code>v</code> as argument, -and uses the result of the call as its result. - - - - -<p> -<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3> -Returns the type of its only argument, coded as a string. -The possible results of this function are -"<code>nil</code>" (a string, not the value <b>nil</b>), -"<code>number</code>", -"<code>string</code>", -"<code>boolean</code>", -"<code>table</code>", -"<code>function</code>", -"<code>thread</code>", -and "<code>userdata</code>". - - - - -<p> -<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3> - - -<p> -A global variable (not a function) that -holds a string containing the running Lua version. -The current value of this variable is "<code>Lua 5.3</code>". - - - - -<p> -<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3> - - -<p> -This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>, -except that it sets a new message handler <code>msgh</code>. - - - - - - - -<h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2> - -<p> -This library comprises the operations to manipulate coroutines, -which come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>. -See <a href="#2.6">§2.6</a> for a general description of coroutines. - - -<p> -<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3> - - -<p> -Creates a new coroutine, with body <code>f</code>. -<code>f</code> must be a function. -Returns this new coroutine, -an object with type <code>"thread"</code>. - - - - -<p> -<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3> - - -<p> -Returns true when the running coroutine can yield. - - -<p> -A running coroutine is yieldable if it is not the main thread and -it is not inside a non-yieldable C function. - - - - -<p> -<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3> - - -<p> -Starts or continues the execution of coroutine <code>co</code>. -The first time you resume a coroutine, -it starts running its body. -The values <code>val1</code>, ... are passed -as the arguments to the body function. -If the coroutine has yielded, -<code>resume</code> restarts it; -the values <code>val1</code>, ... are passed -as the results from the yield. - - -<p> -If the coroutine runs without any errors, -<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code> -(when the coroutine yields) or any values returned by the body function -(when the coroutine terminates). -If there is any error, -<code>resume</code> returns <b>false</b> plus the error message. - - - - -<p> -<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3> - - -<p> -Returns the running coroutine plus a boolean, -true when the running coroutine is the main one. - - - - -<p> -<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3> - - -<p> -Returns the status of coroutine <code>co</code>, as a string: -<code>"running"</code>, -if the coroutine is running (that is, it called <code>status</code>); -<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, -or if it has not started running yet; -<code>"normal"</code> if the coroutine is active but not running -(that is, it has resumed another coroutine); -and <code>"dead"</code> if the coroutine has finished its body function, -or if it has stopped with an error. - - - - -<p> -<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3> - - -<p> -Creates a new coroutine, with body <code>f</code>. -<code>f</code> must be a function. -Returns a function that resumes the coroutine each time it is called. -Any arguments passed to the function behave as the -extra arguments to <code>resume</code>. -Returns the same values returned by <code>resume</code>, -except the first boolean. -In case of error, propagates the error. - - - - -<p> -<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3> - - -<p> -Suspends the execution of the calling coroutine. -Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>. - - - - - - - -<h2>6.3 – <a name="6.3">Modules</a></h2> - -<p> -The package library provides basic -facilities for loading modules in Lua. -It exports one function directly in the global environment: -<a href="#pdf-require"><code>require</code></a>. -Everything else is exported in a table <a name="pdf-package"><code>package</code></a>. - - -<p> -<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3> - - -<p> -Loads the given module. -The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table -to determine whether <code>modname</code> is already loaded. -If it is, then <code>require</code> returns the value stored -at <code>package.loaded[modname]</code>. -Otherwise, it tries to find a <em>loader</em> for the module. - - -<p> -To find a loader, -<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence. -By changing this sequence, -we can change how <code>require</code> looks for a module. -The following explanation is based on the default configuration -for <a href="#pdf-package.searchers"><code>package.searchers</code></a>. - - -<p> -First <code>require</code> queries <code>package.preload[modname]</code>. -If it has a value, -this value (which must be a function) is the loader. -Otherwise <code>require</code> searches for a Lua loader using the -path stored in <a href="#pdf-package.path"><code>package.path</code></a>. -If that also fails, it searches for a C loader using the -path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>. -If that also fails, -it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>). - - -<p> -Once a loader is found, -<code>require</code> calls the loader with two arguments: -<code>modname</code> and an extra value dependent on how it got the loader. -(If the loader came from a file, -this extra value is the file name.) -If the loader returns any non-nil value, -<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>. -If the loader does not return a non-nil value and -has not assigned any value to <code>package.loaded[modname]</code>, -then <code>require</code> assigns <b>true</b> to this entry. -In any case, <code>require</code> returns the -final value of <code>package.loaded[modname]</code>. - - -<p> -If there is any error loading or running the module, -or if it cannot find any loader for the module, -then <code>require</code> raises an error. - - - - -<p> -<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3> - - -<p> -A string describing some compile-time configurations for packages. -This string is a sequence of lines: - -<ul> - -<li>The first line is the directory separator string. -Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li> - -<li>The second line is the character that separates templates in a path. -Default is '<code>;</code>'.</li> - -<li>The third line is the string that marks the -substitution points in a template. -Default is '<code>?</code>'.</li> - -<li>The fourth line is a string that, in a path in Windows, -is replaced by the executable's directory. -Default is '<code>!</code>'.</li> - -<li>The fifth line is a mark to ignore all text after it -when building the <code>luaopen_</code> function name. -Default is '<code>-</code>'.</li> - -</ul> - - - -<p> -<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3> - - -<p> -The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader. - - -<p> -Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way -it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>, -using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>, -or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>, -or a default path defined in <code>luaconf.h</code>. - - - - -<p> -<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3> - - -<p> -A table used by <a href="#pdf-require"><code>require</code></a> to control which -modules are already loaded. -When you require a module <code>modname</code> and -<code>package.loaded[modname]</code> is not false, -<a href="#pdf-require"><code>require</code></a> simply returns the value stored there. - - -<p> -This variable is only a reference to the real table; -assignments to this variable do not change the -table used by <a href="#pdf-require"><code>require</code></a>. - - - - -<p> -<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3> - - -<p> -Dynamically links the host program with the C library <code>libname</code>. - - -<p> -If <code>funcname</code> is "<code>*</code>", -then it only links with the library, -making the symbols exported by the library -available to other dynamically linked libraries. -Otherwise, -it looks for a function <code>funcname</code> inside the library -and returns this function as a C function. -So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype -(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>). - - -<p> -This is a low-level function. -It completely bypasses the package and module system. -Unlike <a href="#pdf-require"><code>require</code></a>, -it does not perform any path searching and -does not automatically adds extensions. -<code>libname</code> must be the complete file name of the C library, -including if necessary a path and an extension. -<code>funcname</code> must be the exact name exported by the C library -(which may depend on the C compiler and linker used). - - -<p> -This function is not supported by Standard C. -As such, it is only available on some platforms -(Windows, Linux, Mac OS X, Solaris, BSD, -plus other Unix systems that support the <code>dlfcn</code> standard). - - - - -<p> -<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3> - - -<p> -The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader. - - -<p> -At start-up, Lua initializes this variable with -the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or -the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or -with a default path defined in <code>luaconf.h</code>, -if those environment variables are not defined. -Any "<code>;;</code>" in the value of the environment variable -is replaced by the default path. - - - - -<p> -<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3> - - -<p> -A table to store loaders for specific modules -(see <a href="#pdf-require"><code>require</code></a>). - - -<p> -This variable is only a reference to the real table; -assignments to this variable do not change the -table used by <a href="#pdf-require"><code>require</code></a>. - - - - -<p> -<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3> - - -<p> -A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules. - - -<p> -Each entry in this table is a <em>searcher function</em>. -When looking for a module, -<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order, -with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its -sole parameter. -The function can return another function (the module <em>loader</em>) -plus an extra value that will be passed to that loader, -or a string explaining why it did not find that module -(or <b>nil</b> if it has nothing to say). - - -<p> -Lua initializes this table with four searcher functions. - - -<p> -The first searcher simply looks for a loader in the -<a href="#pdf-package.preload"><code>package.preload</code></a> table. - - -<p> -The second searcher looks for a loader as a Lua library, -using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>. -The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. - - -<p> -The third searcher looks for a loader as a C library, -using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>. -Again, -the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. -For instance, -if the C path is the string - -<pre> - "./?.so;./?.dll;/usr/local/?/init.so" -</pre><p> -the searcher for module <code>foo</code> -will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>, -and <code>/usr/local/foo/init.so</code>, in that order. -Once it finds a C library, -this searcher first uses a dynamic link facility to link the -application with the library. -Then it tries to find a C function inside the library to -be used as the loader. -The name of this C function is the string "<code>luaopen_</code>" -concatenated with a copy of the module name where each dot -is replaced by an underscore. -Moreover, if the module name has a hyphen, -its suffix after (and including) the first hyphen is removed. -For instance, if the module name is <code>a.b.c-v2.1</code>, -the function name will be <code>luaopen_a_b_c</code>. - - -<p> -The fourth searcher tries an <em>all-in-one loader</em>. -It searches the C path for a library for -the root name of the given module. -For instance, when requiring <code>a.b.c</code>, -it will search for a C library for <code>a</code>. -If found, it looks into it for an open function for -the submodule; -in our example, that would be <code>luaopen_a_b_c</code>. -With this facility, a package can pack several C submodules -into one single library, -with each submodule keeping its original open function. - - -<p> -All searchers except the first one (preload) return as the extra value -the file name where the module was found, -as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>. -The first searcher returns no extra value. - - - - -<p> -<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3> - - -<p> -Searches for the given <code>name</code> in the given <code>path</code>. - - -<p> -A path is a string containing a sequence of -<em>templates</em> separated by semicolons. -For each template, -the function replaces each interrogation mark (if any) -in the template with a copy of <code>name</code> -wherein all occurrences of <code>sep</code> -(a dot, by default) -were replaced by <code>rep</code> -(the system's directory separator, by default), -and then tries to open the resulting file name. - - -<p> -For instance, if the path is the string - -<pre> - "./?.lua;./?.lc;/usr/local/?/init.lua" -</pre><p> -the search for the name <code>foo.a</code> -will try to open the files -<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and -<code>/usr/local/foo/a/init.lua</code>, in that order. - - -<p> -Returns the resulting name of the first file that it can -open in read mode (after closing the file), -or <b>nil</b> plus an error message if none succeeds. -(This error message lists all file names it tried to open.) - - - - - - - -<h2>6.4 – <a name="6.4">String Manipulation</a></h2> - -<p> -This library provides generic functions for string manipulation, -such as finding and extracting substrings, and pattern matching. -When indexing a string in Lua, the first character is at position 1 -(not at 0, as in C). -Indices are allowed to be negative and are interpreted as indexing backwards, -from the end of the string. -Thus, the last character is at position -1, and so on. - - -<p> -The string library provides all its functions inside the table -<a name="pdf-string"><code>string</code></a>. -It also sets a metatable for strings -where the <code>__index</code> field points to the <code>string</code> table. -Therefore, you can use the string functions in object-oriented style. -For instance, <code>string.byte(s,i)</code> -can be written as <code>s:byte(i)</code>. - - -<p> -The string library assumes one-byte character encodings. - - -<p> -<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3> -Returns the internal numeric codes of the characters <code>s[i]</code>, -<code>s[i+1]</code>, ..., <code>s[j]</code>. -The default value for <code>i</code> is 1; -the default value for <code>j</code> is <code>i</code>. -These indices are corrected -following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>. - - -<p> -Numeric codes are not necessarily portable across platforms. - - - - -<p> -<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3> -Receives zero or more integers. -Returns a string with length equal to the number of arguments, -in which each character has the internal numeric code equal -to its corresponding argument. - - -<p> -Numeric codes are not necessarily portable across platforms. - - - - -<p> -<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3> - - -<p> -Returns a string containing a binary representation -(a <em>binary chunk</em>) -of the given function, -so that a later <a href="#pdf-load"><code>load</code></a> on this string returns -a copy of the function (but with new upvalues). -If <code>strip</code> is a true value, -the binary representation may not include all debug information -about the function, -to save space. - - -<p> -Functions with upvalues have only their number of upvalues saved. -When (re)loaded, -those upvalues receive fresh instances containing <b>nil</b>. -(You can use the debug library to serialize -and reload the upvalues of a function -in a way adequate to your needs.) - - - - -<p> -<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3> - - -<p> -Looks for the first match of -<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. -If it finds a match, then <code>find</code> returns the indices of <code>s</code> -where this occurrence starts and ends; -otherwise, it returns <b>nil</b>. -A third, optional numeric argument <code>init</code> specifies -where to start the search; -its default value is 1 and can be negative. -A value of <b>true</b> as a fourth, optional argument <code>plain</code> -turns off the pattern matching facilities, -so the function does a plain "find substring" operation, -with no characters in <code>pattern</code> being considered magic. -Note that if <code>plain</code> is given, then <code>init</code> must be given as well. - - -<p> -If the pattern has captures, -then in a successful match -the captured values are also returned, -after the two indices. - - - - -<p> -<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3> - - -<p> -Returns a formatted version of its variable number of arguments -following the description given in its first argument (which must be a string). -The format string follows the same rules as the ISO C function <code>sprintf</code>. -The only differences are that the options/modifiers -<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>, -and <code>p</code> are not supported -and that there is an extra option, <code>q</code>. - - -<p> -The <code>q</code> option formats a string between double quotes, -using escape sequences when necessary to ensure that -it can safely be read back by the Lua interpreter. -For instance, the call - -<pre> - string.format('%q', 'a string with "quotes" and \n new line') -</pre><p> -may produce the string: - -<pre> - "a string with \"quotes\" and \ - new line" -</pre> - -<p> -Options -<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>, -<code>G</code>, and <code>g</code> all expect a number as argument. -Options <code>c</code>, <code>d</code>, -<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> -expect an integer. -When Lua is compiled with a C89 compiler, -options <code>A</code> and <code>a</code> (hexadecimal floats) -do not support any modifier (flags, width, length). - - -<p> -Option <code>s</code> expects a string; -if its argument is not a string, -it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>. -If the option has any modifier (flags, width, length), -the string argument should not contain embedded zeros. - - - - -<p> -<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3> -Returns an iterator function that, -each time it is called, -returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) -over the string <code>s</code>. -If <code>pattern</code> specifies no captures, -then the whole match is produced in each call. - - -<p> -As an example, the following loop -will iterate over all the words from string <code>s</code>, -printing one per line: - -<pre> - s = "hello world from Lua" - for w in string.gmatch(s, "%a+") do - print(w) - end -</pre><p> -The next example collects all pairs <code>key=value</code> from the -given string into a table: - -<pre> - t = {} - s = "from=world, to=Lua" - for k, v in string.gmatch(s, "(%w+)=(%w+)") do - t[k] = v - end -</pre> - -<p> -For this function, a caret '<code>^</code>' at the start of a pattern does not -work as an anchor, as this would prevent the iteration. - - - - -<p> -<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3> -Returns a copy of <code>s</code> -in which all (or the first <code>n</code>, if given) -occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been -replaced by a replacement string specified by <code>repl</code>, -which can be a string, a table, or a function. -<code>gsub</code> also returns, as its second value, -the total number of matches that occurred. -The name <code>gsub</code> comes from <em>Global SUBstitution</em>. - - -<p> -If <code>repl</code> is a string, then its value is used for replacement. -The character <code>%</code> works as an escape character: -any sequence in <code>repl</code> of the form <code>%<em>d</em></code>, -with <em>d</em> between 1 and 9, -stands for the value of the <em>d</em>-th captured substring. -The sequence <code>%0</code> stands for the whole match. -The sequence <code>%%</code> stands for a single <code>%</code>. - - -<p> -If <code>repl</code> is a table, then the table is queried for every match, -using the first capture as the key. - - -<p> -If <code>repl</code> is a function, then this function is called every time a -match occurs, with all captured substrings passed as arguments, -in order. - - -<p> -In any case, -if the pattern specifies no captures, -then it behaves as if the whole pattern was inside a capture. - - -<p> -If the value returned by the table query or by the function call -is a string or a number, -then it is used as the replacement string; -otherwise, if it is <b>false</b> or <b>nil</b>, -then there is no replacement -(that is, the original match is kept in the string). - - -<p> -Here are some examples: - -<pre> - x = string.gsub("hello world", "(%w+)", "%1 %1") - --> x="hello hello world world" - - x = string.gsub("hello world", "%w+", "%0 %0", 1) - --> x="hello hello world" - - x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") - --> x="world hello Lua from" - - x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) - --> x="home = /home/roberto, user = roberto" - - x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) - return load(s)() - end) - --> x="4+5 = 9" - - local t = {name="lua", version="5.3"} - x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) - --> x="lua-5.3.tar.gz" -</pre> - - - -<p> -<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3> -Receives a string and returns its length. -The empty string <code>""</code> has length 0. -Embedded zeros are counted, -so <code>"a\000bc\000"</code> has length 5. - - - - -<p> -<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3> -Receives a string and returns a copy of this string with all -uppercase letters changed to lowercase. -All other characters are left unchanged. -The definition of what an uppercase letter is depends on the current locale. - - - - -<p> -<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3> -Looks for the first <em>match</em> of -<code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>. -If it finds one, then <code>match</code> returns -the captures from the pattern; -otherwise it returns <b>nil</b>. -If <code>pattern</code> specifies no captures, -then the whole match is returned. -A third, optional numeric argument <code>init</code> specifies -where to start the search; -its default value is 1 and can be negative. - - - - -<p> -<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3> - - -<p> -Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc. -packed (that is, serialized in binary form) -according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). - - - - -<p> -<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3> - - -<p> -Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a> -with the given format. -The format string cannot have the variable-length options -'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>). - - - - -<p> -<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3> -Returns a string that is the concatenation of <code>n</code> copies of -the string <code>s</code> separated by the string <code>sep</code>. -The default value for <code>sep</code> is the empty string -(that is, no separator). -Returns the empty string if <code>n</code> is not positive. - - -<p> -(Note that it is very easy to exhaust the memory of your machine -with a single call to this function.) - - - - -<p> -<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3> -Returns a string that is the string <code>s</code> reversed. - - - - -<p> -<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3> -Returns the substring of <code>s</code> that -starts at <code>i</code> and continues until <code>j</code>; -<code>i</code> and <code>j</code> can be negative. -If <code>j</code> is absent, then it is assumed to be equal to -1 -(which is the same as the string length). -In particular, -the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> -with length <code>j</code>, -and <code>string.sub(s, -i)</code> (for a positive <code>i</code>) -returns a suffix of <code>s</code> -with length <code>i</code>. - - -<p> -If, after the translation of negative indices, -<code>i</code> is less than 1, -it is corrected to 1. -If <code>j</code> is greater than the string length, -it is corrected to that length. -If, after these corrections, -<code>i</code> is greater than <code>j</code>, -the function returns the empty string. - - - - -<p> -<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3> - - -<p> -Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>) -according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>). -An optional <code>pos</code> marks where -to start reading in <code>s</code> (default is 1). -After the read values, -this function also returns the index of the first unread byte in <code>s</code>. - - - - -<p> -<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3> -Receives a string and returns a copy of this string with all -lowercase letters changed to uppercase. -All other characters are left unchanged. -The definition of what a lowercase letter is depends on the current locale. - - - - - -<h3>6.4.1 – <a name="6.4.1">Patterns</a></h3> - -<p> -Patterns in Lua are described by regular strings, -which are interpreted as patterns by the pattern-matching functions -<a href="#pdf-string.find"><code>string.find</code></a>, -<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>, -<a href="#pdf-string.gsub"><code>string.gsub</code></a>, -and <a href="#pdf-string.match"><code>string.match</code></a>. -This section describes the syntax and the meaning -(that is, what they match) of these strings. - - - -<h4>Character Class:</h4><p> -A <em>character class</em> is used to represent a set of characters. -The following combinations are allowed in describing a character class: - -<ul> - -<li><b><em>x</em>: </b> -(where <em>x</em> is not one of the <em>magic characters</em> -<code>^$()%.[]*+-?</code>) -represents the character <em>x</em> itself. -</li> - -<li><b><code>.</code>: </b> (a dot) represents all characters.</li> - -<li><b><code>%a</code>: </b> represents all letters.</li> - -<li><b><code>%c</code>: </b> represents all control characters.</li> - -<li><b><code>%d</code>: </b> represents all digits.</li> - -<li><b><code>%g</code>: </b> represents all printable characters except space.</li> - -<li><b><code>%l</code>: </b> represents all lowercase letters.</li> - -<li><b><code>%p</code>: </b> represents all punctuation characters.</li> - -<li><b><code>%s</code>: </b> represents all space characters.</li> - -<li><b><code>%u</code>: </b> represents all uppercase letters.</li> - -<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li> - -<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li> - -<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character) -represents the character <em>x</em>. -This is the standard way to escape the magic characters. -Any non-alphanumeric character -(including all punctuation characters, even the non-magical) -can be preceded by a '<code>%</code>' -when used to represent itself in a pattern. -</li> - -<li><b><code>[<em>set</em>]</code>: </b> -represents the class which is the union of all -characters in <em>set</em>. -A range of characters can be specified by -separating the end characters of the range, -in ascending order, with a '<code>-</code>'. -All classes <code>%</code><em>x</em> described above can also be used as -components in <em>set</em>. -All other characters in <em>set</em> represent themselves. -For example, <code>[%w_]</code> (or <code>[_%w]</code>) -represents all alphanumeric characters plus the underscore, -<code>[0-7]</code> represents the octal digits, -and <code>[0-7%l%-]</code> represents the octal digits plus -the lowercase letters plus the '<code>-</code>' character. - - -<p> -You can put a closing square bracket in a set -by positioning it as the first character in the set. -You can put a hyphen in a set -by positioning it as the first or the last character in the set. -(You can also use an escape for both cases.) - - -<p> -The interaction between ranges and classes is not defined. -Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> -have no meaning. -</li> - -<li><b><code>[^<em>set</em>]</code>: </b> -represents the complement of <em>set</em>, -where <em>set</em> is interpreted as above. -</li> - -</ul><p> -For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), -the corresponding uppercase letter represents the complement of the class. -For instance, <code>%S</code> represents all non-space characters. - - -<p> -The definitions of letter, space, and other character groups -depend on the current locale. -In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. - - - - - -<h4>Pattern Item:</h4><p> -A <em>pattern item</em> can be - -<ul> - -<li> -a single character class, -which matches any single character in the class; -</li> - -<li> -a single character class followed by '<code>*</code>', -which matches zero or more repetitions of characters in the class. -These repetition items will always match the longest possible sequence; -</li> - -<li> -a single character class followed by '<code>+</code>', -which matches one or more repetitions of characters in the class. -These repetition items will always match the longest possible sequence; -</li> - -<li> -a single character class followed by '<code>-</code>', -which also matches zero or more repetitions of characters in the class. -Unlike '<code>*</code>', -these repetition items will always match the shortest possible sequence; -</li> - -<li> -a single character class followed by '<code>?</code>', -which matches zero or one occurrence of a character in the class. -It always matches one occurrence if possible; -</li> - -<li> -<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; -such item matches a substring equal to the <em>n</em>-th captured string -(see below); -</li> - -<li> -<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; -such item matches strings that start with <em>x</em>, end with <em>y</em>, -and where the <em>x</em> and <em>y</em> are <em>balanced</em>. -This means that, if one reads the string from left to right, -counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, -the ending <em>y</em> is the first <em>y</em> where the count reaches 0. -For instance, the item <code>%b()</code> matches expressions with -balanced parentheses. -</li> - -<li> -<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>; -such item matches an empty string at any position such that -the next character belongs to <em>set</em> -and the previous character does not belong to <em>set</em>. -The set <em>set</em> is interpreted as previously described. -The beginning and the end of the subject are handled as if -they were the character '<code>\0</code>'. -</li> - -</ul> - - - - -<h4>Pattern:</h4><p> -A <em>pattern</em> is a sequence of pattern items. -A caret '<code>^</code>' at the beginning of a pattern anchors the match at the -beginning of the subject string. -A '<code>$</code>' at the end of a pattern anchors the match at the -end of the subject string. -At other positions, -'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves. - - - - - -<h4>Captures:</h4><p> -A pattern can contain sub-patterns enclosed in parentheses; -they describe <em>captures</em>. -When a match succeeds, the substrings of the subject string -that match captures are stored (<em>captured</em>) for future use. -Captures are numbered according to their left parentheses. -For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, -the part of the string matching <code>"a*(.)%w(%s*)"</code> is -stored as the first capture (and therefore has number 1); -the character matching "<code>.</code>" is captured with number 2, -and the part matching "<code>%s*</code>" has number 3. - - -<p> -As a special case, the empty capture <code>()</code> captures -the current string position (a number). -For instance, if we apply the pattern <code>"()aa()"</code> on the -string <code>"flaaap"</code>, there will be two captures: 3 and 5. - - - - - - - -<h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3> - -<p> -The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>, -<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a> -is a format string, -which describes the layout of the structure being created or read. - - -<p> -A format string is a sequence of conversion options. -The conversion options are as follows: - -<ul> -<li><b><code><</code>: </b>sets little endian</li> -<li><b><code>></code>: </b>sets big endian</li> -<li><b><code>=</code>: </b>sets native endian</li> -<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code> -(default is native alignment)</li> -<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li> -<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li> -<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li> -<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li> -<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li> -<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li> -<li><b><code>j</code>: </b>a <code>lua_Integer</code></li> -<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li> -<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li> -<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes -(default is native size)</li> -<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes -(default is native size)</li> -<li><b><code>f</code>: </b>a <code>float</code> (native size)</li> -<li><b><code>d</code>: </b>a <code>double</code> (native size)</li> -<li><b><code>n</code>: </b>a <code>lua_Number</code></li> -<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li> -<li><b><code>z</code>: </b>a zero-terminated string</li> -<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length -coded as an unsigned integer with <code>n</code> bytes -(default is a <code>size_t</code>)</li> -<li><b><code>x</code>: </b>one byte of padding</li> -<li><b><code>X<em>op</em></code>: </b>an empty item that aligns -according to option <code>op</code> -(which is otherwise ignored)</li> -<li><b>'<code> </code>': </b>(empty space) ignored</li> -</ul><p> -(A "<code>[<em>n</em>]</code>" means an optional integral numeral.) -Except for padding, spaces, and configurations -(options "<code>xX <=>!</code>"), -each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>) -or a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>). - - -<p> -For options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>", -<code>n</code> can be any integer between 1 and 16. -All integral options check overflows; -<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size; -<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer. - - -<p> -Any format string starts as if prefixed by "<code>!1=</code>", -that is, -with maximum alignment of 1 (no alignment) -and native endianness. - - -<p> -Alignment works as follows: -For each option, -the format gets extra padding until the data starts -at an offset that is a multiple of the minimum between the -option size and the maximum alignment; -this minimum must be a power of 2. -Options "<code>c</code>" and "<code>z</code>" are not aligned; -option "<code>s</code>" follows the alignment of its starting integer. - - -<p> -All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a> -(and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>). - - - - - - - -<h2>6.5 – <a name="6.5">UTF-8 Support</a></h2> - -<p> -This library provides basic support for UTF-8 encoding. -It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>. -This library does not provide any support for Unicode other -than the handling of the encoding. -Any operation that needs the meaning of a character, -such as character classification, is outside its scope. - - -<p> -Unless stated otherwise, -all functions that expect a byte position as a parameter -assume that the given position is either the start of a byte sequence -or one plus the length of the subject string. -As in the string library, -negative indices count from the end of the string. - - -<p> -<hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3> -Receives zero or more integers, -converts each one to its corresponding UTF-8 byte sequence -and returns a string with the concatenation of all these sequences. - - - - -<p> -<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3> -The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>" -(see <a href="#6.4.1">§6.4.1</a>), -which matches exactly one UTF-8 byte sequence, -assuming that the subject is a valid UTF-8 string. - - - - -<p> -<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3> - - -<p> -Returns values so that the construction - -<pre> - for p, c in utf8.codes(s) do <em>body</em> end -</pre><p> -will iterate over all characters in string <code>s</code>, -with <code>p</code> being the position (in bytes) and <code>c</code> the code point -of each character. -It raises an error if it meets any invalid byte sequence. - - - - -<p> -<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3> -Returns the codepoints (as integers) from all characters in <code>s</code> -that start between byte position <code>i</code> and <code>j</code> (both included). -The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>. -It raises an error if it meets any invalid byte sequence. - - - - -<p> -<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3> -Returns the number of UTF-8 characters in string <code>s</code> -that start between positions <code>i</code> and <code>j</code> (both inclusive). -The default for <code>i</code> is 1 and for <code>j</code> is -1. -If it finds any invalid byte sequence, -returns a false value plus the position of the first invalid byte. - - - - -<p> -<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3> -Returns the position (in bytes) where the encoding of the -<code>n</code>-th character of <code>s</code> -(counting from position <code>i</code>) starts. -A negative <code>n</code> gets characters before position <code>i</code>. -The default for <code>i</code> is 1 when <code>n</code> is non-negative -and <code>#s + 1</code> otherwise, -so that <code>utf8.offset(s, -n)</code> gets the offset of the -<code>n</code>-th character from the end of the string. -If the specified character is neither in the subject -nor right after its end, -the function returns <b>nil</b>. - - -<p> -As a special case, -when <code>n</code> is 0 the function returns the start of the encoding -of the character that contains the <code>i</code>-th byte of <code>s</code>. - - -<p> -This function assumes that <code>s</code> is a valid UTF-8 string. - - - - - - - -<h2>6.6 – <a name="6.6">Table Manipulation</a></h2> - -<p> -This library provides generic functions for table manipulation. -It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>. - - -<p> -Remember that, whenever an operation needs the length of a table, -all caveats about the length operator apply (see <a href="#3.4.7">§3.4.7</a>). -All functions ignore non-numeric keys -in the tables given as arguments. - - -<p> -<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3> - - -<p> -Given a list where all elements are strings or numbers, -returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>. -The default value for <code>sep</code> is the empty string, -the default for <code>i</code> is 1, -and the default for <code>j</code> is <code>#list</code>. -If <code>i</code> is greater than <code>j</code>, returns the empty string. - - - - -<p> -<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3> - - -<p> -Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>, -shifting up the elements -<code>list[pos], list[pos+1], ···, list[#list]</code>. -The default value for <code>pos</code> is <code>#list+1</code>, -so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end -of list <code>t</code>. - - - - -<p> -<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3> - - -<p> -Moves elements from table <code>a1</code> to table <code>a2</code>, -performing the equivalent to the following -multiple assignment: -<code>a2[t],··· = a1[f],···,a1[e]</code>. -The default for <code>a2</code> is <code>a1</code>. -The destination range can overlap with the source range. -The number of elements to be moved must fit in a Lua integer. - - -<p> -Returns the destination table <code>a2</code>. - - - - -<p> -<hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3> - - -<p> -Returns a new table with all arguments stored into keys 1, 2, etc. -and with a field "<code>n</code>" with the total number of arguments. -Note that the resulting table may not be a sequence. - - - - -<p> -<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3> - - -<p> -Removes from <code>list</code> the element at position <code>pos</code>, -returning the value of the removed element. -When <code>pos</code> is an integer between 1 and <code>#list</code>, -it shifts down the elements -<code>list[pos+1], list[pos+2], ···, list[#list]</code> -and erases element <code>list[#list]</code>; -The index <code>pos</code> can also be 0 when <code>#list</code> is 0, -or <code>#list + 1</code>; -in those cases, the function erases the element <code>list[pos]</code>. - - -<p> -The default value for <code>pos</code> is <code>#list</code>, -so that a call <code>table.remove(l)</code> removes the last element -of list <code>l</code>. - - - - -<p> -<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3> - - -<p> -Sorts list elements in a given order, <em>in-place</em>, -from <code>list[1]</code> to <code>list[#list]</code>. -If <code>comp</code> is given, -then it must be a function that receives two list elements -and returns true when the first element must come -before the second in the final order -(so that, after the sort, -<code>i < j</code> implies <code>not comp(list[j],list[i])</code>). -If <code>comp</code> is not given, -then the standard Lua operator <code><</code> is used instead. - - -<p> -Note that the <code>comp</code> function must define -a strict partial order over the elements in the list; -that is, it must be asymmetric and transitive. -Otherwise, no valid sort may be possible. - - -<p> -The sort algorithm is not stable: -elements considered equal by the given order -may have their relative positions changed by the sort. - - - - -<p> -<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3> - - -<p> -Returns the elements from the given list. -This function is equivalent to - -<pre> - return list[i], list[i+1], ···, list[j] -</pre><p> -By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>. - - - - - - - -<h2>6.7 – <a name="6.7">Mathematical Functions</a></h2> - -<p> -This library provides basic mathematical functions. -It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>. -Functions with the annotation "<code>integer/float</code>" give -integer results for integer arguments -and float results for float (or mixed) arguments. -Rounding functions -(<a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, and <a href="#pdf-math.modf"><code>math.modf</code></a>) -return an integer when the result fits in the range of an integer, -or a float otherwise. - - -<p> -<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3> - - -<p> -Returns the absolute value of <code>x</code>. (integer/float) - - - - -<p> -<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3> - - -<p> -Returns the arc cosine of <code>x</code> (in radians). - - - - -<p> -<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3> - - -<p> -Returns the arc sine of <code>x</code> (in radians). - - - - -<p> -<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3> - - -<p> - -Returns the arc tangent of <code>y/x</code> (in radians), -but uses the signs of both arguments to find the -quadrant of the result. -(It also handles correctly the case of <code>x</code> being zero.) - - -<p> -The default value for <code>x</code> is 1, -so that the call <code>math.atan(y)</code> -returns the arc tangent of <code>y</code>. - - - - -<p> -<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3> - - -<p> -Returns the smallest integral value larger than or equal to <code>x</code>. - - - - -<p> -<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3> - - -<p> -Returns the cosine of <code>x</code> (assumed to be in radians). - - - - -<p> -<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3> - - -<p> -Converts the angle <code>x</code> from radians to degrees. - - - - -<p> -<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3> - - -<p> -Returns the value <em>e<sup>x</sup></em> -(where <code>e</code> is the base of natural logarithms). - - - - -<p> -<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3> - - -<p> -Returns the largest integral value smaller than or equal to <code>x</code>. - - - - -<p> -<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3> - - -<p> -Returns the remainder of the division of <code>x</code> by <code>y</code> -that rounds the quotient towards zero. (integer/float) - - - - -<p> -<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3> - - -<p> -The float value <code>HUGE_VAL</code>, -a value larger than any other numeric value. - - - - -<p> -<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3> - - -<p> -Returns the logarithm of <code>x</code> in the given base. -The default for <code>base</code> is <em>e</em> -(so that the function returns the natural logarithm of <code>x</code>). - - - - -<p> -<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3> - - -<p> -Returns the argument with the maximum value, -according to the Lua operator <code><</code>. (integer/float) - - - - -<p> -<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3> -An integer with the maximum value for an integer. - - - - -<p> -<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3> - - -<p> -Returns the argument with the minimum value, -according to the Lua operator <code><</code>. (integer/float) - - - - -<p> -<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3> -An integer with the minimum value for an integer. - - - - -<p> -<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3> - - -<p> -Returns the integral part of <code>x</code> and the fractional part of <code>x</code>. -Its second result is always a float. - - - - -<p> -<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3> - - -<p> -The value of <em>π</em>. - - - - -<p> -<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3> - - -<p> -Converts the angle <code>x</code> from degrees to radians. - - - - -<p> -<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3> - - -<p> -When called without arguments, -returns a pseudo-random float with uniform distribution -in the range <em>[0,1)</em>. -When called with two integers <code>m</code> and <code>n</code>, -<code>math.random</code> returns a pseudo-random integer -with uniform distribution in the range <em>[m, n]</em>. -(The value <em>n-m</em> cannot be negative and must fit in a Lua integer.) -The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>. - - -<p> -This function is an interface to the underling -pseudo-random generator function provided by C. - - - - -<p> -<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3> - - -<p> -Sets <code>x</code> as the "seed" -for the pseudo-random generator: -equal seeds produce equal sequences of numbers. - - - - -<p> -<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3> - - -<p> -Returns the sine of <code>x</code> (assumed to be in radians). - - - - -<p> -<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3> - - -<p> -Returns the square root of <code>x</code>. -(You can also use the expression <code>x^0.5</code> to compute this value.) - - - - -<p> -<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3> - - -<p> -Returns the tangent of <code>x</code> (assumed to be in radians). - - - - -<p> -<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3> - - -<p> -If the value <code>x</code> is convertible to an integer, -returns that integer. -Otherwise, returns <b>nil</b>. - - - - -<p> -<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3> - - -<p> -Returns "<code>integer</code>" if <code>x</code> is an integer, -"<code>float</code>" if it is a float, -or <b>nil</b> if <code>x</code> is not a number. - - - - -<p> -<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3> - - -<p> -Returns a boolean, -true if and only if integer <code>m</code> is below integer <code>n</code> when -they are compared as unsigned integers. - - - - - - - -<h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2> - -<p> -The I/O library provides two different styles for file manipulation. -The first one uses implicit file handles; -that is, there are operations to set a default input file and a -default output file, -and all input/output operations are over these default files. -The second style uses explicit file handles. - - -<p> -When using implicit file handles, -all operations are supplied by table <a name="pdf-io"><code>io</code></a>. -When using explicit file handles, -the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle -and then all operations are supplied as methods of the file handle. - - -<p> -The table <code>io</code> also provides -three predefined file handles with their usual meanings from C: -<a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>. -The I/O library never closes these files. - - -<p> -Unless otherwise stated, -all I/O functions return <b>nil</b> on failure -(plus an error message as a second result and -a system-dependent error code as a third result) -and some value different from <b>nil</b> on success. -In non-POSIX systems, -the computation of the error message and error code -in case of errors -may be not thread safe, -because they rely on the global C variable <code>errno</code>. - - -<p> -<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3> - - -<p> -Equivalent to <code>file:close()</code>. -Without a <code>file</code>, closes the default output file. - - - - -<p> -<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3> - - -<p> -Equivalent to <code>io.output():flush()</code>. - - - - -<p> -<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3> - - -<p> -When called with a file name, it opens the named file (in text mode), -and sets its handle as the default input file. -When called with a file handle, -it simply sets this file handle as the default input file. -When called without arguments, -it returns the current default input file. - - -<p> -In case of errors this function raises the error, -instead of returning an error code. - - - - -<p> -<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, ···])</code></a></h3> - - -<p> -Opens the given file name in read mode -and returns an iterator function that -works like <code>file:lines(···)</code> over the opened file. -When the iterator function detects the end of file, -it returns no values (to finish the loop) and automatically closes the file. - - -<p> -The call <code>io.lines()</code> (with no file name) is equivalent -to <code>io.input():lines("*l")</code>; -that is, it iterates over the lines of the default input file. -In this case, the iterator does not close the file when the loop ends. - - -<p> -In case of errors this function raises the error, -instead of returning an error code. - - - - -<p> -<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3> - - -<p> -This function opens a file, -in the mode specified in the string <code>mode</code>. -In case of success, -it returns a new file handle. - - -<p> -The <code>mode</code> string can be any of the following: - -<ul> -<li><b>"<code>r</code>": </b> read mode (the default);</li> -<li><b>"<code>w</code>": </b> write mode;</li> -<li><b>"<code>a</code>": </b> append mode;</li> -<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li> -<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li> -<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved, - writing is only allowed at the end of file.</li> -</ul><p> -The <code>mode</code> string can also have a '<code>b</code>' at the end, -which is needed in some systems to open the file in binary mode. - - - - -<p> -<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3> - - -<p> -Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file. - - - - -<p> -<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3> - - -<p> -This function is system dependent and is not available -on all platforms. - - -<p> -Starts program <code>prog</code> in a separated process and returns -a file handle that you can use to read data from this program -(if <code>mode</code> is <code>"r"</code>, the default) -or to write data to this program -(if <code>mode</code> is <code>"w"</code>). - - - - -<p> -<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3> - - -<p> -Equivalent to <code>io.input():read(···)</code>. - - - - -<p> -<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3> - - -<p> -In case of success, -returns a handle for a temporary file. -This file is opened in update mode -and it is automatically removed when the program ends. - - - - -<p> -<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3> - - -<p> -Checks whether <code>obj</code> is a valid file handle. -Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, -<code>"closed file"</code> if <code>obj</code> is a closed file handle, -or <b>nil</b> if <code>obj</code> is not a file handle. - - - - -<p> -<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3> - - -<p> -Equivalent to <code>io.output():write(···)</code>. - - - - -<p> -<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3> - - -<p> -Closes <code>file</code>. -Note that files are automatically closed when -their handles are garbage collected, -but that takes an unpredictable amount of time to happen. - - -<p> -When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>, -<a href="#pdf-file:close"><code>file:close</code></a> returns the same values -returned by <a href="#pdf-os.execute"><code>os.execute</code></a>. - - - - -<p> -<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3> - - -<p> -Saves any written data to <code>file</code>. - - - - -<p> -<hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3> - - -<p> -Returns an iterator function that, -each time it is called, -reads the file according to the given formats. -When no format is given, -uses "<code>l</code>" as a default. -As an example, the construction - -<pre> - for c in file:lines(1) do <em>body</em> end -</pre><p> -will iterate over all characters of the file, -starting at the current position. -Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file -when the loop ends. - - -<p> -In case of errors this function raises the error, -instead of returning an error code. - - - - -<p> -<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3> - - -<p> -Reads the file <code>file</code>, -according to the given formats, which specify what to read. -For each format, -the function returns a string or a number with the characters read, -or <b>nil</b> if it cannot read data with the specified format. -(In this latter case, -the function does not read subsequent formats.) -When called without formats, -it uses a default format that reads the next line -(see below). - - -<p> -The available formats are - -<ul> - -<li><b>"<code>n</code>": </b> -reads a numeral and returns it as a float or an integer, -following the lexical conventions of Lua. -(The numeral may have leading spaces and a sign.) -This format always reads the longest input sequence that -is a valid prefix for a numeral; -if that prefix does not form a valid numeral -(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"), -it is discarded and the function returns <b>nil</b>. -</li> - -<li><b>"<code>a</code>": </b> -reads the whole file, starting at the current position. -On end of file, it returns the empty string. -</li> - -<li><b>"<code>l</code>": </b> -reads the next line skipping the end of line, -returning <b>nil</b> on end of file. -This is the default format. -</li> - -<li><b>"<code>L</code>": </b> -reads the next line keeping the end-of-line character (if present), -returning <b>nil</b> on end of file. -</li> - -<li><b><em>number</em>: </b> -reads a string with up to this number of bytes, -returning <b>nil</b> on end of file. -If <code>number</code> is zero, -it reads nothing and returns an empty string, -or <b>nil</b> on end of file. -</li> - -</ul><p> -The formats "<code>l</code>" and "<code>L</code>" should be used only for text files. - - - - -<p> -<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3> - - -<p> -Sets and gets the file position, -measured from the beginning of the file, -to the position given by <code>offset</code> plus a base -specified by the string <code>whence</code>, as follows: - -<ul> -<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li> -<li><b>"<code>cur</code>": </b> base is current position;</li> -<li><b>"<code>end</code>": </b> base is end of file;</li> -</ul><p> -In case of success, <code>seek</code> returns the final file position, -measured in bytes from the beginning of the file. -If <code>seek</code> fails, it returns <b>nil</b>, -plus a string describing the error. - - -<p> -The default value for <code>whence</code> is <code>"cur"</code>, -and for <code>offset</code> is 0. -Therefore, the call <code>file:seek()</code> returns the current -file position, without changing it; -the call <code>file:seek("set")</code> sets the position to the -beginning of the file (and returns 0); -and the call <code>file:seek("end")</code> sets the position to the -end of the file, and returns its size. - - - - -<p> -<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3> - - -<p> -Sets the buffering mode for an output file. -There are three available modes: - -<ul> - -<li><b>"<code>no</code>": </b> -no buffering; the result of any output operation appears immediately. -</li> - -<li><b>"<code>full</code>": </b> -full buffering; output operation is performed only -when the buffer is full or when -you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>). -</li> - -<li><b>"<code>line</code>": </b> -line buffering; output is buffered until a newline is output -or there is any input from some special files -(such as a terminal device). -</li> - -</ul><p> -For the last two cases, <code>size</code> -specifies the size of the buffer, in bytes. -The default is an appropriate size. - - - - -<p> -<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3> - - -<p> -Writes the value of each of its arguments to <code>file</code>. -The arguments must be strings or numbers. - - -<p> -In case of success, this function returns <code>file</code>. -Otherwise it returns <b>nil</b> plus a string describing the error. - - - - - - - -<h2>6.9 – <a name="6.9">Operating System Facilities</a></h2> - -<p> -This library is implemented through table <a name="pdf-os"><code>os</code></a>. - - -<p> -<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3> - - -<p> -Returns an approximation of the amount in seconds of CPU time -used by the program. - - - - -<p> -<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3> - - -<p> -Returns a string or a table containing date and time, -formatted according to the given string <code>format</code>. - - -<p> -If the <code>time</code> argument is present, -this is the time to be formatted -(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value). -Otherwise, <code>date</code> formats the current time. - - -<p> -If <code>format</code> starts with '<code>!</code>', -then the date is formatted in Coordinated Universal Time. -After this optional character, -if <code>format</code> is the string "<code>*t</code>", -then <code>date</code> returns a table with the following fields: -<code>year</code>, <code>month</code> (1–12), <code>day</code> (1–31), -<code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61), -<code>wday</code> (weekday, 1–7, Sunday is 1), -<code>yday</code> (day of the year, 1–366), -and <code>isdst</code> (daylight saving flag, a boolean). -This last field may be absent -if the information is not available. - - -<p> -If <code>format</code> is not "<code>*t</code>", -then <code>date</code> returns the date as a string, -formatted according to the same rules as the ISO C function <code>strftime</code>. - - -<p> -When called without arguments, -<code>date</code> returns a reasonable date and time representation that depends on -the host system and on the current locale. -(More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.) - - -<p> -In non-POSIX systems, -this function may be not thread safe -because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>. - - - - -<p> -<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3> - - -<p> -Returns the difference, in seconds, -from time <code>t1</code> to time <code>t2</code> -(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>). -In POSIX, Windows, and some other systems, -this value is exactly <code>t2</code><em>-</em><code>t1</code>. - - - - -<p> -<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3> - - -<p> -This function is equivalent to the ISO C function <code>system</code>. -It passes <code>command</code> to be executed by an operating system shell. -Its first result is <b>true</b> -if the command terminated successfully, -or <b>nil</b> otherwise. -After this first result -the function returns a string plus a number, -as follows: - -<ul> - -<li><b>"<code>exit</code>": </b> -the command terminated normally; -the following number is the exit status of the command. -</li> - -<li><b>"<code>signal</code>": </b> -the command was terminated by a signal; -the following number is the signal that terminated the command. -</li> - -</ul> - -<p> -When called without a <code>command</code>, -<code>os.execute</code> returns a boolean that is true if a shell is available. - - - - -<p> -<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3> - - -<p> -Calls the ISO C function <code>exit</code> to terminate the host program. -If <code>code</code> is <b>true</b>, -the returned status is <code>EXIT_SUCCESS</code>; -if <code>code</code> is <b>false</b>, -the returned status is <code>EXIT_FAILURE</code>; -if <code>code</code> is a number, -the returned status is this number. -The default value for <code>code</code> is <b>true</b>. - - -<p> -If the optional second argument <code>close</code> is true, -closes the Lua state before exiting. - - - - -<p> -<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3> - - -<p> -Returns the value of the process environment variable <code>varname</code>, -or <b>nil</b> if the variable is not defined. - - - - -<p> -<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3> - - -<p> -Deletes the file (or empty directory, on POSIX systems) -with the given name. -If this function fails, it returns <b>nil</b>, -plus a string describing the error and the error code. -Otherwise, it returns true. - - - - -<p> -<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3> - - -<p> -Renames the file or directory named <code>oldname</code> to <code>newname</code>. -If this function fails, it returns <b>nil</b>, -plus a string describing the error and the error code. -Otherwise, it returns true. - - - - -<p> -<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3> - - -<p> -Sets the current locale of the program. -<code>locale</code> is a system-dependent string specifying a locale; -<code>category</code> is an optional string describing which category to change: -<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, -<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; -the default category is <code>"all"</code>. -The function returns the name of the new locale, -or <b>nil</b> if the request cannot be honored. - - -<p> -If <code>locale</code> is the empty string, -the current locale is set to an implementation-defined native locale. -If <code>locale</code> is the string "<code>C</code>", -the current locale is set to the standard C locale. - - -<p> -When called with <b>nil</b> as the first argument, -this function only returns the name of the current locale -for the given category. - - -<p> -This function may be not thread safe -because of its reliance on C function <code>setlocale</code>. - - - - -<p> -<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3> - - -<p> -Returns the current time when called without arguments, -or a time representing the local date and time specified by the given table. -This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>, -and may have fields -<code>hour</code> (default is 12), -<code>min</code> (default is 0), -<code>sec</code> (default is 0), -and <code>isdst</code> (default is <b>nil</b>). -Other fields are ignored. -For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function. - - -<p> -The values in these fields do not need to be inside their valid ranges. -For instance, if <code>sec</code> is -10, -it means -10 seconds from the time specified by the other fields; -if <code>hour</code> is 1000, -it means +1000 hours from the time specified by the other fields. - - -<p> -The returned value is a number, whose meaning depends on your system. -In POSIX, Windows, and some other systems, -this number counts the number -of seconds since some given start time (the "epoch"). -In other systems, the meaning is not specified, -and the number returned by <code>time</code> can be used only as an argument to -<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>. - - - - -<p> -<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3> - - -<p> -Returns a string with a file name that can -be used for a temporary file. -The file must be explicitly opened before its use -and explicitly removed when no longer needed. - - -<p> -In POSIX systems, -this function also creates a file with that name, -to avoid security risks. -(Someone else might create the file with wrong permissions -in the time between getting the name and creating the file.) -You still have to open the file to use it -and to remove it (even if you do not use it). - - -<p> -When possible, -you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>, -which automatically removes the file when the program ends. - - - - - - - -<h2>6.10 – <a name="6.10">The Debug Library</a></h2> - -<p> -This library provides -the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs. -You should exert care when using this library. -Several of its functions -violate basic assumptions about Lua code -(e.g., that variables local to a function -cannot be accessed from outside; -that userdata metatables cannot be changed by Lua code; -that Lua programs do not crash) -and therefore can compromise otherwise secure code. -Moreover, some functions in this library may be slow. - - -<p> -All functions in this library are provided -inside the <a name="pdf-debug"><code>debug</code></a> table. -All functions that operate over a thread -have an optional first argument which is the -thread to operate over. -The default is always the current thread. - - -<p> -<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3> - - -<p> -Enters an interactive mode with the user, -running each string that the user enters. -Using simple commands and other debug facilities, -the user can inspect global and local variables, -change their values, evaluate expressions, and so on. -A line containing only the word <code>cont</code> finishes this function, -so that the caller continues its execution. - - -<p> -Note that commands for <code>debug.debug</code> are not lexically nested -within any function and so have no direct access to local variables. - - - - -<p> -<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3> - - -<p> -Returns the current hook settings of the thread, as three values: -the current hook function, the current hook mask, -and the current hook count -(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function). - - - - -<p> -<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3> - - -<p> -Returns a table with information about a function. -You can give the function directly -or you can give a number as the value of <code>f</code>, -which means the function running at level <code>f</code> of the call stack -of the given thread: -level 0 is the current function (<code>getinfo</code> itself); -level 1 is the function that called <code>getinfo</code> -(except for tail calls, which do not count on the stack); -and so on. -If <code>f</code> is a number larger than the number of active functions, -then <code>getinfo</code> returns <b>nil</b>. - - -<p> -The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>, -with the string <code>what</code> describing which fields to fill in. -The default for <code>what</code> is to get all information available, -except the table of valid lines. -If present, -the option '<code>f</code>' -adds a field named <code>func</code> with the function itself. -If present, -the option '<code>L</code>' -adds a field named <code>activelines</code> with the table of -valid lines. - - -<p> -For instance, the expression <code>debug.getinfo(1,"n").name</code> returns -a name for the current function, -if a reasonable name can be found, -and the expression <code>debug.getinfo(print)</code> -returns a table with all available information -about the <a href="#pdf-print"><code>print</code></a> function. - - - - -<p> -<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3> - - -<p> -This function returns the name and the value of the local variable -with index <code>local</code> of the function at level <code>f</code> of the stack. -This function accesses not only explicit local variables, -but also parameters, temporaries, etc. - - -<p> -The first parameter or local variable has index 1, and so on, -following the order that they are declared in the code, -counting only the variables that are active -in the current scope of the function. -Negative indices refer to vararg arguments; --1 is the first vararg argument. -The function returns <b>nil</b> if there is no variable with the given index, -and raises an error when called with a level out of range. -(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.) - - -<p> -Variable names starting with '<code>(</code>' (open parenthesis) -represent variables with no known names -(internal variables such as loop control variables, -and variables from chunks saved without debug information). - - -<p> -The parameter <code>f</code> may also be a function. -In that case, <code>getlocal</code> returns only the name of function parameters. - - - - -<p> -<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3> - - -<p> -Returns the metatable of the given <code>value</code> -or <b>nil</b> if it does not have a metatable. - - - - -<p> -<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3> - - -<p> -Returns the registry table (see <a href="#4.5">§4.5</a>). - - - - -<p> -<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3> - - -<p> -This function returns the name and the value of the upvalue -with index <code>up</code> of the function <code>f</code>. -The function returns <b>nil</b> if there is no upvalue with the given index. - - -<p> -Variable names starting with '<code>(</code>' (open parenthesis) -represent variables with no known names -(variables from chunks saved without debug information). - - - - -<p> -<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3> - - -<p> -Returns the Lua value associated to <code>u</code>. -If <code>u</code> is not a full userdata, -returns <b>nil</b>. - - - - -<p> -<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3> - - -<p> -Sets the given function as a hook. -The string <code>mask</code> and the number <code>count</code> describe -when the hook will be called. -The string mask may have any combination of the following characters, -with the given meaning: - -<ul> -<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li> -<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li> -<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li> -</ul><p> -Moreover, -with a <code>count</code> different from zero, -the hook is called also after every <code>count</code> instructions. - - -<p> -When called without arguments, -<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook. - - -<p> -When the hook is called, its first argument is a string -describing the event that has triggered its call: -<code>"call"</code> (or <code>"tail call"</code>), -<code>"return"</code>, -<code>"line"</code>, and <code>"count"</code>. -For line events, -the hook also gets the new line number as its second parameter. -Inside a hook, -you can call <code>getinfo</code> with level 2 to get more information about -the running function -(level 0 is the <code>getinfo</code> function, -and level 1 is the hook function). - - - - -<p> -<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3> - - -<p> -This function assigns the value <code>value</code> to the local variable -with index <code>local</code> of the function at level <code>level</code> of the stack. -The function returns <b>nil</b> if there is no local -variable with the given index, -and raises an error when called with a <code>level</code> out of range. -(You can call <code>getinfo</code> to check whether the level is valid.) -Otherwise, it returns the name of the local variable. - - -<p> -See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about -variable indices and names. - - - - -<p> -<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3> - - -<p> -Sets the metatable for the given <code>value</code> to the given <code>table</code> -(which can be <b>nil</b>). -Returns <code>value</code>. - - - - -<p> -<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3> - - -<p> -This function assigns the value <code>value</code> to the upvalue -with index <code>up</code> of the function <code>f</code>. -The function returns <b>nil</b> if there is no upvalue -with the given index. -Otherwise, it returns the name of the upvalue. - - - - -<p> -<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3> - - -<p> -Sets the given <code>value</code> as -the Lua value associated to the given <code>udata</code>. -<code>udata</code> must be a full userdata. - - -<p> -Returns <code>udata</code>. - - - - -<p> -<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3> - - -<p> -If <code>message</code> is present but is neither a string nor <b>nil</b>, -this function returns <code>message</code> without further processing. -Otherwise, -it returns a string with a traceback of the call stack. -The optional <code>message</code> string is appended -at the beginning of the traceback. -An optional <code>level</code> number tells at which level -to start the traceback -(default is 1, the function calling <code>traceback</code>). - - - - -<p> -<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3> - - -<p> -Returns a unique identifier (as a light userdata) -for the upvalue numbered <code>n</code> -from the given function. - - -<p> -These unique identifiers allow a program to check whether different -closures share upvalues. -Lua closures that share an upvalue -(that is, that access a same external local variable) -will return identical ids for those upvalue indices. - - - - -<p> -<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3> - - -<p> -Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code> -refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>. - - - - - - - -<h1>7 – <a name="7">Lua Standalone</a></h1> - -<p> -Although Lua has been designed as an extension language, -to be embedded in a host C program, -it is also frequently used as a standalone language. -An interpreter for Lua as a standalone language, -called simply <code>lua</code>, -is provided with the standard distribution. -The standalone interpreter includes -all standard libraries, including the debug library. -Its usage is: - -<pre> - lua [options] [script [args]] -</pre><p> -The options are: - -<ul> -<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li> -<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em> and assigns the - result to global @<em>mod</em>;</li> -<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li> -<li><b><code>-v</code>: </b> prints version information;</li> -<li><b><code>-E</code>: </b> ignores environment variables;</li> -<li><b><code>--</code>: </b> stops handling options;</li> -<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li> -</ul><p> -After handling its options, <code>lua</code> runs the given <em>script</em>. -When called without arguments, -<code>lua</code> behaves as <code>lua -v -i</code> -when the standard input (<code>stdin</code>) is a terminal, -and as <code>lua -</code> otherwise. - - -<p> -When called without option <code>-E</code>, -the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a> -(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined) -before running any argument. -If the variable content has the format <code>@<em>filename</em></code>, -then <code>lua</code> executes the file. -Otherwise, <code>lua</code> executes the string itself. - - -<p> -When called with option <code>-E</code>, -besides ignoring <code>LUA_INIT</code>, -Lua also ignores -the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>, -setting the values of -<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a> -with the default paths defined in <code>luaconf.h</code>. - - -<p> -All options are handled in order, except <code>-i</code> and <code>-E</code>. -For instance, an invocation like - -<pre> - $ lua -e'a=1' -e 'print(a)' script.lua -</pre><p> -will first set <code>a</code> to 1, then print the value of <code>a</code>, -and finally run the file <code>script.lua</code> with no arguments. -(Here <code>$</code> is the shell prompt. Your prompt may be different.) - - -<p> -Before running any code, -<code>lua</code> collects all command-line arguments -in a global table called <code>arg</code>. -The script name goes to index 0, -the first argument after the script name goes to index 1, -and so on. -Any arguments before the script name -(that is, the interpreter name plus its options) -go to negative indices. -For instance, in the call - -<pre> - $ lua -la b.lua t1 t2 -</pre><p> -the table is like this: - -<pre> - arg = { [-2] = "lua", [-1] = "-la", - [0] = "b.lua", - [1] = "t1", [2] = "t2" } -</pre><p> -If there is no script in the call, -the interpreter name goes to index 0, -followed by the other arguments. -For instance, the call - -<pre> - $ lua -e "print(arg[1])" -</pre><p> -will print "<code>-e</code>". -If there is a script, -the script is called with arguments -<code>arg[1]</code>, ···, <code>arg[#arg]</code>. -(Like all chunks in Lua, -the script is compiled as a vararg function.) - - -<p> -In interactive mode, -Lua repeatedly prompts and waits for a line. -After reading a line, -Lua first try to interpret the line as an expression. -If it succeeds, it prints its value. -Otherwise, it interprets the line as a statement. -If you write an incomplete statement, -the interpreter waits for its completion -by issuing a different prompt. - - -<p> -If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string, -then its value is used as the prompt. -Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string, -its value is used as the secondary prompt -(issued during incomplete statements). - - -<p> -In case of unprotected errors in the script, -the interpreter reports the error to the standard error stream. -If the error object is not a string but -has a metamethod <code>__tostring</code>, -the interpreter calls this metamethod to produce the final message. -Otherwise, the interpreter converts the error object to a string -and adds a stack traceback to it. - - -<p> -When finishing normally, -the interpreter closes its main Lua state -(see <a href="#lua_close"><code>lua_close</code></a>). -The script can avoid this step by -calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate. - - -<p> -To allow the use of Lua as a -script interpreter in Unix systems, -the standalone interpreter skips -the first line of a chunk if it starts with <code>#</code>. -Therefore, Lua scripts can be made into executable programs -by using <code>chmod +x</code> and the <code>#!</code> form, -as in - -<pre> - #!/usr/local/bin/lua -</pre><p> -(Of course, -the location of the Lua interpreter may be different in your machine. -If <code>lua</code> is in your <code>PATH</code>, -then - -<pre> - #!/usr/bin/env lua -</pre><p> -is a more portable solution.) - - - -<h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1> - -<p> -Here we list the incompatibilities that you may find when moving a program -from Lua 5.2 to Lua 5.3. -You can avoid some incompatibilities by compiling Lua with -appropriate options (see file <code>luaconf.h</code>). -However, -all these compatibility options will be removed in the future. - - -<p> -Lua versions can always change the C API in ways that -do not imply source-code changes in a program, -such as the numeric values for constants -or the implementation of functions as macros. -Therefore, -you should not assume that binaries are compatible between -different Lua versions. -Always recompile clients of the Lua API when -using a new version. - - -<p> -Similarly, Lua versions can always change the internal representation -of precompiled chunks; -precompiled chunks are not compatible between different Lua versions. - - -<p> -The standard paths in the official distribution may -change between versions. - - - -<h2>8.1 – <a name="8.1">Changes in the Language</a></h2> -<ul> - -<li> -The main difference between Lua 5.2 and Lua 5.3 is the -introduction of an integer subtype for numbers. -Although this change should not affect "normal" computations, -some computations -(mainly those that involve some kind of overflow) -can give different results. - - -<p> -You can fix these differences by forcing a number to be a float -(in Lua 5.2 all numbers were float), -in particular writing constants with an ending <code>.0</code> -or using <code>x = x + 0.0</code> to convert a variable. -(This recommendation is only for a quick fix -for an occasional incompatibility; -it is not a general guideline for good programming. -For good programming, -use floats where you need floats -and integers where you need integers.) -</li> - -<li> -The conversion of a float to a string now adds a <code>.0</code> suffix -to the result if it looks like an integer. -(For instance, the float 2.0 will be printed as <code>2.0</code>, -not as <code>2</code>.) -You should always use an explicit format -when you need a specific format for numbers. - - -<p> -(Formally this is not an incompatibility, -because Lua does not specify how numbers are formatted as strings, -but some programs assumed a specific format.) -</li> - -<li> -The generational mode for the garbage collector was removed. -(It was an experimental feature in Lua 5.2.) -</li> - -</ul> - - - - -<h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2> -<ul> - -<li> -The <code>bit32</code> library has been deprecated. -It is easy to require a compatible external library or, -better yet, to replace its functions with appropriate bitwise operations. -(Keep in mind that <code>bit32</code> operates on 32-bit integers, -while the bitwise operators in Lua 5.3 operate on Lua integers, -which by default have 64 bits.) -</li> - -<li> -The Table library now respects metamethods -for setting and getting elements. -</li> - -<li> -The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and -its <code>__ipairs</code> metamethod has been deprecated. -</li> - -<li> -Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore. -For compatibility, Lua will continue to accept (and ignore) this character. -</li> - -<li> -The following functions were deprecated in the mathematical library: -<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>, -<code>frexp</code>, and <code>ldexp</code>. -You can replace <code>math.pow(x,y)</code> with <code>x^y</code>; -you can replace <code>math.atan2</code> with <code>math.atan</code>, -which now accepts one or two arguments; -you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>. -For the other operations, -you can either use an external library or -implement them in Lua. -</li> - -<li> -The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a> -changed the way it handles versioned names. -Now, the version should come after the module name -(as is usual in most other tools). -For compatibility, that searcher still tries the old format -if it cannot find an open function according to the new style. -(Lua 5.2 already worked that way, -but it did not document the change.) -</li> - -<li> -The call <code>collectgarbage("count")</code> now returns only one result. -(You can compute that second result from the fractional part -of the first result.) -</li> - -</ul> - - - - -<h2>8.3 – <a name="8.3">Changes in the API</a></h2> - - -<ul> - -<li> -Continuation functions now receive as arguments what they needed -to get through <code>lua_getctx</code>, -so <code>lua_getctx</code> has been removed. -Adapt your code accordingly. -</li> - -<li> -Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>. -Use 0 as the value of this parameter to get the old behavior. -</li> - -<li> -Functions to inject/project unsigned integers -(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>, -<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>) -were deprecated. -Use their signed equivalents with a type cast. -</li> - -<li> -Macros to project non-default integer types -(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>) -were deprecated. -Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast -(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code). -</li> - -</ul> - - - - -<h1>9 – <a name="9">The Complete Syntax of Lua</a></h1> - -<p> -Here is the complete syntax of Lua in extended BNF. -As usual in extended BNF, -{A} means 0 or more As, -and [A] means an optional A. -(For operator precedences, see <a href="#3.4.8">§3.4.8</a>; -for a description of the terminals -Name, Numeral, -and LiteralString, see <a href="#3.1">§3.1</a>.) - - - - -<pre> - - chunk ::= block - - block ::= {stat} [retstat] - - stat ::= ‘<b>;</b>’ | - varlist ‘<b>=</b>’ explist | - functioncall | - label | - <b>break</b> | - <b>goto</b> Name | - <b>do</b> block <b>end</b> | - <b>while</b> exp <b>do</b> block <b>end</b> | - <b>repeat</b> block <b>until</b> exp | - <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | - <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> | - <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | - <b>function</b> funcname funcbody | - <b>local</b> <b>function</b> Name funcbody | - <b>local</b> namelist [‘<b>=</b>’ explist] - - retstat ::= <b>return</b> [explist] [‘<b>;</b>’] - - label ::= ‘<b>::</b>’ Name ‘<b>::</b>’ - - funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name] - - varlist ::= var {‘<b>,</b>’ var} - - var ::= Name | prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ | prefixexp ‘<b>.</b>’ Name - - namelist ::= Name {‘<b>,</b>’ Name} - - explist ::= exp {‘<b>,</b>’ exp} - - exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | ‘<b>...</b>’ | functiondef | - prefixexp | tableconstructor | exp binop exp | unop exp - - prefixexp ::= var | functioncall | ‘<b>(</b>’ exp ‘<b>)</b>’ - - functioncall ::= prefixexp args | prefixexp ‘<b>:</b>’ Name args - - args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ | tableconstructor | LiteralString - - functiondef ::= <b>function</b> funcbody - - funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b> - - parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] | ‘<b>...</b>’ - - tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’ - - fieldlist ::= field {fieldsep field} [fieldsep] - - field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp | Name ‘<b>=</b>’ exp | exp - - fieldsep ::= ‘<b>,</b>’ | ‘<b>;</b>’ - - binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</b>’ | ‘<b>//</b>’ | ‘<b>^</b>’ | ‘<b>%</b>’ | - ‘<b>&</b>’ | ‘<b>~</b>’ | ‘<b>|</b>’ | ‘<b>>></b>’ | ‘<b><<</b>’ | ‘<b>..</b>’ | - ‘<b><</b>’ | ‘<b><=</b>’ | ‘<b>></b>’ | ‘<b>>=</b>’ | ‘<b>==</b>’ | ‘<b>~=</b>’ | - <b>and</b> | <b>or</b> - - unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’ | ‘<b>~</b>’ - -</pre> - -<p> - - - - - - - - -<P CLASS="footer"> -Last update: -Tue Jun 26 13:16:37 -03 2018 -</P> -<!-- -Last change: revised for Lua 5.3.5 ---> - -</body></html> - |