diff options
Diffstat (limited to 'gtk+-mingw/share/man/man3')
129 files changed, 0 insertions, 24859 deletions
diff --git a/gtk+-mingw/share/man/man3/TIFFClose.3tiff b/gtk+-mingw/share/man/man3/TIFFClose.3tiff deleted file mode 100644 index bcb7604..0000000 --- a/gtk+-mingw/share/man/man3/TIFFClose.3tiff +++ /dev/null @@ -1,53 +0,0 @@ -.\" $Id: TIFFClose.3tiff,v 1.3 2009-08-24 19:13:40 bfriesen Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFClose 3TIFF "November 2, 2005" "libtiff" -.SH NAME -TIFFClose \- close a previously opened -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "void TIFFClose(TIFF *" tif ")" -.SH DESCRIPTION -.IR TIFFClose -closes a file that was previously opened with -.BR TIFFOpen (3TIFF). -Any buffered data are flushed to the file, including the contents of the -current directory (if modified); and all resources are reclaimed. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -Likewise, warning messages are directed to the -.BR TIFFWarning (3TIFF) -routine. -.SH "SEE ALSO" -.BR libtiff (3TIFF), -.BR TIFFOpen (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFDataWidth.3tiff b/gtk+-mingw/share/man/man3/TIFFDataWidth.3tiff deleted file mode 100644 index cb274d8..0000000 --- a/gtk+-mingw/share/man/man3/TIFFDataWidth.3tiff +++ /dev/null @@ -1,74 +0,0 @@ -.\" $Id: TIFFDataWidth.3tiff,v 1.3 2006-03-23 14:54:02 dron Exp $ -.\" -.\" Copyright (c) 2002, Andrey Kiselev <dron@ak4719.spb.edu> -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFDataWidth 3TIFF "September 12, 2002" "libtiff" -.SH NAME -TIFFDataWidth \- Get the size of TIFF data types -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFDataWidth(TIFFDataType " type ")" -.SH DESCRIPTION -.I TIFFDataWidth -returns a size of -.I type -in bytes. -Currently following data types are supported: -.br -.I TIFF_BYTE -.br -.I TIFF_ASCII -.br -.I TIFF_SBYTE -.br -.I TIFF_UNDEFINED -.br -.I TIFF_SHORT -.br -.I TIFF_SSHORT -.br -.I TIFF_LONG -.br -.I TIFF_SLONG -.br -.I TIFF_FLOAT -.br -.I TIFF_IFD -.br -.I TIFF_RATIONAL -.br -.I TIFF_SRATIONAL -.br -.I TIFF_DOUBLE -.br -.SH "RETURN VALUES" -.br -.IR TIFFDataWidth -returns a number of bytes occupied by the item of given type. 0 returned when -uknown data type supplied. -.SH "SEE ALSO" -.BR libtiff (3TIFF), -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFError.3tiff b/gtk+-mingw/share/man/man3/TIFFError.3tiff deleted file mode 100644 index 761ff08..0000000 --- a/gtk+-mingw/share/man/man3/TIFFError.3tiff +++ /dev/null @@ -1,69 +0,0 @@ -.\" $Id: TIFFError.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFError 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFError, TIFFSetErrorHandler \- library error handling interface -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "void TIFFError(const char *" module ", const char *" fmt ", " ... ")" -.sp -.B "#include <stdarg.h>" -.sp -.BI "typedef void (*TIFFErrorHandler)(const char *" module ", const char *" fmt ", va_list " ap ");" -.br -.B "TIFFErrorHandler TIFFSetErrorHandler(TIFFErrorHandler handler);" -.SH DESCRIPTION -.I TIFFError -invokes the library-wide error handling function to (normally) write an error -message to the -.BR stderr . -The -.I fmt -parameter is a -.IR printf (3S) -format string, and any number arguments can be supplied. The -.I module -parameter, if non-zero, is printed before the message; it typically is used to -identify the software module in which an error is detected. -.PP -Applications that desire to capture control in the event of an error should -use -.IR TIFFSetErrorHandler -to override the default error handler. -A -.SM NULL -(0) error handling function may be installed to suppress error messages. -.SH "RETURN VALUES" -.IR TIFFSetErrorHandler -returns a reference to the previous error handling function. -.SH "SEE ALSO" -.BR TIFFWarning (3TIFF), -.BR libtiff (3TIFF), -.BR printf (3) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFFlush.3tiff b/gtk+-mingw/share/man/man3/TIFFFlush.3tiff deleted file mode 100644 index af32350..0000000 --- a/gtk+-mingw/share/man/man3/TIFFFlush.3tiff +++ /dev/null @@ -1,64 +0,0 @@ -.\" $Id: TIFFFlush.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFFlush 3TIFF "December 16, 1991" "libtiff" -.SH NAME -TIFFFlush, TIFFFlushData \- flush pending writes to an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFFlush(TIFF *" tif ")" -.br -.BI "int TIFFFlushData(TIFF *" tif ")" -.SH DESCRIPTION -.IR TIFFFlush -causes any pending writes for the specified file (including writes for the -current directory) to be done. In normal operation this call is never needed \- -the library automatically does any flushing required. -.PP -.IR TIFFFlushData -flushes any pending image data for the specified file to be written out; -directory-related data are not flushed. In normal operation this call is never -needed \- the library automatically does any flushing required. -.SH "RETURN VALUES" -0 is returned if an error is encountered, otherwise 1 is returned. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFWriteEncodedStrip (3TIFF), -.BR TIFFWriteEncodedTile (3TIFF), -.BR TIFFWriteRawStrip (3TIFF), -.BR TIFFWriteRawTile (3TIFF), -.BR TIFFWriteScanline (3TIFF), -.BR TIFFWriteTile (3TIFF) -.BR libtiff (3TIFF), -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFGetField.3tiff b/gtk+-mingw/share/man/man3/TIFFGetField.3tiff deleted file mode 100644 index 0624ee9..0000000 --- a/gtk+-mingw/share/man/man3/TIFFGetField.3tiff +++ /dev/null @@ -1,229 +0,0 @@ -.\" $Id: TIFFGetField.3tiff,v 1.6 2012-05-19 23:15:22 bfriesen Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFGetField 3TIFF "March 18, 2005" "libtiff" -.SH NAME -TIFFGetField, TIFFVGetField \- get the value(s) of a tag in an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFGetField(TIFF *" tif ", ttag_t " tag ", " ... ")" -.sp -.B "#include <stdarg.h>" -.sp -.BI "int TIFFVGetField(TIFF *" tif ", ttag_t " tag ", va_list " ap ")" -.br -.BI "int TIFFGetFieldDefaulted(TIFF *" tif ", ttag_t " tag ", " ... ")" -.br -.BI "int TIFFVGetFieldDefaulted(TIFF *" tif ", ttag_t " tag ", va_list " ap ")" -.SH DESCRIPTION -.IR TIFFGetField -returns the value of a tag or pseudo-tag associated with the the current -directory of the opened -.SM TIFF -file -.IR tif . -(A -.I pseudo-tag -is a parameter that is used to control the operation of the -.SM TIFF -library but whose value is not read or written to the underlying file.) The -file must have been previously opened with -.IR TIFFOpen (3TIFF). -The tag is identified by -.IR tag , -one of the values defined in the include file -.B tiff.h -(see also the table below). The type and number of values returned is -dependent on the tag being requested. The programming interface uses a -variable argument list as prescribed by the -.IR stdarg (3) -interface. The returned values should only be interpreted if -.IR TIFFGetField -returns 1. -.PP -.IR TIFFVGetField -is functionally equivalent to -.IR TIFFGetField -except that it takes a pointer to a variable argument list. -.I TIFFVGetField -is useful for layering interfaces on top of the functionality provided by -.IR TIFFGetField . -.PP -.IR TIFFGetFieldDefaulted -and -.IR TIFFVGetFieldDefaulted -are identical to -.IR TIFFGetField -and -.IR TIFFVGetField , -except that if a tag is not defined in the current directory and it has a -default value, then the default value is returned. -.PP -The tags understood by -.IR libtiff(3TIFF), -the number of parameter values, and the types for the returned values are -shown below. The data types are specified as in C and correspond to the types -used to specify tag values to -.IR TIFFSetField (3TIFF). -Remember that -.IR TIFFGetField -returns parameter values, so all the listed data types are pointers to storage -where values should be returned. -Consult the -.SM TIFF -specification (or relevant industry specification) for information on the -meaning of each tag and their possible values. -.PP -.nf -.ta \w'TIFFTAG_CONSECUTIVEBADFAXLINES'u+2n +\w'Count'u+2n +\w'TIFFFaxFillFunc*'u+2n -\fITag Name\fP \fICount\fP \fITypes\fP \fINotes\fP -.sp 5p -TIFFTAG_ARTIST 1 char** -TIFFTAG_BADFAXLINES 1 uint32* -TIFFTAG_BITSPERSAMPLE 1 uint16* -TIFFTAG_CLEANFAXDATA 1 uint16* -TIFFTAG_COLORMAP 3 uint16** 1<<BitsPerSample arrays -TIFFTAG_COMPRESSION 1 uint16* -TIFFTAG_CONSECUTIVEBADFAXLINES 1 uint32* -TIFFTAG_COPYRIGHT 1 char** -TIFFTAG_DATATYPE 1 uint16* -TIFFTAG_DATETIME 1 char** -TIFFTAG_DOCUMENTNAME 1 char** -TIFFTAG_DOTRANGE 2 uint16* -TIFFTAG_EXTRASAMPLES 2 uint16*,uint16** count & types array -TIFFTAG_FAXFILLFUNC 1 TIFFFaxFillFunc* G3/G4 compression pseudo-tag -TIFFTAG_FAXMODE 1 int* G3/G4 compression pseudo-tag -TIFFTAG_FILLORDER 1 uint16* -TIFFTAG_GROUP3OPTIONS 1 uint32* -TIFFTAG_GROUP4OPTIONS 1 uint32* -TIFFTAG_HALFTONEHINTS 2 uint16* -TIFFTAG_HOSTCOMPUTER 1 char** -TIFFTAG_ICCPROFILE 2 uint32*,void** count, profile data -TIFFTAG_IMAGEDEPTH 1 uint32* -TIFFTAG_IMAGEDESCRIPTION 1 char** -TIFFTAG_IMAGELENGTH 1 uint32* -TIFFTAG_IMAGEWIDTH 1 uint32* -TIFFTAG_INKNAMES 1 char** -TIFFTAG_INKSET 1 uint16* -TIFFTAG_JPEGCOLORMODE 1 int* JPEG pseudo-tag -TIFFTAG_JPEGQUALITY 1 int* JPEG pseudo-tag -TIFFTAG_JPEGTABLES 2 uint32*,void** count & tables -TIFFTAG_JPEGTABLESMODE 1 int* JPEG pseudo-tag -TIFFTAG_MAKE 1 char** -TIFFTAG_MATTEING 1 uint16* -TIFFTAG_MAXSAMPLEVALUE 1 uint16* -TIFFTAG_MINSAMPLEVALUE 1 uint16* -TIFFTAG_MODEL 1 char** -TIFFTAG_ORIENTATION 1 uint16* -TIFFTAG_PAGENAME 1 char** -TIFFTAG_PAGENUMBER 2 uint16* -TIFFTAG_PHOTOMETRIC 1 uint16* -TIFFTAG_PHOTOSHOP 2 uint32*,void** count, data -TIFFTAG_PLANARCONFIG 1 uint16* -TIFFTAG_PREDICTOR 1 uint16* -TIFFTAG_PRIMARYCHROMATICITIES 1 float** 6-entry array -TIFFTAG_REFERENCEBLACKWHITE 1 float** 6-entry array -TIFFTAG_RESOLUTIONUNIT 1 uint16* -TIFFTAG_RICHTIFFIPTC 2 uint32*,void** count, data -TIFFTAG_ROWSPERSTRIP 1 uint32* -TIFFTAG_SAMPLEFORMAT 1 uint16* -TIFFTAG_SAMPLESPERPIXEL 1 uint16* -TIFFTAG_SMAXSAMPLEVALUE 1 double* -TIFFTAG_SMINSAMPLEVALUE 1 double* -TIFFTAG_SOFTWARE 1 char** -TIFFTAG_STONITS 1 double** -TIFFTAG_STRIPBYTECOUNTS 1 uint32** -TIFFTAG_STRIPOFFSETS 1 uint32** -TIFFTAG_SUBFILETYPE 1 uint32* -TIFFTAG_SUBIFD 2 uint16*,uint32** count & offsets array -TIFFTAG_TARGETPRINTER 1 char** -TIFFTAG_THRESHHOLDING 1 uint16* -TIFFTAG_TILEBYTECOUNTS 1 uint32** -TIFFTAG_TILEDEPTH 1 uint32* -TIFFTAG_TILELENGTH 1 uint32* -TIFFTAG_TILEOFFSETS 1 uint32** -TIFFTAG_TILEWIDTH 1 uint32* -TIFFTAG_TRANSFERFUNCTION 1 or 3\(dg uint16**1<<BitsPerSample entry arrays -TIFFTAG_WHITEPOINT 1 float** 2-entry array -TIFFTAG_XMLPACKET 2 uint32*,void** count, data -TIFFTAG_XPOSITION 1 float* -TIFFTAG_XRESOLUTION 1 float* -TIFFTAG_YCBCRCOEFFICIENTS 1 float** 3-entry array -TIFFTAG_YCBCRPOSITIONING 1 uint16* -TIFFTAG_YCBCRSUBSAMPLING 2 uint16* -TIFFTAG_YPOSITION 1 float* -TIFFTAG_YRESOLUTION 1 float*\(dd -.fi -\(dg If -.I SamplesPerPixel -is one, then a single array is returned; otherwise three arrays are returned. -.fi -\(dd The contents of this field are quite complex. See -.IR "The ICC Profile Format Specification" , -Annex B.3 "Embedding ICC Profiles in TIFF Files" (available at -http://www.color.org) for an explanation. -.SH AUTOREGISTERED TAGS -If you can't find the tag in the table above that means this is an unsupported -tag and is not directly supported by -.BR libtiff(3TIFF) -library. You will still be able to read it's value if you know the data type of -that tag. For example, if you want to read the LONG value from the tag 33424 -and ASCII string from the tag 36867 you can use the following code: -.PP -.RS -.nf -uint32 count; -void *data; - -TIFFGetField(tiff, 33424, &count, &data); -printf("Tag %d: %d, count %d\n", 33424, *(uint32 *)data, count); -TIFFGetField(tiff, 36867, &count, &data); -printf("Tag %d: %s, count %d\n", 36867, (char *)data, count); -.fi -.RE -.PP -.SH RETURN VALUES -1 is returned if the tag is defined in the current directory; otherwise a 0 is -returned. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.PP -.BR "Unknown field, tag 0x%x" . -An unknown tag was supplied. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFSetField (3TIFF), -.BR TIFFSetDirectory (3TIFF), -.BR TIFFReadDirectory (3TIFF), -.BR TIFFWriteDirectory (3TIFF) -.BR libtiff (3TIFF), -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFOpen.3tiff b/gtk+-mingw/share/man/man3/TIFFOpen.3tiff deleted file mode 100644 index f420931..0000000 --- a/gtk+-mingw/share/man/man3/TIFFOpen.3tiff +++ /dev/null @@ -1,279 +0,0 @@ -.\" $Id: TIFFOpen.3tiff,v 1.2 2005-07-01 12:36:22 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFOpen 3TIFF "July 1, 2005" "libtiff" -.SH NAME -TIFFOpen, TIFFFdOpen, TIFFClientOpen \- open a -.SM TIFF -file for reading or writing -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "TIFF* TIFFOpen(const char *" filename ", const char *" mode ")" -.br -.BI "TIFF* TIFFFdOpen(const int " fd ", const char *" filename ", const char *" mode ")" -.sp -.B "typedef tsize_t (*TIFFReadWriteProc)(thandle_t, tdata_t, tsize_t);" -.br -.B "typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int);" -.br -.B "typedef int (*TIFFCloseProc)(thandle_t);" -.br -.B "typedef toff_t (*TIFFSizeProc)(thandle_t);" -.br -.B "typedef int (*TIFFMapFileProc)(thandle_t, tdata_t*, toff_t*);" -.br -.B "typedef void (*TIFFUnmapFileProc)(thandle_t, tdata_t, toff_t);" -.sp -.BI "TIFF* TIFFClientOpen(const char *" filename ", const char *" mode ", thandle_t " clientdata ", TIFFReadWriteProc " readproc ", TIFFReadWriteProc " writeproc ", TIFFSeekProc " seekproc ", TIFFCloseProc " closeproc ", TIFFSizeProc " sizeproc ", TIFFMapFileProc " mapproc ", TIFFUnmapFileProc " unmapproc ")" -.SH DESCRIPTION -.IR TIFFOpen -opens a -.SM TIFF -file whose name is -.I filename -and returns a handle to be used in subsequent calls to routines in -.IR libtiff . -If the open operation fails, then zero is returned. -The -.I mode -parameter specifies if the file is to be opened for reading (``r''), -writing (``w''), or appending (``a'') and, optionally, whether -to override certain default aspects of library operation (see below). -When a file is opened for appending, existing data will not -be touched; instead new data will be written as additional subfiles. -If an existing file is opened for writing, all previous data is -overwritten. -.PP -If a file is opened for reading, the first -.SM TIFF -directory in the file is automatically read -(also see -.IR TIFFSetDirectory (3TIFF) -for reading directories other than the first). -If a file is opened for writing or appending, a default directory -is automatically created for writing subsequent data. -This directory has all the default values specified in -.SM TIFF -Revision 6.0: -.IR BitsPerSample =1, -.IR ThreshHolding "=bilevel art scan," -.IR FillOrder =1 -(most significant bit of each data byte is filled first), -.IR Orientation =1 -(the 0th row represents the visual top of the image, and the 0th -column represents the visual left hand side), -.IR SamplesPerPixel =1, -.IR RowsPerStrip =infinity, -.IR ResolutionUnit =2 -(inches), and -.IR Compression =1 -(no compression). -To alter these values, or to define values for additional fields, -.IR TIFFSetField (3TIFF) -must be used. -.PP -.IR TIFFFdOpen -is like -.IR TIFFOpen -except that it opens a -.SM TIFF -file given an open file descriptor -.IR fd . -The file's name and mode must reflect that of the open descriptor. -The object associated with the file descriptor -.BR "must support random access" . -.PP -.IR TIFFClientOpen -is like -.IR TIFFOpen -except that the caller supplies a collection of functions that the -library will use to do \s-1UNIX\s+1-like I/O operations. -The -.I readproc -and -.I writeproc -are called to read and write data at the current file position. -.I seekproc -is called to change the current file position a la -.IR lseek (2). -.I closeproc -is invoked to release any resources associated with an open file. -.I sizeproc -is invoked to obtain the size in bytes of a file. -.I mapproc -and -.I unmapproc -are called to map and unmap a file's contents in memory; c.f. -.IR mmap (2) -and -.IR munmap (2). -The -.I clientdata -parameter is an opaque ``handle'' passed to the client-specified -routines passed as parameters to -.IR TIFFClientOpen . -.SH OPTIONS -The open mode parameter can include the following flags in -addition to the ``r'', ``w'', and ``a'' flags. -Note however that option flags must follow the read-write-append -specification. -.TP -.B l -When creating a new file force information be written with -Little-Endian byte order (but see below). -By default the library will create new files using the native -.SM CPU -byte order. -.TP -.B b -When creating a new file force information be written with -Big-Endian byte order (but see below). -By default the library will create new files using the native -.SM CPU -byte order. -.TP -.B L -Force image data that is read or written to be treated with -bits filled from Least Significant Bit (\s-1LSB\s+1) to -Most Significant Bit (\s-1MSB\s+1). -Note that this is the opposite to the way the library has -worked from its inception. -.TP -.B B -Force image data that is read or written to be treated with -bits filled from Most Significant Bit (\s-1MSB\s+1) to -Least Significant Bit (\s-1LSB\s+1); this is the default. -.TP -.B H -Force image data that is read or written to be treated with -bits filled in the same order as the native -.SM CPU. -.TP -.B M -Enable the use of memory-mapped files for images opened read-only. -If the underlying system does not support memory-mapped files -or if the specific image being opened cannot be memory-mapped -then the library will fallback to using the normal system interface -for reading information. -By default the library will attempt to use memory-mapped files. -.TP -.B m -Disable the use of memory-mapped files. -.TP -.B C -Enable the use of ``strip chopping'' when reading images -that are comprised of a single strip or tile of uncompressed data. -Strip chopping is a mechanism by which the library will automatically -convert the single-strip image to multiple strips, -each of which has about 8 Kilobytes of data. -This facility can be useful in reducing the amount of memory used -to read an image because the library normally reads each strip -in its entirety. -Strip chopping does however alter the apparent contents of the -image because when an image is divided into multiple strips it -looks as though the underlying file contains multiple separate -strips. -Finally, note that default handling of strip chopping is a compile-time -configuration parameter. -The default behaviour, for backwards compatibility, is to enable -strip chopping. -.TP -.B c -Disable the use of strip chopping when reading images. -.TP -.B h -Read TIFF header only, do not load the first image directory. That could be -useful in case of the broken first directory. We can open the file and proceed -to the other directories. -.SH "BYTE ORDER" -The -.SM TIFF -specification (\fBall versions\fP) states that compliant readers -.IR "must be capable of reading images written in either byte order" . -Nonetheless some software that claims to support the reading of -.SM TIFF -images is incapable of reading images in anything but the native -.SM CPU -byte order on which the software was written. -(Especially notorious -are applications written to run on Intel-based machines.) -By default the library will create new files with the native -byte-order of the -.SM CPU -on which the application is run. -This ensures optimal performance and is portable to any application -that conforms to the TIFF specification. -To force the library to use a specific byte-order when creating -a new file the ``b'' and ``l'' option flags may be included in -the call to open a file; for example, ``wb'' or ``wl''. -.SH "RETURN VALUES" -Upon successful completion -.IR TIFFOpen , -.IR TIFFFdOpen , -and -.IR TIFFClientOpen -return a -.SM TIFF -pointer. -Otherwise, NULL is returned. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -Likewise, warning messages are directed to the -.IR TIFFWarning (3TIFF) -routine. -.PP -\fB"%s": Bad mode\fP. -The specified -.I mode -parameter was not one of ``r'' (read), ``w'' (write), or ``a'' (append). -.PP -.BR "%s: Cannot open" . -.IR TIFFOpen () -was unable to open the specified filename for read/writing. -.PP -.BR "Cannot read TIFF header" . -An error occurred while attempting to read the header information. -.PP -.BR "Error writing TIFF header" . -An error occurred while writing the default header information -for a new file. -.PP -.BR "Not a TIFF file, bad magic number %d (0x%x)" . -The magic number in the header was not (hex) -0x4d4d or (hex) 0x4949. -.PP -.BR "Not a TIFF file, bad version number %d (0x%x)" . -The version field in the header was not 42 (decimal). -.PP -.BR "Cannot append to file that has opposite byte ordering" . -A file with a byte ordering opposite to the native byte -ordering of the current machine was opened for appending (``a''). -This is a limitation of the library. -.SH "SEE ALSO" -.IR libtiff (3TIFF), -.IR TIFFClose (3TIFF) diff --git a/gtk+-mingw/share/man/man3/TIFFPrintDirectory.3tiff b/gtk+-mingw/share/man/man3/TIFFPrintDirectory.3tiff deleted file mode 100644 index 437b09e..0000000 --- a/gtk+-mingw/share/man/man3/TIFFPrintDirectory.3tiff +++ /dev/null @@ -1,70 +0,0 @@ -.\" $Id: TIFFPrintDirectory.3tiff,v 1.1 2004-11-11 14:39:16 dron Exp $ -.\" -.\" Copyright (c) 1991-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFPrintDirectory 3TIFF "December 12, 1991" "libtiff" -.SH NAME -TIFFPrintDirectory \- print a description of a -.SM TIFF -directory -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "void TIFFPrintDirectory(TIFF *" tif ", FILE *" fd ", long " flags ")" -.SH DESCRIPTION -.I TIFFPrintDirectory -prints a description of the current directory in the specified -.SM TIFF -file to the standard I/O output stream -.IR fd . -The -.I flags -parameter is used to control the -.I "level of detail" -of the printed information; it is a bit-or of the flags defined in -.BR tiffio.h : -.sp .5 -.nf -.ta \w'#define 'u +\w'TIFFPRINT_JPEGDCTABLES 'u +\w'0x200 'u -#define TIFFPRINT_NONE 0x0 /* no extra info */ -#define TIFFPRINT_STRIPS 0x1 /* strips/tiles info */ -#define TIFFPRINT_CURVES 0x2 /* color/gray response curves */ -#define TIFFPRINT_COLORMAP 0x4 /* colormap */ -#define TIFFPRINT_JPEGQTABLES 0x100 /* JPEG Q matrices */ -#define TIFFPRINT_JPEGACTABLES 0x200 /* JPEG AC tables */ -#define TIFFPRINT_JPEGDCTABLES 0x200 /* JPEG DC tables */ -.fi -.SH NOTES -In C++ the -.I flags -parameter defaults to 0. -.SH "RETURN VALUES" -None. -.SH DIAGNOSTICS -None. -.SH "SEE ALSO" -.IR libtiff (3TIFF), -.IR TIFFOpen (3TIFF), -.IR TIFFReadDirectory (3TIFF), -.IR TIFFSetDirectory (3TIFF) diff --git a/gtk+-mingw/share/man/man3/TIFFRGBAImage.3tiff b/gtk+-mingw/share/man/man3/TIFFRGBAImage.3tiff deleted file mode 100644 index ef1a85c..0000000 --- a/gtk+-mingw/share/man/man3/TIFFRGBAImage.3tiff +++ /dev/null @@ -1,286 +0,0 @@ -.\" $Id: TIFFRGBAImage.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1991-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFRGBAImage 3TIFF "October 29, 2004" "libtiff" -.SH NAME -TIFFRGBAImageOK, TIFFRGBAImageBegin, TIFFRGBAImageGet, TIFFRGBAImageEnd -\- read and decode an image into a raster -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.B "typedef unsigned char TIFFRGBValue;" -.B "typedef struct _TIFFRGBAImage TIFFRGBAImage;" -.sp -.BI "int TIFFRGBAImageOK(TIFF *" tif ", char " emsg[1024] ")" -.br -.BI "int TIFFRGBAImageBegin(TIFFRGBAImage *" img ", TIFF* " tif ", int " stopOnError ", char " emsg[1024] ")" -.br -.BI "int TIFFRGBAImageGet(TIFFRGBAImage *" img ", uint32* " raster ", uint32 " width " , uint32 " height ")" -.br -.BI "void TIFFRGBAImageEnd(TIFFRGBAImage *" img ")" -.br -.SH DESCRIPTION -The routines described here provide a high-level interface -through which -.SM TIFF -images may be read into memory. -Images may be strip- or tile-based and have a variety of different -characteristics: bits/sample, samples/pixel, photometric, etc. -Decoding state is encapsulated in a -.I TIFFRGBAImage -structure making it possible to capture state for multiple images -and quickly switch between them. -The target raster format can be customized to a particular application's -needs by installing custom routines that manipulate image data -according to application requirements. -.PP -The default usage for these routines is: check if an image can -be processed using -.IR TIFFRGBAImageOK , -construct a decoder state block using -.IR TIFFRGBAImageBegin , -read and decode an image into a target raster using -.IR TIFFRGBAImageGet , -and then -release resources using -.IR TIFFRGBAImageEnd . -.I TIFFRGBAImageGet -can be called multiple times to decode an image using different -state parameters. -If multiple images are to be displayed and there is not enough -space for each of the decoded rasters, multiple state blocks can -be managed and then calls can be made to -.I TIFFRGBAImageGet -as needed to display an image. -.PP -The generated raster is assumed to be an array of -.I width -times -.I height -32-bit entries, where -.I width -must be less than or equal to the width of the image (\c -.I height -may be any non-zero size). -If the raster dimensions are smaller than the image, the image data -is cropped to the raster bounds. -If the raster height is greater than that of the image, then the -image data are placed in the lower part of the raster. -(Note that the raster is assume to be organized such that the pixel -at location (\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP]; -with the raster origin in the -.B lower-left -hand corner.) -.PP -Raster pixels are 8-bit packed red, green, blue, alpha samples. -The macros -.IR TIFFGetR , -.IR TIFFGetG , -.IR TIFFGetB , -and -.I TIFFGetA -should be used to access individual samples. -Images without Associated Alpha matting information have a constant -Alpha of 1.0 (255). -.PP -.I TIFFRGBAImageGet -converts non-8-bit images by scaling sample values. -Palette, grayscale, bilevel, -.SM CMYK\c -, and YCbCr images are converted to -.SM RGB -transparently. -Raster pixels are returned uncorrected by any colorimetry information -present in the directory. -.PP -The parameter -.I stopOnError -specifies how to act if an error is encountered while reading -the image. -If -.I stopOnError -is non-zero, then an error will terminate the operation; otherwise -.I TIFFRGBAImageGet -will continue processing data until all the possible data in the -image have been requested. -.SH "ALTERNATE RASTER FORMATS" -To use the core support for reading and processing -.SM TIFF -images, but write the resulting raster data in a different format -one need only override the ``\fIput methods\fP'' used to store raster data. -These methods are are defined in the -.I TIFFRGBAImage -structure and initially setup by -.I TIFFRGBAImageBegin -to point to routines that pack raster data in the default -.SM ABGR -pixel format. -Two different routines are used according to the physical organization -of the image data in the file: -.IR PlanarConfiguration =1 -(packed samples), -and -.IR PlanarConfiguration =2 -(separated samples). -Note that this mechanism can be used to transform the data before -storing it in the raster. -For example one can convert data -to colormap indices for display on a colormap display. -.SH "SIMULTANEOUS RASTER STORE AND DISPLAY" -It is simple to display an image as it is being read into memory -by overriding the put methods as described above for supporting -alternate raster formats. -Simply keep a reference to the default put methods setup by -.I TIFFRGBAImageBegin -and then invoke them before or after each display operation. -For example, the -.IR tiffgt (1) -utility uses the following put method to update the display as -the raster is being filled: -.sp -.nf -.ft C -static void -putContigAndDraw(TIFFRGBAImage* img, uint32* raster, - uint32 x, uint32 y, uint32 w, uint32 h, - int32 fromskew, int32 toskew, - unsigned char* cp) -{ - (*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp); - if (x+w == width) { - w = width; - if (img->orientation == ORIENTATION_TOPLEFT) - lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w); - else - lrectwrite(0, y, w-1, y+h-1, raster); - } -} -.ft R -.fi -.sp -(the original routine provided by the library is saved in the -variable -.IR putContig .) -.SH "SUPPORTING ADDITIONAL TIFF FORMATS" -The -.I TIFFRGBAImage -routines support the most commonly encountered flavors of -.SM TIFF. -It is possible to extend this support by overriding the ``\fIget method\fP'' -invoked by -.I TIFFRGBAImageGet -to read -.SM TIFF -image data. -Details of doing this are a bit involved, it is best to make a copy -of an existing get method and modify it to suit the needs of an -application. -.SH NOTES -Samples must be either 1, 2, 4, 8, or 16 bits. -Colorimetric samples/pixel must be either 1, 3, or 4 (i.e. -.I SamplesPerPixel -minus -.IR ExtraSamples ). -.PP -Palette image colormaps that appear to be incorrectly written -as 8-bit values are automatically scaled to 16-bits. -.SH "RETURN VALUES" -All routines return -1 if the operation was successful. -Otherwise, 0 is returned if an error was encountered and -.I stopOnError -is zero. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -.PP -.BR "Sorry, can not handle %d-bit pictures" . -The image had -.I BitsPerSample -other than 1, 2, 4, 8, or 16. -.PP -.BR "Sorry, can not handle %d-channel images" . -The image had -.I SamplesPerPixel -other than 1, 3, or 4. -.PP -\fBMissing needed "PhotometricInterpretation" tag\fP. -The image did not have a tag that describes how to display -the data. -.PP -\fBNo "PhotometricInterpretation" tag, assuming RGB\fP. -The image was missing a tag that describes how to display it, -but because it has 3 or 4 samples/pixel, it is assumed to be -.SM RGB. -.PP -\fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP. -The image was missing a tag that describes how to display it, -but because it has 1 sample/pixel, it is assumed to be a grayscale -or bilevel image. -.PP -.BR "No space for photometric conversion table" . -There was insufficient memory for a table used to convert -image samples to 8-bit -.SM RGB. -.PP -\fBMissing required "Colormap" tag\fP. -A Palette image did not have a required -.I Colormap -tag. -.PP -.BR "No space for tile buffer" . -There was insufficient memory to allocate an i/o buffer. -.PP -.BR "No space for strip buffer" . -There was insufficient memory to allocate an i/o buffer. -.PP -.BR "Can not handle format" . -The image has a format (combination of -.IR BitsPerSample , -.IR SamplesPerPixel , -and -.IR PhotometricInterpretation ) -that can not be handled. -.PP -.BR "No space for B&W mapping table" . -There was insufficient memory to allocate a table used to map -grayscale data to -.SM RGB. -.PP -.BR "No space for Palette mapping table" . -There was insufficient memory to allocate a table used to map -data to 8-bit -.SM RGB. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFReadRGBAImage (3TIFF), -.BR TIFFReadRGBAImageOriented (3TIFF), -.BR TIFFReadRGBAStrip (3TIFF), -.BR TIFFReadRGBATile (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFReadDirectory.3tiff b/gtk+-mingw/share/man/man3/TIFFReadDirectory.3tiff deleted file mode 100644 index 000bf0a..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadDirectory.3tiff +++ /dev/null @@ -1,164 +0,0 @@ -.\" $Id: TIFFReadDirectory.3tiff,v 1.3 2010-12-12 01:45:35 faxguy Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadDirectory 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFReadDirectory \- get the contents of the next directory in an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFReadDirectory(TIFF *" tif ")" -.SH DESCRIPTION -Read the next directory in the specified file and make it the current -directory. Applications only need to call -.I TIFFReadDirectory -to read multiple subfiles in a single -.SM TIFF -file\(em -the first directory in a file is automatically read when -.IR TIFFOpen -is called. -.SH NOTES -If the library is compiled with -.SM STRIPCHOP_SUPPORT -enabled, then images that have a single uncompressed strip or tile of data are -automatically treated as if they were made up of multiple strips or tiles of -approximately 8 kilobytes each. This operation is done only in-memory; it does -not alter the contents of the file. However, the construction of the ``chopped -strips'' is visible to the application through the number of strips [tiles] -returned by -.I TIFFNumberOfStrips -[\c -.IR TIFFNumberOfTiles ]. -.SH "RETURN VALUES" -If the next directory was successfully read, 1 is returned. Otherwise, 0 is -returned if an error was encountered, or if there are no more directories to -be read. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -All warning messages are directed to the -.IR TIFFWarning (3TIFF) -routine. -.PP -\fBSeek error accessing TIFF directory\fP. -An error occurred while positioning to the location of the -directory. -.PP -\fBWrong data type %d for field "%s"\fP. -The tag entry in the directory had an incorrect data type. -For example, an -.I ImageDescription -tag with a -.SM SHORT -data type. -.PP -\fBTIFF directory is missing required "%s" field\fP. -The specified tag is required to be present by the -.SM TIFF -5.0 specification, but is missing. -The directory is (usually) unusable. -.PP -\fB%s: Rational with zero denominator\fP. -A directory tag has a -.SM RATIONAL -value whose denominator is zero. -.PP -\fBIncorrect count %d for field "%s" (%lu, expecting %lu); tag ignored\fP. -The specified tag's count field is bad. -For example, a count other than 1 for a -.I SubFileType -tag. -.PP -\fBCannot handle different per-sample values for field "%s"\fP. -The tag has -.I SamplesPerPixel -values and they are not all the same; e.g. -.IR BitsPerSample . -The library is unable to handle images of this sort. -.PP -\fBCount mismatch for field "%s"; expecting %d, got %d\fP. -The count field in a -tag does not agree with the number expected by the library. -This should never happen, so if it does, the library refuses to -read the directory. -.PP -\fBInvalid TIFF directory; tags are not sorted in ascending order\fP. -The directory tags are not properly sorted as specified -in the -.SM TIFF -5.0 specification. -This error is not fatal. -.PP -\fBIgnoring unknown field with tag %d (0x%x)\fP. -An unknown tag was encountered in the directory; -the library ignores all such tags. -.PP -\fBTIFF directory is missing required "ImageLength" field\fP. -The image violates the specification by not having a necessary field. -There is no way for the library to recover from this error. -.PP -\fBTIFF directory is missing required "PlanarConfig" field\fP. -The image violates the specification by not having a necessary field. -There is no way for the library to recover from this error. -.PP -\fBTIFF directory is missing required "StripOffsets" field\fP. -The image has multiple strips, but is missing the tag that -specifies the file offset to each strip of data. -There is no way for the library to recover from this error. -.PP -\fBTIFF directory is missing required "TileOffsets" field\fP. -The image has multiple tiles, but is missing the tag that -specifies the file offset to each tile of data. -There is no way for the library to recover from this error. -.PP -\fBTIFF directory is missing required "StripByteCounts" field\fP. -The image has multiple strips, but is missing the tag that -specifies the size of each strip of data. -There is no way for the library to recover from this error. -.PP -\fBTIFF directory is missing required "StripByteCounts" field, calculating from imagelength\fP. -The image violates the specification by not having a necessary field. -However, when the image is comprised of only one strip or tile, the -library will estimate the missing value based on the file size. -.PP -\fBBogus "StripByteCounts" field, ignoring and calculating from imagelength\fP. -Certain vendors violate the specification by writing zero for -the StripByteCounts tag when they want to leave the value -unspecified. -If the image has a single strip, the library will estimate -the missing value based on the file size. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFWriteDirectory (3TIFF), -.BR TIFFSetDirectory (3TIFF), -.BR TIFFSetSubDirectory (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFReadEncodedStrip.3tiff b/gtk+-mingw/share/man/man3/TIFFReadEncodedStrip.3tiff deleted file mode 100644 index d2d7b67..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadEncodedStrip.3tiff +++ /dev/null @@ -1,78 +0,0 @@ -.\" $Id: TIFFReadEncodedStrip.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadEncodedStrip 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFReadEncodedStrip \- read and decode a strip of data from an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFReadEncodedStrip(TIFF *" tif ", tstrip_t " strip ", tdata_t " buf ", tsize_t " size ")" -.SH DESCRIPTION -Read the specified strip of data and place up to -.I size -bytes of decompressed information in the (user supplied) data buffer. -.SH NOTES -The value of -.I strip -is a ``raw strip number.'' -That is, the caller must take into account whether or not the data are -organized in separate planes (\c -.IR PlanarConfiguration =2). -To read a full strip of data the data buffer should typically be at least as -large as the number returned by -.BR TIFFStripSize (3TIFF). -If the -1 passed in -.I size -parameter, the whole strip will be read. You should be sure you have enough -space allocated for the buffer. -.PP -The library attempts to hide bit- and byte-ordering differences between the -image and the native machine by converting data to the native machine order. -Bit reversal is done if the -.I FillOrder -tag is opposite to the native machine bit order. 16- and 32-bit samples are -automatically byte-swapped if the file was written with a byte order opposite -to the native machine byte order, -.SH "RETURN VALUES" -The actual number of bytes of data that were placed in -.I buf -is returned; -.IR TIFFReadEncodedStrip -returns \-1 if an error was encountered. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFReadRawStrip (3TIFF), -.BR TIFFReadScanline (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFReadEncodedTile.3tiff b/gtk+-mingw/share/man/man3/TIFFReadEncodedTile.3tiff deleted file mode 100644 index 5f6d900..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadEncodedTile.3tiff +++ /dev/null @@ -1,76 +0,0 @@ -.\" $Id: TIFFReadEncodedTile.3tiff,v 1.3 2006-10-13 07:22:01 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadEncodedTile 3TIFF "October 13, 2006" "libtiff" -.SH NAME -TIFFReadEncodedTile \- read and decode a tile of data from an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFReadEncodedTile(TIFF *" tif ", ttile_t " tile ", tdata_t " buf ", tsize_t " size ")" -.SH DESCRIPTION -Read the specified tile of data and place up to -.I size -bytes of decompressed information in the (user supplied) data buffer. -.SH NOTES -The value of -.I tile -is a ``raw tile number.'' -That is, the caller must take into account whether or not the data are -organized in separate planes (\c -.IR PlanarConfiguration =2). -.IR TIFFComputeTile -automatically does this when converting an (x,y,z,sample) coordinate quadruple -to a tile number. To read a full tile of data the data buffer should be at -least as large as the value returned by -.IR TIFFTileSize . -.PP -The library attempts to hide bit- and byte-ordering differences between the -image and the native machine by converting data to the native machine order. -Bit reversal is done if the -.I FillOrder -tag is opposite to the native machine bit order. 16- and 32-bit samples are -automatically byte-swapped if the file was written with a byte order opposite -to the native machine byte order, -.SH "RETURN VALUES" -The actual number of bytes of data that were placed in -.I buf -is returned; -.IR TIFFReadEncodedTile -returns \-1 if an error was encountered. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFReadRawTile (3TIFF), -.BR TIFFReadTile (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFReadRGBAImage.3tiff b/gtk+-mingw/share/man/man3/TIFFReadRGBAImage.3tiff deleted file mode 100644 index 5d43ce3..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadRGBAImage.3tiff +++ /dev/null @@ -1,218 +0,0 @@ -.\" $Id: TIFFReadRGBAImage.3tiff,v 1.4 2006-10-13 07:22:01 dron Exp $ -.\" -.\" Copyright (c) 1991-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadRGBAImage 3TIFF "October 13, 2006" "libtiff" -.SH NAME -TIFFReadRGBAImage, TIFFReadRGBAImageOriented \- read and decode an image -into a fixed-format raster -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.B "#define TIFFGetR(abgr) ((abgr) & 0xff)" -.br -.B "#define TIFFGetG(abgr) (((abgr) >> 8) & 0xff)" -.br -.B "#define TIFFGetB(abgr) (((abgr) >> 16) & 0xff)" -.br -.B "#define TIFFGetA(abgr) (((abgr) >> 24) & 0xff)" -.sp -.BI "int TIFFReadRGBAImage(TIFF *" tif ", uint32 " width ", uint32 " height ", uint32 *" raster ", int " stopOnError ")" -.br -.BI "int TIFFReadRGBAImageOriented(TIFF *" tif ", uint32 " width ", uint32 " height ", uint32 *" raster ", int " orientation ", int " stopOnError ")" -.br -.SH DESCRIPTION -.IR TIFFReadRGBAImage -reads a strip- or tile-based image into memory, storing the -result in the user supplied -.IR raster . -The raster is assumed to be an array of -.I width -times -.I height -32-bit entries, where -.I width -must be less than or equal to the width of the image (\c -.I height -may be any non-zero size). -If the raster dimensions are smaller than the image, the image data -is cropped to the raster bounds. -If the raster height is greater than that of the image, then the -image data are placed in the lower part of the raster. -(Note that the raster is assume to be organized such that the pixel -at location (\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP]; -with the raster origin in the lower-left hand corner.) -.PP -.IR TIFFReadRGBAImageOriented -works like -.IR TIFFReadRGBAImage -with except of that user can specify the raster origin position with the -.I orientation -parameter. Four orientations supported: -.TP -.B ORIENTATION_TOPLEFT -origin in top-left corner, -.TP -.B ORIENTATION_TOPRIGHT -origin in top-right corner, -.TP -.B ORIENTATION_BOTLEFT -origin in bottom-left corner -and -.TP -.B ORIENTATION_BOTRIGHT -origin in bottom-right corner. -.LP -If you choose -.B ORIENTATION_BOTLEFT -result will be the same as returned by the -.IR TIFFReadRGBAImage. -.PP -Raster pixels are 8-bit packed red, green, blue, alpha samples. -The macros -.IR TIFFGetR , -.IR TIFFGetG , -.IR TIFFGetB , -and -.I TIFFGetA -should be used to access individual samples. -Images without Associated Alpha matting information have a constant -Alpha of 1.0 (255). -.PP -.I TIFFReadRGBAImage -converts non-8-bit images by scaling sample values. -Palette, grayscale, bilevel, -.SM CMYK\c -, and YCbCr images are converted to -.SM RGB -transparently. -Raster pixels are returned uncorrected by any colorimetry information -present in the directory. -.PP -The paramater -.I stopOnError -specifies how to act if an error is encountered while reading -the image. -If -.I stopOnError -is non-zero, then an error will terminate the operation; otherwise -.I TIFFReadRGBAImage -will continue processing data until all the possible data in the -image have been requested. -.SH NOTES -In C++ the -.I stopOnError -parameter defaults to 0. -.PP -Samples must be either 1, 2, 4, 8, or 16 bits. -Colorimetric samples/pixel must be either 1, 3, or 4 (i.e. -.I SamplesPerPixel -minus -.IR ExtraSamples ). -.PP -Palettte image colormaps that appear to be incorrectly written -as 8-bit values are automatically scaled to 16-bits. -.PP -.I TIFFReadRGBAImage -is just a wrapper around the more general -.IR TIFFRGBAImage (3TIFF) -facilities. -.SH "RETURN VALUES" -1 is returned if the image was successfully read and converted. -Otherwise, 0 is returned if an error was encountered and -.I stopOnError -is zero. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -.PP -.BR "Sorry, can not handle %d-bit pictures" . -The image had -.I BitsPerSample -other than 1, 2, 4, 8, or 16. -.PP -.BR "Sorry, can not handle %d-channel images" . -The image had -.I SamplesPerPixel -other than 1, 3, or 4. -.PP -\fBMissing needed "PhotometricInterpretation" tag\fP. -The image did not have a tag that describes how to display -the data. -.PP -\fBNo "PhotometricInterpretation" tag, assuming RGB\fP. -The image was missing a tag that describes how to display it, -but because it has 3 or 4 samples/pixel, it is assumed to be -.SM RGB. -.PP -\fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP. -The image was missing a tag that describes how to display it, -but because it has 1 sample/pixel, it is assumed to be a grayscale -or bilevel image. -.PP -.BR "No space for photometric conversion table" . -There was insufficient memory for a table used to convert -image samples to 8-bit -.SM RGB. -.PP -\fBMissing required "Colormap" tag\fP. -A Palette image did not have a required -.I Colormap -tag. -.PP -.BR "No space for tile buffer" . -There was insufficient memory to allocate an i/o buffer. -.PP -.BR "No space for strip buffer" . -There was insufficient memory to allocate an i/o buffer. -.PP -.BR "Can not handle format" . -The image has a format (combination of -.IR BitsPerSample , -.IR SamplesPerPixel , -and -.IR PhotometricInterpretation ) -that -.I TIFFReadRGBAImage -can not handle. -.PP -.BR "No space for B&W mapping table" . -There was insufficient memory to allocate a table used to map -grayscale data to -.SM RGB. -.PP -.BR "No space for Palette mapping table" . -There was insufficient memory to allocate a table used to map -data to 8-bit -.SM RGB. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFRGBAImage (3TIFF), -.BR TIFFReadRGBAStrip (3TIFF), -.BR TIFFReadRGBATile (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFReadRGBAStrip.3tiff b/gtk+-mingw/share/man/man3/TIFFReadRGBAStrip.3tiff deleted file mode 100644 index a8bb189..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadRGBAStrip.3tiff +++ /dev/null @@ -1,170 +0,0 @@ -.\" $Id: TIFFReadRGBAStrip.3tiff,v 1.3 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1991-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadRGBAStrip 3TIFF "December 10, 1998" "libtiff" -.SH NAME -TIFFReadRGBAStrip \- read and decode an image strip into a fixed-format raster -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.B "#define TIFFGetR(abgr) ((abgr) & 0xff)" -.br -.B "#define TIFFGetG(abgr) (((abgr) >> 8) & 0xff)" -.br -.B "#define TIFFGetB(abgr) (((abgr) >> 16) & 0xff)" -.br -.B "#define TIFFGetA(abgr) (((abgr) >> 24) & 0xff)" -.sp -.BI "int TIFFReadRGBAStrip(TIFF *" tif ", uint32 " row ", uint32 *" raster ")" -.SH DESCRIPTION -.IR TIFFReadRGBAStrip -reads a single strip of a strip-based image into memory, storing the result in -the user supplied RGBA -.IR raster . -The raster is assumed to be an array of width times rowsperstrip 32-bit -entries, where width is the width of the image (TIFFTAG_IMAGEWIDTH) and -rowsperstrip is the maximum lines in a strip (TIFFTAG_ROWSPERSTRIP). - -.PP -The -.IR row -value should be the row of the first row in the strip (strip * rowsperstrip, -zero based). - -.PP -Note that the raster is assume to be organized such that the pixel at location -(\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP]; with the -raster origin in the -.I lower-left hand corner -of the strip. That is bottom to top organization. When reading a partial last -strip in the file the last line of the image will begin at the beginning of -the buffer. - -.PP -Raster pixels are 8-bit packed red, green, blue, alpha samples. The macros -.IR TIFFGetR , -.IR TIFFGetG , -.IR TIFFGetB , -and -.I TIFFGetA -should be used to access individual samples. Images without Associated Alpha -matting information have a constant Alpha of 1.0 (255). -.PP -See the -.IR TIFFRGBAImage (3TIFF) -page for more details on how various image types are converted to RGBA values. -.SH NOTES -Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel must -be either 1, 3, or 4 (i.e. -.I SamplesPerPixel -minus -.IR ExtraSamples ). -.PP -Palette image colormaps that appear to be incorrectly written as 8-bit values -are automatically scaled to 16-bits. -.PP -.I TIFFReadRGBAStrip -is just a wrapper around the more general -.IR TIFFRGBAImage (3TIFF) -facilities. It's main advantage over the similar -.IR TIFFReadRGBAImage() -function is that for large images a single buffer capable of holding the whole -image doesn't need to be allocated, only enough for one strip. The -.IR TIFFReadRGBATile() -function does a similar operation for tiled images. -.SH "RETURN VALUES" -1 is returned if the image was successfully read and converted. -Otherwise, 0 is returned if an error was encountered. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -.PP -.BR "Sorry, can not handle %d-bit pictures" . -The image had -.I BitsPerSample -other than 1, 2, 4, 8, or 16. -.PP -.BR "Sorry, can not handle %d-channel images" . -The image had -.I SamplesPerPixel -other than 1, 3, or 4. -.PP -\fBMissing needed "PhotometricInterpretation" tag\fP. -The image did not have a tag that describes how to display the data. -.PP -\fBNo "PhotometricInterpretation" tag, assuming RGB\fP. -The image was missing a tag that describes how to display it, but because it -has 3 or 4 samples/pixel, it is assumed to be -.SM RGB. -.PP -\fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP. The image was -missing a tag that describes how to display it, but because it has 1 -sample/pixel, it is assumed to be a grayscale or bilevel image. -.PP -.BR "No space for photometric conversion table" . -There was insufficient memory for a table used to convert image samples to -8-bit -.SM RGB. -.PP -\fBMissing required "Colormap" tag\fP. -A Palette image did not have a required -.I Colormap -tag. -.PP -.BR "No space for tile buffer" . -There was insufficient memory to allocate an i/o buffer. -.PP -.BR "No space for strip buffer" . -There was insufficient memory to allocate an i/o buffer. -.PP -.BR "Can not handle format" . -The image has a format (combination of -.IR BitsPerSample , -.IR SamplesPerPixel , -and -.IR PhotometricInterpretation ) -that -.I TIFFReadRGBAImage -can not handle. -.PP -.BR "No space for B&W mapping table" . -There was insufficient memory to allocate a table used to map grayscale data -to -.SM RGB. -.PP -.BR "No space for Palette mapping table" . -There was insufficient memory to allocate a table used to map data to 8-bit -.SM RGB. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFRGBAImage (3TIFF), -.BR TIFFReadRGBAImage (3TIFF), -.BR TIFFReadRGBATile (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ - diff --git a/gtk+-mingw/share/man/man3/TIFFReadRGBATile.3tiff b/gtk+-mingw/share/man/man3/TIFFReadRGBATile.3tiff deleted file mode 100644 index dfae1a9..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadRGBATile.3tiff +++ /dev/null @@ -1,171 +0,0 @@ -.\" $Id: TIFFReadRGBATile.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1991-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadRGBATile 3TIFF "December 10, 1998" "libtiff" -.SH NAME -TIFFReadRGBATile \- read and decode an image tile into a fixed-format raster -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.B "#define TIFFGetR(abgr) ((abgr) & 0xff)" -.br -.B "#define TIFFGetG(abgr) (((abgr) >> 8) & 0xff)" -.br -.B "#define TIFFGetB(abgr) (((abgr) >> 16) & 0xff)" -.br -.B "#define TIFFGetA(abgr) (((abgr) >> 24) & 0xff)" -.sp -.BI "int TIFFReadRGBATile(TIFF *" tif ", uint32 " x ", uint32 " y ", uint32 *" raster ")" -.SH DESCRIPTION -.IR TIFFReadRGBATile -reads a single tile of a tile-based image into memory, storing the result in -the user supplied RGBA -.IR raster . -The raster is assumed to be an array of width times length 32-bit entries, -where width is the width of a tile (TIFFTAG_TILEWIDTH) and length is the -height of a tile (TIFFTAG_TILELENGTH). - -.PP -The -.IR x -and -.IR y -values are the offsets from the top left corner to the top left corner of the -tile to be read. They must be an exact multiple of the tile width and length. - -.PP -Note that the raster is assume to be organized such that the pixel at location -(\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP]; with the -raster origin in the -.I lower-left hand corner -of the tile. That is bottom to top organization. Edge tiles which partly fall -off the image will be filled out with appropriate zeroed areas. - -.PP -Raster pixels are 8-bit packed red, green, blue, alpha samples. The macros -.IR TIFFGetR , -.IR TIFFGetG , -.IR TIFFGetB , -and -.I TIFFGetA -should be used to access individual samples. Images without Associated Alpha -matting information have a constant Alpha of 1.0 (255). -.PP -See the -.IR TIFFRGBAImage (3TIFF) -page for more details on how various image types are converted to RGBA values. -.SH NOTES -Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel must -be either 1, 3, or 4 (i.e. -.I SamplesPerPixel -minus -.IR ExtraSamples ). -.PP -Palette image colormaps that appear to be incorrectly written as 8-bit values -are automatically scaled to 16-bits. -.PP -.I TIFFReadRGBATile -is just a wrapper around the more general -.IR TIFFRGBAImage (3TIFF) -facilities. It's main advantage over the similar -.IR TIFFReadRGBAImage() -function is that for large images a single buffer capable of holding the whole -image doesn't need to be allocated, only enough for one tile. The -.IR TIFFReadRGBAStrip() -function does a similar operation for stripped images. -.SH "RETURN VALUES" -1 is returned if the image was successfully read and converted. -Otherwise, 0 is returned if an error was encountered. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -.PP -.BR "Sorry, can not handle %d-bit pictures" . -The image had -.I BitsPerSample -other than 1, 2, 4, 8, or 16. -.PP -.BR "Sorry, can not handle %d-channel images" . -The image had -.I SamplesPerPixel -other than 1, 3, or 4. -.PP -\fBMissing needed "PhotometricInterpretation" tag\fP. -The image did not have a tag that describes how to display the data. -.PP -\fBNo "PhotometricInterpretation" tag, assuming RGB\fP. -The image was missing a tag that describes how to display it, but because it -has 3 or 4 samples/pixel, it is assumed to be -.SM RGB. -.PP -\fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP. -The image was missing a tag that describes how to display it, -but because it has 1 sample/pixel, it is assumed to be a grayscale -or bilevel image. -.PP -.BR "No space for photometric conversion table" . -There was insufficient memory for a table used to convert -image samples to 8-bit -.SM RGB. -.PP -\fBMissing required "Colormap" tag\fP. -A Palette image did not have a required -.I Colormap -tag. -.PP -.BR "No space for tile buffer" . -There was insufficient memory to allocate an i/o buffer. -.PP -.BR "No space for strip buffer" . -There was insufficient memory to allocate an i/o buffer. -.PP -.BR "Can not handle format" . -The image has a format (combination of -.IR BitsPerSample , -.IR SamplesPerPixel , -and -.IR PhotometricInterpretation ) -that -.I TIFFReadRGBAImage -can not handle. -.PP -.BR "No space for B&W mapping table" . -There was insufficient memory to allocate a table used to map -grayscale data to -.SM RGB. -.PP -.BR "No space for Palette mapping table" . -There was insufficient memory to allocate a table used to map data to 8-bit -.SM RGB. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFRGBAImage (3TIFF), -.BR TIFFReadRGBAImage (3TIFF), -.BR TIFFReadRGBAStrip (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFReadRawStrip.3tiff b/gtk+-mingw/share/man/man3/TIFFReadRawStrip.3tiff deleted file mode 100644 index 1f2d1d1..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadRawStrip.3tiff +++ /dev/null @@ -1,64 +0,0 @@ -.\" $Id: TIFFReadRawStrip.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadRawStrip 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFReadRawStrip \- return the undecoded contents of a strip of data from an -open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFReadRawStrip(TIFF *" tif ", tstrip_t " strip ", tdata_t " buf ", tsize_t " size ")" -.SH DESCRIPTION -Read the contents of the specified strip into the (user supplied) data buffer. -Note that the value of -.I strip -is a ``raw strip number.'' That is, the caller must take into account whether -or not the data is organized in separate planes (\c -.IR PlanarConfiguration =2). -To read a full strip of data the data buffer should typically be at least as -large as the number returned by -.IR TIFFStripSize . -.SH "RETURN VALUES" -The actual number of bytes of data that were placed in -.I buf -is returned; -.IR TIFFReadEncodedStrip -returns \-1 if an error was encountered. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFReadEncodedStrip (3TIFF), -.BR TIFFReadScanline (3TIFF), -.BR TIFFStripSize (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFReadRawTile.3tiff b/gtk+-mingw/share/man/man3/TIFFReadRawTile.3tiff deleted file mode 100644 index 3945dd9..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadRawTile.3tiff +++ /dev/null @@ -1,65 +0,0 @@ -.\" $Id: TIFFReadRawTile.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadRawTile 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFReadRawTile \- return an undecoded tile of data from an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFReadRawTile(TIFF *" tif ", ttile_t " tile ", tdata_t " buf ", tsize_t " size ")" -.SH DESCRIPTION -Read the contents of the specified tile into the (user supplied) data buffer. -Note that the value of -.I tile -is a ``raw tile number.'' That is, the caller must take into account whether -or not the data is organized in separate planes (\c -.IR PlanarConfiguration =2). -.I TIFFComputeTile -automatically does this when converting an (x,y,z,sample) coordinate quadruple -to a tile number. To read a full tile of data the data buffer should typically -be at least as large as the value returned by -.IR TIFFTileSize . -.SH "RETURN VALUES" -The actual number of bytes of data that were placed in -.I buf -is returned; -.IR TIFFReadEncodedTile -returns \-1 if an error was encountered. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFReadEncodedTile (3TIFF), -.BR TIFFReadTile (3TIFF), -.BR TIFFTileSize (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFReadScanline.3tiff b/gtk+-mingw/share/man/man3/TIFFReadScanline.3tiff deleted file mode 100644 index 7baf651..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadScanline.3tiff +++ /dev/null @@ -1,94 +0,0 @@ -.\" $Id: TIFFReadScanline.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadScanline 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFReadScanline \- read and decode a scanline of data from an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFReadScanline(TIFF *" tif ", tdata_t " buf ", uint32 " row ", tsample_t " sample ")" -.SH DESCRIPTION -Read the data for the specified row into the (user supplied) data buffer -.IR buf . -The data are returned decompressed and, in the native byte- and bit-ordering, -but are otherwise packed (see further below). The buffer must be large enough -to hold an entire scanline of data. Applications should call the routine -.IR TIFFScanlineSize -to find out the size (in bytes) of a scanline buffer. -The -.I row -parameter is always used by -.IR TIFFReadScanline ; -the -.I sample -parameter is used only if data are organized in separate planes (\c -.IR PlanarConfiguration =2). -.SH NOTES -The library attempts to hide bit- and byte-ordering differences between the -image and the native machine by converting data to the native machine order. -Bit reversal is done if the -.I FillOrder -tag is opposite to the native machine bit order. 16- and 32-bit samples are -automatically byte-swapped if the file was written with a byte order opposite -to the native machine byte order, -.PP -In C++ the -.I sample -parameter defaults to 0. -.SH "RETURN VALUES" -.IR TIFFReadScanline -returns \-1 if it detects an error; otherwise 1 is returned. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -.PP -.BR "Compression algorithm does not support random access" . -Data was requested in a non-sequential order from a file that uses a -compression algorithm and that has -.I RowsPerStrip -greater than one. -That is, data in the image is stored in a compressed form, and with multiple -rows packed into a strip. In this case, the library does not support random -access to the data. The data should either be accessed sequentially, or the -file should be converted so that each strip is made up of one row of data. -.SH BUGS -Reading subsampled YCbCR data does not work correctly because, for -.IR PlanarConfiguration =2 -the size of a scanline is not calculated on a per-sample basis, and for -.IR PlanarConfiguration =1 -the library does not unpack the block-interleaved samples; use the strip- and -tile-based interfaces to read these formats. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFReadEncodedStrip (3TIFF), -.BR TIFFReadRawStrip (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFReadTile.3tiff b/gtk+-mingw/share/man/man3/TIFFReadTile.3tiff deleted file mode 100644 index 4a9b20d..0000000 --- a/gtk+-mingw/share/man/man3/TIFFReadTile.3tiff +++ /dev/null @@ -1,84 +0,0 @@ -.\" $Id: TIFFReadTile.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFReadTile 3TIFF "December 16, 1991" "libtiff" -.SH NAME -TIFFReadTile \- read and decode a tile of data from an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFReadTile(TIFF *" tif ", tdata_t " buf ", uint32 " x ", uint32 " y ", uint32 " z ", tsample_t " sample ")" -.SH DESCRIPTION -Return the data for the tile -.I containing -the specified coordinates. The data placed in -.I buf -are returned decompressed and, typically, in the native byte- and -bit-ordering, but are otherwise packed (see further below). The buffer must be -large enough to hold an entire tile of data. Applications should call the -routine -.IR TIFFTileSize -to find out the size (in bytes) of a tile buffer. The -.I x -and -.I y -parameters are always used by -.IR TIFFReadTile . -The -.I z -parameter is used if the image is deeper than 1 slice (\c -.IR ImageDepth >1). -The -.I sample -parameter is used only if data are organized in separate planes (\c -.IR PlanarConfiguration =2). -.SH NOTES -The library attempts to hide bit- and byte-ordering differences between the -image and the native machine by converting data to the native machine order. -Bit reversal is done if the -.I FillOrder -tag is opposite to the native machine bit order. 16- and 32-bit samples are -automatically byte-swapped if the file was written with a byte order opposite -to the native machine byte order, -.SH "RETURN VALUES" -.IR TIFFReadTile -returns \-1 if it detects an error; otherwise the number of bytes in the -decoded tile is returned. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.SH "SEE ALSO" -.BR TIFFCheckTile (3TIFF), -.BR TIFFComputeTile (3TIFF), -.BR TIFFOpen (3TIFF), -.BR TIFFReadEncodedTile (3TIFF), -.BR TIFFReadRawTile (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFSetDirectory.3tiff b/gtk+-mingw/share/man/man3/TIFFSetDirectory.3tiff deleted file mode 100644 index 162d310..0000000 --- a/gtk+-mingw/share/man/man3/TIFFSetDirectory.3tiff +++ /dev/null @@ -1,79 +0,0 @@ -.\" $Id: TIFFSetDirectory.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFSetDirectory 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFSetDirectory, TIFFSetSubDirectory \- set the current directory for an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFSetDirectory(TIFF *" tif ", tdir_t " dirnum ")" -.br -.BI "int TIFFSetSubDirectory(TIFF *" tif ", uint32 " diroff ")" -.SH DESCRIPTION -.I TIFFSetDirectory -changes the current directory and reads its contents with -.IR TIFFReadDirectory . -The parameter -.I dirnum -specifies the subfile/directory as an integer number, with the first directory -numbered zero. -.PP -.I TIFFSetSubDirectory -acts like -.IR TIFFSetDirectory , -except the directory is specified as a file offset instead of an index; this -is required for accessing subdirectories linked through a -.I SubIFD -tag. -.SH "RETURN VALUES" -On successful return 1 is returned. Otherwise, 0 is returned if -.I dirnum -or -.I diroff -specifies a non-existent directory, or if an error was encountered while -reading the directory's contents. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -.PP -.BR "%s: Error fetching directory count" . -An error was encountered while reading the ``directory count'' field. -.PP -.BR "%s: Error fetching directory link" . -An error was encountered while reading the ``link value'' that points to the -next directory in a file. -.SH "SEE ALSO" -.IR TIFFCurrentDirectory (3TIFF), -.IR TIFFOpen (3TIFF), -.IR TIFFReadDirectory (3TIFF), -.IR TIFFWriteDirectory (3TIFF), -.IR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFSetField.3tiff b/gtk+-mingw/share/man/man3/TIFFSetField.3tiff deleted file mode 100644 index 33e9471..0000000 --- a/gtk+-mingw/share/man/man3/TIFFSetField.3tiff +++ /dev/null @@ -1,217 +0,0 @@ -.\" $Id: TIFFSetField.3tiff,v 1.5 2010-05-06 02:54:46 olivier Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFSetField 3TIFF "October 29, 2004" "libtiff" -.SH NAME -TIFFSetField, TIFFVSetField \- set the value(s) of a tag in a -.SM TIFF -file open for writing -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFSetField(TIFF *" tif ", ttag_t " tag ", " ... ")" -.sp -.B "#include <stdarg.h>" -.sp -.BI "int TIFFVSetField(TIFF *" tif ", ttag_t " tag ", va_list " ap ")" -.SH DESCRIPTION -.IR TIFFSetField -sets the value of a field -or pseudo-tag in the current directory associated with -the open -.SM TIFF -file -.IR tif . -(A -.I pseudo-tag -is a parameter that is used to control the operation of the -.SM TIFF -library but whose value is not read or written to the underlying file.) -To set the value of a field -the file must have been previously opened for writing with -.IR TIFFOpen (3TIFF); -pseudo-tags can be set whether the file was opened for reading -or writing. -The field is identified by -.IR tag , -one of the values defined in the include file -.B tiff.h -(see also the table below). -The actual value is specified using a variable argument list, -as prescribed by the -.IR stdarg (3) -interface (\c -or, on some machines, the -.IR varargs (3) -interface.) -.PP -.IR TIFFVSetField -is functionally equivalent to -.IR TIFFSetField -except that it takes a pointer to a variable -argument list. -.I TIFFVSetField -is useful for writing routines that are layered -on top of the functionality provided by -.IR TIFFSetField . -.PP -The tags understood by -.IR libtiff , -the number of parameter values, and the -expected types for the parameter values are shown below. -The data types are: -.I char* -is null-terminated string and corresponds to the -.SM ASCII -data type; -.I uint16 -is an unsigned 16-bit value; -.I uint32 -is an unsigned 32-bit value; -.I uint16* -is an array of unsigned 16-bit values. -.I void* -is an array of data values of unspecified type. - -Consult the -.SM TIFF -specification for information on the meaning of each tag. -.PP -.nf -.ta \w'TIFFTAG_CONSECUTIVEBADFAXLINES'u+2n +\w'Count'u+2n +\w'TIFFFaxFillFunc \(dg'u+2n -\fITag Name\fP \fICount\fP \fITypes\fP \fINotes\fP -.sp 5p -TIFFTAG_ARTIST 1 char* -TIFFTAG_BADFAXLINES 1 uint32 -TIFFTAG_BITSPERSAMPLE 1 uint16 \(dg -TIFFTAG_CLEANFAXDATA 1 uint16 -TIFFTAG_COLORMAP 3 uint16* 1<<BitsPerSample arrays -TIFFTAG_COMPRESSION 1 uint16 \(dg -TIFFTAG_CONSECUTIVEBADFAXLINES 1 uint32 -TIFFTAG_COPYRIGHT 1 char* -TIFFTAG_DATETIME 1 char* -TIFFTAG_DOCUMENTNAME 1 char* -TIFFTAG_DOTRANGE 2 uint16 -TIFFTAG_EXTRASAMPLES 2 uint16,uint16* \(dg count & types array -TIFFTAG_FAXFILLFUNC 1 TIFFFaxFillFunc G3/G4 compression pseudo-tag -TIFFTAG_FAXMODE 1 int \(dg G3/G4 compression pseudo-tag -TIFFTAG_FILLORDER 1 uint16 \(dg -TIFFTAG_GROUP3OPTIONS 1 uint32 \(dg -TIFFTAG_GROUP4OPTIONS 1 uint32 \(dg -TIFFTAG_HALFTONEHINTS 2 uint16 -TIFFTAG_HOSTCOMPUTER 1 char* -TIFFTAG_ICCPROFILE 2 uint32,void* count, profile data -TIFFTAG_IMAGEDEPTH 1 uint32 \(dg -TIFFTAG_IMAGEDESCRIPTION 1 char* -TIFFTAG_IMAGELENGTH 1 uint32 -TIFFTAG_IMAGEWIDTH 1 uint32 \(dg -TIFFTAG_INKNAMES 2 uint16, char* -TIFFTAG_INKSET 1 uint16 \(dg -TIFFTAG_JPEGCOLORMODE 1 int \(dg JPEG pseudo-tag -TIFFTAG_JPEGQUALITY 1 int JPEG pseudo-tag -TIFFTAG_JPEGTABLES 2 uint32*,void* \(dg count & tables -TIFFTAG_JPEGTABLESMODE 1 int \(dg JPEG pseudo-tag -TIFFTAG_MAKE 1 char* -TIFFTAG_MATTEING 1 uint16 \(dg -TIFFTAG_MAXSAMPLEVALUE 1 uint16 -TIFFTAG_MINSAMPLEVALUE 1 uint16 -TIFFTAG_MODEL 1 char* -TIFFTAG_ORIENTATION 1 uint16 -TIFFTAG_PAGENAME 1 char* -TIFFTAG_PAGENUMBER 2 uint16 -TIFFTAG_PHOTOMETRIC 1 uint16 -TIFFTAG_PHOTOSHOP ? uint32,void* count, data -TIFFTAG_PLANARCONFIG 1 uint16 \(dg -TIFFTAG_PREDICTOR 1 uint16 \(dg -TIFFTAG_PRIMARYCHROMATICITIES 1 float* 6-entry array -TIFFTAG_REFERENCEBLACKWHITE 1 float* \(dg 6-entry array -TIFFTAG_RESOLUTIONUNIT 1 uint16 -TIFFTAG_RICHTIFFIPTC 2 uint32,void* count, data -TIFFTAG_ROWSPERSTRIP 1 uint32 \(dg must be > 0 -TIFFTAG_SAMPLEFORMAT 1 uint16 \(dg -TIFFTAG_SAMPLESPERPIXEL 1 uint16 \(dg value must be <= 4 -TIFFTAG_SMAXSAMPLEVALUE 1 double -TIFFTAG_SMINSAMPLEVALUE 1 double -TIFFTAG_SOFTWARE 1 char* -TIFFTAG_STONITS 1 double \(dg -TIFFTAG_SUBFILETYPE 1 uint32 -TIFFTAG_SUBIFD 2 uint16,uint32* count & offsets array -TIFFTAG_TARGETPRINTER 1 char* -TIFFTAG_THRESHHOLDING 1 uint16 -TIFFTAG_TILEDEPTH 1 uint32 \(dg -TIFFTAG_TILELENGTH 1 uint32 \(dg must be a multiple of 8 -TIFFTAG_TILEWIDTH 1 uint32 \(dg must be a multiple of 8 -TIFFTAG_TRANSFERFUNCTION 1 or 3\(dd uint16* 1<<BitsPerSample entry arrays -TIFFTAG_WHITEPOINT 1 float* 2-entry array -TIFFTAG_XMLPACKET 2 uint32,void* count, data -TIFFTAG_XPOSITION 1 float -TIFFTAG_XRESOLUTION 1 float -TIFFTAG_YCBCRCOEFFICIENTS 1 float* \(dg 3-entry array -TIFFTAG_YCBCRPOSITIONING 1 uint16 \(dg -TIFFTAG_YCBCRSAMPLING 2 uint16 \(dg -TIFFTAG_YPOSITION 1 float -TIFFTAG_YRESOLUTION 1 float -.fi -.sp 5p -\(dg Tag may not have its values changed once data is written. -.br -.fi -\(dd -If -.I SamplesPerPixel -is one, then a single array is passed; otherwise three arrays should be -passed. -.fi -* The contents of this field are quite complex. See -.BR "The ICC Profile Format Specification" , -Annex B.3 "Embedding ICC Profiles in TIFF Files" -(available at http://www.color.org) for an explanation. -.br -.SH "RETURN VALUES" -1 is returned if the operation was successful. -Otherwise, 0 is returned if an error was detected. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.PP -\fB%s: Cannot modify tag "%s" while writing\fP. -Data has already been written to the file, so the -specified tag's value can not be changed. -This restriction is applied to all tags that affect -the format of written data. -.PP -\fB%d: Bad value for "%s"\fP. -An invalid value was supplied for the named tag. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFGetField (3TIFF), -.BR TIFFSetDirectory (3TIFF), -.BR TIFFWriteDirectory (3TIFF), -.BR TIFFReadDirectory (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFWarning.3tiff b/gtk+-mingw/share/man/man3/TIFFWarning.3tiff deleted file mode 100644 index 32339aa..0000000 --- a/gtk+-mingw/share/man/man3/TIFFWarning.3tiff +++ /dev/null @@ -1,70 +0,0 @@ -.\" $Id: TIFFWarning.3tiff,v 1.3 2012-06-01 22:02:44 fwarmerdam Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFWarning 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFWarning, TIFFSetWarningHandler \- library warning interface -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "void TIFFWarning(const char *" module ", const char *" fmt ", " ... ")" -.sp -.B "#include <stdarg.h>" -.sp -.BI "typedef void (*TIFFWarningHandler)(const char *" module ", const char *" fmt ", va_list " ap ");" -.sp -.BI "TIFFWarningHandler TIFFSetWarningHandler(TIFFWarningHandler " handler ");" -.SH DESCRIPTION -.I TIFFWarning -invokes the library-wide warning handler function to (normally) write a -warning message to the -.BR stderr . -The -.I fmt -parameter is a -.IR printf (3S) -format string, and any number arguments can be supplied. The -.I module -parameter is interpreted as a string that, if non-zero, should be printed -before the message; it typically is used to identify the software module in -which a warning is detected. -.PP -Applications that desire to capture control in the event of a warning should -use -.IR TIFFSetWarningHandler -to override the default warning handler. -A -.SM NULL -(0) warning handler function may be installed to suppress error messages. -.SH "RETURN VALUES" -.IR TIFFSetWarningHandler -returns a reference to the previous error handling function. -.SH "SEE ALSO" -.BR TIFFError (3TIFF), -.BR libtiff (3TIFF), -.BR printf (3) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFWriteDirectory.3tiff b/gtk+-mingw/share/man/man3/TIFFWriteDirectory.3tiff deleted file mode 100644 index b8de6bf..0000000 --- a/gtk+-mingw/share/man/man3/TIFFWriteDirectory.3tiff +++ /dev/null @@ -1,138 +0,0 @@ -.\" $Id: TIFFWriteDirectory.3tiff,v 1.3 2010-12-12 01:45:35 faxguy Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFWriteDirectory 3TIFF "September 26, 2001" "libtiff" -.SH NAME -TIFFWriteDirectory, TIFFRewriteDirectory, TIFFCheckpointDirectory \- write the -current directory in an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFWriteDirectory(TIFF *" tif ")" -.br -.BI "int TIFFRewriteDirectory(TIFF *" tif ")" -.br -.BI "int TIFFCheckpointDirectory(TIFF *" tif ")" -.SH DESCRIPTION -.IR TIFFWriteDirectory -will write the contents of the current directory to the file and setup to -create a new subfile in the same file. Applications only need to call -.IR TIFFWriteDirectory -when writing multiple subfiles to a single -.SM TIFF -file. -.IR TIFFWriteDirectory -is automatically called by -.IR TIFFClose -and -.IR TIFFFlush -to write a modified directory if the file is open for writing. -.PP -The -.IR TIFFRewriteDirectory -function operates similarly to -.IR TIFFWriteDirectory, -but can be called with directories previously read or written that already -have an established location in the file. It will rewrite the directory, -but instead of place it at it's old location (as -.IR TIFFWriteDirectory -would) it will place them at the end of the file, correcting the pointer from -the preceding directory or file header to point to it's new location. This -is particularly important in cases where the size of the directory and -pointed to data has grown, so it won't fit in the space available at the -old location. -.PP -The -.IR TIFFCheckpointDirectory -writes the current state of the tiff directory into the file to make what -is currently in the file readable. Unlike -.IR TIFFWriteDirectory, -.IR TIFFCheckpointDirectory -does not free up the directory data structures in memory, so they can be -updated (as strips/tiles are written) and written again. Reading such -a partial file you will at worst get a tiff read error for the first -strip/tile encountered that is incomplete, but you will at least get -all the valid data in the file before that. When the file is complete, -just use -.IR TIFFWriteDirectory -as usual to finish it off cleanly. -.SH "RETURN VALUES" -1 is returned when the contents are successfully written to the file. -Otherwise, 0 is returned if an error was encountered when writing -the directory contents. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -.PP -.BR "Error post-encoding before directory write" . -Before writing the contents of the current directory, any pending data are -flushed. This message indicates that an error occurred while doing this. -.PP -.BR "Error flushing data before directory write" . -Before writing the contents of the current directory, any pending data are -flushed. This message indicates that an error occurred while doing this. -.PP -.BR "Cannot write directory, out of space" . -There was not enough space to allocate a temporary area for the directory that -was to be written. -.PP -.BR "Error writing directory count" . -A write error occurred when writing the count of fields in the directory. -.PP -.BR "Error writing directory contents" . -A write error occurred when writing the directory fields. -.PP -.BR "Error writing directory link" . -A write error occurred when writing the link to the next directory. -.PP -\fBError writing data for field "%s"\fP. -A write error occurred when writing indirect data for the specified field. -.PP -.BR "Error writing TIFF header" . -A write error occurred when re-writing header at the front of the file. -.PP -.BR "Error fetching directory count" . -A read error occurred when fetching the directory count field for -a previous directory. -This can occur when setting up a link to the directory that is being -written. -.PP -.BR "Error fetching directory link" . -A read error occurred when fetching the directory link field for -a previous directory. -This can occur when setting up a link to the directory that is being -written. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFError (3TIFF), -.BR TIFFReadDirectory (3TIFF), -.BR TIFFSetDirectory (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFWriteEncodedStrip.3tiff b/gtk+-mingw/share/man/man3/TIFFWriteEncodedStrip.3tiff deleted file mode 100644 index 4130634..0000000 --- a/gtk+-mingw/share/man/man3/TIFFWriteEncodedStrip.3tiff +++ /dev/null @@ -1,102 +0,0 @@ -.\" $Id: TIFFWriteEncodedStrip.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFWriteEncodedStrip 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFWritedEncodedStrip \- compress and write a strip of data to an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFWriteEncodedStrip(TIFF *" tif ", tstrip_t " strip ", tdata_t " buf ", tsize_t " size ")" -.SH DESCRIPTION -Compress -.I size -bytes of raw data from -.I buf -and write the result to the specified strip; replacing any previously written -data. Note that the value of -.I strip -is a ``raw strip number.'' That is, the caller must take into account whether -or not the data are organized in separate planes (\c -.IR PlanarConfiguration =2). -.SH NOTES -The library writes encoded data using the native machine byte order. Correctly -implemented -.SM TIFF -readers are expected to do any necessary byte-swapping to correctly process -image data with BitsPerSample greater than 8. -.PP -The strip number must be valid according to the current settings of the -.I ImageLength -and -.I RowsPerStrip -tags. -An image may be dynamically grown by increasing the value of -.I ImageLength -prior to each call to -.IR TIFFWriteEncodedStrip . -.SH "RETURN VALUES" -\-1 is returned if an error was encountered. Otherwise, the value of -.IR size -is returned. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -.PP -\fB%s: File not open for writing\fP. The file was opened for reading, not -writing. -.PP -\fBCan not write scanlines to a tiled image\fP. The image is assumed to be -organized in tiles because the -.I TileWidth -and -.I TileLength -tags have been set with -.IR TIFFSetField (3TIFF). -.PP -\fB%s: Must set "ImageWidth" before writing data\fP. -The image's width has not be set before the first write. See -.IR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fB%s: Must set "PlanarConfiguration" before writing data\fP. -The organization of data has not be defined before the first write. See -.IR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fB%s: No space for strip arrays"\fP. -There was not enough space for the arrays that hold strip offsets and byte -counts. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFWriteScanline (3TIFF), -.BR TIFFWriteRawStrip (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFWriteEncodedTile.3tiff b/gtk+-mingw/share/man/man3/TIFFWriteEncodedTile.3tiff deleted file mode 100644 index 4bb471f..0000000 --- a/gtk+-mingw/share/man/man3/TIFFWriteEncodedTile.3tiff +++ /dev/null @@ -1,96 +0,0 @@ -.\" $Id: TIFFWriteEncodedTile.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFWriteEncodedTile 3TIFF "December 16, 1991" "libtiff" -.SH NAME -TIFFWritedEncodedTile \- compress and write a tile of data to an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFWriteEncodedTile(TIFF *" tif ", ttile_t " tile ", tdata_t " buf ", tsize_t " size ")" -.SH DESCRIPTION -Compress -.I size -bytes of raw data from -.I buf -and -.B append -the result to the end of the specified tile. Note that the value of -.I tile -is a ``raw tile number.'' That is, the caller must take into account whether -or not the data are organized in separate places (\c -.IR PlanarConfiguration =2). -.IR TIFFComputeTile -automatically does this when converting an (x,y,z,sample) coordinate quadruple -to a tile number. -.SH NOTES -The library writes encoded data using the native machine byte order. Correctly -implemented -.SM TIFF -readers are expected to do any necessary byte-swapping to correctly process -image data with BitsPerSample greater than 8. -.SH "RETURN VALUES" -\-1 is returned if an error was encountered. Otherwise, the value of -.IR size -is returned. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.PP -\fB%s: File not open for writing\fP. -The file was opened for reading, not writing. -.PP -\fBCan not write tiles to a stripped image\fP. -The image is assumed to be organized in strips because neither of the -.I TileWidth -or -.I TileLength -tags have been set with -.BR TIFFSetField (3TIFF). -.PP -\fB%s: Must set "ImageWidth" before writing data\fP. The image's width has not -be set before the first write. See -.BR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fB%s: Must set "PlanarConfiguration" before writing data\fP. The organization -of data has not be defined before the first write. See -.BR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fB%s: No space for tile arrays"\fP. -There was not enough space for the arrays that hold tile offsets and byte -counts. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFWriteTile (3TIFF), -.BR TIFFWriteRawTile (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFWriteRawStrip.3tiff b/gtk+-mingw/share/man/man3/TIFFWriteRawStrip.3tiff deleted file mode 100644 index 0fed3aa..0000000 --- a/gtk+-mingw/share/man/man3/TIFFWriteRawStrip.3tiff +++ /dev/null @@ -1,96 +0,0 @@ -.\" $Id: TIFFWriteRawStrip.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFWriteRawstrip 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFWriteRawStrip \- write a strip of raw data to an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFWriteRawStrip(TIFF *" tif ", tstrip_t " strip ", tdata_t " buf ", tsize_t " size ")" -.SH DESCRIPTION -Append -.I size -bytes of raw data to the specified strip. -.SH NOTES -The strip number must be valid according to the current settings of the -.I ImageLength -and -.I RowsPerStrip -tags. -An image may be dynamically grown by increasing the value of -.I ImageLength -prior to each call to -.IR TIFFWriteRawStrip . -.SH "RETURN VALUES" -\-1 is returned if an error occurred. -Otherwise, the value of -.IR size -is returned. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.PP -\fB%s: File not open for writing\fP. -The file was opened for reading, not writing. -.PP -\fBCan not write scanlines to a tiled image\fP. The image is assumed to be -organized in tiles because the -.I TileWidth -and -.I TileLength -tags have been set with -.BR TIFFSetField (3TIFF). -.PP -\fB%s: Must set "ImageWidth" before writing data\fP. -The image's width has not be set before the first write. -See -.BR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fB%s: Must set "PlanarConfiguration" before writing data\fP. -The organization of data has not be defined before the first write. -See -.BR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fB%s: No space for strip arrays"\fP. -There was not enough space for the arrays that hold strip -offsets and byte counts. -.PP -\fB%s: Strip %d out of range, max %d\fP. -The specified strip is not a valid strip according to the -currently specified image dimensions. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFWriteEncodedStrip (3TIFF), -.BR TIFFWriteScanline (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFWriteRawTile.3tiff b/gtk+-mingw/share/man/man3/TIFFWriteRawTile.3tiff deleted file mode 100644 index d422e58..0000000 --- a/gtk+-mingw/share/man/man3/TIFFWriteRawTile.3tiff +++ /dev/null @@ -1,84 +0,0 @@ -.\" $Id: TIFFWriteRawTile.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFWriteRawtile 3TIFF "December 16, 1991" "libtiff" -.SH NAME -TIFFWriteRawTile \- write a tile of raw data to an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFWriteRawTile(TIFF *" tif ", ttile_t " tile ", tdata_t " buf ", tsize_t " size ")" -.SH DESCRIPTION -Append -.I size -bytes of raw data to the specified tile. -.SH "RETURN VALUES" -\-1 is returned if an error occurred. Otherwise, the value of -.IR size -is returned. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.PP -\fB%s: File not open for writing\fP. -The file was opened for reading, not writing. -.PP -\fBCan not write tiles to a stripped image\fP. -The image is assumed to be organized in strips because neither of the -.I TileWidth -or -.I TileLength -tags have been set with -.BR TIFFSetField (3TIFF). -.PP -\fB%s: Must set "ImageWidth" before writing data\fP. -The image's width has not be set before the first write. -See -.BR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fB%s: Must set "PlanarConfiguration" before writing data\fP. The organization -of data has not be defined before the first write. See -.BR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fB%s: No space for tile arrays"\fP. -There was not enough space for the arrays that hold tile offsets and byte -counts. -.PP -\fB%s: Specified tile %d out of range, max %d\fP. -The specified tile is not valid according to the currently specified image -dimensions. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFWriteEncodedTile (3TIFF), -.BR TIFFWriteScanline (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFWriteScanline.3tiff b/gtk+-mingw/share/man/man3/TIFFWriteScanline.3tiff deleted file mode 100644 index 0dd35f5..0000000 --- a/gtk+-mingw/share/man/man3/TIFFWriteScanline.3tiff +++ /dev/null @@ -1,154 +0,0 @@ -.\" $Id: TIFFWriteScanline.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFWriteScanline 3TIFF "December 16, 1991" "libtiff" -.SH NAME -TIFFWriteScanline \- write a scanline to an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFWriteScanline(TIFF *" tif ", tdata_t " buf ", uint32 " row ", tsample_t " sample ")" -.SH DESCRIPTION -Write data to a file at the specified row. The -.I sample -parameter is used only if data are organized in separate planes (\c -.IR PlanarConfiguration =2). -The data are assumed to be uncompressed and in the native bit- and byte-order -of the host machine. The data written to the file is compressed according to -the compression scheme of the current -.SM TIFF -directory (see further below). If the current scanline is past the end of the -current subfile, the -.I ImageLength -field is automatically increased to include the scanline (except -for -.IR PlanarConfiguration =2, -where the -.I ImageLength -cannot be changed once the first data are written). If the -.I ImageLength -is increased, the -.I StripOffsets -and -.I StripByteCounts -fields are similarly enlarged to reflect data written past the previous end of -image. -.SH NOTES -The library writes encoded data using the native machine byte order. Correctly -implemented -.SM TIFF -readers are expected to do any necessary byte-swapping to correctly process -image data with BitsPerSample greater than 8. The library attempts to hide -bit-ordering differences between the image and the native machine by -converting data from the native machine order. -.PP -In C++ the -.I sample -parameter defaults to 0. -.PP -Once data are written to a file for the current directory, the values of -certain tags may not be altered; see -.IR TIFFSetField (3TIFF) -for more information. -.PP -It is not possible to write scanlines to a file that uses a tiled -organization. The routine -.IR TIFFIsTiled -can be used to determine if the file is organized as tiles or strips. -.SH "RETURN VALUES" -.IR TIFFWriteScanline -returns \-1 if it immediately detects an error and 1 for a successful write. -.SH DIAGNOSTICS -All error messages are directed to the -.IR TIFFError (3TIFF) -routine. -.PP -.BR "%s: File not open for writing . -The file was opened for reading, not writing. -.PP -.BR "Can not write scanlines to a tiled image" . -An attempt was made to write a scanline to a tiled image. The image is assumed -to be organized in tiles because the -.I TileWidth -and -.I TileLength -tags have been set with -.IR TIFFSetField (3TIFF). -.PP -.BR "Compression algorithm does not support random access" . -Data was written in a non-sequential order to a file that uses a compression -algorithm and that has -.I RowsPerStrip -greater than one. That is, data in the image is to be stored in a compressed -form, and with multiple rows packed into a strip. In this case, the library -does not support random access to the data. The data should either be written -as entire strips, sequentially by rows, or the value of -.I RowsPerStrip -should be set to one. -.PP -\fB%s: Must set "ImageWidth" before writing data\fP. -The image's width has not be set before the first write. -See -.BR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fB%s: Must set "PlanarConfiguration" before writing data\fP. -The organization of data has not be defined before the first write. -See -.BR TIFFSetField (3TIFF) -for information on how to do this. -.PP -\fBCan not change "ImageLength" when using separate planes\fP. Separate image -planes are being used (\c -.IR PlanarConfiguration =2), -but the number of rows has not been specified before the first write. The -library supports the dynamic growth of an image only when data are organized -in a contiguous manner (\c -.IR PlanarConfiguration =1). -.PP -.BR "%d: Sample out of range, max %d" . -The -.I sample -parameter was greater than the value of the SamplesPerPixel tag. -.PP -.BR "%s: No space for strip arrays . -There was not enough space for the arrays that hold strip offsets and byte -counts. -.SH BUGS -Writing subsampled YCbCR data does not work correctly because, for -.IR PlanarConfiguration =2 -the size of a scanline is not calculated on a per-sample basis, and for -.IR PlanarConfiguration =1 -the library does not pack the block-interleaved samples. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFWriteEncodedStrip (3TIFF), -.BR TIFFWriteRawStrip (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFWriteTile.3tiff b/gtk+-mingw/share/man/man3/TIFFWriteTile.3tiff deleted file mode 100644 index 08250f7..0000000 --- a/gtk+-mingw/share/man/man3/TIFFWriteTile.3tiff +++ /dev/null @@ -1,77 +0,0 @@ -.\" $Id: TIFFWriteTile.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFWriteTile 3TIFF "November 29, 1999" "libtiff" -.SH NAME -TIFFWriteTile \- encode and write a tile of data to an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFWriteTile(TIFF *" tif ", tdata_t " buf ", uint32 " x ", uint32 " y ", uint32 " z ", tsample_t " sample ")" -.SH DESCRIPTION -Write the data for the tile -.I containing -the specified coordinates. The data in -.I buf -are is (potentially) compressed, and written to the indicated file, normally -being appended to the end of the file. The buffer must be contain an entire -tile of data. Applications should call the routine -.IR TIFFTileSize -to find out the size (in bytes) of a tile buffer. The -.I x -and -.I y -parameters are always used by -.IR TIFFWriteTile . -The -.I z -parameter is used if the image is deeper than 1 slice (\c -.IR ImageDepth >1). -The -.I sample -parameter is used only if data are organized in separate planes (\c -.IR PlanarConfiguration =2). -.SH "RETURN VALUES" -.IR TIFFWriteTile -returns \-1 if it detects an error; otherwise the number of bytes in the tile -is returned. -.SH DIAGNOSTICS -All error messages are directed to the -.BR TIFFError (3TIFF) -routine. -.SH "SEE ALSO" -.BR TIFFCheckTile (3TIFF), -.BR TIFFComputeTile (3TIFF), -.BR TIFFOpen (3TIFF), -.BR TIFFReadTile (3TIFF), -.BR TIFFWriteScanline (3TIFF), -.BR TIFFWriteEncodedTile (3TIFF), -.BR TIFFWriteRawTile (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFbuffer.3tiff b/gtk+-mingw/share/man/man3/TIFFbuffer.3tiff deleted file mode 100644 index a4446cd..0000000 --- a/gtk+-mingw/share/man/man3/TIFFbuffer.3tiff +++ /dev/null @@ -1,77 +0,0 @@ -.\" $Id: TIFFbuffer.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1995 Sam Leffler -.\" Copyright (c) 1995 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFBUFFER 3TIFF "November 1, 2005" "libtiff" -.SH NAME -TIFFReadBufferSetup, TIFFWriteBufferSetup \- I/O buffering control routines -.SH SYNOPSIS -.nf -.B "#include <tiffio.h>" -.sp -.BI "int TIFFReadBufferSetup(TIFF *" tif ", tdata_t " buffer ", tsize_t " size ");" -.BI "int TIFFWriteBufferSetup(TIFF *" tif ", tdata_t " buffer ", tsize_t " size ");" -.fi -.SH DESCRIPTION -The following routines are provided for client-control of the I/O buffers used -by the library. Applications need never use these routines; they are provided -only for ``intelligent clients'' that wish to optimize memory usage and/or -eliminate potential copy operations that can occur when working with images -that have data stored without compression. -.PP -.I TIFFReadBufferSetup -sets up the data buffer used to read raw (encoded) data from a file. If the -specified pointer is -.SM NULL -(zero), then a buffer of the appropriate size is allocated. Otherwise the -caller must guarantee that the buffer is large enough to hold any individual -strip of raw data. -.I TIFFReadBufferSetup -returns a non-zero value if the setup was successful and zero otherwise. -.PP -.I TIFFWriteBufferSetup -sets up the data buffer used to write raw (encoded) data to a file. If the -specified -.I size -is \-1 then the buffer size is selected to hold a complete tile or strip, or -at least 8 kilobytes, whichever is greater. If the specified -.I buffer -is -.SM NULL -(zero), then a buffer of the appropriate size is dynamically allocated. -.I TIFFWriteBufferSetup -returns a non-zero value if the setup was successful and zero otherwise. -.SH DIAGNOSTICS -.BR "%s: No space for data buffer at scanline %ld" . -.I TIFFReadBufferSetup -was unable to dynamically allocate space for a data buffer. -.PP -.BR "%s: No space for output buffer" . -.I TIFFWriteBufferSetup -was unable to dynamically allocate space for a data buffer. -.SH "SEE ALSO" -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFcodec.3tiff b/gtk+-mingw/share/man/man3/TIFFcodec.3tiff deleted file mode 100644 index 78a0f02..0000000 --- a/gtk+-mingw/share/man/man3/TIFFcodec.3tiff +++ /dev/null @@ -1,82 +0,0 @@ -.\" $Id: TIFFcodec.3tiff,v 1.3 2011-08-02 14:09:43 bfriesen Exp $ -.\" -.\" Copyright (c) 1995 Sam Leffler -.\" Copyright (c) 1995 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH CODEC 3TIFF "October 29, 2004" "libtiff" -.SH NAME -TIFFFindCODEC, TIFFRegisterCODEC, TIFFUnRegisterCODEC, TIFFIsCODECConfigured -\- codec-related utility routines -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "const TIFFCodec* TIFFFindCODEC(uint16 " scheme ");" -.br -.BI "TIFFCodec* TIFFRegisterCODEC(uint16 " scheme ", const char *" method ", TIFFInitMethod " init ");" -.br -.BI "void TIFFUnRegisterCODEC(TIFFCodec *" codec ");" -.br -.BI "int TIFFIsCODECConfigured(uint16 " scheme ");" -.SH DESCRIPTION -.I libtiff -supports a variety of compression schemes implemented by software -.IR codecs . -Each codec adheres to a modular interface that provides for -the decoding and encoding of image data; as well as some other -methods for initialization, setup, cleanup, and the control -of default strip and tile sizes. -Codecs are identified by the associated value of the -.SM TIFF -.I Compression -tag; e.g. 5 for -.SM LZW -compression. -.PP -The -.I TIFFRegisterCODEC -routine can be used to -augment or override the set of codecs available to an application. -If the specified -.I scheme -already has a registered codec then it is -.I overridden -and any images with data encoded with this -compression scheme will be decoded using the supplied codec. -.PP -.I TIFFIsCODECConfigured -returns 1 if the codec is configured and working. Otherwise 0 will be returned. -.SH DIAGNOSTICS -.BR "No space to register compression scheme %s" . -.I TIFFRegisterCODEC -was unable to allocate memory for the data structures needed -to register a codec. -.PP -.BR "Cannot remove compression scheme %s; not registered" . -.I TIFFUnRegisterCODEC -did not locate the specified codec in the table of registered -compression schemes. -.SH "SEE ALSO" -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFcolor.3tiff b/gtk+-mingw/share/man/man3/TIFFcolor.3tiff deleted file mode 100644 index e5d2727..0000000 --- a/gtk+-mingw/share/man/man3/TIFFcolor.3tiff +++ /dev/null @@ -1,268 +0,0 @@ -.\" $Id: TIFFcolor.3tiff,v 1.4 2009-11-30 12:22:26 fwarmerdam Exp $ -.\" -.\" Copyright (c) 2003, Andrey Kiselev <dron@ak4719.spb.edu> -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH COLOR 3TIFF "December 21, 2003" "libtiff" -.SH NAME -TIFFYCbCrToRGBInit, TIFFYCbCrtoRGB, TIFFCIELabToRGBInit, TIFFCIELabToXYZ, -TIFFXYZToRGB \- color conversion routines. -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "int TIFFYCbCrToRGBInit(TIFFYCbCrToRGB *" ycbcr ", float *" luma ", float *"refBlackWhite" );" -.br -.BI "void TIFFYCbCrtoRGB(TIFFYCbCrToRGB *" ycbcr ", uint32 " Y ", int32 " Cb ", int32 " Cr ", uint32 *" R ", uint32 *" G ", uint32 *" B " );" -.sp -.BI "int TIFFCIELabToRGBInit(TIFFCIELabToRGB *" cielab ", const TIFFDisplay *" display ", float *" refWhite ");" -.br -.BI "void TIFFCIELabToXYZ(TIFFCIELabToRGB *" cielab ", uint32 " L ", int32 " a ", int32 " b ", float *" X ", float *" Y ", float *" Z ");" -.br -.BI "void TIFFXYZToRGB(TIFFCIELabToRGB *" cielab ", float " X ", float " Y ", float " Z" , uint32 *" R ", uint32 *" G ", uint32 *" B ");" -.SH DESCRIPTION -TIFF supports several color spaces for images stored in that format. There is -usually a problem of application to handle the data properly and convert -between different colorspaces for displaying and printing purposes. To -simplify this task libtiff implements several color conversion routines -itself. In particular, these routines used in -.B TIFFRGBAImage(3TIFF) -interface. -.PP -.B TIFFYCbCrToRGBInit() -used to initialize -.I YCbCr -to -.I RGB -conversion state. Allocating and freeing of the -.I ycbcr -structure belongs to programmer. -.I TIFFYCbCrToRGB -defined in -.B tiffio.h -as -.PP -.RS -.nf -typedef struct { /* YCbCr->RGB support */ - TIFFRGBValue* clamptab; /* range clamping table */ - int* Cr_r_tab; - int* Cb_b_tab; - int32* Cr_g_tab; - int32* Cb_g_tab; - int32* Y_tab; -} TIFFYCbCrToRGB; -.fi -.RE -.PP -.I luma -is a float array of three values representing proportions of the red, green -and blue in luminance, Y (see section 21 of the TIFF 6.0 specification, where -the YCbCr images discussed). -.I TIFFTAG_YCBCRCOEFFICIENTS -holds that values in TIFF file. -.I refBlackWhite -is a float array of 6 values which specifies a pair of headroom and footroom -image data values (codes) for each image component (see section 20 of the -TIFF 6.0 specification where the colorinmetry fields discussed). -.I TIFFTAG_REFERENCEBLACKWHITE -is responsible for storing these values in TIFF file. Following code snippet -should helps to understand the the technique: -.PP -.RS -.nf -float *luma, *refBlackWhite; -uint16 hs, vs; - -/* Initialize structures */ -ycbcr = (TIFFYCbCrToRGB*) - _TIFFmalloc(TIFFroundup(sizeof(TIFFYCbCrToRGB), sizeof(long)) - + 4*256*sizeof(TIFFRGBValue) - + 2*256*sizeof(int) - + 3*256*sizeof(int32)); -if (ycbcr == NULL) { - TIFFError("YCbCr->RGB", - "No space for YCbCr->RGB conversion state"); - exit(0); -} - -TIFFGetFieldDefaulted(tif, TIFFTAG_YCBCRCOEFFICIENTS, &luma); -TIFFGetFieldDefaulted(tif, TIFFTAG_REFERENCEBLACKWHITE, &refBlackWhite); -if (TIFFYCbCrToRGBInit(ycbcr, luma, refBlackWhite) < 0) - exit(0); - -/* Start conversion */ -uint32 r, g, b; -uint32 Y; -int32 Cb, Cr; - -for each pixel in image - TIFFYCbCrtoRGB(img->ycbcr, Y, Cb, Cr, &r, &g, &b); - -/* Free state structure */ -_TIFFfree(ycbcr); -.fi -.RE -.PP - -.PP -.B TIFFCIELabToRGBInit() -initializes the -.I CIE L*a*b* 1976 -to -.I RGB -conversion state. -.B TIFFCIELabToRGB -defined as -.PP -.RS -.nf -#define CIELABTORGB_TABLE_RANGE 1500 - -typedef struct { /* CIE Lab 1976->RGB support */ - int range; /* Size of conversion table */ - float rstep, gstep, bstep; - float X0, Y0, Z0; /* Reference white point */ - TIFFDisplay display; - float Yr2r[CIELABTORGB_TABLE_RANGE + 1]; /* Conversion of Yr to r */ - float Yg2g[CIELABTORGB_TABLE_RANGE + 1]; /* Conversion of Yg to g */ - float Yb2b[CIELABTORGB_TABLE_RANGE + 1]; /* Conversion of Yb to b */ -} TIFFCIELabToRGB; -.fi -.RE -.PP -.I display -is a display device description, declared as -.PP -.RS -.nf -typedef struct { - float d_mat[3][3]; /* XYZ -> luminance matrix */ - float d_YCR; /* Light o/p for reference white */ - float d_YCG; - float d_YCB; - uint32 d_Vrwr; /* Pixel values for ref. white */ - uint32 d_Vrwg; - uint32 d_Vrwb; - float d_Y0R; /* Residual light for black pixel */ - float d_Y0G; - float d_Y0B; - float d_gammaR; /* Gamma values for the three guns */ - float d_gammaG; - float d_gammaB; -} TIFFDisplay; -.fi -.RE -.PP -For example, the one can use sRGB device, which has the following parameters: -.PP -.RS -.nf -TIFFDisplay display_sRGB = { - { /* XYZ -> luminance matrix */ - { 3.2410F, -1.5374F, -0.4986F }, - { -0.9692F, 1.8760F, 0.0416F }, - { 0.0556F, -0.2040F, 1.0570F } - }, - 100.0F, 100.0F, 100.0F, /* Light o/p for reference white */ - 255, 255, 255, /* Pixel values for ref. white */ - 1.0F, 1.0F, 1.0F, /* Residual light o/p for black pixel */ - 2.4F, 2.4F, 2.4F, /* Gamma values for the three guns */ -}; -.fi -.RE -.PP -.I refWhite -is a color temperature of the reference white. The -.I TIFFTAG_WHITEPOINT -contains the chromaticity of the white point of the image from where the -reference white can be calculated using following formulae: -.PP -.RS -refWhite_Y = 100.0 -.br -refWhite_X = whitePoint_x / whitePoint_y * refWhite_Y -.br -refWhite_Z = (1.0 - whitePoint_x - whitePoint_y) / whitePoint_y * refWhite_X -.br -.RE -.PP -The conversion itself performed in two steps: at the first one we will convert -.I CIE L*a*b* 1976 -to -.I CIE XYZ -using -.B TIFFCIELabToXYZ() -routine, and at the second step we will convert -.I CIE XYZ -to -.I RGB -using -.B TIFFXYZToRGB(). -Look at the code sample below: -.PP -.RS -.nf -float *whitePoint; -float refWhite[3]; - -/* Initialize structures */ -img->cielab = (TIFFCIELabToRGB *) - _TIFFmalloc(sizeof(TIFFCIELabToRGB)); -if (!cielab) { - TIFFError("CIE L*a*b*->RGB", - "No space for CIE L*a*b*->RGB conversion state."); - exit(0); -} - -TIFFGetFieldDefaulted(tif, TIFFTAG_WHITEPOINT, &whitePoint); -refWhite[1] = 100.0F; -refWhite[0] = whitePoint[0] / whitePoint[1] * refWhite[1]; -refWhite[2] = (1.0F - whitePoint[0] - whitePoint[1]) - / whitePoint[1] * refWhite[1]; -if (TIFFCIELabToRGBInit(cielab, &display_sRGB, refWhite) < 0) { - TIFFError("CIE L*a*b*->RGB", - "Failed to initialize CIE L*a*b*->RGB conversion state."); - _TIFFfree(cielab); - exit(0); -} - -/* Now we can start to convert */ -uint32 r, g, b; -uint32 L; -int32 a, b; -float X, Y, Z; - -for each pixel in image - TIFFCIELabToXYZ(cielab, L, a, b, &X, &Y, &Z); - TIFFXYZToRGB(cielab, X, Y, Z, &r, &g, &b); - -/* Don't forget to free the state structure */ -_TIFFfree(cielab); -.fi -.RE -.PP -.SH "SEE ALSO" -.BR TIFFRGBAImage (3TIFF) -.BR libtiff (3TIFF), -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFmemory.3tiff b/gtk+-mingw/share/man/man3/TIFFmemory.3tiff deleted file mode 100644 index 55f446b..0000000 --- a/gtk+-mingw/share/man/man3/TIFFmemory.3tiff +++ /dev/null @@ -1,90 +0,0 @@ -.\" $Id: TIFFmemory.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1995 Sam Leffler -.\" Copyright (c) 1995 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH MEMORY 3TIFF "October 15, 1995" "libtiff" -.SH NAME -_TIFFmalloc, \c -_TIFFrealloc, \c -_TIFFfree, \c -_TIFFmemset, \c -_TIFFmemcpy, \c -_TIFFmemcmp, \c -\- memory management-related functions for use with -.SM TIFF -files -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tdata_t _TIFFmalloc(tsize_t " size ");" -.br -.BI "tdata_t _TIFFrealloc(tdata_t " buffer ", tsize_t " size ");" -.br -.BI "void _TIFFfree(tdata_t " buffer ");" -.br -.BI "void _TIFFmemset(tdata_t " s ", int " c ", tsize_t " n ");" -.br -.BI "void _TIFFmemcpy(tdata_t " dest ", const tdata_t " src ", tsize_t " n ");" -.br -.BI "int _TIFFmemcmp(const tdata_t " s1 ", const tdata_t "s2 ", tsize_t " n ");" -.SH DESCRIPTION -These routines are provided for writing portable software that uses -.IR libtiff ; -they hide any memory-management related issues, such as dealing with segmented -architectures found on 16-bit machines. -.PP -.I _TIFFmalloc -and -.I _TIFFrealloc -are used to dynamically allocate and reallocate memory used by -.IR libtiff ; -such as memory passed into the I/O routines. Memory allocated through these -interfaces is released back to the system using the -.I _TIFFfree -routine. -.PP -Memory allocated through one of the above interfaces can be set to a known -value using -.IR _TIFFmemset , -copied to another memory location using -.IR _TIFFmemcpy , -or compared for equality using -.IR _TIFFmemcmp . -These routines conform to the equivalent -.SM ANSI -C routines: -.IR memset , -.IR memcpy , -and -.IR memcmp , -repsectively. -.SH DIAGNOSTICS -None. -.SH "SEE ALSO" -.BR malloc (3), -.BR memory (3), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFquery.3tiff b/gtk+-mingw/share/man/man3/TIFFquery.3tiff deleted file mode 100644 index 8bddc88..0000000 --- a/gtk+-mingw/share/man/man3/TIFFquery.3tiff +++ /dev/null @@ -1,142 +0,0 @@ -.\" $Id: TIFFquery.3tiff,v 1.1 2004-11-11 14:39:16 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH QUERY 3TIFF "October 29, 2004" "libtiff" -.SH NAME -TIFFCurrentRow, -TIFFCurrentStrip, -TIFFCurrentTile, -TIFFCurrentDirectory, -TIFFLastDirectory, -TIFFFileno, -TIFFFileName, -TIFFGetMode, -TIFFIsTiled, -TIFFIsByteSwapped, -TIFFIsUpSampled, -TIFFIsMSB2LSB, -TIFFGetVersion -\- query routines -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "uint32 TIFFCurrentRow(TIFF* " tif ")" -.br -.BI "tstrip_t TIFFCurrentStrip(TIFF* " tif ")" -.br -.BI "ttile_t TIFFCurrentTile(TIFF* " tif ")" -.br -.BI "tdir_t TIFFCurrentDirectory(TIFF* " tif ")" -.br -.BI "int TIFFLastDirectory(TIFF* " tif ")" -.br -.BI "int TIFFFileno(TIFF* " tif ")" -.br -.BI "char* TIFFFileName(TIFF* " tif ")" -.br -.BI "int TIFFGetMode(TIFF* " tif ")" -.br -.BI "int TIFFIsTiled(TIFF* " tif ")" -.br -.BI "int TIFFIsByteSwapped(TIFF* " tif ")" -.br -.BI "int TIFFIsUpSampled(TIFF* " tif ")" -.br -.BI "int TIFFIsMSB2LSB(TIFF* " tif ")" -.br -.BI "const char* TIFFGetVersion(void)" -.SH DESCRIPTION -The following routines return status information about an open -.SM TIFF -file. -.PP -.IR TIFFCurrentDirectory -returns the index of the current directory (directories are numbered starting -at 0). This number is suitable for use with the -.IR TIFFSetDirectory -routine. -.PP -.IR TIFFLastDirectory -returns a non-zero value if the current directory is the last directory in the -file; otherwise zero is returned. -.PP -.IR TIFFCurrentRow , -.IR TIFFCurrentStrip , -and -.IR TIFFCurrentTile , -return the current row, strip, and tile, respectively, that is being read or -written. These values are updated each time a read or write is done. -.PP -.IR TIFFFileno -returns the underlying file descriptor used to access the -.SM TIFF -image in the filesystem. -.PP -.IR TIFFFileName -returns the pathname argument passed to -.IR TIFFOpen -or -.IR TIFFFdOpen . -.PP -.IR TIFFGetMode -returns the mode with which the underlying file was opened. On -.SM UNIX -systems, this is the value passed to the -.IR open (2) -system call. -.PP -.IR TIFFIsTiled -returns a non-zero value if the image data has a tiled organization. Zero is -returned if the image data is organized in strips. -.PP -.IR TIFFIsByteSwapped -returns a non-zero value if the image data was in a different byte-order than -the host machine. Zero is returned if the TIFF file and local host byte-orders -are the same. Note that TIFFReadTile(), TIFFReadStrip() and -TIFFReadScanline() functions already normally perform byte swapping to local -host order if needed. -.PP -.I TIFFIsUpSampled -returns a non-zero value if image data returned through the read interface -routines is being up-sampled. This can be useful to applications that want to -calculate I/O buffer sizes to reflect this usage (though the usual strip and -tile size routines already do this). -.PP -.I TIFFIsMSB2LSB -returns a non-zero value if the image data is being returned with bit 0 as the -most significant bit. -.PP -.IR TIFFGetVersion -returns an -.SM ASCII -string that has a version stamp for the -.SM TIFF -library software. -.SH DIAGNOSTICS -None. -.SH "SEE ALSO" -.IR libtiff (3TIFF), -.IR TIFFOpen (3TIFF), -.IR TIFFFdOpen (3TIFF) diff --git a/gtk+-mingw/share/man/man3/TIFFsize.3tiff b/gtk+-mingw/share/man/man3/TIFFsize.3tiff deleted file mode 100644 index 6de9084..0000000 --- a/gtk+-mingw/share/man/man3/TIFFsize.3tiff +++ /dev/null @@ -1,59 +0,0 @@ -.\" $Id: TIFFsize.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFSIZE 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFScanlineSize, TIFFRasterScanlineSize, -\- return the size of various items associated with an open -.SM TIFF -file -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "tsize_t TIFFRasterScanlineSize(TIFF *" tif ")" -.br -.BI "tsize_t TIFFScanlineSize(TIFF *" tif ")" -.SH DESCRIPTION -.I TIFFScanlineSize -returns the size in bytes of a row of data as it would be returned in a call -to -.IR TIFFReadScanline , -or as it would be expected in a call to -.IR TIFFWriteScanline . -.PP -.I TIFFRasterScanlineSize -returns the size in bytes of a complete decoded and packed raster scanline. -Note that this value may be different from the value returned by -.I TIFFScanlineSize -if data is stored as separate planes. -.SH DIAGNOSTICS -None. -.SH "SEE ALSO" -.BR TIFFOpen (3TIFF), -.BR TIFFReadScanline (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFstrip.3tiff b/gtk+-mingw/share/man/man3/TIFFstrip.3tiff deleted file mode 100644 index bb9658e..0000000 --- a/gtk+-mingw/share/man/man3/TIFFstrip.3tiff +++ /dev/null @@ -1,99 +0,0 @@ -.\" $Id: TIFFstrip.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1992-1997 Sam Leffler -.\" Copyright (c) 1992-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFSTRIP 3TIFF "October 15, 1995" "libtiff" -.SH NAME -TIFFDefaultStripSize, TIFFStripSize, TIFFVStripSize, TIFFRawStripSize, -TIFFComputeStrip, TIFFNumberOfStrips \- strip-related utility routines -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "uint32 TIFFDefaultStripSize(TIFF *" tif ", uint32 " estimate ")" -.br -.BI "tsize_t TIFFStripSize(TIFF *" tif ")" -.br -.BI "tsize_t TIFFVStripSize(TIFF *" tif ", uint32 " nrows ")" -.br -.BI "tsize_t TIFFRawStripSize(TIFF *" tif ", tstrip_t " strip ")" -.br -.BI "tstrip_t TIFFComputeStrip(TIFF *" tif ", uint32 " row ", tsample_t " sample ")" -.br -.BI "tstrip_t TIFFNumberOfStrips(TIFF *" tif ")" -.SH DESCRIPTION -.I TIFFDefaultStripSize -returns the number of rows for a reasonable-sized strip according to the -current settings of the -.IR ImageWidth , -.IR BitsPerSample , -.IR SamplesPerPixel , -tags and any compression-specific requirements. If the -.I estimate -parameter, if non-zero, then it is taken as an estimate of the desired strip -size and adjusted according to any compression-specific requirements. The -value returned by this function is typically used to define the -.I RowsPerStrip -tag. In lieu of any unusual requirements -.I TIFFDefaultStripSize -tries to create strips that have approximately -8 kilobytes of uncompressed data. -.PP -.IR TIFFStripSize -returns the equivalent size for a strip of data as it would be returned in a -call to -.IR TIFFReadEncodedStrip -or as it would be expected in a call to -.IR TIFFWriteEncodedStrip . -.PP -.I TIFFVStripSize -returns the number of bytes in a strip with -.I nrows -rows of data. -.PP -.I TIFFRawStripSize -returns the number of bytes in a raw strip (i.e. not decoded). -.PP -.IR TIFFComputeStrip -returns the strip that contains the specified coordinates. A valid strip is -always returned; out-of-range coordinate values are clamped to the bounds of -the image. The -.I row -parameter is always used in calculating a strip. The -.I sample -parameter is used only if data are organized in separate planes (\c -.IR PlanarConfiguration =2). -.PP -.IR TIFFNumberOfStrips -returns the number of strips in the image. -.SH DIAGNOSTICS -None. -.SH "SEE ALSO" -.BR TIFFReadEncodedStrip (3TIFF), -.BR TIFFReadRawStrip (3TIFF), -.BR TIFFWriteEncodedStrip (3TIFF), -.BR TIFFWriteRawStrip (3TIFF), -.BR libtiff (3TIFF), -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFswab.3tiff b/gtk+-mingw/share/man/man3/TIFFswab.3tiff deleted file mode 100644 index d6432fa..0000000 --- a/gtk+-mingw/share/man/man3/TIFFswab.3tiff +++ /dev/null @@ -1,80 +0,0 @@ -.\" $Id: TIFFswab.3tiff,v 1.2 2005-11-02 11:07:18 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH SWAB 3TIFF "November 04, 2004" "libtiff" -.SH NAME -TIFFGetBitRevTable, TIFFReverseBits, TIFFSwabShort, TIFFSwabLong, -TIFFSwabArrayOfShort, TIFFSwabArrayOfLong \- byte- and bit-swapping routines -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "const unsigned char* TIFFGetBitRevTable(int " reversed ")" -.br -.BI "void TIFFReverseBits(u_char *" data ", unsigned long " nbytes ")" -.br -.BI "void TIFFSwabShort(uint16 *" data ")" -.br -.BI "void TIFFSwabLong(uint32 *" data ")" -.br -.BI "void TIFFSwabArrayOfShort(uint16 *" data ", unsigned long " nshorts ")" -.br -.BI "void TIFFSwabArrayOfLong(uint32 *" data ", unsigned long " nlongs ")" -.SH DESCRIPTION -The following routines are used by the library to swap -16- and 32-bit data and to reverse the order of bits in bytes. -.PP -.IR TIFFSwabShort -and -.IR TIFFSwabLong -swap the bytes in a single 16-bit and 32-bit item, respectively. -.IR TIFFSwabArrayOfShort -and -.IR TIFFSwabArrayOfLong -swap the bytes in an array of 16-bit and 32-bit items, respectively. -.PP -.IR TIFFReverseBits -replaces each byte in -.I data -with the equivalent bit-reversed value. This operation is performed with a -lookup table, which is returned using the -.IR TIFFGetBitRevTable -function. -.I reversed -parameter specifies which table should be returned. Supply -.I 1 -if you want bit reversal table. Supply -.I 0 -to get the table that do not reverse bit values. It is a lookup table that can -be used as an -.IR "identity function" ; -i.e. -.IR "TIFFNoBitRevTable[n] == n" . -.SH DIAGNOSTICS -None. -.SH "SEE ALSO" -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/TIFFtile.3tiff b/gtk+-mingw/share/man/man3/TIFFtile.3tiff deleted file mode 100644 index 5431f31..0000000 --- a/gtk+-mingw/share/man/man3/TIFFtile.3tiff +++ /dev/null @@ -1,131 +0,0 @@ -.\" $Id: TIFFtile.3tiff,v 1.2 2005-11-02 11:07:19 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH TIFFTILE 3TIFF "February 14, 1992" "libtiff" -.SH NAME -TIFFTileSize, TIFFTileRowSize, TIFFVTileSize, TIFFDefaultTileSize, -TIFFComputeTile, TIFFCheckTile, TIFFNumberOfTiles \- tile-related utility -routines -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -.BI "void TIFFDefaultTileSize(TIFF *" tif ", uint32 *" tw ", uint32 *" th ")" -.br -.BI "tsize_t TIFFTileSize(TIFF *" tif ")" -.br -.BI "tsize_t TIFFTileRowSize(TIFF *" tif ")" -.br -.BI "tsize_t TIFFVTileSize(TIFF *" tif ", uint32 " nrows ")" -.br -.BI "ttile_t TIFFComputeTile(TIFF *" tif ", uint32 " x ", uint32 " y ", uint32 " z ", tsample_t " sample ")" -.br -.BI "int TIFFCheckTile(TIFF *" tif ", uint32 " x ", uint32 " y ", uint32 " z ", tsample_t " sample ")" -.br -.BI "ttile_t TIFFNumberOfTiles(TIFF *" tif ")" -.br -.SH DESCRIPTION -.I TIFFDefaultTileSize -returns the pixel width and height of a reasonable-sized tile; suitable for -setting up the -.I TileWidth -and -.I TileLength -tags. -If the -.I tw -and -.I th -values passed in are non-zero, then they are adjusted to reflect any -compression-specific requirements. The returned width and height are -constrained to be a multiple of 16 pixels to conform with the -.SM TIFF -specification. -.PP -.I TIFFTileSize -returns the equivalent size for a tile of data as it would be returned in a -call to -.I TIFFReadTile -or as it would be expected in a call to -.IR TIFFWriteTile . -.PP -.I TIFFVTileSize -returns the number of bytes in a row-aligned tile with -.I nrows -of data. -.PP -.I TIFFTileRowSize -returns the number of bytes of a row of data in a tile. -.PP -.IR TIFFComputeTile -returns the tile that contains the specified coordinates. A valid tile is -always returned; out-of-range coordinate values are clamped to the bounds of -the image. The -.I x -and -.I y -parameters are always used in calculating a tile. The -.I z -parameter is used if the image is deeper than 1 slice (\c -.IR ImageDepth >1). -The -.I sample -parameter is used only if data are organized in separate planes (\c -.IR PlanarConfiguration =2). -.PP -.IR TIFFCheckTile -returns a non-zero value if the supplied coordinates are within the bounds of -the image and zero otherwise. The -.I x -parameter is checked against the value of the -.I ImageWidth -tag. The -.I y -parameter is checked against the value of the -.I ImageLength -tag. The -.I z -parameter is checked against the value of the -.I ImageDepth -tag (if defined). The -.I sample -parameter is checked against the value of the -.I SamplesPerPixel -parameter if the data are organized in separate planes. -.PP -.IR TIFFNumberOfTiles -returns the number of tiles in the image. -.SH DIAGNOSTICS -None. -.SH "SEE ALSO" -.BR TIFFReadEncodedTile (3TIFF), -.BR TIFFReadRawTile (3TIFF), -.BR TIFFReadTile (3TIFF), -.BR TIFFWriteEncodedTile (3TIFF), -.BR TIFFWriteRawTile (3TIFF), -.BR TIFFWriteTile (3TIFF), -.BR libtiff (3TIFF) -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ diff --git a/gtk+-mingw/share/man/man3/bind_textdomain_codeset.3 b/gtk+-mingw/share/man/man3/bind_textdomain_codeset.3 deleted file mode 100644 index 141509b..0000000 --- a/gtk+-mingw/share/man/man3/bind_textdomain_codeset.3 +++ /dev/null @@ -1,72 +0,0 @@ -.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 2 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" GNU glibc-2 source code and manual -.\" GNU gettext source code and manual -.\" LI18NUX 2000 Globalization Specification -.\" -.TH BIND_TEXTDOMAIN_CODESET 3 "May 2001" "GNU gettext 0.18.1" -.SH NAME -bind_textdomain_codeset \- set encoding of message translations -.SH SYNOPSIS -.nf -.B #include <libintl.h> -.sp -.BI "char * bind_textdomain_codeset (const char * " domainname , -.BI " const char * " codeset ); -.fi -.SH DESCRIPTION -The \fBbind_textdomain_codeset\fP function sets the output codeset for message -catalogs for domain \fIdomainname\fP. -.PP -A message domain is a set of translatable \fImsgid\fP messages. Usually, -every software package has its own message domain. -.PP -By default, the \fBgettext\fP family of functions returns translated messages -in the locale's character encoding, which can be retrieved as -\fBnl_langinfo(CODESET)\fP. The need for calling \fBbind_textdomain_codeset\fP -arises for programs which store strings in a locale independent way (e.g. -UTF-8) and want to avoid an extra character set conversion on the returned -translated messages. -.PP -\fIdomainname\fP must be a non-empty string. -.PP -If \fIcodeset\fP is not NULL, it must be a valid encoding name which can be -used for the \fBiconv_open\fP function. The \fBbind_textdomain_codeset\fP -function sets the output codeset for message catalogs belonging to domain -\fIdomainname\fP to \fIcodeset\fP. The function makes copies of the argument -strings as needed. -.PP -If \fIcodeset\fP is NULL, the function returns the previously set codeset for -domain \fIdomainname\fP. The default is NULL, denoting the locale's character -encoding. -.SH "RETURN VALUE" -If successful, the \fBbind_textdomain_codeset\fP function returns the current -codeset for domain \fIdomainname\fP, after possibly changing it. The resulting -string is valid until the next \fBbind_textdomain_codeset\fP call for the same -\fIdomainname\fP and must not be modified or freed. If a memory allocation -failure occurs, it sets \fBerrno\fP to \fBENOMEM\fP and returns NULL. If no -codeset has been set for domain \fIdomainname\fP, it returns NULL. -.SH ERRORS -The following error can occur, among others: -.TP -.B ENOMEM -Not enough memory available. -.SH BUGS -The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid -warnings in C code predating ANSI C. -.SH "SEE ALSO" -.BR gettext (3), -.BR dgettext (3), -.BR dcgettext (3), -.BR ngettext (3), -.BR dngettext (3), -.BR dcngettext (3), -.BR textdomain (3), -.BR nl_langinfo (3), -.BR iconv_open (3) diff --git a/gtk+-mingw/share/man/man3/bindtextdomain.3 b/gtk+-mingw/share/man/man3/bindtextdomain.3 deleted file mode 100644 index 742f78c..0000000 --- a/gtk+-mingw/share/man/man3/bindtextdomain.3 +++ /dev/null @@ -1,69 +0,0 @@ -.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 2 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" GNU glibc-2 source code and manual -.\" GNU gettext source code and manual -.\" LI18NUX 2000 Globalization Specification -.\" -.TH BINDTEXTDOMAIN 3 "May 2001" "GNU gettext 0.18.1" -.SH NAME -bindtextdomain \- set directory containing message catalogs -.SH SYNOPSIS -.nf -.B #include <libintl.h> -.sp -.BI "char * bindtextdomain (const char * " domainname ", const char * " dirname ); -.fi -.SH DESCRIPTION -The \fBbindtextdomain\fP function sets the base directory of the hierarchy -containing message catalogs for a given message domain. -.PP -A message domain is a set of translatable \fImsgid\fP messages. Usually, -every software package has its own message domain. The need for calling -\fBbindtextdomain\fP arises because packages are not always installed with -the same prefix as the <libintl.h> header and the libc/libintl libraries. -.PP -Message catalogs will be expected at the pathnames -\fIdirname\fP/\fIlocale\fP/\fIcategory\fP/\fIdomainname\fP.mo, -where \fIlocale\fP is a locale name and \fIcategory\fP is a locale facet such -as \fBLC_MESSAGES\fP. -.PP -\fIdomainname\fP must be a non-empty string. -.PP -If \fIdirname\fP is not NULL, the base directory for message catalogs belonging -to domain \fIdomainname\fP is set to \fIdirname\fP. The function makes copies -of the argument strings as needed. If the program wishes to call the -\fBchdir\fP function, it is important that \fIdirname\fP be an absolute -pathname; otherwise it cannot be guaranteed that the message catalogs will -be found. -.PP -If \fIdirname\fP is NULL, the function returns the previously set base -directory for domain \fIdomainname\fP. -.SH "RETURN VALUE" -If successful, the \fBbindtextdomain\fP function returns the current base -directory for domain \fIdomainname\fP, after possibly changing it. The -resulting string is valid until the next \fBbindtextdomain\fP call for the -same \fIdomainname\fP and must not be modified or freed. If a memory allocation -failure occurs, it sets \fBerrno\fP to \fBENOMEM\fP and returns NULL. -.SH ERRORS -The following error can occur, among others: -.TP -.B ENOMEM -Not enough memory available. -.SH BUGS -The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid -warnings in C code predating ANSI C. -.SH "SEE ALSO" -.BR gettext (3), -.BR dgettext (3), -.BR dcgettext (3), -.BR ngettext (3), -.BR dngettext (3), -.BR dcngettext (3), -.BR textdomain (3), -.BR realpath (3) diff --git a/gtk+-mingw/share/man/man3/dcgettext.3 b/gtk+-mingw/share/man/man3/dcgettext.3 deleted file mode 100644 index 9082c86..0000000 --- a/gtk+-mingw/share/man/man3/dcgettext.3 +++ /dev/null @@ -1 +0,0 @@ -.so man3/gettext.3 diff --git a/gtk+-mingw/share/man/man3/dcngettext.3 b/gtk+-mingw/share/man/man3/dcngettext.3 deleted file mode 100644 index 5fcf629..0000000 --- a/gtk+-mingw/share/man/man3/dcngettext.3 +++ /dev/null @@ -1 +0,0 @@ -.so man3/ngettext.3 diff --git a/gtk+-mingw/share/man/man3/dgettext.3 b/gtk+-mingw/share/man/man3/dgettext.3 deleted file mode 100644 index 9082c86..0000000 --- a/gtk+-mingw/share/man/man3/dgettext.3 +++ /dev/null @@ -1 +0,0 @@ -.so man3/gettext.3 diff --git a/gtk+-mingw/share/man/man3/dngettext.3 b/gtk+-mingw/share/man/man3/dngettext.3 deleted file mode 100644 index 5fcf629..0000000 --- a/gtk+-mingw/share/man/man3/dngettext.3 +++ /dev/null @@ -1 +0,0 @@ -.so man3/ngettext.3 diff --git a/gtk+-mingw/share/man/man3/ffi.3 b/gtk+-mingw/share/man/man3/ffi.3 deleted file mode 100644 index 1f1d303..0000000 --- a/gtk+-mingw/share/man/man3/ffi.3 +++ /dev/null @@ -1,41 +0,0 @@ -.Dd February 15, 2008 -.Dt FFI 3 -.Sh NAME -.Nm FFI -.Nd Foreign Function Interface -.Sh LIBRARY -libffi, -lffi -.Sh SYNOPSIS -.In ffi.h -.Ft ffi_status -.Fo ffi_prep_cif -.Fa "ffi_cif *cif" -.Fa "ffi_abi abi" -.Fa "unsigned int nargs" -.Fa "ffi_type *rtype" -.Fa "ffi_type **atypes" -.Fc -.Ft void -.Fo ffi_prep_cif_var -.Fa "ffi_cif *cif" -.Fa "ffi_abi abi" -.Fa "unsigned int nfixedargs" -.Fa "unsigned int ntotalargs" -.Fa "ffi_type *rtype" -.Fa "ffi_type **atypes" -.Fc -.Ft void -.Fo ffi_call -.Fa "ffi_cif *cif" -.Fa "void (*fn)(void)" -.Fa "void *rvalue" -.Fa "void **avalue" -.Fc -.Sh DESCRIPTION -The foreign function interface provides a mechanism by which a function can -generate a call to another function at runtime without requiring knowledge of -the called function's interface at compile time. -.Sh SEE ALSO -.Xr ffi_prep_cif 3 , -.Xr ffi_prep_cif_var 3 , -.Xr ffi_call 3 diff --git a/gtk+-mingw/share/man/man3/ffi_call.3 b/gtk+-mingw/share/man/man3/ffi_call.3 deleted file mode 100644 index 5351513..0000000 --- a/gtk+-mingw/share/man/man3/ffi_call.3 +++ /dev/null @@ -1,103 +0,0 @@ -.Dd February 15, 2008 -.Dt ffi_call 3 -.Sh NAME -.Nm ffi_call -.Nd Invoke a foreign function. -.Sh SYNOPSIS -.In ffi.h -.Ft void -.Fo ffi_call -.Fa "ffi_cif *cif" -.Fa "void (*fn)(void)" -.Fa "void *rvalue" -.Fa "void **avalue" -.Fc -.Sh DESCRIPTION -The -.Nm ffi_call -function provides a simple mechanism for invoking a function without -requiring knowledge of the function's interface at compile time. -.Fa fn -is called with the values retrieved from the pointers in the -.Fa avalue -array. The return value from -.Fa fn -is placed in storage pointed to by -.Fa rvalue . -.Fa cif -contains information describing the data types, sizes and alignments of the -arguments to and return value from -.Fa fn , -and must be initialized with -.Nm ffi_prep_cif -before it is used with -.Nm ffi_call . -.Pp -.Fa rvalue -must point to storage that is sizeof(ffi_arg) or larger for non-floating point -types. For smaller-sized return value types, the -.Nm ffi_arg -or -.Nm ffi_sarg -integral type must be used to hold -the return value. -.Sh EXAMPLES -.Bd -literal -#include <ffi.h> -#include <stdio.h> - -unsigned char -foo(unsigned int, float); - -int -main(int argc, const char **argv) -{ - ffi_cif cif; - ffi_type *arg_types[2]; - void *arg_values[2]; - ffi_status status; - - // Because the return value from foo() is smaller than sizeof(long), it - // must be passed as ffi_arg or ffi_sarg. - ffi_arg result; - - // Specify the data type of each argument. Available types are defined - // in <ffi/ffi.h>. - arg_types[0] = &ffi_type_uint; - arg_types[1] = &ffi_type_float; - - // Prepare the ffi_cif structure. - if ((status = ffi_prep_cif(&cif, FFI_DEFAULT_ABI, - 2, &ffi_type_uint8, arg_types)) != FFI_OK) - { - // Handle the ffi_status error. - } - - // Specify the values of each argument. - unsigned int arg1 = 42; - float arg2 = 5.1; - - arg_values[0] = &arg1; - arg_values[1] = &arg2; - - // Invoke the function. - ffi_call(&cif, FFI_FN(foo), &result, arg_values); - - // The ffi_arg 'result' now contains the unsigned char returned from foo(), - // which can be accessed by a typecast. - printf("result is %hhu", (unsigned char)result); - - return 0; -} - -// The target function. -unsigned char -foo(unsigned int x, float y) -{ - unsigned char result = x - y; - return result; -} -.Ed -.Sh SEE ALSO -.Xr ffi 3 , -.Xr ffi_prep_cif 3 diff --git a/gtk+-mingw/share/man/man3/ffi_prep_cif.3 b/gtk+-mingw/share/man/man3/ffi_prep_cif.3 deleted file mode 100644 index e1bdbd7..0000000 --- a/gtk+-mingw/share/man/man3/ffi_prep_cif.3 +++ /dev/null @@ -1,70 +0,0 @@ -.Dd February 15, 2008 -.Dt ffi_prep_cif 3 -.Sh NAME -.Nm ffi_prep_cif -.Nd Prepare a -.Nm ffi_cif -structure for use with -.Nm ffi_call -. -.Sh SYNOPSIS -.In ffi.h -.Ft ffi_status -.Fo ffi_prep_cif -.Fa "ffi_cif *cif" -.Fa "ffi_abi abi" -.Fa "unsigned int nargs" -.Fa "ffi_type *rtype" -.Fa "ffi_type **atypes" -.Fc -.Sh DESCRIPTION -The -.Nm ffi_prep_cif -function prepares a -.Nm ffi_cif -structure for use with -.Nm ffi_call -. -.Fa abi -specifies a set of calling conventions to use. -.Fa atypes -is an array of -.Fa nargs -pointers to -.Nm ffi_type -structs that describe the data type, size and alignment of each argument. -.Fa rtype -points to an -.Nm ffi_type -that describes the data type, size and alignment of the -return value. Note that to call a variadic function -.Nm ffi_prep_cif_var -must be used instead. -.Sh RETURN VALUES -Upon successful completion, -.Nm ffi_prep_cif -returns -.Nm FFI_OK . -It will return -.Nm FFI_BAD_TYPEDEF -if -.Fa cif -is -.Nm NULL -or -.Fa atypes -or -.Fa rtype -is malformed. If -.Fa abi -does not refer to a valid ABI, -.Nm FFI_BAD_ABI -will be returned. Available ABIs are -defined in -.Nm <ffitarget.h> -. -.Sh SEE ALSO -.Xr ffi 3 , -.Xr ffi_call 3 , -.Xr ffi_prep_cif_var 3 - diff --git a/gtk+-mingw/share/man/man3/ffi_prep_cif_var.3 b/gtk+-mingw/share/man/man3/ffi_prep_cif_var.3 deleted file mode 100644 index 7e19d0b..0000000 --- a/gtk+-mingw/share/man/man3/ffi_prep_cif_var.3 +++ /dev/null @@ -1,73 +0,0 @@ -.Dd January 25, 2011 -.Dt ffi_prep_cif_var 3 -.Sh NAME -.Nm ffi_prep_cif_var -.Nd Prepare a -.Nm ffi_cif -structure for use with -.Nm ffi_call -for variadic functions. -.Sh SYNOPSIS -.In ffi.h -.Ft ffi_status -.Fo ffi_prep_cif_var -.Fa "ffi_cif *cif" -.Fa "ffi_abi abi" -.Fa "unsigned int nfixedargs" -.Fa "unsigned int ntotalargs" -.Fa "ffi_type *rtype" -.Fa "ffi_type **atypes" -.Fc -.Sh DESCRIPTION -The -.Nm ffi_prep_cif_var -function prepares a -.Nm ffi_cif -structure for use with -.Nm ffi_call -for variadic functions. -.Fa abi -specifies a set of calling conventions to use. -.Fa atypes -is an array of -.Fa ntotalargs -pointers to -.Nm ffi_type -structs that describe the data type, size and alignment of each argument. -.Fa rtype -points to an -.Nm ffi_type -that describes the data type, size and alignment of the -return value. -.Fa nfixedargs -must contain the number of fixed (non-variadic) arguments. -Note that to call a non-variadic function -.Nm ffi_prep_cif -must be used. -.Sh RETURN VALUES -Upon successful completion, -.Nm ffi_prep_cif_var -returns -.Nm FFI_OK . -It will return -.Nm FFI_BAD_TYPEDEF -if -.Fa cif -is -.Nm NULL -or -.Fa atypes -or -.Fa rtype -is malformed. If -.Fa abi -does not refer to a valid ABI, -.Nm FFI_BAD_ABI -will be returned. Available ABIs are -defined in -.Nm <ffitarget.h> -. -.Sh SEE ALSO -.Xr ffi 3 , -.Xr ffi_call 3 , -.Xr ffi_prep_cif 3 diff --git a/gtk+-mingw/share/man/man3/gettext.3 b/gtk+-mingw/share/man/man3/gettext.3 deleted file mode 100644 index de1400b..0000000 --- a/gtk+-mingw/share/man/man3/gettext.3 +++ /dev/null @@ -1,99 +0,0 @@ -.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 2 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" GNU glibc-2 source code and manual -.\" GNU gettext source code and manual -.\" LI18NUX 2000 Globalization Specification -.\" -.TH GETTEXT 3 "May 2001" "GNU gettext 0.18.1" -.SH NAME -gettext, dgettext, dcgettext \- translate message -.SH SYNOPSIS -.nf -.B #include <libintl.h> -.sp -.BI "char * gettext (const char * " msgid ); -.BI "char * dgettext (const char * " domainname ", const char * " msgid ); -.BI "char * dcgettext (const char * " domainname ", const char * " msgid , -.BI " int " category ); -.fi -.SH DESCRIPTION -The \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions attempt to -translate a text string into the user's native language, by looking up the -translation in a message catalog. -.PP -The \fImsgid\fP argument identifies the message to be translated. By -convention, it is the English version of the message, with non-ASCII -characters replaced by ASCII approximations. This choice allows the -translators to work with message catalogs, called PO files, that contain -both the English and the translated versions of each message, and can be -installed using the \fBmsgfmt\fP utility. -.PP -A message domain is a set of translatable \fImsgid\fP messages. Usually, -every software package has its own message domain. The domain name is used -to determine the message catalog where the translation is looked up; it must -be a non-empty string. For the \fBgettext\fP function, it is specified through -a preceding \fBtextdomain\fP call. For the \fBdgettext\fP and \fBdcgettext\fP -functions, it is passed as the \fIdomainname\fP argument; if this argument is -NULL, the domain name specified through a preceding \fBtextdomain\fP call is -used instead. -.PP -Translation lookup operates in the context of the current locale. For the -\fBgettext\fP and \fBdgettext\fP functions, the \fBLC_MESSAGES\fP locale -facet is used. It is determined by a preceding call to the \fBsetlocale\fP -function. \fBsetlocale(LC_ALL,"")\fP initializes the \fBLC_MESSAGES\fP locale -based on the first nonempty value of the three environment variables -\fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP; see \fBsetlocale\fP(3). For the -\fBdcgettext\fP function, the locale facet is determined by the \fIcategory\fP -argument, which should be one of the \fBLC_xxx\fP constants defined in the -<locale.h> header, excluding \fBLC_ALL\fP. In both cases, the functions also -use the \fBLC_CTYPE\fP locale facet in order to convert the translated message -from the translator's codeset to the current locale's codeset, unless -overridden by a prior call to the \fBbind_textdomain_codeset\fP function. -.PP -The message catalog used by the functions is at the pathname -\fIdirname\fP/\fIlocale\fP/\fIcategory\fP/\fIdomainname\fP.mo. Here -\fIdirname\fP is the directory specified through \fBbindtextdomain\fP. Its -default is system and configuration dependent; typically it is -\fIprefix\fP/share/locale, where \fIprefix\fP is the installation prefix of the -package. \fIlocale\fP is the name of the current locale facet; the GNU -implementation also tries generalizations, such as the language name without -the territory name. \fIcategory\fP is \fBLC_MESSAGES\fP for the \fBgettext\fP -and \fBdgettext\fP functions, or the argument passed to the \fBdcgettext\fP -function. -.PP -If the \fBLANGUAGE\fP environment variable is set to a nonempty value, and the -locale is not the "C" locale, the value of \fBLANGUAGE\fP is assumed to contain -a colon separated list of locale names. The functions will attempt to look up -a translation of \fImsgid\fP in each of the locales in turn. This is a GNU -extension. -.PP -In the "C" locale, or if none of the used catalogs contain a translation for -\fImsgid\fP, the \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions -return \fImsgid\fP. -.SH "RETURN VALUE" -If a translation was found in one of the specified catalogs, it is converted -to the locale's codeset and returned. The resulting string is statically -allocated and must not be modified or freed. Otherwise \fImsgid\fP is returned. -.SH ERRORS -\fBerrno\fP is not modified. -.SH BUGS -The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid -warnings in C code predating ANSI C. -.PP -When an empty string is used for \fImsgid\fP, the functions may return a -nonempty string. -.SH "SEE ALSO" -.BR ngettext (3), -.BR dngettext (3), -.BR dcngettext (3), -.BR setlocale (3), -.BR textdomain (3), -.BR bindtextdomain (3), -.BR bind_textdomain_codeset (3), -.BR msgfmt (1) diff --git a/gtk+-mingw/share/man/man3/iconv.3 b/gtk+-mingw/share/man/man3/iconv.3 deleted file mode 100644 index 3c511ea..0000000 --- a/gtk+-mingw/share/man/man3/iconv.3 +++ /dev/null @@ -1,92 +0,0 @@ -.\" Copyright (c) Bruno Haible <bruno@clisp.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 3 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" GNU glibc-2 source code and manual -.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html -.\" -.TH ICONV 3 "September 7, 2008" "GNU" "Linux Programmer's Manual" -.SH NAME -iconv \- perform character set conversion -.SH SYNOPSIS -.nf -.B #include <iconv.h> -.sp -.BI "size_t iconv (iconv_t " cd , -.BI " const char* * " inbuf ", size_t * "inbytesleft , -.BI " char* * " outbuf ", size_t * "outbytesleft ); -.fi -.SH DESCRIPTION -The argument \fIcd\fP must be a conversion descriptor created using the -function \fBiconv_open\fP. -.PP -The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL. -In this case, the \fBiconv\fP function converts the multibyte sequence -starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP. -At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read. -At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. -.PP -The \fBiconv\fP function converts one multibyte character at a time, and for -each character conversion it increments \fI*inbuf\fP and decrements -\fI*inbytesleft\fP by the number of converted input bytes, it increments -\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted -output bytes, and it updates the conversion state contained in \fIcd\fP. -If the character encoding of the input is stateful, the \fBiconv\fP function -can also convert a sequence of input bytes to an update of the conversion state -without producing any output bytes; such input is called a \fIshift sequence\fP. -The conversion can stop for four reasons: -.PP -1. An invalid multibyte sequence is encountered in the input. In this case -it sets \fBerrno\fP to \fBEILSEQ\fP and returns (size_t)(\-1). \fI*inbuf\fP -is left pointing to the beginning of the invalid multibyte sequence. -.PP -2. The input byte sequence has been entirely converted, i.e. \fI*inbytesleft\fP -has gone down to 0. In this case \fBiconv\fP returns the number of -non-reversible conversions performed during this call. -.PP -3. An incomplete multibyte sequence is encountered in the input, and the -input byte sequence terminates after it. In this case it sets \fBerrno\fP to -\fBEINVAL\fP and returns (size_t)(\-1). \fI*inbuf\fP is left pointing to the -beginning of the incomplete multibyte sequence. -.PP -4. The output buffer has no more room for the next converted character. In -this case it sets \fBerrno\fP to \fBE2BIG\fP and returns (size_t)(\-1). -.PP -A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but -\fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. In this case, the -\fBiconv\fP function attempts to set \fIcd\fP's conversion state to the -initial state and store a corresponding shift sequence at \fI*outbuf\fP. -At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written. -If the output buffer has no more room for this reset sequence, it sets -\fBerrno\fP to \fBE2BIG\fP and returns (size_t)(\-1). Otherwise it increments -\fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes -written. -.PP -A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and -\fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. In this case, the \fBiconv\fP -function sets \fIcd\fP's conversion state to the initial state. -.SH "RETURN VALUE" -The \fBiconv\fP function returns the number of characters converted in a -non-reversible way during this call; reversible conversions are not counted. -In case of error, it sets \fBerrno\fP and returns (size_t)(\-1). -.SH ERRORS -The following errors can occur, among others: -.TP -.B E2BIG -There is not sufficient room at \fI*outbuf\fP. -.TP -.B EILSEQ -An invalid multibyte sequence has been encountered in the input. -.TP -.B EINVAL -An incomplete multibyte sequence has been encountered in the input. -.SH "CONFORMING TO" -POSIX:2001 -.SH "SEE ALSO" -.BR iconv_open (3), -.BR iconvctl (3) -.BR iconv_close (3) diff --git a/gtk+-mingw/share/man/man3/iconv_close.3 b/gtk+-mingw/share/man/man3/iconv_close.3 deleted file mode 100644 index 1989268..0000000 --- a/gtk+-mingw/share/man/man3/iconv_close.3 +++ /dev/null @@ -1,31 +0,0 @@ -.\" Copyright (c) Bruno Haible <bruno@clisp.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 3 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" GNU glibc-2 source code and manual -.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html -.\" -.TH ICONV_CLOSE 3 "March 31, 2007" "GNU" "Linux Programmer's Manual" -.SH NAME -iconv_close \- deallocate descriptor for character set conversion -.SH SYNOPSIS -.nf -.B #include <iconv.h> -.sp -.BI "int iconv_close (iconv_t " cd ); -.fi -.SH DESCRIPTION -The \fBiconv_close\fP function deallocates a conversion descriptor \fIcd\fP -previously allocated using \fBiconv_open\fP. -.SH "RETURN VALUE" -When successful, the \fBiconv_close\fP function returns 0. In case of error, -it sets \fBerrno\fP and returns \-1. -.SH "CONFORMING TO" -POSIX:2001 -.SH "SEE ALSO" -.BR iconv_open (3) -.BR iconv (3) diff --git a/gtk+-mingw/share/man/man3/iconv_open.3 b/gtk+-mingw/share/man/man3/iconv_open.3 deleted file mode 100644 index 8075245..0000000 --- a/gtk+-mingw/share/man/man3/iconv_open.3 +++ /dev/null @@ -1,205 +0,0 @@ -.\" Copyright (c) Bruno Haible <bruno@clisp.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 3 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" GNU glibc-2 source code and manual -.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html -.\" -.TH ICONV_OPEN 3 "November 23, 2010" "GNU" "Linux Programmer's Manual" -.SH NAME -iconv_open \- allocate descriptor for character set conversion -.SH SYNOPSIS -.nf -.B #include <iconv.h> -.sp -.BI "iconv_t iconv_open (const char* " tocode ", const char* " fromcode ); -.fi -.SH DESCRIPTION -The \fBiconv_open\fP function allocates a conversion descriptor suitable -for converting byte sequences from character encoding \fIfromcode\fP to -character encoding \fItocode\fP. -.PP -The values permitted for \fIfromcode\fP and \fItocode\fP and the supported -combinations are system dependent. For the libiconv library, the following -encodings are supported, in all combinations. -.TP -European languages -.nf -.fi -ASCII, ISO\-8859\-{1,2,3,4,5,7,9,10,13,14,15,16}, -KOI8\-R, KOI8\-U, KOI8\-RU, -CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131}, -Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, -Mac{Cyrillic,Ukraine,Greek,Turkish}, -Macintosh -.TP -Semitic languages -.nf -.fi -ISO\-8859\-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic} -.TP -Japanese -.nf -.fi -EUC\-JP, SHIFT_JIS, CP932, ISO\-2022\-JP, ISO\-2022\-JP\-2, ISO\-2022\-JP\-1 -.TP -Chinese -.nf -.fi -EUC\-CN, HZ, GBK, CP936, GB18030, EUC\-TW, BIG5, CP950, BIG5\-HKSCS, -BIG5\-HKSCS:2004, BIG5\-HKSCS:2001, BIG5\-HKSCS:1999, ISO\-2022\-CN, -ISO\-2022\-CN\-EXT -.TP -Korean -.nf -.fi -EUC\-KR, CP949, ISO\-2022\-KR, JOHAB -.TP -Armenian -.nf -.fi -ARMSCII\-8 -.TP -Georgian -.nf -.fi -Georgian\-Academy, Georgian\-PS -.TP -Tajik -.nf -.fi -KOI8\-T -.TP -Kazakh -.nf -.fi -PT154, RK1048 -.TP -Thai -.nf -.fi -TIS\-620, CP874, MacThai -.TP -Laotian -.nf -.fi -MuleLao\-1, CP1133 -.TP -Vietnamese -.nf -.fi -VISCII, TCVN, CP1258 -.TP -Platform specifics -.nf -.fi -HP\-ROMAN8, NEXTSTEP -.TP -Full Unicode -.nf -.fi -UTF\-8 -.nf -.fi -UCS\-2, UCS\-2BE, UCS\-2LE -.nf -.fi -UCS\-4, UCS\-4BE, UCS\-4LE -.nf -.fi -UTF\-16, UTF\-16BE, UTF\-16LE -.nf -.fi -UTF\-32, UTF\-32BE, UTF\-32LE -.nf -.fi -UTF\-7 -.nf -.fi -C99, JAVA -.TP -Full Unicode, in terms of \fBuint16_t\fP or \fBuint32_t\fP -(with machine dependent endianness and alignment) -.nf -.fi -UCS\-2\-INTERNAL, UCS\-4\-INTERNAL -.TP -Locale dependent, in terms of \fBchar\fP or \fBwchar_t\fP -(with machine dependent endianness and alignment, and with semantics -depending on the OS and the current LC_CTYPE locale facet) -.nf -.fi -char, wchar_t -.PP -When configured with the option \fB\-\-enable\-extra\-encodings\fP, it also -provides support for a few extra encodings: -.TP -European languages -.nf -CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125} -.fi -.TP -Semitic languages -.nf -.fi -CP864 -.TP -Japanese -.nf -.fi -EUC\-JISX0213, Shift_JISX0213, ISO\-2022\-JP\-3 -.TP -Chinese -.nf -.fi -BIG5\-2003 (experimental) -.TP -Turkmen -.nf -.fi -TDS565 -.TP -Platform specifics -.nf -.fi -ATARIST, RISCOS\-LATIN1 -.PP -The empty encoding name "" is equivalent to "char": it denotes the -locale dependent character encoding. -.PP -When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration -is activated. This means that when a character cannot be represented in the -target character set, it can be approximated through one or several characters -that look similar to the original character. -.PP -When the string "//IGNORE" is appended to \fItocode\fP, characters that -cannot be represented in the target character set will be silently discarded. -.PP -The resulting conversion descriptor can be used with \fBiconv\fP any number -of times. It remains valid until deallocated using \fBiconv_close\fP. -.PP -A conversion descriptor contains a conversion state. After creation using -\fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP -modifies the descriptor's conversion state. (This implies that a conversion -descriptor can not be used in multiple threads simultaneously.) To bring the -state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP -argument. -.SH "RETURN VALUE" -The \fBiconv_open\fP function returns a freshly allocated conversion -descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(\-1). -.SH ERRORS -The following error can occur, among others: -.TP -.B EINVAL -The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the -implementation. -.SH "CONFORMING TO" -POSIX:2001 -.SH "SEE ALSO" -.BR iconv (3) -.BR iconvctl (3) -.BR iconv_close (3) diff --git a/gtk+-mingw/share/man/man3/iconv_open_into.3 b/gtk+-mingw/share/man/man3/iconv_open_into.3 deleted file mode 100644 index 92c2d53..0000000 --- a/gtk+-mingw/share/man/man3/iconv_open_into.3 +++ /dev/null @@ -1,47 +0,0 @@ -.\" Copyright (c) Bruno Haible <bruno@clisp.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 3 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" iconv.h -.\" -.TH ICONV_OPEN_INTO 3 "September 21, 2008" "GNU" "Linux Programmer's Manual" -.SH NAME -iconv_open_into \- initialize descriptor for character set conversion -.SH SYNOPSIS -.nf -.B #include <iconv.h> -.sp -.BI "int iconv_open_into (const char* " tocode ", const char* " fromcode "," -.BI " iconv_allocation_t* " resultp ); -.fi -.SH DESCRIPTION -The \fBiconv_open_into\fP function initializes a conversion descriptor suitable -for converting byte sequences from character encoding \fIfromcode\fP to -character encoding \fItocode\fP. The conversion descriptor is stored in the -memory pointed to by \fIresultp\fP. -.PP -The values permitted for \fIfromcode\fP and \fItocode\fP are the same as for -the function \fBiconv_open\fP. -.PP -After a successful return from this function, \fIresultp\fP can be be used -as an \fBiconv_t\fP object with the \fBiconv\fP function. -.SH "RETURN VALUE" -The \fBiconv_open_into\fP function fills \fB*\fP\fIresultp\fP and returns 0 if -it succeeds. In case of error, it sets \fBerrno\fP and returns \-1. -.SH ERRORS -The following error can occur, among others: -.TP -.B EINVAL -The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the -implementation. -.SH "CONFORMING TO" -This function is implemented only in GNU libiconv and not in other \fBiconv\fP -implementations. It is not backed by a standard. You can test for its presence -through \fB(_LIBICONV_VERSION >= 0x010D)\fP. -.SH "SEE ALSO" -.BR iconv_open (3) -.BR iconv (3) diff --git a/gtk+-mingw/share/man/man3/iconvctl.3 b/gtk+-mingw/share/man/man3/iconvctl.3 deleted file mode 100644 index 6caf394..0000000 --- a/gtk+-mingw/share/man/man3/iconvctl.3 +++ /dev/null @@ -1,67 +0,0 @@ -.\" Copyright (c) Perry Rapp -.\" Copyright (c) Bruno Haible <bruno@clisp.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 3 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" iconv.h -.\" -.TH ICONVCTL 3 "March 31, 2007" "GNU" "Linux Programmer's Manual" -.SH NAME -iconvctl \- control iconv behavior -.SH SYNOPSIS -.nf -.B #include <iconv.h> -.sp -.BI "int iconvctl (iconv_t " cd " , int " request ", void * " argument ); -.fi -.SH DESCRIPTION -The argument \fIcd\fP must be a conversion descriptor created using the -function \fBiconv_open\fP. -.PP -\fBiconvctl\fP queries or adjusts the behavior of the \fBiconv\fP function, -when invoked with the specified conversion descriptor, depending on the -request value. -.SH "REQUEST VALUES" -The following are permissible values for the \fIrequest\fP parameter. -.TP -.B ICONV_TRIVIALP -\fIargument\fP should be an \fBint *\fP which will receive 1 if the -conversion is trivial, or 0 otherwise. -.TP -.B ICONV_GET_TRANSLITERATE -\fIargument\fP should be an \fBint *\fP which will receive 1 if -transliteration is enabled in the conversion, or 0 otherwise. -.TP -.B ICONV_SET_TRANSLITERATE -\fIargument\fP should be a \fBconst int *\fP, pointing to an \fBint\fP value. -A non-zero value is used to enable transliteration in the conversion. A zero -value disables it. -.TP -.B ICONV_GET_DISCARD_ILSEQ -\fIargument\fP should be an \fBint *\fP which will receive 1 if -"illegal sequence discard and continue" is enabled in the conversion, -or 0 otherwise. -.TP -.B ICONV_SET_DISCARD_ILSEQ -\fIargument\fP should be a \fBconst int *\fP, pointing to an \fBint\fP value. -A non-zero value is used to enable "illegal sequence discard and continue" -in the conversion. A zero value disables it. -.SH "RETURN VALUE" -The \fBiconvctl\fP function returns 0 if it succeeds. In case of error, it sets -\fBerrno\fP and returns \-1. -.SH ERRORS -The following errors can occur, among others: -.TP -.B EINVAL -The request is invalid. -.SH "CONFORMING TO" -This function is implemented only in GNU libiconv and not in other \fBiconv\fP -implementations. It is not backed by a standard. You can test for its presence -through \fB(_LIBICONV_VERSION >= 0x0108)\fP. -.SH "SEE ALSO" -.BR iconv_open (3) -.BR iconv (3) diff --git a/gtk+-mingw/share/man/man3/libpng.3 b/gtk+-mingw/share/man/man3/libpng.3 deleted file mode 100644 index 91afdbe..0000000 --- a/gtk+-mingw/share/man/man3/libpng.3 +++ /dev/null @@ -1,5991 +0,0 @@ -.TH LIBPNG 3 "July 11, 2012" -.SH NAME -libpng \- Portable Network Graphics (PNG) Reference Library 1.5.12 -.SH SYNOPSIS -\fI\fB - -\fB#include <png.h>\fP - -\fI\fB - -\fBpng_uint_32 png_access_version_number \fI(void\fP\fB);\fP - -\fI\fB - -\fBvoid png_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP - -\fI\fB - -\fBvoid png_build_grayscale_palette (int \fP\fIbit_depth\fP\fB, png_colorp \fIpalette\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_calloc (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP - -\fI\fB - -\fBvoid png_chunk_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP - -\fI\fB - -\fBvoid png_chunk_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP - -\fI\fB - -\fBvoid png_chunk_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP - -\fI\fB - -\fBvoid png_convert_from_struct_tm (png_timep \fP\fIptime\fP\fB, struct tm FAR * \fIttime\fP\fB);\fP - -\fI\fB - -\fBvoid png_convert_from_time_t (png_timep \fP\fIptime\fP\fB, time_t \fIttime\fP\fB);\fP - -\fI\fB - -\fBpng_charp png_convert_to_rfc1123 (png_structp \fP\fIpng_ptr\fP\fB, png_timep \fIptime\fP\fB);\fP - -\fI\fB - -\fBpng_infop png_create_info_struct (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_structp png_create_read_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP - -\fI\fB - -\fBpng_structp png_create_read_struct_2 (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP - -\fI\fB - -\fBpng_structp png_create_write_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP - -\fI\fB - -\fBpng_structp png_create_write_struct_2 (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_data_freer (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIfreer\fP\fB, png_uint_32 \fImask)\fP\fB);\fP - -\fI\fB - -\fBvoid png_destroy_info_struct (png_structp \fP\fIpng_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_destroy_read_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fP\fIinfo_ptr_ptr\fP\fB, png_infopp \fIend_info_ptr_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_destroy_write_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_err (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP - -\fI\fB - -\fBvoid png_free (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_free_chunk_list (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_free_default (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_free_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_bit_depth (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_bKGD (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_channels (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_cHRM (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_cHRM_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_cHRM_XYZ (png_structp \fIpng_ptr, - -\fBpng_const_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*red_X\fP\fB, double \fP\fI*red_Y\fP\fB, double \fI*red_Z, - -\fBdouble \fP\fI*green_X\fP\fB, double \fP\fI*green_Y\fP\fB, double \fP\fI*green_Z\fP\fB, double \fI*blue_X, - -\fBdouble \fP\fI*blue_Y\fP\fB, double \fI*blue_Z\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_cHRM_XYZ_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_fixed_point \fP\fI*int_red_X\fP\fB, png_fixed_point \fP\fI*int_red_Y\fP\fB, png_fixed_point \fP\fI*int_red_Z\fP\fB, png_fixed_point \fP\fI*int_green_X\fP\fB, png_fixed_point \fP\fI*int_green_Y\fP\fB, png_fixed_point \fP\fI*int_green_Z\fP\fB, png_fixed_point \fP\fI*int_blue_X\fP\fB, png_fixed_point \fP\fI*int_blue_Y\fP\fB, png_fixed_point \fI*int_blue_Z\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_chunk_cache_max (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_alloc_size_t png_get_chunk_malloc_max (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_color_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_compression_buffer_size (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_compression_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_copyright (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_current_row_number \fI(png_const_structp\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_current_pass_number \fI(png_const_structp\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_error_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_filter_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_gAMA (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_gAMA_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_header_ver (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_header_version (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_hIST (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_iCCP (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_bytepp \fP\fIprofile\fP\fB, png_uint_32 \fI*proflen\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*width\fP\fB, png_uint_32 \fP\fI*height\fP\fB, int \fP\fI*bit_depth\fP\fB, int \fP\fI*color_type\fP\fB, int \fP\fI*interlace_type\fP\fB, int \fP\fI*compression_type\fP\fB, int \fI*filter_type\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_image_height (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_image_width (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_int_32 png_get_int_32 (png_bytep \fIbuf\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_interlace_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_const_bytep png_get_io_chunk_name (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_io_chunk_type (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_io_state (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_libpng_ver (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_mem_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_oFFs (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_pCAL (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fI*purpose\fP\fB, png_int_32 \fP\fI*X0\fP\fB, png_int_32 \fP\fI*X1\fP\fB, int \fP\fI*type\fP\fB, int \fP\fI*nparams\fP\fB, png_charp \fP\fI*units\fP\fB, png_charpp \fI*params\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_pHYs (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP - -\fI\fB - -\fBfloat png_get_pixel_aspect_ratio (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_pHYs_dpi (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP - -\fI\fB - -\fBpng_fixed_point png_get_pixel_aspect_ratio_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_pixels_per_inch (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_pixels_per_meter (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_progressive_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_PLTE (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fI*palette\fP\fB, int \fI*num_palette\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_rgb_to_gray_status (png_const_structp \fIpng_ptr) - -\fBpng_uint_32 png_get_rowbytes (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_bytepp png_get_rows (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_sBIT (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP - -\fI\fB - -\fBvoid png_get_sCAL (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, double* \fP\fIwidth\fP\fB, double* \fIheight\fP\fB);\fP - -\fI\fB - -\fBvoid png_get_sCAL_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_fixed_pointp \fP\fIwidth\fP\fB, png_fixed_pointp \fIheight\fP\fB);\fP - -\fI\fB - -\fBvoid png_get_sCAL_s (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_charpp \fP\fIwidth\fP\fB, png_charpp \fIheight\fP\fB);\fP - -\fI\fB - -\fBpng_bytep png_get_signature (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_sPLT (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_sRGB (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int \fI*file_srgb_intent\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_text (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fI*text_ptr\fP\fB, int \fI*num_text\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_tIME (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fI*mod_time\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_tRNS (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans_alpha\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_color\fP\fB);\fP - -\fI\fB - -\fB/* This function is really an inline macro. \fI*/ - -\fBpng_uint_16 png_get_uint_16 (png_bytep \fIbuf\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_uint_31 (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIbuf\fP\fB);\fP - -\fI\fB - -\fB/* This function is really an inline macro. \fI*/ - -\fBpng_uint_32 png_get_uint_32 (png_bytep \fIbuf\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_unknown_chunks (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_user_chunk_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_user_height_max (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_user_transform_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_user_width_max (png_const_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_valid (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP - -\fI\fB - -\fBfloat png_get_x_offset_inches (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_fixed_point png_get_x_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_int_32 png_get_x_offset_microns (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_int_32 png_get_x_offset_pixels (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_x_pixels_per_inch (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_x_pixels_per_meter (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBfloat png_get_y_offset_inches (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_fixed_point png_get_y_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_int_32 png_get_y_offset_microns (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_int_32 png_get_y_offset_pixels (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_y_pixels_per_inch (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_y_pixels_per_meter (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBint png_handle_as_unknown (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIchunk_name\fP\fB);\fP - -\fI\fB - -\fBvoid png_info_init_3 (png_infopp \fP\fIinfo_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP - -\fI\fB - -\fBvoid png_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP - -\fI\fB - -\fBvoid png_longjmp (png_structp \fP\fIpng_ptr\fP\fB, int \fIval\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_malloc_default (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_malloc_warn (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_permit_mng_features (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fImng_features_permitted\fP\fB);\fP - -\fI\fB - -\fBvoid png_process_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_size\fP\fB);\fP - -\fI\fB - -\fBpng_size_t png_process_data_pause \fP\fI(png_structp\fP\fB, int \fIsave\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_process_data_skip \fI(png_structp\fP\fB);\fP - -\fI\fB - -\fBvoid png_progressive_combine_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIold_row\fP\fB, png_bytep \fInew_row\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, png_voidp \fIparams\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_bytepp \fP\fIdisplay_row\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBint png_reset_zstream (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_save_int_32 (png_bytep \fP\fIbuf\fP\fB, png_int_32 \fIi\fP\fB);\fP - -\fI\fB - -\fBvoid png_save_uint_16 (png_bytep \fP\fIbuf\fP\fB, unsigned int \fIi\fP\fB);\fP - -\fI\fB - -\fBvoid png_save_uint_32 (png_bytep \fP\fIbuf\fP\fB, png_uint_32 \fIi\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_alpha_mode (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImode\fP\fB, double \fIoutput_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_alpha_mode_fixed (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImode\fP\fB, png_fixed_point \fIoutput_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_background (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, double \fIbackground_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_background_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, png_uint_32 \fIbackground_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_benign_errors (png_structp \fP\fIpng_ptr\fP\fB, int \fIallowed\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fIbackground\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_check_for_invalid_index(png_structrp \fP\fIpng_ptr\fP\fB, int \fIallowed\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIwhite_x\fP\fB, double \fP\fIwhite_y\fP\fB, double \fP\fIred_x\fP\fB, double \fP\fIred_y\fP\fB, double \fP\fIgreen_x\fP\fB, double \fP\fIgreen_y\fP\fB, double \fP\fIblue_x\fP\fB, double \fIblue_y\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwhite_x\fP\fB, png_uint_32 \fP\fIwhite_y\fP\fB, png_uint_32 \fP\fIred_x\fP\fB, png_uint_32 \fP\fIred_y\fP\fB, png_uint_32 \fP\fIgreen_x\fP\fB, png_uint_32 \fP\fIgreen_y\fP\fB, png_uint_32 \fP\fIblue_x\fP\fB, png_uint_32 \fIblue_y\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_cHRM_XYZ (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIred_X\fP\fB, double \fP\fIred_Y\fP\fB, double \fP\fIred_Z\fP\fB, double \fP\fIgreen_X\fP\fB, double \fIgreen_Y, - -\fBdouble \fP\fIgreen_Z\fP\fB, double \fP\fIblue_X\fP\fB, double \fP\fIblue_Y\fP\fB, double \fIblue_Z\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_cHRM_XYZ_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_fixed_point \fP\fIint_red_X\fP\fB, png_fixed_point \fP\fIint_red_Y\fP\fB, png_fixed_point \fP\fIint_red_Z\fP\fB, png_fixed_point \fP\fIint_green_X\fP\fB, png_fixed_point \fP\fIint_green_Y\fP\fB, png_fixed_point \fP\fIint_green_Z\fP\fB, png_fixed_point \fP\fIint_blue_X\fP\fB, png_fixed_point \fP\fIint_blue_Y\fP\fB, png_fixed_point \fIint_blue_Z\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_chunk_cache_max (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIuser_chunk_cache_max\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_method (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_crc_action (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIcrit_action\fP\fB, int \fIancil_action\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_error_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarning_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_expand_16 (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_expand_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_filler (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_filter (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImethod\fP\fB, int \fIfilters\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_filter_heuristics (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_doublep \fP\fIfilter_weights\fP\fB, png_doublep \fIfilter_costs\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_filter_heuristics_fixed (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_fixed_point_p \fP\fIfilter_weights\fP\fB, png_fixed_point_p \fIfilter_costs\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_flush (png_structp \fP\fIpng_ptr\fP\fB, int \fInrows\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gamma (png_structp \fP\fIpng_ptr\fP\fB, double \fP\fIscreen_gamma\fP\fB, double \fIdefault_file_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gamma_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIscreen_gamma\fP\fB, png_uint_32 \fIdefault_file_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fIfile_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIfile_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gray_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fIhist\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_const_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_const_bytep \fP\fIprofile\fP\fB, png_uint_32 \fIproflen\fP\fB);\fP - -\fI\fB - -\fBint png_set_interlace_handling (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_invalid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fImask\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_invert_alpha (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_invert_mono (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwidth\fP\fB, png_uint_32 \fP\fIheight\fP\fB, int \fP\fIbit_depth\fP\fB, int \fP\fIcolor_type\fP\fB, int \fP\fIinterlace_type\fP\fB, int \fP\fIcompression_type\fP\fB, int \fIfilter_type\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_keep_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIkeep\fP\fB, png_bytep \fP\fIchunk_list\fP\fB, int \fInum_chunks\fP\fB);\fP - -\fI\fB - -\fBjmp_buf* png_set_longjmp_fn (png_structp \fP\fIpng_ptr\fP\fB, png_longjmp_ptr \fP\fIlongjmp_fn\fP\fB, size_t \fIjmp_buf_size\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_chunk_malloc_max (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIuser_chunk_cache_max\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_buffer_size (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_mem_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIoffset_x\fP\fB, png_uint_32 \fP\fIoffset_y\fP\fB, int \fIunit_type\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_packing (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_packswap (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_palette_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIpurpose\fP\fB, png_int_32 \fP\fIX0\fP\fB, png_int_32 \fP\fIX1\fP\fB, int \fP\fItype\fP\fB, int \fP\fInparams\fP\fB, png_charp \fP\fIunits\fP\fB, png_charpp \fIparams\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIres_x\fP\fB, png_uint_32 \fP\fIres_y\fP\fB, int \fIunit_type\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_progressive_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIprogressive_ptr\fP\fB, png_progressive_info_ptr \fP\fIinfo_fn\fP\fB, png_progressive_row_ptr \fP\fIrow_fn\fP\fB, png_progressive_end_ptr \fIend_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fInum_palette\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_quantize (png_structp \fP\fIpng_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fP\fInum_palette\fP\fB, int \fP\fImaximum_colors\fP\fB, png_uint_16p \fP\fIhistogram\fP\fB, int \fIfull_quantize\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fIread_data_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_read_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_read_status_ptr \fIread_row_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_read_user_chunk_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_chunk_ptr\fP\fB, png_user_chunk_ptr \fIread_user_chunk_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_read_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIread_user_transform_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_rgb_to_gray (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIerror_action\fP\fB, double \fP\fIred\fP\fB, double \fIgreen\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_uint_32 \fP\fIred\fP\fB, png_uint_32 \fIgreen\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytepp \fIrow_pointers\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fIsig_bit\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sCAL_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, png_fixed_point \fP\fIwidth\fP\fB, png_fixed_point \fIheight\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sCAL_s (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, png_charp \fP\fIwidth\fP\fB, png_charp \fIheight\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_scale_16 (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_shift (png_structp \fP\fIpng_ptr\fP\fB, png_color_8p \fItrue_bits\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sig_bytes (png_structp \fP\fIpng_ptr\fP\fB, int \fInum_bytes\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fP\fIsplt_ptr\fP\fB, int \fInum_spalettes\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIsrgb_intent\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sRGB_gAMA_and_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIsrgb_intent\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_strip_16 (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_strip_alpha (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_strip_error_numbers (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIstrip_mode\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_swap (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_swap_alpha (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fItext_ptr\fP\fB, int \fInum_text\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_text_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_text_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_text_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_text_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP - -\fI\fB - -\fBvoid \fP\fIpng_set_text_compression_method\fP\fB, (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod)\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fImod_time\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fItrans_alpha\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_color\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_tRNS_to_alpha (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_set_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkp \fP\fIunknowns\fP\fB, int \fP\fInum\fP\fB, int \fIlocation\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_unknown_chunk_location (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIchunk\fP\fB, int \fIlocation\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_user_limits (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIuser_width_max\fP\fB, png_uint_32 \fIuser_height_max\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_user_transform_info (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_transform_ptr\fP\fB, int \fP\fIuser_transform_depth\fP\fB, int \fIuser_transform_channels\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_write_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fP\fIwrite_data_fn\fP\fB, png_flush_ptr \fIoutput_flush_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_write_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_write_status_ptr \fIwrite_row_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_write_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIwrite_user_transform_fn\fP\fB);\fP - -\fI\fB - -\fBint png_sig_cmp (png_bytep \fP\fIsig\fP\fB, png_size_t \fP\fIstart\fP\fB, png_size_t \fInum_to_check\fP\fB);\fP - -\fI\fB - -\fBvoid png_start_read_image (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_chunk (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_chunk_data (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_chunk_end (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_chunk_start (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_uint_32 \fIlength\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_flush (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_info_before_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, png_voidp \fIparams\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIrow\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_sig (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoidpf png_zalloc (voidpf \fP\fIpng_ptr\fP\fB, uInt \fP\fIitems\fP\fB, uInt \fIsize\fP\fB);\fP - -\fI\fB - -\fBvoid png_zfree (voidpf \fP\fIpng_ptr\fP\fB, voidpf \fIptr\fP\fB);\fP - -\fI\fB - -.SH DESCRIPTION -The -.I libpng -library supports encoding, decoding, and various manipulations of -the Portable Network Graphics (PNG) format image files. It uses the -.IR zlib(3) -compression library. -Following is a copy of the libpng-manual.txt file that accompanies libpng. -.SH LIBPNG.TXT -Libpng-manual.txt - A description on how to use and modify libpng - - libpng version 1.5.12 - July 11, 2012 - Updated and distributed by Glenn Randers-Pehrson - <glennrp at users.sourceforge.net> - Copyright (c) 1998-2011 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.5.12 - July 11, 2012 - Updated and distributed by Glenn Randers-Pehrson - Copyright (c) 1998-2011 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 - -.SH I. Introduction - -This file describes how to use and modify the PNG reference library -(known as libpng) for your own use. There are five sections to this -file: introduction, structures, reading, writing, and modification and -configuration notes for various special platforms. 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 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:2003 (E)) at -<http://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 -<http://www.libpng.org/pub/png/documents/>. 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 <http://www.libpng.org/pub/png/documents/> and as a -W3C Recommendation <http://www.w3.org/TR/REC.png.html>. - -Some additional chunks are described in the special-purpose public chunks -documents at <http://www.libpng.org/pub/png/documents/>. - -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, <http://www.info-zip.org/pub/infozip/zlib/>. -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. - -.SH 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> - -.SS 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. - -.SS 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_USR_CONFIG - -If -DPNG_USR_CONFIG is added to the CFLAGS 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. - -.SH 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. - -.SS 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_read() -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); - } - - fread(header, 1, number, fp); - 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. 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 - -.SS 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 will be saved when read, in case your callback function will need -one or more of them. This behavior can be changed with the -png_set_keep_unknown_chunks() function, described below. - -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. - -.SS 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 0) - - num_chunks - number of chunks affected; if 0, all - unknown chunks are affected. If nonzero, - only the chunks in the list 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: */ - png_set_keep_unknown_chunks(read_ptr, 1, 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 - -.SS 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. -Since very few applications really need to process such large images, -we have imposed an arbitrary 1-million limit on rows and columns. -Larger images will be rejected immediately with a png_error() call. If -you wish to change this limit, you can use - - png_set_user_limits(png_ptr, width_max, height_max); - -to set your own limits, or use width_max = height_max = 0x7fffffffL -to allow all valid dimensions (libpng may reject some very large 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. You can impose a limit on the total number -of sPLT, tEXt, iTXt, zTXt, and unknown 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); - -This limit also applies to the number of buffers that can be allocated -by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks. - -You can also set a limit on the amount of memory that a compressed chunk -other than IDAT can occupy, 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. - -.SS 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, 1/screen_gamma/*file gamma*/); - -or you can use the fixed point equivalent: - - png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma, PNG_FP_1/screen_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 reencode 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 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!) - - 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 -an appropriate format to try if your software, or more -likely hardware, is totally broken, i.e., if it performs -linear arithmetic directly on gamma encoded values. - -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. - -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. - -.SS 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/png_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*png_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. - -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_*(). - -.SS 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. - -.SS 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 or all of 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 16-bit - 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 - - 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. - - 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 was - 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); - - file_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_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(). - -.SS 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 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 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. This transformation -does not affect images that already have full alpha channels. To add an -opaque alpha channel, use filler=0xff or 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. -This 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, -<http://www.poynton.com/>, 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 then 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. - -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. - -.SS 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_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); - -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); - -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. - -.SS Finishing a sequential read - -After you are finished reading the image through the -low-level interface, you can finish reading the file. If you are -interested in comments or time, which may be stored either before or -after the image data, you should pass the separate png_info struct if -you want to keep the comments from before and after the image -separate. - - png_infop end_info = png_create_info_struct(png_ptr); - - if (!end_info) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - return (ERROR); - } - - png_read_end(png_ptr, end_info); - -If you are not interested, you should still call png_read_end() -but you can pass NULL, avoiding the need to create an end_info structure. - - png_read_end(png_ptr, (png_infop)NULL); - -If you don't call png_read_end(), then your file pointer will be -left pointing to the first chunk after the last IDAT, which is probably -not what you want if you expect to read something beyond the end of -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_zalloc() 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_zalloc() 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_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. - -.SS Reading PNG files progressively - -The progressive reader is slightly different then 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 then 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 for - 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. - */ - } - - - -.SH 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. - -.SS 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. - -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. - -.SS 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); - -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); - -.SS 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_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(png_timep) is provided to convert from PNG -time to an RFC 1123 format string. - -.SS Writing unknown chunks - -You can use the png_set_unknown_chunks function to queue up chunks -for writing. You give it a chunk name, raw data, and a size; 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. -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. - -.SS 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(). - -.SS 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. - -.SS 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. - -.SS 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_zalloc() 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_zalloc() 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. - -.SH V. 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(). These currently just call the standard C functions. -png_calloc() calls png_malloc() and then clears the newly -allocated memory to zero. 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. Since it is -unlikely that the method of handling memory allocation on a platform -will change between applications, these functions must be modified in -the library at compile time. 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); - - png_voidp error_ptr = png_get_error_ptr(png_ptr); - -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); - -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 http://cexcept.sourceforge.net), -which is illustrated in pngvalid.c and in contrib/visupng. - -.SS 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. - -.SS Configuring for 16-bit platforms - -You will want to look into zconf.h to tell zlib (and thus libpng) that -it cannot allocate more then 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. - -.SS 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. - -.SS 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 *". - -.SS 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.). - -.SS 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 -%14%in turn includes pngconf.h. -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. - -.SS 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); - - 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 - -.SS 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 and PNG_NO_FILTERS -to turn filtering on and off, 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_FILTER_NONE | PNG_FILTER_SUB - PNG_FILTER_UP | PNG_FILTER_AVG | - PNG_FILTER_PAETH | PNG_ALL_FILTERS; - - 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(). - -It is also possible to influence how libpng chooses from among the -available filters. This is done in one or both of two ways - by -telling it how important it is to keep the same filter for successive -rows, and by telling it the relative computational costs of the filters. - - double weights[3] = {1.5, 1.3, 1.1}, - costs[PNG_FILTER_VALUE_LAST] = - {1.0, 1.3, 1.3, 1.5, 1.7}; - - png_set_filter_heuristics(png_ptr, - PNG_FILTER_HEURISTIC_WEIGHTED, 3, - weights, costs); - -The weights are multiplying factors that indicate to libpng that the -row filter should be the same for successive rows unless another row filter -is that many times better than the previous filter. In the above example, -if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a -"sum of absolute differences" 1.5 x 1.3 times higher than other filters -and still be chosen, while the NONE filter could have a sum 1.1 times -higher than other filters and still be chosen. Unspecified weights are -taken to be 1.0, and the specified weights should probably be declining -like those above in order to emphasize recent filters over older filters. - -The filter costs specify for each filter type a relative decoding cost -to be considered when selecting row filters. This means that filters -with higher costs are less likely to be chosen over filters with lower -costs, unless their "sum of absolute differences" is that much smaller. -The costs do not necessarily reflect the exact computational speeds of -the various filters, since this would unduly influence the final image -size. - -Note that the numbers above were invented purely for this example and -are given only to help explain the function usage. Little testing has -been done to find optimum values for either the costs or the weights. - -.SS 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. - -.SS 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\n", 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. - -.SH VI. 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 -http://www.libmng.com) instead. - -.SH VII. 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. - -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; - -.SH VIII. 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. - -.SH IX. 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. - -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 reenabled, 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. - -.SH X. 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. - -Checking for invalid palette index on read or write was added at libpng -1.5.10. When an invalid index is found, libpng issues a benign error. -This is enabled by default but can be disabled in each png_ptr with - - png_set_check_for_invalid_index(png_ptr, allowed); - - allowed - one of - 0: disable - 1: enable - -A. Changes that affect users of libpng - -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 -the main libpng control structures, png_struct and png_info, deprecated -in earlier versions of libpng, has been completely removed from -libpng 1.5. - -We no longer include zlib.h in png.h. Applications that need access -to information in zlib.h will need to add the '#include "zlib.h"' -directive. It does not matter whether it is placed prior to or after -the '"#include png.h"' directive. - -We moved the png_strcpy(), png_strncpy(), png_strlen(), png_memcpy(), -png_memcmp(), png_sprintf, and png_memcpy() 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. - -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. - -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. libpng 1.5.0 -is consistent with the implementation in 1.4.5 and 1.2.x (where the macro -did not exist.) - -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. - -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.10, the user limits can be set en masse with the -configuration option PNG_SAFE_LIMITS_SUPPORTED. If this option is enabled, -a set of "safe" limits is applied in pngpriv.h. 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() that increase or decrease the limits. Also, -in libpng-1.5.10 the default width and height limits were increased -from 1,000,000 to 0x7ffffff (i.e., made unlimited). Therefore, the -limits are now - default safe - png_user_width_max 0x7fffffff 1,000,000 - png_user_height_max 0x7fffffff 1,000,000 - png_user_chunk_cache_max 0 (unlimited) 128 - png_user_chunk_malloc_max 0 (unlimited) 8,000,000 - -B. Changes to the build and configuration of libpng - -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. - -B.1 Specific changes to library configuration capabilities - -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. 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. - -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.) - -B.2 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, when 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 rarely used alternative of adding a list of feature macros to the -CFLAGS 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 removed. 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 a case where pngusr.h is still required. - -.SH XI. 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, ... - -.SH XII. 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 - - git://libpng.git.sourceforge.net/gitroot/libpng - -or you can browse it via "gitweb" at - - http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng - -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 - - http://libpng.sourceforge.net - -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, or directly to glennrp. - -.SH XIII. Coding style - -Our coding style is similar to the "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 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 ^ and in libpngpf.3 */ - -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 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 prefer to express integers that are used as bit masks in hex format, -with an even number of lower-case hex digits (e.g., 0x00, 0xff, 0x0100). - -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. - -.SH XIV. Y2K Compliance in libpng - -July 11, 2012 - -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.5.12 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 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 will no -longer be 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() in png.c - (formerly png_convert_to_rfc_1152() in error) - 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 - -.SH NOTE - -Note about libpng version numbers: - -Due to various miscommunications, unforeseen code incompatibilities -and occasional factors outside the authors' control, version numbering -on the library has not always been consistent and straightforward. -The following table summarizes matters since version 0.89c, which was -the first widely used release: - - source png.h png.h shared-lib - version string int version - ------- ------ ----- ---------- - 0.89c ("beta 3") 0.89 89 1.0.89 - 0.90 ("beta 4") 0.90 90 0.90 - 0.95 ("beta 5") 0.95 95 0.95 - 0.96 ("beta 6") 0.96 96 0.96 - 0.97b ("beta 7") 1.00.97 97 1.0.1 - 0.97c 0.97 97 2.0.97 - 0.98 0.98 98 2.0.98 - 0.99 0.99 98 2.0.99 - 0.99a-m 0.99 99 2.0.99 - 1.00 1.00 100 2.1.0 - 1.0.0 1.0.0 100 2.1.0 - 1.0.0 (from here on, the 100 2.1.0 - 1.0.1 png.h string is 10001 2.1.0 - 1.0.1a-e identical to the 10002 from here on, the - 1.0.2 source version) 10002 shared library is 2.V - 1.0.2a-b 10003 where V is the source - 1.0.1 10001 code version except as - 1.0.1a-e 10002 2.1.0.1a-e noted. - 1.0.2 10002 2.1.0.2 - 1.0.2a-b 10003 2.1.0.2a-b - 1.0.3 10003 2.1.0.3 - 1.0.3a-d 10004 2.1.0.3a-d - 1.0.4 10004 2.1.0.4 - 1.0.4a-f 10005 2.1.0.4a-f - 1.0.5 (+ 2 patches) 10005 2.1.0.5 - 1.0.5a-d 10006 2.1.0.5a-d - 1.0.5e-r 10100 2.1.0.5e-r - 1.0.5s-v 10006 2.1.0.5s-v - 1.0.6 (+ 3 patches) 10006 2.1.0.6 - 1.0.6d-g 10007 2.1.0.6d-g - 1.0.6h 10007 10.6h - 1.0.6i 10007 10.6i - 1.0.6j 10007 2.1.0.6j - 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14 - 1.0.7beta15-18 1 10007 2.1.0.7beta15-18 - 1.0.7rc1-2 1 10007 2.1.0.7rc1-2 - 1.0.7 1 10007 2.1.0.7 - 1.0.8beta1-4 1 10008 2.1.0.8beta1-4 - 1.0.8rc1 1 10008 2.1.0.8rc1 - 1.0.8 1 10008 2.1.0.8 - 1.0.9beta1-6 1 10009 2.1.0.9beta1-6 - 1.0.9rc1 1 10009 2.1.0.9rc1 - 1.0.9beta7-10 1 10009 2.1.0.9beta7-10 - 1.0.9rc2 1 10009 2.1.0.9rc2 - 1.0.9 1 10009 2.1.0.9 - 1.0.10beta1 1 10010 2.1.0.10beta1 - 1.0.10rc1 1 10010 2.1.0.10rc1 - 1.0.10 1 10010 2.1.0.10 - 1.0.11beta1-3 1 10011 2.1.0.11beta1-3 - 1.0.11rc1 1 10011 2.1.0.11rc1 - 1.0.11 1 10011 2.1.0.11 - 1.0.12beta1-2 2 10012 2.1.0.12beta1-2 - 1.0.12rc1 2 10012 2.1.0.12rc1 - 1.0.12 2 10012 2.1.0.12 - 1.1.0a-f - 10100 2.1.1.0a-f abandoned - 1.2.0beta1-2 2 10200 2.1.2.0beta1-2 - 1.2.0beta3-5 3 10200 3.1.2.0beta3-5 - 1.2.0rc1 3 10200 3.1.2.0rc1 - 1.2.0 3 10200 3.1.2.0 - 1.2.1beta-4 3 10201 3.1.2.1beta1-4 - 1.2.1rc1-2 3 10201 3.1.2.1rc1-2 - 1.2.1 3 10201 3.1.2.1 - 1.2.2beta1-6 12 10202 12.so.0.1.2.2beta1-6 - 1.0.13beta1 10 10013 10.so.0.1.0.13beta1 - 1.0.13rc1 10 10013 10.so.0.1.0.13rc1 - 1.2.2rc1 12 10202 12.so.0.1.2.2rc1 - 1.0.13 10 10013 10.so.0.1.0.13 - 1.2.2 12 10202 12.so.0.1.2.2 - 1.2.3rc1-6 12 10203 12.so.0.1.2.3rc1-6 - 1.2.3 12 10203 12.so.0.1.2.3 - 1.2.4beta1-3 13 10204 12.so.0.1.2.4beta1-3 - 1.2.4rc1 13 10204 12.so.0.1.2.4rc1 - 1.0.14 10 10014 10.so.0.1.0.14 - 1.2.4 13 10204 12.so.0.1.2.4 - 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2 - 1.0.15rc1 10 10015 10.so.0.1.0.15rc1 - 1.0.15 10 10015 10.so.0.1.0.15 - 1.2.5 13 10205 12.so.0.1.2.5 - 1.2.6beta1-4 13 10206 12.so.0.1.2.6beta1-4 - 1.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5 - 1.0.16 10 10016 10.so.0.1.0.16 - 1.2.6 13 10206 12.so.0.1.2.6 - 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2 - 1.0.17rc1 10 10017 12.so.0.1.0.17rc1 - 1.2.7rc1 13 10207 12.so.0.1.2.7rc1 - 1.0.17 10 10017 12.so.0.1.0.17 - 1.2.7 13 10207 12.so.0.1.2.7 - 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5 - 1.0.18rc1-5 10 10018 12.so.0.1.0.18rc1-5 - 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5 - 1.0.18 10 10018 12.so.0.1.0.18 - 1.2.8 13 10208 12.so.0.1.2.8 - 1.2.9beta1-3 13 10209 12.so.0.1.2.9beta1-3 - 1.2.9beta4-11 13 10209 12.so.0.9[.0] - 1.2.9rc1 13 10209 12.so.0.9[.0] - 1.2.9 13 10209 12.so.0.9[.0] - 1.2.10beta1-7 13 10210 12.so.0.10[.0] - 1.2.10rc1-2 13 10210 12.so.0.10[.0] - 1.2.10 13 10210 12.so.0.10[.0] - 1.4.0beta1-6 14 10400 14.so.0.0[.0] - 1.2.11beta1-4 13 10210 12.so.0.11[.0] - 1.4.0beta7-8 14 10400 14.so.0.0[.0] - 1.2.11 13 10211 12.so.0.11[.0] - 1.2.12 13 10212 12.so.0.12[.0] - 1.4.0beta9-14 14 10400 14.so.0.0[.0] - 1.2.13 13 10213 12.so.0.13[.0] - 1.4.0beta15-36 14 10400 14.so.0.0[.0] - 1.4.0beta37-87 14 10400 14.so.14.0[.0] - 1.4.0rc01 14 10400 14.so.14.0[.0] - 1.4.0beta88-109 14 10400 14.so.14.0[.0] - 1.4.0rc02-08 14 10400 14.so.14.0[.0] - 1.4.0 14 10400 14.so.14.0[.0] - 1.4.1beta01-03 14 10401 14.so.14.1[.0] - 1.4.1rc01 14 10401 14.so.14.1[.0] - 1.4.1beta04-12 14 10401 14.so.14.1[.0] - 1.4.1 14 10401 14.so.14.1[.0] - 1.4.2 14 10402 14.so.14.2[.0] - 1.4.3 14 10403 14.so.14.3[.0] - 1.4.4 14 10404 14.so.14.4[.0] - 1.5.0beta01-58 15 10500 15.so.15.0[.0] - 1.5.0rc01-07 15 10500 15.so.15.0[.0] - 1.5.0 15 10500 15.so.15.0[.0] - 1.5.1beta01-11 15 10501 15.so.15.1[.0] - 1.5.1rc01-02 15 10501 15.so.15.1[.0] - 1.5.1 15 10501 15.so.15.1[.0] - 1.5.2beta01-03 15 10502 15.so.15.2[.0] - 1.5.2rc01-03 15 10502 15.so.15.2[.0] - 1.5.2 15 10502 15.so.15.2[.0] - 1.5.3beta01-10 15 10503 15.so.15.3[.0] - 1.5.3rc01-02 15 10503 15.so.15.3[.0] - 1.5.3beta11 15 10503 15.so.15.3[.0] - 1.5.3 [omitted] - 1.5.4beta01-08 15 10504 15.so.15.4[.0] - 1.5.4rc01 15 10504 15.so.15.4[.0] - 1.5.4 15 10504 15.so.15.4[.0] - 1.5.5beta01-08 15 10505 15.so.15.5[.0] - 1.5.5rc01 15 10505 15.so.15.5[.0] - 1.5.5 15 10505 15.so.15.5[.0] - 1.5.6beta01-07 15 10506 15.so.15.6[.0] - 1.5.6rc01-03 15 10506 15.so.15.6[.0] - 1.5.6 15 10506 15.so.15.6[.0] - 1.5.7beta01-05 15 10507 15.so.15.7[.0] - 1.5.7rc01-03 15 10507 15.so.15.7[.0] - 1.5.7 15 10507 15.so.15.7[.0] - 1.5.8beta01 15 10508 15.so.15.8[.0] - 1.5.8rc01 15 10508 15.so.15.8[.0] - 1.5.8 15 10508 15.so.15.8[.0] - 1.5.9beta01-02 15 10509 15.so.15.9[.0] - 1.5.9rc01 15 10509 15.so.15.9[.0] - 1.5.9 15 10509 15.so.15.9[.0] - 1.5.10beta01-05 15 10510 15.so.15.10[.0] - 1.5.10 15 10510 15.so.15.10[.0] - 1.5.11beta01 15 10511 15.so.15.11[.0] - 1.5.11rc01-05 15 10511 15.so.15.11[.0] - 1.5.11 15 10511 15.so.15.11[.0] - 1.5.12 15 10512 15.so.15.12[.0] - -Henceforth the source version will match the shared-library minor -and patch numbers; the shared-library major version number will be -used for changes in backward compatibility, as it is intended. The -PNG_PNGLIB_VER macro, which is not used within libpng but is available -for applications, is an unsigned integer of the form xyyzz corresponding -to the source version x.y.z (leading zeros in y and z). Beta versions -were given the previous public release number plus a letter, until -version 1.0.6j; from then on they were given the upcoming public -release number plus "betaNN" or "rcN". - -.SH "SEE ALSO" -.BR "png"(5), " libpngpf"(3), " zlib"(3), " deflate"(5), " " and " zlib"(5) - -.LP -.IR libpng : -.IP -http://libpng.sourceforge.net (follow the [DOWNLOAD] link) -http://www.libpng.org/pub/png - -.LP -.IR zlib : -.IP -(generally) at the same location as -.I libpng -or at -.br -ftp://ftp.info-zip.org/pub/infozip/zlib - -.LP -.IR PNG specification: RFC 2083 -.IP -(generally) at the same location as -.I libpng -or at -.br -ftp://ds.internic.net/rfc/rfc2083.txt -.br -or (as a W3C Recommendation) at -.br -http://www.w3.org/TR/REC-png.html - -.LP -In the case of any inconsistency between the PNG specification -and this library, the specification takes precedence. - -.SH AUTHORS -This man page: Glenn Randers-Pehrson -<glennrp at users.sourceforge.net> - -The contributing authors would like to thank all those who helped -with testing, bug fixes, and patience. This wouldn't have been -possible without all of you. - -Thanks to Frank J. T. Wojcik for helping with the documentation. - -Libpng version 1.5.12 - July 11, 2012: -Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. -Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). - -Supported by the PNG development group -.br -png-mng-implement at lists.sf.net -(subscription required; visit -png-mng-implement at lists.sourceforge.net (subscription required; visit -https://lists.sourceforge.net/lists/listinfo/png-mng-implement -to subscribe). - -.SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE: - -(This copy of the libpng notices is provided for your convenience. In case of -any discrepancy between this copy and the notices in the file png.h that is -included in the libpng distribution, the latter shall prevail.) - -If you modify libpng you may insert additional notices immediately following -this sentence. - -This code is released under the libpng license. - -libpng versions 1.2.6, August 15, 2004, through 1.5.12, July 11, 2012, are -Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are -distributed according to the same disclaimer and license as libpng-1.2.5 -with the following individual added to the list of Contributing Authors - - Cosmin Truta - -libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October 3, 2002, are -Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are -distributed according to the same disclaimer and license as libpng-1.0.6 -with the following individuals added to the list of Contributing Authors - - Simon-Pierre Cadieux - Eric S. Raymond - Gilles Vollant - -and with the following additions to the disclaimer: - - There is no warranty against interference with your - enjoyment of the library or against infringement. - There is no warranty that our efforts or the library - will fulfill any of your particular purposes or needs. - This library is provided with all faults, and the entire - risk of satisfactory quality, performance, accuracy, and - effort is with the user. - -libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are -Copyright (c) 1998, 1999 Glenn Randers-Pehrson -Distributed according to the same disclaimer and license as libpng-0.96, -with the following individuals added to the list of Contributing Authors: - - Tom Lane - Glenn Randers-Pehrson - Willem van Schaik - -libpng versions 0.89, June 1996, through 0.96, May 1997, are -Copyright (c) 1996, 1997 Andreas Dilger -Distributed according to the same disclaimer and license as libpng-0.88, -with the following individuals added to the list of Contributing Authors: - - John Bowler - Kevin Bracey - Sam Bushell - Magnus Holmgren - Greg Roelofs - Tom Tanner - -libpng versions 0.5, May 1995, through 0.88, January 1996, are -Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc. - -For the purposes of this copyright and license, "Contributing Authors" -is defined as the following set of individuals: - - Andreas Dilger - Dave Martindale - Guy Eric Schalnat - Paul Schmidt - Tim Wegner - -The PNG Reference Library is supplied "AS IS". The Contributing Authors -and Group 42, Inc. disclaim all warranties, expressed or implied, -including, without limitation, the warranties of merchantability and of -fitness for any purpose. The Contributing Authors and Group 42, Inc. -assume no liability for direct, indirect, incidental, special, exemplary, -or consequential damages, which may result from the use of the PNG -Reference Library, even if advised of the possibility of such damage. - -Permission is hereby granted to use, copy, modify, and distribute this -source code, or portions hereof, for any purpose, without fee, subject -to the following restrictions: - -1. The origin of this source code must not be misrepresented. - -2. Altered versions must be plainly marked as such and - must not be misrepresented as being the original source. - -3. This Copyright notice may not be removed or altered from - any source or altered source distribution. - -The Contributing Authors and Group 42, Inc. specifically permit, without -fee, and encourage the use of this source code as a component to -supporting the PNG file format in commercial products. If you use this -source code in a product, acknowledgment is not required but would be -appreciated. - - -A "png_get_copyright" function is available, for convenient use in "about" -boxes and the like: - - printf("%s",png_get_copyright(NULL)); - -Also, the PNG logo (in PNG format, of course) is supplied in the -files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31). - -Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a -certification mark of the Open Source Initiative. - -Glenn Randers-Pehrson -glennrp at users.sourceforge.net -July 11, 2012 - -.\" end of man page - diff --git a/gtk+-mingw/share/man/man3/libpngpf.3 b/gtk+-mingw/share/man/man3/libpngpf.3 deleted file mode 100644 index 4b07ce3..0000000 --- a/gtk+-mingw/share/man/man3/libpngpf.3 +++ /dev/null @@ -1,28 +0,0 @@ -.TH LIBPNGPF 3 "July 11, 2012" -.SH NAME -libpng \- Portable Network Graphics (PNG) Reference Library 1.5.12 -(private functions) -.SH SYNOPSIS -\fB#include \fI"pngpriv.h" - -\fI\fB - -\fBAs of libpng version \fP\fI1.5.1\fP\fB, this section is no longer \fP\fImaintained\fP\fB, now \fIthat - -\fBthe private function prototypes are hidden in pngpriv.h and not \fIaccessible - -\fBto applications. Look in pngpriv.h for the prototypes and a short \fIdescription - -\fBof each \fIfunction. - -\fI\fB - -.SH DESCRIPTION -The functions previously listed here are used privately by libpng -and are not recommended for use by applications. They are -not "exported" to applications using shared libraries. - -.SH SEE ALSO -.BR "png"(5), " libpng"(3), " zlib"(3), " deflate"(5), " " and " zlib"(5) -.SH AUTHOR -Glenn Randers-Pehrson diff --git a/gtk+-mingw/share/man/man3/libtiff.3tiff b/gtk+-mingw/share/man/man3/libtiff.3tiff deleted file mode 100644 index 710f908..0000000 --- a/gtk+-mingw/share/man/man3/libtiff.3tiff +++ /dev/null @@ -1,536 +0,0 @@ -.\" $Id: libtiff.3tiff,v 1.3 2005-11-02 11:07:19 dron Exp $ -.\" -.\" Copyright (c) 1988-1997 Sam Leffler -.\" Copyright (c) 1991-1997 Silicon Graphics, Inc. -.\" -.\" Permission to use, copy, modify, distribute, and sell this software and -.\" its documentation for any purpose is hereby granted without fee, provided -.\" that (i) the above copyright notices and this permission notice appear in -.\" all copies of the software and related documentation, and (ii) the names of -.\" Sam Leffler and Silicon Graphics may not be used in any advertising or -.\" publicity relating to the software without the specific, prior written -.\" permission of Sam Leffler and Silicon Graphics. -.\" -.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, -.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY -.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. -.\" -.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR -.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, -.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF -.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE -.\" OF THIS SOFTWARE. -.\" -.if n .po 0 -.TH INTRO 3TIFF "November 2, 2005" "libtiff" -.SH NAME -libtiff \- introduction to -.IR libtiff , -a library for reading and writing -.SM TIFF -files -.SH SYNOPSIS -.B "#include <tiffio.h>" -.sp -cc file.c -.B -ltiff -.SH DESCRIPTION -.I libtiff -is a library for reading and writing data files encoded with the -.I "Tag Image File" -format, Revision 6.0 (or revision 5.0 or revision 4.0). This file format is -suitable for archiving multi-color and monochromatic image data. -.PP -The library supports several compression algorithms, as indicated by the -.I Compression -field, including: -no compression (1), -.SM CCITT -1D Huffman compression (2), -.SM CCITT -Group 3 Facsimile compression (3), -.SM CCITT -Group 4 Facsimile compression (4), -Lempel-Ziv & Welch compression (5), -baseline JPEG compression (7), -word-aligned 1D Huffman compression (32771), -and -PackBits compression (32773). -In addition, several nonstandard compression algorithms are supported: the -4-bit compression algorithm used by the -.I ThunderScan -program (32809) (decompression only), NeXT's 2-bit compression algorithm -(32766) (decompression only), an experimental LZ-style algorithm known as -Deflate (32946), and an experimental CIE LogLuv compression scheme designed -for images with high dynamic range (32845 for LogL and 32845 for LogLuv). -Directory information may be in either little- or big-endian byte order\-byte -swapping is automatically done by the library. Data bit ordering may be either -Most Significant Bit (\c -.SM MSB\c -) to Least Significant Bit (\c -.SM LSB\c -) or -.SM LSB -to -.SM MSB. -Finally, the library does not support files in which the -.IR BitsPerSample , -.IR Compression , -.IR MinSampleValue , -or -.IR MaxSampleValue -fields are defined differently on a per-sample basis -(in Rev. 6.0 the -.I Compression -tag is not defined on a per-sample basis, so this is immaterial). -.SH "DATA TYPES" -The library makes extensive use of C typedefs to promote portability. -Two sets of typedefs are used, one for communication with clients -of the library and one for internal data structures and parsing of the -.SM TIFF -format. -The following typedefs are exposed to users either through function -definitions or through parameters passed through the varargs interfaces. -.in +.5i -.sp 5p -.ta +\w'typedef unsigned <\fIthing\fP> uint32; 'u -.nf -typedef unsigned short uint16; 16-bit unsigned integer -typedef unsigned <\fIthing\fP> uint32; 32-bit unsigned integer -.sp 5p -typedef unsigned int ttag_t; directory tag -typedef uint16 tdir_t; directory index -typedef uint16 tsample_t; sample number -typedef uint32 tstrip_t; strip number -typedef uint32 ttile_t; tile number -typedef int32 tsize_t; i/o size in bytes -typedef void* tdata_t; image data ref -typedef void* thandle_t; client data handle -typedef int32 toff_t; file offset -.fi -.sp 5p -.in -.5i -Note that -.IR tstrip_t , -.IR ttile_t , -and -.I tsize_t -are constrained to be no more than 32-bit quantities by 32-bit fields they are -stored in in the -.SM TIFF -image. -Likewise -.I tsample_t -is limited by the 16-bit field used to store the -.I SamplesPerPixel -tag. -.I tdir_t -constrains the maximum number of -.SM IFDs -that may appear in an image and may be an arbitrary size (w/o penalty). -.I ttag_t -must be either int, unsigned int, pointer, or double because the library uses -a varargs interface and -.SM "ANSI C" -restricts the type of the parameter before an ellipsis to be a promoted type. -.I toff_t -is defined as int32 because TIFF file offsets are (unsigned) 32-bit -quantities. A signed value is used because some interfaces return \-1 on -error. Finally, note that user-specified data references are passed as opaque -handles and only cast at the lowest layers where their type is presumed. -.SH "LIST OF ROUTINES" -The following routines are part of the library. Consult specific manual pages -for details on their operation; on most systems doing ``man function-name'' -will work. -.sp -.nf -.ta \w'TIFFCheckpointDirectory'u+2n -\fIName\fP \fIDescription\fP -.sp 5p -TIFFCheckpointDirectory writes the current state of the directory -TIFFCheckTile very x,y,z,sample is within image -TIFFCIELabToRGBInit initialize CIE L*a*b* 1976 to RGB conversion state -TIFFCIELabToXYZ perform CIE L*a*b* 1976 to CIE XYZ conversion -TIFFClientOpen open a file for reading or writing -TIFFClose close an open file -TIFFComputeStrip return strip containing y,sample -TIFFComputeTile return tile containing x,y,z,sample -TIFFCurrentDirectory return index of current directory -TIFFCurrentRow return index of current scanline -TIFFCurrentStrip return index of current strip -TIFFCurrentTile return index of current tile -TIFFDataWidth return the size of TIFF data types -TIFFError library error handler -TIFFFdOpen open a file for reading or writing -TIFFFileName return name of open file -TIFFFileno return open file descriptor -TIFFFindCODEC find standard codec for the specific scheme -TIFFFlush flush all pending writes -TIFFFlushData flush pending data writes -TIFFGetBitRevTable return bit reversal table -TIFFGetField return tag value in current directory -TIFFGetFieldDefaulted return tag value in current directory -TIFFGetMode return open file mode -TIFFGetVersion return library version string -TIFFIsCODECConfigured check, whether we have working codec -TIFFIsMSB2LSB return true if image data is being returned - with bit 0 as the most significant bit -TIFFIsTiled return true if image data is tiled -TIFFIsByteSwapped return true if image data is byte-swapped -TIFFNumberOfStrips return number of strips in an image -TIFFNumberOfTiles return number of tiles in an image -TIFFOpen open a file for reading or writing -TIFFPrintDirectory print description of the current directory -TIFFReadBufferSetup specify i/o buffer for reading -TIFFReadDirectory read the next directory -TIFFReadEncodedStrip read and decode a strip of data -TIFFReadEncodedTile read and decode a tile of data -TIFFReadRawStrip read a raw strip of data -TIFFReadRawTile read a raw tile of data -TIFFReadRGBAImage read an image into a fixed format raster -TIFFReadScanline read and decode a row of data -TIFFReadTile read and decode a tile of data -TIFFRegisterCODEC override standard codec for the specific scheme -TIFFReverseBits reverse bits in an array of bytes -TIFFRGBAImageBegin setup decoder state for TIFFRGBAImageGet -TIFFRGBAImageEnd release TIFFRGBAImage decoder state -TIFFRGBAImageGet read and decode an image -TIFFRGBAImageOK is image readable by TIFFRGBAImageGet -TIFFScanlineSize return size of a scanline -TIFFSetDirectory set the current directory -TIFFSetSubDirectory set the current directory -TIFFSetErrorHandler set error handler function -TIFFSetField set a tag's value in the current directory -TIFFSetWarningHandler set warning handler function -TIFFStripSize returns size of a strip -TIFFRawStripSize returns the number of bytes in a raw strip -TIFFSwabShort swap bytes of short -TIFFSwabLong swap bytes of long -TIFFSwabArrayOfShort swap bytes of an array of shorts -TIFFSwabArrayOfLong swap bytes of an array of longs -TIFFTileRowSize return size of a row in a tile -TIFFTileSize return size of a tile -TIFFUnRegisterCODEC unregisters the codec -TIFFVGetField return tag value in current directory -TIFFVGetFieldDefaulted return tag value in current directory -TIFFVSetField set a tag's value in the current directory -TIFFVStripSize returns the number of bytes in a strip -TIFFWarning library warning handler -TIFFWriteDirectory write the current directory -TIFFWriteEncodedStrip compress and write a strip of data -TIFFWriteEncodedTile compress and write a tile of data -TIFFWriteRawStrip write a raw strip of data -TIFFWriteRawTile write a raw tile of data -TIFFWriteScanline write a scanline of data -TIFFWriteTile compress and write a tile of data -TIFFXYZToRGB perform CIE XYZ to RGB conversion -TIFFYCbCrToRGBInit initialize YCbCr to RGB conversion state -TIFFYCbCrtoRGB perform YCbCr to RGB conversion -.sp -Auxiliary functions: -_TIFFfree free memory buffer -_TIFFmalloc dynamically allocate memory buffer -_TIFFmemcmp compare contents of the memory buffers -_TIFFmemcpy copy contents of the one buffer to another -_TIFFmemset fill memory buffer with a constant byte -_TIFFrealloc dynamically reallocate memory buffer - -.fi -.SH "TAG USAGE" -The table below lists the -.SM TIFF -tags that are recognized and handled by the library. -If no use is indicated in the table, then the library -reads and writes the tag, but does not use it internally. -Note that some tags are meaningful only when a particular -compression scheme is being used; e.g. -.I Group3Options -is only useful if -.I Compression -is set to -.SM CCITT -Group 3 encoding. -Tags of this sort are considered -.I codec-specific -tags and the library does not recognize them except when the -.I Compression -tag has been previously set to the relevant compression scheme. -.sp -.nf -.ta \w'TIFFTAG_JPEGTABLESMODE'u+2n +\w'Value'u+2n +\w'R/W'u+2n -\fITag Name\fP \fIValue\fP \fIR/W\fP \fILibrary Use/Notes\fP -.sp 5p -.nf -Artist 315 R/W -BadFaxLines 326 R/W -BitsPerSample 258 R/W lots -CellLength 265 parsed but ignored -CellWidth 264 parsed but ignored -CleanFaxData 327 R/W -ColorMap 320 R/W -ColorResponseUnit 300 parsed but ignored -Compression 259 R/W choosing codec -ConsecutiveBadFaxLines 328 R/W -Copyright 33432 R/W -DataType 32996 R obsoleted by SampleFormat tag -DateTime 306 R/W -DocumentName 269 R/W -DotRange 336 R/W -ExtraSamples 338 R/W lots -FaxRecvParams 34908 R/W -FaxSubAddress 34909 R/W -FaxRecvTime 34910 R/W -FillOrder 266 R/W control bit order -FreeByteCounts 289 parsed but ignored -FreeOffsets 288 parsed but ignored -GrayResponseCurve 291 parsed but ignored -GrayResponseUnit 290 parsed but ignored -Group3Options 292 R/W used by Group 3 codec -Group4Options 293 R/W -HostComputer 316 R/W -ImageDepth 32997 R/W tile/strip calculations -ImageDescription 270 R/W -ImageLength 257 R/W lots -ImageWidth 256 R/W lots -InkNames 333 R/W -InkSet 332 R/W -JPEGTables 347 R/W used by JPEG codec -Make 271 R/W -Matteing 32995 R obsoleted by ExtraSamples tag -MaxSampleValue 281 R/W -MinSampleValue 280 R/W -Model 272 R/W -NewSubFileType 254 R/W called SubFileType in spec -NumberOfInks 334 R/W -Orientation 274 R/W -PageName 285 R/W -PageNumber 297 R/W -PhotometricInterpretation 262 R/W used by Group 3 and JPEG codecs -PlanarConfiguration 284 R/W data i/o -Predictor 317 R/W used by LZW and Deflate codecs -PrimaryChromacities 319 R/W -ReferenceBlackWhite 532 R/W -ResolutionUnit 296 R/W used by Group 3 codec -RowsPerStrip 278 R/W data i/o -SampleFormat 339 R/W -SamplesPerPixel 277 R/W lots -SMinSampleValue 340 R/W -SMaxSampleValue 341 R/W -Software 305 R/W -StoNits 37439 R/W -StripByteCounts 279 R/W data i/o -StripOffsets 273 R/W data i/o -SubFileType 255 R/W called OSubFileType in spec -TargetPrinter 337 R/W -Thresholding 263 R/W -TileByteCounts 324 R/W data i/o -TileDepth 32998 R/W tile/strip calculations -TileLength 323 R/W data i/o -TileOffsets 324 R/W data i/o -TileWidth 322 R/W data i/o -TransferFunction 301 R/W -WhitePoint 318 R/W -XPosition 286 R/W -XResolution 282 R/W -YCbCrCoefficients 529 R/W used by TIFFRGBAImage support -YCbCrPositioning 531 R/W tile/strip size calulcations -YCbCrSubsampling 530 R/W -YPosition 286 R/W -YResolution 283 R/W used by Group 3 codec -.SH "PSEUDO TAGS" -In addition to the normal -.SM TIFF -tags the library supports a collection of -tags whose values lie in a range outside the valid range of -.SM TIFF -tags. -These tags are termed -.I pseud-tags -and are used to control various codec-specific functions within the library. -The table below summarizes the defined pseudo-tags. -.sp -.nf -.ta \w'TIFFTAG_JPEGTABLESMODE'u+2n +\w'Codec'u+2n +\w'R/W'u+2n -\fITag Name\fP \fICodec\fP \fIR/W\fP \fILibrary Use/Notes\fP -.sp 5p -.nf -TIFFTAG_FAXMODE G3 R/W general codec operation -TIFFTAG_FAXFILLFUNC G3/G4 R/W bitmap fill function -TIFFTAG_JPEGQUALITY JPEG R/W compression quality control -TIFFTAG_JPEGCOLORMODE JPEG R/W control colorspace conversions -TIFFTAG_JPEGTABLESMODE JPEG R/W control contents of \fIJPEGTables\fP tag -TIFFTAG_ZIPQUALITY Deflate R/W compression quality level -TIFFTAG_PIXARLOGDATAFMT PixarLog R/W user data format -TIFFTAG_PIXARLOGQUALITY PixarLog R/W compression quality level -TIFFTAG_SGILOGDATAFMT SGILog R/W user data format -.fi -.TP -.B TIFFTAG_FAXMODE -Control the operation of the Group 3 codec. -Possible values (independent bits that can be combined by -or'ing them together) are: -FAXMODE_CLASSIC -(enable old-style format in which the -.SM RTC -is written at the end of the last strip), -FAXMODE_NORTC -(opposite of -FAXMODE_CLASSIC; -also called -FAXMODE_CLASSF), -FAXMODE_NOEOL -(do not write -.SM EOL -codes at the start of each row of data), -FAXMODE_BYTEALIGN -(align each encoded row to an 8-bit boundary), -FAXMODE_WORDALIGN -(align each encoded row to an 16-bit boundary), -The default value is dependent on the compression scheme; this -pseudo-tag is used by the various G3 and G4 codecs to share code. -.TP -.B TIFFTAG_FAXFILLFUNC -Control the function used to convert arrays of black and white -runs to packed bit arrays. -This hook can be used to image decoded scanlines in multi-bit -depth rasters (e.g. for display in colormap mode) -or for other purposes. -The default value is a pointer to a builtin function that images -packed bilevel data. -.TP -.B TIFFTAG_IPTCNEWSPHOTO -Tag contaings image metadata per the IPTC newsphoto spec: Headline, -captioning, credit, etc... Used by most wire services. -.TP -.B TIFFTAG_PHOTOSHOP -Tag contains Photoshop captioning information and metadata. Photoshop -uses in parallel and redundantly alongside IPTCNEWSPHOTO information. -.TP -.B TIFFTAG_JPEGQUALITY -Control the compression quality level used in the baseline algorithm. -Note that quality levels are in the range 0-100 with a default value of 75. -.TP -.B TIFFTAG_JPEGCOLORMODE -Control whether or not conversion is done between -RGB and YCbCr colorspaces. -Possible values are: -JPEGCOLORMODE_RAW -(do not convert), and -JPEGCOLORMODE_RGB -(convert to/from RGB) -The default value is JPEGCOLORMODE_RAW. -.TP -.B TIFFTAG_JPEGTABLESMODE -Control the information written in the -.I JPEGTables -tag. -Possible values (independent bits that can be combined by -or'ing them together) are: -JPEGTABLESMODE_QUANT -(include quantization tables), -and -JPEGTABLESMODE_HUFF -(include Huffman encoding tables). -The default value is JPEGTABLESMODE_QUANT|JPEGTABLESMODE_HUFF. -.TP -.B TIFFTAG_ZIPQUALITY -Control the compression technique used by the Deflate codec. -Quality levels are in the range 1-9 with larger numbers yielding better -compression at the cost of more computation. -The default quality level is 6 which yields a good time-space tradeoff. -.TP -.B TIFFTAG_PIXARLOGDATAFMT -Control the format of user data passed -.I in -to the PixarLog codec when encoding and passed -.I out -from when decoding. -Possible values are: -PIXARLOGDATAFMT_8BIT -for 8-bit unsigned pixels, -PIXARLOGDATAFMT_8BITABGR -for 8-bit unsigned ABGR-ordered pixels, -PIXARLOGDATAFMT_11BITLOG -for 11-bit log-encoded raw data, -PIXARLOGDATAFMT_12BITPICIO -for 12-bit PICIO-compatible data, -PIXARLOGDATAFMT_16BIT -for 16-bit signed samples, -and -PIXARLOGDATAFMT_FLOAT -for 32-bit IEEE floating point samples. -.TP -.B TIFFTAG_PIXARLOGQUALITY -Control the compression technique used by the PixarLog codec. -This value is treated identically to TIFFTAG_ZIPQUALITY; see the -above description. -.TP -.B TIFFTAG_SGILOGDATAFMT -Control the format of client data passed -.I in -to the SGILog codec when encoding and passed -.I out -from when decoding. -Possible values are: -SGILOGDATAFMT_FLTXYZ -for converting between LogLuv and 32-bit IEEE floating valued XYZ pixels, -SGILOGDATAFMT_16BITLUV -for 16-bit encoded Luv pixels, -SGILOGDATAFMT_32BITRAW and SGILOGDATAFMT_24BITRAW -for no conversion of data, -SGILOGDATAFMT_8BITRGB -for returning 8-bit RGB data (valid only when decoding LogLuv-encoded data), -SGILOGDATAFMT_FLTY -for converting between LogL and 32-bit IEEE floating valued Y pixels, -SGILOGDATAFMT_16BITL -for 16-bit encoded L pixels, -and -SGILOGDATAFMT_8BITGRY -for returning 8-bit greyscale data -(valid only when decoding LogL-encoded data). -.SH DIAGNOSTICS -All error messages are directed through the -.IR TIFFError -routine. -By default messages are directed to -.B stderr -in the form: -.IR "module: message\en." -Warning messages are likewise directed through the -.IR TIFFWarning -routine. -.SH "SEE ALSO" -.BR fax2tiff (1), -.BR gif2tiff (1), -.BR pal2rgb (1), -.BR ppm2tiff (1), -.BR rgb2ycbcr (1), -.BR ras2tiff (1), -.BR raw2tiff (1), -.BR sgi2tiff (1), -.BR tiff2bw (1), -.BR tiffdither (1), -.BR tiffdump (1), -.BR tiffcp (1), -.BR tiffcmp (1), -.BR tiffgt (1), -.BR tiffinfo (1), -.BR tiffmedian (1), -.BR tiffsplit (1), -.BR tiffsv (1). -.PP -.BR "Tag Image File Format Specification \(em Revision 6.0" , -an Aldus Technical Memorandum. -.PP -.BR "The Spirit of TIFF Class F" , -an appendix to the TIFF 5.0 specification prepared by Cygnet Technologies. -.PP -Libtiff library home page: -.BR http://www.remotesensing.org/libtiff/ -.SH BUGS -The library does not support multi-sample images -where some samples have different bits/sample. -.PP -The library does not support random access to compressed data -that is organized with more than one row per tile or strip. diff --git a/gtk+-mingw/share/man/man3/libxml.3 b/gtk+-mingw/share/man/man3/libxml.3 deleted file mode 100644 index 88d3eee..0000000 --- a/gtk+-mingw/share/man/man3/libxml.3 +++ /dev/null @@ -1,71 +0,0 @@ -.TH libxml 3 "12 April 2000" -.SH NAME -libxml \- library used to parse XML files -.SH DESCRIPTION -The -.I libxml -library is used to parse XML files. -Its internal document repesentation is as close as possible to the -.I DOM -(Document Object Model) interface, -an API for accessing XML or HTML structured documents. -.LP -The -.I libxml -library also has a -.IR SAX -like -interface, -which is designed to be compatible with -.IR expat (1). -NOTE: -.IR SAX , -the Simple API for XML, -is a standard interface for event-based XML parsing, -developed collaboratively by the members of the XML-DEV mailing list, -currently hosted by OASIS. -The -.I expat -library is a XML 1.0 parser written in C, -which aims to be fully conforming. -It is currently not a validating XML processor. -.LP -The -.I libxml -library now includes a nearly complete -.I XPath -implementation. -The -.I XPath -(XML Path Language) is a language for addressing parts of an -XML document, -designed to be used by both -.I XSLT -and -.IR XPointer . -.LP -The -.I libxml -library exports Push and Pull type parser interfaces for both XML and -.IR html . -.SH FILES -.TP 2.2i -.B /depot/lib/libxml_2.0.0/libxml.a -static library -.TP -.B /depot/lib/libxml_2.0.0/libxml.so -shared library -.TP -.B /depot/package/libxml_2.0.0/bin/xmllint -binary application for parsing XML files -.SH AUTHORS -Daniel Veillard (daniel@veillard.com). -Red Hat Inc. -Manual page by Ziying Sherwin (sherwin@nlm.nih.gov), -Lister Hill National Center for Biomedical Communications, -U.S. National Library of Medicine. -.SH SEE ALSO -.IR xmllint (1), -.IR libxslt (3), -.IR libexslt (3), -.IR xsltproc (1) -.\" end of manual page diff --git a/gtk+-mingw/share/man/man3/ngettext.3 b/gtk+-mingw/share/man/man3/ngettext.3 deleted file mode 100644 index ebff89b..0000000 --- a/gtk+-mingw/share/man/man3/ngettext.3 +++ /dev/null @@ -1,60 +0,0 @@ -.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 2 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" GNU glibc-2 source code and manual -.\" GNU gettext source code and manual -.\" LI18NUX 2000 Globalization Specification -.\" -.TH NGETTEXT 3 "May 2001" "GNU gettext 0.18.1" -.SH NAME -ngettext, dngettext, dcngettext \- translate message and choose plural form -.SH SYNOPSIS -.nf -.B #include <libintl.h> -.sp -.BI "char * ngettext (const char * " msgid ", const char * " msgid_plural , -.BI " unsigned long int " n ); -.BI "char * dngettext (const char * " domainname , -.BI " const char * " msgid ", const char * " msgid_plural , -.BI " unsigned long int " n ); -.BI "char * dcngettext (const char * " domainname , -.BI " const char * " msgid ", const char * " msgid_plural , -.BI " unsigned long int " n ", int " category ); -.fi -.SH DESCRIPTION -The \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions attempt to -translate a text string into the user's native language, by looking up the -appropriate plural form of the translation in a message catalog. -.PP -Plural forms are grammatical variants depending on the a number. Some languages -have two forms, called singular and plural. Other languages have three forms, -called singular, dual and plural. There are also languages with four forms. -.PP -The \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions work like -the \fBgettext\fP, \fBdgettext\fP and \fBdcgettext\fP functions, respectively. -Additionally, they choose the appropriate plural form, which depends on the -number \fIn\fP and the language of the message catalog where the translation -was found. -.PP -In the "C" locale, or if none of the used catalogs contain a translation for -\fImsgid\fP, the \fBngettext\fP, \fBdngettext\fP and \fBdcngettext\fP functions -return \fImsgid\fP if \fIn\fP == 1, or \fImsgid_plural\fP if \fIn\fP != 1. -.SH "RETURN VALUE" -If a translation was found in one of the specified catalogs, the appropriate -plural form is converted to the locale's codeset and returned. The resulting -string is statically allocated and must not be modified or freed. Otherwise -\fImsgid\fP or \fImsgid_plural\fP is returned, as described above. -.SH ERRORS -\fBerrno\fP is not modified. -.SH BUGS -The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid -warnings in C code predating ANSI C. -.SH "SEE ALSO" -.BR gettext (3), -.BR dgettext (3), -.BR dcgettext (3) diff --git a/gtk+-mingw/share/man/man3/pcre.3 b/gtk+-mingw/share/man/man3/pcre.3 deleted file mode 100644 index bb0d57c..0000000 --- a/gtk+-mingw/share/man/man3/pcre.3 +++ /dev/null @@ -1,158 +0,0 @@ -.TH PCRE 3 "10 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH INTRODUCTION -.rs -.sp -The PCRE library is a set of functions that implement regular expression -pattern matching using the same syntax and semantics as Perl, with just a few -differences. Some features that appeared in Python and PCRE before they -appeared in Perl are also available using the Python syntax, there is some -support for one or two .NET and Oniguruma syntax items, and there is an option -for requesting some minor changes that give better JavaScript compatibility. -.P -Starting with release 8.30, it is possible to compile two separate PCRE -libraries: the original, which supports 8-bit character strings (including -UTF-8 strings), and a second library that supports 16-bit character strings -(including UTF-16 strings). The build process allows either one or both to be -built. The majority of the work to make this possible was done by Zoltan -Herczeg. -.P -The two libraries contain identical sets of functions, except that the names in -the 16-bit library start with \fBpcre16_\fP instead of \fBpcre_\fP. To avoid -over-complication and reduce the documentation maintenance load, most of the -documentation describes the 8-bit library, with the differences for the 16-bit -library described separately in the -.\" HREF -\fBpcre16\fP -.\" -page. References to functions or structures of the form \fIpcre[16]_xxx\fP -should be read as meaning "\fIpcre_xxx\fP when using the 8-bit library and -\fIpcre16_xxx\fP when using the 16-bit library". -.P -The current implementation of PCRE corresponds approximately with Perl 5.12, -including support for UTF-8/16 encoded strings and Unicode general category -properties. However, UTF-8/16 and Unicode support has to be explicitly enabled; -it is not the default. The Unicode tables correspond to Unicode release 6.0.0. -.P -In addition to the Perl-compatible matching function, PCRE contains an -alternative function that matches the same compiled patterns in a different -way. In certain circumstances, the alternative function has some advantages. -For a discussion of the two matching algorithms, see the -.\" HREF -\fBpcrematching\fP -.\" -page. -.P -PCRE is written in C and released as a C library. A number of people have -written wrappers and interfaces of various kinds. In particular, Google Inc. -have provided a comprehensive C++ wrapper for the 8-bit library. This is now -included as part of the PCRE distribution. The -.\" HREF -\fBpcrecpp\fP -.\" -page has details of this interface. Other people's contributions can be found -in the \fIContrib\fP directory at the primary FTP site, which is: -.sp -.\" HTML <a href="ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre"> -.\" </a> -ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre -.P -Details of exactly which Perl regular expression features are and are not -supported by PCRE are given in separate documents. See the -.\" HREF -\fBpcrepattern\fP -.\" -and -.\" HREF -\fBpcrecompat\fP -.\" -pages. There is a syntax summary in the -.\" HREF -\fBpcresyntax\fP -.\" -page. -.P -Some features of PCRE can be included, excluded, or changed when the library is -built. The -.\" HREF -\fBpcre_config()\fP -.\" -function makes it possible for a client to discover which features are -available. The features themselves are described in the -.\" HREF -\fBpcrebuild\fP -.\" -page. Documentation about building PCRE for various operating systems can be -found in the \fBREADME\fP and \fBNON-UNIX-USE\fP files in the source -distribution. -.P -The libraries contains a number of undocumented internal functions and data -tables that are used by more than one of the exported external functions, but -which are not intended for use by external callers. Their names all begin with -"_pcre_" or "_pcre16_", which hopefully will not provoke any name clashes. In -some environments, it is possible to control which external symbols are -exported when a shared library is built, and in these cases the undocumented -symbols are not exported. -. -. -.SH "USER DOCUMENTATION" -.rs -.sp -The user documentation for PCRE comprises a number of different sections. In -the "man" format, each of these is a separate "man page". In the HTML format, -each is a separate page, linked from the index page. In the plain text format, -all the sections, except the \fBpcredemo\fP section, are concatenated, for ease -of searching. The sections are as follows: -.sp - pcre this document - pcre16 details of the 16-bit library - pcre-config show PCRE installation configuration information - pcreapi details of PCRE's native C API - pcrebuild options for building PCRE - pcrecallout details of the callout feature - pcrecompat discussion of Perl compatibility - pcrecpp details of the C++ wrapper for the 8-bit library - pcredemo a demonstration C program that uses PCRE - pcregrep description of the \fBpcregrep\fP command (8-bit only) - pcrejit discussion of the just-in-time optimization support - pcrelimits details of size and other limits - pcrematching discussion of the two matching algorithms - pcrepartial details of the partial matching facility -.\" JOIN - pcrepattern syntax and semantics of supported - regular expressions - pcreperform discussion of performance issues - pcreposix the POSIX-compatible C API for the 8-bit library - pcreprecompile details of saving and re-using precompiled patterns - pcresample discussion of the pcredemo program - pcrestack discussion of stack usage - pcresyntax quick syntax reference - pcretest description of the \fBpcretest\fP testing command - pcreunicode discussion of Unicode and UTF-8/16 support -.sp -In addition, in the "man" and HTML formats, there is a short page for each -8-bit C library function, listing its arguments and results. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -.P -Putting an actual email address here seems to have been a spam magnet, so I've -taken it away. If you want to email me, use my two initials, followed by the -two digits 10, at the domain cam.ac.uk. -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 10 January 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcre16.3 b/gtk+-mingw/share/man/man3/pcre16.3 deleted file mode 100644 index 7b97099..0000000 --- a/gtk+-mingw/share/man/man3/pcre16.3 +++ /dev/null @@ -1,389 +0,0 @@ -.TH PCRE 3 "14 April 2012" "PCRE 8.31" -.SH NAME -PCRE - Perl-compatible regular expressions -.sp -.B #include <pcre.h> -. -. -.SH "PCRE 16-BIT API BASIC FUNCTIONS" -.rs -.sp -.SM -.B pcre16 *pcre16_compile(PCRE_SPTR16 \fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.PP -.B pcre16 *pcre16_compile2(PCRE_SPTR16 \fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B int *\fIerrorcodeptr\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.PP -.B pcre16_extra *pcre16_study(const pcre16 *\fIcode\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP); -.PP -.B void pcre16_free_study(pcre16_extra *\fIextra\fP); -.PP -.B int pcre16_exec(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP," -.ti +5n -.B "PCRE_SPTR16 \fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP); -.PP -.B int pcre16_dfa_exec(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP," -.ti +5n -.B "PCRE_SPTR16 \fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP, -.ti +5n -.B int *\fIworkspace\fP, int \fIwscount\fP); -. -. -.SH "PCRE 16-BIT API STRING EXTRACTION FUNCTIONS" -.rs -.sp -.B int pcre16_copy_named_substring(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, PCRE_SPTR16 \fIstringname\fP, -.ti +5n -.B PCRE_UCHAR16 *\fIbuffer\fP, int \fIbuffersize\fP); -.PP -.B int pcre16_copy_substring(PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, PCRE_UCHAR16 *\fIbuffer\fP, -.ti +5n -.B int \fIbuffersize\fP); -.PP -.B int pcre16_get_named_substring(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, PCRE_SPTR16 \fIstringname\fP, -.ti +5n -.B PCRE_SPTR16 *\fIstringptr\fP); -.PP -.B int pcre16_get_stringnumber(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIname\fP); -.PP -.B int pcre16_get_stringtable_entries(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIname\fP, PCRE_UCHAR16 **\fIfirst\fP, PCRE_UCHAR16 **\fIlast\fP); -.PP -.B int pcre16_get_substring(PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, -.ti +5n -.B PCRE_SPTR16 *\fIstringptr\fP); -.PP -.B int pcre16_get_substring_list(PCRE_SPTR16 \fIsubject\fP, -.ti +5n -.B int *\fIovector\fP, int \fIstringcount\fP, "PCRE_SPTR16 **\fIlistptr\fP);" -.PP -.B void pcre16_free_substring(PCRE_SPTR16 \fIstringptr\fP); -.PP -.B void pcre16_free_substring_list(PCRE_SPTR16 *\fIstringptr\fP); -. -. -.SH "PCRE 16-BIT API AUXILIARY FUNCTIONS" -.rs -.sp -.B pcre16_jit_stack *pcre16_jit_stack_alloc(int \fIstartsize\fP, int \fImaxsize\fP); -.PP -.B void pcre16_jit_stack_free(pcre16_jit_stack *\fIstack\fP); -.PP -.B void pcre16_assign_jit_stack(pcre16_extra *\fIextra\fP, -.ti +5n -.B pcre16_jit_callback \fIcallback\fP, void *\fIdata\fP); -.PP -.B const unsigned char *pcre16_maketables(void); -.PP -.B int pcre16_fullinfo(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP," -.ti +5n -.B int \fIwhat\fP, void *\fIwhere\fP); -.PP -.B int pcre16_refcount(pcre16 *\fIcode\fP, int \fIadjust\fP); -.PP -.B int pcre16_config(int \fIwhat\fP, void *\fIwhere\fP); -.PP -.B const char *pcre16_version(void); -.PP -.B int pcre16_pattern_to_host_byte_order(pcre16 *\fIcode\fP, -.ti +5n -.B pcre16_extra *\fIextra\fP, const unsigned char *\fItables\fP); -. -. -.SH "PCRE 16-BIT API INDIRECTED FUNCTIONS" -.rs -.sp -.B void *(*pcre16_malloc)(size_t); -.PP -.B void (*pcre16_free)(void *); -.PP -.B void *(*pcre16_stack_malloc)(size_t); -.PP -.B void (*pcre16_stack_free)(void *); -.PP -.B int (*pcre16_callout)(pcre16_callout_block *); -. -. -.SH "PCRE 16-BIT API 16-BIT-ONLY FUNCTION" -.rs -.sp -.B int pcre16_utf16_to_host_byte_order(PCRE_UCHAR16 *\fIoutput\fP, -.ti +5n -.B PCRE_SPTR16 \fIinput\fP, int \fIlength\fP, int *\fIbyte_order\fP, -.ti +5n -.B int \fIkeep_boms\fP); -. -. -.SH "THE PCRE 16-BIT LIBRARY" -.rs -.sp -Starting with release 8.30, it is possible to compile a PCRE library that -supports 16-bit character strings, including UTF-16 strings, as well as or -instead of the original 8-bit library. The majority of the work to make this -possible was done by Zoltan Herczeg. The two libraries contain identical sets -of functions, used in exactly the same way. Only the names of the functions and -the data types of their arguments and results are different. To avoid -over-complication and reduce the documentation maintenance load, most of the -PCRE documentation describes the 8-bit library, with only occasional references -to the 16-bit library. This page describes what is different when you use the -16-bit library. -.P -WARNING: A single application can be linked with both libraries, but you must -take care when processing any particular pattern to use functions from just one -library. For example, if you want to study a pattern that was compiled with -\fBpcre16_compile()\fP, you must do so with \fBpcre16_study()\fP, not -\fBpcre_study()\fP, and you must free the study data with -\fBpcre16_free_study()\fP. -. -. -.SH "THE HEADER FILE" -.rs -.sp -There is only one header file, \fBpcre.h\fP. It contains prototypes for all the -functions in both libraries, as well as definitions of flags, structures, error -codes, etc. -. -. -.SH "THE LIBRARY NAME" -.rs -.sp -In Unix-like systems, the 16-bit library is called \fBlibpcre16\fP, and can -normally be accesss by adding \fB-lpcre16\fP to the command for linking an -application that uses PCRE. -. -. -.SH "STRING TYPES" -.rs -.sp -In the 8-bit library, strings are passed to PCRE library functions as vectors -of bytes with the C type "char *". In the 16-bit library, strings are passed as -vectors of unsigned 16-bit quantities. The macro PCRE_UCHAR16 specifies an -appropriate data type, and PCRE_SPTR16 is defined as "const PCRE_UCHAR16 *". In -very many environments, "short int" is a 16-bit data type. When PCRE is built, -it defines PCRE_UCHAR16 as "short int", but checks that it really is a 16-bit -data type. If it is not, the build fails with an error message telling the -maintainer to modify the definition appropriately. -. -. -.SH "STRUCTURE TYPES" -.rs -.sp -The types of the opaque structures that are used for compiled 16-bit patterns -and JIT stacks are \fBpcre16\fP and \fBpcre16_jit_stack\fP respectively. The -type of the user-accessible structure that is returned by \fBpcre16_study()\fP -is \fBpcre16_extra\fP, and the type of the structure that is used for passing -data to a callout function is \fBpcre16_callout_block\fP. These structures -contain the same fields, with the same names, as their 8-bit counterparts. The -only difference is that pointers to character strings are 16-bit instead of -8-bit types. -. -. -.SH "16-BIT FUNCTIONS" -.rs -.sp -For every function in the 8-bit library there is a corresponding function in -the 16-bit library with a name that starts with \fBpcre16_\fP instead of -\fBpcre_\fP. The prototypes are listed above. In addition, there is one extra -function, \fBpcre16_utf16_to_host_byte_order()\fP. This is a utility function -that converts a UTF-16 character string to host byte order if necessary. The -other 16-bit functions expect the strings they are passed to be in host byte -order. -.P -The \fIinput\fP and \fIoutput\fP arguments of -\fBpcre16_utf16_to_host_byte_order()\fP may point to the same address, that is, -conversion in place is supported. The output buffer must be at least as long as -the input. -.P -The \fIlength\fP argument specifies the number of 16-bit data units in the -input string; a negative value specifies a zero-terminated string. -.P -If \fIbyte_order\fP is NULL, it is assumed that the string starts off in host -byte order. This may be changed by byte-order marks (BOMs) anywhere in the -string (commonly as the first character). -.P -If \fIbyte_order\fP is not NULL, a non-zero value of the integer to which it -points means that the input starts off in host byte order, otherwise the -opposite order is assumed. Again, BOMs in the string can change this. The final -byte order is passed back at the end of processing. -.P -If \fIkeep_boms\fP is not zero, byte-order mark characters (0xfeff) are copied -into the output string. Otherwise they are discarded. -.P -The result of the function is the number of 16-bit units placed into the output -buffer, including the zero terminator if the string was zero-terminated. -. -. -.SH "SUBJECT STRING OFFSETS" -.rs -.sp -The offsets within subject strings that are returned by the matching functions -are in 16-bit units rather than bytes. -. -. -.SH "NAMED SUBPATTERNS" -.rs -.sp -The name-to-number translation table that is maintained for named subpatterns -uses 16-bit characters. The \fBpcre16_get_stringtable_entries()\fP function -returns the length of each entry in the table as the number of 16-bit data -units. -. -. -.SH "OPTION NAMES" -.rs -.sp -There are two new general option names, PCRE_UTF16 and PCRE_NO_UTF16_CHECK, -which correspond to PCRE_UTF8 and PCRE_NO_UTF8_CHECK in the 8-bit library. In -fact, these new options define the same bits in the options word. There is a -discussion about the -.\" HTML <a href="pcreunicode.html#utf16strings"> -.\" </a> -validity of UTF-16 strings -.\" -in the -.\" HREF -\fBpcreunicode\fP -.\" -page. -.P -For the \fBpcre16_config()\fP function there is an option PCRE_CONFIG_UTF16 -that returns 1 if UTF-16 support is configured, otherwise 0. If this option is -given to \fBpcre_config()\fP, or if the PCRE_CONFIG_UTF8 option is given to -\fBpcre16_config()\fP, the result is the PCRE_ERROR_BADOPTION error. -. -. -.SH "CHARACTER CODES" -.rs -.sp -In 16-bit mode, when PCRE_UTF16 is not set, character values are treated in the -same way as in 8-bit, non UTF-8 mode, except, of course, that they can range -from 0 to 0xffff instead of 0 to 0xff. Character types for characters less than -0xff can therefore be influenced by the locale in the same way as before. -Characters greater than 0xff have only one case, and no "type" (such as letter -or digit). -.P -In UTF-16 mode, the character code is Unicode, in the range 0 to 0x10ffff, with -the exception of values in the range 0xd800 to 0xdfff because those are -"surrogate" values that are used in pairs to encode values greater than 0xffff. -.P -A UTF-16 string can indicate its endianness by special code knows as a -byte-order mark (BOM). The PCRE functions do not handle this, expecting strings -to be in host byte order. A utility function called -\fBpcre16_utf16_to_host_byte_order()\fP is provided to help with this (see -above). -. -. -.SH "ERROR NAMES" -.rs -.sp -The errors PCRE_ERROR_BADUTF16_OFFSET and PCRE_ERROR_SHORTUTF16 correspond to -their 8-bit counterparts. The error PCRE_ERROR_BADMODE is given when a compiled -pattern is passed to a function that processes patterns in the other -mode, for example, if a pattern compiled with \fBpcre_compile()\fP is passed to -\fBpcre16_exec()\fP. -.P -There are new error codes whose names begin with PCRE_UTF16_ERR for invalid -UTF-16 strings, corresponding to the PCRE_UTF8_ERR codes for UTF-8 strings that -are described in the section entitled -.\" HTML <a href="pcreapi.html#badutf8reasons"> -.\" </a> -"Reason codes for invalid UTF-8 strings" -.\" -in the main -.\" HREF -\fBpcreapi\fP -.\" -page. The UTF-16 errors are: -.sp - PCRE_UTF16_ERR1 Missing low surrogate at end of string - PCRE_UTF16_ERR2 Invalid low surrogate follows high surrogate - PCRE_UTF16_ERR3 Isolated low surrogate - PCRE_UTF16_ERR4 Invalid character 0xfffe -. -. -.SH "ERROR TEXTS" -.rs -.sp -If there is an error while compiling a pattern, the error text that is passed -back by \fBpcre16_compile()\fP or \fBpcre16_compile2()\fP is still an 8-bit -character string, zero-terminated. -. -. -.SH "CALLOUTS" -.rs -.sp -The \fIsubject\fP and \fImark\fP fields in the callout block that is passed to -a callout function point to 16-bit vectors. -. -. -.SH "TESTING" -.rs -.sp -The \fBpcretest\fP program continues to operate with 8-bit input and output -files, but it can be used for testing the 16-bit library. If it is run with the -command line option \fB-16\fP, patterns and subject strings are converted from -8-bit to 16-bit before being passed to PCRE, and the 16-bit library functions -are used instead of the 8-bit ones. Returned 16-bit strings are converted to -8-bit for output. If the 8-bit library was not compiled, \fBpcretest\fP -defaults to 16-bit and the \fB-16\fP option is ignored. -.P -When PCRE is being built, the \fBRunTest\fP script that is called by "make -check" uses the \fBpcretest\fP \fB-C\fP option to discover which of the 8-bit -and 16-bit libraries has been built, and runs the tests appropriately. -. -. -.SH "NOT SUPPORTED IN 16-BIT MODE" -.rs -.sp -Not all the features of the 8-bit library are available with the 16-bit -library. The C++ and POSIX wrapper functions support only the 8-bit library, -and the \fBpcregrep\fP program is at present 8-bit only. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 14 April 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcre16_assign_jit_stack.3 b/gtk+-mingw/share/man/man3/pcre16_assign_jit_stack.3 deleted file mode 100644 index fc32dda..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_assign_jit_stack.3 +++ /dev/null @@ -1,57 +0,0 @@ -.TH PCRE_ASSIGN_JIT_STACK 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_assign_jit_stack(pcre_extra *\fIextra\fP, -.ti +5n -.B pcre_jit_callback \fIcallback\fP, void *\fIdata\fP); -.PP -.B void pcre16_assign_jit_stack(pcre16_extra *\fIextra\fP, -.ti +5n -.B pcre16_jit_callback \fIcallback\fP, void *\fIdata\fP); -. -.SH DESCRIPTION -.rs -.sp -This function provides control over the memory used as a stack at run-time by a -call to \fBpcre[16]_exec()\fP with a pattern that has been successfully -compiled with JIT optimization. The arguments are: -.sp - extra the data pointer returned by \fBpcre[16]_study()\fP - callback a callback function - data a JIT stack or a value to be passed to the callback - function -.P -If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32K block on -the machine stack is used. -.P -If \fIcallback\fP is NULL and \fIdata\fP is not NULL, \fIdata\fP must -be a valid JIT stack, the result of calling \fBpcre[16]_jit_stack_alloc()\fP. -.P -If \fIcallback\fP not NULL, it is called with \fIdata\fP as an argument at -the start of matching, in order to set up a JIT stack. If the result is NULL, -the internal 32K stack is used; otherwise the return value must be a valid JIT -stack, the result of calling \fBpcre[16]_jit_stack_alloc()\fP. -.P -You may safely assign the same JIT stack to multiple patterns, as long as they -are all matched in the same thread. In a multithread application, each thread -must use its own JIT stack. For more details, see the -.\" HREF -\fBpcrejit\fP -.\" -page. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_compile.3 b/gtk+-mingw/share/man/man3/pcre16_compile.3 deleted file mode 100644 index c38c251..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_compile.3 +++ /dev/null @@ -1,88 +0,0 @@ -.TH PCRE_COMPILE 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.PP -.B pcre16 *pcre16_compile(PCRE_SPTR16 \fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This function compiles a regular expression into an internal form. It is the -same as \fBpcre[16]_compile2()\fP, except for the absence of the -\fIerrorcodeptr\fP argument. Its arguments are: -.sp - \fIpattern\fP A zero-terminated string containing the - regular expression to be compiled - \fIoptions\fP Zero or more option bits - \fIerrptr\fP Where to put an error message - \fIerroffset\fP Offset in pattern where error was found - \fItableptr\fP Pointer to character tables, or NULL to - use the built-in default -.sp -The option bits are: -.sp - PCRE_ANCHORED Force pattern anchoring - PCRE_AUTO_CALLOUT Compile automatic callouts - PCRE_BSR_ANYCRLF \eR matches only CR, LF, or CRLF - PCRE_BSR_UNICODE \eR matches all Unicode line endings - PCRE_CASELESS Do caseless matching - PCRE_DOLLAR_ENDONLY $ not to match newline at end - PCRE_DOTALL . matches anything including NL - PCRE_DUPNAMES Allow duplicate names for subpatterns - PCRE_EXTENDED Ignore white space and # comments - PCRE_EXTRA PCRE extra features - (not much use currently) - PCRE_FIRSTLINE Force matching to be before newline - PCRE_JAVASCRIPT_COMPAT JavaScript compatibility - PCRE_MULTILINE ^ and $ match newlines within data - PCRE_NEWLINE_ANY Recognize any Unicode newline sequence - PCRE_NEWLINE_ANYCRLF Recognize CR, LF, and CRLF as newline - sequences - PCRE_NEWLINE_CR Set CR as the newline sequence - PCRE_NEWLINE_CRLF Set CRLF as the newline sequence - PCRE_NEWLINE_LF Set LF as the newline sequence - PCRE_NO_AUTO_CAPTURE Disable numbered capturing paren- - theses (named ones available) - PCRE_NO_UTF16_CHECK Do not check the pattern for UTF-16 - validity (only relevant if - PCRE_UTF16 is set) - PCRE_NO_UTF8_CHECK Do not check the pattern for UTF-8 - validity (only relevant if - PCRE_UTF8 is set) - PCRE_UCP Use Unicode properties for \ed, \ew, etc. - PCRE_UNGREEDY Invert greediness of quantifiers - PCRE_UTF16 Run in \fBpcre16_compile()\fP UTF-16 mode - PCRE_UTF8 Run in \fBpcre_compile()\fP UTF-8 mode -.sp -PCRE must be built with UTF support in order to use PCRE_UTF8/16 and -PCRE_NO_UTF8/16_CHECK, and with UCP support if PCRE_UCP is used. -.P -The yield of the function is a pointer to a private data structure that -contains the compiled pattern, or NULL if an error was detected. Note that -compiling regular expressions with one version of PCRE for use with a different -version is not guaranteed to work and may cause crashes. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_compile2.3 b/gtk+-mingw/share/man/man3/pcre16_compile2.3 deleted file mode 100644 index 58b8a14..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_compile2.3 +++ /dev/null @@ -1,94 +0,0 @@ -.TH PCRE_COMPILE2 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B int *\fIerrorcodeptr\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.PP -.B pcre16 *pcre16_compile2(PCRE_SPTR16 \fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B int *\fIerrorcodeptr\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This function compiles a regular expression into an internal form. It is the -same as \fBpcre[16]_compile()\fP, except for the addition of the -\fIerrorcodeptr\fP argument. The arguments are: -. -.sp - \fIpattern\fP A zero-terminated string containing the - regular expression to be compiled - \fIoptions\fP Zero or more option bits - \fIerrorcodeptr\fP Where to put an error code - \fIerrptr\fP Where to put an error message - \fIerroffset\fP Offset in pattern where error was found - \fItableptr\fP Pointer to character tables, or NULL to - use the built-in default -.sp -The option bits are: -.sp - PCRE_ANCHORED Force pattern anchoring - PCRE_AUTO_CALLOUT Compile automatic callouts - PCRE_BSR_ANYCRLF \eR matches only CR, LF, or CRLF - PCRE_BSR_UNICODE \eR matches all Unicode line endings - PCRE_CASELESS Do caseless matching - PCRE_DOLLAR_ENDONLY $ not to match newline at end - PCRE_DOTALL . matches anything including NL - PCRE_DUPNAMES Allow duplicate names for subpatterns - PCRE_EXTENDED Ignore white space and # comments - PCRE_EXTRA PCRE extra features - (not much use currently) - PCRE_FIRSTLINE Force matching to be before newline - PCRE_JAVASCRIPT_COMPAT JavaScript compatibility - PCRE_MULTILINE ^ and $ match newlines within data - PCRE_NEWLINE_ANY Recognize any Unicode newline sequence - PCRE_NEWLINE_ANYCRLF Recognize CR, LF, and CRLF as newline - sequences - PCRE_NEWLINE_CR Set CR as the newline sequence - PCRE_NEWLINE_CRLF Set CRLF as the newline sequence - PCRE_NEWLINE_LF Set LF as the newline sequence - PCRE_NO_AUTO_CAPTURE Disable numbered capturing paren- - theses (named ones available) - PCRE_NO_UTF16_CHECK Do not check the pattern for UTF-16 - validity (only relevant if - PCRE_UTF16 is set) - PCRE_NO_UTF8_CHECK Do not check the pattern for UTF-8 - validity (only relevant if - PCRE_UTF8 is set) - PCRE_UCP Use Unicode properties for \ed, \ew, etc. - PCRE_UNGREEDY Invert greediness of quantifiers - PCRE_UTF16 Run \fBpcre16_compile()\fP in UTF-16 mode - PCRE_UTF8 Run \fBpcre_compile()\fP in UTF-8 mode -.sp -PCRE must be built with UTF support in order to use PCRE_UTF8/16 and -PCRE_NO_UTF8/16_CHECK, and with UCP support if PCRE_UCP is used. -.P -The yield of the function is a pointer to a private data structure that -contains the compiled pattern, or NULL if an error was detected. Note that -compiling regular expressions with one version of PCRE for use with a different -version is not guaranteed to work and may cause crashes. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_config.3 b/gtk+-mingw/share/man/man3/pcre16_config.3 deleted file mode 100644 index 45013a4..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_config.3 +++ /dev/null @@ -1,70 +0,0 @@ -.TH PCRE_CONFIG 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP); -.PP -.B int pcre16_config(int \fIwhat\fP, void *\fIwhere\fP); -. -.SH DESCRIPTION -.rs -.sp -This function makes it possible for a client program to find out which optional -features are available in the version of the PCRE library it is using. The -arguments are as follows: -.sp - \fIwhat\fP A code specifying what information is required - \fIwhere\fP Points to where to put the data -.sp -The \fIwhere\fP argument must point to an integer variable, except for -PCRE_CONFIG_MATCH_LIMIT and PCRE_CONFIG_MATCH_LIMIT_RECURSION, when it must -point to an unsigned long integer. The available codes are: -.sp - PCRE_CONFIG_JIT Availability of just-in-time compiler - support (1=yes 0=no) - PCRE_CONFIG_JITTARGET String containing information about the - target architecture for the JIT compiler, - or NULL if there is no JIT support - PCRE_CONFIG_LINK_SIZE Internal link size: 2, 3, or 4 - PCRE_CONFIG_MATCH_LIMIT Internal resource limit - PCRE_CONFIG_MATCH_LIMIT_RECURSION - Internal recursion depth limit - PCRE_CONFIG_NEWLINE Value of the default newline sequence: - 13 (0x000d) for CR - 10 (0x000a) for LF - 3338 (0x0d0a) for CRLF - -2 for ANYCRLF - -1 for ANY - PCRE_CONFIG_BSR Indicates what \eR matches by default: - 0 all Unicode line endings - 1 CR, LF, or CRLF only - PCRE_CONFIG_POSIX_MALLOC_THRESHOLD - Threshold of return slots, above which - \fBmalloc()\fP is used by the POSIX API - PCRE_CONFIG_STACKRECURSE Recursion implementation (1=stack 0=heap) - PCRE_CONFIG_UTF16 Availability of UTF-16 support (1=yes - 0=no); option for \fBpcre16_config()\fP - PCRE_CONFIG_UTF8 Availability of UTF-8 support (1=yes 0=no); - option for \fBpcre_config()\fP - PCRE_CONFIG_UNICODE_PROPERTIES - Availability of Unicode property support - (1=yes 0=no) -.sp -The function yields 0 on success or PCRE_ERROR_BADOPTION otherwise. That error -is also given if PCRE_CONFIG_UTF16 is passed to \fBpcre_config()\fP or if -PCRE_CONFIG_UTF8 is passed to \fBpcre16_config()\fP. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_copy_named_substring.3 b/gtk+-mingw/share/man/man3/pcre16_copy_named_substring.3 deleted file mode 100644 index 9838816..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_copy_named_substring.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH PCRE_COPY_NAMED_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_copy_named_substring(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, const char *\fIstringname\fP, -.ti +5n -.B char *\fIbuffer\fP, int \fIbuffersize\fP); -.PP -.B int pcre16_copy_named_substring(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, PCRE_SPTR16 \fIstringname\fP, -.ti +5n -.B PCRE_UCHAR16 *\fIbuffer\fP, int \fIbuffersize\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a captured substring, identified -by name, into a given buffer. The arguments are: -.sp - \fIcode\fP Pattern that was successfully matched - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec()\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec()\fP - \fIstringname\fP Name of the required substring - \fIbuffer\fP Buffer to receive the string - \fIbuffersize\fP Size of buffer -.sp -The yield is the length of the substring, PCRE_ERROR_NOMEMORY if the buffer was -too small, or PCRE_ERROR_NOSUBSTRING if the string name is invalid. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_copy_substring.3 b/gtk+-mingw/share/man/man3/pcre16_copy_substring.3 deleted file mode 100644 index 6bb09f8..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_copy_substring.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH PCRE_COPY_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP, -.ti +5n -.B int \fIbuffersize\fP); -.PP -.B int pcre16_copy_substring(PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, PCRE_UCHAR16 *\fIbuffer\fP, -.ti +5n -.B int \fIbuffersize\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a captured substring into a given -buffer. The arguments are: -.sp - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec()\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec()\fP - \fIstringnumber\fP Number of the required substring - \fIbuffer\fP Buffer to receive the string - \fIbuffersize\fP Size of buffer -.sp -The yield is the length of the string, PCRE_ERROR_NOMEMORY if the buffer was -too small, or PCRE_ERROR_NOSUBSTRING if the string number is invalid. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_dfa_exec.3 b/gtk+-mingw/share/man/man3/pcre16_dfa_exec.3 deleted file mode 100644 index 2df5d89..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_dfa_exec.3 +++ /dev/null @@ -1,114 +0,0 @@ -.TH PCRE_DFA_EXEC 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP, -.ti +5n -.B int *\fIworkspace\fP, int \fIwscount\fP); -.PP -.B int pcre16_dfa_exec(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP," -.ti +5n -.B "PCRE_SPTR16 \fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP, -.ti +5n -.B int *\fIworkspace\fP, int \fIwscount\fP); -. -.SH DESCRIPTION -.rs -.sp -This function matches a compiled regular expression against a given subject -string, using an alternative matching algorithm that scans the subject string -just once (\fInot\fP Perl-compatible). Note that the main, Perl-compatible, -matching function is \fBpcre[16]_exec()\fP. The arguments for this function -are: -.sp - \fIcode\fP Points to the compiled pattern - \fIextra\fP Points to an associated \fBpcre[16]_extra\fP structure, - or is NULL - \fIsubject\fP Points to the subject string - \fIlength\fP Length of the subject string, in bytes - \fIstartoffset\fP Offset in bytes in the subject at which to - start matching - \fIoptions\fP Option bits - \fIovector\fP Points to a vector of ints for result offsets - \fIovecsize\fP Number of elements in the vector - \fIworkspace\fP Points to a vector of ints used as working space - \fIwscount\fP Number of elements in the vector -.sp -The options are: -.sp - PCRE_ANCHORED Match only at the first position - PCRE_BSR_ANYCRLF \eR matches only CR, LF, or CRLF - PCRE_BSR_UNICODE \eR matches all Unicode line endings - PCRE_NEWLINE_ANY Recognize any Unicode newline sequence - PCRE_NEWLINE_ANYCRLF Recognize CR, LF, & CRLF as newline sequences - PCRE_NEWLINE_CR Recognize CR as the only newline sequence - PCRE_NEWLINE_CRLF Recognize CRLF as the only newline sequence - PCRE_NEWLINE_LF Recognize LF as the only newline sequence - PCRE_NOTBOL Subject is not the beginning of a line - PCRE_NOTEOL Subject is not the end of a line - PCRE_NOTEMPTY An empty string is not a valid match - PCRE_NOTEMPTY_ATSTART An empty string at the start of the subject - is not a valid match - PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations - PCRE_NO_UTF16_CHECK Do not check the subject for UTF-16 - validity (only relevant if PCRE_UTF16 - was set at compile time) - PCRE_NO_UTF8_CHECK Do not check the subject for UTF-8 - validity (only relevant if PCRE_UTF8 - was set at compile time) - PCRE_PARTIAL ) Return PCRE_ERROR_PARTIAL for a partial - PCRE_PARTIAL_SOFT ) match if no full matches are found - PCRE_PARTIAL_HARD Return PCRE_ERROR_PARTIAL for a partial match - even if there is a full match as well - PCRE_DFA_SHORTEST Return only the shortest match - PCRE_DFA_RESTART Restart after a partial match -.sp -There are restrictions on what may appear in a pattern when using this matching -function. Details are given in the -.\" HREF -\fBpcrematching\fP -.\" -documentation. For details of partial matching, see the -.\" HREF -\fBpcrepartial\fP -.\" -page. -.P -A \fBpcre[16]_extra\fP structure contains the following fields: -.sp - \fIflags\fP Bits indicating which fields are set - \fIstudy_data\fP Opaque data from \fBpcre[16]_study()\fP - \fImatch_limit\fP Limit on internal resource use - \fImatch_limit_recursion\fP Limit on internal recursion depth - \fIcallout_data\fP Opaque data passed back to callouts - \fItables\fP Points to character tables or is NULL - \fImark\fP For passing back a *MARK pointer - \fIexecutable_jit\fP Opaque data from JIT compilation -.sp -The flag bits are PCRE_EXTRA_STUDY_DATA, PCRE_EXTRA_MATCH_LIMIT, -PCRE_EXTRA_MATCH_LIMIT_RECURSION, PCRE_EXTRA_CALLOUT_DATA, -PCRE_EXTRA_TABLES, PCRE_EXTRA_MARK and PCRE_EXTRA_EXECUTABLE_JIT. For this -matching function, the \fImatch_limit\fP and \fImatch_limit_recursion\fP fields -are not used, and must not be set. The PCRE_EXTRA_EXECUTABLE_JIT flag and -the corresponding variable are ignored. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_exec.3 b/gtk+-mingw/share/man/man3/pcre16_exec.3 deleted file mode 100644 index 0ff0f6f..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_exec.3 +++ /dev/null @@ -1,94 +0,0 @@ -.TH PCRE_EXEC 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP); -.PP -.B int pcre16_exec(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP," -.ti +5n -.B "PCRE_SPTR16 \fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP); -. -.SH DESCRIPTION -.rs -.sp -This function matches a compiled regular expression against a given subject -string, using a matching algorithm that is similar to Perl's. It returns -offsets to captured substrings. Its arguments are: -.sp - \fIcode\fP Points to the compiled pattern - \fIextra\fP Points to an associated \fBpcre[16]_extra\fP structure, - or is NULL - \fIsubject\fP Points to the subject string - \fIlength\fP Length of the subject string, in bytes - \fIstartoffset\fP Offset in bytes in the subject at which to - start matching - \fIoptions\fP Option bits - \fIovector\fP Points to a vector of ints for result offsets - \fIovecsize\fP Number of elements in the vector (a multiple of 3) -.sp -The options are: -.sp - PCRE_ANCHORED Match only at the first position - PCRE_BSR_ANYCRLF \eR matches only CR, LF, or CRLF - PCRE_BSR_UNICODE \eR matches all Unicode line endings - PCRE_NEWLINE_ANY Recognize any Unicode newline sequence - PCRE_NEWLINE_ANYCRLF Recognize CR, LF, & CRLF as newline sequences - PCRE_NEWLINE_CR Recognize CR as the only newline sequence - PCRE_NEWLINE_CRLF Recognize CRLF as the only newline sequence - PCRE_NEWLINE_LF Recognize LF as the only newline sequence - PCRE_NOTBOL Subject string is not the beginning of a line - PCRE_NOTEOL Subject string is not the end of a line - PCRE_NOTEMPTY An empty string is not a valid match - PCRE_NOTEMPTY_ATSTART An empty string at the start of the subject - is not a valid match - PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations - PCRE_NO_UTF16_CHECK Do not check the subject for UTF-16 - validity (only relevant if PCRE_UTF16 - was set at compile time) - PCRE_NO_UTF8_CHECK Do not check the subject for UTF-8 - validity (only relevant if PCRE_UTF8 - was set at compile time) - PCRE_PARTIAL ) Return PCRE_ERROR_PARTIAL for a partial - PCRE_PARTIAL_SOFT ) match if no full matches are found - PCRE_PARTIAL_HARD Return PCRE_ERROR_PARTIAL for a partial match - if that is found before a full match -.sp -For details of partial matching, see the -.\" HREF -\fBpcrepartial\fP -.\" -page. A \fBpcre_extra\fP structure contains the following fields: -.sp - \fIflags\fP Bits indicating which fields are set - \fIstudy_data\fP Opaque data from \fBpcre[16]_study()\fP - \fImatch_limit\fP Limit on internal resource use - \fImatch_limit_recursion\fP Limit on internal recursion depth - \fIcallout_data\fP Opaque data passed back to callouts - \fItables\fP Points to character tables or is NULL - \fImark\fP For passing back a *MARK pointer - \fIexecutable_jit\fP Opaque data from JIT compilation -.sp -The flag bits are PCRE_EXTRA_STUDY_DATA, PCRE_EXTRA_MATCH_LIMIT, -PCRE_EXTRA_MATCH_LIMIT_RECURSION, PCRE_EXTRA_CALLOUT_DATA, -PCRE_EXTRA_TABLES, PCRE_EXTRA_MARK and PCRE_EXTRA_EXECUTABLE_JIT. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_free_study.3 b/gtk+-mingw/share/man/man3/pcre16_free_study.3 deleted file mode 100644 index 9fd5d80..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_free_study.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH PCRE_FREE_STUDY 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_free_study(pcre_extra *\fIextra\fP); -.PP -.B void pcre16_free_study(pcre16_extra *\fIextra\fP); -. -.SH DESCRIPTION -.rs -.sp -This function is used to free the memory used for the data generated by a call -to \fBpcre[16]_study()\fP when it is no longer needed. The argument must be the -result of such a call. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_free_substring.3 b/gtk+-mingw/share/man/man3/pcre16_free_substring.3 deleted file mode 100644 index dff5bb0..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_free_substring.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH PCRE_FREE_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_free_substring(const char *\fIstringptr\fP); -.PP -.B void pcre16_free_substring(PCRE_SPTR16 \fIstringptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for freeing the store obtained by a previous -call to \fBpcre[16]_get_substring()\fP or \fBpcre[16]_get_named_substring()\fP. -Its only argument is a pointer to the string. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_free_substring_list.3 b/gtk+-mingw/share/man/man3/pcre16_free_substring_list.3 deleted file mode 100644 index a587759..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_free_substring_list.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH PCRE_FREE_SUBSTRING_LIST 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_free_substring_list(const char **\fIstringptr\fP); -.PP -.B void pcre16_free_substring_list(PCRE_SPTR16 *\fIstringptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for freeing the store obtained by a previous -call to \fBpcre[16]_get_substring_list()\fP. Its only argument is a pointer to -the list of string pointers. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_fullinfo.3 b/gtk+-mingw/share/man/man3/pcre16_fullinfo.3 deleted file mode 100644 index 1c2a58f..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_fullinfo.3 +++ /dev/null @@ -1,78 +0,0 @@ -.TH PCRE_FULLINFO 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B int \fIwhat\fP, void *\fIwhere\fP); -.PP -.B int pcre16_fullinfo(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP," -.ti +5n -.B int \fIwhat\fP, void *\fIwhere\fP); -. -.SH DESCRIPTION -.rs -.sp -This function returns information about a compiled pattern. Its arguments are: -.sp - \fIcode\fP Compiled regular expression - \fIextra\fP Result of \fBpcre[16]_study()\fP or NULL - \fIwhat\fP What information is required - \fIwhere\fP Where to put the information -.sp -The following information is available: -.sp - PCRE_INFO_BACKREFMAX Number of highest back reference - PCRE_INFO_CAPTURECOUNT Number of capturing subpatterns - PCRE_INFO_DEFAULT_TABLES Pointer to default tables - PCRE_INFO_FIRSTBYTE Fixed first data unit for a match, or - -1 for start of string - or after newline, or - -2 otherwise - PCRE_INFO_FIRSTTABLE Table of first data units (after studying) - PCRE_INFO_HASCRORLF Return 1 if explicit CR or LF matches exist - PCRE_INFO_JCHANGED Return 1 if (?J) or (?-J) was used - PCRE_INFO_JIT Return 1 after successful JIT compilation - PCRE_INFO_JITSIZE Size of JIT compiled code - PCRE_INFO_LASTLITERAL Literal last data unit required - PCRE_INFO_MINLENGTH Lower bound length of matching strings - PCRE_INFO_NAMECOUNT Number of named subpatterns - PCRE_INFO_NAMEENTRYSIZE Size of name table entry - PCRE_INFO_NAMETABLE Pointer to name table - PCRE_INFO_OKPARTIAL Return 1 if partial matching can be tried - (always returns 1 after release 8.00) - PCRE_INFO_OPTIONS Option bits used for compilation - PCRE_INFO_SIZE Size of compiled pattern - PCRE_INFO_STUDYSIZE Size of study data -.sp -The \fIwhere\fP argument must point to an integer variable, except for the -following \fIwhat\fP values: -.sp - PCRE_INFO_DEFAULT_TABLES const unsigned char * - PCRE_INFO_FIRSTTABLE const unsigned char * - PCRE_INFO_NAMETABLE PCRE_SPTR16 (16-bit library) - PCRE_INFO_NAMETABLE const unsigned char * (8-bit library) - PCRE_INFO_OPTIONS unsigned long int - PCRE_INFO_SIZE size_t -.sp -The yield of the function is zero on success or: -.sp - PCRE_ERROR_NULL the argument \fIcode\fP was NULL - the argument \fIwhere\fP was NULL - PCRE_ERROR_BADMAGIC the "magic number" was not found - PCRE_ERROR_BADOPTION the value of \fIwhat\fP was invalid -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_get_named_substring.3 b/gtk+-mingw/share/man/man3/pcre16_get_named_substring.3 deleted file mode 100644 index 88dd2da..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_get_named_substring.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH PCRE_GET_NAMED_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_named_substring(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, const char *\fIstringname\fP, -.ti +5n -.B const char **\fIstringptr\fP); -.PP -.B int pcre16_get_named_substring(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, PCRE_SPTR16 \fIstringname\fP, -.ti +5n -.B PCRE_SPTR16 *\fIstringptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a captured substring by name. The -arguments are: -.sp - \fIcode\fP Compiled pattern - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec()\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec()\fP - \fIstringname\fP Name of the required substring - \fIstringptr\fP Where to put the string pointer -.sp -The memory in which the substring is placed is obtained by calling -\fBpcre[16]_malloc()\fP. The convenience function -\fBpcre[16]_free_substring()\fP can be used to free it when it is no longer -needed. The yield of the function is the length of the extracted substring, -PCRE_ERROR_NOMEMORY if sufficient memory could not be obtained, or -PCRE_ERROR_NOSUBSTRING if the string name is invalid. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_get_stringnumber.3 b/gtk+-mingw/share/man/man3/pcre16_get_stringnumber.3 deleted file mode 100644 index 79c52dc..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_get_stringnumber.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH PCRE_GET_STRINGNUMBER 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_stringnumber(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIname\fP); -.PP -.B int pcre16_get_stringnumber(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIname\fP); -. -.SH DESCRIPTION -.rs -.sp -This convenience function finds the number of a named substring capturing -parenthesis in a compiled pattern. Its arguments are: -.sp - \fIcode\fP Compiled regular expression - \fIname\fP Name whose number is required -.sp -The yield of the function is the number of the parenthesis if the name is -found, or PCRE_ERROR_NOSUBSTRING otherwise. When duplicate names are allowed -(PCRE_DUPNAMES is set), it is not defined which of the numbers is returned by -\fBpcre[16]_get_stringnumber()\fP. You can obtain the complete list by calling -\fBpcre[16]_get_stringtable_entries()\fP. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_get_stringtable_entries.3 b/gtk+-mingw/share/man/man3/pcre16_get_stringtable_entries.3 deleted file mode 100644 index a192e83..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_get_stringtable_entries.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH PCRE_GET_STRINGTABLE_ENTRIES 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP); -.PP -.B int pcre16_get_stringtable_entries(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIname\fP, PCRE_UCHAR16 **\fIfirst\fP, PCRE_UCHAR16 **\fIlast\fP); -. -.SH DESCRIPTION -.rs -.sp -This convenience function finds, for a compiled pattern, the first and last -entries for a given name in the table that translates capturing parenthesis -names into numbers. When names are required to be unique (PCRE_DUPNAMES is -\fInot\fP set), it is usually easier to use \fBpcre[16]_get_stringnumber()\fP -instead. -.sp - \fIcode\fP Compiled regular expression - \fIname\fP Name whose entries required - \fIfirst\fP Where to return a pointer to the first entry - \fIlast\fP Where to return a pointer to the last entry -.sp -The yield of the function is the length of each entry, or -PCRE_ERROR_NOSUBSTRING if none are found. -.P -There is a complete description of the PCRE native API, including the format of -the table entries, in the -.\" HREF -\fBpcreapi\fP -.\" -page, and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_get_substring.3 b/gtk+-mingw/share/man/man3/pcre16_get_substring.3 deleted file mode 100644 index 3af1948..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_get_substring.3 +++ /dev/null @@ -1,49 +0,0 @@ -.TH PCRE_GET_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, -.ti +5n -.B const char **\fIstringptr\fP); -.PP -.B int pcre16_get_substring(PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, -.ti +5n -.B PCRE_SPTR16 *\fIstringptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a captured substring. The -arguments are: -.sp - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec()\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec()\fP - \fIstringnumber\fP Number of the required substring - \fIstringptr\fP Where to put the string pointer -.sp -The memory in which the substring is placed is obtained by calling -\fBpcre[16]_malloc()\fP. The convenience function -\fBpcre[16]_free_substring()\fP can be used to free it when it is no longer -needed. The yield of the function is the length of the substring, -PCRE_ERROR_NOMEMORY if sufficient memory could not be obtained, or -PCRE_ERROR_NOSUBSTRING if the string number is invalid. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_get_substring_list.3 b/gtk+-mingw/share/man/man3/pcre16_get_substring_list.3 deleted file mode 100644 index 33c3a51..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_get_substring_list.3 +++ /dev/null @@ -1,45 +0,0 @@ -.TH PCRE_GET_SUBSTRING_LIST 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_substring_list(const char *\fIsubject\fP, -.ti +5n -.B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);" -.PP -.B int pcre16_get_substring_list(PCRE_SPTR16 \fIsubject\fP, -.ti +5n -.B int *\fIovector\fP, int \fIstringcount\fP, "PCRE_SPTR16 **\fIlistptr\fP);" -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a list of all the captured -substrings. The arguments are: -.sp - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec\fP - \fIlistptr\fP Where to put a pointer to the list -.sp -The memory in which the substrings and the list are placed is obtained by -calling \fBpcre[16]_malloc()\fP. The convenience function -\fBpcre[16]_free_substring_list()\fP can be used to free it when it is no -longer needed. A pointer to a list of pointers is put in the variable whose -address is in \fIlistptr\fP. The list is terminated by a NULL pointer. The -yield of the function is zero on success or PCRE_ERROR_NOMEMORY if sufficient -memory could not be obtained. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_jit_stack_alloc.3 b/gtk+-mingw/share/man/man3/pcre16_jit_stack_alloc.3 deleted file mode 100644 index b488d85..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_jit_stack_alloc.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH PCRE_JIT_STACK_ALLOC 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B pcre_jit_stack *pcre_jit_stack_alloc(int \fIstartsize\fP, -.ti +5n -.B int \fImaxsize\fP); -.PP -.B pcre16_jit_stack *pcre16_jit_stack_alloc(int \fIstartsize\fP, -.ti +5n -.B int \fImaxsize\fP); -. -.SH DESCRIPTION -.rs -.sp -This function is used to create a stack for use by the code compiled by the JIT -optimization of \fBpcre[16]_study()\fP. The arguments are a starting size for -the stack, and a maximum size to which it is allowed to grow. The result can be -passed to the JIT run-time code by \fBpcre[16]_assign_jit_stack()\fP, or that -function can set up a callback for obtaining a stack. A maximum stack size of -512K to 1M should be more than enough for any pattern. For more details, see -the -.\" HREF -\fBpcrejit\fP -.\" -page. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_jit_stack_free.3 b/gtk+-mingw/share/man/man3/pcre16_jit_stack_free.3 deleted file mode 100644 index 9f6528b..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_jit_stack_free.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH PCRE_JIT_STACK_FREE 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_jit_stack_free(pcre_jit_stack *\fIstack\fP); -.PP -.B void pcre16_jit_stack_free(pcre16_jit_stack *\fIstack\fP); -. -.SH DESCRIPTION -.rs -.sp -This function is used to free a JIT stack that was created by -\fBpcre[16]_jit_stack_alloc()\fP when it is no longer needed. For more details, -see the -.\" HREF -\fBpcrejit\fP -.\" -page. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_maketables.3 b/gtk+-mingw/share/man/man3/pcre16_maketables.3 deleted file mode 100644 index 73b188b..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_maketables.3 +++ /dev/null @@ -1,31 +0,0 @@ -.TH PCRE_MAKETABLES 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B const unsigned char *pcre_maketables(void); -.PP -.B const unsigned char *pcre16_maketables(void); -. -.SH DESCRIPTION -.rs -.sp -This function builds a set of character tables for character values less than -256. These can be passed to \fBpcre[16]_compile()\fP to override PCRE's -internal, built-in tables (which were made by \fBpcre[16]_maketables()\fP when -PCRE was compiled). You might want to do this if you are using a non-standard -locale. The function yields a pointer to the tables. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_pattern_to_host_byte_order.3 b/gtk+-mingw/share/man/man3/pcre16_pattern_to_host_byte_order.3 deleted file mode 100644 index 8c34473..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_pattern_to_host_byte_order.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH PCRE_PATTERN_TO_HOST_BYTE_ORDER 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_pattern_to_host_byte_order(pcre *\fIcode\fP, -.ti +5n -.B pcre_extra *\fIextra\fP, const unsigned char *\fItables\fP); -.PP -.B int pcre16_pattern_to_host_byte_order(pcre16 *\fIcode\fP, -.ti +5n -.B pcre16_extra *\fIextra\fP, const unsigned char *\fItables\fP); -. -. -.SH DESCRIPTION -.rs -.sp -This function ensures that the bytes in 2-byte and 4-byte values in a compiled -pattern are in the correct order for the current host. It is useful when a -pattern that has been compiled on one host is transferred to another that might -have different endianness. The arguments are: -.sp - \fIcode\fP A compiled regular expression - \fIextra\fP Points to an associated \fBpcre[16]_extra\fP structure, - or is NULL - \fItables\fP Pointer to character tables, or NULL to - set the built-in default -.sp -The result is 0 for success, a negative PCRE_ERROR_xxx value otherwise. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_refcount.3 b/gtk+-mingw/share/man/man3/pcre16_refcount.3 deleted file mode 100644 index a30eecf..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_refcount.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH PCRE_REFCOUNT 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP); -.PP -.B int pcre16_refcount(pcre16 *\fIcode\fP, int \fIadjust\fP); -. -.SH DESCRIPTION -.rs -.sp -This function is used to maintain a reference count inside a data block that -contains a compiled pattern. Its arguments are: -.sp - \fIcode\fP Compiled regular expression - \fIadjust\fP Adjustment to reference value -.sp -The yield of the function is the adjusted reference value, which is constrained -to lie between 0 and 65535. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_study.3 b/gtk+-mingw/share/man/man3/pcre16_study.3 deleted file mode 100644 index 13ea6c4..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_study.3 +++ /dev/null @@ -1,52 +0,0 @@ -.TH PCRE_STUDY 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP); -.PP -.B pcre16_extra *pcre16_study(const pcre16 *\fIcode\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This function studies a compiled pattern, to see if additional information can -be extracted that might speed up matching. Its arguments are: -.sp - \fIcode\fP A compiled regular expression - \fIoptions\fP Options for \fBpcre[16]_study()\fP - \fIerrptr\fP Where to put an error message -.sp -If the function succeeds, it returns a value that can be passed to -\fBpcre[16]_exec()\fP or \fBpcre[16]_dfa_exec()\fP via their \fIextra\fP -arguments. -.P -If the function returns NULL, either it could not find any additional -information, or there was an error. You can tell the difference by looking at -the error value. It is NULL in first case. -.P -The only option is PCRE_STUDY_JIT_COMPILE. It requests just-in-time compilation -if possible. If PCRE has been compiled without JIT support, this option is -ignored. See the -.\" HREF -\fBpcrejit\fP -.\" -page for further details. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_utf16_to_host_byte_order.3 b/gtk+-mingw/share/man/man3/pcre16_utf16_to_host_byte_order.3 deleted file mode 100644 index 8f0d2d4..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_utf16_to_host_byte_order.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH PCRE_UTF16_TO_HOST_BYTE_ORDER 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre16_utf16_to_host_byte_order(PCRE_UCHAR16 *\fIoutput\fP, -.ti +5n -.B PCRE_SPTR16 \fIinput\fP, int \fIlength\fP, int *\fIhost_byte_order\fP, -.ti +5n -.B int \fIkeep_boms\fP); -. -. -.SH DESCRIPTION -.rs -.sp -This function, which exists only in the 16-bit library, converts a UTF-16 -string to the correct order for the current host, taking account of any byte -order marks (BOMs) within the string. Its arguments are: -.sp - \fIoutput\fP pointer to output buffer, may be the same as \fIinput\fP - \fIinput\fP pointer to input buffer - \fIlength\fP number of 16-bit units in the input, or negative for - a zero-terminated string - \fIhost_byte_order\fP a NULL value or a non-zero value pointed to means - start in host byte order - \fIkeep_boms\fP if non-zero, BOMs are copied to the output string -.sp -The result of the function is the number of 16-bit units placed into the output -buffer, including the zero terminator if the string was zero-terminated. -.P -If \fIhost_byte_order\fP is not NULL, it is set to indicate the byte order that -is current at the end of the string. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre16_version.3 b/gtk+-mingw/share/man/man3/pcre16_version.3 deleted file mode 100644 index bcbd4f2..0000000 --- a/gtk+-mingw/share/man/man3/pcre16_version.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH PCRE_VERSION 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B const char *pcre_version(void); -.PP -.B const char *pcre16_version(void); -. -.SH DESCRIPTION -.rs -.sp -This function (even in the 16-bit library) returns a zero-terminated, 8-bit -character string that gives the version number of the PCRE library and the date -of its release. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_assign_jit_stack.3 b/gtk+-mingw/share/man/man3/pcre_assign_jit_stack.3 deleted file mode 100644 index fc32dda..0000000 --- a/gtk+-mingw/share/man/man3/pcre_assign_jit_stack.3 +++ /dev/null @@ -1,57 +0,0 @@ -.TH PCRE_ASSIGN_JIT_STACK 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_assign_jit_stack(pcre_extra *\fIextra\fP, -.ti +5n -.B pcre_jit_callback \fIcallback\fP, void *\fIdata\fP); -.PP -.B void pcre16_assign_jit_stack(pcre16_extra *\fIextra\fP, -.ti +5n -.B pcre16_jit_callback \fIcallback\fP, void *\fIdata\fP); -. -.SH DESCRIPTION -.rs -.sp -This function provides control over the memory used as a stack at run-time by a -call to \fBpcre[16]_exec()\fP with a pattern that has been successfully -compiled with JIT optimization. The arguments are: -.sp - extra the data pointer returned by \fBpcre[16]_study()\fP - callback a callback function - data a JIT stack or a value to be passed to the callback - function -.P -If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32K block on -the machine stack is used. -.P -If \fIcallback\fP is NULL and \fIdata\fP is not NULL, \fIdata\fP must -be a valid JIT stack, the result of calling \fBpcre[16]_jit_stack_alloc()\fP. -.P -If \fIcallback\fP not NULL, it is called with \fIdata\fP as an argument at -the start of matching, in order to set up a JIT stack. If the result is NULL, -the internal 32K stack is used; otherwise the return value must be a valid JIT -stack, the result of calling \fBpcre[16]_jit_stack_alloc()\fP. -.P -You may safely assign the same JIT stack to multiple patterns, as long as they -are all matched in the same thread. In a multithread application, each thread -must use its own JIT stack. For more details, see the -.\" HREF -\fBpcrejit\fP -.\" -page. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_compile.3 b/gtk+-mingw/share/man/man3/pcre_compile.3 deleted file mode 100644 index c38c251..0000000 --- a/gtk+-mingw/share/man/man3/pcre_compile.3 +++ /dev/null @@ -1,88 +0,0 @@ -.TH PCRE_COMPILE 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.PP -.B pcre16 *pcre16_compile(PCRE_SPTR16 \fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This function compiles a regular expression into an internal form. It is the -same as \fBpcre[16]_compile2()\fP, except for the absence of the -\fIerrorcodeptr\fP argument. Its arguments are: -.sp - \fIpattern\fP A zero-terminated string containing the - regular expression to be compiled - \fIoptions\fP Zero or more option bits - \fIerrptr\fP Where to put an error message - \fIerroffset\fP Offset in pattern where error was found - \fItableptr\fP Pointer to character tables, or NULL to - use the built-in default -.sp -The option bits are: -.sp - PCRE_ANCHORED Force pattern anchoring - PCRE_AUTO_CALLOUT Compile automatic callouts - PCRE_BSR_ANYCRLF \eR matches only CR, LF, or CRLF - PCRE_BSR_UNICODE \eR matches all Unicode line endings - PCRE_CASELESS Do caseless matching - PCRE_DOLLAR_ENDONLY $ not to match newline at end - PCRE_DOTALL . matches anything including NL - PCRE_DUPNAMES Allow duplicate names for subpatterns - PCRE_EXTENDED Ignore white space and # comments - PCRE_EXTRA PCRE extra features - (not much use currently) - PCRE_FIRSTLINE Force matching to be before newline - PCRE_JAVASCRIPT_COMPAT JavaScript compatibility - PCRE_MULTILINE ^ and $ match newlines within data - PCRE_NEWLINE_ANY Recognize any Unicode newline sequence - PCRE_NEWLINE_ANYCRLF Recognize CR, LF, and CRLF as newline - sequences - PCRE_NEWLINE_CR Set CR as the newline sequence - PCRE_NEWLINE_CRLF Set CRLF as the newline sequence - PCRE_NEWLINE_LF Set LF as the newline sequence - PCRE_NO_AUTO_CAPTURE Disable numbered capturing paren- - theses (named ones available) - PCRE_NO_UTF16_CHECK Do not check the pattern for UTF-16 - validity (only relevant if - PCRE_UTF16 is set) - PCRE_NO_UTF8_CHECK Do not check the pattern for UTF-8 - validity (only relevant if - PCRE_UTF8 is set) - PCRE_UCP Use Unicode properties for \ed, \ew, etc. - PCRE_UNGREEDY Invert greediness of quantifiers - PCRE_UTF16 Run in \fBpcre16_compile()\fP UTF-16 mode - PCRE_UTF8 Run in \fBpcre_compile()\fP UTF-8 mode -.sp -PCRE must be built with UTF support in order to use PCRE_UTF8/16 and -PCRE_NO_UTF8/16_CHECK, and with UCP support if PCRE_UCP is used. -.P -The yield of the function is a pointer to a private data structure that -contains the compiled pattern, or NULL if an error was detected. Note that -compiling regular expressions with one version of PCRE for use with a different -version is not guaranteed to work and may cause crashes. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_compile2.3 b/gtk+-mingw/share/man/man3/pcre_compile2.3 deleted file mode 100644 index 58b8a14..0000000 --- a/gtk+-mingw/share/man/man3/pcre_compile2.3 +++ /dev/null @@ -1,94 +0,0 @@ -.TH PCRE_COMPILE2 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B int *\fIerrorcodeptr\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.PP -.B pcre16 *pcre16_compile2(PCRE_SPTR16 \fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B int *\fIerrorcodeptr\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This function compiles a regular expression into an internal form. It is the -same as \fBpcre[16]_compile()\fP, except for the addition of the -\fIerrorcodeptr\fP argument. The arguments are: -. -.sp - \fIpattern\fP A zero-terminated string containing the - regular expression to be compiled - \fIoptions\fP Zero or more option bits - \fIerrorcodeptr\fP Where to put an error code - \fIerrptr\fP Where to put an error message - \fIerroffset\fP Offset in pattern where error was found - \fItableptr\fP Pointer to character tables, or NULL to - use the built-in default -.sp -The option bits are: -.sp - PCRE_ANCHORED Force pattern anchoring - PCRE_AUTO_CALLOUT Compile automatic callouts - PCRE_BSR_ANYCRLF \eR matches only CR, LF, or CRLF - PCRE_BSR_UNICODE \eR matches all Unicode line endings - PCRE_CASELESS Do caseless matching - PCRE_DOLLAR_ENDONLY $ not to match newline at end - PCRE_DOTALL . matches anything including NL - PCRE_DUPNAMES Allow duplicate names for subpatterns - PCRE_EXTENDED Ignore white space and # comments - PCRE_EXTRA PCRE extra features - (not much use currently) - PCRE_FIRSTLINE Force matching to be before newline - PCRE_JAVASCRIPT_COMPAT JavaScript compatibility - PCRE_MULTILINE ^ and $ match newlines within data - PCRE_NEWLINE_ANY Recognize any Unicode newline sequence - PCRE_NEWLINE_ANYCRLF Recognize CR, LF, and CRLF as newline - sequences - PCRE_NEWLINE_CR Set CR as the newline sequence - PCRE_NEWLINE_CRLF Set CRLF as the newline sequence - PCRE_NEWLINE_LF Set LF as the newline sequence - PCRE_NO_AUTO_CAPTURE Disable numbered capturing paren- - theses (named ones available) - PCRE_NO_UTF16_CHECK Do not check the pattern for UTF-16 - validity (only relevant if - PCRE_UTF16 is set) - PCRE_NO_UTF8_CHECK Do not check the pattern for UTF-8 - validity (only relevant if - PCRE_UTF8 is set) - PCRE_UCP Use Unicode properties for \ed, \ew, etc. - PCRE_UNGREEDY Invert greediness of quantifiers - PCRE_UTF16 Run \fBpcre16_compile()\fP in UTF-16 mode - PCRE_UTF8 Run \fBpcre_compile()\fP in UTF-8 mode -.sp -PCRE must be built with UTF support in order to use PCRE_UTF8/16 and -PCRE_NO_UTF8/16_CHECK, and with UCP support if PCRE_UCP is used. -.P -The yield of the function is a pointer to a private data structure that -contains the compiled pattern, or NULL if an error was detected. Note that -compiling regular expressions with one version of PCRE for use with a different -version is not guaranteed to work and may cause crashes. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_config.3 b/gtk+-mingw/share/man/man3/pcre_config.3 deleted file mode 100644 index 45013a4..0000000 --- a/gtk+-mingw/share/man/man3/pcre_config.3 +++ /dev/null @@ -1,70 +0,0 @@ -.TH PCRE_CONFIG 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP); -.PP -.B int pcre16_config(int \fIwhat\fP, void *\fIwhere\fP); -. -.SH DESCRIPTION -.rs -.sp -This function makes it possible for a client program to find out which optional -features are available in the version of the PCRE library it is using. The -arguments are as follows: -.sp - \fIwhat\fP A code specifying what information is required - \fIwhere\fP Points to where to put the data -.sp -The \fIwhere\fP argument must point to an integer variable, except for -PCRE_CONFIG_MATCH_LIMIT and PCRE_CONFIG_MATCH_LIMIT_RECURSION, when it must -point to an unsigned long integer. The available codes are: -.sp - PCRE_CONFIG_JIT Availability of just-in-time compiler - support (1=yes 0=no) - PCRE_CONFIG_JITTARGET String containing information about the - target architecture for the JIT compiler, - or NULL if there is no JIT support - PCRE_CONFIG_LINK_SIZE Internal link size: 2, 3, or 4 - PCRE_CONFIG_MATCH_LIMIT Internal resource limit - PCRE_CONFIG_MATCH_LIMIT_RECURSION - Internal recursion depth limit - PCRE_CONFIG_NEWLINE Value of the default newline sequence: - 13 (0x000d) for CR - 10 (0x000a) for LF - 3338 (0x0d0a) for CRLF - -2 for ANYCRLF - -1 for ANY - PCRE_CONFIG_BSR Indicates what \eR matches by default: - 0 all Unicode line endings - 1 CR, LF, or CRLF only - PCRE_CONFIG_POSIX_MALLOC_THRESHOLD - Threshold of return slots, above which - \fBmalloc()\fP is used by the POSIX API - PCRE_CONFIG_STACKRECURSE Recursion implementation (1=stack 0=heap) - PCRE_CONFIG_UTF16 Availability of UTF-16 support (1=yes - 0=no); option for \fBpcre16_config()\fP - PCRE_CONFIG_UTF8 Availability of UTF-8 support (1=yes 0=no); - option for \fBpcre_config()\fP - PCRE_CONFIG_UNICODE_PROPERTIES - Availability of Unicode property support - (1=yes 0=no) -.sp -The function yields 0 on success or PCRE_ERROR_BADOPTION otherwise. That error -is also given if PCRE_CONFIG_UTF16 is passed to \fBpcre_config()\fP or if -PCRE_CONFIG_UTF8 is passed to \fBpcre16_config()\fP. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_copy_named_substring.3 b/gtk+-mingw/share/man/man3/pcre_copy_named_substring.3 deleted file mode 100644 index 9838816..0000000 --- a/gtk+-mingw/share/man/man3/pcre_copy_named_substring.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH PCRE_COPY_NAMED_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_copy_named_substring(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, const char *\fIstringname\fP, -.ti +5n -.B char *\fIbuffer\fP, int \fIbuffersize\fP); -.PP -.B int pcre16_copy_named_substring(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, PCRE_SPTR16 \fIstringname\fP, -.ti +5n -.B PCRE_UCHAR16 *\fIbuffer\fP, int \fIbuffersize\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a captured substring, identified -by name, into a given buffer. The arguments are: -.sp - \fIcode\fP Pattern that was successfully matched - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec()\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec()\fP - \fIstringname\fP Name of the required substring - \fIbuffer\fP Buffer to receive the string - \fIbuffersize\fP Size of buffer -.sp -The yield is the length of the substring, PCRE_ERROR_NOMEMORY if the buffer was -too small, or PCRE_ERROR_NOSUBSTRING if the string name is invalid. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_copy_substring.3 b/gtk+-mingw/share/man/man3/pcre_copy_substring.3 deleted file mode 100644 index 6bb09f8..0000000 --- a/gtk+-mingw/share/man/man3/pcre_copy_substring.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH PCRE_COPY_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP, -.ti +5n -.B int \fIbuffersize\fP); -.PP -.B int pcre16_copy_substring(PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, PCRE_UCHAR16 *\fIbuffer\fP, -.ti +5n -.B int \fIbuffersize\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a captured substring into a given -buffer. The arguments are: -.sp - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec()\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec()\fP - \fIstringnumber\fP Number of the required substring - \fIbuffer\fP Buffer to receive the string - \fIbuffersize\fP Size of buffer -.sp -The yield is the length of the string, PCRE_ERROR_NOMEMORY if the buffer was -too small, or PCRE_ERROR_NOSUBSTRING if the string number is invalid. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_dfa_exec.3 b/gtk+-mingw/share/man/man3/pcre_dfa_exec.3 deleted file mode 100644 index 2df5d89..0000000 --- a/gtk+-mingw/share/man/man3/pcre_dfa_exec.3 +++ /dev/null @@ -1,114 +0,0 @@ -.TH PCRE_DFA_EXEC 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP, -.ti +5n -.B int *\fIworkspace\fP, int \fIwscount\fP); -.PP -.B int pcre16_dfa_exec(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP," -.ti +5n -.B "PCRE_SPTR16 \fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP, -.ti +5n -.B int *\fIworkspace\fP, int \fIwscount\fP); -. -.SH DESCRIPTION -.rs -.sp -This function matches a compiled regular expression against a given subject -string, using an alternative matching algorithm that scans the subject string -just once (\fInot\fP Perl-compatible). Note that the main, Perl-compatible, -matching function is \fBpcre[16]_exec()\fP. The arguments for this function -are: -.sp - \fIcode\fP Points to the compiled pattern - \fIextra\fP Points to an associated \fBpcre[16]_extra\fP structure, - or is NULL - \fIsubject\fP Points to the subject string - \fIlength\fP Length of the subject string, in bytes - \fIstartoffset\fP Offset in bytes in the subject at which to - start matching - \fIoptions\fP Option bits - \fIovector\fP Points to a vector of ints for result offsets - \fIovecsize\fP Number of elements in the vector - \fIworkspace\fP Points to a vector of ints used as working space - \fIwscount\fP Number of elements in the vector -.sp -The options are: -.sp - PCRE_ANCHORED Match only at the first position - PCRE_BSR_ANYCRLF \eR matches only CR, LF, or CRLF - PCRE_BSR_UNICODE \eR matches all Unicode line endings - PCRE_NEWLINE_ANY Recognize any Unicode newline sequence - PCRE_NEWLINE_ANYCRLF Recognize CR, LF, & CRLF as newline sequences - PCRE_NEWLINE_CR Recognize CR as the only newline sequence - PCRE_NEWLINE_CRLF Recognize CRLF as the only newline sequence - PCRE_NEWLINE_LF Recognize LF as the only newline sequence - PCRE_NOTBOL Subject is not the beginning of a line - PCRE_NOTEOL Subject is not the end of a line - PCRE_NOTEMPTY An empty string is not a valid match - PCRE_NOTEMPTY_ATSTART An empty string at the start of the subject - is not a valid match - PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations - PCRE_NO_UTF16_CHECK Do not check the subject for UTF-16 - validity (only relevant if PCRE_UTF16 - was set at compile time) - PCRE_NO_UTF8_CHECK Do not check the subject for UTF-8 - validity (only relevant if PCRE_UTF8 - was set at compile time) - PCRE_PARTIAL ) Return PCRE_ERROR_PARTIAL for a partial - PCRE_PARTIAL_SOFT ) match if no full matches are found - PCRE_PARTIAL_HARD Return PCRE_ERROR_PARTIAL for a partial match - even if there is a full match as well - PCRE_DFA_SHORTEST Return only the shortest match - PCRE_DFA_RESTART Restart after a partial match -.sp -There are restrictions on what may appear in a pattern when using this matching -function. Details are given in the -.\" HREF -\fBpcrematching\fP -.\" -documentation. For details of partial matching, see the -.\" HREF -\fBpcrepartial\fP -.\" -page. -.P -A \fBpcre[16]_extra\fP structure contains the following fields: -.sp - \fIflags\fP Bits indicating which fields are set - \fIstudy_data\fP Opaque data from \fBpcre[16]_study()\fP - \fImatch_limit\fP Limit on internal resource use - \fImatch_limit_recursion\fP Limit on internal recursion depth - \fIcallout_data\fP Opaque data passed back to callouts - \fItables\fP Points to character tables or is NULL - \fImark\fP For passing back a *MARK pointer - \fIexecutable_jit\fP Opaque data from JIT compilation -.sp -The flag bits are PCRE_EXTRA_STUDY_DATA, PCRE_EXTRA_MATCH_LIMIT, -PCRE_EXTRA_MATCH_LIMIT_RECURSION, PCRE_EXTRA_CALLOUT_DATA, -PCRE_EXTRA_TABLES, PCRE_EXTRA_MARK and PCRE_EXTRA_EXECUTABLE_JIT. For this -matching function, the \fImatch_limit\fP and \fImatch_limit_recursion\fP fields -are not used, and must not be set. The PCRE_EXTRA_EXECUTABLE_JIT flag and -the corresponding variable are ignored. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_exec.3 b/gtk+-mingw/share/man/man3/pcre_exec.3 deleted file mode 100644 index 0ff0f6f..0000000 --- a/gtk+-mingw/share/man/man3/pcre_exec.3 +++ /dev/null @@ -1,94 +0,0 @@ -.TH PCRE_EXEC 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP); -.PP -.B int pcre16_exec(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP," -.ti +5n -.B "PCRE_SPTR16 \fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP); -. -.SH DESCRIPTION -.rs -.sp -This function matches a compiled regular expression against a given subject -string, using a matching algorithm that is similar to Perl's. It returns -offsets to captured substrings. Its arguments are: -.sp - \fIcode\fP Points to the compiled pattern - \fIextra\fP Points to an associated \fBpcre[16]_extra\fP structure, - or is NULL - \fIsubject\fP Points to the subject string - \fIlength\fP Length of the subject string, in bytes - \fIstartoffset\fP Offset in bytes in the subject at which to - start matching - \fIoptions\fP Option bits - \fIovector\fP Points to a vector of ints for result offsets - \fIovecsize\fP Number of elements in the vector (a multiple of 3) -.sp -The options are: -.sp - PCRE_ANCHORED Match only at the first position - PCRE_BSR_ANYCRLF \eR matches only CR, LF, or CRLF - PCRE_BSR_UNICODE \eR matches all Unicode line endings - PCRE_NEWLINE_ANY Recognize any Unicode newline sequence - PCRE_NEWLINE_ANYCRLF Recognize CR, LF, & CRLF as newline sequences - PCRE_NEWLINE_CR Recognize CR as the only newline sequence - PCRE_NEWLINE_CRLF Recognize CRLF as the only newline sequence - PCRE_NEWLINE_LF Recognize LF as the only newline sequence - PCRE_NOTBOL Subject string is not the beginning of a line - PCRE_NOTEOL Subject string is not the end of a line - PCRE_NOTEMPTY An empty string is not a valid match - PCRE_NOTEMPTY_ATSTART An empty string at the start of the subject - is not a valid match - PCRE_NO_START_OPTIMIZE Do not do "start-match" optimizations - PCRE_NO_UTF16_CHECK Do not check the subject for UTF-16 - validity (only relevant if PCRE_UTF16 - was set at compile time) - PCRE_NO_UTF8_CHECK Do not check the subject for UTF-8 - validity (only relevant if PCRE_UTF8 - was set at compile time) - PCRE_PARTIAL ) Return PCRE_ERROR_PARTIAL for a partial - PCRE_PARTIAL_SOFT ) match if no full matches are found - PCRE_PARTIAL_HARD Return PCRE_ERROR_PARTIAL for a partial match - if that is found before a full match -.sp -For details of partial matching, see the -.\" HREF -\fBpcrepartial\fP -.\" -page. A \fBpcre_extra\fP structure contains the following fields: -.sp - \fIflags\fP Bits indicating which fields are set - \fIstudy_data\fP Opaque data from \fBpcre[16]_study()\fP - \fImatch_limit\fP Limit on internal resource use - \fImatch_limit_recursion\fP Limit on internal recursion depth - \fIcallout_data\fP Opaque data passed back to callouts - \fItables\fP Points to character tables or is NULL - \fImark\fP For passing back a *MARK pointer - \fIexecutable_jit\fP Opaque data from JIT compilation -.sp -The flag bits are PCRE_EXTRA_STUDY_DATA, PCRE_EXTRA_MATCH_LIMIT, -PCRE_EXTRA_MATCH_LIMIT_RECURSION, PCRE_EXTRA_CALLOUT_DATA, -PCRE_EXTRA_TABLES, PCRE_EXTRA_MARK and PCRE_EXTRA_EXECUTABLE_JIT. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_free_study.3 b/gtk+-mingw/share/man/man3/pcre_free_study.3 deleted file mode 100644 index 9fd5d80..0000000 --- a/gtk+-mingw/share/man/man3/pcre_free_study.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH PCRE_FREE_STUDY 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_free_study(pcre_extra *\fIextra\fP); -.PP -.B void pcre16_free_study(pcre16_extra *\fIextra\fP); -. -.SH DESCRIPTION -.rs -.sp -This function is used to free the memory used for the data generated by a call -to \fBpcre[16]_study()\fP when it is no longer needed. The argument must be the -result of such a call. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_free_substring.3 b/gtk+-mingw/share/man/man3/pcre_free_substring.3 deleted file mode 100644 index dff5bb0..0000000 --- a/gtk+-mingw/share/man/man3/pcre_free_substring.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH PCRE_FREE_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_free_substring(const char *\fIstringptr\fP); -.PP -.B void pcre16_free_substring(PCRE_SPTR16 \fIstringptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for freeing the store obtained by a previous -call to \fBpcre[16]_get_substring()\fP or \fBpcre[16]_get_named_substring()\fP. -Its only argument is a pointer to the string. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_free_substring_list.3 b/gtk+-mingw/share/man/man3/pcre_free_substring_list.3 deleted file mode 100644 index a587759..0000000 --- a/gtk+-mingw/share/man/man3/pcre_free_substring_list.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH PCRE_FREE_SUBSTRING_LIST 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_free_substring_list(const char **\fIstringptr\fP); -.PP -.B void pcre16_free_substring_list(PCRE_SPTR16 *\fIstringptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for freeing the store obtained by a previous -call to \fBpcre[16]_get_substring_list()\fP. Its only argument is a pointer to -the list of string pointers. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_fullinfo.3 b/gtk+-mingw/share/man/man3/pcre_fullinfo.3 deleted file mode 100644 index 1c2a58f..0000000 --- a/gtk+-mingw/share/man/man3/pcre_fullinfo.3 +++ /dev/null @@ -1,78 +0,0 @@ -.TH PCRE_FULLINFO 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B int \fIwhat\fP, void *\fIwhere\fP); -.PP -.B int pcre16_fullinfo(const pcre16 *\fIcode\fP, "const pcre16_extra *\fIextra\fP," -.ti +5n -.B int \fIwhat\fP, void *\fIwhere\fP); -. -.SH DESCRIPTION -.rs -.sp -This function returns information about a compiled pattern. Its arguments are: -.sp - \fIcode\fP Compiled regular expression - \fIextra\fP Result of \fBpcre[16]_study()\fP or NULL - \fIwhat\fP What information is required - \fIwhere\fP Where to put the information -.sp -The following information is available: -.sp - PCRE_INFO_BACKREFMAX Number of highest back reference - PCRE_INFO_CAPTURECOUNT Number of capturing subpatterns - PCRE_INFO_DEFAULT_TABLES Pointer to default tables - PCRE_INFO_FIRSTBYTE Fixed first data unit for a match, or - -1 for start of string - or after newline, or - -2 otherwise - PCRE_INFO_FIRSTTABLE Table of first data units (after studying) - PCRE_INFO_HASCRORLF Return 1 if explicit CR or LF matches exist - PCRE_INFO_JCHANGED Return 1 if (?J) or (?-J) was used - PCRE_INFO_JIT Return 1 after successful JIT compilation - PCRE_INFO_JITSIZE Size of JIT compiled code - PCRE_INFO_LASTLITERAL Literal last data unit required - PCRE_INFO_MINLENGTH Lower bound length of matching strings - PCRE_INFO_NAMECOUNT Number of named subpatterns - PCRE_INFO_NAMEENTRYSIZE Size of name table entry - PCRE_INFO_NAMETABLE Pointer to name table - PCRE_INFO_OKPARTIAL Return 1 if partial matching can be tried - (always returns 1 after release 8.00) - PCRE_INFO_OPTIONS Option bits used for compilation - PCRE_INFO_SIZE Size of compiled pattern - PCRE_INFO_STUDYSIZE Size of study data -.sp -The \fIwhere\fP argument must point to an integer variable, except for the -following \fIwhat\fP values: -.sp - PCRE_INFO_DEFAULT_TABLES const unsigned char * - PCRE_INFO_FIRSTTABLE const unsigned char * - PCRE_INFO_NAMETABLE PCRE_SPTR16 (16-bit library) - PCRE_INFO_NAMETABLE const unsigned char * (8-bit library) - PCRE_INFO_OPTIONS unsigned long int - PCRE_INFO_SIZE size_t -.sp -The yield of the function is zero on success or: -.sp - PCRE_ERROR_NULL the argument \fIcode\fP was NULL - the argument \fIwhere\fP was NULL - PCRE_ERROR_BADMAGIC the "magic number" was not found - PCRE_ERROR_BADOPTION the value of \fIwhat\fP was invalid -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_get_named_substring.3 b/gtk+-mingw/share/man/man3/pcre_get_named_substring.3 deleted file mode 100644 index 88dd2da..0000000 --- a/gtk+-mingw/share/man/man3/pcre_get_named_substring.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH PCRE_GET_NAMED_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_named_substring(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, const char *\fIstringname\fP, -.ti +5n -.B const char **\fIstringptr\fP); -.PP -.B int pcre16_get_named_substring(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, PCRE_SPTR16 \fIstringname\fP, -.ti +5n -.B PCRE_SPTR16 *\fIstringptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a captured substring by name. The -arguments are: -.sp - \fIcode\fP Compiled pattern - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec()\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec()\fP - \fIstringname\fP Name of the required substring - \fIstringptr\fP Where to put the string pointer -.sp -The memory in which the substring is placed is obtained by calling -\fBpcre[16]_malloc()\fP. The convenience function -\fBpcre[16]_free_substring()\fP can be used to free it when it is no longer -needed. The yield of the function is the length of the extracted substring, -PCRE_ERROR_NOMEMORY if sufficient memory could not be obtained, or -PCRE_ERROR_NOSUBSTRING if the string name is invalid. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_get_stringnumber.3 b/gtk+-mingw/share/man/man3/pcre_get_stringnumber.3 deleted file mode 100644 index 79c52dc..0000000 --- a/gtk+-mingw/share/man/man3/pcre_get_stringnumber.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH PCRE_GET_STRINGNUMBER 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_stringnumber(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIname\fP); -.PP -.B int pcre16_get_stringnumber(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIname\fP); -. -.SH DESCRIPTION -.rs -.sp -This convenience function finds the number of a named substring capturing -parenthesis in a compiled pattern. Its arguments are: -.sp - \fIcode\fP Compiled regular expression - \fIname\fP Name whose number is required -.sp -The yield of the function is the number of the parenthesis if the name is -found, or PCRE_ERROR_NOSUBSTRING otherwise. When duplicate names are allowed -(PCRE_DUPNAMES is set), it is not defined which of the numbers is returned by -\fBpcre[16]_get_stringnumber()\fP. You can obtain the complete list by calling -\fBpcre[16]_get_stringtable_entries()\fP. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_get_stringtable_entries.3 b/gtk+-mingw/share/man/man3/pcre_get_stringtable_entries.3 deleted file mode 100644 index a192e83..0000000 --- a/gtk+-mingw/share/man/man3/pcre_get_stringtable_entries.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH PCRE_GET_STRINGTABLE_ENTRIES 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP); -.PP -.B int pcre16_get_stringtable_entries(const pcre16 *\fIcode\fP, -.ti +5n -.B PCRE_SPTR16 \fIname\fP, PCRE_UCHAR16 **\fIfirst\fP, PCRE_UCHAR16 **\fIlast\fP); -. -.SH DESCRIPTION -.rs -.sp -This convenience function finds, for a compiled pattern, the first and last -entries for a given name in the table that translates capturing parenthesis -names into numbers. When names are required to be unique (PCRE_DUPNAMES is -\fInot\fP set), it is usually easier to use \fBpcre[16]_get_stringnumber()\fP -instead. -.sp - \fIcode\fP Compiled regular expression - \fIname\fP Name whose entries required - \fIfirst\fP Where to return a pointer to the first entry - \fIlast\fP Where to return a pointer to the last entry -.sp -The yield of the function is the length of each entry, or -PCRE_ERROR_NOSUBSTRING if none are found. -.P -There is a complete description of the PCRE native API, including the format of -the table entries, in the -.\" HREF -\fBpcreapi\fP -.\" -page, and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_get_substring.3 b/gtk+-mingw/share/man/man3/pcre_get_substring.3 deleted file mode 100644 index 3af1948..0000000 --- a/gtk+-mingw/share/man/man3/pcre_get_substring.3 +++ /dev/null @@ -1,49 +0,0 @@ -.TH PCRE_GET_SUBSTRING 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, -.ti +5n -.B const char **\fIstringptr\fP); -.PP -.B int pcre16_get_substring(PCRE_SPTR16 \fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, -.ti +5n -.B PCRE_SPTR16 *\fIstringptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a captured substring. The -arguments are: -.sp - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec()\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec()\fP - \fIstringnumber\fP Number of the required substring - \fIstringptr\fP Where to put the string pointer -.sp -The memory in which the substring is placed is obtained by calling -\fBpcre[16]_malloc()\fP. The convenience function -\fBpcre[16]_free_substring()\fP can be used to free it when it is no longer -needed. The yield of the function is the length of the substring, -PCRE_ERROR_NOMEMORY if sufficient memory could not be obtained, or -PCRE_ERROR_NOSUBSTRING if the string number is invalid. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_get_substring_list.3 b/gtk+-mingw/share/man/man3/pcre_get_substring_list.3 deleted file mode 100644 index 33c3a51..0000000 --- a/gtk+-mingw/share/man/man3/pcre_get_substring_list.3 +++ /dev/null @@ -1,45 +0,0 @@ -.TH PCRE_GET_SUBSTRING_LIST 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_get_substring_list(const char *\fIsubject\fP, -.ti +5n -.B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);" -.PP -.B int pcre16_get_substring_list(PCRE_SPTR16 \fIsubject\fP, -.ti +5n -.B int *\fIovector\fP, int \fIstringcount\fP, "PCRE_SPTR16 **\fIlistptr\fP);" -. -.SH DESCRIPTION -.rs -.sp -This is a convenience function for extracting a list of all the captured -substrings. The arguments are: -.sp - \fIsubject\fP Subject that has been successfully matched - \fIovector\fP Offset vector that \fBpcre[16]_exec\fP used - \fIstringcount\fP Value returned by \fBpcre[16]_exec\fP - \fIlistptr\fP Where to put a pointer to the list -.sp -The memory in which the substrings and the list are placed is obtained by -calling \fBpcre[16]_malloc()\fP. The convenience function -\fBpcre[16]_free_substring_list()\fP can be used to free it when it is no -longer needed. A pointer to a list of pointers is put in the variable whose -address is in \fIlistptr\fP. The list is terminated by a NULL pointer. The -yield of the function is zero on success or PCRE_ERROR_NOMEMORY if sufficient -memory could not be obtained. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_jit_stack_alloc.3 b/gtk+-mingw/share/man/man3/pcre_jit_stack_alloc.3 deleted file mode 100644 index b488d85..0000000 --- a/gtk+-mingw/share/man/man3/pcre_jit_stack_alloc.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH PCRE_JIT_STACK_ALLOC 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B pcre_jit_stack *pcre_jit_stack_alloc(int \fIstartsize\fP, -.ti +5n -.B int \fImaxsize\fP); -.PP -.B pcre16_jit_stack *pcre16_jit_stack_alloc(int \fIstartsize\fP, -.ti +5n -.B int \fImaxsize\fP); -. -.SH DESCRIPTION -.rs -.sp -This function is used to create a stack for use by the code compiled by the JIT -optimization of \fBpcre[16]_study()\fP. The arguments are a starting size for -the stack, and a maximum size to which it is allowed to grow. The result can be -passed to the JIT run-time code by \fBpcre[16]_assign_jit_stack()\fP, or that -function can set up a callback for obtaining a stack. A maximum stack size of -512K to 1M should be more than enough for any pattern. For more details, see -the -.\" HREF -\fBpcrejit\fP -.\" -page. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_jit_stack_free.3 b/gtk+-mingw/share/man/man3/pcre_jit_stack_free.3 deleted file mode 100644 index 9f6528b..0000000 --- a/gtk+-mingw/share/man/man3/pcre_jit_stack_free.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH PCRE_JIT_STACK_FREE 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B void pcre_jit_stack_free(pcre_jit_stack *\fIstack\fP); -.PP -.B void pcre16_jit_stack_free(pcre16_jit_stack *\fIstack\fP); -. -.SH DESCRIPTION -.rs -.sp -This function is used to free a JIT stack that was created by -\fBpcre[16]_jit_stack_alloc()\fP when it is no longer needed. For more details, -see the -.\" HREF -\fBpcrejit\fP -.\" -page. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_maketables.3 b/gtk+-mingw/share/man/man3/pcre_maketables.3 deleted file mode 100644 index 73b188b..0000000 --- a/gtk+-mingw/share/man/man3/pcre_maketables.3 +++ /dev/null @@ -1,31 +0,0 @@ -.TH PCRE_MAKETABLES 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B const unsigned char *pcre_maketables(void); -.PP -.B const unsigned char *pcre16_maketables(void); -. -.SH DESCRIPTION -.rs -.sp -This function builds a set of character tables for character values less than -256. These can be passed to \fBpcre[16]_compile()\fP to override PCRE's -internal, built-in tables (which were made by \fBpcre[16]_maketables()\fP when -PCRE was compiled). You might want to do this if you are using a non-standard -locale. The function yields a pointer to the tables. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_pattern_to_host_byte_order.3 b/gtk+-mingw/share/man/man3/pcre_pattern_to_host_byte_order.3 deleted file mode 100644 index 8c34473..0000000 --- a/gtk+-mingw/share/man/man3/pcre_pattern_to_host_byte_order.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH PCRE_PATTERN_TO_HOST_BYTE_ORDER 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_pattern_to_host_byte_order(pcre *\fIcode\fP, -.ti +5n -.B pcre_extra *\fIextra\fP, const unsigned char *\fItables\fP); -.PP -.B int pcre16_pattern_to_host_byte_order(pcre16 *\fIcode\fP, -.ti +5n -.B pcre16_extra *\fIextra\fP, const unsigned char *\fItables\fP); -. -. -.SH DESCRIPTION -.rs -.sp -This function ensures that the bytes in 2-byte and 4-byte values in a compiled -pattern are in the correct order for the current host. It is useful when a -pattern that has been compiled on one host is transferred to another that might -have different endianness. The arguments are: -.sp - \fIcode\fP A compiled regular expression - \fIextra\fP Points to an associated \fBpcre[16]_extra\fP structure, - or is NULL - \fItables\fP Pointer to character tables, or NULL to - set the built-in default -.sp -The result is 0 for success, a negative PCRE_ERROR_xxx value otherwise. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_refcount.3 b/gtk+-mingw/share/man/man3/pcre_refcount.3 deleted file mode 100644 index a30eecf..0000000 --- a/gtk+-mingw/share/man/man3/pcre_refcount.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH PCRE_REFCOUNT 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP); -.PP -.B int pcre16_refcount(pcre16 *\fIcode\fP, int \fIadjust\fP); -. -.SH DESCRIPTION -.rs -.sp -This function is used to maintain a reference count inside a data block that -contains a compiled pattern. Its arguments are: -.sp - \fIcode\fP Compiled regular expression - \fIadjust\fP Adjustment to reference value -.sp -The yield of the function is the adjusted reference value, which is constrained -to lie between 0 and 65535. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_study.3 b/gtk+-mingw/share/man/man3/pcre_study.3 deleted file mode 100644 index 13ea6c4..0000000 --- a/gtk+-mingw/share/man/man3/pcre_study.3 +++ /dev/null @@ -1,52 +0,0 @@ -.TH PCRE_STUDY 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP); -.PP -.B pcre16_extra *pcre16_study(const pcre16 *\fIcode\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP); -. -.SH DESCRIPTION -.rs -.sp -This function studies a compiled pattern, to see if additional information can -be extracted that might speed up matching. Its arguments are: -.sp - \fIcode\fP A compiled regular expression - \fIoptions\fP Options for \fBpcre[16]_study()\fP - \fIerrptr\fP Where to put an error message -.sp -If the function succeeds, it returns a value that can be passed to -\fBpcre[16]_exec()\fP or \fBpcre[16]_dfa_exec()\fP via their \fIextra\fP -arguments. -.P -If the function returns NULL, either it could not find any additional -information, or there was an error. You can tell the difference by looking at -the error value. It is NULL in first case. -.P -The only option is PCRE_STUDY_JIT_COMPILE. It requests just-in-time compilation -if possible. If PCRE has been compiled without JIT support, this option is -ignored. See the -.\" HREF -\fBpcrejit\fP -.\" -page for further details. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_utf16_to_host_byte_order.3 b/gtk+-mingw/share/man/man3/pcre_utf16_to_host_byte_order.3 deleted file mode 100644 index 8f0d2d4..0000000 --- a/gtk+-mingw/share/man/man3/pcre_utf16_to_host_byte_order.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH PCRE_UTF16_TO_HOST_BYTE_ORDER 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B int pcre16_utf16_to_host_byte_order(PCRE_UCHAR16 *\fIoutput\fP, -.ti +5n -.B PCRE_SPTR16 \fIinput\fP, int \fIlength\fP, int *\fIhost_byte_order\fP, -.ti +5n -.B int \fIkeep_boms\fP); -. -. -.SH DESCRIPTION -.rs -.sp -This function, which exists only in the 16-bit library, converts a UTF-16 -string to the correct order for the current host, taking account of any byte -order marks (BOMs) within the string. Its arguments are: -.sp - \fIoutput\fP pointer to output buffer, may be the same as \fIinput\fP - \fIinput\fP pointer to input buffer - \fIlength\fP number of 16-bit units in the input, or negative for - a zero-terminated string - \fIhost_byte_order\fP a NULL value or a non-zero value pointed to means - start in host byte order - \fIkeep_boms\fP if non-zero, BOMs are copied to the output string -.sp -The result of the function is the number of 16-bit units placed into the output -buffer, including the zero terminator if the string was zero-terminated. -.P -If \fIhost_byte_order\fP is not NULL, it is set to indicate the byte order that -is current at the end of the string. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcre_version.3 b/gtk+-mingw/share/man/man3/pcre_version.3 deleted file mode 100644 index bcbd4f2..0000000 --- a/gtk+-mingw/share/man/man3/pcre_version.3 +++ /dev/null @@ -1,29 +0,0 @@ -.TH PCRE_VERSION 3 "13 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH SYNOPSIS -.rs -.sp -.B #include <pcre.h> -.PP -.SM -.B const char *pcre_version(void); -.PP -.B const char *pcre16_version(void); -. -.SH DESCRIPTION -.rs -.sp -This function (even in the 16-bit library) returns a zero-terminated, 8-bit -character string that gives the version number of the PCRE library and the date -of its release. -.P -There is a complete description of the PCRE native API in the -.\" HREF -\fBpcreapi\fP -.\" -page and a description of the POSIX API in the -.\" HREF -\fBpcreposix\fP -.\" -page. diff --git a/gtk+-mingw/share/man/man3/pcreapi.3 b/gtk+-mingw/share/man/man3/pcreapi.3 deleted file mode 100644 index 633f311..0000000 --- a/gtk+-mingw/share/man/man3/pcreapi.3 +++ /dev/null @@ -1,2672 +0,0 @@ -.TH PCREAPI 3 "04 May 2012" "PCRE 8.31" -.SH NAME -PCRE - Perl-compatible regular expressions -.sp -.B #include <pcre.h> -. -. -.SH "PCRE NATIVE API BASIC FUNCTIONS" -.rs -.sp -.SM -.B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.PP -.B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B int *\fIerrorcodeptr\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.PP -.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP); -.PP -.B void pcre_free_study(pcre_extra *\fIextra\fP); -.PP -.B int pcre_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP); -.PP -.B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP, -.ti +5n -.B int *\fIworkspace\fP, int \fIwscount\fP); -. -. -.SH "PCRE NATIVE API STRING EXTRACTION FUNCTIONS" -.rs -.sp -.B int pcre_copy_named_substring(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, const char *\fIstringname\fP, -.ti +5n -.B char *\fIbuffer\fP, int \fIbuffersize\fP); -.PP -.B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP, -.ti +5n -.B int \fIbuffersize\fP); -.PP -.B int pcre_get_named_substring(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, const char *\fIstringname\fP, -.ti +5n -.B const char **\fIstringptr\fP); -.PP -.B int pcre_get_stringnumber(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIname\fP); -.PP -.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP); -.PP -.B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, -.ti +5n -.B const char **\fIstringptr\fP); -.PP -.B int pcre_get_substring_list(const char *\fIsubject\fP, -.ti +5n -.B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);" -.PP -.B void pcre_free_substring(const char *\fIstringptr\fP); -.PP -.B void pcre_free_substring_list(const char **\fIstringptr\fP); -. -. -.SH "PCRE NATIVE API AUXILIARY FUNCTIONS" -.rs -.sp -.B pcre_jit_stack *pcre_jit_stack_alloc(int \fIstartsize\fP, int \fImaxsize\fP); -.PP -.B void pcre_jit_stack_free(pcre_jit_stack *\fIstack\fP); -.PP -.B void pcre_assign_jit_stack(pcre_extra *\fIextra\fP, -.ti +5n -.B pcre_jit_callback \fIcallback\fP, void *\fIdata\fP); -.PP -.B const unsigned char *pcre_maketables(void); -.PP -.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B int \fIwhat\fP, void *\fIwhere\fP); -.PP -.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP); -.PP -.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP); -.PP -.B const char *pcre_version(void); -.PP -.B int pcre_pattern_to_host_byte_order(pcre *\fIcode\fP, -.ti +5n -.B pcre_extra *\fIextra\fP, const unsigned char *\fItables\fP); -. -. -.SH "PCRE NATIVE API INDIRECTED FUNCTIONS" -.rs -.sp -.B void *(*pcre_malloc)(size_t); -.PP -.B void (*pcre_free)(void *); -.PP -.B void *(*pcre_stack_malloc)(size_t); -.PP -.B void (*pcre_stack_free)(void *); -.PP -.B int (*pcre_callout)(pcre_callout_block *); -. -. -.SH "PCRE 8-BIT AND 16-BIT LIBRARIES" -.rs -.sp -From release 8.30, PCRE can be compiled as a library for handling 16-bit -character strings as well as, or instead of, the original library that handles -8-bit character strings. To avoid too much complication, this document -describes the 8-bit versions of the functions, with only occasional references -to the 16-bit library. -.P -The 16-bit functions operate in the same way as their 8-bit counterparts; they -just use different data types for their arguments and results, and their names -start with \fBpcre16_\fP instead of \fBpcre_\fP. For every option that has UTF8 -in its name (for example, PCRE_UTF8), there is a corresponding 16-bit name with -UTF8 replaced by UTF16. This facility is in fact just cosmetic; the 16-bit -option names define the same bit values. -.P -References to bytes and UTF-8 in this document should be read as references to -16-bit data quantities and UTF-16 when using the 16-bit library, unless -specified otherwise. More details of the specific differences for the 16-bit -library are given in the -.\" HREF -\fBpcre16\fP -.\" -page. -. -. -.SH "PCRE API OVERVIEW" -.rs -.sp -PCRE has its own native API, which is described in this document. There are -also some wrapper functions (for the 8-bit library only) that correspond to the -POSIX regular expression API, but they do not give access to all the -functionality. They are described in the -.\" HREF -\fBpcreposix\fP -.\" -documentation. Both of these APIs define a set of C function calls. A C++ -wrapper (again for the 8-bit library only) is also distributed with PCRE. It is -documented in the -.\" HREF -\fBpcrecpp\fP -.\" -page. -.P -The native API C function prototypes are defined in the header file -\fBpcre.h\fP, and on Unix-like systems the (8-bit) library itself is called -\fBlibpcre\fP. It can normally be accessed by adding \fB-lpcre\fP to the -command for linking an application that uses PCRE. The header file defines the -macros PCRE_MAJOR and PCRE_MINOR to contain the major and minor release numbers -for the library. Applications can use these to include support for different -releases of PCRE. -.P -In a Windows environment, if you want to statically link an application program -against a non-dll \fBpcre.a\fP file, you must define PCRE_STATIC before -including \fBpcre.h\fP or \fBpcrecpp.h\fP, because otherwise the -\fBpcre_malloc()\fP and \fBpcre_free()\fP exported functions will be declared -\fB__declspec(dllimport)\fP, with unwanted results. -.P -The functions \fBpcre_compile()\fP, \fBpcre_compile2()\fP, \fBpcre_study()\fP, -and \fBpcre_exec()\fP are used for compiling and matching regular expressions -in a Perl-compatible manner. A sample program that demonstrates the simplest -way of using them is provided in the file called \fIpcredemo.c\fP in the PCRE -source distribution. A listing of this program is given in the -.\" HREF -\fBpcredemo\fP -.\" -documentation, and the -.\" HREF -\fBpcresample\fP -.\" -documentation describes how to compile and run it. -.P -Just-in-time compiler support is an optional feature of PCRE that can be built -in appropriate hardware environments. It greatly speeds up the matching -performance of many patterns. Simple programs can easily request that it be -used if available, by setting an option that is ignored when it is not -relevant. More complicated programs might need to make use of the functions -\fBpcre_jit_stack_alloc()\fP, \fBpcre_jit_stack_free()\fP, and -\fBpcre_assign_jit_stack()\fP in order to control the JIT code's memory usage. -These functions are discussed in the -.\" HREF -\fBpcrejit\fP -.\" -documentation. -.P -A second matching function, \fBpcre_dfa_exec()\fP, which is not -Perl-compatible, is also provided. This uses a different algorithm for the -matching. The alternative algorithm finds all possible matches (at a given -point in the subject), and scans the subject just once (unless there are -lookbehind assertions). However, this algorithm does not return captured -substrings. A description of the two matching algorithms and their advantages -and disadvantages is given in the -.\" HREF -\fBpcrematching\fP -.\" -documentation. -.P -In addition to the main compiling and matching functions, there are convenience -functions for extracting captured substrings from a subject string that is -matched by \fBpcre_exec()\fP. They are: -.sp - \fBpcre_copy_substring()\fP - \fBpcre_copy_named_substring()\fP - \fBpcre_get_substring()\fP - \fBpcre_get_named_substring()\fP - \fBpcre_get_substring_list()\fP - \fBpcre_get_stringnumber()\fP - \fBpcre_get_stringtable_entries()\fP -.sp -\fBpcre_free_substring()\fP and \fBpcre_free_substring_list()\fP are also -provided, to free the memory used for extracted strings. -.P -The function \fBpcre_maketables()\fP is used to build a set of character tables -in the current locale for passing to \fBpcre_compile()\fP, \fBpcre_exec()\fP, -or \fBpcre_dfa_exec()\fP. This is an optional facility that is provided for -specialist use. Most commonly, no special tables are passed, in which case -internal tables that are generated when PCRE is built are used. -.P -The function \fBpcre_fullinfo()\fP is used to find out information about a -compiled pattern. The function \fBpcre_version()\fP returns a pointer to a -string containing the version of PCRE and its date of release. -.P -The function \fBpcre_refcount()\fP maintains a reference count in a data block -containing a compiled pattern. This is provided for the benefit of -object-oriented applications. -.P -The global variables \fBpcre_malloc\fP and \fBpcre_free\fP initially contain -the entry points of the standard \fBmalloc()\fP and \fBfree()\fP functions, -respectively. PCRE calls the memory management functions via these variables, -so a calling program can replace them if it wishes to intercept the calls. This -should be done before calling any PCRE functions. -.P -The global variables \fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP are also -indirections to memory management functions. These special functions are used -only when PCRE is compiled to use the heap for remembering data, instead of -recursive function calls, when running the \fBpcre_exec()\fP function. See the -.\" HREF -\fBpcrebuild\fP -.\" -documentation for details of how to do this. It is a non-standard way of -building PCRE, for use in environments that have limited stacks. Because of the -greater use of memory management, it runs more slowly. Separate functions are -provided so that special-purpose external code can be used for this case. When -used, these functions are always called in a stack-like manner (last obtained, -first freed), and always for memory blocks of the same size. There is a -discussion about PCRE's stack usage in the -.\" HREF -\fBpcrestack\fP -.\" -documentation. -.P -The global variable \fBpcre_callout\fP initially contains NULL. It can be set -by the caller to a "callout" function, which PCRE will then call at specified -points during a matching operation. Details are given in the -.\" HREF -\fBpcrecallout\fP -.\" -documentation. -. -. -.\" HTML <a name="newlines"></a> -.SH NEWLINES -.rs -.sp -PCRE supports five different conventions for indicating line breaks in -strings: a single CR (carriage return) character, a single LF (linefeed) -character, the two-character sequence CRLF, any of the three preceding, or any -Unicode newline sequence. The Unicode newline sequences are the three just -mentioned, plus the single characters VT (vertical tab, U+000B), FF (form feed, -U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS -(paragraph separator, U+2029). -.P -Each of the first three conventions is used by at least one operating system as -its standard newline sequence. When PCRE is built, a default can be specified. -The default default is LF, which is the Unix standard. When PCRE is run, the -default can be overridden, either when a pattern is compiled, or when it is -matched. -.P -At compile time, the newline convention can be specified by the \fIoptions\fP -argument of \fBpcre_compile()\fP, or it can be specified by special text at the -start of the pattern itself; this overrides any other settings. See the -.\" HREF -\fBpcrepattern\fP -.\" -page for details of the special character sequences. -.P -In the PCRE documentation the word "newline" is used to mean "the character or -pair of characters that indicate a line break". The choice of newline -convention affects the handling of the dot, circumflex, and dollar -metacharacters, the handling of #-comments in /x mode, and, when CRLF is a -recognized line ending sequence, the match position advancement for a -non-anchored pattern. There is more detail about this in the -.\" HTML <a href="#execoptions"> -.\" </a> -section on \fBpcre_exec()\fP options -.\" -below. -.P -The choice of newline convention does not affect the interpretation of -the \en or \er escape sequences, nor does it affect what \eR matches, which is -controlled in a similar way, but by separate options. -. -. -.SH MULTITHREADING -.rs -.sp -The PCRE functions can be used in multi-threading applications, with the -proviso that the memory management functions pointed to by \fBpcre_malloc\fP, -\fBpcre_free\fP, \fBpcre_stack_malloc\fP, and \fBpcre_stack_free\fP, and the -callout function pointed to by \fBpcre_callout\fP, are shared by all threads. -.P -The compiled form of a regular expression is not altered during matching, so -the same compiled pattern can safely be used by several threads at once. -.P -If the just-in-time optimization feature is being used, it needs separate -memory stack areas for each thread. See the -.\" HREF -\fBpcrejit\fP -.\" -documentation for more details. -. -. -.SH "SAVING PRECOMPILED PATTERNS FOR LATER USE" -.rs -.sp -The compiled form of a regular expression can be saved and re-used at a later -time, possibly by a different program, and even on a host other than the one on -which it was compiled. Details are given in the -.\" HREF -\fBpcreprecompile\fP -.\" -documentation, which includes a description of the -\fBpcre_pattern_to_host_byte_order()\fP function. However, compiling a regular -expression with one version of PCRE for use with a different version is not -guaranteed to work and may cause crashes. -. -. -.SH "CHECKING BUILD-TIME OPTIONS" -.rs -.sp -.B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP); -.PP -The function \fBpcre_config()\fP makes it possible for a PCRE client to -discover which optional features have been compiled into the PCRE library. The -.\" HREF -\fBpcrebuild\fP -.\" -documentation has more details about these optional features. -.P -The first argument for \fBpcre_config()\fP is an integer, specifying which -information is required; the second argument is a pointer to a variable into -which the information is placed. The returned value is zero on success, or the -negative error code PCRE_ERROR_BADOPTION if the value in the first argument is -not recognized. The following information is available: -.sp - PCRE_CONFIG_UTF8 -.sp -The output is an integer that is set to one if UTF-8 support is available; -otherwise it is set to zero. If this option is given to the 16-bit version of -this function, \fBpcre16_config()\fP, the result is PCRE_ERROR_BADOPTION. -.sp - PCRE_CONFIG_UTF16 -.sp -The output is an integer that is set to one if UTF-16 support is available; -otherwise it is set to zero. This value should normally be given to the 16-bit -version of this function, \fBpcre16_config()\fP. If it is given to the 8-bit -version of this function, the result is PCRE_ERROR_BADOPTION. -.sp - PCRE_CONFIG_UNICODE_PROPERTIES -.sp -The output is an integer that is set to one if support for Unicode character -properties is available; otherwise it is set to zero. -.sp - PCRE_CONFIG_JIT -.sp -The output is an integer that is set to one if support for just-in-time -compiling is available; otherwise it is set to zero. -.sp - PCRE_CONFIG_JITTARGET -.sp -The output is a pointer to a zero-terminated "const char *" string. If JIT -support is available, the string contains the name of the architecture for -which the JIT compiler is configured, for example "x86 32bit (little endian + -unaligned)". If JIT support is not available, the result is NULL. -.sp - PCRE_CONFIG_NEWLINE -.sp -The output is an integer whose value specifies the default character sequence -that is recognized as meaning "newline". The four values that are supported -are: 10 for LF, 13 for CR, 3338 for CRLF, -2 for ANYCRLF, and -1 for ANY. -Though they are derived from ASCII, the same values are returned in EBCDIC -environments. The default should normally correspond to the standard sequence -for your operating system. -.sp - PCRE_CONFIG_BSR -.sp -The output is an integer whose value indicates what character sequences the \eR -escape sequence matches by default. A value of 0 means that \eR matches any -Unicode line ending sequence; a value of 1 means that \eR matches only CR, LF, -or CRLF. The default can be overridden when a pattern is compiled or matched. -.sp - PCRE_CONFIG_LINK_SIZE -.sp -The output is an integer that contains the number of bytes used for internal -linkage in compiled regular expressions. For the 8-bit library, the value can -be 2, 3, or 4. For the 16-bit library, the value is either 2 or 4 and is still -a number of bytes. The default value of 2 is sufficient for all but the most -massive patterns, since it allows the compiled pattern to be up to 64K in size. -Larger values allow larger regular expressions to be compiled, at the expense -of slower matching. -.sp - PCRE_CONFIG_POSIX_MALLOC_THRESHOLD -.sp -The output is an integer that contains the threshold above which the POSIX -interface uses \fBmalloc()\fP for output vectors. Further details are given in -the -.\" HREF -\fBpcreposix\fP -.\" -documentation. -.sp - PCRE_CONFIG_MATCH_LIMIT -.sp -The output is a long integer that gives the default limit for the number of -internal matching function calls in a \fBpcre_exec()\fP execution. Further -details are given with \fBpcre_exec()\fP below. -.sp - PCRE_CONFIG_MATCH_LIMIT_RECURSION -.sp -The output is a long integer that gives the default limit for the depth of -recursion when calling the internal matching function in a \fBpcre_exec()\fP -execution. Further details are given with \fBpcre_exec()\fP below. -.sp - PCRE_CONFIG_STACKRECURSE -.sp -The output is an integer that is set to one if internal recursion when running -\fBpcre_exec()\fP is implemented by recursive function calls that use the stack -to remember their state. This is the usual way that PCRE is compiled. The -output is zero if PCRE was compiled to use blocks of data on the heap instead -of recursive function calls. In this case, \fBpcre_stack_malloc\fP and -\fBpcre_stack_free\fP are called to manage memory blocks on the heap, thus -avoiding the use of the stack. -. -. -.SH "COMPILING A PATTERN" -.rs -.sp -.B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.sp -.B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP, -.ti +5n -.B int *\fIerrorcodeptr\fP, -.ti +5n -.B const char **\fIerrptr\fP, int *\fIerroffset\fP, -.ti +5n -.B const unsigned char *\fItableptr\fP); -.P -Either of the functions \fBpcre_compile()\fP or \fBpcre_compile2()\fP can be -called to compile a pattern into an internal form. The only difference between -the two interfaces is that \fBpcre_compile2()\fP has an additional argument, -\fIerrorcodeptr\fP, via which a numerical error code can be returned. To avoid -too much repetition, we refer just to \fBpcre_compile()\fP below, but the -information applies equally to \fBpcre_compile2()\fP. -.P -The pattern is a C string terminated by a binary zero, and is passed in the -\fIpattern\fP argument. A pointer to a single block of memory that is obtained -via \fBpcre_malloc\fP is returned. This contains the compiled code and related -data. The \fBpcre\fP type is defined for the returned block; this is a typedef -for a structure whose contents are not externally defined. It is up to the -caller to free the memory (via \fBpcre_free\fP) when it is no longer required. -.P -Although the compiled code of a PCRE regex is relocatable, that is, it does not -depend on memory location, the complete \fBpcre\fP data block is not -fully relocatable, because it may contain a copy of the \fItableptr\fP -argument, which is an address (see below). -.P -The \fIoptions\fP argument contains various bit settings that affect the -compilation. It should be zero if no options are required. The available -options are described below. Some of them (in particular, those that are -compatible with Perl, but some others as well) can also be set and unset from -within the pattern (see the detailed description in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation). For those options that can be different in different parts of -the pattern, the contents of the \fIoptions\fP argument specifies their -settings at the start of compilation and execution. The PCRE_ANCHORED, -PCRE_BSR_\fIxxx\fP, PCRE_NEWLINE_\fIxxx\fP, PCRE_NO_UTF8_CHECK, and -PCRE_NO_START_OPTIMIZE options can be set at the time of matching as well as at -compile time. -.P -If \fIerrptr\fP is NULL, \fBpcre_compile()\fP returns NULL immediately. -Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fP returns -NULL, and sets the variable pointed to by \fIerrptr\fP to point to a textual -error message. This is a static string that is part of the library. You must -not try to free it. Normally, the offset from the start of the pattern to the -byte that was being processed when the error was discovered is placed in the -variable pointed to by \fIerroffset\fP, which must not be NULL (if it is, an -immediate error is given). However, for an invalid UTF-8 string, the offset is -that of the first byte of the failing character. -.P -Some errors are not detected until the whole pattern has been scanned; in these -cases, the offset passed back is the length of the pattern. Note that the -offset is in bytes, not characters, even in UTF-8 mode. It may sometimes point -into the middle of a UTF-8 character. -.P -If \fBpcre_compile2()\fP is used instead of \fBpcre_compile()\fP, and the -\fIerrorcodeptr\fP argument is not NULL, a non-zero error code number is -returned via this argument in the event of an error. This is in addition to the -textual error message. Error codes and messages are listed below. -.P -If the final argument, \fItableptr\fP, is NULL, PCRE uses a default set of -character tables that are built when PCRE is compiled, using the default C -locale. Otherwise, \fItableptr\fP must be an address that is the result of a -call to \fBpcre_maketables()\fP. This value is stored with the compiled -pattern, and used again by \fBpcre_exec()\fP, unless another table pointer is -passed to it. For more discussion, see the section on locale support below. -.P -This code fragment shows a typical straightforward call to \fBpcre_compile()\fP: -.sp - pcre *re; - const char *error; - int erroffset; - re = pcre_compile( - "^A.*Z", /* the pattern */ - 0, /* default options */ - &error, /* for error message */ - &erroffset, /* for error offset */ - NULL); /* use default character tables */ -.sp -The following names for option bits are defined in the \fBpcre.h\fP header -file: -.sp - PCRE_ANCHORED -.sp -If this bit is set, the pattern is forced to be "anchored", that is, it is -constrained to match only at the first matching point in the string that is -being searched (the "subject string"). This effect can also be achieved by -appropriate constructs in the pattern itself, which is the only way to do it in -Perl. -.sp - PCRE_AUTO_CALLOUT -.sp -If this bit is set, \fBpcre_compile()\fP automatically inserts callout items, -all with number 255, before each pattern item. For discussion of the callout -facility, see the -.\" HREF -\fBpcrecallout\fP -.\" -documentation. -.sp - PCRE_BSR_ANYCRLF - PCRE_BSR_UNICODE -.sp -These options (which are mutually exclusive) control what the \eR escape -sequence matches. The choice is either to match only CR, LF, or CRLF, or to -match any Unicode newline sequence. The default is specified when PCRE is -built. It can be overridden from within the pattern, or by setting an option -when a compiled pattern is matched. -.sp - PCRE_CASELESS -.sp -If this bit is set, letters in the pattern match both upper and lower case -letters. It is equivalent to Perl's /i option, and it can be changed within a -pattern by a (?i) option setting. In UTF-8 mode, PCRE always understands the -concept of case for characters whose values are less than 128, so caseless -matching is always possible. For characters with higher values, the concept of -case is supported if PCRE is compiled with Unicode property support, but not -otherwise. If you want to use caseless matching for characters 128 and above, -you must ensure that PCRE is compiled with Unicode property support as well as -with UTF-8 support. -.sp - PCRE_DOLLAR_ENDONLY -.sp -If this bit is set, a dollar metacharacter in the pattern matches only at the -end of the subject string. Without this option, a dollar also matches -immediately before a newline at the end of the string (but not before any other -newlines). The PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set. -There is no equivalent to this option in Perl, and no way to set it within a -pattern. -.sp - PCRE_DOTALL -.sp -If this bit is set, a dot metacharacter in the pattern matches a character of -any value, including one that indicates a newline. However, it only ever -matches one character, even if newlines are coded as CRLF. Without this option, -a dot does not match when the current position is at a newline. This option is -equivalent to Perl's /s option, and it can be changed within a pattern by a -(?s) option setting. A negative class such as [^a] always matches newline -characters, independent of the setting of this option. -.sp - PCRE_DUPNAMES -.sp -If this bit is set, names used to identify capturing subpatterns need not be -unique. This can be helpful for certain types of pattern when it is known that -only one instance of the named subpattern can ever be matched. There are more -details of named subpatterns below; see also the -.\" HREF -\fBpcrepattern\fP -.\" -documentation. -.sp - PCRE_EXTENDED -.sp -If this bit is set, white space data characters in the pattern are totally -ignored except when escaped or inside a character class. White space does not -include the VT character (code 11). In addition, characters between an -unescaped # outside a character class and the next newline, inclusive, are also -ignored. This is equivalent to Perl's /x option, and it can be changed within a -pattern by a (?x) option setting. -.P -Which characters are interpreted as newlines is controlled by the options -passed to \fBpcre_compile()\fP or by a special sequence at the start of the -pattern, as described in the section entitled -.\" HTML <a href="pcrepattern.html#newlines"> -.\" </a> -"Newline conventions" -.\" -in the \fBpcrepattern\fP documentation. Note that the end of this type of -comment is a literal newline sequence in the pattern; escape sequences that -happen to represent a newline do not count. -.P -This option makes it possible to include comments inside complicated patterns. -Note, however, that this applies only to data characters. White space characters -may never appear within special character sequences in a pattern, for example -within the sequence (?( that introduces a conditional subpattern. -.sp - PCRE_EXTRA -.sp -This option was invented in order to turn on additional functionality of PCRE -that is incompatible with Perl, but it is currently of very little use. When -set, any backslash in a pattern that is followed by a letter that has no -special meaning causes an error, thus reserving these combinations for future -expansion. By default, as in Perl, a backslash followed by a letter with no -special meaning is treated as a literal. (Perl can, however, be persuaded to -give an error for this, by running it with the -w option.) There are at present -no other features controlled by this option. It can also be set by a (?X) -option setting within a pattern. -.sp - PCRE_FIRSTLINE -.sp -If this option is set, an unanchored pattern is required to match before or at -the first newline in the subject string, though the matched text may continue -over the newline. -.sp - PCRE_JAVASCRIPT_COMPAT -.sp -If this option is set, PCRE's behaviour is changed in some ways so that it is -compatible with JavaScript rather than Perl. The changes are as follows: -.P -(1) A lone closing square bracket in a pattern causes a compile-time error, -because this is illegal in JavaScript (by default it is treated as a data -character). Thus, the pattern AB]CD becomes illegal when this option is set. -.P -(2) At run time, a back reference to an unset subpattern group matches an empty -string (by default this causes the current matching alternative to fail). A -pattern such as (\e1)(a) succeeds when this option is set (assuming it can find -an "a" in the subject), whereas it fails by default, for Perl compatibility. -.P -(3) \eU matches an upper case "U" character; by default \eU causes a compile -time error (Perl uses \eU to upper case subsequent characters). -.P -(4) \eu matches a lower case "u" character unless it is followed by four -hexadecimal digits, in which case the hexadecimal number defines the code point -to match. By default, \eu causes a compile time error (Perl uses it to upper -case the following character). -.P -(5) \ex matches a lower case "x" character unless it is followed by two -hexadecimal digits, in which case the hexadecimal number defines the code point -to match. By default, as in Perl, a hexadecimal number is always expected after -\ex, but it may have zero, one, or two digits (so, for example, \exz matches a -binary zero character followed by z). -.sp - PCRE_MULTILINE -.sp -By default, PCRE treats the subject string as consisting of a single line of -characters (even if it actually contains newlines). The "start of line" -metacharacter (^) matches only at the start of the string, while the "end of -line" metacharacter ($) matches only at the end of the string, or before a -terminating newline (unless PCRE_DOLLAR_ENDONLY is set). This is the same as -Perl. -.P -When PCRE_MULTILINE it is set, the "start of line" and "end of line" constructs -match immediately following or immediately before internal newlines in the -subject string, respectively, as well as at the very start and end. This is -equivalent to Perl's /m option, and it can be changed within a pattern by a -(?m) option setting. If there are no newlines in a subject string, or no -occurrences of ^ or $ in a pattern, setting PCRE_MULTILINE has no effect. -.sp - PCRE_NEWLINE_CR - PCRE_NEWLINE_LF - PCRE_NEWLINE_CRLF - PCRE_NEWLINE_ANYCRLF - PCRE_NEWLINE_ANY -.sp -These options override the default newline definition that was chosen when PCRE -was built. Setting the first or the second specifies that a newline is -indicated by a single character (CR or LF, respectively). Setting -PCRE_NEWLINE_CRLF specifies that a newline is indicated by the two-character -CRLF sequence. Setting PCRE_NEWLINE_ANYCRLF specifies that any of the three -preceding sequences should be recognized. Setting PCRE_NEWLINE_ANY specifies -that any Unicode newline sequence should be recognized. The Unicode newline -sequences are the three just mentioned, plus the single characters VT (vertical -tab, U+000B), FF (form feed, U+000C), NEL (next line, U+0085), LS (line -separator, U+2028), and PS (paragraph separator, U+2029). For the 8-bit -library, the last two are recognized only in UTF-8 mode. -.P -The newline setting in the options word uses three bits that are treated -as a number, giving eight possibilities. Currently only six are used (default -plus the five values above). This means that if you set more than one newline -option, the combination may or may not be sensible. For example, -PCRE_NEWLINE_CR with PCRE_NEWLINE_LF is equivalent to PCRE_NEWLINE_CRLF, but -other combinations may yield unused numbers and cause an error. -.P -The only time that a line break in a pattern is specially recognized when -compiling is when PCRE_EXTENDED is set. CR and LF are white space characters, -and so are ignored in this mode. Also, an unescaped # outside a character class -indicates a comment that lasts until after the next line break sequence. In -other circumstances, line break sequences in patterns are treated as literal -data. -.P -The newline option that is set at compile time becomes the default that is used -for \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, but it can be overridden. -.sp - PCRE_NO_AUTO_CAPTURE -.sp -If this option is set, it disables the use of numbered capturing parentheses in -the pattern. Any opening parenthesis that is not followed by ? behaves as if it -were followed by ?: but named parentheses can still be used for capturing (and -they acquire numbers in the usual way). There is no equivalent of this option -in Perl. -.sp - NO_START_OPTIMIZE -.sp -This is an option that acts at matching time; that is, it is really an option -for \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP. If it is set at compile time, -it is remembered with the compiled pattern and assumed at matching time. For -details see the discussion of PCRE_NO_START_OPTIMIZE -.\" HTML <a href="#execoptions"> -.\" </a> -below. -.\" -.sp - PCRE_UCP -.sp -This option changes the way PCRE processes \eB, \eb, \eD, \ed, \eS, \es, \eW, -\ew, and some of the POSIX character classes. By default, only ASCII characters -are recognized, but if PCRE_UCP is set, Unicode properties are used instead to -classify characters. More details are given in the section on -.\" HTML <a href="pcre.html#genericchartypes"> -.\" </a> -generic character types -.\" -in the -.\" HREF -\fBpcrepattern\fP -.\" -page. If you set PCRE_UCP, matching one of the items it affects takes much -longer. The option is available only if PCRE has been compiled with Unicode -property support. -.sp - PCRE_UNGREEDY -.sp -This option inverts the "greediness" of the quantifiers so that they are not -greedy by default, but become greedy if followed by "?". It is not compatible -with Perl. It can also be set by a (?U) option setting within the pattern. -.sp - PCRE_UTF8 -.sp -This option causes PCRE to regard both the pattern and the subject as strings -of UTF-8 characters instead of single-byte strings. However, it is available -only when PCRE is built to include UTF support. If not, the use of this option -provokes an error. Details of how this option changes the behaviour of PCRE are -given in the -.\" HREF -\fBpcreunicode\fP -.\" -page. -.sp - PCRE_NO_UTF8_CHECK -.sp -When PCRE_UTF8 is set, the validity of the pattern as a UTF-8 -string is automatically checked. There is a discussion about the -.\" HTML <a href="pcreunicode.html#utf8strings"> -.\" </a> -validity of UTF-8 strings -.\" -in the -.\" HREF -\fBpcreunicode\fP -.\" -page. If an invalid UTF-8 sequence is found, \fBpcre_compile()\fP returns an -error. If you already know that your pattern is valid, and you want to skip -this check for performance reasons, you can set the PCRE_NO_UTF8_CHECK option. -When it is set, the effect of passing an invalid UTF-8 string as a pattern is -undefined. It may cause your program to crash. Note that this option can also -be passed to \fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP, to suppress the -validity checking of subject strings. -. -. -.SH "COMPILATION ERROR CODES" -.rs -.sp -The following table lists the error codes than may be returned by -\fBpcre_compile2()\fP, along with the error messages that may be returned by -both compiling functions. Note that error messages are always 8-bit ASCII -strings, even in 16-bit mode. As PCRE has developed, some error codes have -fallen out of use. To avoid confusion, they have not been re-used. -.sp - 0 no error - 1 \e at end of pattern - 2 \ec at end of pattern - 3 unrecognized character follows \e - 4 numbers out of order in {} quantifier - 5 number too big in {} quantifier - 6 missing terminating ] for character class - 7 invalid escape sequence in character class - 8 range out of order in character class - 9 nothing to repeat - 10 [this code is not in use] - 11 internal error: unexpected repeat - 12 unrecognized character after (? or (?- - 13 POSIX named classes are supported only within a class - 14 missing ) - 15 reference to non-existent subpattern - 16 erroffset passed as NULL - 17 unknown option bit(s) set - 18 missing ) after comment - 19 [this code is not in use] - 20 regular expression is too large - 21 failed to get memory - 22 unmatched parentheses - 23 internal error: code overflow - 24 unrecognized character after (?< - 25 lookbehind assertion is not fixed length - 26 malformed number or name after (?( - 27 conditional group contains more than two branches - 28 assertion expected after (?( - 29 (?R or (?[+-]digits must be followed by ) - 30 unknown POSIX class name - 31 POSIX collating elements are not supported - 32 this version of PCRE is compiled without UTF support - 33 [this code is not in use] - 34 character value in \ex{...} sequence is too large - 35 invalid condition (?(0) - 36 \eC not allowed in lookbehind assertion - 37 PCRE does not support \eL, \el, \eN{name}, \eU, or \eu - 38 number after (?C is > 255 - 39 closing ) for (?C expected - 40 recursive call could loop indefinitely - 41 unrecognized character after (?P - 42 syntax error in subpattern name (missing terminator) - 43 two named subpatterns have the same name - 44 invalid UTF-8 string (specifically UTF-8) - 45 support for \eP, \ep, and \eX has not been compiled - 46 malformed \eP or \ep sequence - 47 unknown property name after \eP or \ep - 48 subpattern name is too long (maximum 32 characters) - 49 too many named subpatterns (maximum 10000) - 50 [this code is not in use] - 51 octal value is greater than \e377 in 8-bit non-UTF-8 mode - 52 internal error: overran compiling workspace - 53 internal error: previously-checked referenced subpattern - not found - 54 DEFINE group contains more than one branch - 55 repeating a DEFINE group is not allowed - 56 inconsistent NEWLINE options - 57 \eg is not followed by a braced, angle-bracketed, or quoted - name/number or by a plain number - 58 a numbered reference must not be zero - 59 an argument is not allowed for (*ACCEPT), (*FAIL), or (*COMMIT) - 60 (*VERB) not recognized - 61 number is too big - 62 subpattern name expected - 63 digit expected after (?+ - 64 ] is an invalid data character in JavaScript compatibility mode - 65 different names for subpatterns of the same number are - not allowed - 66 (*MARK) must have an argument - 67 this version of PCRE is not compiled with Unicode property - support - 68 \ec must be followed by an ASCII character - 69 \ek is not followed by a braced, angle-bracketed, or quoted name - 70 internal error: unknown opcode in find_fixedlength() - 71 \eN is not supported in a class - 72 too many forward references - 73 disallowed Unicode code point (>= 0xd800 && <= 0xdfff) - 74 invalid UTF-16 string (specifically UTF-16) - 75 name is too long in (*MARK), (*PRUNE), (*SKIP), or (*THEN) - 76 character value in \eu.... sequence is too large -.sp -The numbers 32 and 10000 in errors 48 and 49 are defaults; different values may -be used if the limits were changed when PCRE was built. -. -. -.\" HTML <a name="studyingapattern"></a> -.SH "STUDYING A PATTERN" -.rs -.sp -.B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP -.ti +5n -.B const char **\fIerrptr\fP); -.PP -If a compiled pattern is going to be used several times, it is worth spending -more time analyzing it in order to speed up the time taken for matching. The -function \fBpcre_study()\fP takes a pointer to a compiled pattern as its first -argument. If studying the pattern produces additional information that will -help speed up matching, \fBpcre_study()\fP returns a pointer to a -\fBpcre_extra\fP block, in which the \fIstudy_data\fP field points to the -results of the study. -.P -The returned value from \fBpcre_study()\fP can be passed directly to -\fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP. However, a \fBpcre_extra\fP block -also contains other fields that can be set by the caller before the block is -passed; these are described -.\" HTML <a href="#extradata"> -.\" </a> -below -.\" -in the section on matching a pattern. -.P -If studying the pattern does not produce any useful information, -\fBpcre_study()\fP returns NULL. In that circumstance, if the calling program -wants to pass any of the other fields to \fBpcre_exec()\fP or -\fBpcre_dfa_exec()\fP, it must set up its own \fBpcre_extra\fP block. -.P -The second argument of \fBpcre_study()\fP contains option bits. There are three -options: -.sp - PCRE_STUDY_JIT_COMPILE - PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE - PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE -.sp -If any of these are set, and the just-in-time compiler is available, the -pattern is further compiled into machine code that executes much faster than -the \fBpcre_exec()\fP interpretive matching function. If the just-in-time -compiler is not available, these options are ignored. All other bits in the -\fIoptions\fP argument must be zero. -.P -JIT compilation is a heavyweight optimization. It can take some time for -patterns to be analyzed, and for one-off matches and simple patterns the -benefit of faster execution might be offset by a much slower study time. -Not all patterns can be optimized by the JIT compiler. For those that cannot be -handled, matching automatically falls back to the \fBpcre_exec()\fP -interpreter. For more details, see the -.\" HREF -\fBpcrejit\fP -.\" -documentation. -.P -The third argument for \fBpcre_study()\fP is a pointer for an error message. If -studying succeeds (even if no data is returned), the variable it points to is -set to NULL. Otherwise it is set to point to a textual error message. This is a -static string that is part of the library. You must not try to free it. You -should test the error pointer for NULL after calling \fBpcre_study()\fP, to be -sure that it has run successfully. -.P -When you are finished with a pattern, you can free the memory used for the -study data by calling \fBpcre_free_study()\fP. This function was added to the -API for release 8.20. For earlier versions, the memory could be freed with -\fBpcre_free()\fP, just like the pattern itself. This will still work in cases -where JIT optimization is not used, but it is advisable to change to the new -function when convenient. -.P -This is a typical way in which \fBpcre_study\fP() is used (except that in a -real application there should be tests for errors): -.sp - int rc; - pcre *re; - pcre_extra *sd; - re = pcre_compile("pattern", 0, &error, &erroroffset, NULL); - sd = pcre_study( - re, /* result of pcre_compile() */ - 0, /* no options */ - &error); /* set to NULL or points to a message */ - rc = pcre_exec( /* see below for details of pcre_exec() options */ - re, sd, "subject", 7, 0, 0, ovector, 30); - ... - pcre_free_study(sd); - pcre_free(re); -.sp -Studying a pattern does two things: first, a lower bound for the length of -subject string that is needed to match the pattern is computed. This does not -mean that there are any strings of that length that match, but it does -guarantee that no shorter strings match. The value is used by -\fBpcre_exec()\fP and \fBpcre_dfa_exec()\fP to avoid wasting time by trying to -match strings that are shorter than the lower bound. You can find out the value -in a calling program via the \fBpcre_fullinfo()\fP function. -.P -Studying a pattern is also useful for non-anchored patterns that do not have a -single fixed starting character. A bitmap of possible starting bytes is -created. This speeds up finding a position in the subject at which to start -matching. (In 16-bit mode, the bitmap is used for 16-bit values less than 256.) -.P -These two optimizations apply to both \fBpcre_exec()\fP and -\fBpcre_dfa_exec()\fP, and the information is also used by the JIT compiler. -The optimizations can be disabled by setting the PCRE_NO_START_OPTIMIZE option -when calling \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP, but if this is done, -JIT execution is also disabled. You might want to do this if your pattern -contains callouts or (*MARK) and you want to make use of these facilities in -cases where matching fails. See the discussion of PCRE_NO_START_OPTIMIZE -.\" HTML <a href="#execoptions"> -.\" </a> -below. -.\" -. -. -.\" HTML <a name="localesupport"></a> -.SH "LOCALE SUPPORT" -.rs -.sp -PCRE handles caseless matching, and determines whether characters are letters, -digits, or whatever, by reference to a set of tables, indexed by character -value. When running in UTF-8 mode, this applies only to characters -with codes less than 128. By default, higher-valued codes never match escapes -such as \ew or \ed, but they can be tested with \ep if PCRE is built with -Unicode character property support. Alternatively, the PCRE_UCP option can be -set at compile time; this causes \ew and friends to use Unicode property -support instead of built-in tables. The use of locales with Unicode is -discouraged. If you are handling characters with codes greater than 128, you -should either use UTF-8 and Unicode, or use locales, but not try to mix the -two. -.P -PCRE contains an internal set of tables that are used when the final argument -of \fBpcre_compile()\fP is NULL. These are sufficient for many applications. -Normally, the internal tables recognize only ASCII characters. However, when -PCRE is built, it is possible to cause the internal tables to be rebuilt in the -default "C" locale of the local system, which may cause them to be different. -.P -The internal tables can always be overridden by tables supplied by the -application that calls PCRE. These may be created in a different locale from -the default. As more and more applications change to using Unicode, the need -for this locale support is expected to die away. -.P -External tables are built by calling the \fBpcre_maketables()\fP function, -which has no arguments, in the relevant locale. The result can then be passed -to \fBpcre_compile()\fP or \fBpcre_exec()\fP as often as necessary. For -example, to build and use tables that are appropriate for the French locale -(where accented characters with values greater than 128 are treated as letters), -the following code could be used: -.sp - setlocale(LC_CTYPE, "fr_FR"); - tables = pcre_maketables(); - re = pcre_compile(..., tables); -.sp -The locale name "fr_FR" is used on Linux and other Unix-like systems; if you -are using Windows, the name for the French locale is "french". -.P -When \fBpcre_maketables()\fP runs, the tables are built in memory that is -obtained via \fBpcre_malloc\fP. It is the caller's responsibility to ensure -that the memory containing the tables remains available for as long as it is -needed. -.P -The pointer that is passed to \fBpcre_compile()\fP is saved with the compiled -pattern, and the same tables are used via this pointer by \fBpcre_study()\fP -and normally also by \fBpcre_exec()\fP. Thus, by default, for any single -pattern, compilation, studying and matching all happen in the same locale, but -different patterns can be compiled in different locales. -.P -It is possible to pass a table pointer or NULL (indicating the use of the -internal tables) to \fBpcre_exec()\fP. Although not intended for this purpose, -this facility could be used to match a pattern in a different locale from the -one in which it was compiled. Passing table pointers at run time is discussed -below in the section on matching a pattern. -. -. -.\" HTML <a name="infoaboutpattern"></a> -.SH "INFORMATION ABOUT A PATTERN" -.rs -.sp -.B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B int \fIwhat\fP, void *\fIwhere\fP); -.PP -The \fBpcre_fullinfo()\fP function returns information about a compiled -pattern. It replaces the \fBpcre_info()\fP function, which was removed from the -library at version 8.30, after more than 10 years of obsolescence. -.P -The first argument for \fBpcre_fullinfo()\fP is a pointer to the compiled -pattern. The second argument is the result of \fBpcre_study()\fP, or NULL if -the pattern was not studied. The third argument specifies which piece of -information is required, and the fourth argument is a pointer to a variable -to receive the data. The yield of the function is zero for success, or one of -the following negative numbers: -.sp - PCRE_ERROR_NULL the argument \fIcode\fP was NULL - the argument \fIwhere\fP was NULL - PCRE_ERROR_BADMAGIC the "magic number" was not found - PCRE_ERROR_BADENDIANNESS the pattern was compiled with different - endianness - PCRE_ERROR_BADOPTION the value of \fIwhat\fP was invalid -.sp -The "magic number" is placed at the start of each compiled pattern as an simple -check against passing an arbitrary memory pointer. The endianness error can -occur if a compiled pattern is saved and reloaded on a different host. Here is -a typical call of \fBpcre_fullinfo()\fP, to obtain the length of the compiled -pattern: -.sp - int rc; - size_t length; - rc = pcre_fullinfo( - re, /* result of pcre_compile() */ - sd, /* result of pcre_study(), or NULL */ - PCRE_INFO_SIZE, /* what is required */ - &length); /* where to put the data */ -.sp -The possible values for the third argument are defined in \fBpcre.h\fP, and are -as follows: -.sp - PCRE_INFO_BACKREFMAX -.sp -Return the number of the highest back reference in the pattern. The fourth -argument should point to an \fBint\fP variable. Zero is returned if there are -no back references. -.sp - PCRE_INFO_CAPTURECOUNT -.sp -Return the number of capturing subpatterns in the pattern. The fourth argument -should point to an \fBint\fP variable. -.sp - PCRE_INFO_DEFAULT_TABLES -.sp -Return a pointer to the internal default character tables within PCRE. The -fourth argument should point to an \fBunsigned char *\fP variable. This -information call is provided for internal use by the \fBpcre_study()\fP -function. External callers can cause PCRE to use its internal tables by passing -a NULL table pointer. -.sp - PCRE_INFO_FIRSTBYTE -.sp -Return information about the first data unit of any matched string, for a -non-anchored pattern. (The name of this option refers to the 8-bit library, -where data units are bytes.) The fourth argument should point to an \fBint\fP -variable. -.P -If there is a fixed first value, for example, the letter "c" from a pattern -such as (cat|cow|coyote), its value is returned. In the 8-bit library, the -value is always less than 256; in the 16-bit library the value can be up to -0xffff. -.P -If there is no fixed first value, and if either -.sp -(a) the pattern was compiled with the PCRE_MULTILINE option, and every branch -starts with "^", or -.sp -(b) every branch of the pattern starts with ".*" and PCRE_DOTALL is not set -(if it were set, the pattern would be anchored), -.sp --1 is returned, indicating that the pattern matches only at the start of a -subject string or after any newline within the string. Otherwise -2 is -returned. For anchored patterns, -2 is returned. -.sp - PCRE_INFO_FIRSTTABLE -.sp -If the pattern was studied, and this resulted in the construction of a 256-bit -table indicating a fixed set of values for the first data unit in any matching -string, a pointer to the table is returned. Otherwise NULL is returned. The -fourth argument should point to an \fBunsigned char *\fP variable. -.sp - PCRE_INFO_HASCRORLF -.sp -Return 1 if the pattern contains any explicit matches for CR or LF characters, -otherwise 0. The fourth argument should point to an \fBint\fP variable. An -explicit match is either a literal CR or LF character, or \er or \en. -.sp - PCRE_INFO_JCHANGED -.sp -Return 1 if the (?J) or (?-J) option setting is used in the pattern, otherwise -0. The fourth argument should point to an \fBint\fP variable. (?J) and -(?-J) set and unset the local PCRE_DUPNAMES option, respectively. -.sp - PCRE_INFO_JIT -.sp -Return 1 if the pattern was studied with one of the JIT options, and -just-in-time compiling was successful. The fourth argument should point to an -\fBint\fP variable. A return value of 0 means that JIT support is not available -in this version of PCRE, or that the pattern was not studied with a JIT option, -or that the JIT compiler could not handle this particular pattern. See the -.\" HREF -\fBpcrejit\fP -.\" -documentation for details of what can and cannot be handled. -.sp - PCRE_INFO_JITSIZE -.sp -If the pattern was successfully studied with a JIT option, return the size of -the JIT compiled code, otherwise return zero. The fourth argument should point -to a \fBsize_t\fP variable. -.sp - PCRE_INFO_LASTLITERAL -.sp -Return the value of the rightmost literal data unit that must exist in any -matched string, other than at its start, if such a value has been recorded. The -fourth argument should point to an \fBint\fP variable. If there is no such -value, -1 is returned. For anchored patterns, a last literal value is recorded -only if it follows something of variable length. For example, for the pattern -/^a\ed+z\ed+/ the returned value is "z", but for /^a\edz\ed/ the returned value -is -1. -.sp - PCRE_INFO_MAXLOOKBEHIND -.sp -Return the number of characters (NB not bytes) in the longest lookbehind -assertion in the pattern. Note that the simple assertions \eb and \eB require a -one-character lookbehind. This information is useful when doing multi-segment -matching using the partial matching facilities. -.sp - PCRE_INFO_MINLENGTH -.sp -If the pattern was studied and a minimum length for matching subject strings -was computed, its value is returned. Otherwise the returned value is -1. The -value is a number of characters, which in UTF-8 mode may be different from the -number of bytes. The fourth argument should point to an \fBint\fP variable. A -non-negative value is a lower bound to the length of any matching string. There -may not be any strings of that length that do actually match, but every string -that does match is at least that long. -.sp - PCRE_INFO_NAMECOUNT - PCRE_INFO_NAMEENTRYSIZE - PCRE_INFO_NAMETABLE -.sp -PCRE supports the use of named as well as numbered capturing parentheses. The -names are just an additional way of identifying the parentheses, which still -acquire numbers. Several convenience functions such as -\fBpcre_get_named_substring()\fP are provided for extracting captured -substrings by name. It is also possible to extract the data directly, by first -converting the name to a number in order to access the correct pointers in the -output vector (described with \fBpcre_exec()\fP below). To do the conversion, -you need to use the name-to-number map, which is described by these three -values. -.P -The map consists of a number of fixed-size entries. PCRE_INFO_NAMECOUNT gives -the number of entries, and PCRE_INFO_NAMEENTRYSIZE gives the size of each -entry; both of these return an \fBint\fP value. The entry size depends on the -length of the longest name. PCRE_INFO_NAMETABLE returns a pointer to the first -entry of the table. This is a pointer to \fBchar\fP in the 8-bit library, where -the first two bytes of each entry are the number of the capturing parenthesis, -most significant byte first. In the 16-bit library, the pointer points to -16-bit data units, the first of which contains the parenthesis number. The rest -of the entry is the corresponding name, zero terminated. -.P -The names are in alphabetical order. Duplicate names may appear if (?| is used -to create multiple groups with the same number, as described in the -.\" HTML <a href="pcrepattern.html#dupsubpatternnumber"> -.\" </a> -section on duplicate subpattern numbers -.\" -in the -.\" HREF -\fBpcrepattern\fP -.\" -page. Duplicate names for subpatterns with different numbers are permitted only -if PCRE_DUPNAMES is set. In all cases of duplicate names, they appear in the -table in the order in which they were found in the pattern. In the absence of -(?| this is the order of increasing number; when (?| is used this is not -necessarily the case because later subpatterns may have lower numbers. -.P -As a simple example of the name/number table, consider the following pattern -after compilation by the 8-bit library (assume PCRE_EXTENDED is set, so white -space - including newlines - is ignored): -.sp -.\" JOIN - (?<date> (?<year>(\ed\ed)?\ed\ed) - - (?<month>\ed\ed) - (?<day>\ed\ed) ) -.sp -There are four named subpatterns, so the table has four entries, and each entry -in the table is eight bytes long. The table is as follows, with non-printing -bytes shows in hexadecimal, and undefined bytes shown as ??: -.sp - 00 01 d a t e 00 ?? - 00 05 d a y 00 ?? ?? - 00 04 m o n t h 00 - 00 02 y e a r 00 ?? -.sp -When writing code to extract data from named subpatterns using the -name-to-number map, remember that the length of the entries is likely to be -different for each compiled pattern. -.sp - PCRE_INFO_OKPARTIAL -.sp -Return 1 if the pattern can be used for partial matching with -\fBpcre_exec()\fP, otherwise 0. The fourth argument should point to an -\fBint\fP variable. From release 8.00, this always returns 1, because the -restrictions that previously applied to partial matching have been lifted. The -.\" HREF -\fBpcrepartial\fP -.\" -documentation gives details of partial matching. -.sp - PCRE_INFO_OPTIONS -.sp -Return a copy of the options with which the pattern was compiled. The fourth -argument should point to an \fBunsigned long int\fP variable. These option bits -are those specified in the call to \fBpcre_compile()\fP, modified by any -top-level option settings at the start of the pattern itself. In other words, -they are the options that will be in force when matching starts. For example, -if the pattern /(?im)abc(?-i)d/ is compiled with the PCRE_EXTENDED option, the -result is PCRE_CASELESS, PCRE_MULTILINE, and PCRE_EXTENDED. -.P -A pattern is automatically anchored by PCRE if all of its top-level -alternatives begin with one of the following: -.sp - ^ unless PCRE_MULTILINE is set - \eA always - \eG always -.\" JOIN - .* if PCRE_DOTALL is set and there are no back - references to the subpattern in which .* appears -.sp -For such patterns, the PCRE_ANCHORED bit is set in the options returned by -\fBpcre_fullinfo()\fP. -.sp - PCRE_INFO_SIZE -.sp -Return the size of the compiled pattern in bytes (for both libraries). The -fourth argument should point to a \fBsize_t\fP variable. This value does not -include the size of the \fBpcre\fP structure that is returned by -\fBpcre_compile()\fP. The value that is passed as the argument to -\fBpcre_malloc()\fP when \fBpcre_compile()\fP is getting memory in which to -place the compiled data is the value returned by this option plus the size of -the \fBpcre\fP structure. Studying a compiled pattern, with or without JIT, -does not alter the value returned by this option. -.sp - PCRE_INFO_STUDYSIZE -.sp -Return the size in bytes of the data block pointed to by the \fIstudy_data\fP -field in a \fBpcre_extra\fP block. If \fBpcre_extra\fP is NULL, or there is no -study data, zero is returned. The fourth argument should point to a -\fBsize_t\fP variable. The \fIstudy_data\fP field is set by \fBpcre_study()\fP -to record information that will speed up matching (see the section entitled -.\" HTML <a href="#studyingapattern"> -.\" </a> -"Studying a pattern" -.\" -above). The format of the \fIstudy_data\fP block is private, but its length -is made available via this option so that it can be saved and restored (see the -.\" HREF -\fBpcreprecompile\fP -.\" -documentation for details). -. -. -.SH "REFERENCE COUNTS" -.rs -.sp -.B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP); -.PP -The \fBpcre_refcount()\fP function is used to maintain a reference count in the -data block that contains a compiled pattern. It is provided for the benefit of -applications that operate in an object-oriented manner, where different parts -of the application may be using the same compiled pattern, but you want to free -the block when they are all done. -.P -When a pattern is compiled, the reference count field is initialized to zero. -It is changed only by calling this function, whose action is to add the -\fIadjust\fP value (which may be positive or negative) to it. The yield of the -function is the new value. However, the value of the count is constrained to -lie between 0 and 65535, inclusive. If the new value is outside these limits, -it is forced to the appropriate limit value. -.P -Except when it is zero, the reference count is not correctly preserved if a -pattern is compiled on one host and then transferred to a host whose byte-order -is different. (This seems a highly unlikely scenario.) -. -. -.SH "MATCHING A PATTERN: THE TRADITIONAL FUNCTION" -.rs -.sp -.B int pcre_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP); -.P -The function \fBpcre_exec()\fP is called to match a subject string against a -compiled pattern, which is passed in the \fIcode\fP argument. If the -pattern was studied, the result of the study should be passed in the -\fIextra\fP argument. You can call \fBpcre_exec()\fP with the same \fIcode\fP -and \fIextra\fP arguments as many times as you like, in order to match -different subject strings with the same pattern. -.P -This function is the main matching facility of the library, and it operates in -a Perl-like manner. For specialist use there is also an alternative matching -function, which is described -.\" HTML <a href="#dfamatch"> -.\" </a> -below -.\" -in the section about the \fBpcre_dfa_exec()\fP function. -.P -In most applications, the pattern will have been compiled (and optionally -studied) in the same process that calls \fBpcre_exec()\fP. However, it is -possible to save compiled patterns and study data, and then use them later -in different processes, possibly even on different hosts. For a discussion -about this, see the -.\" HREF -\fBpcreprecompile\fP -.\" -documentation. -.P -Here is an example of a simple call to \fBpcre_exec()\fP: -.sp - int rc; - int ovector[30]; - rc = pcre_exec( - re, /* result of pcre_compile() */ - NULL, /* we didn't study the pattern */ - "some string", /* the subject string */ - 11, /* the length of the subject string */ - 0, /* start at offset 0 in the subject */ - 0, /* default options */ - ovector, /* vector of integers for substring information */ - 30); /* number of elements (NOT size in bytes) */ -. -. -.\" HTML <a name="extradata"></a> -.SS "Extra data for \fBpcre_exec()\fR" -.rs -.sp -If the \fIextra\fP argument is not NULL, it must point to a \fBpcre_extra\fP -data block. The \fBpcre_study()\fP function returns such a block (when it -doesn't return NULL), but you can also create one for yourself, and pass -additional information in it. The \fBpcre_extra\fP block contains the following -fields (not necessarily in this order): -.sp - unsigned long int \fIflags\fP; - void *\fIstudy_data\fP; - void *\fIexecutable_jit\fP; - unsigned long int \fImatch_limit\fP; - unsigned long int \fImatch_limit_recursion\fP; - void *\fIcallout_data\fP; - const unsigned char *\fItables\fP; - unsigned char **\fImark\fP; -.sp -In the 16-bit version of this structure, the \fImark\fP field has type -"PCRE_UCHAR16 **". -.P -The \fIflags\fP field is used to specify which of the other fields are set. The -flag bits are: -.sp - PCRE_EXTRA_CALLOUT_DATA - PCRE_EXTRA_EXECUTABLE_JIT - PCRE_EXTRA_MARK - PCRE_EXTRA_MATCH_LIMIT - PCRE_EXTRA_MATCH_LIMIT_RECURSION - PCRE_EXTRA_STUDY_DATA - PCRE_EXTRA_TABLES -.sp -Other flag bits should be set to zero. The \fIstudy_data\fP field and sometimes -the \fIexecutable_jit\fP field are set in the \fBpcre_extra\fP block that is -returned by \fBpcre_study()\fP, together with the appropriate flag bits. You -should not set these yourself, but you may add to the block by setting other -fields and their corresponding flag bits. -.P -The \fImatch_limit\fP field provides a means of preventing PCRE from using up a -vast amount of resources when running patterns that are not going to match, -but which have a very large number of possibilities in their search trees. The -classic example is a pattern that uses nested unlimited repeats. -.P -Internally, \fBpcre_exec()\fP uses a function called \fBmatch()\fP, which it -calls repeatedly (sometimes recursively). The limit set by \fImatch_limit\fP is -imposed on the number of times this function is called during a match, which -has the effect of limiting the amount of backtracking that can take place. For -patterns that are not anchored, the count restarts from zero for each position -in the subject string. -.P -When \fBpcre_exec()\fP is called with a pattern that was successfully studied -with a JIT option, the way that the matching is executed is entirely different. -However, there is still the possibility of runaway matching that goes on for a -very long time, and so the \fImatch_limit\fP value is also used in this case -(but in a different way) to limit how long the matching can continue. -.P -The default value for the limit can be set when PCRE is built; the default -default is 10 million, which handles all but the most extreme cases. You can -override the default by suppling \fBpcre_exec()\fP with a \fBpcre_extra\fP -block in which \fImatch_limit\fP is set, and PCRE_EXTRA_MATCH_LIMIT is set in -the \fIflags\fP field. If the limit is exceeded, \fBpcre_exec()\fP returns -PCRE_ERROR_MATCHLIMIT. -.P -The \fImatch_limit_recursion\fP field is similar to \fImatch_limit\fP, but -instead of limiting the total number of times that \fBmatch()\fP is called, it -limits the depth of recursion. The recursion depth is a smaller number than the -total number of calls, because not all calls to \fBmatch()\fP are recursive. -This limit is of use only if it is set smaller than \fImatch_limit\fP. -.P -Limiting the recursion depth limits the amount of machine stack that can be -used, or, when PCRE has been compiled to use memory on the heap instead of the -stack, the amount of heap memory that can be used. This limit is not relevant, -and is ignored, when matching is done using JIT compiled code. -.P -The default value for \fImatch_limit_recursion\fP can be set when PCRE is -built; the default default is the same value as the default for -\fImatch_limit\fP. You can override the default by suppling \fBpcre_exec()\fP -with a \fBpcre_extra\fP block in which \fImatch_limit_recursion\fP is set, and -PCRE_EXTRA_MATCH_LIMIT_RECURSION is set in the \fIflags\fP field. If the limit -is exceeded, \fBpcre_exec()\fP returns PCRE_ERROR_RECURSIONLIMIT. -.P -The \fIcallout_data\fP field is used in conjunction with the "callout" feature, -and is described in the -.\" HREF -\fBpcrecallout\fP -.\" -documentation. -.P -The \fItables\fP field is used to pass a character tables pointer to -\fBpcre_exec()\fP; this overrides the value that is stored with the compiled -pattern. A non-NULL value is stored with the compiled pattern only if custom -tables were supplied to \fBpcre_compile()\fP via its \fItableptr\fP argument. -If NULL is passed to \fBpcre_exec()\fP using this mechanism, it forces PCRE's -internal tables to be used. This facility is helpful when re-using patterns -that have been saved after compiling with an external set of tables, because -the external tables might be at a different address when \fBpcre_exec()\fP is -called. See the -.\" HREF -\fBpcreprecompile\fP -.\" -documentation for a discussion of saving compiled patterns for later use. -.P -If PCRE_EXTRA_MARK is set in the \fIflags\fP field, the \fImark\fP field must -be set to point to a suitable variable. If the pattern contains any -backtracking control verbs such as (*MARK:NAME), and the execution ends up with -a name to pass back, a pointer to the name string (zero terminated) is placed -in the variable pointed to by the \fImark\fP field. The names are within the -compiled pattern; if you wish to retain such a name you must copy it before -freeing the memory of a compiled pattern. If there is no name to pass back, the -variable pointed to by the \fImark\fP field is set to NULL. For details of the -backtracking control verbs, see the section entitled -.\" HTML <a href="pcrepattern#backtrackcontrol"> -.\" </a> -"Backtracking control" -.\" -in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation. -. -. -.\" HTML <a name="execoptions"></a> -.SS "Option bits for \fBpcre_exec()\fP" -.rs -.sp -The unused bits of the \fIoptions\fP argument for \fBpcre_exec()\fP must be -zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP, -PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, -PCRE_NO_START_OPTIMIZE, PCRE_NO_UTF8_CHECK, PCRE_PARTIAL_HARD, and -PCRE_PARTIAL_SOFT. -.P -If the pattern was successfully studied with one of the just-in-time (JIT) -compile options, the only supported options for JIT execution are -PCRE_NO_UTF8_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, -PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. If an -unsupported option is used, JIT execution is disabled and the normal -interpretive code in \fBpcre_exec()\fP is run. -.sp - PCRE_ANCHORED -.sp -The PCRE_ANCHORED option limits \fBpcre_exec()\fP to matching at the first -matching position. If a pattern was compiled with PCRE_ANCHORED, or turned out -to be anchored by virtue of its contents, it cannot be made unachored at -matching time. -.sp - PCRE_BSR_ANYCRLF - PCRE_BSR_UNICODE -.sp -These options (which are mutually exclusive) control what the \eR escape -sequence matches. The choice is either to match only CR, LF, or CRLF, or to -match any Unicode newline sequence. These options override the choice that was -made or defaulted when the pattern was compiled. -.sp - PCRE_NEWLINE_CR - PCRE_NEWLINE_LF - PCRE_NEWLINE_CRLF - PCRE_NEWLINE_ANYCRLF - PCRE_NEWLINE_ANY -.sp -These options override the newline definition that was chosen or defaulted when -the pattern was compiled. For details, see the description of -\fBpcre_compile()\fP above. During matching, the newline choice affects the -behaviour of the dot, circumflex, and dollar metacharacters. It may also alter -the way the match position is advanced after a match failure for an unanchored -pattern. -.P -When PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANYCRLF, or PCRE_NEWLINE_ANY is set, and a -match attempt for an unanchored pattern fails when the current position is at a -CRLF sequence, and the pattern contains no explicit matches for CR or LF -characters, the match position is advanced by two characters instead of one, in -other words, to after the CRLF. -.P -The above rule is a compromise that makes the most common cases work as -expected. For example, if the pattern is .+A (and the PCRE_DOTALL option is not -set), it does not match the string "\er\enA" because, after failing at the -start, it skips both the CR and the LF before retrying. However, the pattern -[\er\en]A does match that string, because it contains an explicit CR or LF -reference, and so advances only by one character after the first failure. -.P -An explicit match for CR of LF is either a literal appearance of one of those -characters, or one of the \er or \en escape sequences. Implicit matches such as -[^X] do not count, nor does \es (which includes CR and LF in the characters -that it matches). -.P -Notwithstanding the above, anomalous effects may still occur when CRLF is a -valid newline sequence and explicit \er or \en escapes appear in the pattern. -.sp - PCRE_NOTBOL -.sp -This option specifies that first character of the subject string is not the -beginning of a line, so the circumflex metacharacter should not match before -it. Setting this without PCRE_MULTILINE (at compile time) causes circumflex -never to match. This option affects only the behaviour of the circumflex -metacharacter. It does not affect \eA. -.sp - PCRE_NOTEOL -.sp -This option specifies that the end of the subject string is not the end of a -line, so the dollar metacharacter should not match it nor (except in multiline -mode) a newline immediately before it. Setting this without PCRE_MULTILINE (at -compile time) causes dollar never to match. This option affects only the -behaviour of the dollar metacharacter. It does not affect \eZ or \ez. -.sp - PCRE_NOTEMPTY -.sp -An empty string is not considered to be a valid match if this option is set. If -there are alternatives in the pattern, they are tried. If all the alternatives -match the empty string, the entire match fails. For example, if the pattern -.sp - a?b? -.sp -is applied to a string not beginning with "a" or "b", it matches an empty -string at the start of the subject. With PCRE_NOTEMPTY set, this match is not -valid, so PCRE searches further into the string for occurrences of "a" or "b". -.sp - PCRE_NOTEMPTY_ATSTART -.sp -This is like PCRE_NOTEMPTY, except that an empty string match that is not at -the start of the subject is permitted. If the pattern is anchored, such a match -can occur only if the pattern contains \eK. -.P -Perl has no direct equivalent of PCRE_NOTEMPTY or PCRE_NOTEMPTY_ATSTART, but it -does make a special case of a pattern match of the empty string within its -\fBsplit()\fP function, and when using the /g modifier. It is possible to -emulate Perl's behaviour after matching a null string by first trying the match -again at the same offset with PCRE_NOTEMPTY_ATSTART and PCRE_ANCHORED, and then -if that fails, by advancing the starting offset (see below) and trying an -ordinary match again. There is some code that demonstrates how to do this in -the -.\" HREF -\fBpcredemo\fP -.\" -sample program. In the most general case, you have to check to see if the -newline convention recognizes CRLF as a newline, and if so, and the current -character is CR followed by LF, advance the starting offset by two characters -instead of one. -.sp - PCRE_NO_START_OPTIMIZE -.sp -There are a number of optimizations that \fBpcre_exec()\fP uses at the start of -a match, in order to speed up the process. For example, if it is known that an -unanchored match must start with a specific character, it searches the subject -for that character, and fails immediately if it cannot find it, without -actually running the main matching function. This means that a special item -such as (*COMMIT) at the start of a pattern is not considered until after a -suitable starting point for the match has been found. When callouts or (*MARK) -items are in use, these "start-up" optimizations can cause them to be skipped -if the pattern is never actually used. The start-up optimizations are in effect -a pre-scan of the subject that takes place before the pattern is run. -.P -The PCRE_NO_START_OPTIMIZE option disables the start-up optimizations, possibly -causing performance to suffer, but ensuring that in cases where the result is -"no match", the callouts do occur, and that items such as (*COMMIT) and (*MARK) -are considered at every possible starting position in the subject string. If -PCRE_NO_START_OPTIMIZE is set at compile time, it cannot be unset at matching -time. The use of PCRE_NO_START_OPTIMIZE disables JIT execution; when it is set, -matching is always done using interpretively. -.P -Setting PCRE_NO_START_OPTIMIZE can change the outcome of a matching operation. -Consider the pattern -.sp - (*COMMIT)ABC -.sp -When this is compiled, PCRE records the fact that a match must start with the -character "A". Suppose the subject string is "DEFABC". The start-up -optimization scans along the subject, finds "A" and runs the first match -attempt from there. The (*COMMIT) item means that the pattern must match the -current starting position, which in this case, it does. However, if the same -match is run with PCRE_NO_START_OPTIMIZE set, the initial scan along the -subject string does not happen. The first match attempt is run starting from -"D" and when this fails, (*COMMIT) prevents any further matches being tried, so -the overall result is "no match". If the pattern is studied, more start-up -optimizations may be used. For example, a minimum length for the subject may be -recorded. Consider the pattern -.sp - (*MARK:A)(X|Y) -.sp -The minimum length for a match is one character. If the subject is "ABC", there -will be attempts to match "ABC", "BC", "C", and then finally an empty string. -If the pattern is studied, the final attempt does not take place, because PCRE -knows that the subject is too short, and so the (*MARK) is never encountered. -In this case, studying the pattern does not affect the overall match result, -which is still "no match", but it does affect the auxiliary information that is -returned. -.sp - PCRE_NO_UTF8_CHECK -.sp -When PCRE_UTF8 is set at compile time, the validity of the subject as a UTF-8 -string is automatically checked when \fBpcre_exec()\fP is subsequently called. -The entire string is checked before any other processing takes place. The value -of \fIstartoffset\fP is also checked to ensure that it points to the start of a -UTF-8 character. There is a discussion about the -.\" HTML <a href="pcreunicode.html#utf8strings"> -.\" </a> -validity of UTF-8 strings -.\" -in the -.\" HREF -\fBpcreunicode\fP -.\" -page. If an invalid sequence of bytes is found, \fBpcre_exec()\fP returns the -error PCRE_ERROR_BADUTF8 or, if PCRE_PARTIAL_HARD is set and the problem is a -truncated character at the end of the subject, PCRE_ERROR_SHORTUTF8. In both -cases, information about the precise nature of the error may also be returned -(see the descriptions of these errors in the section entitled \fIError return -values from\fP \fBpcre_exec()\fP -.\" HTML <a href="#errorlist"> -.\" </a> -below). -.\" -If \fIstartoffset\fP contains a value that does not point to the start of a -UTF-8 character (or to the end of the subject), PCRE_ERROR_BADUTF8_OFFSET is -returned. -.P -If you already know that your subject is valid, and you want to skip these -checks for performance reasons, you can set the PCRE_NO_UTF8_CHECK option when -calling \fBpcre_exec()\fP. You might want to do this for the second and -subsequent calls to \fBpcre_exec()\fP if you are making repeated calls to find -all the matches in a single subject string. However, you should be sure that -the value of \fIstartoffset\fP points to the start of a character (or the end -of the subject). When PCRE_NO_UTF8_CHECK is set, the effect of passing an -invalid string as a subject or an invalid value of \fIstartoffset\fP is -undefined. Your program may crash. -.sp - PCRE_PARTIAL_HARD - PCRE_PARTIAL_SOFT -.sp -These options turn on the partial matching feature. For backwards -compatibility, PCRE_PARTIAL is a synonym for PCRE_PARTIAL_SOFT. A partial match -occurs if the end of the subject string is reached successfully, but there are -not enough subject characters to complete the match. If this happens when -PCRE_PARTIAL_SOFT (but not PCRE_PARTIAL_HARD) is set, matching continues by -testing any remaining alternatives. Only if no complete match can be found is -PCRE_ERROR_PARTIAL returned instead of PCRE_ERROR_NOMATCH. In other words, -PCRE_PARTIAL_SOFT says that the caller is prepared to handle a partial match, -but only if no complete match can be found. -.P -If PCRE_PARTIAL_HARD is set, it overrides PCRE_PARTIAL_SOFT. In this case, if a -partial match is found, \fBpcre_exec()\fP immediately returns -PCRE_ERROR_PARTIAL, without considering any other alternatives. In other words, -when PCRE_PARTIAL_HARD is set, a partial match is considered to be more -important that an alternative complete match. -.P -In both cases, the portion of the string that was inspected when the partial -match was found is set as the first matching string. There is a more detailed -discussion of partial and multi-segment matching, with examples, in the -.\" HREF -\fBpcrepartial\fP -.\" -documentation. -. -. -.SS "The string to be matched by \fBpcre_exec()\fP" -.rs -.sp -The subject string is passed to \fBpcre_exec()\fP as a pointer in -\fIsubject\fP, a length in bytes in \fIlength\fP, and a starting byte offset -in \fIstartoffset\fP. If this is negative or greater than the length of the -subject, \fBpcre_exec()\fP returns PCRE_ERROR_BADOFFSET. When the starting -offset is zero, the search for a match starts at the beginning of the subject, -and this is by far the most common case. In UTF-8 mode, the byte offset must -point to the start of a UTF-8 character (or the end of the subject). Unlike the -pattern string, the subject may contain binary zero bytes. -.P -A non-zero starting offset is useful when searching for another match in the -same subject by calling \fBpcre_exec()\fP again after a previous success. -Setting \fIstartoffset\fP differs from just passing over a shortened string and -setting PCRE_NOTBOL in the case of a pattern that begins with any kind of -lookbehind. For example, consider the pattern -.sp - \eBiss\eB -.sp -which finds occurrences of "iss" in the middle of words. (\eB matches only if -the current position in the subject is not a word boundary.) When applied to -the string "Mississipi" the first call to \fBpcre_exec()\fP finds the first -occurrence. If \fBpcre_exec()\fP is called again with just the remainder of the -subject, namely "issipi", it does not match, because \eB is always false at the -start of the subject, which is deemed to be a word boundary. However, if -\fBpcre_exec()\fP is passed the entire string again, but with \fIstartoffset\fP -set to 4, it finds the second occurrence of "iss" because it is able to look -behind the starting point to discover that it is preceded by a letter. -.P -Finding all the matches in a subject is tricky when the pattern can match an -empty string. It is possible to emulate Perl's /g behaviour by first trying the -match again at the same offset, with the PCRE_NOTEMPTY_ATSTART and -PCRE_ANCHORED options, and then if that fails, advancing the starting offset -and trying an ordinary match again. There is some code that demonstrates how to -do this in the -.\" HREF -\fBpcredemo\fP -.\" -sample program. In the most general case, you have to check to see if the -newline convention recognizes CRLF as a newline, and if so, and the current -character is CR followed by LF, advance the starting offset by two characters -instead of one. -.P -If a non-zero starting offset is passed when the pattern is anchored, one -attempt to match at the given offset is made. This can only succeed if the -pattern does not require the match to be at the start of the subject. -. -. -.SS "How \fBpcre_exec()\fP returns captured substrings" -.rs -.sp -In general, a pattern matches a certain portion of the subject, and in -addition, further substrings from the subject may be picked out by parts of the -pattern. Following the usage in Jeffrey Friedl's book, this is called -"capturing" in what follows, and the phrase "capturing subpattern" is used for -a fragment of a pattern that picks out a substring. PCRE supports several other -kinds of parenthesized subpattern that do not cause substrings to be captured. -.P -Captured substrings are returned to the caller via a vector of integers whose -address is passed in \fIovector\fP. The number of elements in the vector is -passed in \fIovecsize\fP, which must be a non-negative number. \fBNote\fP: this -argument is NOT the size of \fIovector\fP in bytes. -.P -The first two-thirds of the vector is used to pass back captured substrings, -each substring using a pair of integers. The remaining third of the vector is -used as workspace by \fBpcre_exec()\fP while matching capturing subpatterns, -and is not available for passing back information. The number passed in -\fIovecsize\fP should always be a multiple of three. If it is not, it is -rounded down. -.P -When a match is successful, information about captured substrings is returned -in pairs of integers, starting at the beginning of \fIovector\fP, and -continuing up to two-thirds of its length at the most. The first element of -each pair is set to the byte offset of the first character in a substring, and -the second is set to the byte offset of the first character after the end of a -substring. \fBNote\fP: these values are always byte offsets, even in UTF-8 -mode. They are not character counts. -.P -The first pair of integers, \fIovector[0]\fP and \fIovector[1]\fP, identify the -portion of the subject string matched by the entire pattern. The next pair is -used for the first capturing subpattern, and so on. The value returned by -\fBpcre_exec()\fP is one more than the highest numbered pair that has been set. -For example, if two substrings have been captured, the returned value is 3. If -there are no capturing subpatterns, the return value from a successful match is -1, indicating that just the first pair of offsets has been set. -.P -If a capturing subpattern is matched repeatedly, it is the last portion of the -string that it matched that is returned. -.P -If the vector is too small to hold all the captured substring offsets, it is -used as far as possible (up to two-thirds of its length), and the function -returns a value of zero. If neither the actual string matched nor any captured -substrings are of interest, \fBpcre_exec()\fP may be called with \fIovector\fP -passed as NULL and \fIovecsize\fP as zero. However, if the pattern contains -back references and the \fIovector\fP is not big enough to remember the related -substrings, PCRE has to get additional memory for use during matching. Thus it -is usually advisable to supply an \fIovector\fP of reasonable size. -.P -There are some cases where zero is returned (indicating vector overflow) when -in fact the vector is exactly the right size for the final match. For example, -consider the pattern -.sp - (a)(?:(b)c|bd) -.sp -If a vector of 6 elements (allowing for only 1 captured substring) is given -with subject string "abd", \fBpcre_exec()\fP will try to set the second -captured string, thereby recording a vector overflow, before failing to match -"c" and backing up to try the second alternative. The zero return, however, -does correctly indicate that the maximum number of slots (namely 2) have been -filled. In similar cases where there is temporary overflow, but the final -number of used slots is actually less than the maximum, a non-zero value is -returned. -.P -The \fBpcre_fullinfo()\fP function can be used to find out how many capturing -subpatterns there are in a compiled pattern. The smallest size for -\fIovector\fP that will allow for \fIn\fP captured substrings, in addition to -the offsets of the substring matched by the whole pattern, is (\fIn\fP+1)*3. -.P -It is possible for capturing subpattern number \fIn+1\fP to match some part of -the subject when subpattern \fIn\fP has not been used at all. For example, if -the string "abc" is matched against the pattern (a|(z))(bc) the return from the -function is 4, and subpatterns 1 and 3 are matched, but 2 is not. When this -happens, both values in the offset pairs corresponding to unused subpatterns -are set to -1. -.P -Offset values that correspond to unused subpatterns at the end of the -expression are also set to -1. For example, if the string "abc" is matched -against the pattern (abc)(x(yz)?)? subpatterns 2 and 3 are not matched. The -return from the function is 2, because the highest used capturing subpattern -number is 1, and the offsets for for the second and third capturing subpatterns -(assuming the vector is large enough, of course) are set to -1. -.P -\fBNote\fP: Elements in the first two-thirds of \fIovector\fP that do not -correspond to capturing parentheses in the pattern are never changed. That is, -if a pattern contains \fIn\fP capturing parentheses, no more than -\fIovector[0]\fP to \fIovector[2n+1]\fP are set by \fBpcre_exec()\fP. The other -elements (in the first two-thirds) retain whatever values they previously had. -.P -Some convenience functions are provided for extracting the captured substrings -as separate strings. These are described below. -. -. -.\" HTML <a name="errorlist"></a> -.SS "Error return values from \fBpcre_exec()\fP" -.rs -.sp -If \fBpcre_exec()\fP fails, it returns a negative number. The following are -defined in the header file: -.sp - PCRE_ERROR_NOMATCH (-1) -.sp -The subject string did not match the pattern. -.sp - PCRE_ERROR_NULL (-2) -.sp -Either \fIcode\fP or \fIsubject\fP was passed as NULL, or \fIovector\fP was -NULL and \fIovecsize\fP was not zero. -.sp - PCRE_ERROR_BADOPTION (-3) -.sp -An unrecognized bit was set in the \fIoptions\fP argument. -.sp - PCRE_ERROR_BADMAGIC (-4) -.sp -PCRE stores a 4-byte "magic number" at the start of the compiled code, to catch -the case when it is passed a junk pointer and to detect when a pattern that was -compiled in an environment of one endianness is run in an environment with the -other endianness. This is the error that PCRE gives when the magic number is -not present. -.sp - PCRE_ERROR_UNKNOWN_OPCODE (-5) -.sp -While running the pattern match, an unknown item was encountered in the -compiled pattern. This error could be caused by a bug in PCRE or by overwriting -of the compiled pattern. -.sp - PCRE_ERROR_NOMEMORY (-6) -.sp -If a pattern contains back references, but the \fIovector\fP that is passed to -\fBpcre_exec()\fP is not big enough to remember the referenced substrings, PCRE -gets a block of memory at the start of matching to use for this purpose. If the -call via \fBpcre_malloc()\fP fails, this error is given. The memory is -automatically freed at the end of matching. -.P -This error is also given if \fBpcre_stack_malloc()\fP fails in -\fBpcre_exec()\fP. This can happen only when PCRE has been compiled with -\fB--disable-stack-for-recursion\fP. -.sp - PCRE_ERROR_NOSUBSTRING (-7) -.sp -This error is used by the \fBpcre_copy_substring()\fP, -\fBpcre_get_substring()\fP, and \fBpcre_get_substring_list()\fP functions (see -below). It is never returned by \fBpcre_exec()\fP. -.sp - PCRE_ERROR_MATCHLIMIT (-8) -.sp -The backtracking limit, as specified by the \fImatch_limit\fP field in a -\fBpcre_extra\fP structure (or defaulted) was reached. See the description -above. -.sp - PCRE_ERROR_CALLOUT (-9) -.sp -This error is never generated by \fBpcre_exec()\fP itself. It is provided for -use by callout functions that want to yield a distinctive error code. See the -.\" HREF -\fBpcrecallout\fP -.\" -documentation for details. -.sp - PCRE_ERROR_BADUTF8 (-10) -.sp -A string that contains an invalid UTF-8 byte sequence was passed as a subject, -and the PCRE_NO_UTF8_CHECK option was not set. If the size of the output vector -(\fIovecsize\fP) is at least 2, the byte offset to the start of the the invalid -UTF-8 character is placed in the first element, and a reason code is placed in -the second element. The reason codes are listed in the -.\" HTML <a href="#badutf8reasons"> -.\" </a> -following section. -.\" -For backward compatibility, if PCRE_PARTIAL_HARD is set and the problem is a -truncated UTF-8 character at the end of the subject (reason codes 1 to 5), -PCRE_ERROR_SHORTUTF8 is returned instead of PCRE_ERROR_BADUTF8. -.sp - PCRE_ERROR_BADUTF8_OFFSET (-11) -.sp -The UTF-8 byte sequence that was passed as a subject was checked and found to -be valid (the PCRE_NO_UTF8_CHECK option was not set), but the value of -\fIstartoffset\fP did not point to the beginning of a UTF-8 character or the -end of the subject. -.sp - PCRE_ERROR_PARTIAL (-12) -.sp -The subject string did not match, but it did match partially. See the -.\" HREF -\fBpcrepartial\fP -.\" -documentation for details of partial matching. -.sp - PCRE_ERROR_BADPARTIAL (-13) -.sp -This code is no longer in use. It was formerly returned when the PCRE_PARTIAL -option was used with a compiled pattern containing items that were not -supported for partial matching. From release 8.00 onwards, there are no -restrictions on partial matching. -.sp - PCRE_ERROR_INTERNAL (-14) -.sp -An unexpected internal error has occurred. This error could be caused by a bug -in PCRE or by overwriting of the compiled pattern. -.sp - PCRE_ERROR_BADCOUNT (-15) -.sp -This error is given if the value of the \fIovecsize\fP argument is negative. -.sp - PCRE_ERROR_RECURSIONLIMIT (-21) -.sp -The internal recursion limit, as specified by the \fImatch_limit_recursion\fP -field in a \fBpcre_extra\fP structure (or defaulted) was reached. See the -description above. -.sp - PCRE_ERROR_BADNEWLINE (-23) -.sp -An invalid combination of PCRE_NEWLINE_\fIxxx\fP options was given. -.sp - PCRE_ERROR_BADOFFSET (-24) -.sp -The value of \fIstartoffset\fP was negative or greater than the length of the -subject, that is, the value in \fIlength\fP. -.sp - PCRE_ERROR_SHORTUTF8 (-25) -.sp -This error is returned instead of PCRE_ERROR_BADUTF8 when the subject string -ends with a truncated UTF-8 character and the PCRE_PARTIAL_HARD option is set. -Information about the failure is returned as for PCRE_ERROR_BADUTF8. It is in -fact sufficient to detect this case, but this special error code for -PCRE_PARTIAL_HARD precedes the implementation of returned information; it is -retained for backwards compatibility. -.sp - PCRE_ERROR_RECURSELOOP (-26) -.sp -This error is returned when \fBpcre_exec()\fP detects a recursion loop within -the pattern. Specifically, it means that either the whole pattern or a -subpattern has been called recursively for the second time at the same position -in the subject string. Some simple patterns that might do this are detected and -faulted at compile time, but more complicated cases, in particular mutual -recursions between two different subpatterns, cannot be detected until run -time. -.sp - PCRE_ERROR_JIT_STACKLIMIT (-27) -.sp -This error is returned when a pattern that was successfully studied using a -JIT compile option is being matched, but the memory available for the -just-in-time processing stack is not large enough. See the -.\" HREF -\fBpcrejit\fP -.\" -documentation for more details. -.sp - PCRE_ERROR_BADMODE (-28) -.sp -This error is given if a pattern that was compiled by the 8-bit library is -passed to a 16-bit library function, or vice versa. -.sp - PCRE_ERROR_BADENDIANNESS (-29) -.sp -This error is given if a pattern that was compiled and saved is reloaded on a -host with different endianness. The utility function -\fBpcre_pattern_to_host_byte_order()\fP can be used to convert such a pattern -so that it runs on the new host. -.P -Error numbers -16 to -20, -22, and -30 are not used by \fBpcre_exec()\fP. -. -. -.\" HTML <a name="badutf8reasons"></a> -.SS "Reason codes for invalid UTF-8 strings" -.rs -.sp -This section applies only to the 8-bit library. The corresponding information -for the 16-bit library is given in the -.\" HREF -\fBpcre16\fP -.\" -page. -.P -When \fBpcre_exec()\fP returns either PCRE_ERROR_BADUTF8 or -PCRE_ERROR_SHORTUTF8, and the size of the output vector (\fIovecsize\fP) is at -least 2, the offset of the start of the invalid UTF-8 character is placed in -the first output vector element (\fIovector[0]\fP) and a reason code is placed -in the second element (\fIovector[1]\fP). The reason codes are given names in -the \fBpcre.h\fP header file: -.sp - PCRE_UTF8_ERR1 - PCRE_UTF8_ERR2 - PCRE_UTF8_ERR3 - PCRE_UTF8_ERR4 - PCRE_UTF8_ERR5 -.sp -The string ends with a truncated UTF-8 character; the code specifies how many -bytes are missing (1 to 5). Although RFC 3629 restricts UTF-8 characters to be -no longer than 4 bytes, the encoding scheme (originally defined by RFC 2279) -allows for up to 6 bytes, and this is checked first; hence the possibility of -4 or 5 missing bytes. -.sp - PCRE_UTF8_ERR6 - PCRE_UTF8_ERR7 - PCRE_UTF8_ERR8 - PCRE_UTF8_ERR9 - PCRE_UTF8_ERR10 -.sp -The two most significant bits of the 2nd, 3rd, 4th, 5th, or 6th byte of the -character do not have the binary value 0b10 (that is, either the most -significant bit is 0, or the next bit is 1). -.sp - PCRE_UTF8_ERR11 - PCRE_UTF8_ERR12 -.sp -A character that is valid by the RFC 2279 rules is either 5 or 6 bytes long; -these code points are excluded by RFC 3629. -.sp - PCRE_UTF8_ERR13 -.sp -A 4-byte character has a value greater than 0x10fff; these code points are -excluded by RFC 3629. -.sp - PCRE_UTF8_ERR14 -.sp -A 3-byte character has a value in the range 0xd800 to 0xdfff; this range of -code points are reserved by RFC 3629 for use with UTF-16, and so are excluded -from UTF-8. -.sp - PCRE_UTF8_ERR15 - PCRE_UTF8_ERR16 - PCRE_UTF8_ERR17 - PCRE_UTF8_ERR18 - PCRE_UTF8_ERR19 -.sp -A 2-, 3-, 4-, 5-, or 6-byte character is "overlong", that is, it codes for a -value that can be represented by fewer bytes, which is invalid. For example, -the two bytes 0xc0, 0xae give the value 0x2e, whose correct coding uses just -one byte. -.sp - PCRE_UTF8_ERR20 -.sp -The two most significant bits of the first byte of a character have the binary -value 0b10 (that is, the most significant bit is 1 and the second is 0). Such a -byte can only validly occur as the second or subsequent byte of a multi-byte -character. -.sp - PCRE_UTF8_ERR21 -.sp -The first byte of a character has the value 0xfe or 0xff. These values can -never occur in a valid UTF-8 string. -. -. -.SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER" -.rs -.sp -.B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP, -.ti +5n -.B int \fIbuffersize\fP); -.PP -.B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, int \fIstringnumber\fP, -.ti +5n -.B const char **\fIstringptr\fP); -.PP -.B int pcre_get_substring_list(const char *\fIsubject\fP, -.ti +5n -.B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);" -.PP -Captured substrings can be accessed directly by using the offsets returned by -\fBpcre_exec()\fP in \fIovector\fP. For convenience, the functions -\fBpcre_copy_substring()\fP, \fBpcre_get_substring()\fP, and -\fBpcre_get_substring_list()\fP are provided for extracting captured substrings -as new, separate, zero-terminated strings. These functions identify substrings -by number. The next section describes functions for extracting named -substrings. -.P -A substring that contains a binary zero is correctly extracted and has a -further zero added on the end, but the result is not, of course, a C string. -However, you can process such a string by referring to the length that is -returned by \fBpcre_copy_substring()\fP and \fBpcre_get_substring()\fP. -Unfortunately, the interface to \fBpcre_get_substring_list()\fP is not adequate -for handling strings containing binary zeros, because the end of the final -string is not independently indicated. -.P -The first three arguments are the same for all three of these functions: -\fIsubject\fP is the subject string that has just been successfully matched, -\fIovector\fP is a pointer to the vector of integer offsets that was passed to -\fBpcre_exec()\fP, and \fIstringcount\fP is the number of substrings that were -captured by the match, including the substring that matched the entire regular -expression. This is the value returned by \fBpcre_exec()\fP if it is greater -than zero. If \fBpcre_exec()\fP returned zero, indicating that it ran out of -space in \fIovector\fP, the value passed as \fIstringcount\fP should be the -number of elements in the vector divided by three. -.P -The functions \fBpcre_copy_substring()\fP and \fBpcre_get_substring()\fP -extract a single substring, whose number is given as \fIstringnumber\fP. A -value of zero extracts the substring that matched the entire pattern, whereas -higher values extract the captured substrings. For \fBpcre_copy_substring()\fP, -the string is placed in \fIbuffer\fP, whose length is given by -\fIbuffersize\fP, while for \fBpcre_get_substring()\fP a new block of memory is -obtained via \fBpcre_malloc\fP, and its address is returned via -\fIstringptr\fP. The yield of the function is the length of the string, not -including the terminating zero, or one of these error codes: -.sp - PCRE_ERROR_NOMEMORY (-6) -.sp -The buffer was too small for \fBpcre_copy_substring()\fP, or the attempt to get -memory failed for \fBpcre_get_substring()\fP. -.sp - PCRE_ERROR_NOSUBSTRING (-7) -.sp -There is no substring whose number is \fIstringnumber\fP. -.P -The \fBpcre_get_substring_list()\fP function extracts all available substrings -and builds a list of pointers to them. All this is done in a single block of -memory that is obtained via \fBpcre_malloc\fP. The address of the memory block -is returned via \fIlistptr\fP, which is also the start of the list of string -pointers. The end of the list is marked by a NULL pointer. The yield of the -function is zero if all went well, or the error code -.sp - PCRE_ERROR_NOMEMORY (-6) -.sp -if the attempt to get the memory block failed. -.P -When any of these functions encounter a substring that is unset, which can -happen when capturing subpattern number \fIn+1\fP matches some part of the -subject, but subpattern \fIn\fP has not been used at all, they return an empty -string. This can be distinguished from a genuine zero-length substring by -inspecting the appropriate offset in \fIovector\fP, which is negative for unset -substrings. -.P -The two convenience functions \fBpcre_free_substring()\fP and -\fBpcre_free_substring_list()\fP can be used to free the memory returned by -a previous call of \fBpcre_get_substring()\fP or -\fBpcre_get_substring_list()\fP, respectively. They do nothing more than call -the function pointed to by \fBpcre_free\fP, which of course could be called -directly from a C program. However, PCRE is used in some situations where it is -linked via a special interface to another programming language that cannot use -\fBpcre_free\fP directly; it is for these cases that the functions are -provided. -. -. -.SH "EXTRACTING CAPTURED SUBSTRINGS BY NAME" -.rs -.sp -.B int pcre_get_stringnumber(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIname\fP); -.PP -.B int pcre_copy_named_substring(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, const char *\fIstringname\fP, -.ti +5n -.B char *\fIbuffer\fP, int \fIbuffersize\fP); -.PP -.B int pcre_get_named_substring(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIsubject\fP, int *\fIovector\fP, -.ti +5n -.B int \fIstringcount\fP, const char *\fIstringname\fP, -.ti +5n -.B const char **\fIstringptr\fP); -.PP -To extract a substring by name, you first have to find associated number. -For example, for this pattern -.sp - (a+)b(?<xxx>\ed+)... -.sp -the number of the subpattern called "xxx" is 2. If the name is known to be -unique (PCRE_DUPNAMES was not set), you can find the number from the name by -calling \fBpcre_get_stringnumber()\fP. The first argument is the compiled -pattern, and the second is the name. The yield of the function is the -subpattern number, or PCRE_ERROR_NOSUBSTRING (-7) if there is no subpattern of -that name. -.P -Given the number, you can extract the substring directly, or use one of the -functions described in the previous section. For convenience, there are also -two functions that do the whole job. -.P -Most of the arguments of \fBpcre_copy_named_substring()\fP and -\fBpcre_get_named_substring()\fP are the same as those for the similarly named -functions that extract by number. As these are described in the previous -section, they are not re-described here. There are just two differences: -.P -First, instead of a substring number, a substring name is given. Second, there -is an extra argument, given at the start, which is a pointer to the compiled -pattern. This is needed in order to gain access to the name-to-number -translation table. -.P -These functions call \fBpcre_get_stringnumber()\fP, and if it succeeds, they -then call \fBpcre_copy_substring()\fP or \fBpcre_get_substring()\fP, as -appropriate. \fBNOTE:\fP If PCRE_DUPNAMES is set and there are duplicate names, -the behaviour may not be what you want (see the next section). -.P -\fBWarning:\fP If the pattern uses the (?| feature to set up multiple -subpatterns with the same number, as described in the -.\" HTML <a href="pcrepattern.html#dupsubpatternnumber"> -.\" </a> -section on duplicate subpattern numbers -.\" -in the -.\" HREF -\fBpcrepattern\fP -.\" -page, you cannot use names to distinguish the different subpatterns, because -names are not included in the compiled code. The matching process uses only -numbers. For this reason, the use of different names for subpatterns of the -same number causes an error at compile time. -. -. -.SH "DUPLICATE SUBPATTERN NAMES" -.rs -.sp -.B int pcre_get_stringtable_entries(const pcre *\fIcode\fP, -.ti +5n -.B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP); -.PP -When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns -are not required to be unique. (Duplicate names are always allowed for -subpatterns with the same number, created by using the (?| feature. Indeed, if -such subpatterns are named, they are required to use the same names.) -.P -Normally, patterns with duplicate names are such that in any one match, only -one of the named subpatterns participates. An example is shown in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation. -.P -When duplicates are present, \fBpcre_copy_named_substring()\fP and -\fBpcre_get_named_substring()\fP return the first substring corresponding to -the given name that is set. If none are set, PCRE_ERROR_NOSUBSTRING (-7) is -returned; no data is returned. The \fBpcre_get_stringnumber()\fP function -returns one of the numbers that are associated with the name, but it is not -defined which it is. -.P -If you want to get full details of all captured substrings for a given name, -you must use the \fBpcre_get_stringtable_entries()\fP function. The first -argument is the compiled pattern, and the second is the name. The third and -fourth are pointers to variables which are updated by the function. After it -has run, they point to the first and last entries in the name-to-number table -for the given name. The function itself returns the length of each entry, or -PCRE_ERROR_NOSUBSTRING (-7) if there are none. The format of the table is -described above in the section entitled \fIInformation about a pattern\fP -.\" HTML <a href="#infoaboutpattern"> -.\" </a> -above. -.\" -Given all the relevant entries for the name, you can extract each of their -numbers, and hence the captured data, if any. -. -. -.SH "FINDING ALL POSSIBLE MATCHES" -.rs -.sp -The traditional matching function uses a similar algorithm to Perl, which stops -when it finds the first match, starting at a given point in the subject. If you -want to find all possible matches, or the longest possible match, consider -using the alternative matching function (see below) instead. If you cannot use -the alternative function, but still need to find all possible matches, you -can kludge it up by making use of the callout facility, which is described in -the -.\" HREF -\fBpcrecallout\fP -.\" -documentation. -.P -What you have to do is to insert a callout right at the end of the pattern. -When your callout function is called, extract and save the current matched -substring. Then return 1, which forces \fBpcre_exec()\fP to backtrack and try -other alternatives. Ultimately, when it runs out of matches, \fBpcre_exec()\fP -will yield PCRE_ERROR_NOMATCH. -. -. -.SH "OBTAINING AN ESTIMATE OF STACK USAGE" -.rs -.sp -Matching certain patterns using \fBpcre_exec()\fP can use a lot of process -stack, which in certain environments can be rather limited in size. Some users -find it helpful to have an estimate of the amount of stack that is used by -\fBpcre_exec()\fP, to help them set recursion limits, as described in the -.\" HREF -\fBpcrestack\fP -.\" -documentation. The estimate that is output by \fBpcretest\fP when called with -the \fB-m\fP and \fB-C\fP options is obtained by calling \fBpcre_exec\fP with -the values NULL, NULL, NULL, -999, and -999 for its first five arguments. -.P -Normally, if its first argument is NULL, \fBpcre_exec()\fP immediately returns -the negative error code PCRE_ERROR_NULL, but with this special combination of -arguments, it returns instead a negative number whose absolute value is the -approximate stack frame size in bytes. (A negative number is used so that it is -clear that no match has happened.) The value is approximate because in some -cases, recursive calls to \fBpcre_exec()\fP occur when there are one or two -additional variables on the stack. -.P -If PCRE has been compiled to use the heap instead of the stack for recursion, -the value returned is the size of each block that is obtained from the heap. -. -. -.\" HTML <a name="dfamatch"></a> -.SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION" -.rs -.sp -.B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP," -.ti +5n -.B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP, -.ti +5n -.B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP, -.ti +5n -.B int *\fIworkspace\fP, int \fIwscount\fP); -.P -The function \fBpcre_dfa_exec()\fP is called to match a subject string against -a compiled pattern, using a matching algorithm that scans the subject string -just once, and does not backtrack. This has different characteristics to the -normal algorithm, and is not compatible with Perl. Some of the features of PCRE -patterns are not supported. Nevertheless, there are times when this kind of -matching can be useful. For a discussion of the two matching algorithms, and a -list of features that \fBpcre_dfa_exec()\fP does not support, see the -.\" HREF -\fBpcrematching\fP -.\" -documentation. -.P -The arguments for the \fBpcre_dfa_exec()\fP function are the same as for -\fBpcre_exec()\fP, plus two extras. The \fIovector\fP argument is used in a -different way, and this is described below. The other common arguments are used -in the same way as for \fBpcre_exec()\fP, so their description is not repeated -here. -.P -The two additional arguments provide workspace for the function. The workspace -vector should contain at least 20 elements. It is used for keeping track of -multiple paths through the pattern tree. More workspace will be needed for -patterns and subjects where there are a lot of potential matches. -.P -Here is an example of a simple call to \fBpcre_dfa_exec()\fP: -.sp - int rc; - int ovector[10]; - int wspace[20]; - rc = pcre_dfa_exec( - re, /* result of pcre_compile() */ - NULL, /* we didn't study the pattern */ - "some string", /* the subject string */ - 11, /* the length of the subject string */ - 0, /* start at offset 0 in the subject */ - 0, /* default options */ - ovector, /* vector of integers for substring information */ - 10, /* number of elements (NOT size in bytes) */ - wspace, /* working space vector */ - 20); /* number of elements (NOT size in bytes) */ -. -.SS "Option bits for \fBpcre_dfa_exec()\fP" -.rs -.sp -The unused bits of the \fIoptions\fP argument for \fBpcre_dfa_exec()\fP must be -zero. The only bits that may be set are PCRE_ANCHORED, PCRE_NEWLINE_\fIxxx\fP, -PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, -PCRE_NO_UTF8_CHECK, PCRE_BSR_ANYCRLF, PCRE_BSR_UNICODE, PCRE_NO_START_OPTIMIZE, -PCRE_PARTIAL_HARD, PCRE_PARTIAL_SOFT, PCRE_DFA_SHORTEST, and PCRE_DFA_RESTART. -All but the last four of these are exactly the same as for \fBpcre_exec()\fP, -so their description is not repeated here. -.sp - PCRE_PARTIAL_HARD - PCRE_PARTIAL_SOFT -.sp -These have the same general effect as they do for \fBpcre_exec()\fP, but the -details are slightly different. When PCRE_PARTIAL_HARD is set for -\fBpcre_dfa_exec()\fP, it returns PCRE_ERROR_PARTIAL if the end of the subject -is reached and there is still at least one matching possibility that requires -additional characters. This happens even if some complete matches have also -been found. When PCRE_PARTIAL_SOFT is set, the return code PCRE_ERROR_NOMATCH -is converted into PCRE_ERROR_PARTIAL if the end of the subject is reached, -there have been no complete matches, but there is still at least one matching -possibility. The portion of the string that was inspected when the longest -partial match was found is set as the first matching string in both cases. -There is a more detailed discussion of partial and multi-segment matching, with -examples, in the -.\" HREF -\fBpcrepartial\fP -.\" -documentation. -.sp - PCRE_DFA_SHORTEST -.sp -Setting the PCRE_DFA_SHORTEST option causes the matching algorithm to stop as -soon as it has found one match. Because of the way the alternative algorithm -works, this is necessarily the shortest possible match at the first possible -matching point in the subject string. -.sp - PCRE_DFA_RESTART -.sp -When \fBpcre_dfa_exec()\fP returns a partial match, it is possible to call it -again, with additional subject characters, and have it continue with the same -match. The PCRE_DFA_RESTART option requests this action; when it is set, the -\fIworkspace\fP and \fIwscount\fP options must reference the same vector as -before because data about the match so far is left in them after a partial -match. There is more discussion of this facility in the -.\" HREF -\fBpcrepartial\fP -.\" -documentation. -. -. -.SS "Successful returns from \fBpcre_dfa_exec()\fP" -.rs -.sp -When \fBpcre_dfa_exec()\fP succeeds, it may have matched more than one -substring in the subject. Note, however, that all the matches from one run of -the function start at the same point in the subject. The shorter matches are -all initial substrings of the longer matches. For example, if the pattern -.sp - <.*> -.sp -is matched against the string -.sp - This is <something> <something else> <something further> no more -.sp -the three matched strings are -.sp - <something> - <something> <something else> - <something> <something else> <something further> -.sp -On success, the yield of the function is a number greater than zero, which is -the number of matched substrings. The substrings themselves are returned in -\fIovector\fP. Each string uses two elements; the first is the offset to the -start, and the second is the offset to the end. In fact, all the strings have -the same start offset. (Space could have been saved by giving this only once, -but it was decided to retain some compatibility with the way \fBpcre_exec()\fP -returns data, even though the meaning of the strings is different.) -.P -The strings are returned in reverse order of length; that is, the longest -matching string is given first. If there were too many matches to fit into -\fIovector\fP, the yield of the function is zero, and the vector is filled with -the longest matches. Unlike \fBpcre_exec()\fP, \fBpcre_dfa_exec()\fP can use -the entire \fIovector\fP for returning matched strings. -. -. -.SS "Error returns from \fBpcre_dfa_exec()\fP" -.rs -.sp -The \fBpcre_dfa_exec()\fP function returns a negative number when it fails. -Many of the errors are the same as for \fBpcre_exec()\fP, and these are -described -.\" HTML <a href="#errorlist"> -.\" </a> -above. -.\" -There are in addition the following errors that are specific to -\fBpcre_dfa_exec()\fP: -.sp - PCRE_ERROR_DFA_UITEM (-16) -.sp -This return is given if \fBpcre_dfa_exec()\fP encounters an item in the pattern -that it does not support, for instance, the use of \eC or a back reference. -.sp - PCRE_ERROR_DFA_UCOND (-17) -.sp -This return is given if \fBpcre_dfa_exec()\fP encounters a condition item that -uses a back reference for the condition, or a test for recursion in a specific -group. These are not supported. -.sp - PCRE_ERROR_DFA_UMLIMIT (-18) -.sp -This return is given if \fBpcre_dfa_exec()\fP is called with an \fIextra\fP -block that contains a setting of the \fImatch_limit\fP or -\fImatch_limit_recursion\fP fields. This is not supported (these fields are -meaningless for DFA matching). -.sp - PCRE_ERROR_DFA_WSSIZE (-19) -.sp -This return is given if \fBpcre_dfa_exec()\fP runs out of space in the -\fIworkspace\fP vector. -.sp - PCRE_ERROR_DFA_RECURSE (-20) -.sp -When a recursive subpattern is processed, the matching function calls itself -recursively, using private vectors for \fIovector\fP and \fIworkspace\fP. This -error is given if the output vector is not large enough. This should be -extremely rare, as a vector of size 1000 is used. -.sp - PCRE_ERROR_DFA_BADRESTART (-30) -.sp -When \fBpcre_dfa_exec()\fP is called with the \fBPCRE_DFA_RESTART\fP option, -some plausibility checks are made on the contents of the workspace, which -should contain data about the previous partial match. If any of these checks -fail, this error is given. -. -. -.SH "SEE ALSO" -.rs -.sp -\fBpcre16\fP(3), \fBpcrebuild\fP(3), \fBpcrecallout\fP(3), \fBpcrecpp(3)\fP(3), -\fBpcrematching\fP(3), \fBpcrepartial\fP(3), \fBpcreposix\fP(3), -\fBpcreprecompile\fP(3), \fBpcresample\fP(3), \fBpcrestack\fP(3). -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 17 June 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcrebuild.3 b/gtk+-mingw/share/man/man3/pcrebuild.3 deleted file mode 100644 index 52f97fb..0000000 --- a/gtk+-mingw/share/man/man3/pcrebuild.3 +++ /dev/null @@ -1,425 +0,0 @@ -.TH PCREBUILD 3 "07 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -. -. -.SH "PCRE BUILD-TIME OPTIONS" -.rs -.sp -This document describes the optional features of PCRE that can be selected when -the library is compiled. It assumes use of the \fBconfigure\fP script, where -the optional features are selected or deselected by providing options to -\fBconfigure\fP before running the \fBmake\fP command. However, the same -options can be selected in both Unix-like and non-Unix-like environments using -the GUI facility of \fBcmake-gui\fP if you are using \fBCMake\fP instead of -\fBconfigure\fP to build PCRE. -.P -There is a lot more information about building PCRE in non-Unix-like -environments in the file called \fINON_UNIX_USE\fP, which is part of the PCRE -distribution. You should consult this file as well as the \fIREADME\fP file if -you are building in a non-Unix-like environment. -.P -The complete list of options for \fBconfigure\fP (which includes the standard -ones such as the selection of the installation directory) can be obtained by -running -.sp - ./configure --help -.sp -The following sections include descriptions of options whose names begin with ---enable or --disable. These settings specify changes to the defaults for the -\fBconfigure\fP command. Because of the way that \fBconfigure\fP works, ---enable and --disable always come in pairs, so the complementary option always -exists as well, but as it specifies the default, it is not described. -. -. -.SH "BUILDING 8-BIT and 16-BIT LIBRARIES" -.rs -.sp -By default, a library called \fBlibpcre\fP is built, containing functions that -take string arguments contained in vectors of bytes, either as single-byte -characters, or interpreted as UTF-8 strings. You can also build a separate -library, called \fBlibpcre16\fP, in which strings are contained in vectors of -16-bit data units and interpreted either as single-unit characters or UTF-16 -strings, by adding -.sp - --enable-pcre16 -.sp -to the \fBconfigure\fP command. If you do not want the 8-bit library, add -.sp - --disable-pcre8 -.sp -as well. At least one of the two libraries must be built. Note that the C++ and -POSIX wrappers are for the 8-bit library only, and that \fBpcregrep\fP is an -8-bit program. None of these are built if you select only the 16-bit library. -. -. -.SH "BUILDING SHARED AND STATIC LIBRARIES" -.rs -.sp -The PCRE building process uses \fBlibtool\fP to build both shared and static -Unix libraries by default. You can suppress one of these by adding one of -.sp - --disable-shared - --disable-static -.sp -to the \fBconfigure\fP command, as required. -. -. -.SH "C++ SUPPORT" -.rs -.sp -By default, if the 8-bit library is being built, the \fBconfigure\fP script -will search for a C++ compiler and C++ header files. If it finds them, it -automatically builds the C++ wrapper library (which supports only 8-bit -strings). You can disable this by adding -.sp - --disable-cpp -.sp -to the \fBconfigure\fP command. -. -. -.SH "UTF-8 and UTF-16 SUPPORT" -.rs -.sp -To build PCRE with support for UTF Unicode character strings, add -.sp - --enable-utf -.sp -to the \fBconfigure\fP command. This setting applies to both libraries, adding -support for UTF-8 to the 8-bit library and support for UTF-16 to the 16-bit -library. There are no separate options for enabling UTF-8 and UTF-16 -independently because that would allow ridiculous settings such as requesting -UTF-16 support while building only the 8-bit library. It is not possible to -build one library with UTF support and the other without in the same -configuration. (For backwards compatibility, --enable-utf8 is a synonym of ---enable-utf.) -.P -Of itself, this setting does not make PCRE treat strings as UTF-8 or UTF-16. As -well as compiling PCRE with this option, you also have have to set the -PCRE_UTF8 or PCRE_UTF16 option when you call one of the pattern compiling -functions. -.P -If you set --enable-utf when compiling in an EBCDIC environment, PCRE expects -its input to be either ASCII or UTF-8 (depending on the run-time option). It is -not possible to support both EBCDIC and UTF-8 codes in the same version of the -library. Consequently, --enable-utf and --enable-ebcdic are mutually -exclusive. -. -. -.SH "UNICODE CHARACTER PROPERTY SUPPORT" -.rs -.sp -UTF support allows the libraries to process character codepoints up to 0x10ffff -in the strings that they handle. On its own, however, it does not provide any -facilities for accessing the properties of such characters. If you want to be -able to use the pattern escapes \eP, \ep, and \eX, which refer to Unicode -character properties, you must add -.sp - --enable-unicode-properties -.sp -to the \fBconfigure\fP command. This implies UTF support, even if you have -not explicitly requested it. -.P -Including Unicode property support adds around 30K of tables to the PCRE -library. Only the general category properties such as \fILu\fP and \fINd\fP are -supported. Details are given in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation. -. -. -.SH "JUST-IN-TIME COMPILER SUPPORT" -.rs -.sp -Just-in-time compiler support is included in the build by specifying -.sp - --enable-jit -.sp -This support is available only for certain hardware architectures. If this -option is set for an unsupported architecture, a compile time error occurs. -See the -.\" HREF -\fBpcrejit\fP -.\" -documentation for a discussion of JIT usage. When JIT support is enabled, -pcregrep automatically makes use of it, unless you add -.sp - --disable-pcregrep-jit -.sp -to the "configure" command. -. -. -.SH "CODE VALUE OF NEWLINE" -.rs -.sp -By default, PCRE interprets the linefeed (LF) character as indicating the end -of a line. This is the normal newline character on Unix-like systems. You can -compile PCRE to use carriage return (CR) instead, by adding -.sp - --enable-newline-is-cr -.sp -to the \fBconfigure\fP command. There is also a --enable-newline-is-lf option, -which explicitly specifies linefeed as the newline character. -.sp -Alternatively, you can specify that line endings are to be indicated by the two -character sequence CRLF. If you want this, add -.sp - --enable-newline-is-crlf -.sp -to the \fBconfigure\fP command. There is a fourth option, specified by -.sp - --enable-newline-is-anycrlf -.sp -which causes PCRE to recognize any of the three sequences CR, LF, or CRLF as -indicating a line ending. Finally, a fifth option, specified by -.sp - --enable-newline-is-any -.sp -causes PCRE to recognize any Unicode newline sequence. -.P -Whatever line ending convention is selected when PCRE is built can be -overridden when the library functions are called. At build time it is -conventional to use the standard for your operating system. -. -. -.SH "WHAT \eR MATCHES" -.rs -.sp -By default, the sequence \eR in a pattern matches any Unicode newline sequence, -whatever has been selected as the line ending sequence. If you specify -.sp - --enable-bsr-anycrlf -.sp -the default is changed so that \eR matches only CR, LF, or CRLF. Whatever is -selected when PCRE is built can be overridden when the library functions are -called. -. -. -.SH "POSIX MALLOC USAGE" -.rs -.sp -When the 8-bit library is called through the POSIX interface (see the -.\" HREF -\fBpcreposix\fP -.\" -documentation), additional working storage is required for holding the pointers -to capturing substrings, because PCRE requires three integers per substring, -whereas the POSIX interface provides only two. If the number of expected -substrings is small, the wrapper function uses space on the stack, because this -is faster than using \fBmalloc()\fP for each call. The default threshold above -which the stack is no longer used is 10; it can be changed by adding a setting -such as -.sp - --with-posix-malloc-threshold=20 -.sp -to the \fBconfigure\fP command. -. -. -.SH "HANDLING VERY LARGE PATTERNS" -.rs -.sp -Within a compiled pattern, offset values are used to point from one part to -another (for example, from an opening parenthesis to an alternation -metacharacter). By default, two-byte values are used for these offsets, leading -to a maximum size for a compiled pattern of around 64K. This is sufficient to -handle all but the most gigantic patterns. Nevertheless, some people do want to -process truly enormous patterns, so it is possible to compile PCRE to use -three-byte or four-byte offsets by adding a setting such as -.sp - --with-link-size=3 -.sp -to the \fBconfigure\fP command. The value given must be 2, 3, or 4. For the -16-bit library, a value of 3 is rounded up to 4. Using longer offsets slows -down the operation of PCRE because it has to load additional data when handling -them. -. -. -.SH "AVOIDING EXCESSIVE STACK USAGE" -.rs -.sp -When matching with the \fBpcre_exec()\fP function, PCRE implements backtracking -by making recursive calls to an internal function called \fBmatch()\fP. In -environments where the size of the stack is limited, this can severely limit -PCRE's operation. (The Unix environment does not usually suffer from this -problem, but it may sometimes be necessary to increase the maximum stack size. -There is a discussion in the -.\" HREF -\fBpcrestack\fP -.\" -documentation.) An alternative approach to recursion that uses memory from the -heap to remember data, instead of using recursive function calls, has been -implemented to work round the problem of limited stack size. If you want to -build a version of PCRE that works this way, add -.sp - --disable-stack-for-recursion -.sp -to the \fBconfigure\fP command. With this configuration, PCRE will use the -\fBpcre_stack_malloc\fP and \fBpcre_stack_free\fP variables to call memory -management functions. By default these point to \fBmalloc()\fP and -\fBfree()\fP, but you can replace the pointers so that your own functions are -used instead. -.P -Separate functions are provided rather than using \fBpcre_malloc\fP and -\fBpcre_free\fP because the usage is very predictable: the block sizes -requested are always the same, and the blocks are always freed in reverse -order. A calling program might be able to implement optimized functions that -perform better than \fBmalloc()\fP and \fBfree()\fP. PCRE runs noticeably more -slowly when built in this way. This option affects only the \fBpcre_exec()\fP -function; it is not relevant for \fBpcre_dfa_exec()\fP. -. -. -.SH "LIMITING PCRE RESOURCE USAGE" -.rs -.sp -Internally, PCRE has a function called \fBmatch()\fP, which it calls repeatedly -(sometimes recursively) when matching a pattern with the \fBpcre_exec()\fP -function. By controlling the maximum number of times this function may be -called during a single matching operation, a limit can be placed on the -resources used by a single call to \fBpcre_exec()\fP. The limit can be changed -at run time, as described in the -.\" HREF -\fBpcreapi\fP -.\" -documentation. The default is 10 million, but this can be changed by adding a -setting such as -.sp - --with-match-limit=500000 -.sp -to the \fBconfigure\fP command. This setting has no effect on the -\fBpcre_dfa_exec()\fP matching function. -.P -In some environments it is desirable to limit the depth of recursive calls of -\fBmatch()\fP more strictly than the total number of calls, in order to -restrict the maximum amount of stack (or heap, if --disable-stack-for-recursion -is specified) that is used. A second limit controls this; it defaults to the -value that is set for --with-match-limit, which imposes no additional -constraints. However, you can set a lower limit by adding, for example, -.sp - --with-match-limit-recursion=10000 -.sp -to the \fBconfigure\fP command. This value can also be overridden at run time. -. -. -.SH "CREATING CHARACTER TABLES AT BUILD TIME" -.rs -.sp -PCRE uses fixed tables for processing characters whose code values are less -than 256. By default, PCRE is built with a set of tables that are distributed -in the file \fIpcre_chartables.c.dist\fP. These tables are for ASCII codes -only. If you add -.sp - --enable-rebuild-chartables -.sp -to the \fBconfigure\fP command, the distributed tables are no longer used. -Instead, a program called \fBdftables\fP is compiled and run. This outputs the -source for new set of tables, created in the default locale of your C run-time -system. (This method of replacing the tables does not work if you are cross -compiling, because \fBdftables\fP is run on the local host. If you need to -create alternative tables when cross compiling, you will have to do so "by -hand".) -. -. -.SH "USING EBCDIC CODE" -.rs -.sp -PCRE assumes by default that it will run in an environment where the character -code is ASCII (or Unicode, which is a superset of ASCII). This is the case for -most computer operating systems. PCRE can, however, be compiled to run in an -EBCDIC environment by adding -.sp - --enable-ebcdic -.sp -to the \fBconfigure\fP command. This setting implies ---enable-rebuild-chartables. You should only use it if you know that you are in -an EBCDIC environment (for example, an IBM mainframe operating system). The ---enable-ebcdic option is incompatible with --enable-utf. -. -. -.SH "PCREGREP OPTIONS FOR COMPRESSED FILE SUPPORT" -.rs -.sp -By default, \fBpcregrep\fP reads all files as plain text. You can build it so -that it recognizes files whose names end in \fB.gz\fP or \fB.bz2\fP, and reads -them with \fBlibz\fP or \fBlibbz2\fP, respectively, by adding one or both of -.sp - --enable-pcregrep-libz - --enable-pcregrep-libbz2 -.sp -to the \fBconfigure\fP command. These options naturally require that the -relevant libraries are installed on your system. Configuration will fail if -they are not. -. -. -.SH "PCREGREP BUFFER SIZE" -.rs -.sp -\fBpcregrep\fP uses an internal buffer to hold a "window" on the file it is -scanning, in order to be able to output "before" and "after" lines when it -finds a match. The size of the buffer is controlled by a parameter whose -default value is 20K. The buffer itself is three times this size, but because -of the way it is used for holding "before" lines, the longest line that is -guaranteed to be processable is the parameter size. You can change the default -parameter value by adding, for example, -.sp - --with-pcregrep-bufsize=50K -.sp -to the \fBconfigure\fP command. The caller of \fPpcregrep\fP can, however, -override this value by specifying a run-time option. -. -. -.SH "PCRETEST OPTION FOR LIBREADLINE SUPPORT" -.rs -.sp -If you add -.sp - --enable-pcretest-libreadline -.sp -to the \fBconfigure\fP command, \fBpcretest\fP is linked with the -\fBlibreadline\fP library, and when its input is from a terminal, it reads it -using the \fBreadline()\fP function. This provides line-editing and history -facilities. Note that \fBlibreadline\fP is GPL-licensed, so if you distribute a -binary of \fBpcretest\fP linked in this way, there may be licensing issues. -.P -Setting this option causes the \fB-lreadline\fP option to be added to the -\fBpcretest\fP build. In many operating environments with a sytem-installed -\fBlibreadline\fP this is sufficient. However, in some environments (e.g. -if an unmodified distribution version of readline is in use), some extra -configuration may be necessary. The INSTALL file for \fBlibreadline\fP says -this: -.sp - "Readline uses the termcap functions, but does not link with the - termcap or curses library itself, allowing applications which link - with readline the to choose an appropriate library." -.sp -If your environment has not been set up so that an appropriate library is -automatically included, you may need to add something like -.sp - LIBS="-ncurses" -.sp -immediately before the \fBconfigure\fP command. -. -. -.SH "SEE ALSO" -.rs -.sp -\fBpcreapi\fP(3), \fBpcre16\fP, \fBpcre_config\fP(3). -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 07 January 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcrecallout.3 b/gtk+-mingw/share/man/man3/pcrecallout.3 deleted file mode 100644 index 6d30111..0000000 --- a/gtk+-mingw/share/man/man3/pcrecallout.3 +++ /dev/null @@ -1,203 +0,0 @@ -.TH PCRECALLOUT 3 "08 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PCRE CALLOUTS" -.rs -.sp -.B int (*pcre_callout)(pcre_callout_block *); -.PP -.B int (*pcre16_callout)(pcre16_callout_block *); -.PP -PCRE provides a feature called "callout", which is a means of temporarily -passing control to the caller of PCRE in the middle of pattern matching. The -caller of PCRE provides an external function by putting its entry point in the -global variable \fIpcre_callout\fP (\fIpcre16_callout\fP for the 16-bit -library). By default, this variable contains NULL, which disables all calling -out. -.P -Within a regular expression, (?C) indicates the points at which the external -function is to be called. Different callout points can be identified by putting -a number less than 256 after the letter C. The default value is zero. -For example, this pattern has two callout points: -.sp - (?C1)abc(?C2)def -.sp -If the PCRE_AUTO_CALLOUT option bit is set when a pattern is compiled, PCRE -automatically inserts callouts, all with number 255, before each item in the -pattern. For example, if PCRE_AUTO_CALLOUT is used with the pattern -.sp - A(\ed{2}|--) -.sp -it is processed as if it were -.sp -(?C255)A(?C255)((?C255)\ed{2}(?C255)|(?C255)-(?C255)-(?C255))(?C255) -.sp -Notice that there is a callout before and after each parenthesis and -alternation bar. Automatic callouts can be used for tracking the progress of -pattern matching. The -.\" HREF -\fBpcretest\fP -.\" -command has an option that sets automatic callouts; when it is used, the output -indicates how the pattern is matched. This is useful information when you are -trying to optimize the performance of a particular pattern. -.P -The use of callouts in a pattern makes it ineligible for optimization by the -just-in-time compiler. Studying such a pattern with the PCRE_STUDY_JIT_COMPILE -option always fails. -. -. -.SH "MISSING CALLOUTS" -.rs -.sp -You should be aware that, because of optimizations in the way PCRE matches -patterns by default, callouts sometimes do not happen. For example, if the -pattern is -.sp - ab(?C4)cd -.sp -PCRE knows that any matching string must contain the letter "d". If the subject -string is "abyz", the lack of "d" means that matching doesn't ever start, and -the callout is never reached. However, with "abyd", though the result is still -no match, the callout is obeyed. -.P -If the pattern is studied, PCRE knows the minimum length of a matching string, -and will immediately give a "no match" return without actually running a match -if the subject is not long enough, or, for unanchored patterns, if it has -been scanned far enough. -.P -You can disable these optimizations by passing the PCRE_NO_START_OPTIMIZE -option to the matching function, or by starting the pattern with -(*NO_START_OPT). This slows down the matching process, but does ensure that -callouts such as the example above are obeyed. -. -. -.SH "THE CALLOUT INTERFACE" -.rs -.sp -During matching, when PCRE reaches a callout point, the external function -defined by \fIpcre_callout\fP or \fIpcre16_callout\fP is called (if it is set). -This applies to both normal and DFA matching. The only argument to the callout -function is a pointer to a \fBpcre_callout\fP or \fBpcre16_callout\fP block. -These structures contains the following fields: -.sp - int \fIversion\fP; - int \fIcallout_number\fP; - int *\fIoffset_vector\fP; - const char *\fIsubject\fP; (8-bit version) - PCRE_SPTR16 \fIsubject\fP; (16-bit version) - int \fIsubject_length\fP; - int \fIstart_match\fP; - int \fIcurrent_position\fP; - int \fIcapture_top\fP; - int \fIcapture_last\fP; - void *\fIcallout_data\fP; - int \fIpattern_position\fP; - int \fInext_item_length\fP; - const unsigned char *\fImark\fP; (8-bit version) - const PCRE_UCHAR16 *\fImark\fP; (16-bit version) -.sp -The \fIversion\fP field is an integer containing the version number of the -block format. The initial version was 0; the current version is 2. The version -number will change again in future if additional fields are added, but the -intention is never to remove any of the existing fields. -.P -The \fIcallout_number\fP field contains the number of the callout, as compiled -into the pattern (that is, the number after ?C for manual callouts, and 255 for -automatically generated callouts). -.P -The \fIoffset_vector\fP field is a pointer to the vector of offsets that was -passed by the caller to the matching function. When \fBpcre_exec()\fP or -\fBpcre16_exec()\fP is used, the contents can be inspected, in order to extract -substrings that have been matched so far, in the same way as for extracting -substrings after a match has completed. For the DFA matching functions, this -field is not useful. -.P -The \fIsubject\fP and \fIsubject_length\fP fields contain copies of the values -that were passed to the matching function. -.P -The \fIstart_match\fP field normally contains the offset within the subject at -which the current match attempt started. However, if the escape sequence \eK -has been encountered, this value is changed to reflect the modified starting -point. If the pattern is not anchored, the callout function may be called -several times from the same point in the pattern for different starting points -in the subject. -.P -The \fIcurrent_position\fP field contains the offset within the subject of the -current match pointer. -.P -When the \fBpcre_exec()\fP or \fBpcre16_exec()\fP is used, the -\fIcapture_top\fP field contains one more than the number of the highest -numbered captured substring so far. If no substrings have been captured, the -value of \fIcapture_top\fP is one. This is always the case when the DFA -functions are used, because they do not support captured substrings. -.P -The \fIcapture_last\fP field contains the number of the most recently captured -substring. If no substrings have been captured, its value is -1. This is always -the case for the DFA matching functions. -.P -The \fIcallout_data\fP field contains a value that is passed to a matching -function specifically so that it can be passed back in callouts. It is passed -in the \fIcallout_data\fP field of a \fBpcre_extra\fP or \fBpcre16_extra\fP -data structure. If no such data was passed, the value of \fIcallout_data\fP in -a callout block is NULL. There is a description of the \fBpcre_extra\fP -structure in the -.\" HREF -\fBpcreapi\fP -.\" -documentation. -.P -The \fIpattern_position\fP field is present from version 1 of the callout -structure. It contains the offset to the next item to be matched in the pattern -string. -.P -The \fInext_item_length\fP field is present from version 1 of the callout -structure. It contains the length of the next item to be matched in the pattern -string. When the callout immediately precedes an alternation bar, a closing -parenthesis, or the end of the pattern, the length is zero. When the callout -precedes an opening parenthesis, the length is that of the entire subpattern. -.P -The \fIpattern_position\fP and \fInext_item_length\fP fields are intended to -help in distinguishing between different automatic callouts, which all have the -same callout number. However, they are set for all callouts. -.P -The \fImark\fP field is present from version 2 of the callout structure. In -callouts from \fBpcre_exec()\fP or \fBpcre16_exec()\fP it contains a pointer to -the zero-terminated name of the most recently passed (*MARK), (*PRUNE), or -(*THEN) item in the match, or NULL if no such items have been passed. Instances -of (*PRUNE) or (*THEN) without a name do not obliterate a previous (*MARK). In -callouts from the DFA matching functions this field always contains NULL. -. -. -.SH "RETURN VALUES" -.rs -.sp -The external callout function returns an integer to PCRE. If the value is zero, -matching proceeds as normal. If the value is greater than zero, matching fails -at the current point, but the testing of other matching possibilities goes -ahead, just as if a lookahead assertion had failed. If the value is less than -zero, the match is abandoned, the matching function returns the negative value. -.P -Negative values should normally be chosen from the set of PCRE_ERROR_xxx -values. In particular, PCRE_ERROR_NOMATCH forces a standard "no match" failure. -The error number PCRE_ERROR_CALLOUT is reserved for use by callout functions; -it will never be used by PCRE itself. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 08 Janurary 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcrecompat.3 b/gtk+-mingw/share/man/man3/pcrecompat.3 deleted file mode 100644 index 45856e4..0000000 --- a/gtk+-mingw/share/man/man3/pcrecompat.3 +++ /dev/null @@ -1,188 +0,0 @@ -.TH PCRECOMPAT 3 "08 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "DIFFERENCES BETWEEN PCRE AND PERL" -.rs -.sp -This document describes the differences in the ways that PCRE and Perl handle -regular expressions. The differences described here are with respect to Perl -versions 5.10 and above. -.P -1. PCRE has only a subset of Perl's Unicode support. Details of what it does -have are given in the -.\" HREF -\fBpcreunicode\fP -.\" -page. -.P -2. PCRE allows repeat quantifiers only on parenthesized assertions, but they do -not mean what you might think. For example, (?!a){3} does not assert that the -next three characters are not "a". It just asserts that the next character is -not "a" three times (in principle: PCRE optimizes this to run the assertion -just once). Perl allows repeat quantifiers on other assertions such as \eb, but -these do not seem to have any use. -.P -3. Capturing subpatterns that occur inside negative lookahead assertions are -counted, but their entries in the offsets vector are never set. Perl sets its -numerical variables from any such patterns that are matched before the -assertion fails to match something (thereby succeeding), but only if the -negative lookahead assertion contains just one branch. -.P -4. Though binary zero characters are supported in the subject string, they are -not allowed in a pattern string because it is passed as a normal C string, -terminated by zero. The escape sequence \e0 can be used in the pattern to -represent a binary zero. -.P -5. The following Perl escape sequences are not supported: \el, \eu, \eL, -\eU, and \eN when followed by a character name or Unicode value. (\eN on its -own, matching a non-newline character, is supported.) In fact these are -implemented by Perl's general string-handling and are not part of its pattern -matching engine. If any of these are encountered by PCRE, an error is -generated by default. However, if the PCRE_JAVASCRIPT_COMPAT option is set, -\eU and \eu are interpreted as JavaScript interprets them. -.P -6. The Perl escape sequences \ep, \eP, and \eX are supported only if PCRE is -built with Unicode character property support. The properties that can be -tested with \ep and \eP are limited to the general category properties such as -Lu and Nd, script names such as Greek or Han, and the derived properties Any -and L&. PCRE does support the Cs (surrogate) property, which Perl does not; the -Perl documentation says "Because Perl hides the need for the user to understand -the internal representation of Unicode characters, there is no need to -implement the somewhat messy concept of surrogates." -.P -7. PCRE implements a simpler version of \eX than Perl, which changed to make -\eX match what Unicode calls an "extended grapheme cluster". This is more -complicated than an extended Unicode sequence, which is what PCRE matches. -.P -8. PCRE does support the \eQ...\eE escape for quoting substrings. Characters in -between are treated as literals. This is slightly different from Perl in that $ -and @ are also handled as literals inside the quotes. In Perl, they cause -variable interpolation (but of course PCRE does not have variables). Note the -following examples: -.sp - Pattern PCRE matches Perl matches -.sp -.\" JOIN - \eQabc$xyz\eE abc$xyz abc followed by the - contents of $xyz - \eQabc\e$xyz\eE abc\e$xyz abc\e$xyz - \eQabc\eE\e$\eQxyz\eE abc$xyz abc$xyz -.sp -The \eQ...\eE sequence is recognized both inside and outside character classes. -.P -9. Fairly obviously, PCRE does not support the (?{code}) and (??{code}) -constructions. However, there is support for recursive patterns. This is not -available in Perl 5.8, but it is in Perl 5.10. Also, the PCRE "callout" -feature allows an external function to be called during pattern matching. See -the -.\" HREF -\fBpcrecallout\fP -.\" -documentation for details. -.P -10. Subpatterns that are called as subroutines (whether or not recursively) are -always treated as atomic groups in PCRE. This is like Python, but unlike Perl. -Captured values that are set outside a subroutine call can be reference from -inside in PCRE, but not in Perl. There is a discussion that explains these -differences in more detail in the -.\" HTML <a href="pcrepattern.html#recursiondifference"> -.\" </a> -section on recursion differences from Perl -.\" -in the -.\" HREF -\fBpcrepattern\fP -.\" -page. -.P -11. If any of the backtracking control verbs are used in an assertion or in a -subpattern that is called as a subroutine (whether or not recursively), their -effect is confined to that subpattern; it does not extend to the surrounding -pattern. This is not always the case in Perl. In particular, if (*THEN) is -present in a group that is called as a subroutine, its action is limited to -that group, even if the group does not contain any | characters. There is one -exception to this: the name from a *(MARK), (*PRUNE), or (*THEN) that is -encountered in a successful positive assertion \fIis\fP passed back when a -match succeeds (compare capturing parentheses in assertions). Note that such -subpatterns are processed as anchored at the point where they are tested. -.P -12. There are some differences that are concerned with the settings of captured -strings when part of a pattern is repeated. For example, matching "aba" against -the pattern /^(a(b)?)+$/ in Perl leaves $2 unset, but in PCRE it is set to "b". -.P -13. PCRE's handling of duplicate subpattern numbers and duplicate subpattern -names is not as general as Perl's. This is a consequence of the fact the PCRE -works internally just with numbers, using an external table to translate -between numbers and names. In particular, a pattern such as (?|(?<a>A)|(?<b)B), -where the two capturing parentheses have the same number but different names, -is not supported, and causes an error at compile time. If it were allowed, it -would not be possible to distinguish which parentheses matched, because both -names map to capturing subpattern number 1. To avoid this confusing situation, -an error is given at compile time. -.P -14. Perl recognizes comments in some places that PCRE does not, for example, -between the ( and ? at the start of a subpattern. If the /x modifier is set, -Perl allows white space between ( and ? but PCRE never does, even if the -PCRE_EXTENDED option is set. -.P -15. PCRE provides some extensions to the Perl regular expression facilities. -Perl 5.10 includes new features that are not in earlier versions of Perl, some -of which (such as named parentheses) have been in PCRE for some time. This list -is with respect to Perl 5.10: -.sp -(a) Although lookbehind assertions in PCRE must match fixed length strings, -each alternative branch of a lookbehind assertion can match a different length -of string. Perl requires them all to have the same length. -.sp -(b) If PCRE_DOLLAR_ENDONLY is set and PCRE_MULTILINE is not set, the $ -meta-character matches only at the very end of the string. -.sp -(c) If PCRE_EXTRA is set, a backslash followed by a letter with no special -meaning is faulted. Otherwise, like Perl, the backslash is quietly ignored. -(Perl can be made to issue a warning.) -.sp -(d) If PCRE_UNGREEDY is set, the greediness of the repetition quantifiers is -inverted, that is, by default they are not greedy, but if followed by a -question mark they are. -.sp -(e) PCRE_ANCHORED can be used at matching time to force a pattern to be tried -only at the first matching position in the subject string. -.sp -(f) The PCRE_NOTBOL, PCRE_NOTEOL, PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, and -PCRE_NO_AUTO_CAPTURE options for \fBpcre_exec()\fP have no Perl equivalents. -.sp -(g) The \eR escape sequence can be restricted to match only CR, LF, or CRLF -by the PCRE_BSR_ANYCRLF option. -.sp -(h) The callout facility is PCRE-specific. -.sp -(i) The partial matching facility is PCRE-specific. -.sp -(j) Patterns compiled by PCRE can be saved and re-used at a later time, even on -different hosts that have the other endianness. However, this does not apply to -optimized data created by the just-in-time compiler. -.sp -(k) The alternative matching functions (\fBpcre_dfa_exec()\fP and -\fBpcre16_dfa_exec()\fP) match in a different way and are not Perl-compatible. -.sp -(l) PCRE recognizes some special sequences such as (*CR) at the start of -a pattern that set overall options that cannot be changed within the pattern. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 01 June 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcrecpp.3 b/gtk+-mingw/share/man/man3/pcrecpp.3 deleted file mode 100644 index fb1c00a..0000000 --- a/gtk+-mingw/share/man/man3/pcrecpp.3 +++ /dev/null @@ -1,348 +0,0 @@ -.TH PCRECPP 3 "08 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions. -.SH "SYNOPSIS OF C++ WRAPPER" -.rs -.sp -.B #include <pcrecpp.h> -. -.SH DESCRIPTION -.rs -.sp -The C++ wrapper for PCRE was provided by Google Inc. Some additional -functionality was added by Giuseppe Maxia. This brief man page was constructed -from the notes in the \fIpcrecpp.h\fP file, which should be consulted for -further details. Note that the C++ wrapper supports only the original 8-bit -PCRE library. There is no 16-bit support at present. -. -. -.SH "MATCHING INTERFACE" -.rs -.sp -The "FullMatch" operation checks that supplied text matches a supplied pattern -exactly. If pointer arguments are supplied, it copies matched sub-strings that -match sub-patterns into them. -.sp - Example: successful match - pcrecpp::RE re("h.*o"); - re.FullMatch("hello"); -.sp - Example: unsuccessful match (requires full match): - pcrecpp::RE re("e"); - !re.FullMatch("hello"); -.sp - Example: creating a temporary RE object: - pcrecpp::RE("h.*o").FullMatch("hello"); -.sp -You can pass in a "const char*" or a "string" for "text". The examples below -tend to use a const char*. You can, as in the different examples above, store -the RE object explicitly in a variable or use a temporary RE object. The -examples below use one mode or the other arbitrarily. Either could correctly be -used for any of these examples. -.P -You must supply extra pointer arguments to extract matched subpieces. -.sp - Example: extracts "ruby" into "s" and 1234 into "i" - int i; - string s; - pcrecpp::RE re("(\e\ew+):(\e\ed+)"); - re.FullMatch("ruby:1234", &s, &i); -.sp - Example: does not try to extract any extra sub-patterns - re.FullMatch("ruby:1234", &s); -.sp - Example: does not try to extract into NULL - re.FullMatch("ruby:1234", NULL, &i); -.sp - Example: integer overflow causes failure - !re.FullMatch("ruby:1234567891234", NULL, &i); -.sp - Example: fails because there aren't enough sub-patterns: - !pcrecpp::RE("\e\ew+:\e\ed+").FullMatch("ruby:1234", &s); -.sp - Example: fails because string cannot be stored in integer - !pcrecpp::RE("(.*)").FullMatch("ruby", &i); -.sp -The provided pointer arguments can be pointers to any scalar numeric -type, or one of: -.sp - string (matched piece is copied to string) - StringPiece (StringPiece is mutated to point to matched piece) - T (where "bool T::ParseFrom(const char*, int)" exists) - NULL (the corresponding matched sub-pattern is not copied) -.sp -The function returns true iff all of the following conditions are satisfied: -.sp - a. "text" matches "pattern" exactly; -.sp - b. The number of matched sub-patterns is >= number of supplied - pointers; -.sp - c. The "i"th argument has a suitable type for holding the - string captured as the "i"th sub-pattern. If you pass in - void * NULL for the "i"th argument, or a non-void * NULL - of the correct type, or pass fewer arguments than the - number of sub-patterns, "i"th captured sub-pattern is - ignored. -.sp -CAVEAT: An optional sub-pattern that does not exist in the matched -string is assigned the empty string. Therefore, the following will -return false (because the empty string is not a valid number): -.sp - int number; - pcrecpp::RE::FullMatch("abc", "[a-z]+(\e\ed+)?", &number); -.sp -The matching interface supports at most 16 arguments per call. -If you need more, consider using the more general interface -\fBpcrecpp::RE::DoMatch\fP. See \fBpcrecpp.h\fP for the signature for -\fBDoMatch\fP. -.P -NOTE: Do not use \fBno_arg\fP, which is used internally to mark the end of a -list of optional arguments, as a placeholder for missing arguments, as this can -lead to segfaults. -. -. -.SH "QUOTING METACHARACTERS" -.rs -.sp -You can use the "QuoteMeta" operation to insert backslashes before all -potentially meaningful characters in a string. The returned string, used as a -regular expression, will exactly match the original string. -.sp - Example: - string quoted = RE::QuoteMeta(unquoted); -.sp -Note that it's legal to escape a character even if it has no special meaning in -a regular expression -- so this function does that. (This also makes it -identical to the perl function of the same name; see "perldoc -f quotemeta".) -For example, "1.5-2.0?" becomes "1\e.5\e-2\e.0\e?". -. -.SH "PARTIAL MATCHES" -.rs -.sp -You can use the "PartialMatch" operation when you want the pattern -to match any substring of the text. -.sp - Example: simple search for a string: - pcrecpp::RE("ell").PartialMatch("hello"); -.sp - Example: find first number in a string: - int number; - pcrecpp::RE re("(\e\ed+)"); - re.PartialMatch("x*100 + 20", &number); - assert(number == 100); -. -. -.SH "UTF-8 AND THE MATCHING INTERFACE" -.rs -.sp -By default, pattern and text are plain text, one byte per character. The UTF8 -flag, passed to the constructor, causes both pattern and string to be treated -as UTF-8 text, still a byte stream but potentially multiple bytes per -character. In practice, the text is likelier to be UTF-8 than the pattern, but -the match returned may depend on the UTF8 flag, so always use it when matching -UTF8 text. For example, "." will match one byte normally but with UTF8 set may -match up to three bytes of a multi-byte character. -.sp - Example: - pcrecpp::RE_Options options; - options.set_utf8(); - pcrecpp::RE re(utf8_pattern, options); - re.FullMatch(utf8_string); -.sp - Example: using the convenience function UTF8(): - pcrecpp::RE re(utf8_pattern, pcrecpp::UTF8()); - re.FullMatch(utf8_string); -.sp -NOTE: The UTF8 flag is ignored if pcre was not configured with the - --enable-utf8 flag. -. -. -.SH "PASSING MODIFIERS TO THE REGULAR EXPRESSION ENGINE" -.rs -.sp -PCRE defines some modifiers to change the behavior of the regular expression -engine. The C++ wrapper defines an auxiliary class, RE_Options, as a vehicle to -pass such modifiers to a RE class. Currently, the following modifiers are -supported: -.sp - modifier description Perl corresponding -.sp - PCRE_CASELESS case insensitive match /i - PCRE_MULTILINE multiple lines match /m - PCRE_DOTALL dot matches newlines /s - PCRE_DOLLAR_ENDONLY $ matches only at end N/A - PCRE_EXTRA strict escape parsing N/A - PCRE_EXTENDED ignore white spaces /x - PCRE_UTF8 handles UTF8 chars built-in - PCRE_UNGREEDY reverses * and *? N/A - PCRE_NO_AUTO_CAPTURE disables capturing parens N/A (*) -.sp -(*) Both Perl and PCRE allow non capturing parentheses by means of the -"?:" modifier within the pattern itself. e.g. (?:ab|cd) does not -capture, while (ab|cd) does. -.P -For a full account on how each modifier works, please check the -PCRE API reference page. -.P -For each modifier, there are two member functions whose name is made -out of the modifier in lowercase, without the "PCRE_" prefix. For -instance, PCRE_CASELESS is handled by -.sp - bool caseless() -.sp -which returns true if the modifier is set, and -.sp - RE_Options & set_caseless(bool) -.sp -which sets or unsets the modifier. Moreover, PCRE_EXTRA_MATCH_LIMIT can be -accessed through the \fBset_match_limit()\fP and \fBmatch_limit()\fP member -functions. Setting \fImatch_limit\fP to a non-zero value will limit the -execution of pcre to keep it from doing bad things like blowing the stack or -taking an eternity to return a result. A value of 5000 is good enough to stop -stack blowup in a 2MB thread stack. Setting \fImatch_limit\fP to zero disables -match limiting. Alternatively, you can call \fBmatch_limit_recursion()\fP -which uses PCRE_EXTRA_MATCH_LIMIT_RECURSION to limit how much PCRE -recurses. \fBmatch_limit()\fP limits the number of matches PCRE does; -\fBmatch_limit_recursion()\fP limits the depth of internal recursion, and -therefore the amount of stack that is used. -.P -Normally, to pass one or more modifiers to a RE class, you declare -a \fIRE_Options\fP object, set the appropriate options, and pass this -object to a RE constructor. Example: -.sp - RE_Options opt; - opt.set_caseless(true); - if (RE("HELLO", opt).PartialMatch("hello world")) ... -.sp -RE_options has two constructors. The default constructor takes no arguments and -creates a set of flags that are off by default. The optional parameter -\fIoption_flags\fP is to facilitate transfer of legacy code from C programs. -This lets you do -.sp - RE(pattern, - RE_Options(PCRE_CASELESS|PCRE_MULTILINE)).PartialMatch(str); -.sp -However, new code is better off doing -.sp - RE(pattern, - RE_Options().set_caseless(true).set_multiline(true)) - .PartialMatch(str); -.sp -If you are going to pass one of the most used modifiers, there are some -convenience functions that return a RE_Options class with the -appropriate modifier already set: \fBCASELESS()\fP, \fBUTF8()\fP, -\fBMULTILINE()\fP, \fBDOTALL\fP(), and \fBEXTENDED()\fP. -.P -If you need to set several options at once, and you don't want to go through -the pains of declaring a RE_Options object and setting several options, there -is a parallel method that give you such ability on the fly. You can concatenate -several \fBset_xxxxx()\fP member functions, since each of them returns a -reference to its class object. For example, to pass PCRE_CASELESS, -PCRE_EXTENDED, and PCRE_MULTILINE to a RE with one statement, you may write: -.sp - RE(" ^ xyz \e\es+ .* blah$", - RE_Options() - .set_caseless(true) - .set_extended(true) - .set_multiline(true)).PartialMatch(sometext); -.sp -. -. -.SH "SCANNING TEXT INCREMENTALLY" -.rs -.sp -The "Consume" operation may be useful if you want to repeatedly -match regular expressions at the front of a string and skip over -them as they match. This requires use of the "StringPiece" type, -which represents a sub-range of a real string. Like RE, StringPiece -is defined in the pcrecpp namespace. -.sp - Example: read lines of the form "var = value" from a string. - string contents = ...; // Fill string somehow - pcrecpp::StringPiece input(contents); // Wrap in a StringPiece -.sp - string var; - int value; - pcrecpp::RE re("(\e\ew+) = (\e\ed+)\en"); - while (re.Consume(&input, &var, &value)) { - ...; - } -.sp -Each successful call to "Consume" will set "var/value", and also -advance "input" so it points past the matched text. -.P -The "FindAndConsume" operation is similar to "Consume" but does not -anchor your match at the beginning of the string. For example, you -could extract all words from a string by repeatedly calling -.sp - pcrecpp::RE("(\e\ew+)").FindAndConsume(&input, &word) -. -. -.SH "PARSING HEX/OCTAL/C-RADIX NUMBERS" -.rs -.sp -By default, if you pass a pointer to a numeric value, the -corresponding text is interpreted as a base-10 number. You can -instead wrap the pointer with a call to one of the operators Hex(), -Octal(), or CRadix() to interpret the text in another base. The -CRadix operator interprets C-style "0" (base-8) and "0x" (base-16) -prefixes, but defaults to base-10. -.sp - Example: - int a, b, c, d; - pcrecpp::RE re("(.*) (.*) (.*) (.*)"); - re.FullMatch("100 40 0100 0x40", - pcrecpp::Octal(&a), pcrecpp::Hex(&b), - pcrecpp::CRadix(&c), pcrecpp::CRadix(&d)); -.sp -will leave 64 in a, b, c, and d. -. -. -.SH "REPLACING PARTS OF STRINGS" -.rs -.sp -You can replace the first match of "pattern" in "str" with "rewrite". -Within "rewrite", backslash-escaped digits (\e1 to \e9) can be -used to insert text matching corresponding parenthesized group -from the pattern. \e0 in "rewrite" refers to the entire matching -text. For example: -.sp - string s = "yabba dabba doo"; - pcrecpp::RE("b+").Replace("d", &s); -.sp -will leave "s" containing "yada dabba doo". The result is true if the pattern -matches and a replacement occurs, false otherwise. -.P -\fBGlobalReplace\fP is like \fBReplace\fP except that it replaces all -occurrences of the pattern in the string with the rewrite. Replacements are -not subject to re-matching. For example: -.sp - string s = "yabba dabba doo"; - pcrecpp::RE("b+").GlobalReplace("d", &s); -.sp -will leave "s" containing "yada dada doo". It returns the number of -replacements made. -.P -\fBExtract\fP is like \fBReplace\fP, except that if the pattern matches, -"rewrite" is copied into "out" (an additional argument) with substitutions. -The non-matching portions of "text" are ignored. Returns true iff a match -occurred and the extraction happened successfully; if no match occurs, the -string is left unaffected. -. -. -.SH AUTHOR -.rs -.sp -.nf -The C++ wrapper was contributed by Google Inc. -Copyright (c) 2007 Google Inc. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 08 January 2012 -.fi diff --git a/gtk+-mingw/share/man/man3/pcrejit.3 b/gtk+-mingw/share/man/man3/pcrejit.3 deleted file mode 100644 index de935a4..0000000 --- a/gtk+-mingw/share/man/man3/pcrejit.3 +++ /dev/null @@ -1,403 +0,0 @@ -.TH PCREJIT 3 "04 May 2012" "PCRE 8.31" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PCRE JUST-IN-TIME COMPILER SUPPORT" -.rs -.sp -Just-in-time compiling is a heavyweight optimization that can greatly speed up -pattern matching. However, it comes at the cost of extra processing before the -match is performed. Therefore, it is of most benefit when the same pattern is -going to be matched many times. This does not necessarily mean many calls of a -matching function; if the pattern is not anchored, matching attempts may take -place many times at various positions in the subject, even for a single call. -Therefore, if the subject string is very long, it may still pay to use JIT for -one-off matches. -.P -JIT support applies only to the traditional Perl-compatible matching function. -It does not apply when the DFA matching function is being used. The code for -this support was written by Zoltan Herczeg. -. -. -.SH "8-BIT and 16-BIT SUPPORT" -.rs -.sp -JIT support is available for both the 8-bit and 16-bit PCRE libraries. To keep -this documentation simple, only the 8-bit interface is described in what -follows. If you are using the 16-bit library, substitute the 16-bit functions -and 16-bit structures (for example, \fIpcre16_jit_stack\fP instead of -\fIpcre_jit_stack\fP). -. -. -.SH "AVAILABILITY OF JIT SUPPORT" -.rs -.sp -JIT support is an optional feature of PCRE. The "configure" option --enable-jit -(or equivalent CMake option) must be set when PCRE is built if you want to use -JIT. The support is limited to the following hardware platforms: -.sp - ARM v5, v7, and Thumb2 - Intel x86 32-bit and 64-bit - MIPS 32-bit - Power PC 32-bit and 64-bit -.sp -If --enable-jit is set on an unsupported platform, compilation fails. -.P -A program that is linked with PCRE 8.20 or later can tell if JIT support is -available by calling \fBpcre_config()\fP with the PCRE_CONFIG_JIT option. The -result is 1 when JIT is available, and 0 otherwise. However, a simple program -does not need to check this in order to use JIT. The API is implemented in a -way that falls back to the interpretive code if JIT is not available. -.P -If your program may sometimes be linked with versions of PCRE that are older -than 8.20, but you want to use JIT when it is available, you can test -the values of PCRE_MAJOR and PCRE_MINOR, or the existence of a JIT macro such -as PCRE_CONFIG_JIT, for compile-time control of your code. -. -. -.SH "SIMPLE USE OF JIT" -.rs -.sp -You have to do two things to make use of the JIT support in the simplest way: -.sp - (1) Call \fBpcre_study()\fP with the PCRE_STUDY_JIT_COMPILE option for - each compiled pattern, and pass the resulting \fBpcre_extra\fP block to - \fBpcre_exec()\fP. -.sp - (2) Use \fBpcre_free_study()\fP to free the \fBpcre_extra\fP block when it is - no longer needed, instead of just freeing it yourself. This - ensures that any JIT data is also freed. -.sp -For a program that may be linked with pre-8.20 versions of PCRE, you can insert -.sp - #ifndef PCRE_STUDY_JIT_COMPILE - #define PCRE_STUDY_JIT_COMPILE 0 - #endif -.sp -so that no option is passed to \fBpcre_study()\fP, and then use something like -this to free the study data: -.sp - #ifdef PCRE_CONFIG_JIT - pcre_free_study(study_ptr); - #else - pcre_free(study_ptr); - #endif -.sp -PCRE_STUDY_JIT_COMPILE requests the JIT compiler to generate code for complete -matches. If you want to run partial matches using the PCRE_PARTIAL_HARD or -PCRE_PARTIAL_SOFT options of \fBpcre_exec()\fP, you should set one or both of -the following options in addition to, or instead of, PCRE_STUDY_JIT_COMPILE -when you call \fBpcre_study()\fP: -.sp - PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE - PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE -.sp -The JIT compiler generates different optimized code for each of the three -modes (normal, soft partial, hard partial). When \fBpcre_exec()\fP is called, -the appropriate code is run if it is available. Otherwise, the pattern is -matched using interpretive code. -.P -In some circumstances you may need to call additional functions. These are -described in the section entitled -.\" HTML <a href="#stackcontrol"> -.\" </a> -"Controlling the JIT stack" -.\" -below. -.P -If JIT support is not available, PCRE_STUDY_JIT_COMPILE etc. are ignored, and -no JIT data is created. Otherwise, the compiled pattern is passed to the JIT -compiler, which turns it into machine code that executes much faster than the -normal interpretive code. When \fBpcre_exec()\fP is passed a \fBpcre_extra\fP -block containing a pointer to JIT code of the appropriate mode (normal or -hard/soft partial), it obeys that code instead of running the interpreter. The -result is identical, but the compiled JIT code runs much faster. -.P -There are some \fBpcre_exec()\fP options that are not supported for JIT -execution. There are also some pattern items that JIT cannot handle. Details -are given below. In both cases, execution automatically falls back to the -interpretive code. If you want to know whether JIT was actually used for a -particular match, you should arrange for a JIT callback function to be set up -as described in the section entitled -.\" HTML <a href="#stackcontrol"> -.\" </a> -"Controlling the JIT stack" -.\" -below, even if you do not need to supply a non-default JIT stack. Such a -callback function is called whenever JIT code is about to be obeyed. If the -execution options are not right for JIT execution, the callback function is not -obeyed. -.P -If the JIT compiler finds an unsupported item, no JIT data is generated. You -can find out if JIT execution is available after studying a pattern by calling -\fBpcre_fullinfo()\fP with the PCRE_INFO_JIT option. A result of 1 means that -JIT compilation was successful. A result of 0 means that JIT support is not -available, or the pattern was not studied with PCRE_STUDY_JIT_COMPILE etc., or -the JIT compiler was not able to handle the pattern. -.P -Once a pattern has been studied, with or without JIT, it can be used as many -times as you like for matching different subject strings. -. -. -.SH "UNSUPPORTED OPTIONS AND PATTERN ITEMS" -.rs -.sp -The only \fBpcre_exec()\fP options that are supported for JIT execution are -PCRE_NO_UTF8_CHECK, PCRE_NO_UTF16_CHECK, PCRE_NOTBOL, PCRE_NOTEOL, -PCRE_NOTEMPTY, PCRE_NOTEMPTY_ATSTART, PCRE_PARTIAL_HARD, and PCRE_PARTIAL_SOFT. -.P -The unsupported pattern items are: -.sp - \eC match a single byte; not supported in UTF-8 mode - (?Cn) callouts - (*PRUNE) ) - (*SKIP) ) backtracking control verbs - (*THEN) ) -.sp -Support for some of these may be added in future. -. -. -.SH "RETURN VALUES FROM JIT EXECUTION" -.rs -.sp -When a pattern is matched using JIT execution, the return values are the same -as those given by the interpretive \fBpcre_exec()\fP code, with the addition of -one new error code: PCRE_ERROR_JIT_STACKLIMIT. This means that the memory used -for the JIT stack was insufficient. See -.\" HTML <a href="#stackcontrol"> -.\" </a> -"Controlling the JIT stack" -.\" -below for a discussion of JIT stack usage. For compatibility with the -interpretive \fBpcre_exec()\fP code, no more than two-thirds of the -\fIovector\fP argument is used for passing back captured substrings. -.P -The error code PCRE_ERROR_MATCHLIMIT is returned by the JIT code if searching a -very large pattern tree goes on for too long, as it is in the same circumstance -when JIT is not used, but the details of exactly what is counted are not the -same. The PCRE_ERROR_RECURSIONLIMIT error code is never returned by JIT -execution. -. -. -.SH "SAVING AND RESTORING COMPILED PATTERNS" -.rs -.sp -The code that is generated by the JIT compiler is architecture-specific, and is -also position dependent. For those reasons it cannot be saved (in a file or -database) and restored later like the bytecode and other data of a compiled -pattern. Saving and restoring compiled patterns is not something many people -do. More detail about this facility is given in the -.\" HREF -\fBpcreprecompile\fP -.\" -documentation. It should be possible to run \fBpcre_study()\fP on a saved and -restored pattern, and thereby recreate the JIT data, but because JIT -compilation uses significant resources, it is probably not worth doing this; -you might as well recompile the original pattern. -. -. -.\" HTML <a name="stackcontrol"></a> -.SH "CONTROLLING THE JIT STACK" -.rs -.sp -When the compiled JIT code runs, it needs a block of memory to use as a stack. -By default, it uses 32K on the machine stack. However, some large or -complicated patterns need more than this. The error PCRE_ERROR_JIT_STACKLIMIT -is given when there is not enough stack. Three functions are provided for -managing blocks of memory for use as JIT stacks. There is further discussion -about the use of JIT stacks in the section entitled -.\" HTML <a href="#stackcontrol"> -.\" </a> -"JIT stack FAQ" -.\" -below. -.P -The \fBpcre_jit_stack_alloc()\fP function creates a JIT stack. Its arguments -are a starting size and a maximum size, and it returns a pointer to an opaque -structure of type \fBpcre_jit_stack\fP, or NULL if there is an error. The -\fBpcre_jit_stack_free()\fP function can be used to free a stack that is no -longer needed. (For the technically minded: the address space is allocated by -mmap or VirtualAlloc.) -.P -JIT uses far less memory for recursion than the interpretive code, -and a maximum stack size of 512K to 1M should be more than enough for any -pattern. -.P -The \fBpcre_assign_jit_stack()\fP function specifies which stack JIT code -should use. Its arguments are as follows: -.sp - pcre_extra *extra - pcre_jit_callback callback - void *data -.sp -The \fIextra\fP argument must be the result of studying a pattern with -PCRE_STUDY_JIT_COMPILE etc. There are three cases for the values of the other -two options: -.sp - (1) If \fIcallback\fP is NULL and \fIdata\fP is NULL, an internal 32K block - on the machine stack is used. -.sp - (2) If \fIcallback\fP is NULL and \fIdata\fP is not NULL, \fIdata\fP must be - a valid JIT stack, the result of calling \fBpcre_jit_stack_alloc()\fP. -.sp - (3) If \fIcallback\fP is not NULL, it must point to a function that is - called with \fIdata\fP as an argument at the start of matching, in - order to set up a JIT stack. If the return from the callback - function is NULL, the internal 32K stack is used; otherwise the - return value must be a valid JIT stack, the result of calling - \fBpcre_jit_stack_alloc()\fP. -.sp -A callback function is obeyed whenever JIT code is about to be run; it is not -obeyed when \fBpcre_exec()\fP is called with options that are incompatible for -JIT execution. A callback function can therefore be used to determine whether a -match operation was executed by JIT or by the interpreter. -.P -You may safely use the same JIT stack for more than one pattern (either by -assigning directly or by callback), as long as the patterns are all matched -sequentially in the same thread. In a multithread application, if you do not -specify a JIT stack, or if you assign or pass back NULL from a callback, that -is thread-safe, because each thread has its own machine stack. However, if you -assign or pass back a non-NULL JIT stack, this must be a different stack for -each thread so that the application is thread-safe. -.P -Strictly speaking, even more is allowed. You can assign the same non-NULL stack -to any number of patterns as long as they are not used for matching by multiple -threads at the same time. For example, you can assign the same stack to all -compiled patterns, and use a global mutex in the callback to wait until the -stack is available for use. However, this is an inefficient solution, and not -recommended. -.P -This is a suggestion for how a multithreaded program that needs to set up -non-default JIT stacks might operate: -.sp - During thread initalization - thread_local_var = pcre_jit_stack_alloc(...) -.sp - During thread exit - pcre_jit_stack_free(thread_local_var) -.sp - Use a one-line callback function - return thread_local_var -.sp -All the functions described in this section do nothing if JIT is not available, -and \fBpcre_assign_jit_stack()\fP does nothing unless the \fBextra\fP argument -is non-NULL and points to a \fBpcre_extra\fP block that is the result of a -successful study with PCRE_STUDY_JIT_COMPILE etc. -. -. -.\" HTML <a name="stackfaq"></a> -.SH "JIT STACK FAQ" -.rs -.sp -(1) Why do we need JIT stacks? -.sp -PCRE (and JIT) is a recursive, depth-first engine, so it needs a stack where -the local data of the current node is pushed before checking its child nodes. -Allocating real machine stack on some platforms is difficult. For example, the -stack chain needs to be updated every time if we extend the stack on PowerPC. -Although it is possible, its updating time overhead decreases performance. So -we do the recursion in memory. -.P -(2) Why don't we simply allocate blocks of memory with \fBmalloc()\fP? -.sp -Modern operating systems have a nice feature: they can reserve an address space -instead of allocating memory. We can safely allocate memory pages inside this -address space, so the stack could grow without moving memory data (this is -important because of pointers). Thus we can allocate 1M address space, and use -only a single memory page (usually 4K) if that is enough. However, we can still -grow up to 1M anytime if needed. -.P -(3) Who "owns" a JIT stack? -.sp -The owner of the stack is the user program, not the JIT studied pattern or -anything else. The user program must ensure that if a stack is used by -\fBpcre_exec()\fP, (that is, it is assigned to the pattern currently running), -that stack must not be used by any other threads (to avoid overwriting the same -memory area). The best practice for multithreaded programs is to allocate a -stack for each thread, and return this stack through the JIT callback function. -.P -(4) When should a JIT stack be freed? -.sp -You can free a JIT stack at any time, as long as it will not be used by -\fBpcre_exec()\fP again. When you assign the stack to a pattern, only a pointer -is set. There is no reference counting or any other magic. You can free the -patterns and stacks in any order, anytime. Just \fIdo not\fP call -\fBpcre_exec()\fP with a pattern pointing to an already freed stack, as that -will cause SEGFAULT. (Also, do not free a stack currently used by -\fBpcre_exec()\fP in another thread). You can also replace the stack for a -pattern at any time. You can even free the previous stack before assigning a -replacement. -.P -(5) Should I allocate/free a stack every time before/after calling -\fBpcre_exec()\fP? -.sp -No, because this is too costly in terms of resources. However, you could -implement some clever idea which release the stack if it is not used in let's -say two minutes. The JIT callback can help to achive this without keeping a -list of the currently JIT studied patterns. -.P -(6) OK, the stack is for long term memory allocation. But what happens if a -pattern causes stack overflow with a stack of 1M? Is that 1M kept until the -stack is freed? -.sp -Especially on embedded sytems, it might be a good idea to release memory -sometimes without freeing the stack. There is no API for this at the moment. -Probably a function call which returns with the currently allocated memory for -any stack and another which allows releasing memory (shrinking the stack) would -be a good idea if someone needs this. -.P -(7) This is too much of a headache. Isn't there any better solution for JIT -stack handling? -.sp -No, thanks to Windows. If POSIX threads were used everywhere, we could throw -out this complicated API. -. -. -.SH "EXAMPLE CODE" -.rs -.sp -This is a single-threaded example that specifies a JIT stack without using a -callback. -.sp - int rc; - int ovector[30]; - pcre *re; - pcre_extra *extra; - pcre_jit_stack *jit_stack; -.sp - re = pcre_compile(pattern, 0, &error, &erroffset, NULL); - /* Check for errors */ - extra = pcre_study(re, PCRE_STUDY_JIT_COMPILE, &error); - jit_stack = pcre_jit_stack_alloc(32*1024, 512*1024); - /* Check for error (NULL) */ - pcre_assign_jit_stack(extra, NULL, jit_stack); - rc = pcre_exec(re, extra, subject, length, 0, 0, ovector, 30); - /* Check results */ - pcre_free(re); - pcre_free_study(extra); - pcre_jit_stack_free(jit_stack); -.sp -. -. -.SH "SEE ALSO" -.rs -.sp -\fBpcreapi\fP(3) -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel (FAQ by Zoltan Herczeg) -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 04 May 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcrelimits.3 b/gtk+-mingw/share/man/man3/pcrelimits.3 deleted file mode 100644 index 0e25f82..0000000 --- a/gtk+-mingw/share/man/man3/pcrelimits.3 +++ /dev/null @@ -1,66 +0,0 @@ -.TH PCRELIMITS 3 "04 May 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "SIZE AND OTHER LIMITATIONS" -.rs -.sp -There are some size limitations in PCRE but it is hoped that they will never in -practice be relevant. -.P -The maximum length of a compiled pattern is approximately 64K data units (bytes -for the 8-bit library, 16-bit units for the 16-bit library) if PCRE is compiled -with the default internal linkage size of 2 bytes. If you want to process -regular expressions that are truly enormous, you can compile PCRE with an -internal linkage size of 3 or 4 (when building the 16-bit library, 3 is rounded -up to 4). See the \fBREADME\fP file in the source distribution and the -.\" HREF -\fBpcrebuild\fP -.\" -documentation for details. In these cases the limit is substantially larger. -However, the speed of execution is slower. -.P -All values in repeating quantifiers must be less than 65536. -.P -There is no limit to the number of parenthesized subpatterns, but there can be -no more than 65535 capturing subpatterns. -.P -There is a limit to the number of forward references to subsequent subpatterns -of around 200,000. Repeated forward references with fixed upper limits, for -example, (?2){0,100} when subpattern number 2 is to the right, are included in -the count. There is no limit to the number of backward references. -.P -The maximum length of name for a named subpattern is 32 characters, and the -maximum number of named subpatterns is 10000. -.P -The maximum length of a name in a (*MARK), (*PRUNE), (*SKIP), or (*THEN) verb -is 255 for the 8-bit library and 65535 for the 16-bit library. -.P -The maximum length of a subject string is the largest positive number that an -integer variable can hold. However, when using the traditional matching -function, PCRE uses recursion to handle subpatterns and indefinite repetition. -This means that the available stack space may limit the size of a subject -string that can be processed by certain patterns. For a discussion of stack -issues, see the -.\" HREF -\fBpcrestack\fP -.\" -documentation. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 04 May 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcrematching.3 b/gtk+-mingw/share/man/man3/pcrematching.3 deleted file mode 100644 index 1a510e0..0000000 --- a/gtk+-mingw/share/man/man3/pcrematching.3 +++ /dev/null @@ -1,205 +0,0 @@ -.TH PCREMATCHING 3 "08 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PCRE MATCHING ALGORITHMS" -.rs -.sp -This document describes the two different algorithms that are available in PCRE -for matching a compiled regular expression against a given subject string. The -"standard" algorithm is the one provided by the \fBpcre_exec()\fP and -\fBpcre16_exec()\fP functions. These work in the same was as Perl's matching -function, and provide a Perl-compatible matching operation. The just-in-time -(JIT) optimization that is described in the -.\" HREF -\fBpcrejit\fP -.\" -documentation is compatible with these functions. -.P -An alternative algorithm is provided by the \fBpcre_dfa_exec()\fP and -\fBpcre16_dfa_exec()\fP functions; they operate in a different way, and are not -Perl-compatible. This alternative has advantages and disadvantages compared -with the standard algorithm, and these are described below. -.P -When there is only one possible way in which a given subject string can match a -pattern, the two algorithms give the same answer. A difference arises, however, -when there are multiple possibilities. For example, if the pattern -.sp - ^<.*> -.sp -is matched against the string -.sp - <something> <something else> <something further> -.sp -there are three possible answers. The standard algorithm finds only one of -them, whereas the alternative algorithm finds all three. -. -. -.SH "REGULAR EXPRESSIONS AS TREES" -.rs -.sp -The set of strings that are matched by a regular expression can be represented -as a tree structure. An unlimited repetition in the pattern makes the tree of -infinite size, but it is still a tree. Matching the pattern to a given subject -string (from a given starting point) can be thought of as a search of the tree. -There are two ways to search a tree: depth-first and breadth-first, and these -correspond to the two matching algorithms provided by PCRE. -. -. -.SH "THE STANDARD MATCHING ALGORITHM" -.rs -.sp -In the terminology of Jeffrey Friedl's book "Mastering Regular -Expressions", the standard algorithm is an "NFA algorithm". It conducts a -depth-first search of the pattern tree. That is, it proceeds along a single -path through the tree, checking that the subject matches what is required. When -there is a mismatch, the algorithm tries any alternatives at the current point, -and if they all fail, it backs up to the previous branch point in the tree, and -tries the next alternative branch at that level. This often involves backing up -(moving to the left) in the subject string as well. The order in which -repetition branches are tried is controlled by the greedy or ungreedy nature of -the quantifier. -.P -If a leaf node is reached, a matching string has been found, and at that point -the algorithm stops. Thus, if there is more than one possible match, this -algorithm returns the first one that it finds. Whether this is the shortest, -the longest, or some intermediate length depends on the way the greedy and -ungreedy repetition quantifiers are specified in the pattern. -.P -Because it ends up with a single path through the tree, it is relatively -straightforward for this algorithm to keep track of the substrings that are -matched by portions of the pattern in parentheses. This provides support for -capturing parentheses and back references. -. -. -.SH "THE ALTERNATIVE MATCHING ALGORITHM" -.rs -.sp -This algorithm conducts a breadth-first search of the tree. Starting from the -first matching point in the subject, it scans the subject string from left to -right, once, character by character, and as it does this, it remembers all the -paths through the tree that represent valid matches. In Friedl's terminology, -this is a kind of "DFA algorithm", though it is not implemented as a -traditional finite state machine (it keeps multiple states active -simultaneously). -.P -Although the general principle of this matching algorithm is that it scans the -subject string only once, without backtracking, there is one exception: when a -lookaround assertion is encountered, the characters following or preceding the -current point have to be independently inspected. -.P -The scan continues until either the end of the subject is reached, or there are -no more unterminated paths. At this point, terminated paths represent the -different matching possibilities (if there are none, the match has failed). -Thus, if there is more than one possible match, this algorithm finds all of -them, and in particular, it finds the longest. The matches are returned in -decreasing order of length. There is an option to stop the algorithm after the -first match (which is necessarily the shortest) is found. -.P -Note that all the matches that are found start at the same point in the -subject. If the pattern -.sp - cat(er(pillar)?)? -.sp -is matched against the string "the caterpillar catchment", the result will be -the three strings "caterpillar", "cater", and "cat" that start at the fifth -character of the subject. The algorithm does not automatically move on to find -matches that start at later positions. -.P -There are a number of features of PCRE regular expressions that are not -supported by the alternative matching algorithm. They are as follows: -.P -1. Because the algorithm finds all possible matches, the greedy or ungreedy -nature of repetition quantifiers is not relevant. Greedy and ungreedy -quantifiers are treated in exactly the same way. However, possessive -quantifiers can make a difference when what follows could also match what is -quantified, for example in a pattern like this: -.sp - ^a++\ew! -.sp -This pattern matches "aaab!" but not "aaa!", which would be matched by a -non-possessive quantifier. Similarly, if an atomic group is present, it is -matched as if it were a standalone pattern at the current point, and the -longest match is then "locked in" for the rest of the overall pattern. -.P -2. When dealing with multiple paths through the tree simultaneously, it is not -straightforward to keep track of captured substrings for the different matching -possibilities, and PCRE's implementation of this algorithm does not attempt to -do this. This means that no captured substrings are available. -.P -3. Because no substrings are captured, back references within the pattern are -not supported, and cause errors if encountered. -.P -4. For the same reason, conditional expressions that use a backreference as the -condition or test for a specific group recursion are not supported. -.P -5. Because many paths through the tree may be active, the \eK escape sequence, -which resets the start of the match when encountered (but may be on some paths -and not on others), is not supported. It causes an error if encountered. -.P -6. Callouts are supported, but the value of the \fIcapture_top\fP field is -always 1, and the value of the \fIcapture_last\fP field is always -1. -.P -7. The \eC escape sequence, which (in the standard algorithm) always matches a -single data unit, even in UTF-8 or UTF-16 modes, is not supported in these -modes, because the alternative algorithm moves through the subject string one -character (not data unit) at a time, for all active paths through the tree. -.P -8. Except for (*FAIL), the backtracking control verbs such as (*PRUNE) are not -supported. (*FAIL) is supported, and behaves like a failing negative assertion. -. -. -.SH "ADVANTAGES OF THE ALTERNATIVE ALGORITHM" -.rs -.sp -Using the alternative matching algorithm provides the following advantages: -.P -1. All possible matches (at a single point in the subject) are automatically -found, and in particular, the longest match is found. To find more than one -match using the standard algorithm, you have to do kludgy things with -callouts. -.P -2. Because the alternative algorithm scans the subject string just once, and -never needs to backtrack (except for lookbehinds), it is possible to pass very -long subject strings to the matching function in several pieces, checking for -partial matching each time. Although it is possible to do multi-segment -matching using the standard algorithm by retaining partially matched -substrings, it is more complicated. The -.\" HREF -\fBpcrepartial\fP -.\" -documentation gives details of partial matching and discusses multi-segment -matching. -. -. -.SH "DISADVANTAGES OF THE ALTERNATIVE ALGORITHM" -.rs -.sp -The alternative algorithm suffers from a number of disadvantages: -.P -1. It is substantially slower than the standard algorithm. This is partly -because it has to search for all possible matches, but is also because it is -less susceptible to optimization. -.P -2. Capturing parentheses and back references are not supported. -.P -3. Although atomic groups are supported, their use does not provide the -performance advantage that it does for the standard algorithm. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 08 January 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcrepartial.3 b/gtk+-mingw/share/man/man3/pcrepartial.3 deleted file mode 100644 index c93e3d1..0000000 --- a/gtk+-mingw/share/man/man3/pcrepartial.3 +++ /dev/null @@ -1,445 +0,0 @@ -.TH PCREPARTIAL 3 "24 February 2012" "PCRE 8.31" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PARTIAL MATCHING IN PCRE" -.rs -.sp -In normal use of PCRE, if the subject string that is passed to a matching -function matches as far as it goes, but is too short to match the entire -pattern, PCRE_ERROR_NOMATCH is returned. There are circumstances where it might -be helpful to distinguish this case from other cases in which there is no -match. -.P -Consider, for example, an application where a human is required to type in data -for a field with specific formatting requirements. An example might be a date -in the form \fIddmmmyy\fP, defined by this pattern: -.sp - ^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$ -.sp -If the application sees the user's keystrokes one by one, and can check that -what has been typed so far is potentially valid, it is able to raise an error -as soon as a mistake is made, by beeping and not reflecting the character that -has been typed, for example. This immediate feedback is likely to be a better -user interface than a check that is delayed until the entire string has been -entered. Partial matching can also be useful when the subject string is very -long and is not all available at once. -.P -PCRE supports partial matching by means of the PCRE_PARTIAL_SOFT and -PCRE_PARTIAL_HARD options, which can be set when calling any of the matching -functions. For backwards compatibility, PCRE_PARTIAL is a synonym for -PCRE_PARTIAL_SOFT. The essential difference between the two options is whether -or not a partial match is preferred to an alternative complete match, though -the details differ between the two types of matching function. If both options -are set, PCRE_PARTIAL_HARD takes precedence. -.P -If you want to use partial matching with just-in-time optimized code, you must -call \fBpcre_study()\fP or \fBpcre16_study()\fP with one or both of these -options: -.sp - PCRE_STUDY_JIT_PARTIAL_SOFT_COMPILE - PCRE_STUDY_JIT_PARTIAL_HARD_COMPILE -.sp -PCRE_STUDY_JIT_COMPILE should also be set if you are going to run non-partial -matches on the same pattern. If the appropriate JIT study mode has not been set -for a match, the interpretive matching code is used. -.P -Setting a partial matching option disables two of PCRE's standard -optimizations. PCRE remembers the last literal data unit in a pattern, and -abandons matching immediately if it is not present in the subject string. This -optimization cannot be used for a subject string that might match only -partially. If the pattern was studied, PCRE knows the minimum length of a -matching string, and does not bother to run the matching function on shorter -strings. This optimization is also disabled for partial matching. -. -. -.SH "PARTIAL MATCHING USING pcre_exec() OR pcre16_exec()" -.rs -.sp -A partial match occurs during a call to \fBpcre_exec()\fP or -\fBpcre16_exec()\fP when the end of the subject string is reached successfully, -but matching cannot continue because more characters are needed. However, at -least one character in the subject must have been inspected. This character -need not form part of the final matched string; lookbehind assertions and the -\eK escape sequence provide ways of inspecting characters before the start of a -matched substring. The requirement for inspecting at least one character exists -because an empty string can always be matched; without such a restriction there -would always be a partial match of an empty string at the end of the subject. -.P -If there are at least two slots in the offsets vector when a partial match is -returned, the first slot is set to the offset of the earliest character that -was inspected. For convenience, the second offset points to the end of the -subject so that a substring can easily be identified. -.P -For the majority of patterns, the first offset identifies the start of the -partially matched string. However, for patterns that contain lookbehind -assertions, or \eK, or begin with \eb or \eB, earlier characters have been -inspected while carrying out the match. For example: -.sp - /(?<=abc)123/ -.sp -This pattern matches "123", but only if it is preceded by "abc". If the subject -string is "xyzabc12", the offsets after a partial match are for the substring -"abc12", because all these characters are needed if another match is tried -with extra characters added to the subject. -.P -What happens when a partial match is identified depends on which of the two -partial matching options are set. -. -. -.SS "PCRE_PARTIAL_SOFT WITH pcre_exec() OR pcre16_exec()" -.rs -.sp -If PCRE_PARTIAL_SOFT is set when \fBpcre_exec()\fP or \fBpcre16_exec()\fP -identifies a partial match, the partial match is remembered, but matching -continues as normal, and other alternatives in the pattern are tried. If no -complete match can be found, PCRE_ERROR_PARTIAL is returned instead of -PCRE_ERROR_NOMATCH. -.P -This option is "soft" because it prefers a complete match over a partial match. -All the various matching items in a pattern behave as if the subject string is -potentially complete. For example, \ez, \eZ, and $ match at the end of the -subject, as normal, and for \eb and \eB the end of the subject is treated as a -non-alphanumeric. -.P -If there is more than one partial match, the first one that was found provides -the data that is returned. Consider this pattern: -.sp - /123\ew+X|dogY/ -.sp -If this is matched against the subject string "abc123dog", both -alternatives fail to match, but the end of the subject is reached during -matching, so PCRE_ERROR_PARTIAL is returned. The offsets are set to 3 and 9, -identifying "123dog" as the first partial match that was found. (In this -example, there are two partial matches, because "dog" on its own partially -matches the second alternative.) -. -. -.SS "PCRE_PARTIAL_HARD WITH pcre_exec() OR pcre16_exec()" -.rs -.sp -If PCRE_PARTIAL_HARD is set for \fBpcre_exec()\fP or \fBpcre16_exec()\fP, -PCRE_ERROR_PARTIAL is returned as soon as a partial match is found, without -continuing to search for possible complete matches. This option is "hard" -because it prefers an earlier partial match over a later complete match. For -this reason, the assumption is made that the end of the supplied subject string -may not be the true end of the available data, and so, if \ez, \eZ, \eb, \eB, -or $ are encountered at the end of the subject, the result is -PCRE_ERROR_PARTIAL, provided that at least one character in the subject has -been inspected. -.P -Setting PCRE_PARTIAL_HARD also affects the way UTF-8 and UTF-16 -subject strings are checked for validity. Normally, an invalid sequence -causes the error PCRE_ERROR_BADUTF8 or PCRE_ERROR_BADUTF16. However, in the -special case of a truncated character at the end of the subject, -PCRE_ERROR_SHORTUTF8 or PCRE_ERROR_SHORTUTF16 is returned when -PCRE_PARTIAL_HARD is set. -. -. -.SS "Comparing hard and soft partial matching" -.rs -.sp -The difference between the two partial matching options can be illustrated by a -pattern such as: -.sp - /dog(sbody)?/ -.sp -This matches either "dog" or "dogsbody", greedily (that is, it prefers the -longer string if possible). If it is matched against the string "dog" with -PCRE_PARTIAL_SOFT, it yields a complete match for "dog". However, if -PCRE_PARTIAL_HARD is set, the result is PCRE_ERROR_PARTIAL. On the other hand, -if the pattern is made ungreedy the result is different: -.sp - /dog(sbody)??/ -.sp -In this case the result is always a complete match because that is found first, -and matching never continues after finding a complete match. It might be easier -to follow this explanation by thinking of the two patterns like this: -.sp - /dog(sbody)?/ is the same as /dogsbody|dog/ - /dog(sbody)??/ is the same as /dog|dogsbody/ -.sp -The second pattern will never match "dogsbody", because it will always find the -shorter match first. -. -. -.SH "PARTIAL MATCHING USING pcre_dfa_exec() OR pcre16_dfa_exec()" -.rs -.sp -The DFA functions move along the subject string character by character, without -backtracking, searching for all possible matches simultaneously. If the end of -the subject is reached before the end of the pattern, there is the possibility -of a partial match, again provided that at least one character has been -inspected. -.P -When PCRE_PARTIAL_SOFT is set, PCRE_ERROR_PARTIAL is returned only if there -have been no complete matches. Otherwise, the complete matches are returned. -However, if PCRE_PARTIAL_HARD is set, a partial match takes precedence over any -complete matches. The portion of the string that was inspected when the longest -partial match was found is set as the first matching string, provided there are -at least two slots in the offsets vector. -.P -Because the DFA functions always search for all possible matches, and there is -no difference between greedy and ungreedy repetition, their behaviour is -different from the standard functions when PCRE_PARTIAL_HARD is set. Consider -the string "dog" matched against the ungreedy pattern shown above: -.sp - /dog(sbody)??/ -.sp -Whereas the standard functions stop as soon as they find the complete match for -"dog", the DFA functions also find the partial match for "dogsbody", and so -return that when PCRE_PARTIAL_HARD is set. -. -. -.SH "PARTIAL MATCHING AND WORD BOUNDARIES" -.rs -.sp -If a pattern ends with one of sequences \eb or \eB, which test for word -boundaries, partial matching with PCRE_PARTIAL_SOFT can give counter-intuitive -results. Consider this pattern: -.sp - /\ebcat\eb/ -.sp -This matches "cat", provided there is a word boundary at either end. If the -subject string is "the cat", the comparison of the final "t" with a following -character cannot take place, so a partial match is found. However, normal -matching carries on, and \eb matches at the end of the subject when the last -character is a letter, so a complete match is found. The result, therefore, is -\fInot\fP PCRE_ERROR_PARTIAL. Using PCRE_PARTIAL_HARD in this case does yield -PCRE_ERROR_PARTIAL, because then the partial match takes precedence. -. -. -.SH "FORMERLY RESTRICTED PATTERNS" -.rs -.sp -For releases of PCRE prior to 8.00, because of the way certain internal -optimizations were implemented in the \fBpcre_exec()\fP function, the -PCRE_PARTIAL option (predecessor of PCRE_PARTIAL_SOFT) could not be used with -all patterns. From release 8.00 onwards, the restrictions no longer apply, and -partial matching with can be requested for any pattern. -.P -Items that were formerly restricted were repeated single characters and -repeated metasequences. If PCRE_PARTIAL was set for a pattern that did not -conform to the restrictions, \fBpcre_exec()\fP returned the error code -PCRE_ERROR_BADPARTIAL (-13). This error code is no longer in use. The -PCRE_INFO_OKPARTIAL call to \fBpcre_fullinfo()\fP to find out if a compiled -pattern can be used for partial matching now always returns 1. -. -. -.SH "EXAMPLE OF PARTIAL MATCHING USING PCRETEST" -.rs -.sp -If the escape sequence \eP is present in a \fBpcretest\fP data line, the -PCRE_PARTIAL_SOFT option is used for the match. Here is a run of \fBpcretest\fP -that uses the date example quoted above: -.sp - re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/ - data> 25jun04\eP - 0: 25jun04 - 1: jun - data> 25dec3\eP - Partial match: 23dec3 - data> 3ju\eP - Partial match: 3ju - data> 3juj\eP - No match - data> j\eP - No match -.sp -The first data string is matched completely, so \fBpcretest\fP shows the -matched substrings. The remaining four strings do not match the complete -pattern, but the first two are partial matches. Similar output is obtained -if DFA matching is used. -.P -If the escape sequence \eP is present more than once in a \fBpcretest\fP data -line, the PCRE_PARTIAL_HARD option is set for the match. -. -. -.SH "MULTI-SEGMENT MATCHING WITH pcre_dfa_exec() OR pcre16_dfa_exec()" -.rs -.sp -When a partial match has been found using a DFA matching function, it is -possible to continue the match by providing additional subject data and calling -the function again with the same compiled regular expression, this time setting -the PCRE_DFA_RESTART option. You must pass the same working space as before, -because this is where details of the previous partial match are stored. Here is -an example using \fBpcretest\fP, using the \eR escape sequence to set the -PCRE_DFA_RESTART option (\eD specifies the use of the DFA matching function): -.sp - re> /^\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed$/ - data> 23ja\eP\eD - Partial match: 23ja - data> n05\eR\eD - 0: n05 -.sp -The first call has "23ja" as the subject, and requests partial matching; the -second call has "n05" as the subject for the continued (restarted) match. -Notice that when the match is complete, only the last part is shown; PCRE does -not retain the previously partially-matched string. It is up to the calling -program to do that if it needs to. -.P -You can set the PCRE_PARTIAL_SOFT or PCRE_PARTIAL_HARD options with -PCRE_DFA_RESTART to continue partial matching over multiple segments. This -facility can be used to pass very long subject strings to the DFA matching -functions. -. -. -.SH "MULTI-SEGMENT MATCHING WITH pcre_exec() OR pcre16_exec()" -.rs -.sp -From release 8.00, the standard matching functions can also be used to do -multi-segment matching. Unlike the DFA functions, it is not possible to -restart the previous match with a new segment of data. Instead, new data must -be added to the previous subject string, and the entire match re-run, starting -from the point where the partial match occurred. Earlier data can be discarded. -.P -It is best to use PCRE_PARTIAL_HARD in this situation, because it does not -treat the end of a segment as the end of the subject when matching \ez, \eZ, -\eb, \eB, and $. Consider an unanchored pattern that matches dates: -.sp - re> /\ed?\ed(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\ed\ed/ - data> The date is 23ja\eP\eP - Partial match: 23ja -.sp -At this stage, an application could discard the text preceding "23ja", add on -text from the next segment, and call the matching function again. Unlike the -DFA matching functions, the entire matching string must always be available, -and the complete matching process occurs for each call, so more memory and more -processing time is needed. -.P -\fBNote:\fP If the pattern contains lookbehind assertions, or \eK, or starts -with \eb or \eB, the string that is returned for a partial match includes -characters that precede the partially matched string itself, because these must -be retained when adding on more characters for a subsequent matching attempt. -However, in some cases you may need to retain even earlier characters, as -discussed in the next section. -. -. -.SH "ISSUES WITH MULTI-SEGMENT MATCHING" -.rs -.sp -Certain types of pattern may give problems with multi-segment matching, -whichever matching function is used. -.P -1. If the pattern contains a test for the beginning of a line, you need to pass -the PCRE_NOTBOL option when the subject string for any call does start at the -beginning of a line. There is also a PCRE_NOTEOL option, but in practice when -doing multi-segment matching you should be using PCRE_PARTIAL_HARD, which -includes the effect of PCRE_NOTEOL. -.P -2. Lookbehind assertions that have already been obeyed are catered for in the -offsets that are returned for a partial match. However a lookbehind assertion -later in the pattern could require even earlier characters to be inspected. You -can handle this case by using the PCRE_INFO_MAXLOOKBEHIND option of the -\fBpcre_fullinfo()\fP or \fBpcre16_fullinfo()\fP functions to obtain the length -of the largest lookbehind in the pattern. This length is given in characters, -not bytes. If you always retain at least that many characters before the -partially matched string, all should be well. (Of course, near the start of the -subject, fewer characters may be present; in that case all characters should be -retained.) -.P -3. Because a partial match must always contain at least one character, what -might be considered a partial match of an empty string actually gives a "no -match" result. For example: -.sp - re> /c(?<=abc)x/ - data> ab\eP - No match -.sp -If the next segment begins "cx", a match should be found, but this will only -happen if characters from the previous segment are retained. For this reason, a -"no match" result should be interpreted as "partial match of an empty string" -when the pattern contains lookbehinds. -.P -4. Matching a subject string that is split into multiple segments may not -always produce exactly the same result as matching over one single long string, -especially when PCRE_PARTIAL_SOFT is used. The section "Partial Matching and -Word Boundaries" above describes an issue that arises if the pattern ends with -\eb or \eB. Another kind of difference may occur when there are multiple -matching possibilities, because (for PCRE_PARTIAL_SOFT) a partial match result -is given only when there are no completed matches. This means that as soon as -the shortest match has been found, continuation to a new subject segment is no -longer possible. Consider again this \fBpcretest\fP example: -.sp - re> /dog(sbody)?/ - data> dogsb\eP - 0: dog - data> do\eP\eD - Partial match: do - data> gsb\eR\eP\eD - 0: g - data> dogsbody\eD - 0: dogsbody - 1: dog -.sp -The first data line passes the string "dogsb" to a standard matching function, -setting the PCRE_PARTIAL_SOFT option. Although the string is a partial match -for "dogsbody", the result is not PCRE_ERROR_PARTIAL, because the shorter -string "dog" is a complete match. Similarly, when the subject is presented to -a DFA matching function in several parts ("do" and "gsb" being the first two) -the match stops when "dog" has been found, and it is not possible to continue. -On the other hand, if "dogsbody" is presented as a single string, a DFA -matching function finds both matches. -.P -Because of these problems, it is best to use PCRE_PARTIAL_HARD when matching -multi-segment data. The example above then behaves differently: -.sp - re> /dog(sbody)?/ - data> dogsb\eP\eP - Partial match: dogsb - data> do\eP\eD - Partial match: do - data> gsb\eR\eP\eP\eD - Partial match: gsb -.sp -5. Patterns that contain alternatives at the top level which do not all start -with the same pattern item may not work as expected when PCRE_DFA_RESTART is -used. For example, consider this pattern: -.sp - 1234|3789 -.sp -If the first part of the subject is "ABC123", a partial match of the first -alternative is found at offset 3. There is no partial match for the second -alternative, because such a match does not start at the same point in the -subject string. Attempting to continue with the string "7890" does not yield a -match because only those alternatives that match at one point in the subject -are remembered. The problem arises because the start of the second alternative -matches within the first alternative. There is no problem with anchored -patterns or patterns such as: -.sp - 1234|ABCD -.sp -where no string can be a partial match for both alternatives. This is not a -problem if a standard matching function is used, because the entire match has -to be rerun each time: -.sp - re> /1234|3789/ - data> ABC123\eP\eP - Partial match: 123 - data> 1237890 - 0: 3789 -.sp -Of course, instead of using PCRE_DFA_RESTART, the same technique of re-running -the entire match can also be used with the DFA matching functions. Another -possibility is to work with two buffers. If a partial match at offset \fIn\fP -in the first buffer is followed by "no match" when PCRE_DFA_RESTART is used on -the second buffer, you can then try a new match starting at offset \fIn+1\fP in -the first buffer. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 24 February 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcrepattern.3 b/gtk+-mingw/share/man/man3/pcrepattern.3 deleted file mode 100644 index 6e6cc23..0000000 --- a/gtk+-mingw/share/man/man3/pcrepattern.3 +++ /dev/null @@ -1,2918 +0,0 @@ -.TH PCREPATTERN 3 "04 May 2012" "PCRE 8.31" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PCRE REGULAR EXPRESSION DETAILS" -.rs -.sp -The syntax and semantics of the regular expressions that are supported by PCRE -are described in detail below. There is a quick-reference syntax summary in the -.\" HREF -\fBpcresyntax\fP -.\" -page. PCRE tries to match Perl syntax and semantics as closely as it can. PCRE -also supports some alternative regular expression syntax (which does not -conflict with the Perl syntax) in order to provide some compatibility with -regular expressions in Python, .NET, and Oniguruma. -.P -Perl's regular expressions are described in its own documentation, and -regular expressions in general are covered in a number of books, some of which -have copious examples. Jeffrey Friedl's "Mastering Regular Expressions", -published by O'Reilly, covers regular expressions in great detail. This -description of PCRE's regular expressions is intended as reference material. -.P -The original operation of PCRE was on strings of one-byte characters. However, -there is now also support for UTF-8 strings in the original library, and a -second library that supports 16-bit and UTF-16 character strings. To use these -features, PCRE must be built to include appropriate support. When using UTF -strings you must either call the compiling function with the PCRE_UTF8 or -PCRE_UTF16 option, or the pattern must start with one of these special -sequences: -.sp - (*UTF8) - (*UTF16) -.sp -Starting a pattern with such a sequence is equivalent to setting the relevant -option. This feature is not Perl-compatible. How setting a UTF mode affects -pattern matching is mentioned in several places below. There is also a summary -of features in the -.\" HREF -\fBpcreunicode\fP -.\" -page. -.P -Another special sequence that may appear at the start of a pattern or in -combination with (*UTF8) or (*UTF16) is: -.sp - (*UCP) -.sp -This has the same effect as setting the PCRE_UCP option: it causes sequences -such as \ed and \ew to use Unicode properties to determine character types, -instead of recognizing only characters with codes less than 128 via a lookup -table. -.P -If a pattern starts with (*NO_START_OPT), it has the same effect as setting the -PCRE_NO_START_OPTIMIZE option either at compile or matching time. There are -also some more of these special sequences that are concerned with the handling -of newlines; they are described below. -.P -The remainder of this document discusses the patterns that are supported by -PCRE when one its main matching functions, \fBpcre_exec()\fP (8-bit) or -\fBpcre16_exec()\fP (16-bit), is used. PCRE also has alternative matching -functions, \fBpcre_dfa_exec()\fP and \fBpcre16_dfa_exec()\fP, which match using -a different algorithm that is not Perl-compatible. Some of the features -discussed below are not available when DFA matching is used. The advantages and -disadvantages of the alternative functions, and how they differ from the normal -functions, are discussed in the -.\" HREF -\fBpcrematching\fP -.\" -page. -. -. -.\" HTML <a name="newlines"></a> -.SH "NEWLINE CONVENTIONS" -.rs -.sp -PCRE supports five different conventions for indicating line breaks in -strings: a single CR (carriage return) character, a single LF (linefeed) -character, the two-character sequence CRLF, any of the three preceding, or any -Unicode newline sequence. The -.\" HREF -\fBpcreapi\fP -.\" -page has -.\" HTML <a href="pcreapi.html#newlines"> -.\" </a> -further discussion -.\" -about newlines, and shows how to set the newline convention in the -\fIoptions\fP arguments for the compiling and matching functions. -.P -It is also possible to specify a newline convention by starting a pattern -string with one of the following five sequences: -.sp - (*CR) carriage return - (*LF) linefeed - (*CRLF) carriage return, followed by linefeed - (*ANYCRLF) any of the three above - (*ANY) all Unicode newline sequences -.sp -These override the default and the options given to the compiling function. For -example, on a Unix system where LF is the default newline sequence, the pattern -.sp - (*CR)a.b -.sp -changes the convention to CR. That pattern matches "a\enb" because LF is no -longer a newline. Note that these special settings, which are not -Perl-compatible, are recognized only at the very start of a pattern, and that -they must be in upper case. If more than one of them is present, the last one -is used. -.P -The newline convention affects the interpretation of the dot metacharacter when -PCRE_DOTALL is not set, and also the behaviour of \eN. However, it does not -affect what the \eR escape sequence matches. By default, this is any Unicode -newline sequence, for Perl compatibility. However, this can be changed; see the -description of \eR in the section entitled -.\" HTML <a href="#newlineseq"> -.\" </a> -"Newline sequences" -.\" -below. A change of \eR setting can be combined with a change of newline -convention. -. -. -.SH "CHARACTERS AND METACHARACTERS" -.rs -.sp -A regular expression is a pattern that is matched against a subject string from -left to right. Most characters stand for themselves in a pattern, and match the -corresponding characters in the subject. As a trivial example, the pattern -.sp - The quick brown fox -.sp -matches a portion of a subject string that is identical to itself. When -caseless matching is specified (the PCRE_CASELESS option), letters are matched -independently of case. In a UTF mode, PCRE always understands the concept of -case for characters whose values are less than 128, so caseless matching is -always possible. For characters with higher values, the concept of case is -supported if PCRE is compiled with Unicode property support, but not otherwise. -If you want to use caseless matching for characters 128 and above, you must -ensure that PCRE is compiled with Unicode property support as well as with -UTF support. -.P -The power of regular expressions comes from the ability to include alternatives -and repetitions in the pattern. These are encoded in the pattern by the use of -\fImetacharacters\fP, which do not stand for themselves but instead are -interpreted in some special way. -.P -There are two different sets of metacharacters: those that are recognized -anywhere in the pattern except within square brackets, and those that are -recognized within square brackets. Outside square brackets, the metacharacters -are as follows: -.sp - \e general escape character with several uses - ^ assert start of string (or line, in multiline mode) - $ assert end of string (or line, in multiline mode) - . match any character except newline (by default) - [ start character class definition - | start of alternative branch - ( start subpattern - ) end subpattern - ? extends the meaning of ( - also 0 or 1 quantifier - also quantifier minimizer - * 0 or more quantifier - + 1 or more quantifier - also "possessive quantifier" - { start min/max quantifier -.sp -Part of a pattern that is in square brackets is called a "character class". In -a character class the only metacharacters are: -.sp - \e general escape character - ^ negate the class, but only if the first character - - indicates character range -.\" JOIN - [ POSIX character class (only if followed by POSIX - syntax) - ] terminates the character class -.sp -The following sections describe the use of each of the metacharacters. -. -. -.SH BACKSLASH -.rs -.sp -The backslash character has several uses. Firstly, if it is followed by a -character that is not a number or a letter, it takes away any special meaning -that character may have. This use of backslash as an escape character applies -both inside and outside character classes. -.P -For example, if you want to match a * character, you write \e* in the pattern. -This escaping action applies whether or not the following character would -otherwise be interpreted as a metacharacter, so it is always safe to precede a -non-alphanumeric with backslash to specify that it stands for itself. In -particular, if you want to match a backslash, you write \e\e. -.P -In a UTF mode, only ASCII numbers and letters have any special meaning after a -backslash. All other characters (in particular, those whose codepoints are -greater than 127) are treated as literals. -.P -If a pattern is compiled with the PCRE_EXTENDED option, white space in the -pattern (other than in a character class) and characters between a # outside -a character class and the next newline are ignored. An escaping backslash can -be used to include a white space or # character as part of the pattern. -.P -If you want to remove the special meaning from a sequence of characters, you -can do so by putting them between \eQ and \eE. This is different from Perl in -that $ and @ are handled as literals in \eQ...\eE sequences in PCRE, whereas in -Perl, $ and @ cause variable interpolation. Note the following examples: -.sp - Pattern PCRE matches Perl matches -.sp -.\" JOIN - \eQabc$xyz\eE abc$xyz abc followed by the - contents of $xyz - \eQabc\e$xyz\eE abc\e$xyz abc\e$xyz - \eQabc\eE\e$\eQxyz\eE abc$xyz abc$xyz -.sp -The \eQ...\eE sequence is recognized both inside and outside character classes. -An isolated \eE that is not preceded by \eQ is ignored. If \eQ is not followed -by \eE later in the pattern, the literal interpretation continues to the end of -the pattern (that is, \eE is assumed at the end). If the isolated \eQ is inside -a character class, this causes an error, because the character class is not -terminated. -. -. -.\" HTML <a name="digitsafterbackslash"></a> -.SS "Non-printing characters" -.rs -.sp -A second use of backslash provides a way of encoding non-printing characters -in patterns in a visible manner. There is no restriction on the appearance of -non-printing characters, apart from the binary zero that terminates a pattern, -but when a pattern is being prepared by text editing, it is often easier to use -one of the following escape sequences than the binary character it represents: -.sp - \ea alarm, that is, the BEL character (hex 07) - \ecx "control-x", where x is any ASCII character - \ee escape (hex 1B) - \ef form feed (hex 0C) - \en linefeed (hex 0A) - \er carriage return (hex 0D) - \et tab (hex 09) - \eddd character with octal code ddd, or back reference - \exhh character with hex code hh - \ex{hhh..} character with hex code hhh.. (non-JavaScript mode) - \euhhhh character with hex code hhhh (JavaScript mode only) -.sp -The precise effect of \ecx is as follows: if x is a lower case letter, it -is converted to upper case. Then bit 6 of the character (hex 40) is inverted. -Thus \ecz becomes hex 1A (z is 7A), but \ec{ becomes hex 3B ({ is 7B), while -\ec; becomes hex 7B (; is 3B). If the byte following \ec has a value greater -than 127, a compile-time error occurs. This locks out non-ASCII characters in -all modes. (When PCRE is compiled in EBCDIC mode, all byte values are valid. A -lower case letter is converted to upper case, and then the 0xc0 bits are -flipped.) -.P -By default, after \ex, from zero to two hexadecimal digits are read (letters -can be in upper or lower case). Any number of hexadecimal digits may appear -between \ex{ and }, but the character code is constrained as follows: -.sp - 8-bit non-UTF mode less than 0x100 - 8-bit UTF-8 mode less than 0x10ffff and a valid codepoint - 16-bit non-UTF mode less than 0x10000 - 16-bit UTF-16 mode less than 0x10ffff and a valid codepoint -.sp -Invalid Unicode codepoints are the range 0xd800 to 0xdfff (the so-called -"surrogate" codepoints). -.P -If characters other than hexadecimal digits appear between \ex{ and }, or if -there is no terminating }, this form of escape is not recognized. Instead, the -initial \ex will be interpreted as a basic hexadecimal escape, with no -following digits, giving a character whose value is zero. -.P -If the PCRE_JAVASCRIPT_COMPAT option is set, the interpretation of \ex is -as just described only when it is followed by two hexadecimal digits. -Otherwise, it matches a literal "x" character. In JavaScript mode, support for -code points greater than 256 is provided by \eu, which must be followed by -four hexadecimal digits; otherwise it matches a literal "u" character. -Character codes specified by \eu in JavaScript mode are constrained in the same -was as those specified by \ex in non-JavaScript mode. -.P -Characters whose value is less than 256 can be defined by either of the two -syntaxes for \ex (or by \eu in JavaScript mode). There is no difference in the -way they are handled. For example, \exdc is exactly the same as \ex{dc} (or -\eu00dc in JavaScript mode). -.P -After \e0 up to two further octal digits are read. If there are fewer than two -digits, just those that are present are used. Thus the sequence \e0\ex\e07 -specifies two binary zeros followed by a BEL character (code value 7). Make -sure you supply two digits after the initial zero if the pattern character that -follows is itself an octal digit. -.P -The handling of a backslash followed by a digit other than 0 is complicated. -Outside a character class, PCRE reads it and any following digits as a decimal -number. If the number is less than 10, or if there have been at least that many -previous capturing left parentheses in the expression, the entire sequence is -taken as a \fIback reference\fP. A description of how this works is given -.\" HTML <a href="#backreferences"> -.\" </a> -later, -.\" -following the discussion of -.\" HTML <a href="#subpattern"> -.\" </a> -parenthesized subpatterns. -.\" -.P -Inside a character class, or if the decimal number is greater than 9 and there -have not been that many capturing subpatterns, PCRE re-reads up to three octal -digits following the backslash, and uses them to generate a data character. Any -subsequent digits stand for themselves. The value of the character is -constrained in the same way as characters specified in hexadecimal. -For example: -.sp - \e040 is another way of writing a space -.\" JOIN - \e40 is the same, provided there are fewer than 40 - previous capturing subpatterns - \e7 is always a back reference -.\" JOIN - \e11 might be a back reference, or another way of - writing a tab - \e011 is always a tab - \e0113 is a tab followed by the character "3" -.\" JOIN - \e113 might be a back reference, otherwise the - character with octal code 113 -.\" JOIN - \e377 might be a back reference, otherwise - the value 255 (decimal) -.\" JOIN - \e81 is either a back reference, or a binary zero - followed by the two characters "8" and "1" -.sp -Note that octal values of 100 or greater must not be introduced by a leading -zero, because no more than three octal digits are ever read. -.P -All the sequences that define a single character value can be used both inside -and outside character classes. In addition, inside a character class, \eb is -interpreted as the backspace character (hex 08). -.P -\eN is not allowed in a character class. \eB, \eR, and \eX are not special -inside a character class. Like other unrecognized escape sequences, they are -treated as the literal characters "B", "R", and "X" by default, but cause an -error if the PCRE_EXTRA option is set. Outside a character class, these -sequences have different meanings. -. -. -.SS "Unsupported escape sequences" -.rs -.sp -In Perl, the sequences \el, \eL, \eu, and \eU are recognized by its string -handler and used to modify the case of following characters. By default, PCRE -does not support these escape sequences. However, if the PCRE_JAVASCRIPT_COMPAT -option is set, \eU matches a "U" character, and \eu can be used to define a -character by code point, as described in the previous section. -. -. -.SS "Absolute and relative back references" -.rs -.sp -The sequence \eg followed by an unsigned or a negative number, optionally -enclosed in braces, is an absolute or relative back reference. A named back -reference can be coded as \eg{name}. Back references are discussed -.\" HTML <a href="#backreferences"> -.\" </a> -later, -.\" -following the discussion of -.\" HTML <a href="#subpattern"> -.\" </a> -parenthesized subpatterns. -.\" -. -. -.SS "Absolute and relative subroutine calls" -.rs -.sp -For compatibility with Oniguruma, the non-Perl syntax \eg followed by a name or -a number enclosed either in angle brackets or single quotes, is an alternative -syntax for referencing a subpattern as a "subroutine". Details are discussed -.\" HTML <a href="#onigurumasubroutines"> -.\" </a> -later. -.\" -Note that \eg{...} (Perl syntax) and \eg<...> (Oniguruma syntax) are \fInot\fP -synonymous. The former is a back reference; the latter is a -.\" HTML <a href="#subpatternsassubroutines"> -.\" </a> -subroutine -.\" -call. -. -. -.\" HTML <a name="genericchartypes"></a> -.SS "Generic character types" -.rs -.sp -Another use of backslash is for specifying generic character types: -.sp - \ed any decimal digit - \eD any character that is not a decimal digit - \eh any horizontal white space character - \eH any character that is not a horizontal white space character - \es any white space character - \eS any character that is not a white space character - \ev any vertical white space character - \eV any character that is not a vertical white space character - \ew any "word" character - \eW any "non-word" character -.sp -There is also the single sequence \eN, which matches a non-newline character. -This is the same as -.\" HTML <a href="#fullstopdot"> -.\" </a> -the "." metacharacter -.\" -when PCRE_DOTALL is not set. Perl also uses \eN to match characters by name; -PCRE does not support this. -.P -Each pair of lower and upper case escape sequences partitions the complete set -of characters into two disjoint sets. Any given character matches one, and only -one, of each pair. The sequences can appear both inside and outside character -classes. They each match one character of the appropriate type. If the current -matching point is at the end of the subject string, all of them fail, because -there is no character to match. -.P -For compatibility with Perl, \es does not match the VT character (code 11). -This makes it different from the the POSIX "space" class. The \es characters -are HT (9), LF (10), FF (12), CR (13), and space (32). If "use locale;" is -included in a Perl script, \es may match the VT character. In PCRE, it never -does. -.P -A "word" character is an underscore or any character that is a letter or digit. -By default, the definition of letters and digits is controlled by PCRE's -low-valued character tables, and may vary if locale-specific matching is taking -place (see -.\" HTML <a href="pcreapi.html#localesupport"> -.\" </a> -"Locale support" -.\" -in the -.\" HREF -\fBpcreapi\fP -.\" -page). For example, in a French locale such as "fr_FR" in Unix-like systems, -or "french" in Windows, some character codes greater than 128 are used for -accented letters, and these are then matched by \ew. The use of locales with -Unicode is discouraged. -.P -By default, in a UTF mode, characters with values greater than 128 never match -\ed, \es, or \ew, and always match \eD, \eS, and \eW. These sequences retain -their original meanings from before UTF support was available, mainly for -efficiency reasons. However, if PCRE is compiled with Unicode property support, -and the PCRE_UCP option is set, the behaviour is changed so that Unicode -properties are used to determine character types, as follows: -.sp - \ed any character that \ep{Nd} matches (decimal digit) - \es any character that \ep{Z} matches, plus HT, LF, FF, CR - \ew any character that \ep{L} or \ep{N} matches, plus underscore -.sp -The upper case escapes match the inverse sets of characters. Note that \ed -matches only decimal digits, whereas \ew matches any Unicode digit, as well as -any Unicode letter, and underscore. Note also that PCRE_UCP affects \eb, and -\eB because they are defined in terms of \ew and \eW. Matching these sequences -is noticeably slower when PCRE_UCP is set. -.P -The sequences \eh, \eH, \ev, and \eV are features that were added to Perl at -release 5.10. In contrast to the other sequences, which match only ASCII -characters by default, these always match certain high-valued codepoints, -whether or not PCRE_UCP is set. The horizontal space characters are: -.sp - U+0009 Horizontal tab - U+0020 Space - U+00A0 Non-break space - U+1680 Ogham space mark - U+180E Mongolian vowel separator - U+2000 En quad - U+2001 Em quad - U+2002 En space - U+2003 Em space - U+2004 Three-per-em space - U+2005 Four-per-em space - U+2006 Six-per-em space - U+2007 Figure space - U+2008 Punctuation space - U+2009 Thin space - U+200A Hair space - U+202F Narrow no-break space - U+205F Medium mathematical space - U+3000 Ideographic space -.sp -The vertical space characters are: -.sp - U+000A Linefeed - U+000B Vertical tab - U+000C Form feed - U+000D Carriage return - U+0085 Next line - U+2028 Line separator - U+2029 Paragraph separator -.sp -In 8-bit, non-UTF-8 mode, only the characters with codepoints less than 256 are -relevant. -. -. -.\" HTML <a name="newlineseq"></a> -.SS "Newline sequences" -.rs -.sp -Outside a character class, by default, the escape sequence \eR matches any -Unicode newline sequence. In 8-bit non-UTF-8 mode \eR is equivalent to the -following: -.sp - (?>\er\en|\en|\ex0b|\ef|\er|\ex85) -.sp -This is an example of an "atomic group", details of which are given -.\" HTML <a href="#atomicgroup"> -.\" </a> -below. -.\" -This particular group matches either the two-character sequence CR followed by -LF, or one of the single characters LF (linefeed, U+000A), VT (vertical tab, -U+000B), FF (form feed, U+000C), CR (carriage return, U+000D), or NEL (next -line, U+0085). The two-character sequence is treated as a single unit that -cannot be split. -.P -In other modes, two additional characters whose codepoints are greater than 255 -are added: LS (line separator, U+2028) and PS (paragraph separator, U+2029). -Unicode character property support is not needed for these characters to be -recognized. -.P -It is possible to restrict \eR to match only CR, LF, or CRLF (instead of the -complete set of Unicode line endings) by setting the option PCRE_BSR_ANYCRLF -either at compile time or when the pattern is matched. (BSR is an abbrevation -for "backslash R".) This can be made the default when PCRE is built; if this is -the case, the other behaviour can be requested via the PCRE_BSR_UNICODE option. -It is also possible to specify these settings by starting a pattern string with -one of the following sequences: -.sp - (*BSR_ANYCRLF) CR, LF, or CRLF only - (*BSR_UNICODE) any Unicode newline sequence -.sp -These override the default and the options given to the compiling function, but -they can themselves be overridden by options given to a matching function. Note -that these special settings, which are not Perl-compatible, are recognized only -at the very start of a pattern, and that they must be in upper case. If more -than one of them is present, the last one is used. They can be combined with a -change of newline convention; for example, a pattern can start with: -.sp - (*ANY)(*BSR_ANYCRLF) -.sp -They can also be combined with the (*UTF8), (*UTF16), or (*UCP) special -sequences. Inside a character class, \eR is treated as an unrecognized escape -sequence, and so matches the letter "R" by default, but causes an error if -PCRE_EXTRA is set. -. -. -.\" HTML <a name="uniextseq"></a> -.SS Unicode character properties -.rs -.sp -When PCRE is built with Unicode character property support, three additional -escape sequences that match characters with specific properties are available. -When in 8-bit non-UTF-8 mode, these sequences are of course limited to testing -characters whose codepoints are less than 256, but they do work in this mode. -The extra escape sequences are: -.sp - \ep{\fIxx\fP} a character with the \fIxx\fP property - \eP{\fIxx\fP} a character without the \fIxx\fP property - \eX an extended Unicode sequence -.sp -The property names represented by \fIxx\fP above are limited to the Unicode -script names, the general category properties, "Any", which matches any -character (including newline), and some special PCRE properties (described -in the -.\" HTML <a href="#extraprops"> -.\" </a> -next section). -.\" -Other Perl properties such as "InMusicalSymbols" are not currently supported by -PCRE. Note that \eP{Any} does not match any characters, so always causes a -match failure. -.P -Sets of Unicode characters are defined as belonging to certain scripts. A -character from one of these sets can be matched using a script name. For -example: -.sp - \ep{Greek} - \eP{Han} -.sp -Those that are not part of an identified script are lumped together as -"Common". The current list of scripts is: -.P -Arabic, -Armenian, -Avestan, -Balinese, -Bamum, -Batak, -Bengali, -Bopomofo, -Brahmi, -Braille, -Buginese, -Buhid, -Canadian_Aboriginal, -Carian, -Chakma, -Cham, -Cherokee, -Common, -Coptic, -Cuneiform, -Cypriot, -Cyrillic, -Deseret, -Devanagari, -Egyptian_Hieroglyphs, -Ethiopic, -Georgian, -Glagolitic, -Gothic, -Greek, -Gujarati, -Gurmukhi, -Han, -Hangul, -Hanunoo, -Hebrew, -Hiragana, -Imperial_Aramaic, -Inherited, -Inscriptional_Pahlavi, -Inscriptional_Parthian, -Javanese, -Kaithi, -Kannada, -Katakana, -Kayah_Li, -Kharoshthi, -Khmer, -Lao, -Latin, -Lepcha, -Limbu, -Linear_B, -Lisu, -Lycian, -Lydian, -Malayalam, -Mandaic, -Meetei_Mayek, -Meroitic_Cursive, -Meroitic_Hieroglyphs, -Miao, -Mongolian, -Myanmar, -New_Tai_Lue, -Nko, -Ogham, -Old_Italic, -Old_Persian, -Old_South_Arabian, -Old_Turkic, -Ol_Chiki, -Oriya, -Osmanya, -Phags_Pa, -Phoenician, -Rejang, -Runic, -Samaritan, -Saurashtra, -Sharada, -Shavian, -Sinhala, -Sora_Sompeng, -Sundanese, -Syloti_Nagri, -Syriac, -Tagalog, -Tagbanwa, -Tai_Le, -Tai_Tham, -Tai_Viet, -Takri, -Tamil, -Telugu, -Thaana, -Thai, -Tibetan, -Tifinagh, -Ugaritic, -Vai, -Yi. -.P -Each character has exactly one Unicode general category property, specified by -a two-letter abbreviation. For compatibility with Perl, negation can be -specified by including a circumflex between the opening brace and the property -name. For example, \ep{^Lu} is the same as \eP{Lu}. -.P -If only one letter is specified with \ep or \eP, it includes all the general -category properties that start with that letter. In this case, in the absence -of negation, the curly brackets in the escape sequence are optional; these two -examples have the same effect: -.sp - \ep{L} - \epL -.sp -The following general category property codes are supported: -.sp - C Other - Cc Control - Cf Format - Cn Unassigned - Co Private use - Cs Surrogate -.sp - L Letter - Ll Lower case letter - Lm Modifier letter - Lo Other letter - Lt Title case letter - Lu Upper case letter -.sp - M Mark - Mc Spacing mark - Me Enclosing mark - Mn Non-spacing mark -.sp - N Number - Nd Decimal number - Nl Letter number - No Other number -.sp - P Punctuation - Pc Connector punctuation - Pd Dash punctuation - Pe Close punctuation - Pf Final punctuation - Pi Initial punctuation - Po Other punctuation - Ps Open punctuation -.sp - S Symbol - Sc Currency symbol - Sk Modifier symbol - Sm Mathematical symbol - So Other symbol -.sp - Z Separator - Zl Line separator - Zp Paragraph separator - Zs Space separator -.sp -The special property L& is also supported: it matches a character that has -the Lu, Ll, or Lt property, in other words, a letter that is not classified as -a modifier or "other". -.P -The Cs (Surrogate) property applies only to characters in the range U+D800 to -U+DFFF. Such characters are not valid in Unicode strings and so -cannot be tested by PCRE, unless UTF validity checking has been turned off -(see the discussion of PCRE_NO_UTF8_CHECK and PCRE_NO_UTF16_CHECK in the -.\" HREF -\fBpcreapi\fP -.\" -page). Perl does not support the Cs property. -.P -The long synonyms for property names that Perl supports (such as \ep{Letter}) -are not supported by PCRE, nor is it permitted to prefix any of these -properties with "Is". -.P -No character that is in the Unicode table has the Cn (unassigned) property. -Instead, this property is assumed for any code point that is not in the -Unicode table. -.P -Specifying caseless matching does not affect these escape sequences. For -example, \ep{Lu} always matches only upper case letters. -.P -The \eX escape matches any number of Unicode characters that form an extended -Unicode sequence. \eX is equivalent to -.sp - (?>\ePM\epM*) -.sp -That is, it matches a character without the "mark" property, followed by zero -or more characters with the "mark" property, and treats the sequence as an -atomic group -.\" HTML <a href="#atomicgroup"> -.\" </a> -(see below). -.\" -Characters with the "mark" property are typically accents that affect the -preceding character. None of them have codepoints less than 256, so in -8-bit non-UTF-8 mode \eX matches any one character. -.P -Note that recent versions of Perl have changed \eX to match what Unicode calls -an "extended grapheme cluster", which has a more complicated definition. -.P -Matching characters by Unicode property is not fast, because PCRE has to search -a structure that contains data for over fifteen thousand characters. That is -why the traditional escape sequences such as \ed and \ew do not use Unicode -properties in PCRE by default, though you can make them do so by setting the -PCRE_UCP option or by starting the pattern with (*UCP). -. -. -.\" HTML <a name="extraprops"></a> -.SS PCRE's additional properties -.rs -.sp -As well as the standard Unicode properties described in the previous -section, PCRE supports four more that make it possible to convert traditional -escape sequences such as \ew and \es and POSIX character classes to use Unicode -properties. PCRE uses these non-standard, non-Perl properties internally when -PCRE_UCP is set. They are: -.sp - Xan Any alphanumeric character - Xps Any POSIX space character - Xsp Any Perl space character - Xwd Any Perl "word" character -.sp -Xan matches characters that have either the L (letter) or the N (number) -property. Xps matches the characters tab, linefeed, vertical tab, form feed, or -carriage return, and any other character that has the Z (separator) property. -Xsp is the same as Xps, except that vertical tab is excluded. Xwd matches the -same characters as Xan, plus underscore. -. -. -.\" HTML <a name="resetmatchstart"></a> -.SS "Resetting the match start" -.rs -.sp -The escape sequence \eK causes any previously matched characters not to be -included in the final matched sequence. For example, the pattern: -.sp - foo\eKbar -.sp -matches "foobar", but reports that it has matched "bar". This feature is -similar to a lookbehind assertion -.\" HTML <a href="#lookbehind"> -.\" </a> -(described below). -.\" -However, in this case, the part of the subject before the real match does not -have to be of fixed length, as lookbehind assertions do. The use of \eK does -not interfere with the setting of -.\" HTML <a href="#subpattern"> -.\" </a> -captured substrings. -.\" -For example, when the pattern -.sp - (foo)\eKbar -.sp -matches "foobar", the first substring is still set to "foo". -.P -Perl documents that the use of \eK within assertions is "not well defined". In -PCRE, \eK is acted upon when it occurs inside positive assertions, but is -ignored in negative assertions. -. -. -.\" HTML <a name="smallassertions"></a> -.SS "Simple assertions" -.rs -.sp -The final use of backslash is for certain simple assertions. An assertion -specifies a condition that has to be met at a particular point in a match, -without consuming any characters from the subject string. The use of -subpatterns for more complicated assertions is described -.\" HTML <a href="#bigassertions"> -.\" </a> -below. -.\" -The backslashed assertions are: -.sp - \eb matches at a word boundary - \eB matches when not at a word boundary - \eA matches at the start of the subject - \eZ matches at the end of the subject - also matches before a newline at the end of the subject - \ez matches only at the end of the subject - \eG matches at the first matching position in the subject -.sp -Inside a character class, \eb has a different meaning; it matches the backspace -character. If any other of these assertions appears in a character class, by -default it matches the corresponding literal character (for example, \eB -matches the letter B). However, if the PCRE_EXTRA option is set, an "invalid -escape sequence" error is generated instead. -.P -A word boundary is a position in the subject string where the current character -and the previous character do not both match \ew or \eW (i.e. one matches -\ew and the other matches \eW), or the start or end of the string if the -first or last character matches \ew, respectively. In a UTF mode, the meanings -of \ew and \eW can be changed by setting the PCRE_UCP option. When this is -done, it also affects \eb and \eB. Neither PCRE nor Perl has a separate "start -of word" or "end of word" metasequence. However, whatever follows \eb normally -determines which it is. For example, the fragment \eba matches "a" at the start -of a word. -.P -The \eA, \eZ, and \ez assertions differ from the traditional circumflex and -dollar (described in the next section) in that they only ever match at the very -start and end of the subject string, whatever options are set. Thus, they are -independent of multiline mode. These three assertions are not affected by the -PCRE_NOTBOL or PCRE_NOTEOL options, which affect only the behaviour of the -circumflex and dollar metacharacters. However, if the \fIstartoffset\fP -argument of \fBpcre_exec()\fP is non-zero, indicating that matching is to start -at a point other than the beginning of the subject, \eA can never match. The -difference between \eZ and \ez is that \eZ matches before a newline at the end -of the string as well as at the very end, whereas \ez matches only at the end. -.P -The \eG assertion is true only when the current matching position is at the -start point of the match, as specified by the \fIstartoffset\fP argument of -\fBpcre_exec()\fP. It differs from \eA when the value of \fIstartoffset\fP is -non-zero. By calling \fBpcre_exec()\fP multiple times with appropriate -arguments, you can mimic Perl's /g option, and it is in this kind of -implementation where \eG can be useful. -.P -Note, however, that PCRE's interpretation of \eG, as the start of the current -match, is subtly different from Perl's, which defines it as the end of the -previous match. In Perl, these can be different when the previously matched -string was empty. Because PCRE does just one match at a time, it cannot -reproduce this behaviour. -.P -If all the alternatives of a pattern begin with \eG, the expression is anchored -to the starting match position, and the "anchored" flag is set in the compiled -regular expression. -. -. -.SH "CIRCUMFLEX AND DOLLAR" -.rs -.sp -Outside a character class, in the default matching mode, the circumflex -character is an assertion that is true only if the current matching point is -at the start of the subject string. If the \fIstartoffset\fP argument of -\fBpcre_exec()\fP is non-zero, circumflex can never match if the PCRE_MULTILINE -option is unset. Inside a character class, circumflex has an entirely different -meaning -.\" HTML <a href="#characterclass"> -.\" </a> -(see below). -.\" -.P -Circumflex need not be the first character of the pattern if a number of -alternatives are involved, but it should be the first thing in each alternative -in which it appears if the pattern is ever to match that branch. If all -possible alternatives start with a circumflex, that is, if the pattern is -constrained to match only at the start of the subject, it is said to be an -"anchored" pattern. (There are also other constructs that can cause a pattern -to be anchored.) -.P -A dollar character is an assertion that is true only if the current matching -point is at the end of the subject string, or immediately before a newline -at the end of the string (by default). Dollar need not be the last character of -the pattern if a number of alternatives are involved, but it should be the last -item in any branch in which it appears. Dollar has no special meaning in a -character class. -.P -The meaning of dollar can be changed so that it matches only at the very end of -the string, by setting the PCRE_DOLLAR_ENDONLY option at compile time. This -does not affect the \eZ assertion. -.P -The meanings of the circumflex and dollar characters are changed if the -PCRE_MULTILINE option is set. When this is the case, a circumflex matches -immediately after internal newlines as well as at the start of the subject -string. It does not match after a newline that ends the string. A dollar -matches before any newlines in the string, as well as at the very end, when -PCRE_MULTILINE is set. When newline is specified as the two-character -sequence CRLF, isolated CR and LF characters do not indicate newlines. -.P -For example, the pattern /^abc$/ matches the subject string "def\enabc" (where -\en represents a newline) in multiline mode, but not otherwise. Consequently, -patterns that are anchored in single line mode because all branches start with -^ are not anchored in multiline mode, and a match for circumflex is possible -when the \fIstartoffset\fP argument of \fBpcre_exec()\fP is non-zero. The -PCRE_DOLLAR_ENDONLY option is ignored if PCRE_MULTILINE is set. -.P -Note that the sequences \eA, \eZ, and \ez can be used to match the start and -end of the subject in both modes, and if all branches of a pattern start with -\eA it is always anchored, whether or not PCRE_MULTILINE is set. -. -. -.\" HTML <a name="fullstopdot"></a> -.SH "FULL STOP (PERIOD, DOT) AND \eN" -.rs -.sp -Outside a character class, a dot in the pattern matches any one character in -the subject string except (by default) a character that signifies the end of a -line. -.P -When a line ending is defined as a single character, dot never matches that -character; when the two-character sequence CRLF is used, dot does not match CR -if it is immediately followed by LF, but otherwise it matches all characters -(including isolated CRs and LFs). When any Unicode line endings are being -recognized, dot does not match CR or LF or any of the other line ending -characters. -.P -The behaviour of dot with regard to newlines can be changed. If the PCRE_DOTALL -option is set, a dot matches any one character, without exception. If the -two-character sequence CRLF is present in the subject string, it takes two dots -to match it. -.P -The handling of dot is entirely independent of the handling of circumflex and -dollar, the only relationship being that they both involve newlines. Dot has no -special meaning in a character class. -.P -The escape sequence \eN behaves like a dot, except that it is not affected by -the PCRE_DOTALL option. In other words, it matches any character except one -that signifies the end of a line. Perl also uses \eN to match characters by -name; PCRE does not support this. -. -. -.SH "MATCHING A SINGLE DATA UNIT" -.rs -.sp -Outside a character class, the escape sequence \eC matches any one data unit, -whether or not a UTF mode is set. In the 8-bit library, one data unit is one -byte; in the 16-bit library it is a 16-bit unit. Unlike a dot, \eC always -matches line-ending characters. The feature is provided in Perl in order to -match individual bytes in UTF-8 mode, but it is unclear how it can usefully be -used. Because \eC breaks up characters into individual data units, matching one -unit with \eC in a UTF mode means that the rest of the string may start with a -malformed UTF character. This has undefined results, because PCRE assumes that -it is dealing with valid UTF strings (and by default it checks this at the -start of processing unless the PCRE_NO_UTF8_CHECK or PCRE_NO_UTF16_CHECK option -is used). -.P -PCRE does not allow \eC to appear in lookbehind assertions -.\" HTML <a href="#lookbehind"> -.\" </a> -(described below) -.\" -in a UTF mode, because this would make it impossible to calculate the length of -the lookbehind. -.P -In general, the \eC escape sequence is best avoided. However, one -way of using it that avoids the problem of malformed UTF characters is to use a -lookahead to check the length of the next character, as in this pattern, which -could be used with a UTF-8 string (ignore white space and line breaks): -.sp - (?| (?=[\ex00-\ex7f])(\eC) | - (?=[\ex80-\ex{7ff}])(\eC)(\eC) | - (?=[\ex{800}-\ex{ffff}])(\eC)(\eC)(\eC) | - (?=[\ex{10000}-\ex{1fffff}])(\eC)(\eC)(\eC)(\eC)) -.sp -A group that starts with (?| resets the capturing parentheses numbers in each -alternative (see -.\" HTML <a href="#dupsubpatternnumber"> -.\" </a> -"Duplicate Subpattern Numbers" -.\" -below). The assertions at the start of each branch check the next UTF-8 -character for values whose encoding uses 1, 2, 3, or 4 bytes, respectively. The -character's individual bytes are then captured by the appropriate number of -groups. -. -. -.\" HTML <a name="characterclass"></a> -.SH "SQUARE BRACKETS AND CHARACTER CLASSES" -.rs -.sp -An opening square bracket introduces a character class, terminated by a closing -square bracket. A closing square bracket on its own is not special by default. -However, if the PCRE_JAVASCRIPT_COMPAT option is set, a lone closing square -bracket causes a compile-time error. If a closing square bracket is required as -a member of the class, it should be the first data character in the class -(after an initial circumflex, if present) or escaped with a backslash. -.P -A character class matches a single character in the subject. In a UTF mode, the -character may be more than one data unit long. A matched character must be in -the set of characters defined by the class, unless the first character in the -class definition is a circumflex, in which case the subject character must not -be in the set defined by the class. If a circumflex is actually required as a -member of the class, ensure it is not the first character, or escape it with a -backslash. -.P -For example, the character class [aeiou] matches any lower case vowel, while -[^aeiou] matches any character that is not a lower case vowel. Note that a -circumflex is just a convenient notation for specifying the characters that -are in the class by enumerating those that are not. A class that starts with a -circumflex is not an assertion; it still consumes a character from the subject -string, and therefore it fails if the current pointer is at the end of the -string. -.P -In UTF-8 (UTF-16) mode, characters with values greater than 255 (0xffff) can be -included in a class as a literal string of data units, or by using the \ex{ -escaping mechanism. -.P -When caseless matching is set, any letters in a class represent both their -upper case and lower case versions, so for example, a caseless [aeiou] matches -"A" as well as "a", and a caseless [^aeiou] does not match "A", whereas a -caseful version would. In a UTF mode, PCRE always understands the concept of -case for characters whose values are less than 128, so caseless matching is -always possible. For characters with higher values, the concept of case is -supported if PCRE is compiled with Unicode property support, but not otherwise. -If you want to use caseless matching in a UTF mode for characters 128 and -above, you must ensure that PCRE is compiled with Unicode property support as -well as with UTF support. -.P -Characters that might indicate line breaks are never treated in any special way -when matching character classes, whatever line-ending sequence is in use, and -whatever setting of the PCRE_DOTALL and PCRE_MULTILINE options is used. A class -such as [^a] always matches one of these characters. -.P -The minus (hyphen) character can be used to specify a range of characters in a -character class. For example, [d-m] matches any letter between d and m, -inclusive. If a minus character is required in a class, it must be escaped with -a backslash or appear in a position where it cannot be interpreted as -indicating a range, typically as the first or last character in the class. -.P -It is not possible to have the literal character "]" as the end character of a -range. A pattern such as [W-]46] is interpreted as a class of two characters -("W" and "-") followed by a literal string "46]", so it would match "W46]" or -"-46]". However, if the "]" is escaped with a backslash it is interpreted as -the end of range, so [W-\e]46] is interpreted as a class containing a range -followed by two other characters. The octal or hexadecimal representation of -"]" can also be used to end a range. -.P -Ranges operate in the collating sequence of character values. They can also be -used for characters specified numerically, for example [\e000-\e037]. Ranges -can include any characters that are valid for the current mode. -.P -If a range that includes letters is used when caseless matching is set, it -matches the letters in either case. For example, [W-c] is equivalent to -[][\e\e^_`wxyzabc], matched caselessly, and in a non-UTF mode, if character -tables for a French locale are in use, [\exc8-\excb] matches accented E -characters in both cases. In UTF modes, PCRE supports the concept of case for -characters with values greater than 128 only when it is compiled with Unicode -property support. -.P -The character escape sequences \ed, \eD, \eh, \eH, \ep, \eP, \es, \eS, \ev, -\eV, \ew, and \eW may appear in a character class, and add the characters that -they match to the class. For example, [\edABCDEF] matches any hexadecimal -digit. In UTF modes, the PCRE_UCP option affects the meanings of \ed, \es, \ew -and their upper case partners, just as it does when they appear outside a -character class, as described in the section entitled -.\" HTML <a href="#genericchartypes"> -.\" </a> -"Generic character types" -.\" -above. The escape sequence \eb has a different meaning inside a character -class; it matches the backspace character. The sequences \eB, \eN, \eR, and \eX -are not special inside a character class. Like any other unrecognized escape -sequences, they are treated as the literal characters "B", "N", "R", and "X" by -default, but cause an error if the PCRE_EXTRA option is set. -.P -A circumflex can conveniently be used with the upper case character types to -specify a more restricted set of characters than the matching lower case type. -For example, the class [^\eW_] matches any letter or digit, but not underscore, -whereas [\ew] includes underscore. A positive character class should be read as -"something OR something OR ..." and a negative class as "NOT something AND NOT -something AND NOT ...". -.P -The only metacharacters that are recognized in character classes are backslash, -hyphen (only where it can be interpreted as specifying a range), circumflex -(only at the start), opening square bracket (only when it can be interpreted as -introducing a POSIX class name - see the next section), and the terminating -closing square bracket. However, escaping other non-alphanumeric characters -does no harm. -. -. -.SH "POSIX CHARACTER CLASSES" -.rs -.sp -Perl supports the POSIX notation for character classes. This uses names -enclosed by [: and :] within the enclosing square brackets. PCRE also supports -this notation. For example, -.sp - [01[:alpha:]%] -.sp -matches "0", "1", any alphabetic character, or "%". The supported class names -are: -.sp - alnum letters and digits - alpha letters - ascii character codes 0 - 127 - blank space or tab only - cntrl control characters - digit decimal digits (same as \ed) - graph printing characters, excluding space - lower lower case letters - print printing characters, including space - punct printing characters, excluding letters and digits and space - space white space (not quite the same as \es) - upper upper case letters - word "word" characters (same as \ew) - xdigit hexadecimal digits -.sp -The "space" characters are HT (9), LF (10), VT (11), FF (12), CR (13), and -space (32). Notice that this list includes the VT character (code 11). This -makes "space" different to \es, which does not include VT (for Perl -compatibility). -.P -The name "word" is a Perl extension, and "blank" is a GNU extension from Perl -5.8. Another Perl extension is negation, which is indicated by a ^ character -after the colon. For example, -.sp - [12[:^digit:]] -.sp -matches "1", "2", or any non-digit. PCRE (and Perl) also recognize the POSIX -syntax [.ch.] and [=ch=] where "ch" is a "collating element", but these are not -supported, and an error is given if they are encountered. -.P -By default, in UTF modes, characters with values greater than 128 do not match -any of the POSIX character classes. However, if the PCRE_UCP option is passed -to \fBpcre_compile()\fP, some of the classes are changed so that Unicode -character properties are used. This is achieved by replacing the POSIX classes -by other sequences, as follows: -.sp - [:alnum:] becomes \ep{Xan} - [:alpha:] becomes \ep{L} - [:blank:] becomes \eh - [:digit:] becomes \ep{Nd} - [:lower:] becomes \ep{Ll} - [:space:] becomes \ep{Xps} - [:upper:] becomes \ep{Lu} - [:word:] becomes \ep{Xwd} -.sp -Negated versions, such as [:^alpha:] use \eP instead of \ep. The other POSIX -classes are unchanged, and match only characters with code points less than -128. -. -. -.SH "VERTICAL BAR" -.rs -.sp -Vertical bar characters are used to separate alternative patterns. For example, -the pattern -.sp - gilbert|sullivan -.sp -matches either "gilbert" or "sullivan". Any number of alternatives may appear, -and an empty alternative is permitted (matching the empty string). The matching -process tries each alternative in turn, from left to right, and the first one -that succeeds is used. If the alternatives are within a subpattern -.\" HTML <a href="#subpattern"> -.\" </a> -(defined below), -.\" -"succeeds" means matching the rest of the main pattern as well as the -alternative in the subpattern. -. -. -.SH "INTERNAL OPTION SETTING" -.rs -.sp -The settings of the PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, and -PCRE_EXTENDED options (which are Perl-compatible) can be changed from within -the pattern by a sequence of Perl option letters enclosed between "(?" and ")". -The option letters are -.sp - i for PCRE_CASELESS - m for PCRE_MULTILINE - s for PCRE_DOTALL - x for PCRE_EXTENDED -.sp -For example, (?im) sets caseless, multiline matching. It is also possible to -unset these options by preceding the letter with a hyphen, and a combined -setting and unsetting such as (?im-sx), which sets PCRE_CASELESS and -PCRE_MULTILINE while unsetting PCRE_DOTALL and PCRE_EXTENDED, is also -permitted. If a letter appears both before and after the hyphen, the option is -unset. -.P -The PCRE-specific options PCRE_DUPNAMES, PCRE_UNGREEDY, and PCRE_EXTRA can be -changed in the same way as the Perl-compatible options by using the characters -J, U and X respectively. -.P -When one of these option changes occurs at top level (that is, not inside -subpattern parentheses), the change applies to the remainder of the pattern -that follows. If the change is placed right at the start of a pattern, PCRE -extracts it into the global options (and it will therefore show up in data -extracted by the \fBpcre_fullinfo()\fP function). -.P -An option change within a subpattern (see below for a description of -subpatterns) affects only that part of the subpattern that follows it, so -.sp - (a(?i)b)c -.sp -matches abc and aBc and no other strings (assuming PCRE_CASELESS is not used). -By this means, options can be made to have different settings in different -parts of the pattern. Any changes made in one alternative do carry on -into subsequent branches within the same subpattern. For example, -.sp - (a(?i)b|c) -.sp -matches "ab", "aB", "c", and "C", even though when matching "C" the first -branch is abandoned before the option setting. This is because the effects of -option settings happen at compile time. There would be some very weird -behaviour otherwise. -.P -\fBNote:\fP There are other PCRE-specific options that can be set by the -application when the compiling or matching functions are called. In some cases -the pattern can contain special leading sequences such as (*CRLF) to override -what the application has set or what has been defaulted. Details are given in -the section entitled -.\" HTML <a href="#newlineseq"> -.\" </a> -"Newline sequences" -.\" -above. There are also the (*UTF8), (*UTF16), and (*UCP) leading sequences that -can be used to set UTF and Unicode property modes; they are equivalent to -setting the PCRE_UTF8, PCRE_UTF16, and the PCRE_UCP options, respectively. -. -. -.\" HTML <a name="subpattern"></a> -.SH SUBPATTERNS -.rs -.sp -Subpatterns are delimited by parentheses (round brackets), which can be nested. -Turning part of a pattern into a subpattern does two things: -.sp -1. It localizes a set of alternatives. For example, the pattern -.sp - cat(aract|erpillar|) -.sp -matches "cataract", "caterpillar", or "cat". Without the parentheses, it would -match "cataract", "erpillar" or an empty string. -.sp -2. It sets up the subpattern as a capturing subpattern. This means that, when -the whole pattern matches, that portion of the subject string that matched the -subpattern is passed back to the caller via the \fIovector\fP argument of the -matching function. (This applies only to the traditional matching functions; -the DFA matching functions do not support capturing.) -.P -Opening parentheses are counted from left to right (starting from 1) to obtain -numbers for the capturing subpatterns. For example, if the string "the red -king" is matched against the pattern -.sp - the ((red|white) (king|queen)) -.sp -the captured substrings are "red king", "red", and "king", and are numbered 1, -2, and 3, respectively. -.P -The fact that plain parentheses fulfil two functions is not always helpful. -There are often times when a grouping subpattern is required without a -capturing requirement. If an opening parenthesis is followed by a question mark -and a colon, the subpattern does not do any capturing, and is not counted when -computing the number of any subsequent capturing subpatterns. For example, if -the string "the white queen" is matched against the pattern -.sp - the ((?:red|white) (king|queen)) -.sp -the captured substrings are "white queen" and "queen", and are numbered 1 and -2. The maximum number of capturing subpatterns is 65535. -.P -As a convenient shorthand, if any option settings are required at the start of -a non-capturing subpattern, the option letters may appear between the "?" and -the ":". Thus the two patterns -.sp - (?i:saturday|sunday) - (?:(?i)saturday|sunday) -.sp -match exactly the same set of strings. Because alternative branches are tried -from left to right, and options are not reset until the end of the subpattern -is reached, an option setting in one branch does affect subsequent branches, so -the above patterns match "SUNDAY" as well as "Saturday". -. -. -.\" HTML <a name="dupsubpatternnumber"></a> -.SH "DUPLICATE SUBPATTERN NUMBERS" -.rs -.sp -Perl 5.10 introduced a feature whereby each alternative in a subpattern uses -the same numbers for its capturing parentheses. Such a subpattern starts with -(?| and is itself a non-capturing subpattern. For example, consider this -pattern: -.sp - (?|(Sat)ur|(Sun))day -.sp -Because the two alternatives are inside a (?| group, both sets of capturing -parentheses are numbered one. Thus, when the pattern matches, you can look -at captured substring number one, whichever alternative matched. This construct -is useful when you want to capture part, but not all, of one of a number of -alternatives. Inside a (?| group, parentheses are numbered as usual, but the -number is reset at the start of each branch. The numbers of any capturing -parentheses that follow the subpattern start after the highest number used in -any branch. The following example is taken from the Perl documentation. The -numbers underneath show in which buffer the captured content will be stored. -.sp - # before ---------------branch-reset----------- after - / ( a ) (?| x ( y ) z | (p (q) r) | (t) u (v) ) ( z ) /x - # 1 2 2 3 2 3 4 -.sp -A back reference to a numbered subpattern uses the most recent value that is -set for that number by any subpattern. The following pattern matches "abcabc" -or "defdef": -.sp - /(?|(abc)|(def))\e1/ -.sp -In contrast, a subroutine call to a numbered subpattern always refers to the -first one in the pattern with the given number. The following pattern matches -"abcabc" or "defabc": -.sp - /(?|(abc)|(def))(?1)/ -.sp -If a -.\" HTML <a href="#conditions"> -.\" </a> -condition test -.\" -for a subpattern's having matched refers to a non-unique number, the test is -true if any of the subpatterns of that number have matched. -.P -An alternative approach to using this "branch reset" feature is to use -duplicate named subpatterns, as described in the next section. -. -. -.SH "NAMED SUBPATTERNS" -.rs -.sp -Identifying capturing parentheses by number is simple, but it can be very hard -to keep track of the numbers in complicated regular expressions. Furthermore, -if an expression is modified, the numbers may change. To help with this -difficulty, PCRE supports the naming of subpatterns. This feature was not -added to Perl until release 5.10. Python had the feature earlier, and PCRE -introduced it at release 4.0, using the Python syntax. PCRE now supports both -the Perl and the Python syntax. Perl allows identically numbered subpatterns to -have different names, but PCRE does not. -.P -In PCRE, a subpattern can be named in one of three ways: (?<name>...) or -(?'name'...) as in Perl, or (?P<name>...) as in Python. References to capturing -parentheses from other parts of the pattern, such as -.\" HTML <a href="#backreferences"> -.\" </a> -back references, -.\" -.\" HTML <a href="#recursion"> -.\" </a> -recursion, -.\" -and -.\" HTML <a href="#conditions"> -.\" </a> -conditions, -.\" -can be made by name as well as by number. -.P -Names consist of up to 32 alphanumeric characters and underscores. Named -capturing parentheses are still allocated numbers as well as names, exactly as -if the names were not present. The PCRE API provides function calls for -extracting the name-to-number translation table from a compiled pattern. There -is also a convenience function for extracting a captured substring by name. -.P -By default, a name must be unique within a pattern, but it is possible to relax -this constraint by setting the PCRE_DUPNAMES option at compile time. (Duplicate -names are also always permitted for subpatterns with the same number, set up as -described in the previous section.) Duplicate names can be useful for patterns -where only one instance of the named parentheses can match. Suppose you want to -match the name of a weekday, either as a 3-letter abbreviation or as the full -name, and in both cases you want to extract the abbreviation. This pattern -(ignoring the line breaks) does the job: -.sp - (?<DN>Mon|Fri|Sun)(?:day)?| - (?<DN>Tue)(?:sday)?| - (?<DN>Wed)(?:nesday)?| - (?<DN>Thu)(?:rsday)?| - (?<DN>Sat)(?:urday)? -.sp -There are five capturing substrings, but only one is ever set after a match. -(An alternative way of solving this problem is to use a "branch reset" -subpattern, as described in the previous section.) -.P -The convenience function for extracting the data by name returns the substring -for the first (and in this example, the only) subpattern of that name that -matched. This saves searching to find which numbered subpattern it was. -.P -If you make a back reference to a non-unique named subpattern from elsewhere in -the pattern, the one that corresponds to the first occurrence of the name is -used. In the absence of duplicate numbers (see the previous section) this is -the one with the lowest number. If you use a named reference in a condition -test (see the -.\" -.\" HTML <a href="#conditions"> -.\" </a> -section about conditions -.\" -below), either to check whether a subpattern has matched, or to check for -recursion, all subpatterns with the same name are tested. If the condition is -true for any one of them, the overall condition is true. This is the same -behaviour as testing by number. For further details of the interfaces for -handling named subpatterns, see the -.\" HREF -\fBpcreapi\fP -.\" -documentation. -.P -\fBWarning:\fP You cannot use different names to distinguish between two -subpatterns with the same number because PCRE uses only the numbers when -matching. For this reason, an error is given at compile time if different names -are given to subpatterns with the same number. However, you can give the same -name to subpatterns with the same number, even when PCRE_DUPNAMES is not set. -. -. -.SH REPETITION -.rs -.sp -Repetition is specified by quantifiers, which can follow any of the following -items: -.sp - a literal data character - the dot metacharacter - the \eC escape sequence - the \eX escape sequence - the \eR escape sequence - an escape such as \ed or \epL that matches a single character - a character class - a back reference (see next section) - a parenthesized subpattern (including assertions) - a subroutine call to a subpattern (recursive or otherwise) -.sp -The general repetition quantifier specifies a minimum and maximum number of -permitted matches, by giving the two numbers in curly brackets (braces), -separated by a comma. The numbers must be less than 65536, and the first must -be less than or equal to the second. For example: -.sp - z{2,4} -.sp -matches "zz", "zzz", or "zzzz". A closing brace on its own is not a special -character. If the second number is omitted, but the comma is present, there is -no upper limit; if the second number and the comma are both omitted, the -quantifier specifies an exact number of required matches. Thus -.sp - [aeiou]{3,} -.sp -matches at least 3 successive vowels, but may match many more, while -.sp - \ed{8} -.sp -matches exactly 8 digits. An opening curly bracket that appears in a position -where a quantifier is not allowed, or one that does not match the syntax of a -quantifier, is taken as a literal character. For example, {,6} is not a -quantifier, but a literal string of four characters. -.P -In UTF modes, quantifiers apply to characters rather than to individual data -units. Thus, for example, \ex{100}{2} matches two characters, each of -which is represented by a two-byte sequence in a UTF-8 string. Similarly, -\eX{3} matches three Unicode extended sequences, each of which may be several -data units long (and they may be of different lengths). -.P -The quantifier {0} is permitted, causing the expression to behave as if the -previous item and the quantifier were not present. This may be useful for -subpatterns that are referenced as -.\" HTML <a href="#subpatternsassubroutines"> -.\" </a> -subroutines -.\" -from elsewhere in the pattern (but see also the section entitled -.\" HTML <a href="#subdefine"> -.\" </a> -"Defining subpatterns for use by reference only" -.\" -below). Items other than subpatterns that have a {0} quantifier are omitted -from the compiled pattern. -.P -For convenience, the three most common quantifiers have single-character -abbreviations: -.sp - * is equivalent to {0,} - + is equivalent to {1,} - ? is equivalent to {0,1} -.sp -It is possible to construct infinite loops by following a subpattern that can -match no characters with a quantifier that has no upper limit, for example: -.sp - (a?)* -.sp -Earlier versions of Perl and PCRE used to give an error at compile time for -such patterns. However, because there are cases where this can be useful, such -patterns are now accepted, but if any repetition of the subpattern does in fact -match no characters, the loop is forcibly broken. -.P -By default, the quantifiers are "greedy", that is, they match as much as -possible (up to the maximum number of permitted times), without causing the -rest of the pattern to fail. The classic example of where this gives problems -is in trying to match comments in C programs. These appear between /* and */ -and within the comment, individual * and / characters may appear. An attempt to -match C comments by applying the pattern -.sp - /\e*.*\e*/ -.sp -to the string -.sp - /* first comment */ not comment /* second comment */ -.sp -fails, because it matches the entire string owing to the greediness of the .* -item. -.P -However, if a quantifier is followed by a question mark, it ceases to be -greedy, and instead matches the minimum number of times possible, so the -pattern -.sp - /\e*.*?\e*/ -.sp -does the right thing with the C comments. The meaning of the various -quantifiers is not otherwise changed, just the preferred number of matches. -Do not confuse this use of question mark with its use as a quantifier in its -own right. Because it has two uses, it can sometimes appear doubled, as in -.sp - \ed??\ed -.sp -which matches one digit by preference, but can match two if that is the only -way the rest of the pattern matches. -.P -If the PCRE_UNGREEDY option is set (an option that is not available in Perl), -the quantifiers are not greedy by default, but individual ones can be made -greedy by following them with a question mark. In other words, it inverts the -default behaviour. -.P -When a parenthesized subpattern is quantified with a minimum repeat count that -is greater than 1 or with a limited maximum, more memory is required for the -compiled pattern, in proportion to the size of the minimum or maximum. -.P -If a pattern starts with .* or .{0,} and the PCRE_DOTALL option (equivalent -to Perl's /s) is set, thus allowing the dot to match newlines, the pattern is -implicitly anchored, because whatever follows will be tried against every -character position in the subject string, so there is no point in retrying the -overall match at any position after the first. PCRE normally treats such a -pattern as though it were preceded by \eA. -.P -In cases where it is known that the subject string contains no newlines, it is -worth setting PCRE_DOTALL in order to obtain this optimization, or -alternatively using ^ to indicate anchoring explicitly. -.P -However, there is one situation where the optimization cannot be used. When .* -is inside capturing parentheses that are the subject of a back reference -elsewhere in the pattern, a match at the start may fail where a later one -succeeds. Consider, for example: -.sp - (.*)abc\e1 -.sp -If the subject is "xyz123abc123" the match point is the fourth character. For -this reason, such a pattern is not implicitly anchored. -.P -When a capturing subpattern is repeated, the value captured is the substring -that matched the final iteration. For example, after -.sp - (tweedle[dume]{3}\es*)+ -.sp -has matched "tweedledum tweedledee" the value of the captured substring is -"tweedledee". However, if there are nested capturing subpatterns, the -corresponding captured values may have been set in previous iterations. For -example, after -.sp - /(a|(b))+/ -.sp -matches "aba" the value of the second captured substring is "b". -. -. -.\" HTML <a name="atomicgroup"></a> -.SH "ATOMIC GROUPING AND POSSESSIVE QUANTIFIERS" -.rs -.sp -With both maximizing ("greedy") and minimizing ("ungreedy" or "lazy") -repetition, failure of what follows normally causes the repeated item to be -re-evaluated to see if a different number of repeats allows the rest of the -pattern to match. Sometimes it is useful to prevent this, either to change the -nature of the match, or to cause it fail earlier than it otherwise might, when -the author of the pattern knows there is no point in carrying on. -.P -Consider, for example, the pattern \ed+foo when applied to the subject line -.sp - 123456bar -.sp -After matching all 6 digits and then failing to match "foo", the normal -action of the matcher is to try again with only 5 digits matching the \ed+ -item, and then with 4, and so on, before ultimately failing. "Atomic grouping" -(a term taken from Jeffrey Friedl's book) provides the means for specifying -that once a subpattern has matched, it is not to be re-evaluated in this way. -.P -If we use atomic grouping for the previous example, the matcher gives up -immediately on failing to match "foo" the first time. The notation is a kind of -special parenthesis, starting with (?> as in this example: -.sp - (?>\ed+)foo -.sp -This kind of parenthesis "locks up" the part of the pattern it contains once -it has matched, and a failure further into the pattern is prevented from -backtracking into it. Backtracking past it to previous items, however, works as -normal. -.P -An alternative description is that a subpattern of this type matches the string -of characters that an identical standalone pattern would match, if anchored at -the current point in the subject string. -.P -Atomic grouping subpatterns are not capturing subpatterns. Simple cases such as -the above example can be thought of as a maximizing repeat that must swallow -everything it can. So, while both \ed+ and \ed+? are prepared to adjust the -number of digits they match in order to make the rest of the pattern match, -(?>\ed+) can only match an entire sequence of digits. -.P -Atomic groups in general can of course contain arbitrarily complicated -subpatterns, and can be nested. However, when the subpattern for an atomic -group is just a single repeated item, as in the example above, a simpler -notation, called a "possessive quantifier" can be used. This consists of an -additional + character following a quantifier. Using this notation, the -previous example can be rewritten as -.sp - \ed++foo -.sp -Note that a possessive quantifier can be used with an entire group, for -example: -.sp - (abc|xyz){2,3}+ -.sp -Possessive quantifiers are always greedy; the setting of the PCRE_UNGREEDY -option is ignored. They are a convenient notation for the simpler forms of -atomic group. However, there is no difference in the meaning of a possessive -quantifier and the equivalent atomic group, though there may be a performance -difference; possessive quantifiers should be slightly faster. -.P -The possessive quantifier syntax is an extension to the Perl 5.8 syntax. -Jeffrey Friedl originated the idea (and the name) in the first edition of his -book. Mike McCloskey liked it, so implemented it when he built Sun's Java -package, and PCRE copied it from there. It ultimately found its way into Perl -at release 5.10. -.P -PCRE has an optimization that automatically "possessifies" certain simple -pattern constructs. For example, the sequence A+B is treated as A++B because -there is no point in backtracking into a sequence of A's when B must follow. -.P -When a pattern contains an unlimited repeat inside a subpattern that can itself -be repeated an unlimited number of times, the use of an atomic group is the -only way to avoid some failing matches taking a very long time indeed. The -pattern -.sp - (\eD+|<\ed+>)*[!?] -.sp -matches an unlimited number of substrings that either consist of non-digits, or -digits enclosed in <>, followed by either ! or ?. When it matches, it runs -quickly. However, if it is applied to -.sp - aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa -.sp -it takes a long time before reporting failure. This is because the string can -be divided between the internal \eD+ repeat and the external * repeat in a -large number of ways, and all have to be tried. (The example uses [!?] rather -than a single character at the end, because both PCRE and Perl have an -optimization that allows for fast failure when a single character is used. They -remember the last single character that is required for a match, and fail early -if it is not present in the string.) If the pattern is changed so that it uses -an atomic group, like this: -.sp - ((?>\eD+)|<\ed+>)*[!?] -.sp -sequences of non-digits cannot be broken, and failure happens quickly. -. -. -.\" HTML <a name="backreferences"></a> -.SH "BACK REFERENCES" -.rs -.sp -Outside a character class, a backslash followed by a digit greater than 0 (and -possibly further digits) is a back reference to a capturing subpattern earlier -(that is, to its left) in the pattern, provided there have been that many -previous capturing left parentheses. -.P -However, if the decimal number following the backslash is less than 10, it is -always taken as a back reference, and causes an error only if there are not -that many capturing left parentheses in the entire pattern. In other words, the -parentheses that are referenced need not be to the left of the reference for -numbers less than 10. A "forward back reference" of this type can make sense -when a repetition is involved and the subpattern to the right has participated -in an earlier iteration. -.P -It is not possible to have a numerical "forward back reference" to a subpattern -whose number is 10 or more using this syntax because a sequence such as \e50 is -interpreted as a character defined in octal. See the subsection entitled -"Non-printing characters" -.\" HTML <a href="#digitsafterbackslash"> -.\" </a> -above -.\" -for further details of the handling of digits following a backslash. There is -no such problem when named parentheses are used. A back reference to any -subpattern is possible using named parentheses (see below). -.P -Another way of avoiding the ambiguity inherent in the use of digits following a -backslash is to use the \eg escape sequence. This escape must be followed by an -unsigned number or a negative number, optionally enclosed in braces. These -examples are all identical: -.sp - (ring), \e1 - (ring), \eg1 - (ring), \eg{1} -.sp -An unsigned number specifies an absolute reference without the ambiguity that -is present in the older syntax. It is also useful when literal digits follow -the reference. A negative number is a relative reference. Consider this -example: -.sp - (abc(def)ghi)\eg{-1} -.sp -The sequence \eg{-1} is a reference to the most recently started capturing -subpattern before \eg, that is, is it equivalent to \e2 in this example. -Similarly, \eg{-2} would be equivalent to \e1. The use of relative references -can be helpful in long patterns, and also in patterns that are created by -joining together fragments that contain references within themselves. -.P -A back reference matches whatever actually matched the capturing subpattern in -the current subject string, rather than anything matching the subpattern -itself (see -.\" HTML <a href="#subpatternsassubroutines"> -.\" </a> -"Subpatterns as subroutines" -.\" -below for a way of doing that). So the pattern -.sp - (sens|respons)e and \e1ibility -.sp -matches "sense and sensibility" and "response and responsibility", but not -"sense and responsibility". If caseful matching is in force at the time of the -back reference, the case of letters is relevant. For example, -.sp - ((?i)rah)\es+\e1 -.sp -matches "rah rah" and "RAH RAH", but not "RAH rah", even though the original -capturing subpattern is matched caselessly. -.P -There are several different ways of writing back references to named -subpatterns. The .NET syntax \ek{name} and the Perl syntax \ek<name> or -\ek'name' are supported, as is the Python syntax (?P=name). Perl 5.10's unified -back reference syntax, in which \eg can be used for both numeric and named -references, is also supported. We could rewrite the above example in any of -the following ways: -.sp - (?<p1>(?i)rah)\es+\ek<p1> - (?'p1'(?i)rah)\es+\ek{p1} - (?P<p1>(?i)rah)\es+(?P=p1) - (?<p1>(?i)rah)\es+\eg{p1} -.sp -A subpattern that is referenced by name may appear in the pattern before or -after the reference. -.P -There may be more than one back reference to the same subpattern. If a -subpattern has not actually been used in a particular match, any back -references to it always fail by default. For example, the pattern -.sp - (a|(bc))\e2 -.sp -always fails if it starts to match "a" rather than "bc". However, if the -PCRE_JAVASCRIPT_COMPAT option is set at compile time, a back reference to an -unset value matches an empty string. -.P -Because there may be many capturing parentheses in a pattern, all digits -following a backslash are taken as part of a potential back reference number. -If the pattern continues with a digit character, some delimiter must be used to -terminate the back reference. If the PCRE_EXTENDED option is set, this can be -white space. Otherwise, the \eg{ syntax or an empty comment (see -.\" HTML <a href="#comments"> -.\" </a> -"Comments" -.\" -below) can be used. -. -.SS "Recursive back references" -.rs -.sp -A back reference that occurs inside the parentheses to which it refers fails -when the subpattern is first used, so, for example, (a\e1) never matches. -However, such references can be useful inside repeated subpatterns. For -example, the pattern -.sp - (a|b\e1)+ -.sp -matches any number of "a"s and also "aba", "ababbaa" etc. At each iteration of -the subpattern, the back reference matches the character string corresponding -to the previous iteration. In order for this to work, the pattern must be such -that the first iteration does not need to match the back reference. This can be -done using alternation, as in the example above, or by a quantifier with a -minimum of zero. -.P -Back references of this type cause the group that they reference to be treated -as an -.\" HTML <a href="#atomicgroup"> -.\" </a> -atomic group. -.\" -Once the whole group has been matched, a subsequent matching failure cannot -cause backtracking into the middle of the group. -. -. -.\" HTML <a name="bigassertions"></a> -.SH ASSERTIONS -.rs -.sp -An assertion is a test on the characters following or preceding the current -matching point that does not actually consume any characters. The simple -assertions coded as \eb, \eB, \eA, \eG, \eZ, \ez, ^ and $ are described -.\" HTML <a href="#smallassertions"> -.\" </a> -above. -.\" -.P -More complicated assertions are coded as subpatterns. There are two kinds: -those that look ahead of the current position in the subject string, and those -that look behind it. An assertion subpattern is matched in the normal way, -except that it does not cause the current matching position to be changed. -.P -Assertion subpatterns are not capturing subpatterns. If such an assertion -contains capturing subpatterns within it, these are counted for the purposes of -numbering the capturing subpatterns in the whole pattern. However, substring -capturing is carried out only for positive assertions, because it does not make -sense for negative assertions. -.P -For compatibility with Perl, assertion subpatterns may be repeated; though -it makes no sense to assert the same thing several times, the side effect of -capturing parentheses may occasionally be useful. In practice, there only three -cases: -.sp -(1) If the quantifier is {0}, the assertion is never obeyed during matching. -However, it may contain internal capturing parenthesized groups that are called -from elsewhere via the -.\" HTML <a href="#subpatternsassubroutines"> -.\" </a> -subroutine mechanism. -.\" -.sp -(2) If quantifier is {0,n} where n is greater than zero, it is treated as if it -were {0,1}. At run time, the rest of the pattern match is tried with and -without the assertion, the order depending on the greediness of the quantifier. -.sp -(3) If the minimum repetition is greater than zero, the quantifier is ignored. -The assertion is obeyed just once when encountered during matching. -. -. -.SS "Lookahead assertions" -.rs -.sp -Lookahead assertions start with (?= for positive assertions and (?! for -negative assertions. For example, -.sp - \ew+(?=;) -.sp -matches a word followed by a semicolon, but does not include the semicolon in -the match, and -.sp - foo(?!bar) -.sp -matches any occurrence of "foo" that is not followed by "bar". Note that the -apparently similar pattern -.sp - (?!foo)bar -.sp -does not find an occurrence of "bar" that is preceded by something other than -"foo"; it finds any occurrence of "bar" whatsoever, because the assertion -(?!foo) is always true when the next three characters are "bar". A -lookbehind assertion is needed to achieve the other effect. -.P -If you want to force a matching failure at some point in a pattern, the most -convenient way to do it is with (?!) because an empty string always matches, so -an assertion that requires there not to be an empty string must always fail. -The backtracking control verb (*FAIL) or (*F) is a synonym for (?!). -. -. -.\" HTML <a name="lookbehind"></a> -.SS "Lookbehind assertions" -.rs -.sp -Lookbehind assertions start with (?<= for positive assertions and (?<! for -negative assertions. For example, -.sp - (?<!foo)bar -.sp -does find an occurrence of "bar" that is not preceded by "foo". The contents of -a lookbehind assertion are restricted such that all the strings it matches must -have a fixed length. However, if there are several top-level alternatives, they -do not all have to have the same fixed length. Thus -.sp - (?<=bullock|donkey) -.sp -is permitted, but -.sp - (?<!dogs?|cats?) -.sp -causes an error at compile time. Branches that match different length strings -are permitted only at the top level of a lookbehind assertion. This is an -extension compared with Perl, which requires all branches to match the same -length of string. An assertion such as -.sp - (?<=ab(c|de)) -.sp -is not permitted, because its single top-level branch can match two different -lengths, but it is acceptable to PCRE if rewritten to use two top-level -branches: -.sp - (?<=abc|abde) -.sp -In some cases, the escape sequence \eK -.\" HTML <a href="#resetmatchstart"> -.\" </a> -(see above) -.\" -can be used instead of a lookbehind assertion to get round the fixed-length -restriction. -.P -The implementation of lookbehind assertions is, for each alternative, to -temporarily move the current position back by the fixed length and then try to -match. If there are insufficient characters before the current position, the -assertion fails. -.P -In a UTF mode, PCRE does not allow the \eC escape (which matches a single data -unit even in a UTF mode) to appear in lookbehind assertions, because it makes -it impossible to calculate the length of the lookbehind. The \eX and \eR -escapes, which can match different numbers of data units, are also not -permitted. -.P -.\" HTML <a href="#subpatternsassubroutines"> -.\" </a> -"Subroutine" -.\" -calls (see below) such as (?2) or (?&X) are permitted in lookbehinds, as long -as the subpattern matches a fixed-length string. -.\" HTML <a href="#recursion"> -.\" </a> -Recursion, -.\" -however, is not supported. -.P -Possessive quantifiers can be used in conjunction with lookbehind assertions to -specify efficient matching of fixed-length strings at the end of subject -strings. Consider a simple pattern such as -.sp - abcd$ -.sp -when applied to a long string that does not match. Because matching proceeds -from left to right, PCRE will look for each "a" in the subject and then see if -what follows matches the rest of the pattern. If the pattern is specified as -.sp - ^.*abcd$ -.sp -the initial .* matches the entire string at first, but when this fails (because -there is no following "a"), it backtracks to match all but the last character, -then all but the last two characters, and so on. Once again the search for "a" -covers the entire string, from right to left, so we are no better off. However, -if the pattern is written as -.sp - ^.*+(?<=abcd) -.sp -there can be no backtracking for the .*+ item; it can match only the entire -string. The subsequent lookbehind assertion does a single test on the last four -characters. If it fails, the match fails immediately. For long strings, this -approach makes a significant difference to the processing time. -. -. -.SS "Using multiple assertions" -.rs -.sp -Several assertions (of any sort) may occur in succession. For example, -.sp - (?<=\ed{3})(?<!999)foo -.sp -matches "foo" preceded by three digits that are not "999". Notice that each of -the assertions is applied independently at the same point in the subject -string. First there is a check that the previous three characters are all -digits, and then there is a check that the same three characters are not "999". -This pattern does \fInot\fP match "foo" preceded by six characters, the first -of which are digits and the last three of which are not "999". For example, it -doesn't match "123abcfoo". A pattern to do that is -.sp - (?<=\ed{3}...)(?<!999)foo -.sp -This time the first assertion looks at the preceding six characters, checking -that the first three are digits, and then the second assertion checks that the -preceding three characters are not "999". -.P -Assertions can be nested in any combination. For example, -.sp - (?<=(?<!foo)bar)baz -.sp -matches an occurrence of "baz" that is preceded by "bar" which in turn is not -preceded by "foo", while -.sp - (?<=\ed{3}(?!999)...)foo -.sp -is another pattern that matches "foo" preceded by three digits and any three -characters that are not "999". -. -. -.\" HTML <a name="conditions"></a> -.SH "CONDITIONAL SUBPATTERNS" -.rs -.sp -It is possible to cause the matching process to obey a subpattern -conditionally or to choose between two alternative subpatterns, depending on -the result of an assertion, or whether a specific capturing subpattern has -already been matched. The two possible forms of conditional subpattern are: -.sp - (?(condition)yes-pattern) - (?(condition)yes-pattern|no-pattern) -.sp -If the condition is satisfied, the yes-pattern is used; otherwise the -no-pattern (if present) is used. If there are more than two alternatives in the -subpattern, a compile-time error occurs. Each of the two alternatives may -itself contain nested subpatterns of any form, including conditional -subpatterns; the restriction to two alternatives applies only at the level of -the condition. This pattern fragment is an example where the alternatives are -complex: -.sp - (?(1) (A|B|C) | (D | (?(2)E|F) | E) ) -.sp -.P -There are four kinds of condition: references to subpatterns, references to -recursion, a pseudo-condition called DEFINE, and assertions. -. -.SS "Checking for a used subpattern by number" -.rs -.sp -If the text between the parentheses consists of a sequence of digits, the -condition is true if a capturing subpattern of that number has previously -matched. If there is more than one capturing subpattern with the same number -(see the earlier -.\" -.\" HTML <a href="#recursion"> -.\" </a> -section about duplicate subpattern numbers), -.\" -the condition is true if any of them have matched. An alternative notation is -to precede the digits with a plus or minus sign. In this case, the subpattern -number is relative rather than absolute. The most recently opened parentheses -can be referenced by (?(-1), the next most recent by (?(-2), and so on. Inside -loops it can also make sense to refer to subsequent groups. The next -parentheses to be opened can be referenced as (?(+1), and so on. (The value -zero in any of these forms is not used; it provokes a compile-time error.) -.P -Consider the following pattern, which contains non-significant white space to -make it more readable (assume the PCRE_EXTENDED option) and to divide it into -three parts for ease of discussion: -.sp - ( \e( )? [^()]+ (?(1) \e) ) -.sp -The first part matches an optional opening parenthesis, and if that -character is present, sets it as the first captured substring. The second part -matches one or more characters that are not parentheses. The third part is a -conditional subpattern that tests whether or not the first set of parentheses -matched. If they did, that is, if subject started with an opening parenthesis, -the condition is true, and so the yes-pattern is executed and a closing -parenthesis is required. Otherwise, since no-pattern is not present, the -subpattern matches nothing. In other words, this pattern matches a sequence of -non-parentheses, optionally enclosed in parentheses. -.P -If you were embedding this pattern in a larger one, you could use a relative -reference: -.sp - ...other stuff... ( \e( )? [^()]+ (?(-1) \e) ) ... -.sp -This makes the fragment independent of the parentheses in the larger pattern. -. -.SS "Checking for a used subpattern by name" -.rs -.sp -Perl uses the syntax (?(<name>)...) or (?('name')...) to test for a used -subpattern by name. For compatibility with earlier versions of PCRE, which had -this facility before Perl, the syntax (?(name)...) is also recognized. However, -there is a possible ambiguity with this syntax, because subpattern names may -consist entirely of digits. PCRE looks first for a named subpattern; if it -cannot find one and the name consists entirely of digits, PCRE looks for a -subpattern of that number, which must be greater than zero. Using subpattern -names that consist entirely of digits is not recommended. -.P -Rewriting the above example to use a named subpattern gives this: -.sp - (?<OPEN> \e( )? [^()]+ (?(<OPEN>) \e) ) -.sp -If the name used in a condition of this kind is a duplicate, the test is -applied to all subpatterns of the same name, and is true if any one of them has -matched. -. -.SS "Checking for pattern recursion" -.rs -.sp -If the condition is the string (R), and there is no subpattern with the name R, -the condition is true if a recursive call to the whole pattern or any -subpattern has been made. If digits or a name preceded by ampersand follow the -letter R, for example: -.sp - (?(R3)...) or (?(R&name)...) -.sp -the condition is true if the most recent recursion is into a subpattern whose -number or name is given. This condition does not check the entire recursion -stack. If the name used in a condition of this kind is a duplicate, the test is -applied to all subpatterns of the same name, and is true if any one of them is -the most recent recursion. -.P -At "top level", all these recursion test conditions are false. -.\" HTML <a href="#recursion"> -.\" </a> -The syntax for recursive patterns -.\" -is described below. -. -.\" HTML <a name="subdefine"></a> -.SS "Defining subpatterns for use by reference only" -.rs -.sp -If the condition is the string (DEFINE), and there is no subpattern with the -name DEFINE, the condition is always false. In this case, there may be only one -alternative in the subpattern. It is always skipped if control reaches this -point in the pattern; the idea of DEFINE is that it can be used to define -subroutines that can be referenced from elsewhere. (The use of -.\" HTML <a href="#subpatternsassubroutines"> -.\" </a> -subroutines -.\" -is described below.) For example, a pattern to match an IPv4 address such as -"192.168.23.245" could be written like this (ignore white space and line -breaks): -.sp - (?(DEFINE) (?<byte> 2[0-4]\ed | 25[0-5] | 1\ed\ed | [1-9]?\ed) ) - \eb (?&byte) (\e.(?&byte)){3} \eb -.sp -The first part of the pattern is a DEFINE group inside which a another group -named "byte" is defined. This matches an individual component of an IPv4 -address (a number less than 256). When matching takes place, this part of the -pattern is skipped because DEFINE acts like a false condition. The rest of the -pattern uses references to the named group to match the four dot-separated -components of an IPv4 address, insisting on a word boundary at each end. -. -.SS "Assertion conditions" -.rs -.sp -If the condition is not in any of the above formats, it must be an assertion. -This may be a positive or negative lookahead or lookbehind assertion. Consider -this pattern, again containing non-significant white space, and with the two -alternatives on the second line: -.sp - (?(?=[^a-z]*[a-z]) - \ed{2}-[a-z]{3}-\ed{2} | \ed{2}-\ed{2}-\ed{2} ) -.sp -The condition is a positive lookahead assertion that matches an optional -sequence of non-letters followed by a letter. In other words, it tests for the -presence of at least one letter in the subject. If a letter is found, the -subject is matched against the first alternative; otherwise it is matched -against the second. This pattern matches strings in one of the two forms -dd-aaa-dd or dd-dd-dd, where aaa are letters and dd are digits. -. -. -.\" HTML <a name="comments"></a> -.SH COMMENTS -.rs -.sp -There are two ways of including comments in patterns that are processed by -PCRE. In both cases, the start of the comment must not be in a character class, -nor in the middle of any other sequence of related characters such as (?: or a -subpattern name or number. The characters that make up a comment play no part -in the pattern matching. -.P -The sequence (?# marks the start of a comment that continues up to the next -closing parenthesis. Nested parentheses are not permitted. If the PCRE_EXTENDED -option is set, an unescaped # character also introduces a comment, which in -this case continues to immediately after the next newline character or -character sequence in the pattern. Which characters are interpreted as newlines -is controlled by the options passed to a compiling function or by a special -sequence at the start of the pattern, as described in the section entitled -.\" HTML <a href="#newlines"> -.\" </a> -"Newline conventions" -.\" -above. Note that the end of this type of comment is a literal newline sequence -in the pattern; escape sequences that happen to represent a newline do not -count. For example, consider this pattern when PCRE_EXTENDED is set, and the -default newline convention is in force: -.sp - abc #comment \en still comment -.sp -On encountering the # character, \fBpcre_compile()\fP skips along, looking for -a newline in the pattern. The sequence \en is still literal at this stage, so -it does not terminate the comment. Only an actual character with the code value -0x0a (the default newline) does so. -. -. -.\" HTML <a name="recursion"></a> -.SH "RECURSIVE PATTERNS" -.rs -.sp -Consider the problem of matching a string in parentheses, allowing for -unlimited nested parentheses. Without the use of recursion, the best that can -be done is to use a pattern that matches up to some fixed depth of nesting. It -is not possible to handle an arbitrary nesting depth. -.P -For some time, Perl has provided a facility that allows regular expressions to -recurse (amongst other things). It does this by interpolating Perl code in the -expression at run time, and the code can refer to the expression itself. A Perl -pattern using code interpolation to solve the parentheses problem can be -created like this: -.sp - $re = qr{\e( (?: (?>[^()]+) | (?p{$re}) )* \e)}x; -.sp -The (?p{...}) item interpolates Perl code at run time, and in this case refers -recursively to the pattern in which it appears. -.P -Obviously, PCRE cannot support the interpolation of Perl code. Instead, it -supports special syntax for recursion of the entire pattern, and also for -individual subpattern recursion. After its introduction in PCRE and Python, -this kind of recursion was subsequently introduced into Perl at release 5.10. -.P -A special item that consists of (? followed by a number greater than zero and a -closing parenthesis is a recursive subroutine call of the subpattern of the -given number, provided that it occurs inside that subpattern. (If not, it is a -.\" HTML <a href="#subpatternsassubroutines"> -.\" </a> -non-recursive subroutine -.\" -call, which is described in the next section.) The special item (?R) or (?0) is -a recursive call of the entire regular expression. -.P -This PCRE pattern solves the nested parentheses problem (assume the -PCRE_EXTENDED option is set so that white space is ignored): -.sp - \e( ( [^()]++ | (?R) )* \e) -.sp -First it matches an opening parenthesis. Then it matches any number of -substrings which can either be a sequence of non-parentheses, or a recursive -match of the pattern itself (that is, a correctly parenthesized substring). -Finally there is a closing parenthesis. Note the use of a possessive quantifier -to avoid backtracking into sequences of non-parentheses. -.P -If this were part of a larger pattern, you would not want to recurse the entire -pattern, so instead you could use this: -.sp - ( \e( ( [^()]++ | (?1) )* \e) ) -.sp -We have put the pattern into parentheses, and caused the recursion to refer to -them instead of the whole pattern. -.P -In a larger pattern, keeping track of parenthesis numbers can be tricky. This -is made easier by the use of relative references. Instead of (?1) in the -pattern above you can write (?-2) to refer to the second most recently opened -parentheses preceding the recursion. In other words, a negative number counts -capturing parentheses leftwards from the point at which it is encountered. -.P -It is also possible to refer to subsequently opened parentheses, by writing -references such as (?+2). However, these cannot be recursive because the -reference is not inside the parentheses that are referenced. They are always -.\" HTML <a href="#subpatternsassubroutines"> -.\" </a> -non-recursive subroutine -.\" -calls, as described in the next section. -.P -An alternative approach is to use named parentheses instead. The Perl syntax -for this is (?&name); PCRE's earlier syntax (?P>name) is also supported. We -could rewrite the above example as follows: -.sp - (?<pn> \e( ( [^()]++ | (?&pn) )* \e) ) -.sp -If there is more than one subpattern with the same name, the earliest one is -used. -.P -This particular example pattern that we have been looking at contains nested -unlimited repeats, and so the use of a possessive quantifier for matching -strings of non-parentheses is important when applying the pattern to strings -that do not match. For example, when this pattern is applied to -.sp - (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa() -.sp -it yields "no match" quickly. However, if a possessive quantifier is not used, -the match runs for a very long time indeed because there are so many different -ways the + and * repeats can carve up the subject, and all have to be tested -before failure can be reported. -.P -At the end of a match, the values of capturing parentheses are those from -the outermost level. If you want to obtain intermediate values, a callout -function can be used (see below and the -.\" HREF -\fBpcrecallout\fP -.\" -documentation). If the pattern above is matched against -.sp - (ab(cd)ef) -.sp -the value for the inner capturing parentheses (numbered 2) is "ef", which is -the last value taken on at the top level. If a capturing subpattern is not -matched at the top level, its final captured value is unset, even if it was -(temporarily) set at a deeper level during the matching process. -.P -If there are more than 15 capturing parentheses in a pattern, PCRE has to -obtain extra memory to store data during a recursion, which it does by using -\fBpcre_malloc\fP, freeing it via \fBpcre_free\fP afterwards. If no memory can -be obtained, the match fails with the PCRE_ERROR_NOMEMORY error. -.P -Do not confuse the (?R) item with the condition (R), which tests for recursion. -Consider this pattern, which matches text in angle brackets, allowing for -arbitrary nesting. Only digits are allowed in nested brackets (that is, when -recursing), whereas any characters are permitted at the outer level. -.sp - < (?: (?(R) \ed++ | [^<>]*+) | (?R)) * > -.sp -In this pattern, (?(R) is the start of a conditional subpattern, with two -different alternatives for the recursive and non-recursive cases. The (?R) item -is the actual recursive call. -. -. -.\" HTML <a name="recursiondifference"></a> -.SS "Differences in recursion processing between PCRE and Perl" -.rs -.sp -Recursion processing in PCRE differs from Perl in two important ways. In PCRE -(like Python, but unlike Perl), a recursive subpattern call is always treated -as an atomic group. That is, once it has matched some of the subject string, it -is never re-entered, even if it contains untried alternatives and there is a -subsequent matching failure. This can be illustrated by the following pattern, -which purports to match a palindromic string that contains an odd number of -characters (for example, "a", "aba", "abcba", "abcdcba"): -.sp - ^(.|(.)(?1)\e2)$ -.sp -The idea is that it either matches a single character, or two identical -characters surrounding a sub-palindrome. In Perl, this pattern works; in PCRE -it does not if the pattern is longer than three characters. Consider the -subject string "abcba": -.P -At the top level, the first character is matched, but as it is not at the end -of the string, the first alternative fails; the second alternative is taken -and the recursion kicks in. The recursive call to subpattern 1 successfully -matches the next character ("b"). (Note that the beginning and end of line -tests are not part of the recursion). -.P -Back at the top level, the next character ("c") is compared with what -subpattern 2 matched, which was "a". This fails. Because the recursion is -treated as an atomic group, there are now no backtracking points, and so the -entire match fails. (Perl is able, at this point, to re-enter the recursion and -try the second alternative.) However, if the pattern is written with the -alternatives in the other order, things are different: -.sp - ^((.)(?1)\e2|.)$ -.sp -This time, the recursing alternative is tried first, and continues to recurse -until it runs out of characters, at which point the recursion fails. But this -time we do have another alternative to try at the higher level. That is the big -difference: in the previous case the remaining alternative is at a deeper -recursion level, which PCRE cannot use. -.P -To change the pattern so that it matches all palindromic strings, not just -those with an odd number of characters, it is tempting to change the pattern to -this: -.sp - ^((.)(?1)\e2|.?)$ -.sp -Again, this works in Perl, but not in PCRE, and for the same reason. When a -deeper recursion has matched a single character, it cannot be entered again in -order to match an empty string. The solution is to separate the two cases, and -write out the odd and even cases as alternatives at the higher level: -.sp - ^(?:((.)(?1)\e2|)|((.)(?3)\e4|.)) -.sp -If you want to match typical palindromic phrases, the pattern has to ignore all -non-word characters, which can be done like this: -.sp - ^\eW*+(?:((.)\eW*+(?1)\eW*+\e2|)|((.)\eW*+(?3)\eW*+\e4|\eW*+.\eW*+))\eW*+$ -.sp -If run with the PCRE_CASELESS option, this pattern matches phrases such as "A -man, a plan, a canal: Panama!" and it works well in both PCRE and Perl. Note -the use of the possessive quantifier *+ to avoid backtracking into sequences of -non-word characters. Without this, PCRE takes a great deal longer (ten times or -more) to match typical phrases, and Perl takes so long that you think it has -gone into a loop. -.P -\fBWARNING\fP: The palindrome-matching patterns above work only if the subject -string does not start with a palindrome that is shorter than the entire string. -For example, although "abcba" is correctly matched, if the subject is "ababa", -PCRE finds the palindrome "aba" at the start, then fails at top level because -the end of the string does not follow. Once again, it cannot jump back into the -recursion to try other alternatives, so the entire match fails. -.P -The second way in which PCRE and Perl differ in their recursion processing is -in the handling of captured values. In Perl, when a subpattern is called -recursively or as a subpattern (see the next section), it has no access to any -values that were captured outside the recursion, whereas in PCRE these values -can be referenced. Consider this pattern: -.sp - ^(.)(\e1|a(?2)) -.sp -In PCRE, this pattern matches "bab". The first capturing parentheses match "b", -then in the second group, when the back reference \e1 fails to match "b", the -second alternative matches "a" and then recurses. In the recursion, \e1 does -now match "b" and so the whole match succeeds. In Perl, the pattern fails to -match because inside the recursive call \e1 cannot access the externally set -value. -. -. -.\" HTML <a name="subpatternsassubroutines"></a> -.SH "SUBPATTERNS AS SUBROUTINES" -.rs -.sp -If the syntax for a recursive subpattern call (either by number or by -name) is used outside the parentheses to which it refers, it operates like a -subroutine in a programming language. The called subpattern may be defined -before or after the reference. A numbered reference can be absolute or -relative, as in these examples: -.sp - (...(absolute)...)...(?2)... - (...(relative)...)...(?-1)... - (...(?+1)...(relative)... -.sp -An earlier example pointed out that the pattern -.sp - (sens|respons)e and \e1ibility -.sp -matches "sense and sensibility" and "response and responsibility", but not -"sense and responsibility". If instead the pattern -.sp - (sens|respons)e and (?1)ibility -.sp -is used, it does match "sense and responsibility" as well as the other two -strings. Another example is given in the discussion of DEFINE above. -.P -All subroutine calls, whether recursive or not, are always treated as atomic -groups. That is, once a subroutine has matched some of the subject string, it -is never re-entered, even if it contains untried alternatives and there is a -subsequent matching failure. Any capturing parentheses that are set during the -subroutine call revert to their previous values afterwards. -.P -Processing options such as case-independence are fixed when a subpattern is -defined, so if it is used as a subroutine, such options cannot be changed for -different calls. For example, consider this pattern: -.sp - (abc)(?i:(?-1)) -.sp -It matches "abcabc". It does not match "abcABC" because the change of -processing option does not affect the called subpattern. -. -. -.\" HTML <a name="onigurumasubroutines"></a> -.SH "ONIGURUMA SUBROUTINE SYNTAX" -.rs -.sp -For compatibility with Oniguruma, the non-Perl syntax \eg followed by a name or -a number enclosed either in angle brackets or single quotes, is an alternative -syntax for referencing a subpattern as a subroutine, possibly recursively. Here -are two of the examples used above, rewritten using this syntax: -.sp - (?<pn> \e( ( (?>[^()]+) | \eg<pn> )* \e) ) - (sens|respons)e and \eg'1'ibility -.sp -PCRE supports an extension to Oniguruma: if a number is preceded by a -plus or a minus sign it is taken as a relative reference. For example: -.sp - (abc)(?i:\eg<-1>) -.sp -Note that \eg{...} (Perl syntax) and \eg<...> (Oniguruma syntax) are \fInot\fP -synonymous. The former is a back reference; the latter is a subroutine call. -. -. -.SH CALLOUTS -.rs -.sp -Perl has a feature whereby using the sequence (?{...}) causes arbitrary Perl -code to be obeyed in the middle of matching a regular expression. This makes it -possible, amongst other things, to extract different substrings that match the -same pair of parentheses when there is a repetition. -.P -PCRE provides a similar feature, but of course it cannot obey arbitrary Perl -code. The feature is called "callout". The caller of PCRE provides an external -function by putting its entry point in the global variable \fIpcre_callout\fP -(8-bit library) or \fIpcre16_callout\fP (16-bit library). By default, this -variable contains NULL, which disables all calling out. -.P -Within a regular expression, (?C) indicates the points at which the external -function is to be called. If you want to identify different callout points, you -can put a number less than 256 after the letter C. The default value is zero. -For example, this pattern has two callout points: -.sp - (?C1)abc(?C2)def -.sp -If the PCRE_AUTO_CALLOUT flag is passed to a compiling function, callouts are -automatically installed before each item in the pattern. They are all numbered -255. -.P -During matching, when PCRE reaches a callout point, the external function is -called. It is provided with the number of the callout, the position in the -pattern, and, optionally, one item of data originally supplied by the caller of -the matching function. The callout function may cause matching to proceed, to -backtrack, or to fail altogether. A complete description of the interface to -the callout function is given in the -.\" HREF -\fBpcrecallout\fP -.\" -documentation. -. -. -.\" HTML <a name="backtrackcontrol"></a> -.SH "BACKTRACKING CONTROL" -.rs -.sp -Perl 5.10 introduced a number of "Special Backtracking Control Verbs", which -are described in the Perl documentation as "experimental and subject to change -or removal in a future version of Perl". It goes on to say: "Their usage in -production code should be noted to avoid problems during upgrades." The same -remarks apply to the PCRE features described in this section. -.P -Since these verbs are specifically related to backtracking, most of them can be -used only when the pattern is to be matched using one of the traditional -matching functions, which use a backtracking algorithm. With the exception of -(*FAIL), which behaves like a failing negative assertion, they cause an error -if encountered by a DFA matching function. -.P -If any of these verbs are used in an assertion or in a subpattern that is -called as a subroutine (whether or not recursively), their effect is confined -to that subpattern; it does not extend to the surrounding pattern, with one -exception: the name from a *(MARK), (*PRUNE), or (*THEN) that is encountered in -a successful positive assertion \fIis\fP passed back when a match succeeds -(compare capturing parentheses in assertions). Note that such subpatterns are -processed as anchored at the point where they are tested. Note also that Perl's -treatment of subroutines and assertions is different in some cases. -.P -The new verbs make use of what was previously invalid syntax: an opening -parenthesis followed by an asterisk. They are generally of the form -(*VERB) or (*VERB:NAME). Some may take either form, with differing behaviour, -depending on whether or not an argument is present. A name is any sequence of -characters that does not include a closing parenthesis. The maximum length of -name is 255 in the 8-bit library and 65535 in the 16-bit library. If the name -is empty, that is, if the closing parenthesis immediately follows the colon, -the effect is as if the colon were not there. Any number of these verbs may -occur in a pattern. -. -. -.\" HTML <a name="nooptimize"></a> -.SS "Optimizations that affect backtracking verbs" -.rs -.sp -PCRE contains some optimizations that are used to speed up matching by running -some checks at the start of each match attempt. For example, it may know the -minimum length of matching subject, or that a particular character must be -present. When one of these optimizations suppresses the running of a match, any -included backtracking verbs will not, of course, be processed. You can suppress -the start-of-match optimizations by setting the PCRE_NO_START_OPTIMIZE option -when calling \fBpcre_compile()\fP or \fBpcre_exec()\fP, or by starting the -pattern with (*NO_START_OPT). There is more discussion of this option in the -section entitled -.\" HTML <a href="pcreapi.html#execoptions"> -.\" </a> -"Option bits for \fBpcre_exec()\fP" -.\" -in the -.\" HREF -\fBpcreapi\fP -.\" -documentation. -.P -Experiments with Perl suggest that it too has similar optimizations, sometimes -leading to anomalous results. -. -. -.SS "Verbs that act immediately" -.rs -.sp -The following verbs act as soon as they are encountered. They may not be -followed by a name. -.sp - (*ACCEPT) -.sp -This verb causes the match to end successfully, skipping the remainder of the -pattern. However, when it is inside a subpattern that is called as a -subroutine, only that subpattern is ended successfully. Matching then continues -at the outer level. If (*ACCEPT) is inside capturing parentheses, the data so -far is captured. For example: -.sp - A((?:A|B(*ACCEPT)|C)D) -.sp -This matches "AB", "AAD", or "ACD"; when it matches "AB", "B" is captured by -the outer parentheses. -.sp - (*FAIL) or (*F) -.sp -This verb causes a matching failure, forcing backtracking to occur. It is -equivalent to (?!) but easier to read. The Perl documentation notes that it is -probably useful only when combined with (?{}) or (??{}). Those are, of course, -Perl features that are not present in PCRE. The nearest equivalent is the -callout feature, as for example in this pattern: -.sp - a+(?C)(*FAIL) -.sp -A match with the string "aaaa" always fails, but the callout is taken before -each backtrack happens (in this example, 10 times). -. -. -.SS "Recording which path was taken" -.rs -.sp -There is one verb whose main purpose is to track how a match was arrived at, -though it also has a secondary use in conjunction with advancing the match -starting point (see (*SKIP) below). -.sp - (*MARK:NAME) or (*:NAME) -.sp -A name is always required with this verb. There may be as many instances of -(*MARK) as you like in a pattern, and their names do not have to be unique. -.P -When a match succeeds, the name of the last-encountered (*MARK) on the matching -path is passed back to the caller as described in the section entitled -.\" HTML <a href="pcreapi.html#extradata"> -.\" </a> -"Extra data for \fBpcre_exec()\fP" -.\" -in the -.\" HREF -\fBpcreapi\fP -.\" -documentation. Here is an example of \fBpcretest\fP output, where the /K -modifier requests the retrieval and outputting of (*MARK) data: -.sp - re> /X(*MARK:A)Y|X(*MARK:B)Z/K - data> XY - 0: XY - MK: A - XZ - 0: XZ - MK: B -.sp -The (*MARK) name is tagged with "MK:" in this output, and in this example it -indicates which of the two alternatives matched. This is a more efficient way -of obtaining this information than putting each alternative in its own -capturing parentheses. -.P -If (*MARK) is encountered in a positive assertion, its name is recorded and -passed back if it is the last-encountered. This does not happen for negative -assertions. -.P -After a partial match or a failed match, the name of the last encountered -(*MARK) in the entire match process is returned. For example: -.sp - re> /X(*MARK:A)Y|X(*MARK:B)Z/K - data> XP - No match, mark = B -.sp -Note that in this unanchored example the mark is retained from the match -attempt that started at the letter "X" in the subject. Subsequent match -attempts starting at "P" and then with an empty string do not get as far as the -(*MARK) item, but nevertheless do not reset it. -.P -If you are interested in (*MARK) values after failed matches, you should -probably set the PCRE_NO_START_OPTIMIZE option -.\" HTML <a href="#nooptimize"> -.\" </a> -(see above) -.\" -to ensure that the match is always attempted. -. -. -.SS "Verbs that act after backtracking" -.rs -.sp -The following verbs do nothing when they are encountered. Matching continues -with what follows, but if there is no subsequent match, causing a backtrack to -the verb, a failure is forced. That is, backtracking cannot pass to the left of -the verb. However, when one of these verbs appears inside an atomic group, its -effect is confined to that group, because once the group has been matched, -there is never any backtracking into it. In this situation, backtracking can -"jump back" to the left of the entire atomic group. (Remember also, as stated -above, that this localization also applies in subroutine calls and assertions.) -.P -These verbs differ in exactly what kind of failure occurs when backtracking -reaches them. -.sp - (*COMMIT) -.sp -This verb, which may not be followed by a name, causes the whole match to fail -outright if the rest of the pattern does not match. Even if the pattern is -unanchored, no further attempts to find a match by advancing the starting point -take place. Once (*COMMIT) has been passed, \fBpcre_exec()\fP is committed to -finding a match at the current starting point, or not at all. For example: -.sp - a+(*COMMIT)b -.sp -This matches "xxaab" but not "aacaab". It can be thought of as a kind of -dynamic anchor, or "I've started, so I must finish." The name of the most -recently passed (*MARK) in the path is passed back when (*COMMIT) forces a -match failure. -.P -Note that (*COMMIT) at the start of a pattern is not the same as an anchor, -unless PCRE's start-of-match optimizations are turned off, as shown in this -\fBpcretest\fP example: -.sp - re> /(*COMMIT)abc/ - data> xyzabc - 0: abc - xyzabc\eY - No match -.sp -PCRE knows that any match must start with "a", so the optimization skips along -the subject to "a" before running the first match attempt, which succeeds. When -the optimization is disabled by the \eY escape in the second subject, the match -starts at "x" and so the (*COMMIT) causes it to fail without trying any other -starting points. -.sp - (*PRUNE) or (*PRUNE:NAME) -.sp -This verb causes the match to fail at the current starting position in the -subject if the rest of the pattern does not match. If the pattern is -unanchored, the normal "bumpalong" advance to the next starting character then -happens. Backtracking can occur as usual to the left of (*PRUNE), before it is -reached, or when matching to the right of (*PRUNE), but if there is no match to -the right, backtracking cannot cross (*PRUNE). In simple cases, the use of -(*PRUNE) is just an alternative to an atomic group or possessive quantifier, -but there are some uses of (*PRUNE) that cannot be expressed in any other way. -The behaviour of (*PRUNE:NAME) is the same as (*MARK:NAME)(*PRUNE). In an -anchored pattern (*PRUNE) has the same effect as (*COMMIT). -.sp - (*SKIP) -.sp -This verb, when given without a name, is like (*PRUNE), except that if the -pattern is unanchored, the "bumpalong" advance is not to the next character, -but to the position in the subject where (*SKIP) was encountered. (*SKIP) -signifies that whatever text was matched leading up to it cannot be part of a -successful match. Consider: -.sp - a+(*SKIP)b -.sp -If the subject is "aaaac...", after the first match attempt fails (starting at -the first character in the string), the starting point skips on to start the -next attempt at "c". Note that a possessive quantifer does not have the same -effect as this example; although it would suppress backtracking during the -first match attempt, the second attempt would start at the second character -instead of skipping on to "c". -.sp - (*SKIP:NAME) -.sp -When (*SKIP) has an associated name, its behaviour is modified. If the -following pattern fails to match, the previous path through the pattern is -searched for the most recent (*MARK) that has the same name. If one is found, -the "bumpalong" advance is to the subject position that corresponds to that -(*MARK) instead of to where (*SKIP) was encountered. If no (*MARK) with a -matching name is found, the (*SKIP) is ignored. -.sp - (*THEN) or (*THEN:NAME) -.sp -This verb causes a skip to the next innermost alternative if the rest of the -pattern does not match. That is, it cancels pending backtracking, but only -within the current alternative. Its name comes from the observation that it can -be used for a pattern-based if-then-else block: -.sp - ( COND1 (*THEN) FOO | COND2 (*THEN) BAR | COND3 (*THEN) BAZ ) ... -.sp -If the COND1 pattern matches, FOO is tried (and possibly further items after -the end of the group if FOO succeeds); on failure, the matcher skips to the -second alternative and tries COND2, without backtracking into COND1. The -behaviour of (*THEN:NAME) is exactly the same as (*MARK:NAME)(*THEN). -If (*THEN) is not inside an alternation, it acts like (*PRUNE). -.P -Note that a subpattern that does not contain a | character is just a part of -the enclosing alternative; it is not a nested alternation with only one -alternative. The effect of (*THEN) extends beyond such a subpattern to the -enclosing alternative. Consider this pattern, where A, B, etc. are complex -pattern fragments that do not contain any | characters at this level: -.sp - A (B(*THEN)C) | D -.sp -If A and B are matched, but there is a failure in C, matching does not -backtrack into A; instead it moves to the next alternative, that is, D. -However, if the subpattern containing (*THEN) is given an alternative, it -behaves differently: -.sp - A (B(*THEN)C | (*FAIL)) | D -.sp -The effect of (*THEN) is now confined to the inner subpattern. After a failure -in C, matching moves to (*FAIL), which causes the whole subpattern to fail -because there are no more alternatives to try. In this case, matching does now -backtrack into A. -.P -Note also that a conditional subpattern is not considered as having two -alternatives, because only one is ever used. In other words, the | character in -a conditional subpattern has a different meaning. Ignoring white space, -consider: -.sp - ^.*? (?(?=a) a | b(*THEN)c ) -.sp -If the subject is "ba", this pattern does not match. Because .*? is ungreedy, -it initially matches zero characters. The condition (?=a) then fails, the -character "b" is matched, but "c" is not. At this point, matching does not -backtrack to .*? as might perhaps be expected from the presence of the | -character. The conditional subpattern is part of the single alternative that -comprises the whole pattern, and so the match fails. (If there was a backtrack -into .*?, allowing it to match "b", the match would succeed.) -.P -The verbs just described provide four different "strengths" of control when -subsequent matching fails. (*THEN) is the weakest, carrying on the match at the -next alternative. (*PRUNE) comes next, failing the match at the current -starting position, but allowing an advance to the next character (for an -unanchored pattern). (*SKIP) is similar, except that the advance may be more -than one character. (*COMMIT) is the strongest, causing the entire match to -fail. -.P -If more than one such verb is present in a pattern, the "strongest" one wins. -For example, consider this pattern, where A, B, etc. are complex pattern -fragments: -.sp - (A(*COMMIT)B(*THEN)C|D) -.sp -Once A has matched, PCRE is committed to this match, at the current starting -position. If subsequently B matches, but C does not, the normal (*THEN) action -of trying the next alternative (that is, D) does not happen because (*COMMIT) -overrides. -. -. -.SH "SEE ALSO" -.rs -.sp -\fBpcreapi\fP(3), \fBpcrecallout\fP(3), \fBpcrematching\fP(3), -\fBpcresyntax\fP(3), \fBpcre\fP(3), \fBpcre16(3)\fP. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 17 June 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcreperform.3 b/gtk+-mingw/share/man/man3/pcreperform.3 deleted file mode 100644 index 3cfad1d..0000000 --- a/gtk+-mingw/share/man/man3/pcreperform.3 +++ /dev/null @@ -1,178 +0,0 @@ -.TH PCREPERFORM 3 "09 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PCRE PERFORMANCE" -.rs -.sp -Two aspects of performance are discussed below: memory usage and processing -time. The way you express your pattern as a regular expression can affect both -of them. -. -.SH "COMPILED PATTERN MEMORY USAGE" -.rs -.sp -Patterns are compiled by PCRE into a reasonably efficient interpretive code, so -that most simple patterns do not use much memory. However, there is one case -where the memory usage of a compiled pattern can be unexpectedly large. If a -parenthesized subpattern has a quantifier with a minimum greater than 1 and/or -a limited maximum, the whole subpattern is repeated in the compiled code. For -example, the pattern -.sp - (abc|def){2,4} -.sp -is compiled as if it were -.sp - (abc|def)(abc|def)((abc|def)(abc|def)?)? -.sp -(Technical aside: It is done this way so that backtrack points within each of -the repetitions can be independently maintained.) -.P -For regular expressions whose quantifiers use only small numbers, this is not -usually a problem. However, if the numbers are large, and particularly if such -repetitions are nested, the memory usage can become an embarrassment. For -example, the very simple pattern -.sp - ((ab){1,1000}c){1,3} -.sp -uses 51K bytes when compiled using the 8-bit library. When PCRE is compiled -with its default internal pointer size of two bytes, the size limit on a -compiled pattern is 64K data units, and this is reached with the above pattern -if the outer repetition is increased from 3 to 4. PCRE can be compiled to use -larger internal pointers and thus handle larger compiled patterns, but it is -better to try to rewrite your pattern to use less memory if you can. -.P -One way of reducing the memory usage for such patterns is to make use of PCRE's -.\" HTML <a href="pcrepattern.html#subpatternsassubroutines"> -.\" </a> -"subroutine" -.\" -facility. Re-writing the above pattern as -.sp - ((ab)(?2){0,999}c)(?1){0,2} -.sp -reduces the memory requirements to 18K, and indeed it remains under 20K even -with the outer repetition increased to 100. However, this pattern is not -exactly equivalent, because the "subroutine" calls are treated as -.\" HTML <a href="pcrepattern.html#atomicgroup"> -.\" </a> -atomic groups -.\" -into which there can be no backtracking if there is a subsequent matching -failure. Therefore, PCRE cannot do this kind of rewriting automatically. -Furthermore, there is a noticeable loss of speed when executing the modified -pattern. Nevertheless, if the atomic grouping is not a problem and the loss of -speed is acceptable, this kind of rewriting will allow you to process patterns -that PCRE cannot otherwise handle. -. -. -.SH "STACK USAGE AT RUN TIME" -.rs -.sp -When \fBpcre_exec()\fP or \fBpcre16_exec()\fP is used for matching, certain -kinds of pattern can cause it to use large amounts of the process stack. In -some environments the default process stack is quite small, and if it runs out -the result is often SIGSEGV. This issue is probably the most frequently raised -problem with PCRE. Rewriting your pattern can often help. The -.\" HREF -\fBpcrestack\fP -.\" -documentation discusses this issue in detail. -. -. -.SH "PROCESSING TIME" -.rs -.sp -Certain items in regular expression patterns are processed more efficiently -than others. It is more efficient to use a character class like [aeiou] than a -set of single-character alternatives such as (a|e|i|o|u). In general, the -simplest construction that provides the required behaviour is usually the most -efficient. Jeffrey Friedl's book contains a lot of useful general discussion -about optimizing regular expressions for efficient performance. This document -contains a few observations about PCRE. -.P -Using Unicode character properties (the \ep, \eP, and \eX escapes) is slow, -because PCRE has to scan a structure that contains data for over fifteen -thousand characters whenever it needs a character's property. If you can find -an alternative pattern that does not use character properties, it will probably -be faster. -.P -By default, the escape sequences \eb, \ed, \es, and \ew, and the POSIX -character classes such as [:alpha:] do not use Unicode properties, partly for -backwards compatibility, and partly for performance reasons. However, you can -set PCRE_UCP if you want Unicode character properties to be used. This can -double the matching time for items such as \ed, when matched with -a traditional matching function; the performance loss is less with -a DFA matching function, and in both cases there is not much difference for -\eb. -.P -When a pattern begins with .* not in parentheses, or in parentheses that are -not the subject of a backreference, and the PCRE_DOTALL option is set, the -pattern is implicitly anchored by PCRE, since it can match only at the start of -a subject string. However, if PCRE_DOTALL is not set, PCRE cannot make this -optimization, because the . metacharacter does not then match a newline, and if -the subject string contains newlines, the pattern may match from the character -immediately following one of them instead of from the very start. For example, -the pattern -.sp - .*second -.sp -matches the subject "first\enand second" (where \en stands for a newline -character), with the match starting at the seventh character. In order to do -this, PCRE has to retry the match starting after every newline in the subject. -.P -If you are using such a pattern with subject strings that do not contain -newlines, the best performance is obtained by setting PCRE_DOTALL, or starting -the pattern with ^.* or ^.*? to indicate explicit anchoring. That saves PCRE -from having to scan along the subject looking for a newline to restart at. -.P -Beware of patterns that contain nested indefinite repeats. These can take a -long time to run when applied to a string that does not match. Consider the -pattern fragment -.sp - ^(a+)* -.sp -This can match "aaaa" in 16 different ways, and this number increases very -rapidly as the string gets longer. (The * repeat can match 0, 1, 2, 3, or 4 -times, and for each of those cases other than 0 or 4, the + repeats can match -different numbers of times.) When the remainder of the pattern is such that the -entire match is going to fail, PCRE has in principle to try every possible -variation, and this can take an extremely long time, even for relatively short -strings. -.P -An optimization catches some of the more simple cases such as -.sp - (a+)*b -.sp -where a literal character follows. Before embarking on the standard matching -procedure, PCRE checks that there is a "b" later in the subject string, and if -there is not, it fails the match immediately. However, when there is no -following literal this optimization cannot be used. You can see the difference -by comparing the behaviour of -.sp - (a+)*\ed -.sp -with the pattern above. The former gives a failure almost instantly when -applied to a whole line of "a" characters, whereas the latter takes an -appreciable time with strings longer than about 20 characters. -.P -In many cases, the solution to this kind of performance issue is to use an -atomic group or a possessive quantifier. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 09 January 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcreposix.3 b/gtk+-mingw/share/man/man3/pcreposix.3 deleted file mode 100644 index 411e548..0000000 --- a/gtk+-mingw/share/man/man3/pcreposix.3 +++ /dev/null @@ -1,270 +0,0 @@ -.TH PCREPOSIX 3 "09 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions. -.SH "SYNOPSIS OF POSIX API" -.rs -.sp -.B #include <pcreposix.h> -.PP -.SM -.B int regcomp(regex_t *\fIpreg\fP, const char *\fIpattern\fP, -.ti +5n -.B int \fIcflags\fP); -.PP -.B int regexec(regex_t *\fIpreg\fP, const char *\fIstring\fP, -.ti +5n -.B size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[], int \fIeflags\fP); -.PP -.B size_t regerror(int \fIerrcode\fP, const regex_t *\fIpreg\fP, -.ti +5n -.B char *\fIerrbuf\fP, size_t \fIerrbuf_size\fP); -.PP -.B void regfree(regex_t *\fIpreg\fP); -. -.SH DESCRIPTION -.rs -.sp -This set of functions provides a POSIX-style API for the PCRE regular -expression 8-bit library. See the -.\" HREF -\fBpcreapi\fP -.\" -documentation for a description of PCRE's native API, which contains much -additional functionality. There is no POSIX-style wrapper for PCRE's 16-bit -library. -.P -The functions described here are just wrapper functions that ultimately call -the PCRE native API. Their prototypes are defined in the \fBpcreposix.h\fP -header file, and on Unix systems the library itself is called -\fBpcreposix.a\fP, so can be accessed by adding \fB-lpcreposix\fP to the -command for linking an application that uses them. Because the POSIX functions -call the native ones, it is also necessary to add \fB-lpcre\fP. -.P -I have implemented only those POSIX option bits that can be reasonably mapped -to PCRE native options. In addition, the option REG_EXTENDED is defined with -the value zero. This has no effect, but since programs that are written to the -POSIX interface often use it, this makes it easier to slot in PCRE as a -replacement library. Other POSIX options are not even defined. -.P -There are also some other options that are not defined by POSIX. These have -been added at the request of users who want to make use of certain -PCRE-specific features via the POSIX calling interface. -.P -When PCRE is called via these functions, it is only the API that is POSIX-like -in style. The syntax and semantics of the regular expressions themselves are -still those of Perl, subject to the setting of various PCRE options, as -described below. "POSIX-like in style" means that the API approximates to the -POSIX definition; it is not fully POSIX-compatible, and in multi-byte encoding -domains it is probably even less compatible. -.P -The header for these functions is supplied as \fBpcreposix.h\fP to avoid any -potential clash with other POSIX libraries. It can, of course, be renamed or -aliased as \fBregex.h\fP, which is the "correct" name. It provides two -structure types, \fIregex_t\fP for compiled internal forms, and -\fIregmatch_t\fP for returning captured substrings. It also defines some -constants whose names start with "REG_"; these are used for setting options and -identifying error codes. -. -. -.SH "COMPILING A PATTERN" -.rs -.sp -The function \fBregcomp()\fP is called to compile a pattern into an -internal form. The pattern is a C string terminated by a binary zero, and -is passed in the argument \fIpattern\fP. The \fIpreg\fP argument is a pointer -to a \fBregex_t\fP structure that is used as a base for storing information -about the compiled regular expression. -.P -The argument \fIcflags\fP is either zero, or contains one or more of the bits -defined by the following macros: -.sp - REG_DOTALL -.sp -The PCRE_DOTALL option is set when the regular expression is passed for -compilation to the native function. Note that REG_DOTALL is not part of the -POSIX standard. -.sp - REG_ICASE -.sp -The PCRE_CASELESS option is set when the regular expression is passed for -compilation to the native function. -.sp - REG_NEWLINE -.sp -The PCRE_MULTILINE option is set when the regular expression is passed for -compilation to the native function. Note that this does \fInot\fP mimic the -defined POSIX behaviour for REG_NEWLINE (see the following section). -.sp - REG_NOSUB -.sp -The PCRE_NO_AUTO_CAPTURE option is set when the regular expression is passed -for compilation to the native function. In addition, when a pattern that is -compiled with this flag is passed to \fBregexec()\fP for matching, the -\fInmatch\fP and \fIpmatch\fP arguments are ignored, and no captured strings -are returned. -.sp - REG_UCP -.sp -The PCRE_UCP option is set when the regular expression is passed for -compilation to the native function. This causes PCRE to use Unicode properties -when matchine \ed, \ew, etc., instead of just recognizing ASCII values. Note -that REG_UTF8 is not part of the POSIX standard. -.sp - REG_UNGREEDY -.sp -The PCRE_UNGREEDY option is set when the regular expression is passed for -compilation to the native function. Note that REG_UNGREEDY is not part of the -POSIX standard. -.sp - REG_UTF8 -.sp -The PCRE_UTF8 option is set when the regular expression is passed for -compilation to the native function. This causes the pattern itself and all data -strings used for matching it to be treated as UTF-8 strings. Note that REG_UTF8 -is not part of the POSIX standard. -.P -In the absence of these flags, no options are passed to the native function. -This means the the regex is compiled with PCRE default semantics. In -particular, the way it handles newline characters in the subject string is the -Perl way, not the POSIX way. Note that setting PCRE_MULTILINE has only -\fIsome\fP of the effects specified for REG_NEWLINE. It does not affect the way -newlines are matched by . (they are not) or by a negative class such as [^a] -(they are). -.P -The yield of \fBregcomp()\fP is zero on success, and non-zero otherwise. The -\fIpreg\fP structure is filled in on success, and one member of the structure -is public: \fIre_nsub\fP contains the number of capturing subpatterns in -the regular expression. Various error codes are defined in the header file. -.P -NOTE: If the yield of \fBregcomp()\fP is non-zero, you must not attempt to -use the contents of the \fIpreg\fP structure. If, for example, you pass it to -\fBregexec()\fP, the result is undefined and your program is likely to crash. -. -. -.SH "MATCHING NEWLINE CHARACTERS" -.rs -.sp -This area is not simple, because POSIX and Perl take different views of things. -It is not possible to get PCRE to obey POSIX semantics, but then PCRE was never -intended to be a POSIX engine. The following table lists the different -possibilities for matching newline characters in PCRE: -.sp - Default Change with -.sp - . matches newline no PCRE_DOTALL - newline matches [^a] yes not changeable - $ matches \en at end yes PCRE_DOLLARENDONLY - $ matches \en in middle no PCRE_MULTILINE - ^ matches \en in middle no PCRE_MULTILINE -.sp -This is the equivalent table for POSIX: -.sp - Default Change with -.sp - . matches newline yes REG_NEWLINE - newline matches [^a] yes REG_NEWLINE - $ matches \en at end no REG_NEWLINE - $ matches \en in middle no REG_NEWLINE - ^ matches \en in middle no REG_NEWLINE -.sp -PCRE's behaviour is the same as Perl's, except that there is no equivalent for -PCRE_DOLLAR_ENDONLY in Perl. In both PCRE and Perl, there is no way to stop -newline from matching [^a]. -.P -The default POSIX newline handling can be obtained by setting PCRE_DOTALL and -PCRE_DOLLAR_ENDONLY, but there is no way to make PCRE behave exactly as for the -REG_NEWLINE action. -. -. -.SH "MATCHING A PATTERN" -.rs -.sp -The function \fBregexec()\fP is called to match a compiled pattern \fIpreg\fP -against a given \fIstring\fP, which is by default terminated by a zero byte -(but see REG_STARTEND below), subject to the options in \fIeflags\fP. These can -be: -.sp - REG_NOTBOL -.sp -The PCRE_NOTBOL option is set when calling the underlying PCRE matching -function. -.sp - REG_NOTEMPTY -.sp -The PCRE_NOTEMPTY option is set when calling the underlying PCRE matching -function. Note that REG_NOTEMPTY is not part of the POSIX standard. However, -setting this option can give more POSIX-like behaviour in some situations. -.sp - REG_NOTEOL -.sp -The PCRE_NOTEOL option is set when calling the underlying PCRE matching -function. -.sp - REG_STARTEND -.sp -The string is considered to start at \fIstring\fP + \fIpmatch[0].rm_so\fP and -to have a terminating NUL located at \fIstring\fP + \fIpmatch[0].rm_eo\fP -(there need not actually be a NUL at that location), regardless of the value of -\fInmatch\fP. This is a BSD extension, compatible with but not specified by -IEEE Standard 1003.2 (POSIX.2), and should be used with caution in software -intended to be portable to other systems. Note that a non-zero \fIrm_so\fP does -not imply REG_NOTBOL; REG_STARTEND affects only the location of the string, not -how it is matched. -.P -If the pattern was compiled with the REG_NOSUB flag, no data about any matched -strings is returned. The \fInmatch\fP and \fIpmatch\fP arguments of -\fBregexec()\fP are ignored. -.P -If the value of \fInmatch\fP is zero, or if the value \fIpmatch\fP is NULL, -no data about any matched strings is returned. -.P -Otherwise,the portion of the string that was matched, and also any captured -substrings, are returned via the \fIpmatch\fP argument, which points to an -array of \fInmatch\fP structures of type \fIregmatch_t\fP, containing the -members \fIrm_so\fP and \fIrm_eo\fP. These contain the offset to the first -character of each substring and the offset to the first character after the end -of each substring, respectively. The 0th element of the vector relates to the -entire portion of \fIstring\fP that was matched; subsequent elements relate to -the capturing subpatterns of the regular expression. Unused entries in the -array have both structure members set to -1. -.P -A successful match yields a zero return; various error codes are defined in the -header file, of which REG_NOMATCH is the "expected" failure code. -. -. -.SH "ERROR MESSAGES" -.rs -.sp -The \fBregerror()\fP function maps a non-zero errorcode from either -\fBregcomp()\fP or \fBregexec()\fP to a printable message. If \fIpreg\fP is not -NULL, the error should have arisen from the use of that structure. A message -terminated by a binary zero is placed in \fIerrbuf\fP. The length of the -message, including the zero, is limited to \fIerrbuf_size\fP. The yield of the -function is the size of buffer needed to hold the whole message. -. -. -.SH MEMORY USAGE -.rs -.sp -Compiling a regular expression causes memory to be allocated and associated -with the \fIpreg\fP structure. The function \fBregfree()\fP frees all such -memory, after which \fIpreg\fP may no longer be used as a compiled expression. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 09 January 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcreprecompile.3 b/gtk+-mingw/share/man/man3/pcreprecompile.3 deleted file mode 100644 index 13ee212..0000000 --- a/gtk+-mingw/share/man/man3/pcreprecompile.3 +++ /dev/null @@ -1,151 +0,0 @@ -.TH PCREPRECOMPILE 3 "10 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "SAVING AND RE-USING PRECOMPILED PCRE PATTERNS" -.rs -.sp -If you are running an application that uses a large number of regular -expression patterns, it may be useful to store them in a precompiled form -instead of having to compile them every time the application is run. -If you are not using any private character tables (see the -.\" HREF -\fBpcre_maketables()\fP -.\" -documentation), this is relatively straightforward. If you are using private -tables, it is a little bit more complicated. However, if you are using the -just-in-time optimization feature, it is not possible to save and reload the -JIT data. -.P -If you save compiled patterns to a file, you can copy them to a different host -and run them there. If the two hosts have different endianness (byte order), -you should run the \fBpcre[16]_pattern_to_host_byte_order()\fP function on the -new host before trying to match the pattern. The matching functions return -PCRE_ERROR_BADENDIANNESS if they detect a pattern with the wrong endianness. -.P -Compiling regular expressions with one version of PCRE for use with a different -version is not guaranteed to work and may cause crashes, and saving and -restoring a compiled pattern loses any JIT optimization data. -. -. -.SH "SAVING A COMPILED PATTERN" -.rs -.sp -The value returned by \fBpcre[16]_compile()\fP points to a single block of -memory that holds the compiled pattern and associated data. You can find the -length of this block in bytes by calling \fBpcre[16]_fullinfo()\fP with an -argument of PCRE_INFO_SIZE. You can then save the data in any appropriate -manner. Here is sample code for the 8-bit library that compiles a pattern and -writes it to a file. It assumes that the variable \fIfd\fP refers to a file -that is open for output: -.sp - int erroroffset, rc, size; - char *error; - pcre *re; -.sp - re = pcre_compile("my pattern", 0, &error, &erroroffset, NULL); - if (re == NULL) { ... handle errors ... } - rc = pcre_fullinfo(re, NULL, PCRE_INFO_SIZE, &size); - if (rc < 0) { ... handle errors ... } - rc = fwrite(re, 1, size, fd); - if (rc != size) { ... handle errors ... } -.sp -In this example, the bytes that comprise the compiled pattern are copied -exactly. Note that this is binary data that may contain any of the 256 possible -byte values. On systems that make a distinction between binary and non-binary -data, be sure that the file is opened for binary output. -.P -If you want to write more than one pattern to a file, you will have to devise a -way of separating them. For binary data, preceding each pattern with its length -is probably the most straightforward approach. Another possibility is to write -out the data in hexadecimal instead of binary, one pattern to a line. -.P -Saving compiled patterns in a file is only one possible way of storing them for -later use. They could equally well be saved in a database, or in the memory of -some daemon process that passes them via sockets to the processes that want -them. -.P -If the pattern has been studied, it is also possible to save the normal study -data in a similar way to the compiled pattern itself. However, if the -PCRE_STUDY_JIT_COMPILE was used, the just-in-time data that is created cannot -be saved because it is too dependent on the current environment. When studying -generates additional information, \fBpcre[16]_study()\fP returns a pointer to a -\fBpcre[16]_extra\fP data block. Its format is defined in the -.\" HTML <a href="pcreapi.html#extradata"> -.\" </a> -section on matching a pattern -.\" -in the -.\" HREF -\fBpcreapi\fP -.\" -documentation. The \fIstudy_data\fP field points to the binary study data, and -this is what you must save (not the \fBpcre[16]_extra\fP block itself). The -length of the study data can be obtained by calling \fBpcre[16]_fullinfo()\fP -with an argument of PCRE_INFO_STUDYSIZE. Remember to check that -\fBpcre[16]_study()\fP did return a non-NULL value before trying to save the -study data. -. -. -.SH "RE-USING A PRECOMPILED PATTERN" -.rs -.sp -Re-using a precompiled pattern is straightforward. Having reloaded it into main -memory, called \fBpcre[16]_pattern_to_host_byte_order()\fP if necessary, -you pass its pointer to \fBpcre[16]_exec()\fP or \fBpcre[16]_dfa_exec()\fP in -the usual way. -.P -However, if you passed a pointer to custom character tables when the pattern -was compiled (the \fItableptr\fP argument of \fBpcre[16]_compile()\fP), you -must now pass a similar pointer to \fBpcre[16]_exec()\fP or -\fBpcre[16]_dfa_exec()\fP, because the value saved with the compiled pattern -will obviously be nonsense. A field in a \fBpcre[16]_extra()\fP block is used -to pass this data, as described in the -.\" HTML <a href="pcreapi.html#extradata"> -.\" </a> -section on matching a pattern -.\" -in the -.\" HREF -\fBpcreapi\fP -.\" -documentation. -.P -If you did not provide custom character tables when the pattern was compiled, -the pointer in the compiled pattern is NULL, which causes the matching -functions to use PCRE's internal tables. Thus, you do not need to take any -special action at run time in this case. -.P -If you saved study data with the compiled pattern, you need to create your own -\fBpcre[16]_extra\fP data block and set the \fIstudy_data\fP field to point to the -reloaded study data. You must also set the PCRE_EXTRA_STUDY_DATA bit in the -\fIflags\fP field to indicate that study data is present. Then pass the -\fBpcre[16]_extra\fP block to the matching function in the usual way. If the -pattern was studied for just-in-time optimization, that data cannot be saved, -and so is lost by a save/restore cycle. -. -. -.SH "COMPATIBILITY WITH DIFFERENT PCRE RELEASES" -.rs -.sp -In general, it is safest to recompile all saved patterns when you update to a -new PCRE release, though not all updates actually require this. -. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 10 January 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcresample.3 b/gtk+-mingw/share/man/man3/pcresample.3 deleted file mode 100644 index d7fe7ec..0000000 --- a/gtk+-mingw/share/man/man3/pcresample.3 +++ /dev/null @@ -1,99 +0,0 @@ -.TH PCRESAMPLE 3 "10 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PCRE SAMPLE PROGRAM" -.rs -.sp -A simple, complete demonstration program, to get you started with using PCRE, -is supplied in the file \fIpcredemo.c\fP in the PCRE distribution. A listing of -this program is given in the -.\" HREF -\fBpcredemo\fP -.\" -documentation. If you do not have a copy of the PCRE distribution, you can save -this listing to re-create \fIpcredemo.c\fP. -.P -The demonstration program, which uses the original PCRE 8-bit library, compiles -the regular expression that is its first argument, and matches it against the -subject string in its second argument. No PCRE options are set, and default -character tables are used. If matching succeeds, the program outputs the -portion of the subject that matched, together with the contents of any captured -substrings. -.P -If the -g option is given on the command line, the program then goes on to -check for further matches of the same regular expression in the same subject -string. The logic is a little bit tricky because of the possibility of matching -an empty string. Comments in the code explain what is going on. -.P -If PCRE is installed in the standard include and library directories for your -operating system, you should be able to compile the demonstration program using -this command: -.sp - gcc -o pcredemo pcredemo.c -lpcre -.sp -If PCRE is installed elsewhere, you may need to add additional options to the -command line. For example, on a Unix-like system that has PCRE installed in -\fI/usr/local\fP, you can compile the demonstration program using a command -like this: -.sp -.\" JOINSH - gcc -o pcredemo -I/usr/local/include pcredemo.c \e - -L/usr/local/lib -lpcre -.sp -In a Windows environment, if you want to statically link the program against a -non-dll \fBpcre.a\fP file, you must uncomment the line that defines PCRE_STATIC -before including \fBpcre.h\fP, because otherwise the \fBpcre_malloc()\fP and -\fBpcre_free()\fP exported functions will be declared -\fB__declspec(dllimport)\fP, with unwanted results. -.P -Once you have compiled and linked the demonstration program, you can run simple -tests like this: -.sp - ./pcredemo 'cat|dog' 'the cat sat on the mat' - ./pcredemo -g 'cat|dog' 'the dog sat on the cat' -.sp -Note that there is a much more comprehensive test program, called -.\" HREF -\fBpcretest\fP, -.\" -which supports many more facilities for testing regular expressions and both -PCRE libraries. The -.\" HREF -\fBpcredemo\fP -.\" -program is provided as a simple coding example. -.P -If you try to run -.\" HREF -\fBpcredemo\fP -.\" -when PCRE is not installed in the standard library directory, you may get an -error like this on some operating systems (e.g. Solaris): -.sp - ld.so.1: a.out: fatal: libpcre.so.0: open failed: No such file or directory -.sp -This is caused by the way shared library support works on those systems. You -need to add -.sp - -R/usr/local/lib -.sp -(for example) to the compile command to get round this problem. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 10 January 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcrestack.3 b/gtk+-mingw/share/man/man3/pcrestack.3 deleted file mode 100644 index fdd7fd9..0000000 --- a/gtk+-mingw/share/man/man3/pcrestack.3 +++ /dev/null @@ -1,215 +0,0 @@ -.TH PCRESTACK 3 "21 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PCRE DISCUSSION OF STACK USAGE" -.rs -.sp -When you call \fBpcre[16]_exec()\fP, it makes use of an internal function -called \fBmatch()\fP. This calls itself recursively at branch points in the -pattern, in order to remember the state of the match so that it can back up and -try a different alternative if the first one fails. As matching proceeds deeper -and deeper into the tree of possibilities, the recursion depth increases. The -\fBmatch()\fP function is also called in other circumstances, for example, -whenever a parenthesized sub-pattern is entered, and in certain cases of -repetition. -.P -Not all calls of \fBmatch()\fP increase the recursion depth; for an item such -as a* it may be called several times at the same level, after matching -different numbers of a's. Furthermore, in a number of cases where the result of -the recursive call would immediately be passed back as the result of the -current call (a "tail recursion"), the function is just restarted instead. -.P -The above comments apply when \fBpcre[16]_exec()\fP is run in its normal -interpretive manner. If the pattern was studied with the -PCRE_STUDY_JIT_COMPILE option, and just-in-time compiling was successful, and -the options passed to \fBpcre[16]_exec()\fP were not incompatible, the matching -process uses the JIT-compiled code instead of the \fBmatch()\fP function. In -this case, the memory requirements are handled entirely differently. See the -.\" HREF -\fBpcrejit\fP -.\" -documentation for details. -.P -The \fBpcre[16]_dfa_exec()\fP function operates in an entirely different way, -and uses recursion only when there is a regular expression recursion or -subroutine call in the pattern. This includes the processing of assertion and -"once-only" subpatterns, which are handled like subroutine calls. Normally, -these are never very deep, and the limit on the complexity of -\fBpcre[16]_dfa_exec()\fP is controlled by the amount of workspace it is given. -However, it is possible to write patterns with runaway infinite recursions; -such patterns will cause \fBpcre[16]_dfa_exec()\fP to run out of stack. At -present, there is no protection against this. -.P -The comments that follow do NOT apply to \fBpcre[16]_dfa_exec()\fP; they are -relevant only for \fBpcre[16]_exec()\fP without the JIT optimization. -. -. -.SS "Reducing \fBpcre[16]_exec()\fP's stack usage" -.rs -.sp -Each time that \fBmatch()\fP is actually called recursively, it uses memory -from the process stack. For certain kinds of pattern and data, very large -amounts of stack may be needed, despite the recognition of "tail recursion". -You can often reduce the amount of recursion, and therefore the amount of stack -used, by modifying the pattern that is being matched. Consider, for example, -this pattern: -.sp - ([^<]|<(?!inet))+ -.sp -It matches from wherever it starts until it encounters "<inet" or the end of -the data, and is the kind of pattern that might be used when processing an XML -file. Each iteration of the outer parentheses matches either one character that -is not "<" or a "<" that is not followed by "inet". However, each time a -parenthesis is processed, a recursion occurs, so this formulation uses a stack -frame for each matched character. For a long string, a lot of stack is -required. Consider now this rewritten pattern, which matches exactly the same -strings: -.sp - ([^<]++|<(?!inet))+ -.sp -This uses very much less stack, because runs of characters that do not contain -"<" are "swallowed" in one item inside the parentheses. Recursion happens only -when a "<" character that is not followed by "inet" is encountered (and we -assume this is relatively rare). A possessive quantifier is used to stop any -backtracking into the runs of non-"<" characters, but that is not related to -stack usage. -.P -This example shows that one way of avoiding stack problems when matching long -subject strings is to write repeated parenthesized subpatterns to match more -than one character whenever possible. -. -. -.SS "Compiling PCRE to use heap instead of stack for \fBpcre[16]_exec()\fP" -.rs -.sp -In environments where stack memory is constrained, you might want to compile -PCRE to use heap memory instead of stack for remembering back-up points when -\fBpcre[16]_exec()\fP is running. This makes it run a lot more slowly, however. -Details of how to do this are given in the -.\" HREF -\fBpcrebuild\fP -.\" -documentation. When built in this way, instead of using the stack, PCRE obtains -and frees memory by calling the functions that are pointed to by the -\fBpcre[16]_stack_malloc\fP and \fBpcre[16]_stack_free\fP variables. By -default, these point to \fBmalloc()\fP and \fBfree()\fP, but you can replace -the pointers to cause PCRE to use your own functions. Since the block sizes are -always the same, and are always freed in reverse order, it may be possible to -implement customized memory handlers that are more efficient than the standard -functions. -. -. -.SS "Limiting \fBpcre[16]_exec()\fP's stack usage" -.rs -.sp -You can set limits on the number of times that \fBmatch()\fP is called, both in -total and recursively. If a limit is exceeded, \fBpcre[16]_exec()\fP returns an -error code. Setting suitable limits should prevent it from running out of -stack. The default values of the limits are very large, and unlikely ever to -operate. They can be changed when PCRE is built, and they can also be set when -\fBpcre[16]_exec()\fP is called. For details of these interfaces, see the -.\" HREF -\fBpcrebuild\fP -.\" -documentation and the -.\" HTML <a href="pcreapi.html#extradata"> -.\" </a> -section on extra data for \fBpcre[16]_exec()\fP -.\" -in the -.\" HREF -\fBpcreapi\fP -.\" -documentation. -.P -As a very rough rule of thumb, you should reckon on about 500 bytes per -recursion. Thus, if you want to limit your stack usage to 8Mb, you should set -the limit at 16000 recursions. A 64Mb stack, on the other hand, can support -around 128000 recursions. -.P -In Unix-like environments, the \fBpcretest\fP test program has a command line -option (\fB-S\fP) that can be used to increase the size of its stack. As long -as the stack is large enough, another option (\fB-M\fP) can be used to find the -smallest limits that allow a particular pattern to match a given subject -string. This is done by calling \fBpcre[16]_exec()\fP repeatedly with different -limits. -. -. -.SS "Obtaining an estimate of stack usage" -.rs -.sp -The actual amount of stack used per recursion can vary quite a lot, depending -on the compiler that was used to build PCRE and the optimization or debugging -options that were set for it. The rule of thumb value of 500 bytes mentioned -above may be larger or smaller than what is actually needed. A better -approximation can be obtained by running this command: -.sp - pcretest -m -C -.sp -The \fB-C\fP option causes \fBpcretest\fP to output information about the -options with which PCRE was compiled. When \fB-m\fP is also given (before -\fB-C\fP), information about stack use is given in a line like this: -.sp - Match recursion uses stack: approximate frame size = 640 bytes -.sp -The value is approximate because some recursions need a bit more (up to perhaps -16 more bytes). -.P -If the above command is given when PCRE is compiled to use the heap instead of -the stack for recursion, the value that is output is the size of each block -that is obtained from the heap. -. -. -.SS "Changing stack size in Unix-like systems" -.rs -.sp -In Unix-like environments, there is not often a problem with the stack unless -very long strings are involved, though the default limit on stack size varies -from system to system. Values from 8Mb to 64Mb are common. You can find your -default limit by running the command: -.sp - ulimit -s -.sp -Unfortunately, the effect of running out of stack is often SIGSEGV, though -sometimes a more explicit error message is given. You can normally increase the -limit on stack size by code such as this: -.sp - struct rlimit rlim; - getrlimit(RLIMIT_STACK, &rlim); - rlim.rlim_cur = 100*1024*1024; - setrlimit(RLIMIT_STACK, &rlim); -.sp -This reads the current limits (soft and hard) using \fBgetrlimit()\fP, then -attempts to increase the soft limit to 100Mb using \fBsetrlimit()\fP. You must -do this before calling \fBpcre[16]_exec()\fP. -. -. -.SS "Changing stack size in Mac OS X" -.rs -.sp -Using \fBsetrlimit()\fP, as described above, should also work on Mac OS X. It -is also possible to set a stack size when linking a program. There is a -discussion about stack sizes in Mac OS X at this web site: -.\" HTML <a href="http://developer.apple.com/qa/qa2005/qa1419.html"> -.\" </a> -http://developer.apple.com/qa/qa2005/qa1419.html. -.\" -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 21 January 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcresyntax.3 b/gtk+-mingw/share/man/man3/pcresyntax.3 deleted file mode 100644 index 59eaa84..0000000 --- a/gtk+-mingw/share/man/man3/pcresyntax.3 +++ /dev/null @@ -1,494 +0,0 @@ -.TH PCRESYNTAX 3 "10 January 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "PCRE REGULAR EXPRESSION SYNTAX SUMMARY" -.rs -.sp -The full syntax and semantics of the regular expressions that are supported by -PCRE are described in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation. This document contains a quick-reference summary of the syntax. -. -. -.SH "QUOTING" -.rs -.sp - \ex where x is non-alphanumeric is a literal x - \eQ...\eE treat enclosed characters as literal -. -. -.SH "CHARACTERS" -.rs -.sp - \ea alarm, that is, the BEL character (hex 07) - \ecx "control-x", where x is any ASCII character - \ee escape (hex 1B) - \ef form feed (hex 0C) - \en newline (hex 0A) - \er carriage return (hex 0D) - \et tab (hex 09) - \eddd character with octal code ddd, or backreference - \exhh character with hex code hh - \ex{hhh..} character with hex code hhh.. -. -. -.SH "CHARACTER TYPES" -.rs -.sp - . any character except newline; - in dotall mode, any character whatsoever - \eC one data unit, even in UTF mode (best avoided) - \ed a decimal digit - \eD a character that is not a decimal digit - \eh a horizontal white space character - \eH a character that is not a horizontal white space character - \eN a character that is not a newline - \ep{\fIxx\fP} a character with the \fIxx\fP property - \eP{\fIxx\fP} a character without the \fIxx\fP property - \eR a newline sequence - \es a white space character - \eS a character that is not a white space character - \ev a vertical white space character - \eV a character that is not a vertical white space character - \ew a "word" character - \eW a "non-word" character - \eX an extended Unicode sequence -.sp -In PCRE, by default, \ed, \eD, \es, \eS, \ew, and \eW recognize only ASCII -characters, even in a UTF mode. However, this can be changed by setting the -PCRE_UCP option. -. -. -.SH "GENERAL CATEGORY PROPERTIES FOR \ep and \eP" -.rs -.sp - C Other - Cc Control - Cf Format - Cn Unassigned - Co Private use - Cs Surrogate -.sp - L Letter - Ll Lower case letter - Lm Modifier letter - Lo Other letter - Lt Title case letter - Lu Upper case letter - L& Ll, Lu, or Lt -.sp - M Mark - Mc Spacing mark - Me Enclosing mark - Mn Non-spacing mark -.sp - N Number - Nd Decimal number - Nl Letter number - No Other number -.sp - P Punctuation - Pc Connector punctuation - Pd Dash punctuation - Pe Close punctuation - Pf Final punctuation - Pi Initial punctuation - Po Other punctuation - Ps Open punctuation -.sp - S Symbol - Sc Currency symbol - Sk Modifier symbol - Sm Mathematical symbol - So Other symbol -.sp - Z Separator - Zl Line separator - Zp Paragraph separator - Zs Space separator -. -. -.SH "PCRE SPECIAL CATEGORY PROPERTIES FOR \ep and \eP" -.rs -.sp - Xan Alphanumeric: union of properties L and N - Xps POSIX space: property Z or tab, NL, VT, FF, CR - Xsp Perl space: property Z or tab, NL, FF, CR - Xwd Perl word: property Xan or underscore -. -. -.SH "SCRIPT NAMES FOR \ep AND \eP" -.rs -.sp -Arabic, -Armenian, -Avestan, -Balinese, -Bamum, -Batak, -Bengali, -Bopomofo, -Brahmi, -Braille, -Buginese, -Buhid, -Canadian_Aboriginal, -Carian, -Chakma, -Cham, -Cherokee, -Common, -Coptic, -Cuneiform, -Cypriot, -Cyrillic, -Deseret, -Devanagari, -Egyptian_Hieroglyphs, -Ethiopic, -Georgian, -Glagolitic, -Gothic, -Greek, -Gujarati, -Gurmukhi, -Han, -Hangul, -Hanunoo, -Hebrew, -Hiragana, -Imperial_Aramaic, -Inherited, -Inscriptional_Pahlavi, -Inscriptional_Parthian, -Javanese, -Kaithi, -Kannada, -Katakana, -Kayah_Li, -Kharoshthi, -Khmer, -Lao, -Latin, -Lepcha, -Limbu, -Linear_B, -Lisu, -Lycian, -Lydian, -Malayalam, -Mandaic, -Meetei_Mayek, -Meroitic_Cursive, -Meroitic_Hieroglyphs, -Miao, -Mongolian, -Myanmar, -New_Tai_Lue, -Nko, -Ogham, -Old_Italic, -Old_Persian, -Old_South_Arabian, -Old_Turkic, -Ol_Chiki, -Oriya, -Osmanya, -Phags_Pa, -Phoenician, -Rejang, -Runic, -Samaritan, -Saurashtra, -Sharada, -Shavian, -Sinhala, -Sora_Sompeng, -Sundanese, -Syloti_Nagri, -Syriac, -Tagalog, -Tagbanwa, -Tai_Le, -Tai_Tham, -Tai_Viet, -Takri, -Tamil, -Telugu, -Thaana, -Thai, -Tibetan, -Tifinagh, -Ugaritic, -Vai, -Yi. -. -. -.SH "CHARACTER CLASSES" -.rs -.sp - [...] positive character class - [^...] negative character class - [x-y] range (can be used for hex characters) - [[:xxx:]] positive POSIX named set - [[:^xxx:]] negative POSIX named set -.sp - alnum alphanumeric - alpha alphabetic - ascii 0-127 - blank space or tab - cntrl control character - digit decimal digit - graph printing, excluding space - lower lower case letter - print printing, including space - punct printing, excluding alphanumeric - space white space - upper upper case letter - word same as \ew - xdigit hexadecimal digit -.sp -In PCRE, POSIX character set names recognize only ASCII characters by default, -but some of them use Unicode properties if PCRE_UCP is set. You can use -\eQ...\eE inside a character class. -. -. -.SH "QUANTIFIERS" -.rs -.sp - ? 0 or 1, greedy - ?+ 0 or 1, possessive - ?? 0 or 1, lazy - * 0 or more, greedy - *+ 0 or more, possessive - *? 0 or more, lazy - + 1 or more, greedy - ++ 1 or more, possessive - +? 1 or more, lazy - {n} exactly n - {n,m} at least n, no more than m, greedy - {n,m}+ at least n, no more than m, possessive - {n,m}? at least n, no more than m, lazy - {n,} n or more, greedy - {n,}+ n or more, possessive - {n,}? n or more, lazy -. -. -.SH "ANCHORS AND SIMPLE ASSERTIONS" -.rs -.sp - \eb word boundary - \eB not a word boundary - ^ start of subject - also after internal newline in multiline mode - \eA start of subject - $ end of subject - also before newline at end of subject - also before internal newline in multiline mode - \eZ end of subject - also before newline at end of subject - \ez end of subject - \eG first matching position in subject -. -. -.SH "MATCH POINT RESET" -.rs -.sp - \eK reset start of match -. -. -.SH "ALTERNATION" -.rs -.sp - expr|expr|expr... -. -. -.SH "CAPTURING" -.rs -.sp - (...) capturing group - (?<name>...) named capturing group (Perl) - (?'name'...) named capturing group (Perl) - (?P<name>...) named capturing group (Python) - (?:...) non-capturing group - (?|...) non-capturing group; reset group numbers for - capturing groups in each alternative -. -. -.SH "ATOMIC GROUPS" -.rs -.sp - (?>...) atomic, non-capturing group -. -. -. -. -.SH "COMMENT" -.rs -.sp - (?#....) comment (not nestable) -. -. -.SH "OPTION SETTING" -.rs -.sp - (?i) caseless - (?J) allow duplicate names - (?m) multiline - (?s) single line (dotall) - (?U) default ungreedy (lazy) - (?x) extended (ignore white space) - (?-...) unset option(s) -.sp -The following are recognized only at the start of a pattern or after one of the -newline-setting options with similar syntax: -.sp - (*NO_START_OPT) no start-match optimization (PCRE_NO_START_OPTIMIZE) - (*UTF8) set UTF-8 mode: 8-bit library (PCRE_UTF8) - (*UTF16) set UTF-16 mode: 16-bit library (PCRE_UTF16) - (*UCP) set PCRE_UCP (use Unicode properties for \ed etc) -. -. -.SH "LOOKAHEAD AND LOOKBEHIND ASSERTIONS" -.rs -.sp - (?=...) positive look ahead - (?!...) negative look ahead - (?<=...) positive look behind - (?<!...) negative look behind -.sp -Each top-level branch of a look behind must be of a fixed length. -. -. -.SH "BACKREFERENCES" -.rs -.sp - \en reference by number (can be ambiguous) - \egn reference by number - \eg{n} reference by number - \eg{-n} relative reference by number - \ek<name> reference by name (Perl) - \ek'name' reference by name (Perl) - \eg{name} reference by name (Perl) - \ek{name} reference by name (.NET) - (?P=name) reference by name (Python) -. -. -.SH "SUBROUTINE REFERENCES (POSSIBLY RECURSIVE)" -.rs -.sp - (?R) recurse whole pattern - (?n) call subpattern by absolute number - (?+n) call subpattern by relative number - (?-n) call subpattern by relative number - (?&name) call subpattern by name (Perl) - (?P>name) call subpattern by name (Python) - \eg<name> call subpattern by name (Oniguruma) - \eg'name' call subpattern by name (Oniguruma) - \eg<n> call subpattern by absolute number (Oniguruma) - \eg'n' call subpattern by absolute number (Oniguruma) - \eg<+n> call subpattern by relative number (PCRE extension) - \eg'+n' call subpattern by relative number (PCRE extension) - \eg<-n> call subpattern by relative number (PCRE extension) - \eg'-n' call subpattern by relative number (PCRE extension) -. -. -.SH "CONDITIONAL PATTERNS" -.rs -.sp - (?(condition)yes-pattern) - (?(condition)yes-pattern|no-pattern) -.sp - (?(n)... absolute reference condition - (?(+n)... relative reference condition - (?(-n)... relative reference condition - (?(<name>)... named reference condition (Perl) - (?('name')... named reference condition (Perl) - (?(name)... named reference condition (PCRE) - (?(R)... overall recursion condition - (?(Rn)... specific group recursion condition - (?(R&name)... specific recursion condition - (?(DEFINE)... define subpattern for reference - (?(assert)... assertion condition -. -. -.SH "BACKTRACKING CONTROL" -.rs -.sp -The following act immediately they are reached: -.sp - (*ACCEPT) force successful match - (*FAIL) force backtrack; synonym (*F) - (*MARK:NAME) set name to be passed back; synonym (*:NAME) -.sp -The following act only when a subsequent match failure causes a backtrack to -reach them. They all force a match failure, but they differ in what happens -afterwards. Those that advance the start-of-match point do so only if the -pattern is not anchored. -.sp - (*COMMIT) overall failure, no advance of starting point - (*PRUNE) advance to next starting character - (*PRUNE:NAME) equivalent to (*MARK:NAME)(*PRUNE) - (*SKIP) advance to current matching position - (*SKIP:NAME) advance to position corresponding to an earlier - (*MARK:NAME); if not found, the (*SKIP) is ignored - (*THEN) local failure, backtrack to next alternation - (*THEN:NAME) equivalent to (*MARK:NAME)(*THEN) -. -. -.SH "NEWLINE CONVENTIONS" -.rs -.sp -These are recognized only at the very start of the pattern or after a -(*BSR_...), (*UTF8), (*UTF16) or (*UCP) option. -.sp - (*CR) carriage return only - (*LF) linefeed only - (*CRLF) carriage return followed by linefeed - (*ANYCRLF) all three of the above - (*ANY) any Unicode newline sequence -. -. -.SH "WHAT \eR MATCHES" -.rs -.sp -These are recognized only at the very start of the pattern or after a -(*...) option that sets the newline convention or a UTF or UCP mode. -.sp - (*BSR_ANYCRLF) CR, LF, or CRLF - (*BSR_UNICODE) any Unicode newline sequence -. -. -.SH "CALLOUTS" -.rs -.sp - (?C) callout - (?Cn) callout with data n -. -. -.SH "SEE ALSO" -.rs -.sp -\fBpcrepattern\fP(3), \fBpcreapi\fP(3), \fBpcrecallout\fP(3), -\fBpcrematching\fP(3), \fBpcre\fP(3). -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 10 January 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/pcreunicode.3 b/gtk+-mingw/share/man/man3/pcreunicode.3 deleted file mode 100644 index e8dc80e..0000000 --- a/gtk+-mingw/share/man/man3/pcreunicode.3 +++ /dev/null @@ -1,225 +0,0 @@ -.TH PCREUNICODE 3 "14 April 2012" "PCRE 8.30" -.SH NAME -PCRE - Perl-compatible regular expressions -.SH "UTF-8, UTF-16, AND UNICODE PROPERTY SUPPORT" -.rs -.sp -From Release 8.30, in addition to its previous UTF-8 support, PCRE also -supports UTF-16 by means of a separate 16-bit library. This can be built as -well as, or instead of, the 8-bit library. -. -. -.SH "UTF-8 SUPPORT" -.rs -.sp -In order process UTF-8 strings, you must build PCRE's 8-bit library with UTF -support, and, in addition, you must call -.\" HREF -\fBpcre_compile()\fP -.\" -with the PCRE_UTF8 option flag, or the pattern must start with the sequence -(*UTF8). When either of these is the case, both the pattern and any subject -strings that are matched against it are treated as UTF-8 strings instead of -strings of 1-byte characters. -. -. -.SH "UTF-16 SUPPORT" -.rs -.sp -In order process UTF-16 strings, you must build PCRE's 16-bit library with UTF -support, and, in addition, you must call -.\" HTML <a href="pcre_compile.html"> -.\" </a> -\fBpcre16_compile()\fP -.\" -with the PCRE_UTF16 option flag, or the pattern must start with the sequence -(*UTF16). When either of these is the case, both the pattern and any subject -strings that are matched against it are treated as UTF-16 strings instead of -strings of 16-bit characters. -. -. -.SH "UTF SUPPORT OVERHEAD" -.rs -.sp -If you compile PCRE with UTF support, but do not use it at run time, the -library will be a bit bigger, but the additional run time overhead is limited -to testing the PCRE_UTF8/16 flag occasionally, so should not be very big. -. -. -.SH "UNICODE PROPERTY SUPPORT" -.rs -.sp -If PCRE is built with Unicode character property support (which implies UTF -support), the escape sequences \ep{..}, \eP{..}, and \eX can be used. -The available properties that can be tested are limited to the general -category properties such as Lu for an upper case letter or Nd for a decimal -number, the Unicode script names such as Arabic or Han, and the derived -properties Any and L&. A full list is given in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation. Only the short names for properties are supported. For example, -\ep{L} matches a letter. Its Perl synonym, \ep{Letter}, is not supported. -Furthermore, in Perl, many properties may optionally be prefixed by "Is", for -compatibility with Perl 5.6. PCRE does not support this. -. -. -.\" HTML <a name="utf8strings"></a> -.SS "Validity of UTF-8 strings" -.rs -.sp -When you set the PCRE_UTF8 flag, the byte strings passed as patterns and -subjects are (by default) checked for validity on entry to the relevant -functions. The entire string is checked before any other processing takes -place. From release 7.3 of PCRE, the check is according the rules of RFC 3629, -which are themselves derived from the Unicode specification. Earlier releases -of PCRE followed the rules of RFC 2279, which allows the full range of 31-bit -values (0 to 0x7FFFFFFF). The current check allows only values in the range U+0 -to U+10FFFF, excluding U+D800 to U+DFFF. -.P -The excluded code points are the "Surrogate Area" of Unicode. They are reserved -for use by UTF-16, where they are used in pairs to encode codepoints with -values greater than 0xFFFF. The code points that are encoded by UTF-16 pairs -are available independently in the UTF-8 encoding. (In other words, the whole -surrogate thing is a fudge for UTF-16 which unfortunately messes up UTF-8.) -.P -If an invalid UTF-8 string is passed to PCRE, an error return is given. At -compile time, the only additional information is the offset to the first byte -of the failing character. The run-time functions \fBpcre_exec()\fP and -\fBpcre_dfa_exec()\fP also pass back this information, as well as a more -detailed reason code if the caller has provided memory in which to do this. -.P -In some situations, you may already know that your strings are valid, and -therefore want to skip these checks in order to improve performance, for -example in the case of a long subject string that is being scanned repeatedly -with different patterns. If you set the PCRE_NO_UTF8_CHECK flag at compile time -or at run time, PCRE assumes that the pattern or subject it is given -(respectively) contains only valid UTF-8 codes. In this case, it does not -diagnose an invalid UTF-8 string. -.P -If you pass an invalid UTF-8 string when PCRE_NO_UTF8_CHECK is set, what -happens depends on why the string is invalid. If the string conforms to the -"old" definition of UTF-8 (RFC 2279), it is processed as a string of characters -in the range 0 to 0x7FFFFFFF by \fBpcre_dfa_exec()\fP and the interpreted -version of \fBpcre_exec()\fP. In other words, apart from the initial validity -test, these functions (when in UTF-8 mode) handle strings according to the more -liberal rules of RFC 2279. However, the just-in-time (JIT) optimization for -\fBpcre_exec()\fP supports only RFC 3629. If you are using JIT optimization, or -if the string does not even conform to RFC 2279, the result is undefined. Your -program may crash. -.P -If you want to process strings of values in the full range 0 to 0x7FFFFFFF, -encoded in a UTF-8-like manner as per the old RFC, you can set -PCRE_NO_UTF8_CHECK to bypass the more restrictive test. However, in this -situation, you will have to apply your own validity check, and avoid the use of -JIT optimization. -. -. -.\" HTML <a name="utf16strings"></a> -.SS "Validity of UTF-16 strings" -.rs -.sp -When you set the PCRE_UTF16 flag, the strings of 16-bit data units that are -passed as patterns and subjects are (by default) checked for validity on entry -to the relevant functions. Values other than those in the surrogate range -U+D800 to U+DFFF are independent code points. Values in the surrogate range -must be used in pairs in the correct manner. -.P -If an invalid UTF-16 string is passed to PCRE, an error return is given. At -compile time, the only additional information is the offset to the first data -unit of the failing character. The run-time functions \fBpcre16_exec()\fP and -\fBpcre16_dfa_exec()\fP also pass back this information, as well as a more -detailed reason code if the caller has provided memory in which to do this. -.P -In some situations, you may already know that your strings are valid, and -therefore want to skip these checks in order to improve performance. If you set -the PCRE_NO_UTF16_CHECK flag at compile time or at run time, PCRE assumes that -the pattern or subject it is given (respectively) contains only valid UTF-16 -sequences. In this case, it does not diagnose an invalid UTF-16 string. -. -. -.SS "General comments about UTF modes" -.rs -.sp -1. Codepoints less than 256 can be specified by either braced or unbraced -hexadecimal escape sequences (for example, \ex{b3} or \exb3). Larger values -have to use braced sequences. -.P -2. Octal numbers up to \e777 are recognized, and in UTF-8 mode, they match -two-byte characters for values greater than \e177. -.P -3. Repeat quantifiers apply to complete UTF characters, not to individual -data units, for example: \ex{100}{3}. -.P -4. The dot metacharacter matches one UTF character instead of a single data -unit. -.P -5. The escape sequence \eC can be used to match a single byte in UTF-8 mode, or -a single 16-bit data unit in UTF-16 mode, but its use can lead to some strange -effects because it breaks up multi-unit characters (see the description of \eC -in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation). The use of \eC is not supported in the alternative matching -function \fBpcre[16]_dfa_exec()\fP, nor is it supported in UTF mode by the JIT -optimization of \fBpcre[16]_exec()\fP. If JIT optimization is requested for a -UTF pattern that contains \eC, it will not succeed, and so the matching will -be carried out by the normal interpretive function. -.P -6. The character escapes \eb, \eB, \ed, \eD, \es, \eS, \ew, and \eW correctly -test characters of any code value, but, by default, the characters that PCRE -recognizes as digits, spaces, or word characters remain the same set as in -non-UTF mode, all with values less than 256. This remains true even when PCRE -is built to include Unicode property support, because to do otherwise would -slow down PCRE in many common cases. Note in particular that this applies to -\eb and \eB, because they are defined in terms of \ew and \eW. If you really -want to test for a wider sense of, say, "digit", you can use explicit Unicode -property tests such as \ep{Nd}. Alternatively, if you set the PCRE_UCP option, -the way that the character escapes work is changed so that Unicode properties -are used to determine which characters match. There are more details in the -section on -.\" HTML <a href="pcrepattern.html#genericchartypes"> -.\" </a> -generic character types -.\" -in the -.\" HREF -\fBpcrepattern\fP -.\" -documentation. -.P -7. Similarly, characters that match the POSIX named character classes are all -low-valued characters, unless the PCRE_UCP option is set. -.P -8. However, the horizontal and vertical white space matching escapes (\eh, \eH, -\ev, and \eV) do match all the appropriate Unicode characters, whether or not -PCRE_UCP is set. -.P -9. Case-insensitive matching applies only to characters whose values are less -than 128, unless PCRE is built with Unicode property support. Even when Unicode -property support is available, PCRE still uses its own character tables when -checking the case of low-valued characters, so as not to degrade performance. -The Unicode property information is used only for characters with higher -values. Furthermore, PCRE supports case-insensitive matching only when there is -a one-to-one mapping between a letter's cases. There are a small number of -many-to-one mappings in Unicode; these are not supported by PCRE. -. -. -.SH AUTHOR -.rs -.sp -.nf -Philip Hazel -University Computing Service -Cambridge CB2 3QH, England. -.fi -. -. -.SH REVISION -.rs -.sp -.nf -Last updated: 14 April 2012 -Copyright (c) 1997-2012 University of Cambridge. -.fi diff --git a/gtk+-mingw/share/man/man3/regex.3.gz b/gtk+-mingw/share/man/man3/regex.3.gz Binary files differdeleted file mode 100644 index edd45ad..0000000 --- a/gtk+-mingw/share/man/man3/regex.3.gz +++ /dev/null diff --git a/gtk+-mingw/share/man/man3/textdomain.3 b/gtk+-mingw/share/man/man3/textdomain.3 deleted file mode 100644 index a3568cd..0000000 --- a/gtk+-mingw/share/man/man3/textdomain.3 +++ /dev/null @@ -1,57 +0,0 @@ -.\" Copyright (c) Bruno Haible <haible@clisp.cons.org> -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 2 of -.\" the License, or (at your option) any later version. -.\" -.\" References consulted: -.\" GNU glibc-2 source code and manual -.\" GNU gettext source code and manual -.\" LI18NUX 2000 Globalization Specification -.\" -.TH TEXTDOMAIN 3 "May 2001" "GNU gettext 0.18.1" -.SH NAME -textdomain \- set domain for future gettext() calls -.SH SYNOPSIS -.nf -.B #include <libintl.h> -.sp -.BI "char * textdomain (const char * " domainname ); -.fi -.SH DESCRIPTION -The \fBtextdomain\fP function sets or retrieves the current message domain. -.PP -A message domain is a set of translatable \fImsgid\fP messages. Usually, -every software package has its own message domain. The domain name is used -to determine the message catalog where a translation is looked up; it must -be a non-empty string. -.PP -The current message domain is used by the \fBgettext\fP, \fBngettext\fP -functions, and by the \fBdgettext\fP, \fBdcgettext\fP, \fBdngettext\fP and -\fBdcngettext\fP functions when called with a NULL domainname argument. -.PP -If \fIdomainname\fP is not NULL, the current message domain is set to -\fIdomainname\fP. The string the function stores internally is a copy of the -\fIdomainname\fP argument. -.PP -If \fIdomainname\fP is NULL, the function returns the current message domain. -.SH "RETURN VALUE" -If successful, the \fBtextdomain\fP function returns the current message -domain, after possibly changing it. The resulting string is valid until the -next \fBtextdomain\fP call and must not be modified or freed. If a memory -allocation failure occurs, it sets \fBerrno\fP to \fBENOMEM\fP and returns -NULL. -.SH ERRORS -The following error can occur, among others: -.TP -.B ENOMEM -Not enough memory available. -.SH BUGS -The return type ought to be \fBconst char *\fP, but is \fBchar *\fP to avoid -warnings in C code predating ANSI C. -.SH "SEE ALSO" -.BR gettext (3), -.BR ngettext (3), -.BR bindtextdomain (3), -.BR bind_textdomain_codeset (3) |