shithub: riscv

--- a/.hgignore

+++ b/.hgignore

@@ -1,7 +1,6 @@

 syntax: regexp

-\.[ao]?[12578vqki]?$

-\.(pyo|pyc|exe)$

-^\.dummy$

+^sys/src/.*\.[ao]?[12578vqki]?$

+^sys/lib/python/.*\.(pyo|pyc|exe)$

 ^(dev|fd|net|srv|env|root|mnt|n)/

 ^(386|68000|68020|alpha|amd64|arm|power|power64|sparc|sparc64)/(bin|lib)/

 ^acme/bin/(386|68000|68020|alpha|amd64|arm|power|power64|sparc|sparc64)/

--- a/sys/src/ape/cmd/patch/patch.1

+++ /dev/null

@@ -1,1064 +1,0 @@

-.\" patch man page

-.de Id

-.ds Dt \\$4

-..

-.Id $Id: patch.man,v 1.23 1997/07/16 12:26:36 eggert Exp $

-.ds = \-\^\-

-.de Sp

-.if t .sp .3

-.if n .sp

-..

-.TH PATCH 1 \*(Dt GNU

-.ta 3n

-.SH NAME

-patch \- apply a diff file to an original

-.SH SYNOPSIS

-.B patch

-.RI [ options ]

-.RI [ originalfile

-.RI [ patchfile ]]

-.Sp

-but usually just

-.Sp

-.BI "patch \-p" "num"

-.BI < patchfile

-.SH DESCRIPTION

-.B patch

-takes a patch file

-.I patchfile

-containing a difference listing produced by the

-.B diff

-program and applies those differences to one or more original files,

-producing patched versions.

-Normally the patched versions are put in place of the originals.

-Backups can be made; see the

-.B \-b

-or

-.B \*=backup

-option.

-The names of the files to be patched are usually taken from the patch file,

-but if there's just one file to be patched it can specified on the

-command line as

-.IR originalfile .

-.PP

-Upon startup, patch attempts to determine the type of the diff listing,

-unless overruled by a

-\fB\-c\fP (\fB\*=context\fP),

-\fB\-e\fP (\fB\*=ed\fP),

-\fB\-n\fP (\fB\*=normal\fP),

-or

-\fB\-u\fP (\fB\*=unified\fP)

-option.

-Context diffs (old-style, new-style, and unified) and

-normal diffs are applied by the

-.B patch

-program itself, while

-.B ed

-diffs are simply fed to the

-.BR ed (1)

-editor via a pipe.

-.PP

-.B patch

-tries to skip any leading garbage, apply the diff,

-and then skip any trailing garbage.

-Thus you could feed an article or message containing a

-diff listing to

-.BR patch ,

-and it should work.

-If the entire diff is indented by a consistent amount,

-or if a context diff is encapsulated one or more times by prepending

-"\fB\- \fP" to lines starting with "\fB\-\fP" as specified by Internet RFC 934,

-this is taken into account.

-.PP

-With context diffs, and to a lesser extent with normal diffs,

-.B patch

-can detect when the line numbers mentioned in the patch are incorrect,

-and attempts to find the correct place to apply each hunk of the patch.

-As a first guess, it takes the line number mentioned for the hunk, plus or

-minus any offset used in applying the previous hunk.

-If that is not the correct place,

-.B patch

-scans both forwards and backwards for a set of lines matching the context

-given in the hunk.

-First

-.B patch

-looks for a place where all lines of the context match.

-If no such place is found, and it's a context diff, and the maximum fuzz factor

-is set to 1 or more, then another scan takes place ignoring the first and last

-line of context.

-If that fails, and the maximum fuzz factor is set to 2 or more,

-the first two and last two lines of context are ignored,

-and another scan is made.

-(The default maximum fuzz factor is 2.)

-If

-.B patch

-cannot find a place to install that hunk of the patch, it puts the

-hunk out to a reject file, which normally is the name of the output file

-plus a

-.B \&.rej

-suffix, or

-.B #

-if

-.B \&.rej

-would generate a file name that is too long

-(if even appending the single character

-.B #

-makes the file name too long, then

-.B #

-replaces the file name's last character).

-(The rejected hunk comes out in ordinary context diff form regardless of

-the input patch's form.

-If the input was a normal diff, many of the contexts are simply null.)

-The line numbers on the hunks in the reject file may be different than

-in the patch file: they reflect the approximate location patch thinks the

-failed hunks belong in the new file rather than the old one.

-.PP

-As each hunk is completed, you are told if the hunk

-failed, and if so which line (in the new file)

-.B patch

-thought the hunk should go on.

-If the hunk is installed at a different line

-from the line number specified in the diff you

-are told the offset.

-A single large offset

-.I may

-indicate that a hunk was installed in the

-wrong place.

-You are also told if a fuzz factor was used to make the match, in which

-case you should also be slightly suspicious.

-If the

-.B \*=verbose

-option is given, you are also told about hunks that match exactly.

-.PP

-If no original file

-.I origfile

-is specified on the command line,

-.B patch

-tries to figure out from the leading garbage what the name of the file

-to edit is, using the following rules.

-.TP 3

-.B " \(bu"

-If the header is that of a context diff,

-.B patch

-takes the old and new file names in the header.

-Any

-.B /dev/null

-names are ignored.

-.TP

-.B " \(bu"

-If there is an

-.B Index:\&

-line in the leading garbage

-and if either the old and new names are both absent or the

-.B POSIXLY_CORRECT

-environment variable is set,

-.B patch

-takes the name in the

-.B Index:\&

-line.

-.TP

-.B " \(bu"

-For the purpose of the following rules,

-the names are considered to be in the order (old, new, index),

-regardless of the order that they appear in the header.

-.TP

-.B " \(bu"

-If some of the named files exist,

-.B patch

-uses the first name if the

-.B POSIXLY_CORRECT

-environment variable is set, and the best name otherwise.

-.TP

-.B " \(bu"

-If

-.B patch

-is not ignoring \s-1RCS\s0 and \s-1SCCS\s0 (see the

-.BI "\-g\ " num

-or

-.BI \*=get= num

-option), and no named files exist

-but an \s-1RCS\s0 or \s-1SCCS\s0 master is found,

-.B patch

-uses the first named file with an \s-1RCS\s0 or \s-1SCCS\s0 master.

-.TP

-.B " \(bu"

-If no named files exist, no \s-1RCS\s0 or \s-1SCCS\s0 master was found,

-some names are given,

-.B POSIXLY_CORRECT

-is not set, and the patch appears to create a file,

-.B patch

-uses the best name requiring the creation of the fewest directories.

-.TP

-.B " \(bu"

-If no file name results from the above heuristics, you are asked

-for the name of the file to patch.

-.LP

-To determine the

-.I best

-of a nonempty list of file names,

-.B patch

-first takes all the names with the fewest path name components;

-of those, it then takes all the names with the shortest basename;

-of those, it then takes all the shortest names;

-finally, it takes the first remaining name.

-.PP

-Additionally, if the leading garbage contains a

-.B Prereq:\&

-line,

-.B patch

-takes the first word from the prerequisites line (normally a version

-number) and checks the original file to see if that word can be found.

-If not,

-.B patch

-asks for confirmation before proceeding.

-.PP

-The upshot of all this is that you should be able to say, while in a news

-interface, something like the following:

-.Sp

-	\fB| patch \-d /usr/src/local/blurfl\fP

-.Sp

-and patch a file in the

-.B blurfl

-directory directly from the article containing

-the patch.

-.PP

-If the patch file contains more than one patch,

-.B patch

-tries to apply each of them as if they came from separate patch files.

-This means, among other things, that it is assumed that the name of the file

-to patch must be determined for each diff listing,

-and that the garbage before each diff listing

-contains interesting things such as file names and revision level, as

-mentioned previously.

-.SH OPTIONS

-.TP 3

-\fB\-b\fP  or  \fB\*=backup\fP

-Make backup files.

-That is, when patching a file,

-rename or copy the original instead of removing it.

-When backing up a file that does not exist,

-an empty, unreadable backup file is created

-as a placeholder to represent the nonexistent file.

-See the

-.B \-V

-or

-.B \*=version\-control

-option for details about how backup file names are determined.

-.TP

-.B \*=backup\-if\-mismatch

-Back up a file if the patch does not match the file exactly

-and if backups are not otherwise requested.

-This is the default unless the

-.B POSIXLY_CORRECT

-environment variable is set.

-.TP

-.B \*=no\-backup\-if\-mismatch

-Do not back up a file if the patch does not match the file exactly

-and if backups are not otherwise requested.

-This is the default if the

-.B POSIXLY_CORRECT

-environment variable is set.

-.TP

-\fB\-B\fP \fIpref\fP  or  \fB\*=prefix=\fP\fIpref\fP

-Prefix

-.I pref

-to a file name when generating its simple backup file name.

-For example, with

-.B "\-B\ /junk/"

-the simple backup file name for

-.B src/patch/util.c

-is

-.BR /junk/src/patch/util.c .

-.TP

-\fB\*=binary\fP

-Read and write all files in binary mode,

-except for standard output and

-.BR /dev/tty .

-This option has no effect on \s-1POSIX\s0-compliant systems.

-On systems like \s-1DOS\s0 where this option makes a difference,

-the patch should be generated by

-.BR "diff\ \-a\ \*=binary" .

-.TP

-\fB\-c\fP  or  \fB\*=context\fP

-Interpret the patch file as a ordinary context diff.

-.TP

-\fB\-d\fP \fIdir\fP  or  \fB\*=directory=\fP\fIdir\fP

-Change to the directory

-.I dir

-immediately, before doing

-anything else.

-.TP

-\fB\-D\fP \fIdefine\fP  or  \fB\*=ifdef=\fP\fIdefine\fP

-Use the

-.BR #ifdef " .\|.\|. " #endif

-construct to mark changes, with

-.I define

-as the differentiating symbol.

-.TP

-.B "\*=dry\-run"

-Print the results of applying the patches without actually changing any files.

-.TP

-\fB\-e\fP  or  \fB\*=ed\fP

-Interpret the patch file as an

-.B ed

-script.

-.TP

-\fB\-E\fP  or  \fB\*=remove\-empty\-files\fP

-Remove output files that are empty after the patches have been applied.

-Normally this option is unnecessary, since

-.B patch

-can examine the time stamps on the header to determine whether a file

-should exist after patching.

-However, if the input is not a context diff or if the

-.B POSIXLY_CORRECT

-environment variable is set,

-.B patch

-does not remove empty patched files unless this option is given.

-When

-.B patch

-removes a file, it also attempts to remove any empty ancestor directories.

-.TP

-\fB\-f\fP  or  \fB\*=force\fP

-Assume that the user knows exactly what he or she is doing, and do not

-ask any questions.  Skip patches whose headers

-do not say which file is to be patched; patch files even though they have the

-wrong version for the

-.B Prereq:\&

-line in the patch; and assume that

-patches are not reversed even if they look like they are.

-This option does not suppress commentary; use

-.B \-s

-for that.

-.TP

-\fB\-F\fP \fInum\fP  or  \fB\*=fuzz=\fP\fInum\fP

-Set the maximum fuzz factor.

-This option only applies to diffs that have context, and causes

-.B patch

-to ignore up to that many lines in looking for places to install a hunk.

-Note that a larger fuzz factor increases the odds of a faulty patch.

-The default fuzz factor is 2, and it may not be set to more than

-the number of lines of context in the context diff, ordinarily 3.

-.TP

-\fB\-g\fP \fInum\fP  or  \fB\*=get=\fP\fInum\fP

-This option controls

-.BR patch 's

-actions when a file is under \s-1RCS\s0 or \s-1SCCS\s0 control,

-and does not exist or is read-only and matches the default version.

-If

-.I num

-is positive,

-.B patch

-gets (or checks out) the file from the revision control system; if zero,

-.B patch

-ignores \s-1RCS\s0 and \s-1SCCS\s0 and does not get the file; and if negative,

-.B patch

-asks the user whether to get the file.

-The default value of this option is given by the value of the

-.B PATCH_GET

-environment variable if it is set; if not, the default value is zero if

-.B POSIXLY_CORRECT

-is set, negative otherwise.

-.TP

-.B "\*=help"

-Print a summary of options and exit.

-.TP

-\fB\-i\fP \fIpatchfile\fP  or  \fB\*=input=\fP\fIpatchfile\fP

-Read the patch from

-.IR patchfile .

-If

-.I patchfile

-is

-.BR \- ,

-read from standard input, the default.

-.TP

-\fB\-l\fP  or  \fB\*=ignore\-whitespace\fP

-Match patterns loosely, in case tabs or spaces

-have been munged in your files.

-Any sequence of one or more blanks in the patch file matches any sequence

-in the original file, and sequences of blanks at the ends of lines are ignored.

-Normal characters must still match exactly.

-Each line of the context must still match a line in the original file.

-.TP

-\fB\-n\fP  or  \fB\*=normal\fP

-Interpret the patch file as a normal diff.

-.TP

-\fB\-N\fP  or  \fB\*=forward\fP

-Ignore patches that seem to be reversed or already applied.

-See also

-.BR \-R .

-.TP

-\fB\-o\fP \fIoutfile\fP  or  \fB\*=output=\fP\fIoutfile\fP

-Send output to

-.I outfile

-instead of patching files in place.

-.TP

-\fB\-p\fP\fInum\fP  or  \fB\*=strip\fP\fB=\fP\fInum\fP

-Strip the smallest prefix containing

-.I num

-leading slashes from each file name found in the patch file.

-A sequence of one or more adjacent slashes is counted as a single slash.

-This controls how file names found in the patch file are treated, in case

-you keep your files in a different directory than the person who sent

-out the patch.

-For example, supposing the file name in the patch file was

-.Sp

-	\fB/u/howard/src/blurfl/blurfl.c\fP

-.Sp

-setting

-.B \-p0

-gives the entire file name unmodified,

-.B \-p1

-gives

-.Sp

-	\fBu/howard/src/blurfl/blurfl.c\fP

-.Sp

-without the leading slash,

-.B \-p4

-gives

-.Sp

-	\fBblurfl/blurfl.c\fP

-.Sp

-and not specifying

-.B \-p

-at all just gives you \fBblurfl.c\fP.

-Whatever you end up with is looked for either in the current directory,

-or the directory specified by the

-.B \-d

-option.

-.TP

-\fB\-r\fP \fIrejectfile\fP  or  \fB\*=reject\-file=\fP\fIrejectfile\fP

-Put rejects into

-.I rejectfile

-instead of the default

-.B \&.rej

-file.

-.TP

-\fB\-R\fP  or  \fB\*=reverse\fP

-Assume that this patch was created with the old and new files swapped.

-(Yes, I'm afraid that does happen occasionally, human nature being what it

-is.)

-.B patch

-attempts to swap each hunk around before applying it.

-Rejects come out in the swapped format.

-The

-.B \-R

-option does not work with

-.B ed

-diff scripts because there is too little

-information to reconstruct the reverse operation.

-.Sp

-If the first hunk of a patch fails,

-.B patch

-reverses the hunk to see if it can be applied that way.

-If it can, you are asked if you want to have the

-.B \-R

-option set.

-If it can't, the patch continues to be applied normally.

-(Note: this method cannot detect a reversed patch if it is a normal diff

-and if the first command is an append (i.e. it should have been a delete)

-since appends always succeed, due to the fact that a null context matches

-anywhere.

-Luckily, most patches add or change lines rather than delete them, so most

-reversed normal diffs begin with a delete, which fails, triggering

-the heuristic.)

-.TP

-\fB\-s\fP  or  \fB\*=silent\fP  or  \fB\*=quiet\fP

-Work silently, unless an error occurs.

-.TP

-\fB\-t\fP  or  \fB\*=batch\fP

-Suppress questions like

-.BR \-f ,

-but make some different assumptions:

-skip patches whose headers do not contain file names (the same as \fB\-f\fP);

-skip patches for which the file has the wrong version for the

-.B Prereq:\&

-line

-in the patch; and assume that patches are reversed if they look like

-they are.

-.TP

-\fB\-T\fP  or  \fB\*=set\-time\fP

-Set the modification and access times of patched files from time stamps

-given in context diff headers, assuming that the context diff headers

-use local time.  This option is not recommended, because patches using

-local time cannot easily be used by people in other time zones, and

-because local time stamps are ambiguous when local clocks move backwards

-during daylight-saving time adjustments.  Instead of using this option,

-generate patches with \s-1UTC\s0 and use the

-.B \-Z

-or

-.B \*=set\-utc

-option instead.

-.TP

-\fB\-u\fP  or  \fB\*=unified\fP

-Interpret the patch file as a unified context diff.

-.TP

-\fB\-v\fP  or  \fB\*=version\fP

-Print out

-.BR patch 's

-revision header and patch level, and exit.

-.TP

-\fB\-V\fP \fImethod\fP  or  \fB\*=version\-control=\fP\fImethod\fP

-Use

-.I method

-to determine

-backup file names.  The method can also be given by the

-.B PATCH_VERSION_CONTROL

-(or, if that's not set, the

-.BR VERSION_CONTROL )

-environment variable, which is overridden by this option.

-The method does not affect whether backup files are made;

-it affects only the names of any backup files that are made.

-.Sp

-The value of

-.I method

-is like the \s-1GNU\s0

-Emacs `version-control' variable;

-.B patch

-also recognizes synonyms that

-are more descriptive.  The valid values for

-.I method

-are (unique abbreviations are

-accepted):

-.RS

-.TP 3

-\fBexisting\fP  or  \fBnil\fP

-Make numbered backups of files that already have them,

-otherwise simple backups.

-This is the default.

-.TP

-\fBnumbered\fP  or  \fBt\fP

-Make numbered backups.  The numbered backup file name for

-.I F

-is

-.IB F .~ N ~

-where

-.I N

-is the version number.

-.TP

-\fBsimple\fP  or  \fBnever\fP

-Make simple backups.

-The

-.B \-B

-or

-.BR \*=prefix ,

-.B \-Y

-or

-.BR \*=basename\-prefix ,

-and

-.B \-z

-or

-.BR \*=suffix

-options specify the simple backup file name.

-If none of these options are given, then a simple backup suffix is used;

-it is the value of the

-.B SIMPLE_BACKUP_SUFFIX

-environment variable if set, and is

-.B \&.orig

-otherwise.

-.PP

-With numbered or simple backups,

-if the backup file name is too long, the backup suffix

-.B ~

-is used instead; if even appending

-.B ~

-would make the name too long, then

-.B ~

-replaces the last character of the file name.

-.RE

-.TP

-\fB\*=verbose\fP

-Output extra information about the work being done.

-.TP

-\fB\-x\fP \fInum\fP  or  \fB\*=debug=\fP\fInum\fP

-Set internal debugging flags of interest only to

-.B patch

-patchers.

-.TP

-\fB\-Y\fP \fIpref\fP  or  \fB\*=basename\-prefix=\fP\fIpref\fP

-Prefix

-.I pref

-to the basename of a file name when generating its simple backup file name.

-For example, with

-.B "\-Y\ .del/"

-the simple backup file name for

-.B src/patch/util.c

-is

-.BR src/patch/.del/util.c .

-.TP

-\fB\-z\fP \fIsuffix\fP  or  \fB\*=suffix=\fP\fIsuffix\fP

-Use

-.I suffix

-as the simple backup suffix.

-For example, with

-.B "\-z\ -"

-the simple backup file name for

-.B src/patch/util.c

-is

-.BR src/patch/util.c- .

-The backup suffix may also be specified by the

-.B SIMPLE_BACKUP_SUFFIX

-environment variable, which is overridden by this option.

-.TP

-\fB\-Z\fP  or  \fB\*=set\-utc\fP

-Set the modification and access times of patched files from time stamps

-given in context diff headers, assuming that the context diff headers

-use Coordinated Universal Time (\s-1UTC\s0, often known as \s-1GMT\s0).

-Also see the

-.B \-T

-or

-.B \*=set\-time

-option.

-.Sp

-The

-.B \-Z

-or

-.B \*=set\-utc

-and

-.B \-T

-or

-.B \*=set\-time

-options normally refrain from setting a file's time if the file's original time

-does not match the time given in the patch header, or if its

-contents do not match the patch exactly.  However, if the

-.B \-f

-or

-.B \*=force

-option is given, the file time is set regardless.

-.Sp

-Due to the limitations of

-.B diff

-output format, these options cannot update the times of files whose

-contents have not changed.  Also, if you use these options, you should remove

-(e.g. with

-.BR "make\ clean" )

-all files that depend on the patched files, so that later invocations of

-.B make

-do not get confused by the patched files' times.

-.SH ENVIRONMENT

-.TP 3

-\fBPATCH_GET\fP

-This specifies whether

-.B patch

-gets missing or read-only files from \s-1RCS\s0 or \s-1SCCS\s0

-by default; see the

-.B \-g

-or

-.B \*=get

-option.

-.TP

-.B POSIXLY_CORRECT

-If set,

-.B patch

-conforms more strictly to the \s-1POSIX\s0 standard:

-it takes the first existing file from the list (old, new, index)

-when intuiting file names from diff headers,

-it does not remove files that are empty after patching,

-it does not ask whether to get files from \s-1RCS\s0 or \s-1SCCS\s0,

-it requires that all options precede the files in the command line,

-and it does not backup files when there is a mismatch.

-.TP

-.B SIMPLE_BACKUP_SUFFIX

-Extension to use for simple backup file names instead of

-.BR \&.orig .

-.TP

-\fBTMPDIR\fP, \fBTMP\fP, \fBTEMP\fP

-Directory to put temporary files in;

-.B patch

-uses the first environment variable in this list that is set.

-If none are set, the default is system-dependent;

-it is normally

-.B /tmp

-on Unix hosts.

-.TP

-\fBVERSION_CONTROL\fP or \fBPATCH_VERSION_CONTROL\fP

-Selects version control style; see the

-.B \-v

-or

-.B \*=version\-control

-option.

-.SH FILES

-.TP 3

-.IB $TMPDIR "/p\(**"

-temporary files

-.TP

-.B /dev/tty

-controlling terminal; used to get answers to questions asked of the user

-.SH "SEE ALSO"

-.BR diff (1),

-.BR ed (1)

-.Sp

-Marshall T. Rose and Einar A. Stefferud,

-Proposed Standard for Message Encapsulation,

-Internet RFC 934 <URL:ftp://ftp.isi.edu/in-notes/rfc934.txt> (1985-01).

-.SH "NOTES FOR PATCH SENDERS"

-There are several things you should bear in mind if you are going to

-be sending out patches.

-.PP

-Create your patch systematically.

-A good method is the command

-.BI "diff\ \-Naur\ " "old\ new"

-where

-.I old

-and

-.I new

-identify the old and new directories.

-The names

-.I old

-and

-.I new

-should not contain any slashes.

-The

-.B diff

-command's headers should have dates

-and times in Universal Time using traditional Unix format,

-so that patch recipients can use the

-.B \-Z

-or

-.B \*=set\-utc

-option.

-Here is an example command, using Bourne shell syntax:

-.Sp

-	\fBLC_ALL=C TZ=UTC0 diff \-Naur gcc\-2.7 gcc\-2.8\fP

-.PP

-Tell your recipients how to apply the patch

-by telling them which directory to

-.B cd

-to, and which

-.B patch

-options to use.  The option string

-.B "\-Np1"

-is recommended.

-Test your procedure by pretending to be a recipient and applying

-your patch to a copy of the original files.

-.PP

-You can save people a lot of grief by keeping a

-.B patchlevel.h

-file which is patched to increment the patch level

-as the first diff in the patch file you send out.

-If you put a

-.B Prereq:\&

-line in with the patch, it won't let them apply

-patches out of order without some warning.

-.PP

-You can create a file by sending out a diff that compares

-.B /dev/null

-or an empty file dated the Epoch (1970-01-01 00:00:00 \s-1UTC\s0)

-to the file you want to create.

-This only works if the file you want to create doesn't exist already in

-the target directory.

-Conversely, you can remove a file by sending out a context diff that compares

-the file to be deleted with an empty file dated the Epoch.

-The file will be removed unless the

-.B POSIXLY_CORRECT

-environment variable is set and the

-.B \-E

-or

-.B \*=remove\-empty\-files

-option is not given.

-An easy way to generate patches that create and remove files

-is to use \s-1GNU\s0

-.BR diff 's

-.B \-N

-or

-.B \*=new\-file

-option.

-.PP

-If the recipient is supposed to use the

-.BI \-p N

-option, do not send output that looks like this:

-.Sp

-.ft B

-.ne 3

-	diff \-Naur v2.0.29/prog/README prog/README

-.br

-	\-\^\-\^\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997

-.br

-	+\^+\^+ prog/README   Mon Mar 17 14:58:22 1997

-.ft

-.Sp

-because the two file names have different numbers of slashes,

-and different versions of

-.B patch

-interpret the file names differently.

-To avoid confusion, send output that looks like this instead:

-.Sp

-.ft B

-.ne 3

-	diff \-Naur v2.0.29/prog/README v2.0.30/prog/README

-.br

-	\-\^\-\^\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997

-.br

-	+\^+\^+ v2.0.30/prog/README   Mon Mar 17 14:58:22 1997

-.ft

-.Sp

-.PP

-Avoid sending patches that compare backup file names like

-.BR README.orig ,

-since this might confuse

-.B patch

-into patching a backup file instead of the real file.

-Instead, send patches that compare the same base file names

-in different directories, e.g.\&

-.B old/README

-and

-.BR new/README .

-.PP

-Take care not to send out reversed patches, since it makes people wonder

-whether they already applied the patch.

-.PP

-Try not to have your patch modify derived files

-(e.g. the file

-.B configure

-where there is a line

-.B "configure: configure.in"

-in your makefile), since the recipient should be

-able to regenerate the derived files anyway.

-If you must send diffs of derived files,

-generate the diffs using \s-1UTC\s0,

-have the recipients apply the patch with the

-.B \-Z

-or

-.B \*=set\-utc

-option, and have them remove any unpatched files that depend on patched files

-(e.g. with

-.BR "make\ clean" ).

-.PP

-While you may be able to get away with putting 582 diff listings into

-one file, it may be wiser to group related patches into separate files in

-case something goes haywire.

-.SH DIAGNOSTICS

-Diagnostics generally indicate that

-.B patch

-couldn't parse your patch file.

-.PP

-If the

-.B \*=verbose

-option is given, the message

-.B Hmm.\|.\|.\&

-indicates that there is unprocessed text in

-the patch file and that

-.B patch

-is attempting to intuit whether there is a patch in that text and, if so,

-what kind of patch it is.

-.PP

-.BR patch 's

-exit status is

-0 if all hunks are applied successfully,

-1 if some hunks cannot be applied,

-and 2 if there is more serious trouble.

-When applying a set of patches in a loop it behooves you to check this

-exit status so you don't apply a later patch to a partially patched file.

-.SH CAVEATS

-Context diffs cannot reliably represent the creation or deletion of

-empty files, empty directories, or special files such as symbolic links.

-Nor can they represent changes to file metadata like ownership, permissions,

-or whether one file is a hard link to another.

-If changes like these are also required, separate instructions

-(e.g. a shell script) to accomplish them should accompany the patch.

-.PP

-.B patch

-cannot tell if the line numbers are off in an

-.B ed

-script, and can detect

-bad line numbers in a normal diff only when it finds a change or deletion.

-A context diff using fuzz factor 3 may have the same problem.

-Until a suitable interactive interface is added, you should probably do

-a context diff in these cases to see if the changes made sense.

-Of course, compiling without errors is a pretty good indication that the patch

-worked, but not always.

-.PP

-.B patch

-usually produces the correct results, even when it has to do a lot of

-guessing.

-However, the results are guaranteed to be correct only when the patch is

-applied to exactly the same version of the file that the patch was

-generated from.

-.SH "COMPATIBILITY ISSUES"

-The \s-1POSIX\s0 standard specifies behavior that differs from

-.BR patch 's

-traditional behavior.

-You should be aware of these differences if you must interoperate with

-.B patch

-versions 2.1 and earlier, which are not \s-1POSIX\s0-compliant.

-.TP 3

-.B " \(bu"

-In traditional

-.BR patch ,

-the

-.B \-p

-option's operand was optional, and a bare

-.B \-p

-was equivalent to

-.BR \-p0.

-The

-.B \-p

-option now requires an operand, and

-.B "\-p\ 0"

-is now equivalent to

-.BR \-p0 .

-For maximum compatibility, use options like

-.B \-p0

-and

-.BR \-p1 .

-.Sp

-Also,

-traditional

-.B patch

-simply counted slashes when stripping path prefixes;

-.B patch

-now counts pathname components.

-That is, a sequence of one or more adjacent slashes

-now counts as a single slash.

-For maximum portability, avoid sending patches containing

-.B //

-in file names.

-.TP

-.B " \(bu"

-In traditional

-.BR patch ,

-backups were enabled by default.

-This behavior is now enabled with the

-.B \-b

-or

-.B \*=backup

-option.

-.Sp

-Conversely, in \s-1POSIX\s0

-.BR patch ,

-backups are never made, even when there is a mismatch.

-In \s-1GNU\s0

-.BR patch ,

-this behavior is enabled with the

-.B \*=no\-backup\-if\-mismatch

-option or by setting the

-.B POSIXLY_CORRECT

-environment variable.

-.Sp

-The

-.BI \-b "\ suffix"

-option

-of traditional

-.B patch

-is equivalent to the

-.BI "\-b\ \-z" "\ suffix"

-options of \s-1GNU\s0

-.BR patch .

-.TP

-.B " \(bu"

-Traditional

-.B patch

-used a complicated (and incompletely documented) method

-to intuit the name of the file to be patched from the patch header.

-This method was not \s-1POSIX\s0-compliant, and had a few gotchas.

-Now

-.B patch

-uses a different, equally complicated (but better documented) method

-that is optionally \s-1POSIX\s0-compliant; we hope it has

-fewer gotchas.  The two methods are compatible if the

-file names in the context diff header and the

-.B Index:\&

-line are all identical after prefix-stripping.

-Your patch is normally compatible if each header's file names

-all contain the same number of slashes.

-.TP

-.B " \(bu"

-When traditional

-.B patch

-asked the user a question, it sent the question to standard error

-and looked for an answer from

-the first file in the following list that was a terminal:

-standard error, standard output,

-.BR /dev/tty ,

-and standard input.

-Now

-.B patch

-sends questions to standard output and gets answers from

-.BR /dev/tty .

-Defaults for some answers have been changed so that

-.B patch

-never goes into an infinite loop when using default answers.

-.TP

-.B " \(bu"

-Traditional

-.B patch

-exited with a status value that counted the number of bad hunks,

-or with status 1 if there was real trouble.

-Now

-.B patch

-exits with status 1 if some hunks failed,

-or with 2 if there was real trouble.

-.TP

-.B " \(bu"

-Limit yourself to the following options when sending instructions

-meant to be executed by anyone running \s-1GNU\s0

-.BR patch ,

-traditional

-.BR patch ,

-or a \s-1POSIX\s0-compliant

-.BR patch .

-Spaces are significant in the following list, and operands are required.

-.Sp

-.nf

-.in +3

-.ne 11

-.B \-c

-.BI \-d " dir"

-.BI \-D " define"

-.B \-e

-.B \-l

-.B \-n

-.B \-N

-.BI \-o " outfile"

-.BI \-p num

-.B \-R

-.BI \-r " rejectfile"

-.in

-.fi

-.SH BUGS

-.B patch

-could be smarter about partial matches, excessively deviant offsets and

-swapped code, but that would take an extra pass.

-.PP

-If code has been duplicated (for instance with

-\fB#ifdef OLDCODE\fP .\|.\|. \fB#else .\|.\|. #endif\fP),

-.B patch

-is incapable of patching both versions, and, if it works at all, will likely

-patch the wrong one, and tell you that it succeeded to boot.

-.PP

-If you apply a patch you've already applied,

-.B patch

-thinks it is a reversed patch, and offers to un-apply the patch.

-This could be construed as a feature.

-.SH COPYING

-Copyright

-.if t \(co

-1984, 1985, 1986, 1988 Larry Wall.

-.br

-Copyright

-.if t \(co

-1997 Free Software Foundation, Inc.

-.PP

-Permission is granted to make and distribute verbatim copies of

-this manual provided the copyright notice and this permission notice

-are preserved on all copies.

-.PP

-Permission is granted to copy and distribute modified versions of this

-manual under the conditions for verbatim copying, provided that the

-entire resulting derived work is distributed under the terms of a

-permission notice identical to this one.

-.PP

-Permission is granted to copy and distribute translations of this

-manual into another language, under the above conditions for modified

-versions, except that this permission notice may be included in

-translations approved by the copyright holders instead of in

-the original English.

-.SH AUTHORS

-Larry Wall wrote the original version of

-.BR patch .

-Paul Eggert removed

-.BR patch 's

-arbitrary limits; added support for binary files,

-setting file times, and deleting files;

-and made it conform better to \s-1POSIX\s0.

-Other contributors include Wayne Davison, who added unidiff support,

-and David MacKenzie, who added configuration and backup support.

--- /dev/null

+++ b/sys/src/ape/cmd/patch/patch.1.man

@@ -1,0 +1,1064 @@

+.\" patch man page

+.de Id

+.ds Dt \\$4

+..

+.Id $Id: patch.man,v 1.23 1997/07/16 12:26:36 eggert Exp $

+.ds = \-\^\-

+.de Sp

+.if t .sp .3

+.if n .sp

+..

+.TH PATCH 1 \*(Dt GNU

+.ta 3n

+.SH NAME

+patch \- apply a diff file to an original

+.SH SYNOPSIS

+.B patch

+.RI [ options ]

+.RI [ originalfile

+.RI [ patchfile ]]

+.Sp

+but usually just

+.Sp

+.BI "patch \-p" "num"

+.BI < patchfile

+.SH DESCRIPTION

+.B patch

+takes a patch file

+.I patchfile

+containing a difference listing produced by the

+.B diff

+program and applies those differences to one or more original files,

+producing patched versions.

+Normally the patched versions are put in place of the originals.

+Backups can be made; see the

+.B \-b

+or

+.B \*=backup

+option.

+The names of the files to be patched are usually taken from the patch file,

+but if there's just one file to be patched it can specified on the

+command line as

+.IR originalfile .

+.PP

+Upon startup, patch attempts to determine the type of the diff listing,

+unless overruled by a

+\fB\-c\fP (\fB\*=context\fP),

+\fB\-e\fP (\fB\*=ed\fP),

+\fB\-n\fP (\fB\*=normal\fP),

+or

+\fB\-u\fP (\fB\*=unified\fP)

+option.

+Context diffs (old-style, new-style, and unified) and

+normal diffs are applied by the

+.B patch

+program itself, while

+.B ed

+diffs are simply fed to the

+.BR ed (1)

+editor via a pipe.

+.PP

+.B patch

+tries to skip any leading garbage, apply the diff,

+and then skip any trailing garbage.

+Thus you could feed an article or message containing a

+diff listing to

+.BR patch ,

+and it should work.

+If the entire diff is indented by a consistent amount,

+or if a context diff is encapsulated one or more times by prepending

+"\fB\- \fP" to lines starting with "\fB\-\fP" as specified by Internet RFC 934,

+this is taken into account.

+.PP

+With context diffs, and to a lesser extent with normal diffs,

+.B patch

+can detect when the line numbers mentioned in the patch are incorrect,

+and attempts to find the correct place to apply each hunk of the patch.

+As a first guess, it takes the line number mentioned for the hunk, plus or

+minus any offset used in applying the previous hunk.

+If that is not the correct place,

+.B patch

+scans both forwards and backwards for a set of lines matching the context

+given in the hunk.

+First

+.B patch

+looks for a place where all lines of the context match.

+If no such place is found, and it's a context diff, and the maximum fuzz factor

+is set to 1 or more, then another scan takes place ignoring the first and last

+line of context.

+If that fails, and the maximum fuzz factor is set to 2 or more,

+the first two and last two lines of context are ignored,

+and another scan is made.

+(The default maximum fuzz factor is 2.)

+If

+.B patch

+cannot find a place to install that hunk of the patch, it puts the

+hunk out to a reject file, which normally is the name of the output file

+plus a

+.B \&.rej

+suffix, or

+.B #

+if

+.B \&.rej

+would generate a file name that is too long

+(if even appending the single character

+.B #

+makes the file name too long, then

+.B #

+replaces the file name's last character).

+(The rejected hunk comes out in ordinary context diff form regardless of

+the input patch's form.

+If the input was a normal diff, many of the contexts are simply null.)

+The line numbers on the hunks in the reject file may be different than

+in the patch file: they reflect the approximate location patch thinks the

+failed hunks belong in the new file rather than the old one.

+.PP

+As each hunk is completed, you are told if the hunk

+failed, and if so which line (in the new file)

+.B patch

+thought the hunk should go on.

+If the hunk is installed at a different line

+from the line number specified in the diff you

+are told the offset.

+A single large offset

+.I may

+indicate that a hunk was installed in the

+wrong place.

+You are also told if a fuzz factor was used to make the match, in which

+case you should also be slightly suspicious.

+If the

+.B \*=verbose

+option is given, you are also told about hunks that match exactly.

+.PP

+If no original file

+.I origfile

+is specified on the command line,

+.B patch

+tries to figure out from the leading garbage what the name of the file

+to edit is, using the following rules.

+.TP 3

+.B " \(bu"

+If the header is that of a context diff,

+.B patch

+takes the old and new file names in the header.

+Any

+.B /dev/null

+names are ignored.

+.TP

+.B " \(bu"

+If there is an

+.B Index:\&

+line in the leading garbage

+and if either the old and new names are both absent or the

+.B POSIXLY_CORRECT

+environment variable is set,

+.B patch

+takes the name in the

+.B Index:\&

+line.

+.TP

+.B " \(bu"

+For the purpose of the following rules,

+the names are considered to be in the order (old, new, index),

+regardless of the order that they appear in the header.

+.TP

+.B " \(bu"

+If some of the named files exist,

+.B patch

+uses the first name if the

+.B POSIXLY_CORRECT

+environment variable is set, and the best name otherwise.

+.TP

+.B " \(bu"

+If

+.B patch

+is not ignoring \s-1RCS\s0 and \s-1SCCS\s0 (see the

+.BI "\-g\ " num

+or

+.BI \*=get= num

+option), and no named files exist

+but an \s-1RCS\s0 or \s-1SCCS\s0 master is found,

+.B patch

+uses the first named file with an \s-1RCS\s0 or \s-1SCCS\s0 master.

+.TP

+.B " \(bu"

+If no named files exist, no \s-1RCS\s0 or \s-1SCCS\s0 master was found,

+some names are given,

+.B POSIXLY_CORRECT

+is not set, and the patch appears to create a file,

+.B patch

+uses the best name requiring the creation of the fewest directories.

+.TP

+.B " \(bu"

+If no file name results from the above heuristics, you are asked

+for the name of the file to patch.

+.LP

+To determine the

+.I best

+of a nonempty list of file names,

+.B patch

+first takes all the names with the fewest path name components;

+of those, it then takes all the names with the shortest basename;

+of those, it then takes all the shortest names;

+finally, it takes the first remaining name.

+.PP

+Additionally, if the leading garbage contains a

+.B Prereq:\&

+line,

+.B patch

+takes the first word from the prerequisites line (normally a version

+number) and checks the original file to see if that word can be found.

+If not,

+.B patch

+asks for confirmation before proceeding.

+.PP

+The upshot of all this is that you should be able to say, while in a news

+interface, something like the following:

+.Sp

+	\fB| patch \-d /usr/src/local/blurfl\fP

+.Sp

+and patch a file in the

+.B blurfl

+directory directly from the article containing

+the patch.

+.PP

+If the patch file contains more than one patch,

+.B patch

+tries to apply each of them as if they came from separate patch files.

+This means, among other things, that it is assumed that the name of the file

+to patch must be determined for each diff listing,

+and that the garbage before each diff listing

+contains interesting things such as file names and revision level, as

+mentioned previously.

+.SH OPTIONS

+.TP 3

+\fB\-b\fP  or  \fB\*=backup\fP

+Make backup files.

+That is, when patching a file,

+rename or copy the original instead of removing it.

+When backing up a file that does not exist,

+an empty, unreadable backup file is created

+as a placeholder to represent the nonexistent file.

+See the

+.B \-V

+or

+.B \*=version\-control

+option for details about how backup file names are determined.

+.TP

+.B \*=backup\-if\-mismatch

+Back up a file if the patch does not match the file exactly

+and if backups are not otherwise requested.

+This is the default unless the

+.B POSIXLY_CORRECT

+environment variable is set.

+.TP

+.B \*=no\-backup\-if\-mismatch

+Do not back up a file if the patch does not match the file exactly

+and if backups are not otherwise requested.

+This is the default if the

+.B POSIXLY_CORRECT

+environment variable is set.

+.TP

+\fB\-B\fP \fIpref\fP  or  \fB\*=prefix=\fP\fIpref\fP

+Prefix

+.I pref

+to a file name when generating its simple backup file name.

+For example, with

+.B "\-B\ /junk/"

+the simple backup file name for

+.B src/patch/util.c

+is

+.BR /junk/src/patch/util.c .

+.TP

+\fB\*=binary\fP

+Read and write all files in binary mode,

+except for standard output and

+.BR /dev/tty .

+This option has no effect on \s-1POSIX\s0-compliant systems.

+On systems like \s-1DOS\s0 where this option makes a difference,

+the patch should be generated by

+.BR "diff\ \-a\ \*=binary" .

+.TP

+\fB\-c\fP  or  \fB\*=context\fP

+Interpret the patch file as a ordinary context diff.

+.TP

+\fB\-d\fP \fIdir\fP  or  \fB\*=directory=\fP\fIdir\fP

+Change to the directory

+.I dir

+immediately, before doing

+anything else.

+.TP

+\fB\-D\fP \fIdefine\fP  or  \fB\*=ifdef=\fP\fIdefine\fP

+Use the

+.BR #ifdef " .\|.\|. " #endif

+construct to mark changes, with

+.I define

+as the differentiating symbol.

+.TP

+.B "\*=dry\-run"

+Print the results of applying the patches without actually changing any files.

+.TP

+\fB\-e\fP  or  \fB\*=ed\fP

+Interpret the patch file as an

+.B ed

+script.

+.TP

+\fB\-E\fP  or  \fB\*=remove\-empty\-files\fP

+Remove output files that are empty after the patches have been applied.

+Normally this option is unnecessary, since

+.B patch

+can examine the time stamps on the header to determine whether a file

+should exist after patching.

+However, if the input is not a context diff or if the

+.B POSIXLY_CORRECT

+environment variable is set,

+.B patch

+does not remove empty patched files unless this option is given.

+When

+.B patch

+removes a file, it also attempts to remove any empty ancestor directories.

+.TP

+\fB\-f\fP  or  \fB\*=force\fP

+Assume that the user knows exactly what he or she is doing, and do not

+ask any questions.  Skip patches whose headers

+do not say which file is to be patched; patch files even though they have the

+wrong version for the

+.B Prereq:\&

+line in the patch; and assume that

+patches are not reversed even if they look like they are.

+This option does not suppress commentary; use

+.B \-s

+for that.

+.TP

+\fB\-F\fP \fInum\fP  or  \fB\*=fuzz=\fP\fInum\fP

+Set the maximum fuzz factor.

+This option only applies to diffs that have context, and causes

+.B patch

+to ignore up to that many lines in looking for places to install a hunk.

+Note that a larger fuzz factor increases the odds of a faulty patch.

+The default fuzz factor is 2, and it may not be set to more than

+the number of lines of context in the context diff, ordinarily 3.

+.TP

+\fB\-g\fP \fInum\fP  or  \fB\*=get=\fP\fInum\fP

+This option controls

+.BR patch 's

+actions when a file is under \s-1RCS\s0 or \s-1SCCS\s0 control,

+and does not exist or is read-only and matches the default version.

+If

+.I num

+is positive,

+.B patch

+gets (or checks out) the file from the revision control system; if zero,

+.B patch

+ignores \s-1RCS\s0 and \s-1SCCS\s0 and does not get the file; and if negative,

+.B patch

+asks the user whether to get the file.

+The default value of this option is given by the value of the

+.B PATCH_GET

+environment variable if it is set; if not, the default value is zero if

+.B POSIXLY_CORRECT

+is set, negative otherwise.

+.TP

+.B "\*=help"

+Print a summary of options and exit.

+.TP

+\fB\-i\fP \fIpatchfile\fP  or  \fB\*=input=\fP\fIpatchfile\fP

+Read the patch from

+.IR patchfile .

+If

+.I patchfile

+is

+.BR \- ,

+read from standard input, the default.

+.TP

+\fB\-l\fP  or  \fB\*=ignore\-whitespace\fP

+Match patterns loosely, in case tabs or spaces

+have been munged in your files.

+Any sequence of one or more blanks in the patch file matches any sequence

+in the original file, and sequences of blanks at the ends of lines are ignored.

+Normal characters must still match exactly.

+Each line of the context must still match a line in the original file.

+.TP

+\fB\-n\fP  or  \fB\*=normal\fP

+Interpret the patch file as a normal diff.

+.TP

+\fB\-N\fP  or  \fB\*=forward\fP

+Ignore patches that seem to be reversed or already applied.

+See also

+.BR \-R .

+.TP

+\fB\-o\fP \fIoutfile\fP  or  \fB\*=output=\fP\fIoutfile\fP

+Send output to

+.I outfile

+instead of patching files in place.

+.TP

+\fB\-p\fP\fInum\fP  or  \fB\*=strip\fP\fB=\fP\fInum\fP

+Strip the smallest prefix containing

+.I num

+leading slashes from each file name found in the patch file.

+A sequence of one or more adjacent slashes is counted as a single slash.

+This controls how file names found in the patch file are treated, in case

+you keep your files in a different directory than the person who sent

+out the patch.

+For example, supposing the file name in the patch file was

+.Sp

+	\fB/u/howard/src/blurfl/blurfl.c\fP

+.Sp

+setting

+.B \-p0

+gives the entire file name unmodified,

+.B \-p1

+gives

+.Sp

+	\fBu/howard/src/blurfl/blurfl.c\fP

+.Sp

+without the leading slash,

+.B \-p4

+gives

+.Sp

+	\fBblurfl/blurfl.c\fP

+.Sp

+and not specifying

+.B \-p

+at all just gives you \fBblurfl.c\fP.

+Whatever you end up with is looked for either in the current directory,

+or the directory specified by the

+.B \-d

+option.

+.TP

+\fB\-r\fP \fIrejectfile\fP  or  \fB\*=reject\-file=\fP\fIrejectfile\fP

+Put rejects into

+.I rejectfile

+instead of the default

+.B \&.rej

+file.

+.TP

+\fB\-R\fP  or  \fB\*=reverse\fP

+Assume that this patch was created with the old and new files swapped.

+(Yes, I'm afraid that does happen occasionally, human nature being what it

+is.)

+.B patch

+attempts to swap each hunk around before applying it.

+Rejects come out in the swapped format.

+The

+.B \-R

+option does not work with

+.B ed

+diff scripts because there is too little

+information to reconstruct the reverse operation.

+.Sp

+If the first hunk of a patch fails,

+.B patch

+reverses the hunk to see if it can be applied that way.

+If it can, you are asked if you want to have the

+.B \-R

+option set.

+If it can't, the patch continues to be applied normally.

+(Note: this method cannot detect a reversed patch if it is a normal diff

+and if the first command is an append (i.e. it should have been a delete)

+since appends always succeed, due to the fact that a null context matches

+anywhere.

+Luckily, most patches add or change lines rather than delete them, so most

+reversed normal diffs begin with a delete, which fails, triggering

+the heuristic.)

+.TP

+\fB\-s\fP  or  \fB\*=silent\fP  or  \fB\*=quiet\fP

+Work silently, unless an error occurs.

+.TP

+\fB\-t\fP  or  \fB\*=batch\fP

+Suppress questions like

+.BR \-f ,

+but make some different assumptions:

+skip patches whose headers do not contain file names (the same as \fB\-f\fP);

+skip patches for which the file has the wrong version for the

+.B Prereq:\&

+line

+in the patch; and assume that patches are reversed if they look like

+they are.

+.TP

+\fB\-T\fP  or  \fB\*=set\-time\fP

+Set the modification and access times of patched files from time stamps

+given in context diff headers, assuming that the context diff headers

+use local time.  This option is not recommended, because patches using

+local time cannot easily be used by people in other time zones, and

+because local time stamps are ambiguous when local clocks move backwards

+during daylight-saving time adjustments.  Instead of using this option,

+generate patches with \s-1UTC\s0 and use the

+.B \-Z

+or

+.B \*=set\-utc

+option instead.

+.TP

+\fB\-u\fP  or  \fB\*=unified\fP

+Interpret the patch file as a unified context diff.

+.TP

+\fB\-v\fP  or  \fB\*=version\fP

+Print out

+.BR patch 's

+revision header and patch level, and exit.

+.TP

+\fB\-V\fP \fImethod\fP  or  \fB\*=version\-control=\fP\fImethod\fP

+Use

+.I method

+to determine

+backup file names.  The method can also be given by the

+.B PATCH_VERSION_CONTROL

+(or, if that's not set, the

+.BR VERSION_CONTROL )

+environment variable, which is overridden by this option.

+The method does not affect whether backup files are made;

+it affects only the names of any backup files that are made.

+.Sp

+The value of

+.I method

+is like the \s-1GNU\s0

+Emacs `version-control' variable;

+.B patch

+also recognizes synonyms that

+are more descriptive.  The valid values for

+.I method

+are (unique abbreviations are

+accepted):

+.RS

+.TP 3

+\fBexisting\fP  or  \fBnil\fP

+Make numbered backups of files that already have them,

+otherwise simple backups.

+This is the default.

+.TP

+\fBnumbered\fP  or  \fBt\fP

+Make numbered backups.  The numbered backup file name for

+.I F

+is

+.IB F .~ N ~

+where

+.I N

+is the version number.

+.TP

+\fBsimple\fP  or  \fBnever\fP

+Make simple backups.

+The

+.B \-B

+or

+.BR \*=prefix ,

+.B \-Y

+or

+.BR \*=basename\-prefix ,

+and

+.B \-z

+or

+.BR \*=suffix

+options specify the simple backup file name.

+If none of these options are given, then a simple backup suffix is used;

+it is the value of the

+.B SIMPLE_BACKUP_SUFFIX

+environment variable if set, and is

+.B \&.orig

+otherwise.

+.PP

+With numbered or simple backups,

+if the backup file name is too long, the backup suffix

+.B ~

+is used instead; if even appending

+.B ~

+would make the name too long, then

+.B ~

+replaces the last character of the file name.

+.RE

+.TP

+\fB\*=verbose\fP

+Output extra information about the work being done.

+.TP

+\fB\-x\fP \fInum\fP  or  \fB\*=debug=\fP\fInum\fP

+Set internal debugging flags of interest only to

+.B patch

+patchers.

+.TP

+\fB\-Y\fP \fIpref\fP  or  \fB\*=basename\-prefix=\fP\fIpref\fP

+Prefix

+.I pref

+to the basename of a file name when generating its simple backup file name.

+For example, with

+.B "\-Y\ .del/"

+the simple backup file name for

+.B src/patch/util.c

+is

+.BR src/patch/.del/util.c .

+.TP

+\fB\-z\fP \fIsuffix\fP  or  \fB\*=suffix=\fP\fIsuffix\fP

+Use

+.I suffix

+as the simple backup suffix.

+For example, with

+.B "\-z\ -"

+the simple backup file name for

+.B src/patch/util.c

+is

+.BR src/patch/util.c- .

+The backup suffix may also be specified by the

+.B SIMPLE_BACKUP_SUFFIX

+environment variable, which is overridden by this option.

+.TP

+\fB\-Z\fP  or  \fB\*=set\-utc\fP

+Set the modification and access times of patched files from time stamps

+given in context diff headers, assuming that the context diff headers

+use Coordinated Universal Time (\s-1UTC\s0, often known as \s-1GMT\s0).

+Also see the

+.B \-T

+or

+.B \*=set\-time

+option.

+.Sp

+The

+.B \-Z

+or

+.B \*=set\-utc

+and

+.B \-T

+or

+.B \*=set\-time

+options normally refrain from setting a file's time if the file's original time

+does not match the time given in the patch header, or if its

+contents do not match the patch exactly.  However, if the

+.B \-f

+or

+.B \*=force

+option is given, the file time is set regardless.

+.Sp

+Due to the limitations of

+.B diff

+output format, these options cannot update the times of files whose

+contents have not changed.  Also, if you use these options, you should remove

+(e.g. with

+.BR "make\ clean" )

+all files that depend on the patched files, so that later invocations of

+.B make

+do not get confused by the patched files' times.

+.SH ENVIRONMENT

+.TP 3

+\fBPATCH_GET\fP

+This specifies whether

+.B patch

+gets missing or read-only files from \s-1RCS\s0 or \s-1SCCS\s0

+by default; see the

+.B \-g

+or

+.B \*=get

+option.

+.TP

+.B POSIXLY_CORRECT

+If set,

+.B patch

+conforms more strictly to the \s-1POSIX\s0 standard:

+it takes the first existing file from the list (old, new, index)

+when intuiting file names from diff headers,

+it does not remove files that are empty after patching,

+it does not ask whether to get files from \s-1RCS\s0 or \s-1SCCS\s0,

+it requires that all options precede the files in the command line,

+and it does not backup files when there is a mismatch.

+.TP

+.B SIMPLE_BACKUP_SUFFIX

+Extension to use for simple backup file names instead of

+.BR \&.orig .

+.TP

+\fBTMPDIR\fP, \fBTMP\fP, \fBTEMP\fP

+Directory to put temporary files in;

+.B patch

+uses the first environment variable in this list that is set.

+If none are set, the default is system-dependent;

+it is normally

+.B /tmp

+on Unix hosts.

+.TP

+\fBVERSION_CONTROL\fP or \fBPATCH_VERSION_CONTROL\fP

+Selects version control style; see the

+.B \-v

+or

+.B \*=version\-control

+option.

+.SH FILES

+.TP 3

+.IB $TMPDIR "/p\(**"

+temporary files

+.TP

+.B /dev/tty

+controlling terminal; used to get answers to questions asked of the user

+.SH "SEE ALSO"

+.BR diff (1),

+.BR ed (1)

+.Sp

+Marshall T. Rose and Einar A. Stefferud,

+Proposed Standard for Message Encapsulation,

+Internet RFC 934 <URL:ftp://ftp.isi.edu/in-notes/rfc934.txt> (1985-01).

+.SH "NOTES FOR PATCH SENDERS"

+There are several things you should bear in mind if you are going to

+be sending out patches.

+.PP

+Create your patch systematically.

+A good method is the command

+.BI "diff\ \-Naur\ " "old\ new"

+where

+.I old

+and

+.I new

+identify the old and new directories.

+The names

+.I old

+and

+.I new

+should not contain any slashes.

+The

+.B diff

+command's headers should have dates

+and times in Universal Time using traditional Unix format,

+so that patch recipients can use the

+.B \-Z

+or

+.B \*=set\-utc

+option.

+Here is an example command, using Bourne shell syntax:

+.Sp

+	\fBLC_ALL=C TZ=UTC0 diff \-Naur gcc\-2.7 gcc\-2.8\fP

+.PP

+Tell your recipients how to apply the patch

+by telling them which directory to

+.B cd

+to, and which

+.B patch

+options to use.  The option string

+.B "\-Np1"

+is recommended.

+Test your procedure by pretending to be a recipient and applying

+your patch to a copy of the original files.

+.PP

+You can save people a lot of grief by keeping a

+.B patchlevel.h

+file which is patched to increment the patch level

+as the first diff in the patch file you send out.

+If you put a

+.B Prereq:\&

+line in with the patch, it won't let them apply

+patches out of order without some warning.

+.PP

+You can create a file by sending out a diff that compares

+.B /dev/null

+or an empty file dated the Epoch (1970-01-01 00:00:00 \s-1UTC\s0)

+to the file you want to create.

+This only works if the file you want to create doesn't exist already in

+the target directory.

+Conversely, you can remove a file by sending out a context diff that compares

+the file to be deleted with an empty file dated the Epoch.

+The file will be removed unless the

+.B POSIXLY_CORRECT

+environment variable is set and the

+.B \-E

+or

+.B \*=remove\-empty\-files

+option is not given.

+An easy way to generate patches that create and remove files

+is to use \s-1GNU\s0

+.BR diff 's

+.B \-N

+or

+.B \*=new\-file

+option.

+.PP

+If the recipient is supposed to use the

+.BI \-p N

+option, do not send output that looks like this:

+.Sp

+.ft B

+.ne 3

+	diff \-Naur v2.0.29/prog/README prog/README

+.br

+	\-\^\-\^\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997

+.br

+	+\^+\^+ prog/README   Mon Mar 17 14:58:22 1997

+.ft

+.Sp

+because the two file names have different numbers of slashes,

+and different versions of

+.B patch

+interpret the file names differently.

+To avoid confusion, send output that looks like this instead:

+.Sp

+.ft B

+.ne 3

+	diff \-Naur v2.0.29/prog/README v2.0.30/prog/README

+.br

+	\-\^\-\^\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997

+.br

+	+\^+\^+ v2.0.30/prog/README   Mon Mar 17 14:58:22 1997

+.ft

+.Sp

+.PP

+Avoid sending patches that compare backup file names like

+.BR README.orig ,

+since this might confuse

+.B patch

+into patching a backup file instead of the real file.

+Instead, send patches that compare the same base file names

+in different directories, e.g.\&

+.B old/README

+and

+.BR new/README .

+.PP

+Take care not to send out reversed patches, since it makes people wonder

+whether they already applied the patch.

+.PP

+Try not to have your patch modify derived files

+(e.g. the file

+.B configure

+where there is a line

+.B "configure: configure.in"

+in your makefile), since the recipient should be

+able to regenerate the derived files anyway.

+If you must send diffs of derived files,

+generate the diffs using \s-1UTC\s0,

+have the recipients apply the patch with the

+.B \-Z

+or

+.B \*=set\-utc

+option, and have them remove any unpatched files that depend on patched files

+(e.g. with

+.BR "make\ clean" ).

+.PP

+While you may be able to get away with putting 582 diff listings into

+one file, it may be wiser to group related patches into separate files in

+case something goes haywire.

+.SH DIAGNOSTICS

+Diagnostics generally indicate that

+.B patch

+couldn't parse your patch file.

+.PP

+If the

+.B \*=verbose

+option is given, the message

+.B Hmm.\|.\|.\&

+indicates that there is unprocessed text in

+the patch file and that

+.B patch

+is attempting to intuit whether there is a patch in that text and, if so,

+what kind of patch it is.

+.PP

+.BR patch 's

+exit status is

+0 if all hunks are applied successfully,

+1 if some hunks cannot be applied,

+and 2 if there is more serious trouble.

+When applying a set of patches in a loop it behooves you to check this

+exit status so you don't apply a later patch to a partially patched file.

+.SH CAVEATS

+Context diffs cannot reliably represent the creation or deletion of

+empty files, empty directories, or special files such as symbolic links.

+Nor can they represent changes to file metadata like ownership, permissions,

+or whether one file is a hard link to another.

+If changes like these are also required, separate instructions

+(e.g. a shell script) to accomplish them should accompany the patch.

+.PP

+.B patch

+cannot tell if the line numbers are off in an

+.B ed

+script, and can detect

+bad line numbers in a normal diff only when it finds a change or deletion.

+A context diff using fuzz factor 3 may have the same problem.

+Until a suitable interactive interface is added, you should probably do

+a context diff in these cases to see if the changes made sense.

+Of course, compiling without errors is a pretty good indication that the patch

+worked, but not always.

+.PP

+.B patch

+usually produces the correct results, even when it has to do a lot of

+guessing.

+However, the results are guaranteed to be correct only when the patch is

+applied to exactly the same version of the file that the patch was

+generated from.

+.SH "COMPATIBILITY ISSUES"

+The \s-1POSIX\s0 standard specifies behavior that differs from

+.BR patch 's

+traditional behavior.

+You should be aware of these differences if you must interoperate with

+.B patch

+versions 2.1 and earlier, which are not \s-1POSIX\s0-compliant.

+.TP 3

+.B " \(bu"

+In traditional

+.BR patch ,

+the

+.B \-p

+option's operand was optional, and a bare

+.B \-p

+was equivalent to

+.BR \-p0.

+The

+.B \-p

+option now requires an operand, and

+.B "\-p\ 0"

+is now equivalent to

+.BR \-p0 .

+For maximum compatibility, use options like

+.B \-p0

+and

+.BR \-p1 .

+.Sp

+Also,

+traditional

+.B patch

+simply counted slashes when stripping path prefixes;

+.B patch

+now counts pathname components.

+That is, a sequence of one or more adjacent slashes

+now counts as a single slash.

+For maximum portability, avoid sending patches containing

+.B //

+in file names.

+.TP

+.B " \(bu"

+In traditional

+.BR patch ,

+backups were enabled by default.

+This behavior is now enabled with the

+.B \-b

+or

+.B \*=backup

+option.

+.Sp

+Conversely, in \s-1POSIX\s0

+.BR patch ,

+backups are never made, even when there is a mismatch.

+In \s-1GNU\s0

+.BR patch ,

+this behavior is enabled with the

+.B \*=no\-backup\-if\-mismatch

+option or by setting the

+.B POSIXLY_CORRECT

+environment variable.

+.Sp

+The

+.BI \-b "\ suffix"

+option

+of traditional

+.B patch

+is equivalent to the

+.BI "\-b\ \-z" "\ suffix"

+options of \s-1GNU\s0

+.BR patch .

+.TP

+.B " \(bu"

+Traditional

+.B patch

+used a complicated (and incompletely documented) method

+to intuit the name of the file to be patched from the patch header.

+This method was not \s-1POSIX\s0-compliant, and had a few gotchas.

+Now

+.B patch

+uses a different, equally complicated (but better documented) method

+that is optionally \s-1POSIX\s0-compliant; we hope it has

+fewer gotchas.  The two methods are compatible if the

+file names in the context diff header and the

+.B Index:\&

+line are all identical after prefix-stripping.

+Your patch is normally compatible if each header's file names

+all contain the same number of slashes.

+.TP

+.B " \(bu"

+When traditional

+.B patch

+asked the user a question, it sent the question to standard error

+and looked for an answer from

+the first file in the following list that was a terminal:

+standard error, standard output,

+.BR /dev/tty ,

+and standard input.

+Now

+.B patch

+sends questions to standard output and gets answers from

+.BR /dev/tty .

+Defaults for some answers have been changed so that

+.B patch

+never goes into an infinite loop when using default answers.

+.TP

+.B " \(bu"

+Traditional

+.B patch

+exited with a status value that counted the number of bad hunks,

+or with status 1 if there was real trouble.

+Now

+.B patch

+exits with status 1 if some hunks failed,

+or with 2 if there was real trouble.

+.TP

+.B " \(bu"

+Limit yourself to the following options when sending instructions

+meant to be executed by anyone running \s-1GNU\s0

+.BR patch ,

+traditional

+.BR patch ,

+or a \s-1POSIX\s0-compliant

+.BR patch .

+Spaces are significant in the following list, and operands are required.

+.Sp

+.nf

+.in +3

+.ne 11

+.B \-c

+.BI \-d " dir"

+.BI \-D " define"

+.B \-e

+.B \-l

+.B \-n

+.B \-N

+.BI \-o " outfile"

+.BI \-p num

+.B \-R

+.BI \-r " rejectfile"

+.in

+.fi

+.SH BUGS

+.B patch

+could be smarter about partial matches, excessively deviant offsets and

+swapped code, but that would take an extra pass.

+.PP

+If code has been duplicated (for instance with

+\fB#ifdef OLDCODE\fP .\|.\|. \fB#else .\|.\|. #endif\fP),

+.B patch

+is incapable of patching both versions, and, if it works at all, will likely

+patch the wrong one, and tell you that it succeeded to boot.

+.PP

+If you apply a patch you've already applied,

+.B patch

+thinks it is a reversed patch, and offers to un-apply the patch.

+This could be construed as a feature.

+.SH COPYING

+Copyright

+.if t \(co

+1984, 1985, 1986, 1988 Larry Wall.

+.br

+Copyright

+.if t \(co

+1997 Free Software Foundation, Inc.

+.PP

+Permission is granted to make and distribute verbatim copies of

+this manual provided the copyright notice and this permission notice

+are preserved on all copies.

+.PP

+Permission is granted to copy and distribute modified versions of this

+manual under the conditions for verbatim copying, provided that the

+entire resulting derived work is distributed under the terms of a

+permission notice identical to this one.

+.PP

+Permission is granted to copy and distribute translations of this

+manual into another language, under the above conditions for modified

+versions, except that this permission notice may be included in

+translations approved by the copyright holders instead of in

+the original English.

+.SH AUTHORS

+Larry Wall wrote the original version of

+.BR patch .

+Paul Eggert removed

+.BR patch 's

+arbitrary limits; added support for binary files,

+setting file times, and deleting files;

+and made it conform better to \s-1POSIX\s0.

+Other contributors include Wayne Davison, who added unidiff support,

+and David MacKenzie, who added configuration and backup support.

--- a/sys/src/ape/cmd/pax/cpio.1

+++ /dev/null

@@ -1,271 +1,0 @@

-.\" $Id: cpio.1,v 1.2 89/02/12 10:08:42 mark Exp $

-.TH CPIO 1 "USENIX Association" ""

-.SH NAME

-cpio \- copy file archives in and out

-.SH SYNOPSIS

-.B cpio

-.BR \-o [ Bacv ]

-.br

-.B cpio

-.BR \-i [ Bcdfmrtuv ]

-.RI [ pattern... ]

-.br

-.B cpio

-.BR \-p [ adlmruv ]

-.I directory

-.SH DESCRIPTION

-The

-.B cpio

-utility produces and reads files in the format specified by the

-.B cpio

-.B "Archive/Interchange File Format"

-specified in

-.IR "IEEE Std. 1003.1-1988" .

-.PP

-The

-.B "cpio -i"

-(copy in) utility extracts files from the standard input, which is

-assumed to be the product of a previous

-.B "cpio -o" .

-Only files with names that match

-.I patterns

-are selected.

-Multiple

-.I patterns

-may be specified and if no

-.I patterns

-are specified, the default for

-.I patterns

-is \*, selecting all files.

-The extracted files are conditionally created and copied into the

-current directory, and possibly any levels below, based upon the

-options described below and the permissions of the files will be those

-of the previous

-.B "cpio -o" .

-The owner and group of the files will be that of the current user

-unless the user has appropriate privileges, which causes

-.B cpio

-to retains the owner and group of the files of the previous

-.B "cpio -o" .

-.PP

-The

-.B "cpio -p"

-(pass) utility reads the standard input to obtain a list of path names

-of files that are conditionally created and copied into the

-destination

-.I directory

-based upon the options described below.

-.PP

-If an error is detected, the cause is reported and the

-.B cpio

-utility will continue to copy other files.

-.B cpio

-will skip over any unrecognized files which it encounters in the archive.

-.PP

-The following restrictions apply to the

-.B cpio

-utility:

-.IP 1 .25i

-Pathnames are restricted to 256 characters.

-.IP 2 .25i

-Appropriate privileges are required to copy special files.

-.IP 3 .25i

-Blocks are reported in 512-byte quantities.

-.SS Options

-The following options are available:

-.TP .5i

-.B \-B

-Input/output is to be blocked 5120 bytes to the record.

-Can only be used with

-.B "cpio -o"

-or

-.B "cpio -i"

-for data that is directed to or from character special files.

-.TP .5i

-.B \-a

-Reset access times of input files after they have been copied.

-When the

-.B \-l

-option is also specified, the linked files do not have their access

-times reset.

-Can only be used with

-.B "cpio -o"

-or

-.B "cpio -i" .

-.TP .5i

-.B \-c

-Write header information in ASCII character for for portability.

-Can only be used with

-.B "cpio -i"

-or

-.B "cpio -o" .

-Note that this option should always be used to write portable files.

-.TP .5i

-.B \-d

-Creates directories as needed.

-Can only be used with

-.B "cpio -i"

-or

-.B "cpio -p" .

-.TP .5i

-.B \-f

-Copy in all files except those in

-.I patterns .

-Can only be used with

-.B "cpio -i" .

-.TP .5i

-.B \-l

-Whenever possible, link files rather than copying them.

-Can only be used with

-.B "cpio -p" .

-.TP .5i

-.B \-m

-Retain previous modification times.

-This option is ineffective on directories that are being copied.

-Can only be used with

-.B "cpio -i"

-or

-.B "cpio -p" .

-.TP .5i

-.B \-r

-Interactively rename files.

-The user is asked whether to rename

-.I pattern

-each invocation.

-Read and write permissions for

-.B "/dev/tty"

-are required for this option.

-If the user types a null line, the file is skipped.

-Should only be used with

-.B "cpio -i"

-or

-.B "cpio -o" .

-.TP .5i

-.B \-t

-Print a table of contents of the input.

-No files are created.

-Can only be used with

-.B "cpio -i" .

-.TP .5i

-.B \-u

-Copy files unconditionally; usually an older file will not replace a

-new file with the same name.

-Can only be used with

-.B "cpio -i"

-or

-.B "cpio -p" .

-.TP .5i

-.B \-v

-Verbose: cause the names of the affected files to be printed.

-Can only be used with

-.B "cpio -i" .

-Provides a detailed listing when used with the

-.B \-t

-option.

-.SS Operands

-The following operands are available:

-.TP 1i

-.I patterns

-Simple regular expressions given in the name-generating notation of the

-shell.

-.TP 1i

-.I directory

-The destination directory.

-.SS "Exit Status"

-The

-.B cpio

-utility exits with one of the following values:

-.TP .5i

-0

-All input files were copied.

-.TP .5i

-2

-The utility encountered errors in copying or accessing files or

-directories.

-An error will be reported for nonexistent files or directories, or

-permissions that do not allow the user to access the source or target

-files.

-.SS

-It is important to use the

-.B "-depth"

-option of the

-.B find

-utility to generate pathnames for

-.B cpio .

-This eliminates problems

-.B cpio

-could have trying to create files under read-only directories.

-.PP

-The following command:

-.RS

-ls | cpio -o > ../newfile

-.RE

-copies out the files listed by the

-.B ls

-utility and redirects them to the file

-.B newfile .

-.PP

-The following command:

-.RS

-cat newfile | cpio -id "memo/al" "memo/b*"

-.RE

-uses the output file

-.B newfile

-from the

-.B "cpio -o"

-utility, takes those files that match the patterns

-.B "memo/al"

-and

-.B "memo/b*" ,

-creates the directories below the current directory, and places the

-files in the appropriate directories.

-.PP

-The command

-.RS

-find . -depth -print | cpio -pdlmv newdir

-.RE

-takes the file names piped to it from the

-.B find

-utility and copies or links those files to another directory

-named

-.B newdir ,

-while retaining the modification time.

-.SH FILES

-.TP 1i

-/dev/tty

-used to prompt the user for information when the

-.B \-i

-or

-.B \-r

-options are specified.

-.SH "SEE ALSO"

-find(1), pax(1), tar(1), cpio(5), tar(5)

-.SH COPYRIGHT

-Copyright (c) 1989 Mark H. Colburn.

-.br

-All rights reserved.

-.PP

-Redistribution and use in source and binary forms are permitted

-provided that the above copyright notice is duplicated in all such

-forms and that any documentation, advertising materials, and other

-materials related to such distribution and use acknowledge that the

-software was developed by Mark H. Colburn and sponsored by The

-USENIX Association.

-.PP

-THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR

-IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED

-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

-.SH AUTHOR

-Mark H. Colburn

-.br

-NAPS International

-.br

-117 Mackubin Street, Suite 1

-.br

-St. Paul, MN 55102

-.br

[email protected]

-.sp 2

-Sponsored by

-.B "The USENIX Association"

-for public distribution.

--- /dev/null

+++ b/sys/src/ape/cmd/pax/cpio.1.man

@@ -1,0 +1,271 @@

+.\" $Id: cpio.1,v 1.2 89/02/12 10:08:42 mark Exp $

+.TH CPIO 1 "USENIX Association" ""

+.SH NAME

+cpio \- copy file archives in and out

+.SH SYNOPSIS

+.B cpio

+.BR \-o [ Bacv ]

+.br

+.B cpio

+.BR \-i [ Bcdfmrtuv ]

+.RI [ pattern... ]

+.br

+.B cpio

+.BR \-p [ adlmruv ]

+.I directory

+.SH DESCRIPTION

+The

+.B cpio

+utility produces and reads files in the format specified by the

+.B cpio

+.B "Archive/Interchange File Format"

+specified in

+.IR "IEEE Std. 1003.1-1988" .

+.PP

+The

+.B "cpio -i"

+(copy in) utility extracts files from the standard input, which is

+assumed to be the product of a previous

+.B "cpio -o" .

+Only files with names that match

+.I patterns

+are selected.

+Multiple

+.I patterns

+may be specified and if no

+.I patterns

+are specified, the default for

+.I patterns

+is \*, selecting all files.

+The extracted files are conditionally created and copied into the

+current directory, and possibly any levels below, based upon the

+options described below and the permissions of the files will be those

+of the previous

+.B "cpio -o" .

+The owner and group of the files will be that of the current user

+unless the user has appropriate privileges, which causes

+.B cpio

+to retains the owner and group of the files of the previous

+.B "cpio -o" .

+.PP

+The

+.B "cpio -p"

+(pass) utility reads the standard input to obtain a list of path names

+of files that are conditionally created and copied into the

+destination

+.I directory

+based upon the options described below.

+.PP

+If an error is detected, the cause is reported and the

+.B cpio

+utility will continue to copy other files.

+.B cpio

+will skip over any unrecognized files which it encounters in the archive.

+.PP

+The following restrictions apply to the

+.B cpio

+utility:

+.IP 1 .25i

+Pathnames are restricted to 256 characters.

+.IP 2 .25i

+Appropriate privileges are required to copy special files.

+.IP 3 .25i

+Blocks are reported in 512-byte quantities.

+.SS Options

+The following options are available:

+.TP .5i

+.B \-B

+Input/output is to be blocked 5120 bytes to the record.

+Can only be used with

+.B "cpio -o"

+or

+.B "cpio -i"

+for data that is directed to or from character special files.

+.TP .5i

+.B \-a

+Reset access times of input files after they have been copied.

+When the

+.B \-l

+option is also specified, the linked files do not have their access

+times reset.

+Can only be used with

+.B "cpio -o"

+or

+.B "cpio -i" .

+.TP .5i

+.B \-c

+Write header information in ASCII character for for portability.

+Can only be used with

+.B "cpio -i"

+or

+.B "cpio -o" .

+Note that this option should always be used to write portable files.

+.TP .5i

+.B \-d

+Creates directories as needed.

+Can only be used with

+.B "cpio -i"

+or

+.B "cpio -p" .

+.TP .5i

+.B \-f

+Copy in all files except those in

+.I patterns .

+Can only be used with

+.B "cpio -i" .

+.TP .5i

+.B \-l

+Whenever possible, link files rather than copying them.

+Can only be used with

+.B "cpio -p" .

+.TP .5i

+.B \-m

+Retain previous modification times.

+This option is ineffective on directories that are being copied.

+Can only be used with

+.B "cpio -i"

+or

+.B "cpio -p" .

+.TP .5i

+.B \-r

+Interactively rename files.

+The user is asked whether to rename

+.I pattern

+each invocation.

+Read and write permissions for

+.B "/dev/tty"

+are required for this option.

+If the user types a null line, the file is skipped.

+Should only be used with

+.B "cpio -i"

+or

+.B "cpio -o" .

+.TP .5i

+.B \-t

+Print a table of contents of the input.

+No files are created.

+Can only be used with

+.B "cpio -i" .

+.TP .5i

+.B \-u

+Copy files unconditionally; usually an older file will not replace a

+new file with the same name.

+Can only be used with

+.B "cpio -i"

+or

+.B "cpio -p" .

+.TP .5i

+.B \-v

+Verbose: cause the names of the affected files to be printed.

+Can only be used with

+.B "cpio -i" .

+Provides a detailed listing when used with the

+.B \-t

+option.

+.SS Operands

+The following operands are available:

+.TP 1i

+.I patterns

+Simple regular expressions given in the name-generating notation of the

+shell.

+.TP 1i

+.I directory

+The destination directory.

+.SS "Exit Status"

+The

+.B cpio

+utility exits with one of the following values:

+.TP .5i

+0

+All input files were copied.

+.TP .5i

+2

+The utility encountered errors in copying or accessing files or

+directories.

+An error will be reported for nonexistent files or directories, or

+permissions that do not allow the user to access the source or target

+files.

+.SS

+It is important to use the

+.B "-depth"

+option of the

+.B find

+utility to generate pathnames for

+.B cpio .

+This eliminates problems

+.B cpio

+could have trying to create files under read-only directories.

+.PP

+The following command:

+.RS

+ls | cpio -o > ../newfile

+.RE

+copies out the files listed by the

+.B ls

+utility and redirects them to the file

+.B newfile .

+.PP

+The following command:

+.RS

+cat newfile | cpio -id "memo/al" "memo/b*"

+.RE

+uses the output file

+.B newfile

+from the

+.B "cpio -o"

+utility, takes those files that match the patterns

+.B "memo/al"

+and

+.B "memo/b*" ,

+creates the directories below the current directory, and places the

+files in the appropriate directories.

+.PP

+The command

+.RS

+find . -depth -print | cpio -pdlmv newdir

+.RE

+takes the file names piped to it from the

+.B find

+utility and copies or links those files to another directory

+named

+.B newdir ,

+while retaining the modification time.

+.SH FILES

+.TP 1i

+/dev/tty

+used to prompt the user for information when the

+.B \-i

+or

+.B \-r

+options are specified.

+.SH "SEE ALSO"

+find(1), pax(1), tar(1), cpio(5), tar(5)

+.SH COPYRIGHT

+Copyright (c) 1989 Mark H. Colburn.

+.br

+All rights reserved.

+.PP

+Redistribution and use in source and binary forms are permitted

+provided that the above copyright notice is duplicated in all such

+forms and that any documentation, advertising materials, and other

+materials related to such distribution and use acknowledge that the

+software was developed by Mark H. Colburn and sponsored by The

+USENIX Association.

+.PP

+THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR

+IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED

+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

+.SH AUTHOR

+Mark H. Colburn

+.br

+NAPS International

+.br

+117 Mackubin Street, Suite 1

+.br

+St. Paul, MN 55102

+.br

[email protected]

+.sp 2

+Sponsored by

+.B "The USENIX Association"

+for public distribution.

--- a/sys/src/ape/cmd/pax/pax.1

+++ /dev/null

@@ -1,579 +1,0 @@

-.\" $Id: pax.1,v 1.2 89/02/12 10:08:47 mark Exp $

-.TH PAX 1 "USENIX Association" ""

-.SH NAME

-pax \- portable archive exchange

-.SH SYNOPSIS

-.TP \w'\fBpax\fR\ 'u

-.B pax

-.RB [ \-cimopuvy ]

-.RI "[\fB\-f\fR" " archive" ]

-.RI "[\fB\-s\fR" " replstr" ]

-.RI "[\fB\-t\fR" " device" ]

-.RI [ pattern... ]

-.TP \w'\fBpax\ \-r\fR\ 'u

-.B "pax\ \-r"

-.RB [ \-cimnopuvy ]

-.RI "[\fB\-f\fR" " archive" ]

-.RI "[\fB\-s\fR" " replstr" ]

-.RI "[\fB\-t\fR" " device" ]

-.RI [ pattern... ]

-.TP \w'\fBpax\ \-w\fR\ 'u

-.B "pax\ \-w"

-.RB [ \-adimuvy ]

-.RI "[\fB\-b\fR" " blocking" ]

-.RI "[\fB\-f\fR" " archive" ]

-.RI "[\fB\-s\fR" " replstr" ]

-.RI "[\fB\-t\fR" " device" ]

-.RI "[\fB\-x\fR" " format" ]

-.RI [ pathname... ]

-.TP \w'\fBpax\ \-rw\fR\ 'u

-.B "pax\ \-rw"

-.RB [ \-ilmopuvy ]

-.RI "[\fB\-s\fR" " replstr" ]

-.RI [ pathname... ]

-directory

-.SH DESCRIPTION

-.I Pax

-reads and writes archive files which conform to the

-.B "Archive/Interchange File Format"

-specified in

-.IR "IEEE Std. 1003.1-1988" .

-.I Pax

-can also read, but not write, a number of other file formats

-in addition to those specified in the

-.B "Archive/Interchange File Format"

-description.

-Support for these traditional file formats, such as V7

-.I "tar"

-and System V binary

-.I "cpio"

-format archives,

-is provided for backward compatibility and to maximize portability.

-.PP

-.I Pax

-will also support traditional

-.I cpio

-and

-System V

-.I tar

-interfaces if invoked with the name

-"cpio" or "tar" respectively.

-See the

-.I cpio(1)

-or

-.I tar(1)

-manual pages for more details.

-.PP

-Combinations of the

-.B \-r

-and

-.B \-w

-command line arguments specify whether

-.I pax

-will read, write or list the contents of the specified archive,

-or move the specified files to another directory.

-.PP

-The command line arguments are:

-.TP .5i

-.B \-w

-writes the files and directories specified by

-.I pathname

-operands to the standard output together with the pathname and status

-information prescribed by the archive format used.

-A directory

-.I pathname

-operand refers to the files and (recursively) subdirectories of that

-directory.

-If no

-.I pathname

-operands are given, then the standard input is read to get a

-list of pathnames to copy, one pathname per line.

-In this case, only those pathnames appearing on the standard input are

-copied.

-.TP .5i

-.B \-r

-.I Pax

-reads an archive file from the standard input.

-Only files with names that match any of the

-.I pattern

-operands are selected for extraction.

-The selected files are conditionally created and copied relative to the

-current directory tree, subject to the options described below.

-By default, the owner and group of selected files will be that of the

-invoking process, and the permissions and modification times will be the

-sames as those in the archive.

-.RS .5i

-.PP

-The supported archive formats are automatically detected on input.

-The default output format is

-.IR ustar ,

-but may be overridden by the

-.B \-x

-.I format

-option described below.

-.RE

-.TP .5i

-.B \-rw

-.I Pax

-reads the files and directories named in the

-.I pathname

-operands and copies them to the destination

-.IR directory .

-A directory

-.I pathname

-operand refers to the files and (recursively) subdirectories of that

-directory.

-If no

-.I pathname

-operands are given, the standard input is read to get a list of pathnames

-to copy, one pathname per line.

-In this case, only those pathnames appearing on the standard input are

-copied.

-The directory named by the

-.I directory

-operand must exist and have the proper permissions before the copy can

-occur.

-.PP

-If neither the

-.BR \-r " or " \-w

-options are given, then

-.I pax

-will list the contents of the specified archive.

-In this mode,

-.I pax

-lists normal files one per line, hard link pathnames as

-.sp

-.RS 1i

-.IR pathname " == " linkname

-.RE

-.sp

-and symbolic link pathnames (if supported by the implementation) as

-.sp

-.RS 1i

-.IR pathname " -> " linkname

-.RE

-.sp

-where

-.I pathname

-is the name of the file being extracted, and

-.I linkname

-is the name of a file which appeared earlier in the archive.

-.PP

-If the

-.B \-v

-option is specified, then

-.I pax

-list normal pathnames in the same format used by the

-.I ls

-utility with the

-.B \-l

-option.

-Hard links are shown as

-.sp

-.RS 1i

-.IR "<ls -l listing>" " == " linkname

-.RE

-.sp

-and symbolic links (if supported) are shown as

-.sp

-.RS 1i

-.IR "<ls -l listing>" " -> " linkname

-.RE

-.sp

-.PP

-.I Pax

-is capable of reading and writing archives which span multiple physical

-volumes.

-Upon detecting an end of medium on an archive which is not yet completed,

-.I pax

-will prompt the user for the next volume of the archive and will allow the

-user to specify the location of the next volume.

-.SS Options

-The following options are available:

-.TP 1i

-.B \-a

-The files specified by

-.I pathname

-are appended to the specified archive.

-.TP 1i

-.BI \-b " blocking"

-Block the output at

-.I blocking

-bytes per write to the archive file.

-A

-.B k

-suffix multiplies

-.I blocking

-by 1024, a

-.B b

-suffix multiplies

-.I blocking

-by 512 and a

-.B m

-suffix multiplies

-.I blocking

-by 1048576 (1 megabyte).

-For machines with 16-bit int's (VAXen, XENIX-286, etc.),

-the maximum buffer size is 32k-1.

-If not specified,

-.I blocking

-is automatically determined on input and is ignored for

-.B \-rw.

-.TP 1i

-.B \-c

-Complement the match sense of the

-.I pattern

-operands.

-.TP 1i

-.B \-d

-Intermediate directories not explicitly listed in the archive are not

-created.

-This option is ignored unless

-the

-.B \-r

-option is specified.

-.TP 1i

-.BI \-f " archive"

-The

-.I archive

-option specifies the pathname of the input or output archive,

-overriding the default of standard input for

-.B \-r

-or standard output for

-.BR \-w .

-.TP 1i

-.B \-i

-Interactively rename files.

-Substitutions specified by

-.B \-s

-options (described below)

-are performed before requesting the new file name from the user.

-A file is skipped if an empty line is entered and

-.I pax

-exits with an exit status of 0 if

-.B EOF

-is encountered.

-.TP 1i

-.B \-l

-Files are linked rather than copied when possible.

-.TP 1i

-.B \-m

-File modification times are not retained.

-.TP 1i

-.B \-n

-When

-.B \-r

-is specified, but

-.B \-w

-is not, the

-.I pattern

-arguments are treated as ordinary file names.

-Only the first occurrence of each of these files in the input archive

-is read.

-The

-.B pax

-utility exits with a zero exit status after all files in the list have been

-read.

-If one or more files in the list is not found,

-.B pax

-writes a diagnostic to standard error for each of the files and exits with

-a non-zero exit status.

-the file names are compared before any of the

-.BR \-i ,

-.BR \-s ,

-or

-.B \-y

-options are applied.

-.TP 1i

-.B \-o

-Restore file ownership as specified in the archive.

-The invoking process must have appropriate privileges to accomplish this.

-.TP 1i

-.B \-p

-Preserve the access time of the input files after they have been copied.

-.TP 1i

-.BI \-s " replstr"

-File names are modified according to the substitution expression using the

-syntax of

-.I "ed(1)"

-as shown:

-.sp

-.RS 2i

--s /\fIold\fR/\fInew\fR/\fB[\fRgp\fB]\fR

-.RE

-.RS 1i

-.PP

-Any non null character may be used as a delimiter (a / is used here as an

-example).

-Multiple

-.B \-s

-expressions may be specified; the expressions are applied in the order

-specified terminating with the first successful substitution.

-The optional trailing

-.B p

-causes successful mappings to be listed on standard error.

-The optional trailing

-.B g

-causes the

-.I old

-expression to be replaced each time it occurs in the source string.

-Files that substitute to an empty string are ignored both on input and

-output.

-.RE

-.TP 1i

-.BI \-t " device"

-The

-.I device

-option argument is an implementation-defined identifier that names the input

-or output archive device, overriding the default of standard input for

-.B \-r

-and standard output for

-.BR \-w .

-.TP 1i

-.B \-u

-Copy each file only if it is newer than a pre-existing file with the same

-name.

-This implies

-.BR \-a .

-.TP 1i

-.B \-v

-List file names as they are encountered.

-Produces a verbose table of contents listing on the standard output when both

-.B \-r

-and

-.B \-w

-are omitted,

-otherwise the file names are printed to standard error as they are

-encountered in the archive.

-.TP 1i

-.BI \-x " format"

-Specifies the output archive

-.IR format .

-The input format, which must be one of the following, is automatically

-determined when the

-.B \-r

-option is used.

-The supported formats are:

-.RS 1i

-.TP 0.75i

-.I cpio

-The extended

-.I CPIO

-interchange format specified in

-.B "Extended CPIO Format" in

-.I "IEEE Std. 1003.1-1988."

-.TP 0.75i

-.I ustar

-The extended

-.I TAR

-interchange format specified in

-.B "Extended TAR Format" in

-.I "IEEE Std. 1003.1-1988."

-This is the default archive format.

-.RE

-.TP 1i

-.B \-y

-Interactively prompt for the disposition of each file.

-Substitutions specified by

-.B \-s

-options (described above)

-are performed before prompting the user for disposition.

-.B EOF

-or an input line starting with the character

-.B q

-caused

-.I pax

-to exit.

-Otherwise, an input line starting with anything other than

-.B y

-causes the file to be ignored.

-This option cannot be used in conjunction with the

-.B \-i

-option.

-.PP

-Only the last of multiple

-.B \-f

-or

-.B \-t

-options take effect.

-.PP

-When writing to an archive, the

-standard input is used as a list of pathnames if no

-.I pathname

-operands are specified.

-The format is one pathname per line.

-Otherwise, the standard input is the archive file,

-which is formatted according to one of the specifications in

-.B "Archive/Interchange File format"

-in

-.IR "IEEE Std. 1003.1-1988" ,

-or some other implementation-defined format.

-.PP

-The user ID and group ID of the process, together with the appropriate

-privileges, affect the ability of

-.I pax

-to restore ownership and permissions attributes of the archived files.

-(See

-.I "format-reading utility"

-in

-.B "Archive/Interchange File Format"

-in

-.IR "IEEE Std. 1003.1-1988" ".)"

-.PP

-The options

-.BR \-a ,

-.BR \-c ,

-.BR \-d ,

-.BR \-i ,

-.BR \-l ,

-.BR \-p ,

-.BR \-t ,

-.BR \-u ,

-and

-.BR \-y

-are provided for functional compatibility with the historical

-.I cpio

-and

-.I tar

-utilities.

-The option defaults were chosen based on the most common usage of these

-options, therefore, some of the options have meanings different than

-those of the historical commands.

-.SS Operands

-The following operands are available:

-.TP 1i

-.I directory

-The destination directory pathname for copies when both the

-.B \-r

-and

-.B \-w

-options are specified.

-The directory must exist and be writable before the copy or and error

-results.

-.TP 1i

-.I pathname

-A file whose contents are used instead of the files named on the standard

-input.

-When a directory is named, all of its files and (recursively)

-subdirectories

-are copied as well.

-.TP 1i

-.IR pattern

-A

-.I pattern

-is given in the standard shell pattern matching notation.

-The default if no

-.I pattern

-is  specified is

-.BR * \,

-which selects all files.

-.SH EXAMPLES

-The following command

-.sp

-.RS 1i

-pax \-w \-f /dev/rmt0 \.

-.RE

-.sp

-copies the contents of the current directory to tape drive 0.

-.PP

-The commands

-.sp

-.RS 1i

-.RI mkdir " newdir"

-.br

-.RI cd " olddir"

-.br

-.RI "pax -rw . " newdir

-.RE

-.sp

-copies the contents of

-.I olddir

-to

-.I newdir .

-.PP

-The command

-.sp

-.RS 1i

-pax \-r \-s ',//*usr//*,,' -f pax.out

-.RE

-.sp

-reads the archive

-.B pax.out

-with all files rooted in "/usr" in the archive extracted

-relative to the current directory.

-.SH FILES

-.TP 1i

-/dev/tty

-used to prompt the user for information when the

-.BR \-i " or " \-y

-options are specified.

-.SH "SEE ALSO"

-cpio(1), find(1), tar(1), cpio(5), tar(5)

-.SH DIAGNOSTICS

-.I Pax

-will terminate immediately, without processing any

-additional files on the command line or in the archive.

-.SH "EXIT CODES"

-.I Pax

-will exit with one of the following values:

-.IP 0 .5i

-All files in the archive were processed successfully.

-.IP ">0" .5i

-.I Pax

-aborted due to errors encountered during operation.

-.SH BUGS

-Special permissions may be required to copy or extract special files.

-.PP

-Device, user ID, and group ID numbers larger than 65535 cause additional

-header records to be output.

-These records are ignored by some historical version of

-.I "cpio(1)"

-and

-.IR "tar(1)" .

-.PP

-The archive formats described in

-.B "Archive/Interchange File Format"

-have certain restrictions that have

-been carried over from historical usage.

-For example, there are restrictions on the length of pathnames stored in

-the archive.

-.PP

-When getting an "ls -l" style listing on

-.I tar

-format archives, link counts are listed as zero since the

-.I ustar

-archive format does not keep link count information.

-.PP

-On 16 bit architectures, the largest buffer size is 32k-1.

-This is due, in part, to using integers in the buffer allocation schemes,

-however, on many of these machines, it is not possible to allocate blocks

-of memory larger than 32k.

-.SH COPYRIGHT

-Copyright (c) 1989 Mark H. Colburn.

-.br

-All rights reserved.

-.PP

-Redistribution and use in source and binary forms are permitted

-provided that the above copyright notice is duplicated in all such

-forms and that any documentation, advertising materials, and other

-materials related to such distribution and use acknowledge that the

-software was developed by Mark H. Colburn and sponsored by The

-USENIX Association.

-.PP

-THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR

-IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED

-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

-.SH AUTHOR

-Mark H. Colburn

-.br

-Minnetech Consulting, Inc.

-.br

-117 Mackubin Street, Suite 1

-.br

-St. Paul, MN 55102

-.br

[email protected]

-.sp 2

-Sponsored by

-.B "The USENIX Association"

-for public distribution.

--- /dev/null

+++ b/sys/src/ape/cmd/pax/pax.1.man

@@ -1,0 +1,579 @@

+.\" $Id: pax.1,v 1.2 89/02/12 10:08:47 mark Exp $

+.TH PAX 1 "USENIX Association" ""

+.SH NAME

+pax \- portable archive exchange

+.SH SYNOPSIS

+.TP \w'\fBpax\fR\ 'u

+.B pax

+.RB [ \-cimopuvy ]

+.RI "[\fB\-f\fR" " archive" ]

+.RI "[\fB\-s\fR" " replstr" ]

+.RI "[\fB\-t\fR" " device" ]

+.RI [ pattern... ]

+.TP \w'\fBpax\ \-r\fR\ 'u

+.B "pax\ \-r"

+.RB [ \-cimnopuvy ]

+.RI "[\fB\-f\fR" " archive" ]

+.RI "[\fB\-s\fR" " replstr" ]

+.RI "[\fB\-t\fR" " device" ]

+.RI [ pattern... ]

+.TP \w'\fBpax\ \-w\fR\ 'u

+.B "pax\ \-w"

+.RB [ \-adimuvy ]

+.RI "[\fB\-b\fR" " blocking" ]

+.RI "[\fB\-f\fR" " archive" ]

+.RI "[\fB\-s\fR" " replstr" ]

+.RI "[\fB\-t\fR" " device" ]

+.RI "[\fB\-x\fR" " format" ]

+.RI [ pathname... ]

+.TP \w'\fBpax\ \-rw\fR\ 'u

+.B "pax\ \-rw"

+.RB [ \-ilmopuvy ]

+.RI "[\fB\-s\fR" " replstr" ]

+.RI [ pathname... ]

+directory

+.SH DESCRIPTION

+.I Pax

+reads and writes archive files which conform to the

+.B "Archive/Interchange File Format"

+specified in

+.IR "IEEE Std. 1003.1-1988" .

+.I Pax

+can also read, but not write, a number of other file formats

+in addition to those specified in the

+.B "Archive/Interchange File Format"

+description.

+Support for these traditional file formats, such as V7

+.I "tar"

+and System V binary

+.I "cpio"

+format archives,

+is provided for backward compatibility and to maximize portability.

+.PP

+.I Pax

+will also support traditional

+.I cpio

+and

+System V

+.I tar

+interfaces if invoked with the name

+"cpio" or "tar" respectively.

+See the

+.I cpio(1)

+or

+.I tar(1)

+manual pages for more details.

+.PP

+Combinations of the

+.B \-r

+and

+.B \-w

+command line arguments specify whether

+.I pax

+will read, write or list the contents of the specified archive,

+or move the specified files to another directory.

+.PP

+The command line arguments are:

+.TP .5i

+.B \-w

+writes the files and directories specified by

+.I pathname

+operands to the standard output together with the pathname and status

+information prescribed by the archive format used.

+A directory

+.I pathname

+operand refers to the files and (recursively) subdirectories of that

+directory.

+If no

+.I pathname

+operands are given, then the standard input is read to get a

+list of pathnames to copy, one pathname per line.

+In this case, only those pathnames appearing on the standard input are

+copied.

+.TP .5i

+.B \-r

+.I Pax

+reads an archive file from the standard input.

+Only files with names that match any of the

+.I pattern

+operands are selected for extraction.

+The selected files are conditionally created and copied relative to the

+current directory tree, subject to the options described below.

+By default, the owner and group of selected files will be that of the

+invoking process, and the permissions and modification times will be the

+sames as those in the archive.

+.RS .5i

+.PP

+The supported archive formats are automatically detected on input.

+The default output format is

+.IR ustar ,

+but may be overridden by the

+.B \-x

+.I format

+option described below.

+.RE

+.TP .5i

+.B \-rw

+.I Pax

+reads the files and directories named in the

+.I pathname

+operands and copies them to the destination

+.IR directory .

+A directory

+.I pathname

+operand refers to the files and (recursively) subdirectories of that

+directory.

+If no

+.I pathname

+operands are given, the standard input is read to get a list of pathnames

+to copy, one pathname per line.

+In this case, only those pathnames appearing on the standard input are

+copied.

+The directory named by the

+.I directory

+operand must exist and have the proper permissions before the copy can

+occur.

+.PP

+If neither the

+.BR \-r " or " \-w

+options are given, then

+.I pax

+will list the contents of the specified archive.

+In this mode,

+.I pax

+lists normal files one per line, hard link pathnames as

+.sp

+.RS 1i

+.IR pathname " == " linkname

+.RE

+.sp

+and symbolic link pathnames (if supported by the implementation) as

+.sp

+.RS 1i

+.IR pathname " -> " linkname

+.RE

+.sp

+where

+.I pathname

+is the name of the file being extracted, and

+.I linkname

+is the name of a file which appeared earlier in the archive.

+.PP

+If the

+.B \-v

+option is specified, then

+.I pax

+list normal pathnames in the same format used by the

+.I ls

+utility with the

+.B \-l

+option.

+Hard links are shown as

+.sp

+.RS 1i

+.IR "<ls -l listing>" " == " linkname

+.RE

+.sp

+and symbolic links (if supported) are shown as

+.sp

+.RS 1i

+.IR "<ls -l listing>" " -> " linkname

+.RE

+.sp

+.PP

+.I Pax

+is capable of reading and writing archives which span multiple physical

+volumes.

+Upon detecting an end of medium on an archive which is not yet completed,

+.I pax

+will prompt the user for the next volume of the archive and will allow the

+user to specify the location of the next volume.

+.SS Options

+The following options are available:

+.TP 1i

+.B \-a

+The files specified by

+.I pathname

+are appended to the specified archive.

+.TP 1i

+.BI \-b " blocking"

+Block the output at

+.I blocking

+bytes per write to the archive file.

+A

+.B k

+suffix multiplies

+.I blocking

+by 1024, a

+.B b

+suffix multiplies

+.I blocking

+by 512 and a

+.B m

+suffix multiplies

+.I blocking

+by 1048576 (1 megabyte).

+For machines with 16-bit int's (VAXen, XENIX-286, etc.),

+the maximum buffer size is 32k-1.

+If not specified,

+.I blocking

+is automatically determined on input and is ignored for

+.B \-rw.

+.TP 1i

+.B \-c

+Complement the match sense of the

+.I pattern

+operands.

+.TP 1i

+.B \-d

+Intermediate directories not explicitly listed in the archive are not

+created.

+This option is ignored unless

+the

+.B \-r

+option is specified.

+.TP 1i

+.BI \-f " archive"

+The

+.I archive

+option specifies the pathname of the input or output archive,

+overriding the default of standard input for

+.B \-r

+or standard output for

+.BR \-w .

+.TP 1i

+.B \-i

+Interactively rename files.

+Substitutions specified by

+.B \-s

+options (described below)

+are performed before requesting the new file name from the user.

+A file is skipped if an empty line is entered and

+.I pax

+exits with an exit status of 0 if

+.B EOF

+is encountered.

+.TP 1i

+.B \-l

+Files are linked rather than copied when possible.

+.TP 1i

+.B \-m

+File modification times are not retained.

+.TP 1i

+.B \-n

+When

+.B \-r

+is specified, but

+.B \-w

+is not, the

+.I pattern

+arguments are treated as ordinary file names.

+Only the first occurrence of each of these files in the input archive

+is read.

+The

+.B pax

+utility exits with a zero exit status after all files in the list have been

+read.

+If one or more files in the list is not found,

+.B pax

+writes a diagnostic to standard error for each of the files and exits with

+a non-zero exit status.

+the file names are compared before any of the

+.BR \-i ,

+.BR \-s ,

+or

+.B \-y

+options are applied.

+.TP 1i

+.B \-o

+Restore file ownership as specified in the archive.

+The invoking process must have appropriate privileges to accomplish this.

+.TP 1i

+.B \-p

+Preserve the access time of the input files after they have been copied.

+.TP 1i

+.BI \-s " replstr"

+File names are modified according to the substitution expression using the

+syntax of

+.I "ed(1)"

+as shown:

+.sp

+.RS 2i

+-s /\fIold\fR/\fInew\fR/\fB[\fRgp\fB]\fR

+.RE

+.RS 1i

+.PP

+Any non null character may be used as a delimiter (a / is used here as an

+example).

+Multiple

+.B \-s

+expressions may be specified; the expressions are applied in the order

+specified terminating with the first successful substitution.

+The optional trailing

+.B p

+causes successful mappings to be listed on standard error.

+The optional trailing

+.B g

+causes the

+.I old

+expression to be replaced each time it occurs in the source string.

+Files that substitute to an empty string are ignored both on input and

+output.

+.RE

+.TP 1i

+.BI \-t " device"

+The

+.I device

+option argument is an implementation-defined identifier that names the input

+or output archive device, overriding the default of standard input for

+.B \-r

+and standard output for

+.BR \-w .

+.TP 1i

+.B \-u

+Copy each file only if it is newer than a pre-existing file with the same

+name.

+This implies

+.BR \-a .

+.TP 1i

+.B \-v

+List file names as they are encountered.

+Produces a verbose table of contents listing on the standard output when both

+.B \-r

+and

+.B \-w

+are omitted,

+otherwise the file names are printed to standard error as they are

+encountered in the archive.

+.TP 1i

+.BI \-x " format"

+Specifies the output archive

+.IR format .

+The input format, which must be one of the following, is automatically

+determined when the

+.B \-r

+option is used.

+The supported formats are:

+.RS 1i

+.TP 0.75i

+.I cpio

+The extended

+.I CPIO

+interchange format specified in

+.B "Extended CPIO Format" in

+.I "IEEE Std. 1003.1-1988."

+.TP 0.75i

+.I ustar

+The extended

+.I TAR

+interchange format specified in

+.B "Extended TAR Format" in

+.I "IEEE Std. 1003.1-1988."

+This is the default archive format.

+.RE

+.TP 1i

+.B \-y

+Interactively prompt for the disposition of each file.

+Substitutions specified by

+.B \-s

+options (described above)

+are performed before prompting the user for disposition.

+.B EOF

+or an input line starting with the character

+.B q

+caused

+.I pax

+to exit.

+Otherwise, an input line starting with anything other than

+.B y

+causes the file to be ignored.

+This option cannot be used in conjunction with the

+.B \-i

+option.

+.PP

+Only the last of multiple

+.B \-f

+or

+.B \-t

+options take effect.

+.PP

+When writing to an archive, the

+standard input is used as a list of pathnames if no

+.I pathname

+operands are specified.

+The format is one pathname per line.

+Otherwise, the standard input is the archive file,

+which is formatted according to one of the specifications in

+.B "Archive/Interchange File format"

+in

+.IR "IEEE Std. 1003.1-1988" ,

+or some other implementation-defined format.

+.PP

+The user ID and group ID of the process, together with the appropriate

+privileges, affect the ability of

+.I pax

+to restore ownership and permissions attributes of the archived files.

+(See

+.I "format-reading utility"

+in

+.B "Archive/Interchange File Format"

+in

+.IR "IEEE Std. 1003.1-1988" ".)"

+.PP

+The options

+.BR \-a ,

+.BR \-c ,

+.BR \-d ,

+.BR \-i ,

+.BR \-l ,

+.BR \-p ,

+.BR \-t ,

+.BR \-u ,

+and

+.BR \-y

+are provided for functional compatibility with the historical

+.I cpio

+and

+.I tar

+utilities.

+The option defaults were chosen based on the most common usage of these

+options, therefore, some of the options have meanings different than

+those of the historical commands.

+.SS Operands

+The following operands are available:

+.TP 1i

+.I directory

+The destination directory pathname for copies when both the

+.B \-r

+and

+.B \-w

+options are specified.

+The directory must exist and be writable before the copy or and error

+results.

+.TP 1i

+.I pathname

+A file whose contents are used instead of the files named on the standard

+input.

+When a directory is named, all of its files and (recursively)

+subdirectories

+are copied as well.

+.TP 1i

+.IR pattern

+A

+.I pattern

+is given in the standard shell pattern matching notation.

+The default if no

+.I pattern

+is  specified is

+.BR * \,

+which selects all files.

+.SH EXAMPLES

+The following command

+.sp

+.RS 1i

+pax \-w \-f /dev/rmt0 \.

+.RE

+.sp

+copies the contents of the current directory to tape drive 0.

+.PP

+The commands

+.sp

+.RS 1i

+.RI mkdir " newdir"

+.br

+.RI cd " olddir"

+.br

+.RI "pax -rw . " newdir

+.RE

+.sp

+copies the contents of

+.I olddir

+to

+.I newdir .

+.PP

+The command

+.sp

+.RS 1i

+pax \-r \-s ',//*usr//*,,' -f pax.out

+.RE

+.sp

+reads the archive

+.B pax.out

+with all files rooted in "/usr" in the archive extracted

+relative to the current directory.

+.SH FILES

+.TP 1i

+/dev/tty

+used to prompt the user for information when the

+.BR \-i " or " \-y

+options are specified.

+.SH "SEE ALSO"

+cpio(1), find(1), tar(1), cpio(5), tar(5)

+.SH DIAGNOSTICS

+.I Pax

+will terminate immediately, without processing any

+additional files on the command line or in the archive.

+.SH "EXIT CODES"

+.I Pax

+will exit with one of the following values:

+.IP 0 .5i

+All files in the archive were processed successfully.

+.IP ">0" .5i

+.I Pax

+aborted due to errors encountered during operation.

+.SH BUGS

+Special permissions may be required to copy or extract special files.

+.PP

+Device, user ID, and group ID numbers larger than 65535 cause additional

+header records to be output.

+These records are ignored by some historical version of

+.I "cpio(1)"

+and

+.IR "tar(1)" .

+.PP

+The archive formats described in

+.B "Archive/Interchange File Format"

+have certain restrictions that have

+been carried over from historical usage.

+For example, there are restrictions on the length of pathnames stored in

+the archive.

+.PP

+When getting an "ls -l" style listing on

+.I tar

+format archives, link counts are listed as zero since the

+.I ustar

+archive format does not keep link count information.

+.PP

+On 16 bit architectures, the largest buffer size is 32k-1.

+This is due, in part, to using integers in the buffer allocation schemes,

+however, on many of these machines, it is not possible to allocate blocks

+of memory larger than 32k.

+.SH COPYRIGHT

+Copyright (c) 1989 Mark H. Colburn.

+.br

+All rights reserved.

+.PP

+Redistribution and use in source and binary forms are permitted

+provided that the above copyright notice is duplicated in all such

+forms and that any documentation, advertising materials, and other

+materials related to such distribution and use acknowledge that the

+software was developed by Mark H. Colburn and sponsored by The

+USENIX Association.

+.PP

+THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR

+IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED

+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

+.SH AUTHOR

+Mark H. Colburn

+.br

+Minnetech Consulting, Inc.

+.br

+117 Mackubin Street, Suite 1

+.br

+St. Paul, MN 55102

+.br

[email protected]

+.sp 2

+Sponsored by

+.B "The USENIX Association"

+for public distribution.

--- a/sys/src/ape/cmd/pax/tar.1

+++ /dev/null

@@ -1,195 +1,0 @@

-.\" $Id: tar.1,v 1.2 89/02/12 10:08:55 mark Exp $

-.TH TAR 1 "USENIX Association" ""

-.SH NAME

-tar \- process tape archives

-.SH SYNOPSIS

-.B tar

-.BR \-c [ bfvw ]

-.I device

-.I block

-.I filename...

-.br

-.B tar

-.BR \-r [ bvw ]

-.I device

-.I block

-.RI [ filename... ]

-.br

-.B tar

-.BR \-t [ fv ]

-.I device

-.br

-.B tar

-.BR \-u [ bvw ]

-.I device

-.I block

-.br

-.B tar

-.BR \-x [ flmovw ]

-.I device

-.RI [ filename... ]

-.SH DESCRIPTION

-.I Tar

-reads and writes archive files which conform to the

-.B "Archive/Interchange File Format"

-specified in

-.IR "IEEE Std. 1003.1-1988" .

-.SS Options

-The following options are available:

-.TP 1i

-.B \-c

-Creates a new archive; writing begins at the beginning of the archive,

-instead of after the last file.

-.TP 1i

-.B \-r

-Writes names files to the end of the archive.

-.TP 1i

-.B \-t

-Lists the names of all of the files in the archive.

-.TP 1i

-.B \-u

-Causes named files to be

-added to the archive if they are not already there, or have been

-modified since last written into the archive.

-This implies the

-.B \-r

-option.

-.TP 1i

-.B \-x

-Extracts named files

-from the archive.

-If a named file matches a directory whose contents had been written onto

-the archive, that directory is recursively extracted.

-If a named file in the archive does not exist on the system, the file is

-create with the same mode as the one in the archive, except that the

-set-user-id and get-group-id modes are not set unless the user has

-appropriate privileges.

-.PP

-If the files exist, their modes are not changed except as described above.

-The owner, group and modification time are restored if possible.

-If no

-.I filename

-argument is given, the entire contents of the archive is extracted.

-Note that if several files with the same name are in the archive,

-the last one will overwrite all earlier ones.

-.TP 1i

-.B \-b

-Causes

-.I tar

-to use the next argument on the command line as the blocking factor for

-tape records.

-The default is 1; the maximum is 20.

-This option should only be used with raw magnetic tape archives.

-Normally, the block size is determined automatically when reading tapes.

-.TP 1i

-.B \-f

-Causes

-.I tar

-to use the next argument on the command line as the name of the archive

-instead of the default, which is usually a tape drive.

-If

-.B -

-is specified as a filename

-.I tar

-writes to the standard output or reads from the standard input, whichever

-is appropriate for the options given.

-Thus,

-.I tar

-can be used as the head or tail of a pipeline.

-.TP 1i

-.B \-l

-Tells

-.I tar

-to report if it cannot resolve all of the links to the files being

-archived.

-If

-.B \-l

-is not specified, no error messages are written to the standard output.

-This modifier is only valid with the

-.BR \-c ,

-.B \-r

-and

-.BR \-u

-options.

-.TP 1i

-.B \-m

-Tells

-.I tar

-not to restore the modification times.

-The modification time of the file will be the time of extraction.

-This modifier is invalid with th

-.B \-t

-option.

-.TP 1i

-.B \-o

-Causes extracted files to take on the user and group identifier of the user

-running the program rather than those on the archive.

-This modifier is only valid with the

-.B \-x

-option.

-.TP 1i

-.B \-v

-Causes

-.I tar

-to operate verbosely.  Usually,

-.I tar

-does its work silently, but

-the

-.B v

-modifier causes it to print the name of each file it processes,

-preceded by the option letter.

-With the

-.B \-t

-option,

-.B v

-gives more information about the archive entries than just the name.

-.TP 1i

-.B \-w

-Causes

-.I tar

-to print the action to be taken, followed by the name of the file, and then

-wait for the user's confirmation.

-If a word beginning with

-.B y

-is given, the action is performed.

-Any other input means "no".

-This modifier is invalid with the

-.B \-t

-option.

-.SH FILES

-.TP 1i

-/dev/tty

-used to prompt the user for information when the

-.BR \-i " or " \-y

-options are specified.

-.SH "SEE ALSO"

-cpio(1), dd(1), find(1), pax(1), cpio(5), tar(5)

-.SH COPYRIGHT

-Copyright (c) 1989 Mark H. Colburn.

-.br

-All rights reserved.

-.PP

-Redistribution and use in source and binary forms are permitted

-provided that the above copyright notice is duplicated in all such

-forms and that any documentation, advertising materials, and other

-materials related to such distribution and use acknowledge that the

-software was developed by Mark H. Colburn and sponsored by The

-USENIX Association.

-.PP

-THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR

-IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED

-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

-.SH AUTHOR

-Mark H. Colburn

-.br

-NAPS International

-.br

-117 Mackubin Street, Suite 1

-.br

-St. Paul, MN 55102

-.br

[email protected]

-.sp 2

-Sponsored by

-.B "The USENIX Association"

-for public distribution.

--- /dev/null

+++ b/sys/src/ape/cmd/pax/tar.1.man

@@ -1,0 +1,195 @@

+.\" $Id: tar.1,v 1.2 89/02/12 10:08:55 mark Exp $

+.TH TAR 1 "USENIX Association" ""

+.SH NAME

+tar \- process tape archives

+.SH SYNOPSIS

+.B tar

+.BR \-c [ bfvw ]

+.I device

+.I block

+.I filename...

+.br

+.B tar

+.BR \-r [ bvw ]

+.I device

+.I block

+.RI [ filename... ]

+.br

+.B tar

+.BR \-t [ fv ]

+.I device

+.br

+.B tar

+.BR \-u [ bvw ]

+.I device

+.I block

+.br

+.B tar

+.BR \-x [ flmovw ]

+.I device

+.RI [ filename... ]

+.SH DESCRIPTION

+.I Tar

+reads and writes archive files which conform to the

+.B "Archive/Interchange File Format"

+specified in

+.IR "IEEE Std. 1003.1-1988" .

+.SS Options

+The following options are available:

+.TP 1i

+.B \-c

+Creates a new archive; writing begins at the beginning of the archive,

+instead of after the last file.

+.TP 1i

+.B \-r

+Writes names files to the end of the archive.

+.TP 1i

+.B \-t

+Lists the names of all of the files in the archive.

+.TP 1i

+.B \-u

+Causes named files to be

+added to the archive if they are not already there, or have been

+modified since last written into the archive.

+This implies the

+.B \-r

+option.

+.TP 1i

+.B \-x

+Extracts named files

+from the archive.

+If a named file matches a directory whose contents had been written onto

+the archive, that directory is recursively extracted.

+If a named file in the archive does not exist on the system, the file is

+create with the same mode as the one in the archive, except that the

+set-user-id and get-group-id modes are not set unless the user has

+appropriate privileges.

+.PP

+If the files exist, their modes are not changed except as described above.

+The owner, group and modification time are restored if possible.

+If no

+.I filename

+argument is given, the entire contents of the archive is extracted.

+Note that if several files with the same name are in the archive,

+the last one will overwrite all earlier ones.

+.TP 1i

+.B \-b

+Causes

+.I tar

+to use the next argument on the command line as the blocking factor for

+tape records.

+The default is 1; the maximum is 20.

+This option should only be used with raw magnetic tape archives.

+Normally, the block size is determined automatically when reading tapes.

+.TP 1i

+.B \-f

+Causes

+.I tar

+to use the next argument on the command line as the name of the archive

+instead of the default, which is usually a tape drive.

+If

+.B -

+is specified as a filename

+.I tar

+writes to the standard output or reads from the standard input, whichever

+is appropriate for the options given.

+Thus,

+.I tar

+can be used as the head or tail of a pipeline.

+.TP 1i

+.B \-l

+Tells

+.I tar

+to report if it cannot resolve all of the links to the files being

+archived.

+If

+.B \-l

+is not specified, no error messages are written to the standard output.

+This modifier is only valid with the

+.BR \-c ,

+.B \-r

+and

+.BR \-u

+options.

+.TP 1i

+.B \-m

+Tells

+.I tar

+not to restore the modification times.

+The modification time of the file will be the time of extraction.

+This modifier is invalid with th

+.B \-t

+option.

+.TP 1i

+.B \-o

+Causes extracted files to take on the user and group identifier of the user

+running the program rather than those on the archive.

+This modifier is only valid with the

+.B \-x

+option.

+.TP 1i

+.B \-v

+Causes

+.I tar

+to operate verbosely.  Usually,

+.I tar

+does its work silently, but

+the

+.B v

+modifier causes it to print the name of each file it processes,

+preceded by the option letter.

+With the

+.B \-t

+option,

+.B v

+gives more information about the archive entries than just the name.

+.TP 1i

+.B \-w

+Causes

+.I tar

+to print the action to be taken, followed by the name of the file, and then

+wait for the user's confirmation.

+If a word beginning with

+.B y

+is given, the action is performed.

+Any other input means "no".

+This modifier is invalid with the

+.B \-t

+option.

+.SH FILES

+.TP 1i

+/dev/tty

+used to prompt the user for information when the

+.BR \-i " or " \-y

+options are specified.

+.SH "SEE ALSO"

+cpio(1), dd(1), find(1), pax(1), cpio(5), tar(5)

+.SH COPYRIGHT

+Copyright (c) 1989 Mark H. Colburn.

+.br

+All rights reserved.

+.PP

+Redistribution and use in source and binary forms are permitted

+provided that the above copyright notice is duplicated in all such

+forms and that any documentation, advertising materials, and other

+materials related to such distribution and use acknowledge that the

+software was developed by Mark H. Colburn and sponsored by The

+USENIX Association.

+.PP

+THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR

+IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED

+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

+.SH AUTHOR

+Mark H. Colburn

+.br

+NAPS International

+.br

+117 Mackubin Street, Suite 1

+.br

+St. Paul, MN 55102

+.br

[email protected]

+.sp 2

+Sponsored by

+.B "The USENIX Association"

+for public distribution.

--- a/sys/src/cmd/gs/jpeg/ansi2knr.1

+++ /dev/null

@@ -1,36 +1,0 @@

-.TH ANSI2KNR 1 "19 Jan 1996"

-.SH NAME

-ansi2knr \- convert ANSI C to Kernighan & Ritchie C

-.SH SYNOPSIS

-.I ansi2knr

-[--varargs] input_file [output_file]

-.SH DESCRIPTION

-If no output_file is supplied, output goes to stdout.

-.br

-There are no error messages.

-.sp

-.I ansi2knr

-recognizes function definitions by seeing a non-keyword identifier at the left

-margin, followed by a left parenthesis, with a right parenthesis as the last

-character on the line, and with a left brace as the first token on the

-following line (ignoring possible intervening comments).  It will recognize a

-multi-line header provided that no intervening line ends with a left or right

-brace or a semicolon.  These algorithms ignore whitespace and comments, except

-that the function name must be the first thing on the line.

-.sp

-The following constructs will confuse it:

-.br

-     - Any other construct that starts at the left margin and follows the

-above syntax (such as a macro or function call).

-.br

-     - Some macros that tinker with the syntax of the function header.

-.sp

-The --varargs switch is obsolete, and is recognized only for

-backwards compatibility.  The present version of

-.I ansi2knr

-will always attempt to convert a ... argument to va_alist and va_dcl.

-.SH AUTHOR

-L. Peter Deutsch <[email protected]> wrote the original ansi2knr and

-continues to maintain the current version; most of the code in the current

-version is his work.  ansi2knr also includes contributions by Francois

-Pinard <[email protected]> and Jim Avera <[email protected]>.

--- /dev/null

+++ b/sys/src/cmd/gs/jpeg/ansi2knr.1.man

@@ -1,0 +1,36 @@

+.TH ANSI2KNR 1 "19 Jan 1996"

+.SH NAME

+ansi2knr \- convert ANSI C to Kernighan & Ritchie C

+.SH SYNOPSIS

+.I ansi2knr

+[--varargs] input_file [output_file]

+.SH DESCRIPTION

+If no output_file is supplied, output goes to stdout.

+.br

+There are no error messages.

+.sp

+.I ansi2knr

+recognizes function definitions by seeing a non-keyword identifier at the left

+margin, followed by a left parenthesis, with a right parenthesis as the last

+character on the line, and with a left brace as the first token on the

+following line (ignoring possible intervening comments).  It will recognize a

+multi-line header provided that no intervening line ends with a left or right

+brace or a semicolon.  These algorithms ignore whitespace and comments, except

+that the function name must be the first thing on the line.

+.sp

+The following constructs will confuse it:

+.br

+     - Any other construct that starts at the left margin and follows the

+above syntax (such as a macro or function call).

+.br

+     - Some macros that tinker with the syntax of the function header.

+.sp

+The --varargs switch is obsolete, and is recognized only for

+backwards compatibility.  The present version of

+.I ansi2knr

+will always attempt to convert a ... argument to va_alist and va_dcl.

+.SH AUTHOR

+L. Peter Deutsch <[email protected]> wrote the original ansi2knr and

+continues to maintain the current version; most of the code in the current

+version is his work.  ansi2knr also includes contributions by Francois

+Pinard <[email protected]> and Jim Avera <[email protected]>.

--- a/sys/src/cmd/gs/jpeg/cjpeg.1

+++ /dev/null

@@ -1,292 +1,0 @@

-.TH CJPEG 1 "20 March 1998"

-.SH NAME

-cjpeg \- compress an image file to a JPEG file

-.SH SYNOPSIS

-.B cjpeg

-[

-.I options

-]

-[

-.I filename

-]

-.LP

-.SH DESCRIPTION

-.LP

-.B cjpeg

-compresses the named image file, or the standard input if no file is

-named, and produces a JPEG/JFIF file on the standard output.

-The currently supported input file formats are: PPM (PBMPLUS color

-format), PGM (PBMPLUS gray-scale format), BMP, Targa, and RLE (Utah Raster

-Toolkit format).  (RLE is supported only if the URT library is available.)

-.SH OPTIONS

-All switch names may be abbreviated; for example,

-.B \-grayscale

-may be written

-.B \-gray

-or

-.BR \-gr .

-Most of the "basic" switches can be abbreviated to as little as one letter.

-Upper and lower case are equivalent (thus

-.B \-BMP

-is the same as

-.BR \-bmp ).

-British spellings are also accepted (e.g.,

-.BR \-greyscale ),

-though for brevity these are not mentioned below.

-.PP

-The basic switches are:

-.TP

-.BI \-quality " N"

-Scale quantization tables to adjust image quality.  Quality is 0 (worst) to

-100 (best); default is 75.  (See below for more info.)

-.TP

-.B \-grayscale

-Create monochrome JPEG file from color input.  Be sure to use this switch when

-compressing a grayscale BMP file, because

-.B cjpeg

-isn't bright enough to notice whether a BMP file uses only shades of gray.

-By saying

-.BR \-grayscale ,

-you'll get a smaller JPEG file that takes less time to process.

-.TP

-.B \-optimize

-Perform optimization of entropy encoding parameters.  Without this, default

-encoding parameters are used.

-.B \-optimize

-usually makes the JPEG file a little smaller, but

-.B cjpeg

-runs somewhat slower and needs much more memory.  Image quality and speed of

-decompression are unaffected by

-.BR \-optimize .

-.TP

-.B \-progressive

-Create progressive JPEG file (see below).

-.TP

-.B \-targa

-Input file is Targa format.  Targa files that contain an "identification"

-field will not be automatically recognized by

-.BR cjpeg ;

-for such files you must specify

-.B \-targa

-to make

-.B cjpeg

-treat the input as Targa format.

-For most Targa files, you won't need this switch.

-.PP

-The

-.B \-quality

-switch lets you trade off compressed file size against quality of the

-reconstructed image: the higher the quality setting, the larger the JPEG file,

-and the closer the output image will be to the original input.  Normally you

-want to use the lowest quality setting (smallest file) that decompresses into

-something visually indistinguishable from the original image.  For this

-purpose the quality setting should be between 50 and 95; the default of 75 is

-often about right.  If you see defects at

-.B \-quality

-75, then go up 5 or 10 counts at a time until you are happy with the output

-image.  (The optimal setting will vary from one image to another.)

-.PP

-.B \-quality

-100 will generate a quantization table of all 1's, minimizing loss in the

-quantization step (but there is still information loss in subsampling, as well

-as roundoff error).  This setting is mainly of interest for experimental

-purposes.  Quality values above about 95 are

-.B not

-recommended for normal use; the compressed file size goes up dramatically for

-hardly any gain in output image quality.

-.PP

-In the other direction, quality values below 50 will produce very small files

-of low image quality.  Settings around 5 to 10 might be useful in preparing an

-index of a large image library, for example.  Try

-.B \-quality

-2 (or so) for some amusing Cubist effects.  (Note: quality

-values below about 25 generate 2-byte quantization tables, which are

-considered optional in the JPEG standard.

-.B cjpeg

-emits a warning message when you give such a quality value, because some

-other JPEG programs may be unable to decode the resulting file.  Use

-.B \-baseline

-if you need to ensure compatibility at low quality values.)

-.PP

-The

-.B \-progressive

-switch creates a "progressive JPEG" file.  In this type of JPEG file, the data

-is stored in multiple scans of increasing quality.  If the file is being

-transmitted over a slow communications link, the decoder can use the first

-scan to display a low-quality image very quickly, and can then improve the

-display with each subsequent scan.  The final image is exactly equivalent to a

-standard JPEG file of the same quality setting, and the total file size is

-about the same --- often a little smaller.

-.B Caution:

-progressive JPEG is not yet widely implemented, so many decoders will be

-unable to view a progressive JPEG file at all.

-.PP

-Switches for advanced users:

-.TP

-.B \-dct int

-Use integer DCT method (default).

-.TP

-.B \-dct fast

-Use fast integer DCT (less accurate).

-.TP

-.B \-dct float

-Use floating-point DCT method.

-The float method is very slightly more accurate than the int method, but is

-much slower unless your machine has very fast floating-point hardware.  Also

-note that results of the floating-point method may vary slightly across

-machines, while the integer methods should give the same results everywhere.

-The fast integer method is much less accurate than the other two.

-.TP

-.BI \-restart " N"

-Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is

-attached to the number.

-.B \-restart 0

-(the default) means no restart markers.

-.TP

-.BI \-smooth " N"

-Smooth the input image to eliminate dithering noise.  N, ranging from 1 to

-100, indicates the strength of smoothing.  0 (the default) means no smoothing.

-.TP

-.BI \-maxmemory " N"

-Set limit for amount of memory to use in processing large images.  Value is

-in thousands of bytes, or millions of bytes if "M" is attached to the

-number.  For example,

-.B \-max 4m

-selects 4000000 bytes.  If more space is needed, temporary files will be used.

-.TP

-.BI \-outfile " name"

-Send output image to the named file, not to standard output.

-.TP

-.B \-verbose

-Enable debug printout.  More

-.BR \-v 's

-give more output.  Also, version information is printed at startup.

-.TP

-.B \-debug

-Same as

-.BR \-verbose .

-.PP

-The

-.B \-restart

-option inserts extra markers that allow a JPEG decoder to resynchronize after

-a transmission error.  Without restart markers, any damage to a compressed

-file will usually ruin the image from the point of the error to the end of the

-image; with restart markers, the damage is usually confined to the portion of

-the image up to the next restart marker.  Of course, the restart markers

-occupy extra space.  We recommend

-.B \-restart 1

-for images that will be transmitted across unreliable networks such as Usenet.

-.PP

-The

-.B \-smooth

-option filters the input to eliminate fine-scale noise.  This is often useful

-when converting dithered images to JPEG: a moderate smoothing factor of 10 to

-50 gets rid of dithering patterns in the input file, resulting in a smaller

-JPEG file and a better-looking image.  Too large a smoothing factor will

-visibly blur the image, however.

-.PP

-Switches for wizards:

-.TP

-.B \-baseline

-Force baseline-compatible quantization tables to be generated.  This clamps

-quantization values to 8 bits even at low quality settings.  (This switch is

-poorly named, since it does not ensure that the output is actually baseline

-JPEG.  For example, you can use

-.B \-baseline

-and

-.B \-progressive

-together.)

-.TP

-.BI \-qtables " file"

-Use the quantization tables given in the specified text file.

-.TP

-.BI \-qslots " N[,...]"

-Select which quantization table to use for each color component.

-.TP

-.BI \-sample " HxV[,...]"

-Set JPEG sampling factors for each color component.

-.TP

-.BI \-scans " file"

-Use the scan script given in the specified text file.

-.PP

-The "wizard" switches are intended for experimentation with JPEG.  If you

-don't know what you are doing, \fBdon't use them\fR.  These switches are

-documented further in the file wizard.doc.

-.SH EXAMPLES

-.LP

-This example compresses the PPM file foo.ppm with a quality factor of

-60 and saves the output as foo.jpg:

-.IP

-.B cjpeg \-quality

-.I 60 foo.ppm

-.B >

-.I foo.jpg

-.SH HINTS

-Color GIF files are not the ideal input for JPEG; JPEG is really intended for

-compressing full-color (24-bit) images.  In particular, don't try to convert

-cartoons, line drawings, and other images that have only a few distinct

-colors.  GIF works great on these, JPEG does not.  If you want to convert a

-GIF to JPEG, you should experiment with

-.BR cjpeg 's

-.B \-quality

-and

-.B \-smooth

-options to get a satisfactory conversion.

-.B \-smooth 10

-or so is often helpful.

-.PP

-Avoid running an image through a series of JPEG compression/decompression

-cycles.  Image quality loss will accumulate; after ten or so cycles the image

-may be noticeably worse than it was after one cycle.  It's best to use a

-lossless format while manipulating an image, then convert to JPEG format when

-you are ready to file the image away.

-.PP

-The

-.B \-optimize

-option to

-.B cjpeg

-is worth using when you are making a "final" version for posting or archiving.

-It's also a win when you are using low quality settings to make very small

-JPEG files; the percentage improvement is often a lot more than it is on

-larger files.  (At present,

-.B \-optimize

-mode is always selected when generating progressive JPEG files.)

-.SH ENVIRONMENT

-.TP

-.B JPEGMEM

-If this environment variable is set, its value is the default memory limit.

-The value is specified as described for the

-.B \-maxmemory

-switch.

-.B JPEGMEM

-overrides the default value specified when the program was compiled, and

-itself is overridden by an explicit

-.BR \-maxmemory .

-.SH SEE ALSO

-.BR djpeg (1),

-.BR jpegtran (1),

-.BR rdjpgcom (1),

-.BR wrjpgcom (1)

-.br

-.BR ppm (5),

-.BR pgm (5)

-.br

-Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",

-Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

-.SH AUTHOR

-Independent JPEG Group

-.SH BUGS

-Arithmetic coding is not supported for legal reasons.

-.PP

-GIF input files are no longer supported, to avoid the Unisys LZW patent.

-Use a Unisys-licensed program if you need to read a GIF file.  (Conversion

-of GIF files to JPEG is usually a bad idea anyway.)

-.PP

-Not all variants of BMP and Targa file formats are supported.

-.PP

-The

-.B \-targa

-switch is not a bug, it's a feature.  (It would be a bug if the Targa format

-designers had not been clueless.)

-.PP

-Still not as fast as we'd like.

--- /dev/null

+++ b/sys/src/cmd/gs/jpeg/cjpeg.1.man

@@ -1,0 +1,292 @@

+.TH CJPEG 1 "20 March 1998"

+.SH NAME

+cjpeg \- compress an image file to a JPEG file

+.SH SYNOPSIS

+.B cjpeg

+[

+.I options

+]

+[

+.I filename

+]

+.LP

+.SH DESCRIPTION

+.LP

+.B cjpeg

+compresses the named image file, or the standard input if no file is

+named, and produces a JPEG/JFIF file on the standard output.

+The currently supported input file formats are: PPM (PBMPLUS color

+format), PGM (PBMPLUS gray-scale format), BMP, Targa, and RLE (Utah Raster

+Toolkit format).  (RLE is supported only if the URT library is available.)

+.SH OPTIONS

+All switch names may be abbreviated; for example,

+.B \-grayscale

+may be written

+.B \-gray

+or

+.BR \-gr .

+Most of the "basic" switches can be abbreviated to as little as one letter.

+Upper and lower case are equivalent (thus

+.B \-BMP

+is the same as

+.BR \-bmp ).

+British spellings are also accepted (e.g.,

+.BR \-greyscale ),

+though for brevity these are not mentioned below.

+.PP

+The basic switches are:

+.TP

+.BI \-quality " N"

+Scale quantization tables to adjust image quality.  Quality is 0 (worst) to

+100 (best); default is 75.  (See below for more info.)

+.TP

+.B \-grayscale

+Create monochrome JPEG file from color input.  Be sure to use this switch when

+compressing a grayscale BMP file, because

+.B cjpeg

+isn't bright enough to notice whether a BMP file uses only shades of gray.

+By saying

+.BR \-grayscale ,

+you'll get a smaller JPEG file that takes less time to process.

+.TP

+.B \-optimize

+Perform optimization of entropy encoding parameters.  Without this, default

+encoding parameters are used.

+.B \-optimize

+usually makes the JPEG file a little smaller, but

+.B cjpeg

+runs somewhat slower and needs much more memory.  Image quality and speed of

+decompression are unaffected by

+.BR \-optimize .

+.TP

+.B \-progressive

+Create progressive JPEG file (see below).

+.TP

+.B \-targa

+Input file is Targa format.  Targa files that contain an "identification"

+field will not be automatically recognized by

+.BR cjpeg ;

+for such files you must specify

+.B \-targa

+to make

+.B cjpeg

+treat the input as Targa format.

+For most Targa files, you won't need this switch.

+.PP

+The

+.B \-quality

+switch lets you trade off compressed file size against quality of the

+reconstructed image: the higher the quality setting, the larger the JPEG file,

+and the closer the output image will be to the original input.  Normally you

+want to use the lowest quality setting (smallest file) that decompresses into

+something visually indistinguishable from the original image.  For this

+purpose the quality setting should be between 50 and 95; the default of 75 is

+often about right.  If you see defects at

+.B \-quality

+75, then go up 5 or 10 counts at a time until you are happy with the output

+image.  (The optimal setting will vary from one image to another.)

+.PP

+.B \-quality

+100 will generate a quantization table of all 1's, minimizing loss in the

+quantization step (but there is still information loss in subsampling, as well

+as roundoff error).  This setting is mainly of interest for experimental

+purposes.  Quality values above about 95 are

+.B not

+recommended for normal use; the compressed file size goes up dramatically for

+hardly any gain in output image quality.

+.PP

+In the other direction, quality values below 50 will produce very small files

+of low image quality.  Settings around 5 to 10 might be useful in preparing an

+index of a large image library, for example.  Try

+.B \-quality

+2 (or so) for some amusing Cubist effects.  (Note: quality

+values below about 25 generate 2-byte quantization tables, which are

+considered optional in the JPEG standard.

+.B cjpeg

+emits a warning message when you give such a quality value, because some

+other JPEG programs may be unable to decode the resulting file.  Use

+.B \-baseline

+if you need to ensure compatibility at low quality values.)

+.PP

+The

+.B \-progressive

+switch creates a "progressive JPEG" file.  In this type of JPEG file, the data

+is stored in multiple scans of increasing quality.  If the file is being

+transmitted over a slow communications link, the decoder can use the first

+scan to display a low-quality image very quickly, and can then improve the

+display with each subsequent scan.  The final image is exactly equivalent to a

+standard JPEG file of the same quality setting, and the total file size is

+about the same --- often a little smaller.

+.B Caution:

+progressive JPEG is not yet widely implemented, so many decoders will be

+unable to view a progressive JPEG file at all.

+.PP

+Switches for advanced users:

+.TP

+.B \-dct int

+Use integer DCT method (default).

+.TP

+.B \-dct fast

+Use fast integer DCT (less accurate).

+.TP

+.B \-dct float

+Use floating-point DCT method.

+The float method is very slightly more accurate than the int method, but is

+much slower unless your machine has very fast floating-point hardware.  Also

+note that results of the floating-point method may vary slightly across

+machines, while the integer methods should give the same results everywhere.

+The fast integer method is much less accurate than the other two.

+.TP

+.BI \-restart " N"

+Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is

+attached to the number.

+.B \-restart 0

+(the default) means no restart markers.

+.TP

+.BI \-smooth " N"

+Smooth the input image to eliminate dithering noise.  N, ranging from 1 to

+100, indicates the strength of smoothing.  0 (the default) means no smoothing.

+.TP

+.BI \-maxmemory " N"

+Set limit for amount of memory to use in processing large images.  Value is

+in thousands of bytes, or millions of bytes if "M" is attached to the

+number.  For example,

+.B \-max 4m

+selects 4000000 bytes.  If more space is needed, temporary files will be used.

+.TP

+.BI \-outfile " name"

+Send output image to the named file, not to standard output.

+.TP

+.B \-verbose

+Enable debug printout.  More

+.BR \-v 's

+give more output.  Also, version information is printed at startup.

+.TP

+.B \-debug

+Same as

+.BR \-verbose .

+.PP

+The

+.B \-restart

+option inserts extra markers that allow a JPEG decoder to resynchronize after

+a transmission error.  Without restart markers, any damage to a compressed

+file will usually ruin the image from the point of the error to the end of the

+image; with restart markers, the damage is usually confined to the portion of

+the image up to the next restart marker.  Of course, the restart markers

+occupy extra space.  We recommend

+.B \-restart 1

+for images that will be transmitted across unreliable networks such as Usenet.

+.PP

+The

+.B \-smooth

+option filters the input to eliminate fine-scale noise.  This is often useful

+when converting dithered images to JPEG: a moderate smoothing factor of 10 to

+50 gets rid of dithering patterns in the input file, resulting in a smaller

+JPEG file and a better-looking image.  Too large a smoothing factor will

+visibly blur the image, however.

+.PP

+Switches for wizards:

+.TP

+.B \-baseline

+Force baseline-compatible quantization tables to be generated.  This clamps

+quantization values to 8 bits even at low quality settings.  (This switch is

+poorly named, since it does not ensure that the output is actually baseline

+JPEG.  For example, you can use

+.B \-baseline

+and

+.B \-progressive

+together.)

+.TP

+.BI \-qtables " file"

+Use the quantization tables given in the specified text file.

+.TP

+.BI \-qslots " N[,...]"

+Select which quantization table to use for each color component.

+.TP

+.BI \-sample " HxV[,...]"

+Set JPEG sampling factors for each color component.

+.TP

+.BI \-scans " file"

+Use the scan script given in the specified text file.

+.PP

+The "wizard" switches are intended for experimentation with JPEG.  If you

+don't know what you are doing, \fBdon't use them\fR.  These switches are

+documented further in the file wizard.doc.

+.SH EXAMPLES

+.LP

+This example compresses the PPM file foo.ppm with a quality factor of

+60 and saves the output as foo.jpg:

+.IP

+.B cjpeg \-quality

+.I 60 foo.ppm

+.B >

+.I foo.jpg

+.SH HINTS

+Color GIF files are not the ideal input for JPEG; JPEG is really intended for

+compressing full-color (24-bit) images.  In particular, don't try to convert

+cartoons, line drawings, and other images that have only a few distinct

+colors.  GIF works great on these, JPEG does not.  If you want to convert a

+GIF to JPEG, you should experiment with

+.BR cjpeg 's

+.B \-quality

+and

+.B \-smooth

+options to get a satisfactory conversion.

+.B \-smooth 10

+or so is often helpful.

+.PP

+Avoid running an image through a series of JPEG compression/decompression

+cycles.  Image quality loss will accumulate; after ten or so cycles the image

+may be noticeably worse than it was after one cycle.  It's best to use a

+lossless format while manipulating an image, then convert to JPEG format when

+you are ready to file the image away.

+.PP

+The

+.B \-optimize

+option to

+.B cjpeg

+is worth using when you are making a "final" version for posting or archiving.

+It's also a win when you are using low quality settings to make very small

+JPEG files; the percentage improvement is often a lot more than it is on

+larger files.  (At present,

+.B \-optimize

+mode is always selected when generating progressive JPEG files.)

+.SH ENVIRONMENT

+.TP

+.B JPEGMEM

+If this environment variable is set, its value is the default memory limit.

+The value is specified as described for the

+.B \-maxmemory

+switch.

+.B JPEGMEM

+overrides the default value specified when the program was compiled, and

+itself is overridden by an explicit

+.BR \-maxmemory .

+.SH SEE ALSO

+.BR djpeg (1),

+.BR jpegtran (1),

+.BR rdjpgcom (1),

+.BR wrjpgcom (1)

+.br

+.BR ppm (5),

+.BR pgm (5)

+.br

+Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",

+Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

+.SH AUTHOR

+Independent JPEG Group

+.SH BUGS

+Arithmetic coding is not supported for legal reasons.

+.PP

+GIF input files are no longer supported, to avoid the Unisys LZW patent.

+Use a Unisys-licensed program if you need to read a GIF file.  (Conversion

+of GIF files to JPEG is usually a bad idea anyway.)

+.PP

+Not all variants of BMP and Targa file formats are supported.

+.PP

+The

+.B \-targa

+switch is not a bug, it's a feature.  (It would be a bug if the Targa format

+designers had not been clueless.)

+.PP

+Still not as fast as we'd like.

--- a/sys/src/cmd/gs/jpeg/djpeg.1

+++ /dev/null

@@ -1,253 +1,0 @@

-.TH DJPEG 1 "22 August 1997"

-.SH NAME

-djpeg \- decompress a JPEG file to an image file

-.SH SYNOPSIS

-.B djpeg

-[

-.I options

-]

-[

-.I filename

-]

-.LP

-.SH DESCRIPTION

-.LP

-.B djpeg

-decompresses the named JPEG file, or the standard input if no file is named,

-and produces an image file on the standard output.  PBMPLUS (PPM/PGM), BMP,

-GIF, Targa, or RLE (Utah Raster Toolkit) output format can be selected.

-(RLE is supported only if the URT library is available.)

-.SH OPTIONS

-All switch names may be abbreviated; for example,

-.B \-grayscale

-may be written

-.B \-gray

-or

-.BR \-gr .

-Most of the "basic" switches can be abbreviated to as little as one letter.

-Upper and lower case are equivalent (thus

-.B \-BMP

-is the same as

-.BR \-bmp ).

-British spellings are also accepted (e.g.,

-.BR \-greyscale ),

-though for brevity these are not mentioned below.

-.PP

-The basic switches are:

-.TP

-.BI \-colors " N"

-Reduce image to at most N colors.  This reduces the number of colors used in

-the output image, so that it can be displayed on a colormapped display or

-stored in a colormapped file format.  For example, if you have an 8-bit

-display, you'd need to reduce to 256 or fewer colors.

-.TP

-.BI \-quantize " N"

-Same as

-.BR \-colors .

-.B \-colors

-is the recommended name,

-.B \-quantize

-is provided only for backwards compatibility.

-.TP

-.B \-fast

-Select recommended processing options for fast, low quality output.  (The

-default options are chosen for highest quality output.)  Currently, this is

-equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR.

-.TP

-.B \-grayscale

-Force gray-scale output even if JPEG file is color.  Useful for viewing on

-monochrome displays; also,

-.B djpeg

-runs noticeably faster in this mode.

-.TP

-.BI \-scale " M/N"

-Scale the output image by a factor M/N.  Currently the scale factor must be

-1/1, 1/2, 1/4, or 1/8.  Scaling is handy if the image is larger than your

-screen; also,

-.B djpeg

-runs much faster when scaling down the output.

-.TP

-.B \-bmp

-Select BMP output format (Windows flavor).  8-bit colormapped format is

-emitted if

-.B \-colors

-or

-.B \-grayscale

-is specified, or if the JPEG file is gray-scale; otherwise, 24-bit full-color

-format is emitted.

-.TP

-.B \-gif

-Select GIF output format.  Since GIF does not support more than 256 colors,

-.B \-colors 256

-is assumed (unless you specify a smaller number of colors).

-.TP

-.B \-os2

-Select BMP output format (OS/2 1.x flavor).  8-bit colormapped format is

-emitted if

-.B \-colors

-or

-.B \-grayscale

-is specified, or if the JPEG file is gray-scale; otherwise, 24-bit full-color

-format is emitted.

-.TP

-.B \-pnm

-Select PBMPLUS (PPM/PGM) output format (this is the default format).

-PGM is emitted if the JPEG file is gray-scale or if

-.B \-grayscale

-is specified; otherwise PPM is emitted.

-.TP

-.B \-rle

-Select RLE output format.  (Requires URT library.)

-.TP

-.B \-targa

-Select Targa output format.  Gray-scale format is emitted if the JPEG file is

-gray-scale or if

-.B \-grayscale

-is specified; otherwise, colormapped format is emitted if

-.B \-colors

-is specified; otherwise, 24-bit full-color format is emitted.

-.PP

-Switches for advanced users:

-.TP

-.B \-dct int

-Use integer DCT method (default).

-.TP

-.B \-dct fast

-Use fast integer DCT (less accurate).

-.TP

-.B \-dct float

-Use floating-point DCT method.

-The float method is very slightly more accurate than the int method, but is

-much slower unless your machine has very fast floating-point hardware.  Also

-note that results of the floating-point method may vary slightly across

-machines, while the integer methods should give the same results everywhere.

-The fast integer method is much less accurate than the other two.

-.TP

-.B \-dither fs

-Use Floyd-Steinberg dithering in color quantization.

-.TP

-.B \-dither ordered

-Use ordered dithering in color quantization.

-.TP

-.B \-dither none

-Do not use dithering in color quantization.

-By default, Floyd-Steinberg dithering is applied when quantizing colors; this

-is slow but usually produces the best results.  Ordered dither is a compromise

-between speed and quality; no dithering is fast but usually looks awful.  Note

-that these switches have no effect unless color quantization is being done.

-Ordered dither is only available in

-.B \-onepass

-mode.

-.TP

-.BI \-map " file"

-Quantize to the colors used in the specified image file.  This is useful for

-producing multiple files with identical color maps, or for forcing a

-predefined set of colors to be used.  The

-.I file

-must be a GIF or PPM file. This option overrides

-.B \-colors

-and

-.BR \-onepass .

-.TP

-.B \-nosmooth

-Use a faster, lower-quality upsampling routine.

-.TP

-.B \-onepass

-Use one-pass instead of two-pass color quantization.  The one-pass method is

-faster and needs less memory, but it produces a lower-quality image.

-.B \-onepass

-is ignored unless you also say

-.B \-colors

-.IR N .

-Also, the one-pass method is always used for gray-scale output (the two-pass

-method is no improvement then).

-.TP

-.BI \-maxmemory " N"

-Set limit for amount of memory to use in processing large images.  Value is

-in thousands of bytes, or millions of bytes if "M" is attached to the

-number.  For example,

-.B \-max 4m

-selects 4000000 bytes.  If more space is needed, temporary files will be used.

-.TP

-.BI \-outfile " name"

-Send output image to the named file, not to standard output.

-.TP

-.B \-verbose

-Enable debug printout.  More

-.BR \-v 's

-give more output.  Also, version information is printed at startup.

-.TP

-.B \-debug

-Same as

-.BR \-verbose .

-.SH EXAMPLES

-.LP

-This example decompresses the JPEG file foo.jpg, quantizes it to

-256 colors, and saves the output in 8-bit BMP format in foo.bmp:

-.IP

-.B djpeg \-colors 256 \-bmp

-.I foo.jpg

-.B >

-.I foo.bmp

-.SH HINTS

-To get a quick preview of an image, use the

-.B \-grayscale

-and/or

-.B \-scale

-switches.

-.B \-grayscale \-scale 1/8

-is the fastest case.

-.PP

-Several options are available that trade off image quality to gain speed.

-.B \-fast

-turns on the recommended settings.

-.PP

-.B \-dct fast

-and/or

-.B \-nosmooth

-gain speed at a small sacrifice in quality.

-When producing a color-quantized image,

-.B \-onepass \-dither ordered

-is fast but much lower quality than the default behavior.

-.B \-dither none

-may give acceptable results in two-pass mode, but is seldom tolerable in

-one-pass mode.

-.PP

-If you are fortunate enough to have very fast floating point hardware,

-\fB\-dct float\fR may be even faster than \fB\-dct fast\fR.  But on most

-machines \fB\-dct float\fR is slower than \fB\-dct int\fR; in this case it is

-not worth using, because its theoretical accuracy advantage is too small to be

-significant in practice.

-.SH ENVIRONMENT

-.TP

-.B JPEGMEM

-If this environment variable is set, its value is the default memory limit.

-The value is specified as described for the

-.B \-maxmemory

-switch.

-.B JPEGMEM

-overrides the default value specified when the program was compiled, and

-itself is overridden by an explicit

-.BR \-maxmemory .

-.SH SEE ALSO

-.BR cjpeg (1),

-.BR jpegtran (1),

-.BR rdjpgcom (1),

-.BR wrjpgcom (1)

-.br

-.BR ppm (5),

-.BR pgm (5)

-.br

-Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",

-Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

-.SH AUTHOR

-Independent JPEG Group

-.SH BUGS

-Arithmetic coding is not supported for legal reasons.

-.PP

-To avoid the Unisys LZW patent,

-.B djpeg

-produces uncompressed GIF files.  These are larger than they should be, but

-are readable by standard GIF decoders.

-.PP

-Still not as fast as we'd like.

--- /dev/null

+++ b/sys/src/cmd/gs/jpeg/djpeg.1.man

@@ -1,0 +1,253 @@

+.TH DJPEG 1 "22 August 1997"

+.SH NAME

+djpeg \- decompress a JPEG file to an image file

+.SH SYNOPSIS

+.B djpeg

+[

+.I options

+]

+[

+.I filename

+]

+.LP

+.SH DESCRIPTION

+.LP

+.B djpeg

+decompresses the named JPEG file, or the standard input if no file is named,

+and produces an image file on the standard output.  PBMPLUS (PPM/PGM), BMP,

+GIF, Targa, or RLE (Utah Raster Toolkit) output format can be selected.

+(RLE is supported only if the URT library is available.)

+.SH OPTIONS

+All switch names may be abbreviated; for example,

+.B \-grayscale

+may be written

+.B \-gray

+or

+.BR \-gr .

+Most of the "basic" switches can be abbreviated to as little as one letter.

+Upper and lower case are equivalent (thus

+.B \-BMP

+is the same as

+.BR \-bmp ).

+British spellings are also accepted (e.g.,

+.BR \-greyscale ),

+though for brevity these are not mentioned below.

+.PP

+The basic switches are:

+.TP

+.BI \-colors " N"

+Reduce image to at most N colors.  This reduces the number of colors used in

+the output image, so that it can be displayed on a colormapped display or

+stored in a colormapped file format.  For example, if you have an 8-bit

+display, you'd need to reduce to 256 or fewer colors.

+.TP

+.BI \-quantize " N"

+Same as

+.BR \-colors .

+.B \-colors

+is the recommended name,

+.B \-quantize

+is provided only for backwards compatibility.

+.TP

+.B \-fast

+Select recommended processing options for fast, low quality output.  (The

+default options are chosen for highest quality output.)  Currently, this is

+equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR.

+.TP

+.B \-grayscale

+Force gray-scale output even if JPEG file is color.  Useful for viewing on

+monochrome displays; also,

+.B djpeg

+runs noticeably faster in this mode.

+.TP

+.BI \-scale " M/N"

+Scale the output image by a factor M/N.  Currently the scale factor must be

+1/1, 1/2, 1/4, or 1/8.  Scaling is handy if the image is larger than your

+screen; also,

+.B djpeg

+runs much faster when scaling down the output.

+.TP

+.B \-bmp

+Select BMP output format (Windows flavor).  8-bit colormapped format is

+emitted if

+.B \-colors

+or

+.B \-grayscale

+is specified, or if the JPEG file is gray-scale; otherwise, 24-bit full-color

+format is emitted.

+.TP

+.B \-gif

+Select GIF output format.  Since GIF does not support more than 256 colors,

+.B \-colors 256

+is assumed (unless you specify a smaller number of colors).

+.TP

+.B \-os2

+Select BMP output format (OS/2 1.x flavor).  8-bit colormapped format is

+emitted if

+.B \-colors

+or

+.B \-grayscale

+is specified, or if the JPEG file is gray-scale; otherwise, 24-bit full-color

+format is emitted.

+.TP

+.B \-pnm

+Select PBMPLUS (PPM/PGM) output format (this is the default format).

+PGM is emitted if the JPEG file is gray-scale or if

+.B \-grayscale

+is specified; otherwise PPM is emitted.

+.TP

+.B \-rle

+Select RLE output format.  (Requires URT library.)

+.TP

+.B \-targa

+Select Targa output format.  Gray-scale format is emitted if the JPEG file is

+gray-scale or if

+.B \-grayscale

+is specified; otherwise, colormapped format is emitted if

+.B \-colors

+is specified; otherwise, 24-bit full-color format is emitted.

+.PP

+Switches for advanced users:

+.TP

+.B \-dct int

+Use integer DCT method (default).

+.TP

+.B \-dct fast

+Use fast integer DCT (less accurate).

+.TP

+.B \-dct float

+Use floating-point DCT method.

+The float method is very slightly more accurate than the int method, but is

+much slower unless your machine has very fast floating-point hardware.  Also

+note that results of the floating-point method may vary slightly across

+machines, while the integer methods should give the same results everywhere.

+The fast integer method is much less accurate than the other two.

+.TP

+.B \-dither fs

+Use Floyd-Steinberg dithering in color quantization.

+.TP

+.B \-dither ordered

+Use ordered dithering in color quantization.

+.TP

+.B \-dither none

+Do not use dithering in color quantization.

+By default, Floyd-Steinberg dithering is applied when quantizing colors; this

+is slow but usually produces the best results.  Ordered dither is a compromise

+between speed and quality; no dithering is fast but usually looks awful.  Note

+that these switches have no effect unless color quantization is being done.

+Ordered dither is only available in

+.B \-onepass

+mode.

+.TP

+.BI \-map " file"

+Quantize to the colors used in the specified image file.  This is useful for

+producing multiple files with identical color maps, or for forcing a

+predefined set of colors to be used.  The

+.I file

+must be a GIF or PPM file. This option overrides

+.B \-colors

+and

+.BR \-onepass .

+.TP

+.B \-nosmooth

+Use a faster, lower-quality upsampling routine.

+.TP

+.B \-onepass

+Use one-pass instead of two-pass color quantization.  The one-pass method is

+faster and needs less memory, but it produces a lower-quality image.

+.B \-onepass

+is ignored unless you also say

+.B \-colors

+.IR N .

+Also, the one-pass method is always used for gray-scale output (the two-pass

+method is no improvement then).

+.TP

+.BI \-maxmemory " N"

+Set limit for amount of memory to use in processing large images.  Value is

+in thousands of bytes, or millions of bytes if "M" is attached to the

+number.  For example,

+.B \-max 4m

+selects 4000000 bytes.  If more space is needed, temporary files will be used.

+.TP

+.BI \-outfile " name"

+Send output image to the named file, not to standard output.

+.TP

+.B \-verbose

+Enable debug printout.  More

+.BR \-v 's

+give more output.  Also, version information is printed at startup.

+.TP

+.B \-debug

+Same as

+.BR \-verbose .

+.SH EXAMPLES

+.LP

+This example decompresses the JPEG file foo.jpg, quantizes it to

+256 colors, and saves the output in 8-bit BMP format in foo.bmp:

+.IP

+.B djpeg \-colors 256 \-bmp

+.I foo.jpg

+.B >

+.I foo.bmp

+.SH HINTS

+To get a quick preview of an image, use the

+.B \-grayscale

+and/or

+.B \-scale

+switches.

+.B \-grayscale \-scale 1/8

+is the fastest case.

+.PP

+Several options are available that trade off image quality to gain speed.

+.B \-fast

+turns on the recommended settings.

+.PP

+.B \-dct fast

+and/or

+.B \-nosmooth

+gain speed at a small sacrifice in quality.

+When producing a color-quantized image,

+.B \-onepass \-dither ordered

+is fast but much lower quality than the default behavior.

+.B \-dither none

+may give acceptable results in two-pass mode, but is seldom tolerable in

+one-pass mode.

+.PP

+If you are fortunate enough to have very fast floating point hardware,

+\fB\-dct float\fR may be even faster than \fB\-dct fast\fR.  But on most

+machines \fB\-dct float\fR is slower than \fB\-dct int\fR; in this case it is

+not worth using, because its theoretical accuracy advantage is too small to be

+significant in practice.

+.SH ENVIRONMENT

+.TP

+.B JPEGMEM

+If this environment variable is set, its value is the default memory limit.

+The value is specified as described for the

+.B \-maxmemory

+switch.

+.B JPEGMEM

+overrides the default value specified when the program was compiled, and

+itself is overridden by an explicit

+.BR \-maxmemory .

+.SH SEE ALSO

+.BR cjpeg (1),

+.BR jpegtran (1),

+.BR rdjpgcom (1),

+.BR wrjpgcom (1)

+.br

+.BR ppm (5),

+.BR pgm (5)

+.br

+Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",

+Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

+.SH AUTHOR

+Independent JPEG Group

+.SH BUGS

+Arithmetic coding is not supported for legal reasons.

+.PP

+To avoid the Unisys LZW patent,

+.B djpeg

+produces uncompressed GIF files.  These are larger than they should be, but

+are readable by standard GIF decoders.

+.PP

+Still not as fast as we'd like.

--- a/sys/src/cmd/gs/jpeg/jpegtran.1

+++ /dev/null

@@ -1,238 +1,0 @@

-.TH JPEGTRAN 1 "3 August 1997"

-.SH NAME

-jpegtran \- lossless transformation of JPEG files

-.SH SYNOPSIS

-.B jpegtran

-[

-.I options

-]

-[

-.I filename

-]

-.LP

-.SH DESCRIPTION

-.LP

-.B jpegtran

-performs various useful transformations of JPEG files.

-It can translate the coded representation from one variant of JPEG to another,

-for example from baseline JPEG to progressive JPEG or vice versa.  It can also

-perform some rearrangements of the image data, for example turning an image

-from landscape to portrait format by rotation.

-.PP

-.B jpegtran

-works by rearranging the compressed data (DCT coefficients), without

-ever fully decoding the image.  Therefore, its transformations are lossless:

-there is no image degradation at all, which would not be true if you used

-.B djpeg

-followed by

-.B cjpeg

-to accomplish the same conversion.  But by the same token,

-.B jpegtran

-cannot perform lossy operations such as changing the image quality.

-.PP

-.B jpegtran

-reads the named JPEG/JFIF file, or the standard input if no file is

-named, and produces a JPEG/JFIF file on the standard output.

-.SH OPTIONS

-All switch names may be abbreviated; for example,

-.B \-optimize

-may be written

-.B \-opt

-or

-.BR \-o .

-Upper and lower case are equivalent.

-British spellings are also accepted (e.g.,

-.BR \-optimise ),

-though for brevity these are not mentioned below.

-.PP

-To specify the coded JPEG representation used in the output file,

-.B jpegtran

-accepts a subset of the switches recognized by

-.BR cjpeg :

-.TP

-.B \-optimize

-Perform optimization of entropy encoding parameters.

-.TP

-.B \-progressive

-Create progressive JPEG file.

-.TP

-.BI \-restart " N"

-Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is

-attached to the number.

-.TP

-.BI \-scans " file"

-Use the scan script given in the specified text file.

-.PP

-See

-.BR cjpeg (1)

-for more details about these switches.

-If you specify none of these switches, you get a plain baseline-JPEG output

-file.  The quality setting and so forth are determined by the input file.

-.PP

-The image can be losslessly transformed by giving one of these switches:

-.TP

-.B \-flip horizontal

-Mirror image horizontally (left-right).

-.TP

-.B \-flip vertical

-Mirror image vertically (top-bottom).

-.TP

-.B \-rotate 90

-Rotate image 90 degrees clockwise.

-.TP

-.B \-rotate 180

-Rotate image 180 degrees.

-.TP

-.B \-rotate 270

-Rotate image 270 degrees clockwise (or 90 ccw).

-.TP

-.B \-transpose

-Transpose image (across UL-to-LR axis).

-.TP

-.B \-transverse

-Transverse transpose (across UR-to-LL axis).

-.PP

-The transpose transformation has no restrictions regarding image dimensions.

-The other transformations operate rather oddly if the image dimensions are not

-a multiple of the iMCU size (usually 8 or 16 pixels), because they can only

-transform complete blocks of DCT coefficient data in the desired way.

-.PP

-.BR jpegtran 's

-default behavior when transforming an odd-size image is designed

-to preserve exact reversibility and mathematical consistency of the

-transformation set.  As stated, transpose is able to flip the entire image

-area.  Horizontal mirroring leaves any partial iMCU column at the right edge

-untouched, but is able to flip all rows of the image.  Similarly, vertical

-mirroring leaves any partial iMCU row at the bottom edge untouched, but is

-able to flip all columns.  The other transforms can be built up as sequences

-of transpose and flip operations; for consistency, their actions on edge

-pixels are defined to be the same as the end result of the corresponding

-transpose-and-flip sequence.

-.PP

-For practical use, you may prefer to discard any untransformable edge pixels

-rather than having a strange-looking strip along the right and/or bottom edges

-of a transformed image.  To do this, add the

-.B \-trim

-switch:

-.TP

-.B \-trim

-Drop non-transformable edge blocks.

-.PP

-Obviously, a transformation with

-.B \-trim

-is not reversible, so strictly speaking

-.B jpegtran

-with this switch is not lossless.  Also, the expected mathematical

-equivalences between the transformations no longer hold.  For example,

-.B \-rot 270 -trim

-trims only the bottom edge, but

-.B \-rot 90 -trim

-followed by

-.B \-rot 180 -trim

-trims both edges.

-.PP

-Another not-strictly-lossless transformation switch is:

-.TP

-.B \-grayscale

-Force grayscale output.

-.PP

-This option discards the chrominance channels if the input image is YCbCr

-(ie, a standard color JPEG), resulting in a grayscale JPEG file.  The

-luminance channel is preserved exactly, so this is a better method of reducing

-to grayscale than decompression, conversion, and recompression.  This switch

-is particularly handy for fixing a monochrome picture that was mistakenly

-encoded as a color JPEG.  (In such a case, the space savings from getting rid

-of the near-empty chroma channels won't be large; but the decoding time for

-a grayscale JPEG is substantially less than that for a color JPEG.)

-.PP

-.B jpegtran

-also recognizes these switches that control what to do with "extra" markers,

-such as comment blocks:

-.TP

-.B \-copy none

-Copy no extra markers from source file.  This setting suppresses all

-comments and other excess baggage present in the source file.

-.TP

-.B \-copy comments

-Copy only comment markers.  This setting copies comments from the source file,

-but discards any other inessential data.

-.TP

-.B \-copy all

-Copy all extra markers.  This setting preserves miscellaneous markers

-found in the source file, such as JFIF thumbnails and Photoshop settings.

-In some files these extra markers can be sizable.

-.PP

-The default behavior is

-.BR "\-copy comments" .

-(Note: in IJG releases v6 and v6a,

-.B jpegtran

-always did the equivalent of

-.BR "\-copy none" .)

-.PP

-Additional switches recognized by jpegtran are:

-.TP

-.BI \-maxmemory " N"

-Set limit for amount of memory to use in processing large images.  Value is

-in thousands of bytes, or millions of bytes if "M" is attached to the

-number.  For example,

-.B \-max 4m

-selects 4000000 bytes.  If more space is needed, temporary files will be used.

-.TP

-.BI \-outfile " name"

-Send output image to the named file, not to standard output.

-.TP

-.B \-verbose

-Enable debug printout.  More

-.BR \-v 's

-give more output.  Also, version information is printed at startup.

-.TP

-.B \-debug

-Same as

-.BR \-verbose .

-.SH EXAMPLES

-.LP

-This example converts a baseline JPEG file to progressive form:

-.IP

-.B jpegtran \-progressive

-.I foo.jpg

-.B >

-.I fooprog.jpg

-.PP

-This example rotates an image 90 degrees clockwise, discarding any

-unrotatable edge pixels:

-.IP

-.B jpegtran \-rot 90 -trim

-.I foo.jpg

-.B >

-.I foo90.jpg

-.SH ENVIRONMENT

-.TP

-.B JPEGMEM

-If this environment variable is set, its value is the default memory limit.

-The value is specified as described for the

-.B \-maxmemory

-switch.

-.B JPEGMEM

-overrides the default value specified when the program was compiled, and

-itself is overridden by an explicit

-.BR \-maxmemory .

-.SH SEE ALSO

-.BR cjpeg (1),

-.BR djpeg (1),

-.BR rdjpgcom (1),

-.BR wrjpgcom (1)

-.br

-Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",

-Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

-.SH AUTHOR

-Independent JPEG Group

-.SH BUGS

-Arithmetic coding is not supported for legal reasons.

-.PP

-The transform options can't transform odd-size images perfectly.  Use

-.B \-trim

-if you don't like the results without it.

-.PP

-The entire image is read into memory and then written out again, even in

-cases where this isn't really necessary.  Expect swapping on large images,

-especially when using the more complex transform options.

--- /dev/null

+++ b/sys/src/cmd/gs/jpeg/jpegtran.1.man

@@ -1,0 +1,238 @@

+.TH JPEGTRAN 1 "3 August 1997"

+.SH NAME

+jpegtran \- lossless transformation of JPEG files

+.SH SYNOPSIS

+.B jpegtran

+[

+.I options

+]

+[

+.I filename

+]

+.LP

+.SH DESCRIPTION

+.LP

+.B jpegtran

+performs various useful transformations of JPEG files.

+It can translate the coded representation from one variant of JPEG to another,

+for example from baseline JPEG to progressive JPEG or vice versa.  It can also

+perform some rearrangements of the image data, for example turning an image

+from landscape to portrait format by rotation.

+.PP

+.B jpegtran

+works by rearranging the compressed data (DCT coefficients), without

+ever fully decoding the image.  Therefore, its transformations are lossless:

+there is no image degradation at all, which would not be true if you used

+.B djpeg

+followed by

+.B cjpeg

+to accomplish the same conversion.  But by the same token,

+.B jpegtran

+cannot perform lossy operations such as changing the image quality.

+.PP

+.B jpegtran

+reads the named JPEG/JFIF file, or the standard input if no file is

+named, and produces a JPEG/JFIF file on the standard output.

+.SH OPTIONS

+All switch names may be abbreviated; for example,

+.B \-optimize

+may be written

+.B \-opt

+or

+.BR \-o .

+Upper and lower case are equivalent.

+British spellings are also accepted (e.g.,

+.BR \-optimise ),

+though for brevity these are not mentioned below.

+.PP

+To specify the coded JPEG representation used in the output file,

+.B jpegtran

+accepts a subset of the switches recognized by

+.BR cjpeg :

+.TP

+.B \-optimize

+Perform optimization of entropy encoding parameters.

+.TP

+.B \-progressive

+Create progressive JPEG file.

+.TP

+.BI \-restart " N"

+Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is

+attached to the number.

+.TP

+.BI \-scans " file"

+Use the scan script given in the specified text file.

+.PP

+See

+.BR cjpeg (1)

+for more details about these switches.

+If you specify none of these switches, you get a plain baseline-JPEG output

+file.  The quality setting and so forth are determined by the input file.

+.PP

+The image can be losslessly transformed by giving one of these switches:

+.TP

+.B \-flip horizontal

+Mirror image horizontally (left-right).

+.TP

+.B \-flip vertical

+Mirror image vertically (top-bottom).

+.TP

+.B \-rotate 90

+Rotate image 90 degrees clockwise.

+.TP

+.B \-rotate 180

+Rotate image 180 degrees.

+.TP

+.B \-rotate 270

+Rotate image 270 degrees clockwise (or 90 ccw).

+.TP

+.B \-transpose

+Transpose image (across UL-to-LR axis).

+.TP

+.B \-transverse

+Transverse transpose (across UR-to-LL axis).

+.PP

+The transpose transformation has no restrictions regarding image dimensions.

+The other transformations operate rather oddly if the image dimensions are not

+a multiple of the iMCU size (usually 8 or 16 pixels), because they can only

+transform complete blocks of DCT coefficient data in the desired way.

+.PP

+.BR jpegtran 's

+default behavior when transforming an odd-size image is designed

+to preserve exact reversibility and mathematical consistency of the

+transformation set.  As stated, transpose is able to flip the entire image

+area.  Horizontal mirroring leaves any partial iMCU column at the right edge

+untouched, but is able to flip all rows of the image.  Similarly, vertical

+mirroring leaves any partial iMCU row at the bottom edge untouched, but is

+able to flip all columns.  The other transforms can be built up as sequences

+of transpose and flip operations; for consistency, their actions on edge

+pixels are defined to be the same as the end result of the corresponding

+transpose-and-flip sequence.

+.PP

+For practical use, you may prefer to discard any untransformable edge pixels

+rather than having a strange-looking strip along the right and/or bottom edges

+of a transformed image.  To do this, add the

+.B \-trim

+switch:

+.TP

+.B \-trim

+Drop non-transformable edge blocks.

+.PP

+Obviously, a transformation with

+.B \-trim

+is not reversible, so strictly speaking

+.B jpegtran

+with this switch is not lossless.  Also, the expected mathematical

+equivalences between the transformations no longer hold.  For example,

+.B \-rot 270 -trim

+trims only the bottom edge, but

+.B \-rot 90 -trim

+followed by

+.B \-rot 180 -trim

+trims both edges.

+.PP

+Another not-strictly-lossless transformation switch is:

+.TP

+.B \-grayscale

+Force grayscale output.

+.PP

+This option discards the chrominance channels if the input image is YCbCr

+(ie, a standard color JPEG), resulting in a grayscale JPEG file.  The

+luminance channel is preserved exactly, so this is a better method of reducing

+to grayscale than decompression, conversion, and recompression.  This switch

+is particularly handy for fixing a monochrome picture that was mistakenly

+encoded as a color JPEG.  (In such a case, the space savings from getting rid

+of the near-empty chroma channels won't be large; but the decoding time for

+a grayscale JPEG is substantially less than that for a color JPEG.)

+.PP

+.B jpegtran

+also recognizes these switches that control what to do with "extra" markers,

+such as comment blocks:

+.TP

+.B \-copy none

+Copy no extra markers from source file.  This setting suppresses all

+comments and other excess baggage present in the source file.

+.TP

+.B \-copy comments

+Copy only comment markers.  This setting copies comments from the source file,

+but discards any other inessential data.

+.TP

+.B \-copy all

+Copy all extra markers.  This setting preserves miscellaneous markers

+found in the source file, such as JFIF thumbnails and Photoshop settings.

+In some files these extra markers can be sizable.

+.PP

+The default behavior is

+.BR "\-copy comments" .

+(Note: in IJG releases v6 and v6a,

+.B jpegtran

+always did the equivalent of

+.BR "\-copy none" .)

+.PP

+Additional switches recognized by jpegtran are:

+.TP

+.BI \-maxmemory " N"

+Set limit for amount of memory to use in processing large images.  Value is

+in thousands of bytes, or millions of bytes if "M" is attached to the

+number.  For example,

+.B \-max 4m

+selects 4000000 bytes.  If more space is needed, temporary files will be used.

+.TP

+.BI \-outfile " name"

+Send output image to the named file, not to standard output.

+.TP

+.B \-verbose

+Enable debug printout.  More

+.BR \-v 's

+give more output.  Also, version information is printed at startup.

+.TP

+.B \-debug

+Same as

+.BR \-verbose .

+.SH EXAMPLES

+.LP

+This example converts a baseline JPEG file to progressive form:

+.IP

+.B jpegtran \-progressive

+.I foo.jpg

+.B >

+.I fooprog.jpg

+.PP

+This example rotates an image 90 degrees clockwise, discarding any

+unrotatable edge pixels:

+.IP

+.B jpegtran \-rot 90 -trim

+.I foo.jpg

+.B >

+.I foo90.jpg

+.SH ENVIRONMENT

+.TP

+.B JPEGMEM

+If this environment variable is set, its value is the default memory limit.

+The value is specified as described for the

+.B \-maxmemory

+switch.

+.B JPEGMEM

+overrides the default value specified when the program was compiled, and

+itself is overridden by an explicit

+.BR \-maxmemory .

+.SH SEE ALSO

+.BR cjpeg (1),

+.BR djpeg (1),

+.BR rdjpgcom (1),

+.BR wrjpgcom (1)

+.br

+Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",

+Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.

+.SH AUTHOR

+Independent JPEG Group

+.SH BUGS

+Arithmetic coding is not supported for legal reasons.

+.PP

+The transform options can't transform odd-size images perfectly.  Use

+.B \-trim

+if you don't like the results without it.

+.PP

+The entire image is read into memory and then written out again, even in

+cases where this isn't really necessary.  Expect swapping on large images,

+especially when using the more complex transform options.

--- a/sys/src/cmd/gs/jpeg/rdjpgcom.1

+++ /dev/null

@@ -1,54 +1,0 @@

-.TH RDJPGCOM 1 "11 October 1997"

-.SH NAME

-rdjpgcom \- display text comments from a JPEG file

-.SH SYNOPSIS

-.B rdjpgcom

-[

-.B \-verbose

-]

-[

-.I filename

-]

-.LP

-.SH DESCRIPTION

-.LP

-.B rdjpgcom

-reads the named JPEG/JFIF file, or the standard input if no file is named,

-and prints any text comments found in the file on the standard output.

-.PP

-The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file.

-Although the standard doesn't actually define what COM blocks are for, they

-are widely used to hold user-supplied text strings.  This lets you add

-annotations, titles, index terms, etc to your JPEG files, and later retrieve

-them as text.  COM blocks do not interfere with the image stored in the JPEG

-file.  The maximum size of a COM block is 64K, but you can have as many of

-them as you like in one JPEG file.

-.SH OPTIONS

-.TP

-.B \-verbose

-Causes

-.B rdjpgcom

-to also display the JPEG image dimensions.

-.PP

-Switch names may be abbreviated, and are not case sensitive.

-.SH HINTS

-.B rdjpgcom

-does not depend on the IJG JPEG library.  Its source code is intended as an

-illustration of the minimum amount of code required to parse a JPEG file

-header correctly.

-.PP

-In

-.B \-verbose

-mode,

-.B rdjpgcom

-will also attempt to print the contents of any "APP12" markers as text.

-Some digital cameras produce APP12 markers containing useful textual

-information.  If you like, you can modify the source code to print

-other APPn marker types as well.

-.SH SEE ALSO

-.BR cjpeg (1),

-.BR djpeg (1),

-.BR jpegtran (1),

-.BR wrjpgcom (1)

-.SH AUTHOR

-Independent JPEG Group

--- /dev/null

+++ b/sys/src/cmd/gs/jpeg/rdjpgcom.1.man

@@ -1,0 +1,54 @@

+.TH RDJPGCOM 1 "11 October 1997"

+.SH NAME

+rdjpgcom \- display text comments from a JPEG file

+.SH SYNOPSIS

+.B rdjpgcom

+[

+.B \-verbose

+]

+[

+.I filename

+]

+.LP

+.SH DESCRIPTION

+.LP

+.B rdjpgcom

+reads the named JPEG/JFIF file, or the standard input if no file is named,

+and prints any text comments found in the file on the standard output.

+.PP

+The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file.

+Although the standard doesn't actually define what COM blocks are for, they

+are widely used to hold user-supplied text strings.  This lets you add

+annotations, titles, index terms, etc to your JPEG files, and later retrieve

+them as text.  COM blocks do not interfere with the image stored in the JPEG

+file.  The maximum size of a COM block is 64K, but you can have as many of

+them as you like in one JPEG file.

+.SH OPTIONS

+.TP

+.B \-verbose

+Causes

+.B rdjpgcom

+to also display the JPEG image dimensions.

+.PP

+Switch names may be abbreviated, and are not case sensitive.

+.SH HINTS

+.B rdjpgcom

+does not depend on the IJG JPEG library.  Its source code is intended as an

+illustration of the minimum amount of code required to parse a JPEG file

+header correctly.

+.PP

+In

+.B \-verbose

+mode,

+.B rdjpgcom

+will also attempt to print the contents of any "APP12" markers as text.

+Some digital cameras produce APP12 markers containing useful textual

+information.  If you like, you can modify the source code to print

+other APPn marker types as well.

+.SH SEE ALSO

+.BR cjpeg (1),

+.BR djpeg (1),

+.BR jpegtran (1),

+.BR wrjpgcom (1)

+.SH AUTHOR

+Independent JPEG Group

--- a/sys/src/cmd/gs/jpeg/wrjpgcom.1

+++ /dev/null

@@ -1,103 +1,0 @@

-.TH WRJPGCOM 1 "15 June 1995"

-.SH NAME

-wrjpgcom \- insert text comments into a JPEG file

-.SH SYNOPSIS

-.B wrjpgcom

-[

-.B \-replace

-]

-[

-.BI \-comment " text"

-]

-[

-.BI \-cfile " name"

-]

-[

-.I filename

-]

-.LP

-.SH DESCRIPTION

-.LP

-.B wrjpgcom

-reads the named JPEG/JFIF file, or the standard input if no file is named,

-and generates a new JPEG/JFIF file on standard output.  A comment block is

-added to the file.

-.PP

-The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file.

-Although the standard doesn't actually define what COM blocks are for, they

-are widely used to hold user-supplied text strings.  This lets you add

-annotations, titles, index terms, etc to your JPEG files, and later retrieve

-them as text.  COM blocks do not interfere with the image stored in the JPEG

-file.  The maximum size of a COM block is 64K, but you can have as many of

-them as you like in one JPEG file.

-.PP

-.B wrjpgcom

-adds a COM block, containing text you provide, to a JPEG file.

-Ordinarily, the COM block is added after any existing COM blocks; but you

-can delete the old COM blocks if you wish.

-.SH OPTIONS

-Switch names may be abbreviated, and are not case sensitive.

-.TP

-.B \-replace

-Delete any existing COM blocks from the file.

-.TP

-.BI \-comment " text"

-Supply text for new COM block on command line.

-.TP

-.BI \-cfile " name"

-Read text for new COM block from named file.

-.PP

-If you have only one line of comment text to add, you can provide it on the

-command line with

-.BR \-comment .

-The comment text must be surrounded with quotes so that it is treated as a

-single argument.  Longer comments can be read from a text file.

-.PP

-If you give neither

-.B \-comment

-nor

-.BR \-cfile ,

-then

-.B wrjpgcom

-will read the comment text from standard input.  (In this case an input image

-file name MUST be supplied, so that the source JPEG file comes from somewhere

-else.)  You can enter multiple lines, up to 64KB worth.  Type an end-of-file

-indicator (usually control-D) to terminate the comment text entry.

-.PP

-.B wrjpgcom

-will not add a COM block if the provided comment string is empty.  Therefore

-\fB\-replace \-comment ""\fR can be used to delete all COM blocks from a file.

-.SH EXAMPLES

-.LP

-Add a short comment to in.jpg, producing out.jpg:

-.IP

-.B wrjpgcom \-c

-\fI"View of my back yard" in.jpg

-.B >

-.I out.jpg

-.PP

-Attach a long comment previously stored in comment.txt:

-.IP

-.B wrjpgcom

-.I in.jpg

-.B <

-.I comment.txt

-.B >

-.I out.jpg

-.PP

-or equivalently

-.IP

-.B wrjpgcom

-.B -cfile

-.I comment.txt

-.B <

-.I in.jpg

-.B >

-.I out.jpg

-.SH SEE ALSO

-.BR cjpeg (1),

-.BR djpeg (1),

-.BR jpegtran (1),

-.BR rdjpgcom (1)

-.SH AUTHOR

-Independent JPEG Group

--- /dev/null

+++ b/sys/src/cmd/gs/jpeg/wrjpgcom.1.man

@@ -1,0 +1,103 @@

+.TH WRJPGCOM 1 "15 June 1995"

+.SH NAME

+wrjpgcom \- insert text comments into a JPEG file

+.SH SYNOPSIS

+.B wrjpgcom

+[

+.B \-replace

+]

+[

+.BI \-comment " text"

+]

+[

+.BI \-cfile " name"

+]

+[

+.I filename

+]

+.LP

+.SH DESCRIPTION

+.LP

+.B wrjpgcom

+reads the named JPEG/JFIF file, or the standard input if no file is named,

+and generates a new JPEG/JFIF file on standard output.  A comment block is

+added to the file.

+.PP

+The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file.

+Although the standard doesn't actually define what COM blocks are for, they

+are widely used to hold user-supplied text strings.  This lets you add

+annotations, titles, index terms, etc to your JPEG files, and later retrieve

+them as text.  COM blocks do not interfere with the image stored in the JPEG

+file.  The maximum size of a COM block is 64K, but you can have as many of

+them as you like in one JPEG file.

+.PP

+.B wrjpgcom

+adds a COM block, containing text you provide, to a JPEG file.

+Ordinarily, the COM block is added after any existing COM blocks; but you

+can delete the old COM blocks if you wish.

+.SH OPTIONS

+Switch names may be abbreviated, and are not case sensitive.

+.TP

+.B \-replace

+Delete any existing COM blocks from the file.

+.TP

+.BI \-comment " text"

+Supply text for new COM block on command line.

+.TP

+.BI \-cfile " name"

+Read text for new COM block from named file.

+.PP

+If you have only one line of comment text to add, you can provide it on the

+command line with

+.BR \-comment .

+The comment text must be surrounded with quotes so that it is treated as a

+single argument.  Longer comments can be read from a text file.

+.PP

+If you give neither

+.B \-comment

+nor

+.BR \-cfile ,

+then

+.B wrjpgcom

+will read the comment text from standard input.  (In this case an input image

+file name MUST be supplied, so that the source JPEG file comes from somewhere

+else.)  You can enter multiple lines, up to 64KB worth.  Type an end-of-file

+indicator (usually control-D) to terminate the comment text entry.

+.PP

+.B wrjpgcom

+will not add a COM block if the provided comment string is empty.  Therefore

+\fB\-replace \-comment ""\fR can be used to delete all COM blocks from a file.

+.SH EXAMPLES

+.LP

+Add a short comment to in.jpg, producing out.jpg:

+.IP

+.B wrjpgcom \-c

+\fI"View of my back yard" in.jpg

+.B >

+.I out.jpg

+.PP

+Attach a long comment previously stored in comment.txt:

+.IP

+.B wrjpgcom

+.I in.jpg

+.B <

+.I comment.txt

+.B >

+.I out.jpg

+.PP

+or equivalently

+.IP

+.B wrjpgcom

+.B -cfile

+.I comment.txt

+.B <

+.I in.jpg

+.B >

+.I out.jpg

+.SH SEE ALSO

+.BR cjpeg (1),

+.BR djpeg (1),

+.BR jpegtran (1),

+.BR rdjpgcom (1)

+.SH AUTHOR

+Independent JPEG Group

--- a/sys/src/cmd/gs/libpng/libpng.3

+++ /dev/null

@@ -1,4022 +1,0 @@

-.TH LIBPNG 3 "December 3, 2004"

-.SH NAME

-libpng \- Portable Network Graphics (PNG) Reference Library 1.2.8

-.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

-\fBint png_check_sig (png_bytep \fP\fIsig\fP\fB, int \fInum\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

-\fBint png_debug(int \fP\fIlevel\fP\fB, png_const_charp \fImessage\fP\fB);\fP

-\fI\fB

-\fBint png_debug1(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fIp1\fP\fB);\fP

-\fI\fB

-\fBint png_debug2(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fP\fIp1\fP\fB, \fIp2\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_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_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_bKGD (png_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_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fP\fIpng_ptr\fP\fB, png_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_byte png_get_color_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_byte png_get_compression_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_byte png_get_copyright (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_get_error_ptr (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_byte png_get_filter_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_byte png_get_header_version (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_charpp \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_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_image_width (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_byte png_get_interlace_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_byte png_get_libpng_ver (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_get_mem_ptr(png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_get_progressive_ptr (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fIpng_ptr)

-\fBpng_uint_32 png_get_rowbytes (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_bytepp png_get_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP

-\fI\fB

-\fBpng_bytep png_get_signature (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fI*intent\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_text (png_structp \fP\fIpng_ptr\fP\fB, png_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_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_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_values\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_get_user_chunk_ptr (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_user_height_max( png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_get_user_transform_ptr (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_user_width_max (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_valid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP

-\fI\fB

-\fBpng_int_32 png_get_x_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_int_32 png_get_x_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_x_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_int_32 png_get_y_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_int_32 png_get_y_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_y_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_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_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP

-\fI\fB

-\fBDEPRECATED: void png_info_init (png_infop \fIinfo_ptr\fP\fB);\fP

-\fI\fB

-\fBDEPRECATED: void png_info_init_2 (png_infopp \fP\fIptr_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_malloc_default(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP

-\fI\fB

-\fBvoidp png_memcpy (png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_size_t \fIsize\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_memcpy_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_uint_32 \fIsize\fP\fB);\fP

-\fI\fB

-\fBvoidp png_memset (png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_size_t \fIsize\fP\fB);\fP

-\fI\fB

-\fBpng_voidp png_memset_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_uint_32 \fIsize\fP\fB);\fP

-\fI\fB

-\fBDEPRECATED: void png_permit_empty_plte (png_structp \fP\fIpng_ptr\fP\fB, int \fIempty_plte_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

-\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_destroy (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_infop \fIend_info_ptr\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

-\fBDEPRECATED: void png_read_init (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBDEPRECATED: void png_read_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\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

-\fB#if \fI!defined(PNG_1_0_X)

-\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#endif

-\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_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_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_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_dither (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_dither\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_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_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_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_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_charp \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

-\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_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_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_fixed_point \fP\fIred\fP\fB, png_fixed_point \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, png_charp \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\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 \fIintent\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 \fIintent\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_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_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\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_values\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_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_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

-\fBvoid png_set_compression_buffer_size(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\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_destroy (png_structp \fIpng_ptr\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

-\fBDEPRECATED: void png_write_init (png_structp \fIpng_ptr\fP\fB);\fP

-\fI\fB

-\fBDEPRECATED: void png_write_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\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

-\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.txt file that accompanies libpng.

-.SH LIBPNG.TXT

-libpng.txt - A description on how to use and modify libpng

- libpng version 1.2.8 - December 3, 2004

- Updated and distributed by Glenn Randers-Pehrson

- <glennrp at users.sourceforge.net>

- Copyright (c) 1998-2004 Glenn Randers-Pehrson

- For conditions of distribution and use, see copyright

- notice in png.h.

- based on:

- 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.

-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/>

-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.  Note: thread safety may be defeated

-by use of some of the MMX assembler code in pnggccrd.c, which is only

-compiled when the user defines PNG_THREAD_UNSAFE_OK.

-.SH II. Structures

-There are two main structures that are important to libpng, png_struct

-and png_info.  The first, png_struct, is an internal structure that

-will not, for the most part, be used by a user except as the first

-variable passed to every libpng function call.

-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.  The fields of png_info are still available for

-older applications, but it is suggested that applications use the new

-interfaces if at all possible.

-Applications that do make direct access to the members of png_struct (except

-for png_ptr->jmpbuf) must be recompiled whenever the library is updated,

-and applications that make direct access to the members of png_info must

-be recompiled if they were compiled or loaded with libpng version 1.0.6,

-in which the members were in a different order.  In version 1.0.7, the

-members of the png_info structure reverted to the old order, as they were

-in versions 0.97c through 1.0.5.  Starting with version 2.0.0, both

-structures are going to be hidden, and the contents of the structures will

-only be accessible through the png_get/png_set functions.

-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>

-.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 if the bytes match the corresponding

-bytes of the PNG signature, or nonzero 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);

-    }

-    png_infop end_info = png_create_info_struct(png_ptr);

-    if (!end_info)

-    {

-        png_destroy_read_struct(&png_ptr, &info_ptr,

-          (png_infopp)NULL);

-        return (ERROR);

-    }

-If you want to use your own memory allocation routines,

-define PNG_USER_MEM_SUPPORTED 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 jmpbuf field 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);

-    }

-If you would rather avoid the complexity of setjmp/longjmp issues,

-you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case

-errors will result in a call to PNG_ABORT() which defaults to abort().

-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);

-.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_ptr ptr,

-         png_unknown_chunkp chunk);

-    {

-       /* The unknown chunk structure contains your

-          chunk data: */

-           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.  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);

-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_ptr 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);

-.SS Width and height 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 override 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().

-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);

-.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; unknown chunks will be discarded. To change

-this, you can call:

-    png_set_keep_unknown_chunks(png_ptr, keep,

-        chunk_list, num_chunks);

-    keep       - 0: do not handle as unknown

-                 1: 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.

-.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_STRIP_16      Strip 16-bit samples to

-                                8 bits

-    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

-(This excludes setting a background color, doing gamma transformation,

-dithering, 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 logical 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]=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 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.

-.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

-    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)

-    compression_type - (must be PNG_COMPRESSION_TYPE_BASE

-                     for PNG 1.0)

-    interlace_type - (PNG_INTERLACE_NONE or

-                     PNG_INTERLACE_ADAM7)

-    Any or all of interlace_type, compression_type, of

-    filter_method can be NULL if you are

-    not interested in their values.

-    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())).

-    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);

-    filter_method    = png_get_filter_type(png_ptr,

-                         info_ptr);

-    compression_type = png_get_compression_type(png_ptr,

-                         info_ptr);

-    interlace_type   = png_get_interlace_type(png_ptr,

-                         info_ptr);

-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.

-    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, &gamma);

-    gamma          - the gamma the file is written

-                     at (PNG_INFO_gAMA)

-    png_get_sRGB(png_ptr, info_ptr, &srgb_intent);

-    srgb_intent    - the rendering intent (PNG_INFO_sRGB)

-                     The presence of the sRGB chunk

-                     means that the pixel data is in the

-                     sRGB color space.  This chunk also

-                     implies specific values of gAMA and

-                     cHRM.

-    png_get_iCCP(png_ptr, info_ptr, &name,

-       &compression_type, &profile, &proflen);

-    name            - The profile name.

-    compression     - 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, &num_trans,

-                     &trans_values);

-    trans          - array of transparent entries for

-                     palette (PNG_INFO_tRNS)

-    trans_values   - graylevel or color sample values of

-                     the single transparent color for

-                     non-paletted images (PNG_INFO_tRNS)

-    num_trans      - number of transparent entries

-                     (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 (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).

-    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);

-    palette_ptr    - array of palette structures holding

-                     contents of one or more sPLT chunks

-                     read.

-    num_spalettes  - number of 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

-    offset_y       - positive offset from the top edge

-                     of the screen

-    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

-    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 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)

-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)

-For more information, see the png_info definition in png.h and 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.  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.

-The colors used for the background and transparency values should be

-supplied in the same format/depth as the current image data.  They

-are stored in the same format/depth as the image data in a bKGD or tRNS

-chunk, so this is what libpng expects for this data.  The colors are

-transformed to keep in sync with the image data when an application

-calls the png_read_update_info() routine (see 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_strip_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(), or png_set_strip_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 (color_type == PNG_COLOR_TYPE_GRAY &&

-        bit_depth < 8) png_set_gray_1_2_4_to_8(png_ptr);

-    if (png_get_valid(png_ptr, info_ptr,

-        PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);

-These three 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.

-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)

-        png_set_strip_16(png_ptr);

-If, for some reason, you don't need the alpha channel on an image,

-and you want to remove it rather than combining it with the background

-(but the image author certainly had in mind that you *would* combine

-it with the background, so that's what you should probably do):

-    if (color_type & PNG_COLOR_MASK_ALPHA)

-        png_set_strip_alpha(png_ptr);

-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_fixed(png_ptr, error_action,

-             int red_weight, int 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 times 100000

-    green_weight:     weight of green component times 100000

-                      If either weight is negative, default

-                      weights (21268, 71514) are used.

-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.  bKGD and sBIT data

-will be silently converted to grayscale, using the green channel

-data, regardless of the error_action setting.

-With red_weight+green_weight<=100000,

-the normalized graylevel is computed:

-    int rw = red_weight * 65536;

-    int gw = green_weight * 65536;

-    int bw = 65536 - (rw + gw);

-    gray = (rw*red + gw*green + bw*blue)/65536;

-The default values approximate those recommended in the Charles

-Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>

-Copyright (c) 1998-01-04 Charles Poynton <poynton at inforamp.net>

-    Y = 0.212671 * R + 0.715160 * G + 0.072169 * B

-Libpng approximates this with

-    Y = 0.21268 * R    + 0.7151 * G    + 0.07217 * B

-which can be expressed with integers as

-    Y = (6969 * R + 23434 * G + 2365 * B)/32768

-The calculation is done in a linear colorspace, if the image gamma

-is known.

-If you have a grayscale and you are using png_set_expand_depth(),

-png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to

-a higher bit-depth, you must either supply the background color as a gray

-value at the original file bit-depth (need_expand = 1) or else supply the

-background color as an RGB triplet at the final, expanded bit depth

-(need_expand = 0).  Similarly, if you are reading a paletted image, you

-must either supply the background color as a palette index (need_expand = 1)

-or as an RGB triplet that may or may not be in the palette (need_expand = 0).

-    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, 1.0);

-    else

-        png_set_background(png_ptr, &my_background,

-          PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);

-The png_set_background() function tells libpng to composite images

-with alpha or simple transparency against the supplied background

-color.  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 whether the color is in the gamma space of the

-display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file

-(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one

-that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't

-know why anyone would use this, but it's here).

-To properly display PNG images on any kind of system, the application needs

-to know what the display gamma is.  Ideally, the user will know this, and

-the application will allow them to set it.  One method of allowing the user

-to set the display gamma separately for each system is to check for a

-SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be

-correctly set.

-Note that display_gamma is the overall gamma correction required to produce

-pleasing results, which depends on the lighting conditions in the surrounding

-environment.  In a dim or brightly lit room, no compensation other than

-the physical gamma exponent of the monitor is needed, while in a dark room

-a slightly smaller exponent is better.

-   double gamma, screen_gamma;

-   if (/* We have a user-defined screen

-       gamma value */)

-   {

-      screen_gamma = user_defined_screen_gamma;

-   }

-   /* One way that applications can share the same

-      screen gamma value */

-   else if ((gamma_str = getenv("SCREEN_GAMMA"))

-      != NULL)

-   {

-      screen_gamma = (double)atof(gamma_str);

-   }

-   /* If we don't have another value */

-   else

-   {

-      screen_gamma = 2.2; /* A good guess for a

-           PC monitor in a bright office or a dim room */

-      screen_gamma = 2.0; /* A good guess for a

-           PC monitor in a dark room */

-      screen_gamma = 1.7 or 1.0;  /* A good

-           guess for Mac systems */

-   }

-The png_set_gamma() function handles gamma transformations of the data.

-Pass both the file gamma and the current screen_gamma.  If the file does

-not have a gamma value, you can pass one anyway if you have an idea what

-it is (usually 0.45455 is a good guess for GIF images on PCs).  Note

-that file gammas are inverted from screen gammas.  See the discussions

-on gamma in the PNG specification for an excellent description of what

-gamma is, and why all applications should support it.  It is strongly

-recommended that PNG viewers support gamma correction.

-   if (png_get_gAMA(png_ptr, info_ptr, &gamma))

-      png_set_gamma(png_ptr, screen_gamma, 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_dither()

-will do that.  Note that this is a simple match dither that merely

-finds the closest color available.  This should work fairly well with

-optimized palettes, and fairly badly with linear color cubes.  If you

-pass a palette that is larger then 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, it 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_dither(png_ptr, palette, num_palette,

-            max_screen_colors, histogram, 1);

-      }

-      else

-      {

-         png_color std_color_cube[MAX_SCREEN_COLORS] =

-            { ... colors ... };

-         png_set_dither(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_ptr ptr, row_info_ptr

-       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.

-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.  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.

-    png_read_update_info(png_ptr, 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.

-.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() 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)

-is 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.

-libpng can fill out those images or it can give them to you "as is".

-If you want them 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 you don't want libpng to handle the interlacing details, just call

-png_read_rows() seven times to read in all seven images.  Each of the

-images is a valid image by itself, or they can all be combined on an

-8x8 grid to form a single image (although if you intend to combine them

-you would be far better off using the libpng interlace handling).

-The first pass will return an image 1/8 as wide as the entire image

-(every 8th column starting in column 0) and 1/8 as high as the original

-(every 8th row starting in row 0), the second will be 1/8 as wide

-(starting in column 4) and 1/8 as high (also starting in row 0).  The

-third pass will be 1/4 as wide (every 4th pixel starting in column 0) and

-1/8 as high (every 8th row starting in row 4), and the fourth pass will

-be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,

-and every 4th row starting in row 0).  The fifth pass will return an

-image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),

-while the sixth pass will be 1/2 as wide and 1/2 as high as the original

-(starting in column 1 and row 0).  The seventh and final pass will be as

-wide as the original, and 1/2 as high, containing all of the odd

-numbered scanlines.  Phew!

-If 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.

-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);

-.SS Finishing a sequential read

-After you are finished reading the image through either the high- or

-low-level interfaces, you can finish reading the file.  If you are

-interested in comments or time, which may be stored either before or

-after the image data, you should pass the separate png_info struct if

-you want to keep the comments from before and after the image

-separate.  If you are not interested, you can pass NULL.

-   png_read_end(png_ptr, end_info);

-When you are done, you can free all memory allocated by libpng like this:

-   png_destroy_read_struct(&png_ptr, &info_ptr,

-       &end_info);

-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 logical 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)

-    mask   - which data elements are affected

-             same choices as in png_free_data()

-    freer  - one of

-               PNG_DESTROY_WILL_FREE_DATA

-               PNG_SET_WILL_FREE_DATA

-               PNG_USER_WILL_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 logical 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);

-    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 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.

-       For the non-NULL rows of interlaced images,

-       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:

-     */

-        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.

-    */

- }

- 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_SETJMP_NOT_SUPPORTED, in which case

-errors will result in a call to PNG_ABORT() which defaults to abort().

-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);

-.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_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);

-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 logical 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_AVE   | PNG_FILTER_VALUE_AVE  |

-       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.

-    /* set the zlib compression level */

-    png_set_compression_level(png_ptr,

-        Z_BEST_COMPRESSION);

-    /* set other zlib parameters */

-    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)

-extern PNG_EXPORT(void,png_set_zbuf_size)

-.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)

-    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, gamma);

-    gamma          - the gamma the image was created

-                     at (PNG_INFO_gAMA)

-    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     - 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, num_trans,

-       trans_values);

-    trans          - array of transparent entries for

-                     palette (PNG_INFO_tRNS)

-    trans_values   - graylevel or color sample values of

-                     the single transparent color for

-                     non-paletted images (PNG_INFO_tRNS)

-    num_trans      - number of transparent entries

-                     (PNG_INFO_tRNS)

-    png_set_hIST(png_ptr, info_ptr, hist);

-                    (PNG_INFO_hIST)

-    hist           - histogram of palette (array of

-                     png_uint_16)

-    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 (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).

-    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

-    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 1000 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.

-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 logical 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_ptr ptr, row_info_ptr

-       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.

-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 seven 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);

-As some of these rows are not used, and thus return immediately,

-you may want to read about interlacing in the PNG specification,

-and only update the rows that are actually used.

-.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 logical 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)

-    mask   - which data elements are affected

-             same choices as in png_free_data()

-    freer  - one of

-               PNG_DESTROY_WILL_FREE_DATA

-               PNG_SET_WILL_FREE_DATA

-               PNG_USER_WILL_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 three 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.  The third is a

-run-time issue:  choosing between and/or tuning one or more alternate

-versions of computationally intensive routines; specifically, optimized

-assembly-language (and therefore compiler- and platform-dependent)

-versions.

-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()

-and png_free().  These currently just call the standard C functions.  If

-your pointers can't access more then 64K at a time, you will want to set

-MAXSEG_64K in zlib.h.  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_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().

-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);

-Supplying NULL for the read, write, or flush functions sets them back

-to using the default C stream functions.  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_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),

-but you could change this to do things like exit() if you should wish.

-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).

-.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.  Hoewver, 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 unknown

-chunks in a generic method, via callback functions, instead of by

-modifying libpng functions.

-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/delete

-an include, this is the place to do it.  The includes that are not

-needed outside libpng are protected by the PNG_INTERNAL definition,

-which is only defined for those routines inside libpng itself.  The

-files in libpng proper only include png.h, which includes pngconf.h.

-.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:

-    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.

-    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.

-    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);

-.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_AVE |

-              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_.

-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.  Runtime optimization

-A new feature in libpng 1.2.0 is the ability to dynamically switch between

-standard and optimized versions of some routines.  Currently these are

-limited to three computationally intensive tasks when reading PNG files:

-decoding row filters, expanding interlacing, and combining interlaced or

-transparent row data with previous row data.  Currently the optimized

-versions are available only for x86 (Intel, AMD, etc.) platforms with

-MMX support, though this may change in future versions.  (For example,

-the non-MMX assembler optimizations for zlib might become similarly

-runtime-selectable in future releases, in which case libpng could be

-extended to support them.  Alternatively, the compile-time choice of

-floating-point versus integer routines for gamma correction might become

-runtime-selectable.)

-Because such optimizations tend to be very platform- and compiler-dependent,

-both in how they are written and in how they perform, the new runtime code

-in libpng has been written to allow programs to query, enable, and disable

-either specific optimizations or all such optimizations.  For example, to

-enable all possible optimizations (bearing in mind that some "optimizations"

-may actually run more slowly in rare cases):

-    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

-       png_uint_32 mask, flags;

-       flags = png_get_asm_flags(png_ptr);

-       mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);

-       png_set_asm_flags(png_ptr, flags | mask);

-    #endif

-To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ

-by itself when calling png_get_asm_flagmask(); similarly for optimizing

-only writing.  To disable all optimizations:

-    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

-       flags = png_get_asm_flags(png_ptr);

-       mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);

-       png_set_asm_flags(png_ptr, flags & ~mask);

-    #endif

-To enable or disable only MMX-related features, use png_get_mmx_flagmask()

-in place of png_get_asm_flagmask().  The mmx version takes one additional

-parameter:

-    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

-       int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;

-       int compilerID;

-       mask = png_get_mmx_flagmask(selection, &compilerID);

-    #endif

-On return, compilerID will indicate which version of the MMX assembler

-optimizations was compiled.  Currently two flavors exist:  Microsoft

-Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).

-On non-x86 platforms or on systems compiled without MMX optimizations, a

-value of -1 is used.

-Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return

-all valid, settable optimization bits for the version of the library that's

-currently in use.  In the case of shared (dynamically linked) libraries,

-this may include optimizations that did not exist at the time the code was

-written and compiled.  It is also possible, of course, to enable only known,

-specific optimizations; for example:

-    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

-       flags = 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_set_asm_flags(png_ptr, flags);

-    #endif

-This method would enable only the MMX read-optimizations available at the

-time of libpng 1.2.0's release, regardless of whether a later version of

-the DLL were actually being used.  (Also note that these functions did not

-exist in versions older than 1.2.0, so any attempt to run a dynamically

-linked app on such an older version would fail.)

-To determine whether the processor supports MMX instructions at all, use

-the png_mmx_support() function:

-    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

-       mmxsupport = png_mmx_support();

-    #endif

-It returns -1 if MMX support is not compiled into libpng, 0 if MMX code

-is compiled but MMX is not supported by the processor, or 1 if MMX support

-is fully available.  Note that png_mmx_support(), png_get_mmx_flagmask(),

-and png_get_asm_flagmask() all may be called without allocating and ini-

-tializing any PNG structures (for example, as part of a usage screen or

-"about" box).

-The following code can be used to prevent an application from using the

-thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK

-defined:

-#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \

-  && defined(PNG_THREAD_UNSAFE_OK)

-    /* Disable thread-unsafe features of pnggccrd */

-    if (png_access_version() >= 10200)

-    {

-      png_uint_32 mmx_disable_mask = 0;

-      png_uint_32 asm_flags;

-      mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW  \

-                          | PNG_ASM_FLAG_MMX_READ_FILTER_SUB   \

-                          | PNG_ASM_FLAG_MMX_READ_FILTER_AVG   \

-                          | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );

-      asm_flags = png_get_asm_flags(png_ptr);

-      png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);

-    }

-#endif

-For more extensive examples of runtime querying, enabling and disabling

-of optimized features, see contrib/gregbook/readpng2.c in the libpng

-source-code distribution.

-.SH VII.  MNG support

-The MNG specification (available at http://www.libpng.org/pub/mng) allows

-certain extensions to PNG for PNG images that are embedded in MNG datastreams.

-Libpng can support some of these extensions.  To enable them, use the

-png_permit_mng_features() function:

-   feature_set = png_permit_mng_features(png_ptr, mask)

-   mask is a png_uint_32 containing the logical 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 logical 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 VIII.  Changes to Libpng from version 0.88

-It should be noted that versions of libpng later than 0.96 are not

-distributed by the original libpng author, Guy Schalnat, nor by

-Andreas Dilger, who had taken over from Guy during 1996 and 1997, and

-distributed versions 0.89 through 0.96, but rather by another member

-of the original PNG Group, Glenn Randers-Pehrson.  Guy and Andreas are

-still alive and well, but they have moved on to other things.

-The old libpng functions png_read_init(), png_write_init(),

-png_info_init(), png_read_destroy(), and png_write_destroy() have been

-moved to PNG_INTERNAL in version 0.95 to discourage their use.  These

-functions will be removed from libpng version 2.0.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).

-You can also check which version of png.h you used when compiling your

-application:

-   png_uint_32 application_vn = PNG_LIBPNG_VER;

-.SH IX. Y2K Compliance in libpng

-December 3, 2004

-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.2.8 are Y2K compliant.  It is my belief that earlier

-versions were also Y2K compliant.

-Libpng only has three year fields.  One is a 2-byte unsigned integer that

-will hold years up to 65535.  The other two hold the date in text

-format, and will hold years up to 9999.

-The integer is

-    "png_uint_16 year" in png_time_struct.

-The strings are

-    "png_charp time_buffer" in png_struct and

-    "near_time_buffer", which is a local character string in png.c.

-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

-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"

-libpngpf(3), png(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.2.8 - December 3, 2004:

-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-implement at ccrc.wustl.edu (subscription required; write to

-majordomo at ccrc.wustl.edu with "subscribe png-implement" in the message).

-.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.

-libpng version 1.2.6, December 3, 2004, is

-Copyright (c) 2004 Glenn Randers-Pehrson, and is

-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

-December 3, 2004

-.\" end of man page

--- /dev/null

+++ b/sys/src/cmd/gs/libpng/libpng.3.man

@@ -1,0 +1,4022 @@

+.TH LIBPNG 3 "December 3, 2004"

+.SH NAME

+libpng \- Portable Network Graphics (PNG) Reference Library 1.2.8

+.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

+\fBint png_check_sig (png_bytep \fP\fIsig\fP\fB, int \fInum\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

+\fBint png_debug(int \fP\fIlevel\fP\fB, png_const_charp \fImessage\fP\fB);\fP

+\fI\fB

+\fBint png_debug1(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fIp1\fP\fB);\fP

+\fI\fB

+\fBint png_debug2(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fP\fIp1\fP\fB, \fIp2\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_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_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_bKGD (png_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_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fP\fIpng_ptr\fP\fB, png_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_byte png_get_color_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_byte png_get_compression_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_byte png_get_copyright (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_get_error_ptr (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_byte png_get_filter_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_byte png_get_header_version (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_charpp \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_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_image_width (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_byte png_get_interlace_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_byte png_get_libpng_ver (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_get_mem_ptr(png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_get_progressive_ptr (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_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_structp \fIpng_ptr)

+\fBpng_uint_32 png_get_rowbytes (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_bytepp png_get_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP

+\fI\fB

+\fBpng_bytep png_get_signature (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fI*intent\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_text (png_structp \fP\fIpng_ptr\fP\fB, png_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_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_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_values\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_get_user_chunk_ptr (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_user_height_max( png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_get_user_transform_ptr (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_user_width_max (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_valid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP

+\fI\fB

+\fBpng_int_32 png_get_x_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_int_32 png_get_x_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_x_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_int_32 png_get_y_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_int_32 png_get_y_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_y_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_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_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP

+\fI\fB

+\fBDEPRECATED: void png_info_init (png_infop \fIinfo_ptr\fP\fB);\fP

+\fI\fB

+\fBDEPRECATED: void png_info_init_2 (png_infopp \fP\fIptr_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_malloc_default(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP

+\fI\fB

+\fBvoidp png_memcpy (png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_size_t \fIsize\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_memcpy_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_uint_32 \fIsize\fP\fB);\fP

+\fI\fB

+\fBvoidp png_memset (png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_size_t \fIsize\fP\fB);\fP

+\fI\fB

+\fBpng_voidp png_memset_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_uint_32 \fIsize\fP\fB);\fP

+\fI\fB

+\fBDEPRECATED: void png_permit_empty_plte (png_structp \fP\fIpng_ptr\fP\fB, int \fIempty_plte_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

+\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_destroy (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_infop \fIend_info_ptr\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

+\fBDEPRECATED: void png_read_init (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBDEPRECATED: void png_read_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\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

+\fB#if \fI!defined(PNG_1_0_X)

+\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#endif

+\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_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_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_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_dither (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_dither\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_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_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_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_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_charp \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

+\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_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_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_fixed_point \fP\fIred\fP\fB, png_fixed_point \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, png_charp \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\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 \fIintent\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 \fIintent\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_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_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\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_values\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_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_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

+\fBvoid png_set_compression_buffer_size(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\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_destroy (png_structp \fIpng_ptr\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

+\fBDEPRECATED: void png_write_init (png_structp \fIpng_ptr\fP\fB);\fP

+\fI\fB

+\fBDEPRECATED: void png_write_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\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

+\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.txt file that accompanies libpng.

+.SH LIBPNG.TXT

+libpng.txt - A description on how to use and modify libpng

+ libpng version 1.2.8 - December 3, 2004

+ Updated and distributed by Glenn Randers-Pehrson

+ <glennrp at users.sourceforge.net>

+ Copyright (c) 1998-2004 Glenn Randers-Pehrson

+ For conditions of distribution and use, see copyright

+ notice in png.h.

+ based on:

+ 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.

+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/>

+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.  Note: thread safety may be defeated

+by use of some of the MMX assembler code in pnggccrd.c, which is only

+compiled when the user defines PNG_THREAD_UNSAFE_OK.

+.SH II. Structures

+There are two main structures that are important to libpng, png_struct

+and png_info.  The first, png_struct, is an internal structure that

+will not, for the most part, be used by a user except as the first

+variable passed to every libpng function call.

+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.  The fields of png_info are still available for

+older applications, but it is suggested that applications use the new

+interfaces if at all possible.

+Applications that do make direct access to the members of png_struct (except

+for png_ptr->jmpbuf) must be recompiled whenever the library is updated,

+and applications that make direct access to the members of png_info must

+be recompiled if they were compiled or loaded with libpng version 1.0.6,

+in which the members were in a different order.  In version 1.0.7, the

+members of the png_info structure reverted to the old order, as they were

+in versions 0.97c through 1.0.5.  Starting with version 2.0.0, both

+structures are going to be hidden, and the contents of the structures will

+only be accessible through the png_get/png_set functions.

+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>

+.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 if the bytes match the corresponding

+bytes of the PNG signature, or nonzero 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);

+    }

+    png_infop end_info = png_create_info_struct(png_ptr);

+    if (!end_info)

+    {

+        png_destroy_read_struct(&png_ptr, &info_ptr,

+          (png_infopp)NULL);

+        return (ERROR);

+    }

+If you want to use your own memory allocation routines,

+define PNG_USER_MEM_SUPPORTED 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 jmpbuf field 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);

+    }

+If you would rather avoid the complexity of setjmp/longjmp issues,

+you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case

+errors will result in a call to PNG_ABORT() which defaults to abort().

+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);

+.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_ptr ptr,

+         png_unknown_chunkp chunk);

+    {

+       /* The unknown chunk structure contains your

+          chunk data: */

+           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.  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);

+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_ptr 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);

+.SS Width and height 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 override 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().

+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);

+.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; unknown chunks will be discarded. To change

+this, you can call:

+    png_set_keep_unknown_chunks(png_ptr, keep,

+        chunk_list, num_chunks);

+    keep       - 0: do not handle as unknown

+                 1: 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.

+.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_STRIP_16      Strip 16-bit samples to

+                                8 bits

+    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

+(This excludes setting a background color, doing gamma transformation,

+dithering, 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 logical 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]=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 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.

+.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

+    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)

+    compression_type - (must be PNG_COMPRESSION_TYPE_BASE

+                     for PNG 1.0)

+    interlace_type - (PNG_INTERLACE_NONE or

+                     PNG_INTERLACE_ADAM7)

+    Any or all of interlace_type, compression_type, of

+    filter_method can be NULL if you are

+    not interested in their values.

+    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())).

+    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);

+    filter_method    = png_get_filter_type(png_ptr,

+                         info_ptr);

+    compression_type = png_get_compression_type(png_ptr,

+                         info_ptr);

+    interlace_type   = png_get_interlace_type(png_ptr,

+                         info_ptr);

+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.

+    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, &gamma);

+    gamma          - the gamma the file is written

+                     at (PNG_INFO_gAMA)

+    png_get_sRGB(png_ptr, info_ptr, &srgb_intent);

+    srgb_intent    - the rendering intent (PNG_INFO_sRGB)

+                     The presence of the sRGB chunk

+                     means that the pixel data is in the

+                     sRGB color space.  This chunk also

+                     implies specific values of gAMA and

+                     cHRM.

+    png_get_iCCP(png_ptr, info_ptr, &name,

+       &compression_type, &profile, &proflen);

+    name            - The profile name.

+    compression     - 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, &num_trans,

+                     &trans_values);

+    trans          - array of transparent entries for

+                     palette (PNG_INFO_tRNS)

+    trans_values   - graylevel or color sample values of

+                     the single transparent color for

+                     non-paletted images (PNG_INFO_tRNS)

+    num_trans      - number of transparent entries

+                     (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 (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).

+    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);

+    palette_ptr    - array of palette structures holding

+                     contents of one or more sPLT chunks

+                     read.

+    num_spalettes  - number of 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

+    offset_y       - positive offset from the top edge

+                     of the screen

+    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

+    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 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)

+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)

+For more information, see the png_info definition in png.h and 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.  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.

+The colors used for the background and transparency values should be

+supplied in the same format/depth as the current image data.  They

+are stored in the same format/depth as the image data in a bKGD or tRNS

+chunk, so this is what libpng expects for this data.  The colors are

+transformed to keep in sync with the image data when an application

+calls the png_read_update_info() routine (see 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_strip_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(), or png_set_strip_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 (color_type == PNG_COLOR_TYPE_GRAY &&

+        bit_depth < 8) png_set_gray_1_2_4_to_8(png_ptr);

+    if (png_get_valid(png_ptr, info_ptr,

+        PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);

+These three 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.

+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)

+        png_set_strip_16(png_ptr);

+If, for some reason, you don't need the alpha channel on an image,

+and you want to remove it rather than combining it with the background

+(but the image author certainly had in mind that you *would* combine

+it with the background, so that's what you should probably do):

+    if (color_type & PNG_COLOR_MASK_ALPHA)

+        png_set_strip_alpha(png_ptr);

+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_fixed(png_ptr, error_action,

+             int red_weight, int 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 times 100000

+    green_weight:     weight of green component times 100000

+                      If either weight is negative, default

+                      weights (21268, 71514) are used.

+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.  bKGD and sBIT data

+will be silently converted to grayscale, using the green channel

+data, regardless of the error_action setting.

+With red_weight+green_weight<=100000,

+the normalized graylevel is computed:

+    int rw = red_weight * 65536;

+    int gw = green_weight * 65536;

+    int bw = 65536 - (rw + gw);

+    gray = (rw*red + gw*green + bw*blue)/65536;

+The default values approximate those recommended in the Charles

+Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>

+Copyright (c) 1998-01-04 Charles Poynton <poynton at inforamp.net>

+    Y = 0.212671 * R + 0.715160 * G + 0.072169 * B

+Libpng approximates this with

+    Y = 0.21268 * R    + 0.7151 * G    + 0.07217 * B

+which can be expressed with integers as

+    Y = (6969 * R + 23434 * G + 2365 * B)/32768

+The calculation is done in a linear colorspace, if the image gamma

+is known.

+If you have a grayscale and you are using png_set_expand_depth(),

+png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to

+a higher bit-depth, you must either supply the background color as a gray

+value at the original file bit-depth (need_expand = 1) or else supply the

+background color as an RGB triplet at the final, expanded bit depth

+(need_expand = 0).  Similarly, if you are reading a paletted image, you

+must either supply the background color as a palette index (need_expand = 1)

+or as an RGB triplet that may or may not be in the palette (need_expand = 0).

+    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, 1.0);

+    else

+        png_set_background(png_ptr, &my_background,

+          PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);

+The png_set_background() function tells libpng to composite images

+with alpha or simple transparency against the supplied background

+color.  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 whether the color is in the gamma space of the

+display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file

+(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one

+that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't

+know why anyone would use this, but it's here).

+To properly display PNG images on any kind of system, the application needs

+to know what the display gamma is.  Ideally, the user will know this, and

+the application will allow them to set it.  One method of allowing the user

+to set the display gamma separately for each system is to check for a

+SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be

+correctly set.

+Note that display_gamma is the overall gamma correction required to produce

+pleasing results, which depends on the lighting conditions in the surrounding

+environment.  In a dim or brightly lit room, no compensation other than

+the physical gamma exponent of the monitor is needed, while in a dark room

+a slightly smaller exponent is better.

+   double gamma, screen_gamma;

+   if (/* We have a user-defined screen

+       gamma value */)

+   {

+      screen_gamma = user_defined_screen_gamma;

+   }

+   /* One way that applications can share the same

+      screen gamma value */

+   else if ((gamma_str = getenv("SCREEN_GAMMA"))

+      != NULL)

+   {

+      screen_gamma = (double)atof(gamma_str);

+   }

+   /* If we don't have another value */

+   else

+   {

+      screen_gamma = 2.2; /* A good guess for a

+           PC monitor in a bright office or a dim room */

+      screen_gamma = 2.0; /* A good guess for a

+           PC monitor in a dark room */

+      screen_gamma = 1.7 or 1.0;  /* A good

+           guess for Mac systems */

+   }

+The png_set_gamma() function handles gamma transformations of the data.

+Pass both the file gamma and the current screen_gamma.  If the file does

+not have a gamma value, you can pass one anyway if you have an idea what

+it is (usually 0.45455 is a good guess for GIF images on PCs).  Note

+that file gammas are inverted from screen gammas.  See the discussions

+on gamma in the PNG specification for an excellent description of what

+gamma is, and why all applications should support it.  It is strongly

+recommended that PNG viewers support gamma correction.

+   if (png_get_gAMA(png_ptr, info_ptr, &gamma))

+      png_set_gamma(png_ptr, screen_gamma, 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_dither()

+will do that.  Note that this is a simple match dither that merely

+finds the closest color available.  This should work fairly well with

+optimized palettes, and fairly badly with linear color cubes.  If you

+pass a palette that is larger then 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, it 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_dither(png_ptr, palette, num_palette,

+            max_screen_colors, histogram, 1);

+      }

+      else

+      {

+         png_color std_color_cube[MAX_SCREEN_COLORS] =

+            { ... colors ... };

+         png_set_dither(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_ptr ptr, row_info_ptr

+       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.

+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.  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.

+    png_read_update_info(png_ptr, 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.

+.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() 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)

+is 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.

+libpng can fill out those images or it can give them to you "as is".

+If you want them 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 you don't want libpng to handle the interlacing details, just call

+png_read_rows() seven times to read in all seven images.  Each of the

+images is a valid image by itself, or they can all be combined on an

+8x8 grid to form a single image (although if you intend to combine them

+you would be far better off using the libpng interlace handling).

+The first pass will return an image 1/8 as wide as the entire image

+(every 8th column starting in column 0) and 1/8 as high as the original

+(every 8th row starting in row 0), the second will be 1/8 as wide

+(starting in column 4) and 1/8 as high (also starting in row 0).  The

+third pass will be 1/4 as wide (every 4th pixel starting in column 0) and

+1/8 as high (every 8th row starting in row 4), and the fourth pass will

+be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,

+and every 4th row starting in row 0).  The fifth pass will return an

+image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),

+while the sixth pass will be 1/2 as wide and 1/2 as high as the original

+(starting in column 1 and row 0).  The seventh and final pass will be as

+wide as the original, and 1/2 as high, containing all of the odd

+numbered scanlines.  Phew!

+If 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.

+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);

+.SS Finishing a sequential read

+After you are finished reading the image through either the high- or

+low-level interfaces, you can finish reading the file.  If you are

+interested in comments or time, which may be stored either before or

+after the image data, you should pass the separate png_info struct if

+you want to keep the comments from before and after the image

+separate.  If you are not interested, you can pass NULL.

+   png_read_end(png_ptr, end_info);

+When you are done, you can free all memory allocated by libpng like this:

+   png_destroy_read_struct(&png_ptr, &info_ptr,

+       &end_info);

+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 logical 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)

+    mask   - which data elements are affected

+             same choices as in png_free_data()

+    freer  - one of

+               PNG_DESTROY_WILL_FREE_DATA

+               PNG_SET_WILL_FREE_DATA

+               PNG_USER_WILL_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 logical 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);

+    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 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.

+       For the non-NULL rows of interlaced images,

+       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:

+     */

+        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.

+    */

+ }

+ 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_SETJMP_NOT_SUPPORTED, in which case

+errors will result in a call to PNG_ABORT() which defaults to abort().

+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);

+.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_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);

+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 logical 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_AVE   | PNG_FILTER_VALUE_AVE  |

+       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.

+    /* set the zlib compression level */

+    png_set_compression_level(png_ptr,

+        Z_BEST_COMPRESSION);

+    /* set other zlib parameters */

+    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)

+extern PNG_EXPORT(void,png_set_zbuf_size)

+.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)

+    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, gamma);

+    gamma          - the gamma the image was created

+                     at (PNG_INFO_gAMA)

+    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     - 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, num_trans,

+       trans_values);

+    trans          - array of transparent entries for

+                     palette (PNG_INFO_tRNS)

+    trans_values   - graylevel or color sample values of

+                     the single transparent color for

+                     non-paletted images (PNG_INFO_tRNS)

+    num_trans      - number of transparent entries

+                     (PNG_INFO_tRNS)

+    png_set_hIST(png_ptr, info_ptr, hist);

+                    (PNG_INFO_hIST)

+    hist           - histogram of palette (array of

+                     png_uint_16)

+    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 (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).

+    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

+    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 1000 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.

+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 logical 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_ptr ptr, row_info_ptr

+       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.

+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 seven 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);

+As some of these rows are not used, and thus return immediately,

+you may want to read about interlacing in the PNG specification,

+and only update the rows that are actually used.

+.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 logical 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)

+    mask   - which data elements are affected

+             same choices as in png_free_data()

+    freer  - one of

+               PNG_DESTROY_WILL_FREE_DATA

+               PNG_SET_WILL_FREE_DATA

+               PNG_USER_WILL_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 three 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.  The third is a

+run-time issue:  choosing between and/or tuning one or more alternate

+versions of computationally intensive routines; specifically, optimized

+assembly-language (and therefore compiler- and platform-dependent)

+versions.

+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()

+and png_free().  These currently just call the standard C functions.  If

+your pointers can't access more then 64K at a time, you will want to set

+MAXSEG_64K in zlib.h.  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_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().

+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);

+Supplying NULL for the read, write, or flush functions sets them back

+to using the default C stream functions.  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_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),

+but you could change this to do things like exit() if you should wish.

+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).

+.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.  Hoewver, 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 unknown

+chunks in a generic method, via callback functions, instead of by

+modifying libpng functions.

+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/delete

+an include, this is the place to do it.  The includes that are not

+needed outside libpng are protected by the PNG_INTERNAL definition,

+which is only defined for those routines inside libpng itself.  The

+files in libpng proper only include png.h, which includes pngconf.h.

+.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:

+    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.

+    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.

+    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);

+.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_AVE |

+              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_.

+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.  Runtime optimization

+A new feature in libpng 1.2.0 is the ability to dynamically switch between

+standard and optimized versions of some routines.  Currently these are

+limited to three computationally intensive tasks when reading PNG files:

+decoding row filters, expanding interlacing, and combining interlaced or

+transparent row data with previous row data.  Currently the optimized

+versions are available only for x86 (Intel, AMD, etc.) platforms with

+MMX support, though this may change in future versions.  (For example,

+the non-MMX assembler optimizations for zlib might become similarly

+runtime-selectable in future releases, in which case libpng could be

+extended to support them.  Alternatively, the compile-time choice of

+floating-point versus integer routines for gamma correction might become

+runtime-selectable.)

+Because such optimizations tend to be very platform- and compiler-dependent,

+both in how they are written and in how they perform, the new runtime code

+in libpng has been written to allow programs to query, enable, and disable

+either specific optimizations or all such optimizations.  For example, to

+enable all possible optimizations (bearing in mind that some "optimizations"

+may actually run more slowly in rare cases):

+    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

+       png_uint_32 mask, flags;

+       flags = png_get_asm_flags(png_ptr);

+       mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);

+       png_set_asm_flags(png_ptr, flags | mask);

+    #endif

+To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ

+by itself when calling png_get_asm_flagmask(); similarly for optimizing

+only writing.  To disable all optimizations:

+    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

+       flags = png_get_asm_flags(png_ptr);

+       mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);

+       png_set_asm_flags(png_ptr, flags & ~mask);

+    #endif

+To enable or disable only MMX-related features, use png_get_mmx_flagmask()

+in place of png_get_asm_flagmask().  The mmx version takes one additional

+parameter:

+    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

+       int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;

+       int compilerID;

+       mask = png_get_mmx_flagmask(selection, &compilerID);

+    #endif

+On return, compilerID will indicate which version of the MMX assembler

+optimizations was compiled.  Currently two flavors exist:  Microsoft

+Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).

+On non-x86 platforms or on systems compiled without MMX optimizations, a

+value of -1 is used.

+Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return

+all valid, settable optimization bits for the version of the library that's

+currently in use.  In the case of shared (dynamically linked) libraries,

+this may include optimizations that did not exist at the time the code was

+written and compiled.  It is also possible, of course, to enable only known,

+specific optimizations; for example:

+    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

+       flags = 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_set_asm_flags(png_ptr, flags);

+    #endif

+This method would enable only the MMX read-optimizations available at the

+time of libpng 1.2.0's release, regardless of whether a later version of

+the DLL were actually being used.  (Also note that these functions did not

+exist in versions older than 1.2.0, so any attempt to run a dynamically

+linked app on such an older version would fail.)

+To determine whether the processor supports MMX instructions at all, use

+the png_mmx_support() function:

+    #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)

+       mmxsupport = png_mmx_support();

+    #endif

+It returns -1 if MMX support is not compiled into libpng, 0 if MMX code

+is compiled but MMX is not supported by the processor, or 1 if MMX support

+is fully available.  Note that png_mmx_support(), png_get_mmx_flagmask(),

+and png_get_asm_flagmask() all may be called without allocating and ini-

+tializing any PNG structures (for example, as part of a usage screen or

+"about" box).

+The following code can be used to prevent an application from using the

+thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK

+defined:

+#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \

+  && defined(PNG_THREAD_UNSAFE_OK)

+    /* Disable thread-unsafe features of pnggccrd */

+    if (png_access_version() >= 10200)

+    {

+      png_uint_32 mmx_disable_mask = 0;

+      png_uint_32 asm_flags;

+      mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW  \

+                          | PNG_ASM_FLAG_MMX_READ_FILTER_SUB   \

+                          | PNG_ASM_FLAG_MMX_READ_FILTER_AVG   \

+                          | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );

+      asm_flags = png_get_asm_flags(png_ptr);

+      png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);

+    }

+#endif

+For more extensive examples of runtime querying, enabling and disabling

+of optimized features, see contrib/gregbook/readpng2.c in the libpng

+source-code distribution.

+.SH VII.  MNG support

+The MNG specification (available at http://www.libpng.org/pub/mng) allows

+certain extensions to PNG for PNG images that are embedded in MNG datastreams.

+Libpng can support some of these extensions.  To enable them, use the

+png_permit_mng_features() function:

+   feature_set = png_permit_mng_features(png_ptr, mask)

+   mask is a png_uint_32 containing the logical 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 logical 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 VIII.  Changes to Libpng from version 0.88

+It should be noted that versions of libpng later than 0.96 are not

+distributed by the original libpng author, Guy Schalnat, nor by

+Andreas Dilger, who had taken over from Guy during 1996 and 1997, and

+distributed versions 0.89 through 0.96, but rather by another member

+of the original PNG Group, Glenn Randers-Pehrson.  Guy and Andreas are

+still alive and well, but they have moved on to other things.

+The old libpng functions png_read_init(), png_write_init(),

+png_info_init(), png_read_destroy(), and png_write_destroy() have been

+moved to PNG_INTERNAL in version 0.95 to discourage their use.  These

+functions will be removed from libpng version 2.0.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).

+You can also check which version of png.h you used when compiling your

+application:

+   png_uint_32 application_vn = PNG_LIBPNG_VER;

+.SH IX. Y2K Compliance in libpng

+December 3, 2004

+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.2.8 are Y2K compliant.  It is my belief that earlier

+versions were also Y2K compliant.

+Libpng only has three year fields.  One is a 2-byte unsigned integer that

+will hold years up to 65535.  The other two hold the date in text

+format, and will hold years up to 9999.

+The integer is

+    "png_uint_16 year" in png_time_struct.

+The strings are

+    "png_charp time_buffer" in png_struct and

+    "near_time_buffer", which is a local character string in png.c.

+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

+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"

+libpngpf(3), png(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.2.8 - December 3, 2004:

+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-implement at ccrc.wustl.edu (subscription required; write to

+majordomo at ccrc.wustl.edu with "subscribe png-implement" in the message).

+.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.

+libpng version 1.2.6, December 3, 2004, is

+Copyright (c) 2004 Glenn Randers-Pehrson, and is

+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

+December 3, 2004

+.\" end of man page

--- a/sys/src/cmd/gs/libpng/libpngpf.3

+++ /dev/null

@@ -1,1096 +1,0 @@

-.TH LIBPNGPF 3 "December 3, 2004"

-.SH NAME

-libpng \- Portable Network Graphics (PNG) Reference Library 1.2.8

-(private functions)

-.SH SYNOPSIS

-\fB\fB#include <png.h>\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_build_gamma_table (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_build_grayscale_palette (int \fP\fI\fP\fIbit_depth\fP\fB\fP\fB, png_colorp \fI\fIpalette\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_calculate_crc (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIptr\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_check_chunk_name (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIchunk_name\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBpng_size_t png_check_keyword (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charpp \fI\fInew_key\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_combine_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fI\fImask\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_correct_palette (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, int \fI\fInum_palette\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBint png_crc_error (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBint png_crc_finish (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIskip\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_crc_read (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBpng_voidp png_create_struct (int \fI\fItype\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBpng_voidp png_create_struct_2 (int \fP\fI\fP\fItype\fP\fB\fP\fB, png_malloc_ptr \fP\fI\fP\fImalloc_fn\fP\fB\fP\fB, png_voidp \fI\fImem_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBpng_charp png_decompress_chunk (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fP\fI\fP\fIcomp_type\fP\fB\fP\fB, png_charp \fP\fI\fP\fIchunkdata\fP\fB\fP\fB, png_size_t \fP\fI\fP\fIchunklength\fP\fB\fP\fB, png_size_t \fP\fI\fP\fIprefix_length\fP\fB\fP\fB, png_size_t \fI\fI*data_length\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_destroy_struct (png_voidp \fI\fIstruct_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_destroy_struct_2 (png_voidp \fP\fI\fP\fIstruct_ptr\fP\fB\fP\fB, png_free_ptr \fP\fI\fP\fIfree_fn\fP\fB\fP\fB, png_voidp \fI\fImem_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_background (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fItrans_values\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIbackground\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIbackground_1\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_table\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_from_1\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_to_1\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_from_1\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_to_1\fP\fB\fP\fB, int \fI\fIgamma_shift\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_bgr (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_chop (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_dither (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIpalette_lookup\fP\fB\fP\fB, png_bytep \fI\fIdither_lookup\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_expand (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_16p \fI\fItrans_value\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_expand_palette (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, png_bytep \fP\fI\fP\fItrans\fP\fB\fP\fB, int \fI\fInum_trans\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_gamma (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_table\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_table\fP\fB\fP\fB, int \fI\fIgamma_shift\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_gray_to_rgb (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_invert (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_pack (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fI\fIbit_depth\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_packswap (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_read_filler (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIfiller\fP\fB\fP\fB, png_uint_32 \fI\fIflags\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_read_interlace (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fP\fI\fP\fIpass\fP\fB\fP\fB, png_uint_32 \fI\fItransformations\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_read_invert_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_read_swap_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_read_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBint png_do_rgb_to_gray (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_shift (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_8p \fI\fIbit_depth\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_strip_filler (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fI\fIflags\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_swap (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_unpack (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_unshift (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_8p \fI\fIsig_bits\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_write_interlace (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fI\fIpass\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_write_invert_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_write_swap_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_do_write_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid *png_far_to_near (png_structp png_ptr,png_voidp \fP\fI\fP\fIptr\fP\fB\fP\fB, int \fI\fIcheck\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_flush (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBpng_int_32 png_get_int_32 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBpng_uint_16 png_get_uint_16 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBpng_uint_32 png_get_uint_31 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBpng_uint_32 png_get_uint_32 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_bKGD (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_cHRM (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_gAMA (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_hIST (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_IEND (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_IHDR (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_iCCP (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_iTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_oFFs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_pCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_pHYs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_PLTE (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_sBIT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_sCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_sPLT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_sRGB (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_tIME (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_tRNS (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_unknown (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_handle_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_info_destroy (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_init_mmx_flags (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_init_read_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_process_IDAT_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIbuffer_length\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_process_some_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_check_crc (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_crc_finish (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_crc_skip (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_fill_buffer (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_handle_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_handle_unknown (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_handle_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_have_end (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_have_info (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_have_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_process_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_read_chunk (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_read_end (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_read_IDAT (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_read_sig (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_read_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_read_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_restore_buffer (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIbuffer_length\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_push_save_buffer (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_read_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_read_filter_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIprev_row\fP\fB\fP\fB, int \fI\fIfilter\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_read_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_read_push_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_read_start_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_read_transform_info (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_reset_crc (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_save_int_32 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_int_32 \fI\fIi\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_save_uint_16 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, unsigned int \fI\fIi\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_save_uint_32 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_uint_32 \fI\fIi\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBint png_set_text_2 (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_textp \fP\fI\fP\fItext_ptr\fP\fB\fP\fB, int \fI\fInum_text\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_cHRM (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, double \fP\fI\fP\fIwhite_x\fP\fB\fP\fB, double \fP\fI\fP\fIwhite_y\fP\fB\fP\fB, double \fP\fI\fP\fIred_x\fP\fB\fP\fB, double \fP\fI\fP\fIred_y\fP\fB\fP\fB, double \fP\fI\fP\fIgreen_x\fP\fB\fP\fB, double \fP\fI\fP\fIgreen_y\fP\fB\fP\fB, double \fP\fI\fP\fIblue_x\fP\fB\fP\fB, double \fI\fIblue_y\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_cHRM_fixed (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwhite_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwhite_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIred_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIred_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIgreen_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIgreen_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIblue_x\fP\fB\fP\fB, png_uint_32 \fI\fIblue_y\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_filtered_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIfiltered_row\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_find_filter (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_row_infop \fI\fIrow_info\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_gAMA (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, double \fI\fIfile_gamma\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_gAMA_fixed (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIint_file_gamma\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_hIST (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_16p \fP\fI\fP\fIhist\fP\fB\fP\fB, int \fI\fInum_hist\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_iCCP (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIname\fP\fB\fP\fB, int \fP\fI\fP\fIcompression_type\fP\fB\fP\fB, png_charp \fP\fI\fP\fIprofile\fP\fB\fP\fB, int \fI\fIproflen\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_IDAT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_IEND (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_IHDR (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwidth\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIheight\fP\fB\fP\fB, int \fP\fI\fP\fIbit_depth\fP\fB\fP\fB, int \fP\fI\fP\fIcolor_type\fP\fB\fP\fB, int \fP\fI\fP\fIcompression_type\fP\fB\fP\fB, int \fP\fI\fP\fIfilter_type\fP\fB\fP\fB, int \fI\fIinterlace_type\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_iTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fP\fI\fP\fIcompression\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fIlang\fP\fB\fP\fB, png_charp \fP\fI\fP\fItranslated_key\fP\fB\fP\fB, png_charp \fI\fItext\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_oFFs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIx_offset\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIy_offset\fP\fB\fP\fB, int \fI\fIunit_type\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_pCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIpurpose\fP\fB\fP\fB, png_int_32 \fP\fI\fP\fIX0\fP\fB\fP\fB, png_int_32 \fP\fI\fP\fIX1\fP\fB\fP\fB, int \fP\fI\fP\fItype\fP\fB\fP\fB, int \fP\fI\fP\fInparams\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunits\fP\fB\fP\fB, png_charpp \fI\fIparams\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_pHYs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIx_pixels_per_unit\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIy_pixels_per_unit\fP\fB\fP\fB, int \fI\fIunit_type\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_PLTE (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, png_uint_32 \fI\fInum_pal\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_sBIT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_color_8p \fP\fI\fP\fIsbit\fP\fB\fP\fB, int \fI\fIcolor_type\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_sCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunit\fP\fB\fP\fB, double \fP\fI\fP\fIwidth\fP\fB\fP\fB, double \fI\fIheight\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_sCAL_s (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunit\fP\fB\fP\fB, png_charp \fP\fI\fP\fIwidth\fP\fB\fP\fB, png_charp \fI\fIheight\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_sig (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_sRGB (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fI\fIintent\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_sPLT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_spalette_p \fI\fIpalette\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_start_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fItext\fP\fB\fP\fB, png_size_t \fI\fItext_len\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_tIME (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_timep \fI\fImod_time\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_tRNS (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fItrans\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIvalues\fP\fB\fP\fB, int \fP\fI\fP\fInumber\fP\fB\fP\fB, int \fI\fIcolor_type\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_write_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fItext\fP\fB\fP\fB, png_size_t \fP\fI\fP\fItext_len\fP\fB\fP\fB, int \fI\fIcompression\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoidpf png_zalloc (voidpf \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, uInt \fP\fI\fP\fIitems\fP\fB\fP\fB, uInt \fI\fIsize\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-\fB\fBvoid png_zfree (voidpf \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, voidpf \fI\fIptr\fP\fB\fP\fB);\fP\fP

-\fI\fB

-\fI\fB\fI\fB

-\fI\fB

-.SH DESCRIPTION

-The functions listed above are used privately by libpng

-and are not recommended for use by applications.  They are

-not "exported" to applications using shared libraries.  They

-are listed alphabetically here as an aid to libpng maintainers.

-See png.h for more information on these functions.

-.SH SEE ALSO

-libpng(3), png(5)

-.SH AUTHOR

-Glenn Randers-Pehrson

--- /dev/null

+++ b/sys/src/cmd/gs/libpng/libpngpf.3.man

@@ -1,0 +1,1096 @@

+.TH LIBPNGPF 3 "December 3, 2004"

+.SH NAME

+libpng \- Portable Network Graphics (PNG) Reference Library 1.2.8

+(private functions)

+.SH SYNOPSIS

+\fB\fB#include <png.h>\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_build_gamma_table (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_build_grayscale_palette (int \fP\fI\fP\fIbit_depth\fP\fB\fP\fB, png_colorp \fI\fIpalette\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_calculate_crc (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIptr\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_check_chunk_name (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIchunk_name\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBpng_size_t png_check_keyword (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charpp \fI\fInew_key\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_combine_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fI\fImask\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_correct_palette (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, int \fI\fInum_palette\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBint png_crc_error (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBint png_crc_finish (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIskip\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_crc_read (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBpng_voidp png_create_struct (int \fI\fItype\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBpng_voidp png_create_struct_2 (int \fP\fI\fP\fItype\fP\fB\fP\fB, png_malloc_ptr \fP\fI\fP\fImalloc_fn\fP\fB\fP\fB, png_voidp \fI\fImem_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBpng_charp png_decompress_chunk (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fP\fI\fP\fIcomp_type\fP\fB\fP\fB, png_charp \fP\fI\fP\fIchunkdata\fP\fB\fP\fB, png_size_t \fP\fI\fP\fIchunklength\fP\fB\fP\fB, png_size_t \fP\fI\fP\fIprefix_length\fP\fB\fP\fB, png_size_t \fI\fI*data_length\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_destroy_struct (png_voidp \fI\fIstruct_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_destroy_struct_2 (png_voidp \fP\fI\fP\fIstruct_ptr\fP\fB\fP\fB, png_free_ptr \fP\fI\fP\fIfree_fn\fP\fB\fP\fB, png_voidp \fI\fImem_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_background (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fItrans_values\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIbackground\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIbackground_1\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_table\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_from_1\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_to_1\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_from_1\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_to_1\fP\fB\fP\fB, int \fI\fIgamma_shift\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_bgr (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_chop (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_dither (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIpalette_lookup\fP\fB\fP\fB, png_bytep \fI\fIdither_lookup\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_expand (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_16p \fI\fItrans_value\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_expand_palette (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, png_bytep \fP\fI\fP\fItrans\fP\fB\fP\fB, int \fI\fInum_trans\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_gamma (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_table\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_table\fP\fB\fP\fB, int \fI\fIgamma_shift\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_gray_to_rgb (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_invert (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_pack (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fI\fIbit_depth\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_packswap (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_read_filler (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIfiller\fP\fB\fP\fB, png_uint_32 \fI\fIflags\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_read_interlace (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fP\fI\fP\fIpass\fP\fB\fP\fB, png_uint_32 \fI\fItransformations\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_read_invert_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_read_swap_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_read_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBint png_do_rgb_to_gray (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_shift (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_8p \fI\fIbit_depth\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_strip_filler (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fI\fIflags\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_swap (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_unpack (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_unshift (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_8p \fI\fIsig_bits\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_write_interlace (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fI\fIpass\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_write_invert_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_write_swap_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_do_write_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid *png_far_to_near (png_structp png_ptr,png_voidp \fP\fI\fP\fIptr\fP\fB\fP\fB, int \fI\fIcheck\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_flush (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBpng_int_32 png_get_int_32 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBpng_uint_16 png_get_uint_16 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBpng_uint_32 png_get_uint_31 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBpng_uint_32 png_get_uint_32 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_bKGD (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_cHRM (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_gAMA (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_hIST (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_IEND (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_IHDR (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_iCCP (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_iTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_oFFs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_pCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_pHYs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_PLTE (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_sBIT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_sCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_sPLT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_sRGB (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_tIME (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_tRNS (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_unknown (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_handle_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_info_destroy (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_init_mmx_flags (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_init_read_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_process_IDAT_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIbuffer_length\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_process_some_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_check_crc (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_crc_finish (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_crc_skip (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_fill_buffer (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_handle_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_handle_unknown (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_handle_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_have_end (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_have_info (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_have_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_process_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_read_chunk (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_read_end (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_read_IDAT (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_read_sig (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_read_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_read_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_restore_buffer (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIbuffer_length\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_push_save_buffer (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_read_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_read_filter_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIprev_row\fP\fB\fP\fB, int \fI\fIfilter\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_read_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_read_push_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_read_start_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_read_transform_info (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_reset_crc (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_save_int_32 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_int_32 \fI\fIi\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_save_uint_16 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, unsigned int \fI\fIi\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_save_uint_32 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_uint_32 \fI\fIi\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBint png_set_text_2 (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_textp \fP\fI\fP\fItext_ptr\fP\fB\fP\fB, int \fI\fInum_text\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_cHRM (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, double \fP\fI\fP\fIwhite_x\fP\fB\fP\fB, double \fP\fI\fP\fIwhite_y\fP\fB\fP\fB, double \fP\fI\fP\fIred_x\fP\fB\fP\fB, double \fP\fI\fP\fIred_y\fP\fB\fP\fB, double \fP\fI\fP\fIgreen_x\fP\fB\fP\fB, double \fP\fI\fP\fIgreen_y\fP\fB\fP\fB, double \fP\fI\fP\fIblue_x\fP\fB\fP\fB, double \fI\fIblue_y\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_cHRM_fixed (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwhite_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwhite_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIred_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIred_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIgreen_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIgreen_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIblue_x\fP\fB\fP\fB, png_uint_32 \fI\fIblue_y\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_filtered_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIfiltered_row\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_find_filter (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_row_infop \fI\fIrow_info\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_gAMA (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, double \fI\fIfile_gamma\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_gAMA_fixed (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIint_file_gamma\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_hIST (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_16p \fP\fI\fP\fIhist\fP\fB\fP\fB, int \fI\fInum_hist\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_iCCP (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIname\fP\fB\fP\fB, int \fP\fI\fP\fIcompression_type\fP\fB\fP\fB, png_charp \fP\fI\fP\fIprofile\fP\fB\fP\fB, int \fI\fIproflen\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_IDAT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_IEND (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_IHDR (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwidth\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIheight\fP\fB\fP\fB, int \fP\fI\fP\fIbit_depth\fP\fB\fP\fB, int \fP\fI\fP\fIcolor_type\fP\fB\fP\fB, int \fP\fI\fP\fIcompression_type\fP\fB\fP\fB, int \fP\fI\fP\fIfilter_type\fP\fB\fP\fB, int \fI\fIinterlace_type\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_iTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fP\fI\fP\fIcompression\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fIlang\fP\fB\fP\fB, png_charp \fP\fI\fP\fItranslated_key\fP\fB\fP\fB, png_charp \fI\fItext\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_oFFs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIx_offset\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIy_offset\fP\fB\fP\fB, int \fI\fIunit_type\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_pCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIpurpose\fP\fB\fP\fB, png_int_32 \fP\fI\fP\fIX0\fP\fB\fP\fB, png_int_32 \fP\fI\fP\fIX1\fP\fB\fP\fB, int \fP\fI\fP\fItype\fP\fB\fP\fB, int \fP\fI\fP\fInparams\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunits\fP\fB\fP\fB, png_charpp \fI\fIparams\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_pHYs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIx_pixels_per_unit\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIy_pixels_per_unit\fP\fB\fP\fB, int \fI\fIunit_type\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_PLTE (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, png_uint_32 \fI\fInum_pal\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_sBIT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_color_8p \fP\fI\fP\fIsbit\fP\fB\fP\fB, int \fI\fIcolor_type\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_sCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunit\fP\fB\fP\fB, double \fP\fI\fP\fIwidth\fP\fB\fP\fB, double \fI\fIheight\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_sCAL_s (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunit\fP\fB\fP\fB, png_charp \fP\fI\fP\fIwidth\fP\fB\fP\fB, png_charp \fI\fIheight\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_sig (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_sRGB (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fI\fIintent\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_sPLT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_spalette_p \fI\fIpalette\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_start_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fItext\fP\fB\fP\fB, png_size_t \fI\fItext_len\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_tIME (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_timep \fI\fImod_time\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_tRNS (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fItrans\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIvalues\fP\fB\fP\fB, int \fP\fI\fP\fInumber\fP\fB\fP\fB, int \fI\fIcolor_type\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_write_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fItext\fP\fB\fP\fB, png_size_t \fP\fI\fP\fItext_len\fP\fB\fP\fB, int \fI\fIcompression\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoidpf png_zalloc (voidpf \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, uInt \fP\fI\fP\fIitems\fP\fB\fP\fB, uInt \fI\fIsize\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+\fB\fBvoid png_zfree (voidpf \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, voidpf \fI\fIptr\fP\fB\fP\fB);\fP\fP

+\fI\fB

+\fI\fB\fI\fB

+\fI\fB

+.SH DESCRIPTION

+The functions listed above are used privately by libpng

+and are not recommended for use by applications.  They are

+not "exported" to applications using shared libraries.  They

+are listed alphabetically here as an aid to libpng maintainers.

+See png.h for more information on these functions.

+.SH SEE ALSO

+libpng(3), png(5)

+.SH AUTHOR

+Glenn Randers-Pehrson

--- a/sys/src/cmd/gs/libpng/png.5

+++ /dev/null

@@ -1,74 +1,0 @@

-.TH PNG 5 "December 3, 2004"

-.SH NAME

-png \- Portable Network Graphics (PNG) format

-.SH DESCRIPTION

-PNG (Portable Network Graphics) is an extensible file format for the

-lossless, portable, well-compressed storage of raster images. PNG provides

-a patent-free replacement for GIF and can also replace many

-common uses of TIFF. Indexed-color, grayscale, and truecolor images are

-supported, plus an optional alpha channel. Sample depths range from

-1 to 16 bits.

-.br

-PNG is designed to work well in online viewing applications, such as the

-World Wide Web, so it is fully streamable with a progressive display

-option. PNG is robust, providing both full file integrity checking and

-fast, simple detection of common transmission errors. Also, PNG can store

-gamma and chromaticity data for improved color matching on heterogeneous

-platforms.

-.SH "SEE ALSO"

-.IR libpng(3), zlib(3), deflate(5), and zlib(5)

-.LP

-PNG specification (second edition), November 2003:

-.IP

-.br

-  <http://www.w3.org/TR/2003/REC-PNG-20031110/

-PNG 1.2 specification, July 1999:

-.IP

-.br

-http://www.libpng.org/pub/png

-.LP

-PNG 1.0 specification, October 1996:

-.IP

-.br

-RFC 2083

-.IP

-.br

-ftp://ds.internic.net/rfc/rfc2083.txt

-.br

-or (as a W3C Recommendation) at

-.br

-http://www.w3.org/TR/REC-png.html

-.SH AUTHORS

-This man page: Glenn Randers-Pehrson

-.LP

-Portable Network Graphics (PNG) Specification (Second Edition)

-Information technology - Computer graphics and image processing -

-Portable Network Graphics (PNG): Functional specification.

-ISO/IEC 15948:2003 (E) (November 10, 2003): David Duce and others.

-.LP

-Portable Network Graphics (PNG) Specification Version 1.2 (July 8, 1999):

-Glenn Randers-Pehrson and others (png-list).

-.LP

-Portable Network Graphics (PNG) Specification Version 1.0 (October 1, 1996):

-Thomas Boutell and others (png-list).

-.LP

-.SH COPYRIGHT NOTICE

-.LP

-This man page is Copyright (c) 1998-2004 Glenn Randers-Pehrson.  See png.h

-for conditions of use and distribution.

-.LP

-The PNG Specification (Second Edition) is

-Copyright (c) 2003 W3C. (MIT, ERCIM, Keio), All Rights Reserved.

-.LP

-The PNG-1.2 specification is copyright (c) 1999 Glenn Randers-Pehrson.

-See the specification for conditions of use and distribution.

-.LP

-The PNG-1.0 specification is copyright (c) 1996 Massachusetts Institute of

-Technology.  See the specification for conditions of use and distribution.

-.LP

-.\" end of man page

--- /dev/null

+++ b/sys/src/cmd/gs/libpng/png.5.man

@@ -1,0 +1,74 @@

+.TH PNG 5 "December 3, 2004"

+.SH NAME

+png \- Portable Network Graphics (PNG) format

+.SH DESCRIPTION

+PNG (Portable Network Graphics) is an extensible file format for the

+lossless, portable, well-compressed storage of raster images. PNG provides

+a patent-free replacement for GIF and can also replace many

+common uses of TIFF. Indexed-color, grayscale, and truecolor images are

+supported, plus an optional alpha channel. Sample depths range from

+1 to 16 bits.

+.br

+PNG is designed to work well in online viewing applications, such as the

+World Wide Web, so it is fully streamable with a progressive display

+option. PNG is robust, providing both full file integrity checking and

+fast, simple detection of common transmission errors. Also, PNG can store

+gamma and chromaticity data for improved color matching on heterogeneous

+platforms.

+.SH "SEE ALSO"

+.IR libpng(3), zlib(3), deflate(5), and zlib(5)

+.LP

+PNG specification (second edition), November 2003:

+.IP

+.br

+  <http://www.w3.org/TR/2003/REC-PNG-20031110/

+PNG 1.2 specification, July 1999:

+.IP

+.br

+http://www.libpng.org/pub/png

+.LP

+PNG 1.0 specification, October 1996:

+.IP

+.br

+RFC 2083

+.IP

+.br

+ftp://ds.internic.net/rfc/rfc2083.txt

+.br

+or (as a W3C Recommendation) at

+.br

+http://www.w3.org/TR/REC-png.html

+.SH AUTHORS

+This man page: Glenn Randers-Pehrson

+.LP

+Portable Network Graphics (PNG) Specification (Second Edition)

+Information technology - Computer graphics and image processing -

+Portable Network Graphics (PNG): Functional specification.

+ISO/IEC 15948:2003 (E) (November 10, 2003): David Duce and others.

+.LP

+Portable Network Graphics (PNG) Specification Version 1.2 (July 8, 1999):

+Glenn Randers-Pehrson and others (png-list).

+.LP

+Portable Network Graphics (PNG) Specification Version 1.0 (October 1, 1996):

+Thomas Boutell and others (png-list).

+.LP

+.SH COPYRIGHT NOTICE

+.LP

+This man page is Copyright (c) 1998-2004 Glenn Randers-Pehrson.  See png.h

+for conditions of use and distribution.

+.LP

+The PNG Specification (Second Edition) is

+Copyright (c) 2003 W3C. (MIT, ERCIM, Keio), All Rights Reserved.

+.LP

+The PNG-1.2 specification is copyright (c) 1999 Glenn Randers-Pehrson.

+See the specification for conditions of use and distribution.

+.LP

+The PNG-1.0 specification is copyright (c) 1996 Massachusetts Institute of

+Technology.  See the specification for conditions of use and distribution.

+.LP

+.\" end of man page

--- a/sys/src/cmd/gs/man/dvipdf.1

+++ /dev/null

@@ -1,29 +1,0 @@

-.\" $Id: dvipdf.1,v 1.37 2005/10/20 19:46:55 ray Exp $

-.TH DVIPDF 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-dvipdf \- Convert TeX DVI file to PDF using ghostscript and dvips

-.SH SYNOPSIS

-\fBdvipdf\fR [ \fIoptions\fR ] \fIinput.dvi\fR [ \fIoutput.pdf\fR ] ...

-.SH DESCRIPTION

-This script invokes

-.BR dvips (1)

-with the

-.B -q

-option, and pipes its output into

-.BR gs (1)

-with the following options:

-.ce

-.B -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite

-as well as

-.B -sOutputFile

-and any options from the command-line.

-.SH SEE ALSO

-gs(1), dvips(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/dvipdf.1.man

@@ -1,0 +1,29 @@

+.\" $Id: dvipdf.1,v 1.37 2005/10/20 19:46:55 ray Exp $

+.TH DVIPDF 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+dvipdf \- Convert TeX DVI file to PDF using ghostscript and dvips

+.SH SYNOPSIS

+\fBdvipdf\fR [ \fIoptions\fR ] \fIinput.dvi\fR [ \fIoutput.pdf\fR ] ...

+.SH DESCRIPTION

+This script invokes

+.BR dvips (1)

+with the

+.B -q

+option, and pipes its output into

+.BR gs (1)

+with the following options:

+.ce

+.B -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite

+as well as

+.B -sOutputFile

+and any options from the command-line.

+.SH SEE ALSO

+gs(1), dvips(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/man/eps2eps.1

+++ /dev/null

@@ -1,25 +1,0 @@

-.\" $Id: eps2eps.1,v 1.4 2002/07/11 02:54:22 lpd Exp $

-.TH PS2PS 1 "31 December 2000" 6.60 "Ghostscript Tools" \" -*- nroff -*-

-.SH NAME

-ps2ps, eps2eps \- Ghostscript PostScript "distiller"

-.SH SYNOPSIS

-\fBps2ps\fR [ \fIoptions\fR ] \fIinput.ps output.ps\fR

-.br

-\fBeps2eps\fR [ \fIoptions\fR ] \fIinput.eps output.eps\fR

-.SH DESCRIPTION

-\fBps2ps\fR uses \fIgs\fR(1) to convert \fBPostScript\fR(tm) file

-"input.ps" to simpler and (usually) faster PostScript in

-"output.ps".  Normally the output is allowed to use PostScript Level 2

-constructs, but the \fB\-dLanguageLevel=1\fR option restricts the output to

-Level 1.

-.PP

-\fBeps2eps\fR performs the equivalent optimization for Encapsulated

-PostScript (EPS) files.

-.SH FILES

-Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

-system, from which you can get more details.

-.SH VERSION

-This document was last revised for Ghostscript version 6.60.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

--- /dev/null

+++ b/sys/src/cmd/gs/man/eps2eps.1.man

@@ -1,0 +1,25 @@

+.\" $Id: eps2eps.1,v 1.4 2002/07/11 02:54:22 lpd Exp $

+.TH PS2PS 1 "31 December 2000" 6.60 "Ghostscript Tools" \" -*- nroff -*-

+.SH NAME

+ps2ps, eps2eps \- Ghostscript PostScript "distiller"

+.SH SYNOPSIS

+\fBps2ps\fR [ \fIoptions\fR ] \fIinput.ps output.ps\fR

+.br

+\fBeps2eps\fR [ \fIoptions\fR ] \fIinput.eps output.eps\fR

+.SH DESCRIPTION

+\fBps2ps\fR uses \fIgs\fR(1) to convert \fBPostScript\fR(tm) file

+"input.ps" to simpler and (usually) faster PostScript in

+"output.ps".  Normally the output is allowed to use PostScript Level 2

+constructs, but the \fB\-dLanguageLevel=1\fR option restricts the output to

+Level 1.

+.PP

+\fBeps2eps\fR performs the equivalent optimization for Encapsulated

+PostScript (EPS) files.

+.SH FILES

+Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

+system, from which you can get more details.

+.SH VERSION

+This document was last revised for Ghostscript version 6.60.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

--- a/sys/src/cmd/gs/man/font2c.1

+++ /dev/null

@@ -1,25 +1,0 @@

-.\" $Id: font2c.1,v 1.37 2005/10/20 19:46:55 ray Exp $

-.TH FONT2C 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-font2c \- Write PostScript Type 0 or Type 1 font as C code

-.SH SYNOPSIS

-\fBfont2c\fR \fIfontnames\fR

-.SH DESCRIPTION

-This script invokes

-.BR gs (1)

-with the following options:

-.ce

-.B -q -dNODISPLAY -dWRITESYSTEMDICT

-followed by the arguments from the command line.

-This will write out a PostScript Type 0 or Type 1 font as C code

-that can be linked with the interpreter.

-.SH SEE ALSO

-gs(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/font2c.1.man

@@ -1,0 +1,25 @@

+.\" $Id: font2c.1,v 1.37 2005/10/20 19:46:55 ray Exp $

+.TH FONT2C 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+font2c \- Write PostScript Type 0 or Type 1 font as C code

+.SH SYNOPSIS

+\fBfont2c\fR \fIfontnames\fR

+.SH DESCRIPTION

+This script invokes

+.BR gs (1)

+with the following options:

+.ce

+.B -q -dNODISPLAY -dWRITESYSTEMDICT

+followed by the arguments from the command line.

+This will write out a PostScript Type 0 or Type 1 font as C code

+that can be linked with the interpreter.

+.SH SEE ALSO

+gs(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/man/gs.1

+++ /dev/null

@@ -1,404 +1,0 @@

-.\" $Id: gs.1,v 1.38 2005/10/20 19:46:55 ray Exp $

-.TH GS 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-gs \- Ghostscript (PostScript and PDF language interpreter and previewer)

-.SH SYNOPSIS

-\fBgs\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(Unix, VMS)\fR

-.br

-\fBgswin32c\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows)\fR

-.br

-\fBgswin32\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows 3.1)\fR

-.br

-\fBgsos2\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(OS/2)\fR

-.de TQ

-.br

-.ns

-.TP \\$1

-..

-.SH DESCRIPTION

-The \fBgs\fR (\fBgswin32c\fR, \fBgswin32\fR, \fBgsos2\fR)

-command invokes \fBGhostscript\fR, an interpreter of Adobe Systems'

-\fBPostScript\fR(tm) and \fBPortable Document Format\fR (PDF) languages.

-\fBgs\fR reads "files" in sequence and executes them as Ghostscript

-programs. After doing this, it reads further input from the standard input

-stream (normally the keyboard), interpreting each line separately. The

-interpreter exits gracefully when it encounters the "quit" command (either

-in a file or from the keyboard), at end-of-file, or at an interrupt signal

-(such as Control-C at the keyboard).

-.PP

-The interpreter recognizes many option switches, some of which are described

-below. Please see the usage documenation for complete information. Switches

-may appear anywhere in the command line and apply to all files thereafter.

-Invoking Ghostscript with the \fB\-h\fR or \fB\-?\fR switch produces a

-message which shows several useful switches, all the devices known to

-that executable, and the search path for fonts; on Unix it also shows the

-location of detailed documentation.

-.PP

-Ghostscript may be built to use many different output devices.  To see

-which devices your executable includes, run "\fBgs -h\fR".  Unless you

-specify a particular device, Ghostscript normally opens the first one of

-those and directs output to it, so if the first one in the list is the one

-you want to use, just issue the command

-.PP

-.nf

-	gs myfile.ps

-.fi

-.PP

-You can also check the set of available devices from within Ghostscript:

-invoke Ghostscript and type

-.PP

-.nf

-	devicenames ==

-.fi

-.PP

-but the first device on the resulting list may not be the default device

-you determine with "\fBgs -h\fR".  To specify "AbcXyz" as the

-initial output device, include the switch

-.PP

-.nf

-	\-sDEVICE=AbcXyz

-.fi

-.PP

-For example, for output to an Epson printer you might use the command

-.PP

-.nf

-	gs \-sDEVICE=epson myfile.ps

-.fi

-.PP

-The "\-sDEVICE=" switch must precede the first mention of a file to print,

-and only the switch's first use has any effect.

-.PP

-Finally, you can specify a default device in the environment variable

-\fBGS_DEVICE\fR.  The order of precedence for these alternatives from

-highest to lowest (Ghostscript uses the device defined highest in the list)

-is:

-.PP

-Some devices can support different resolutions (densities).  To specify

-the resolution on such a printer, use the "\-r" switch:

-.PP

-.nf

-	gs \-sDEVICE=<device> \-r<xres>x<yres>

-.fi

-.PP

-For example, on a 9-pin Epson-compatible printer, you get the

-lowest-density (fastest) mode with

-.PP

-.nf

-	gs \-sDEVICE=epson \-r60x72

-.fi

-.PP

-and the highest-density (best output quality) mode with

-.PP

-.nf

-	gs \-sDEVICE=epson \-r240x72.

-.fi

-.PP

-If you select a printer as the output device, Ghostscript also allows you

-to choose where Ghostscript sends the output \-\- on Unix systems, usually

-to a temporary file.  To send the output to a file "foo.xyz",

-use the switch

-.PP

-.nf

-	\-sOutputFile=foo.xyz

-.fi

-.PP

-You might want to print each page separately.  To do this, send the output

-to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile="

-switch with "%d" in a filename template:

-.PP

-.nf

-	\-sOutputFile=foo%d.xyz

-.fi

-.PP

-Each resulting file receives one page of output, and the files are numbered

-in sequence.  "%d" is a printf format specification; you can also use a

-variant like "%02d".

-.PP

-On Unix and MS Windows systems you can also send output to a pipe.  For example, to

-pipe output to the "\fBlpr\fR" command (which, on many Unix systems,

-directs it to a printer), use the option

-.PP

-.nf

-	\-sOutputFile=%pipe%lpr

-.fi

-.PP

-Note that the '%' characters need to be doubled on MS Windows to avoid

-mangling by the command interpreter.

-.PP

-You can also send output to standard output:

-.PP

-.nf

-	\-sOutputFile=\-

-.fi

-or

-.nf

-	\-sOutputFile=%stdout%

-.fi

-.PP

-In this case you must also use the \fB\-q\fR switch, to prevent Ghostscript

-from writing messages to standard output.

-.PP

-To select a specific paper size, use the command line switch

-.PP

-.nf

-	-sPAPERSIZE=<paper_size>

-.fi

-.PP

-for instance

-.PP

-.nf

-	-sPAPERSIZE=a4

-.fi

-or

-.nf

-	-sPAPERSIZE=legal

-.fi

-.PP

-Most ISO and US paper sizes are recognized. See the usage documenatation for

-a full list, or the definitions in the initialization file "gs_statd.ps".

-.PP

-Ghostscript can do many things other than print or view PostScript and

-PDF files.  For example, if you want to know the bounding box of a

-PostScript (or EPS) file, Ghostscript provides a special "device" that

-just prints out this information.

-.PP

-For example, using one of the example files distributed with Ghostscript,

-.PP

-.nf

-	gs \-sDEVICE=bbox golfer.ps

-.fi

-.PP

-prints out

-.PP

-.nf

-	%%BoundingBox: 0 25 583 732

-	%%HiResBoundingBox: 0.808497 25.009496 582.994503 731.809445

-.fi

-.SH OPTIONS

-.TP

-.BI \-\- " filename arg1 ..."

-Takes the next argument as a file name as usual, but takes all remaining

-arguments (even if they have the syntactic form of switches) and defines

-the name "ARGUMENTS" in "userdict" (not "systemdict") as an

-array of those strings, \fBbefore\fR running the file.  When Ghostscript

-finishes executing the file, it exits back to the shell.

-.TP

-.BI \-D name = token

-.TQ

-.BI \-d name = token

-Define a name in "systemdict" with the given definition.  The token must be

-exactly one token (as defined by the "token" operator) and may contain no

-whitespace.

-.TP

-.BI \-D name

-.TQ

-.BI \-d name

-Define a name in "systemdict" with value=null.

-.TP

-.BI \-S name = string

-.TQ

-.BI \-s name = string

-Define a name in "systemdict" with a given string as value.  This is

-different from \fB\-d\fR.  For example, \fB\-dname=35\fR is equivalent to the

-program fragment

-.br

-	/name 35 def

-.br

-whereas \fB\-sname=35\fR is equivalent to

-.br

-	/name (35) def

-.TP

-.B \-q

-Quiet startup: suppress normal startup messages, and also do the

-equivalent of \fB\-dQUIET\fR.

-.TP

-.BI \-g number1 x number2

-Equivalent to \fB\-dDEVICEWIDTH=\fR\fInumber1\fR and

-\fB\-dDEVICEHEIGHT=\fR\fInumber2\fR.  This is for the benefit of devices

-(such as X11 windows) that require (or allow) width and height to be

-specified.

-.TP

-.BI \-r number

-.TQ

-.BI \-r number1 x number2

-Equivalent to \fB\-dDEVICEXRESOLUTION=\fR\fInumber1\fR and

-\fB\-dDEVICEYRESOLUTION=\fR\fInumber2\fR.  This is for the benefit of

-devices such as printers that support multiple X and Y resolutions.  If

-only one number is given, it is used for both X and Y resolutions.

-.TP

-.BI \-I directories

-Adds the designated list of directories at the head of the

-search path for library files.

-.TP

-.B \-

-This is not really a switch, but indicates to Ghostscript that standard

-input is coming from a file or a pipe and not interactively from the

-command line.  Ghostscript reads from standard input until it reaches

-end-of-file, executing it like any other file, and then continues with

-processing the command line.  When the command line has been entirely

-processed, Ghostscript exits rather than going into its interactive mode.

-.PP

-Note that the normal initialization file "gs_init.ps" makes "systemdict"

-read-only, so the values of names defined with \fB\-D\fR, \fB\-d\fR,

-\fB\-S\fR, or \fB\-s\fR cannot be changed (although, of course, they can be

-superseded by definitions in "userdict" or other dictionaries.)

-.SH "SPECIAL NAMES"

-.TP

-.B \-dDISKFONTS

-Causes individual character outlines to be loaded from the disk

-the first time they are encountered.  (Normally Ghostscript loads all the

-character outlines when it loads a font.)  This may allow loading more

-fonts into RAM, at the expense of slower rendering.

-.TP

-.B \-dNOCACHE

-Disables character caching.  Useful only for debugging.

-.TP

-.B \-dNOBIND

-Disables the "bind" operator.  Useful only for debugging.

-.TP

-.B \-dNODISPLAY

-Suppresses the normal initialization of the output device.

-This may be useful when debugging.

-.TP

-.B \-dNOPAUSE

-Disables the prompt and pause at the end of each page.  This may be

-desirable for applications where another program is driving Ghostscript.

-.TP

-.B \-dNOPLATFONTS

-Disables the use of fonts supplied by the underlying platform (for instance

-X Windows). This may be needed if the platform fonts look undesirably

-different from the scalable fonts.

-.TP

-.B \-dSAFER

-Disables the "deletefile" and "renamefile" operators and the ability to

-open files in any mode other than read-only.  This strongly recommended for

-spoolers, conversion scripts or other sensitive environments where a badly

-written or malicious PostScript program code must be prevented from changing

-important files.

-.TP

-.B \-dWRITESYSTEMDICT

-Leaves "systemdict" writable.  This is necessary when running special

-utility programs such as \fBfont2c\fR and \fBpcharstr\fR, which must bypass

-normal PostScript access protection.

-.TP

-.BI \-sDEVICE= device

-Selects an alternate initial output device, as described above.

-.TP

-.BI \-sOutputFile= filename

-Selects an alternate output file (or pipe) for the initial output

-device, as described above.

-.SH FILES

-.PP

-The locations of many Ghostscript run-time files are compiled into the

-executable when it is built.  On Unix these are typically based in

-\fB/usr/local\fR, but this may be different on your system.  Under DOS they

-are typically based in \fBC:\\GS\fR, but may be elsewhere, especially if

-you install Ghostscript with \fBGSview\fR.  Run "\fBgs -h\fR" to find the

-location of Ghostscript documentation on your system, from which you can

-get more details.

-.TP

-.B /usr/local/share/ghostscript/#.##/*

-Startup files, utilities, and basic font definitions

-.TP

-.B /usr/local/share/ghostscript/fonts/*

-More font definitions

-.TP

-.B /usr/local/share/ghostscript/#.##/examples/*

-Ghostscript demonstration files

-.TP

-.B /usr/local/share/ghostscript/#.##/doc/*

-Diverse document files

-.SH "INITIALIZATION FILES"

-When looking for the initialization files "gs_*.ps", the files related to

-fonts, or the file for the "run" operator, Ghostscript first tries to open

-the file with the name as given, using the current working directory if no

-directory is specified.  If this fails, and the file name doesn't specify

-an explicit directory or drive (for instance, doesn't contain "/" on Unix

-systems or "\\" on MS Windows systems), Ghostscript tries directories in this

-order:

-.TP 4

-1.

-the directories specified by the \fB\-I\fR switches in the command

-line (see below), if any;

-.TP

-2.

-the directories specified by the \fBGS_LIB\fR environment variable,

-if any;

-.TP

-3.

-the directories specified by the \fBGS_LIB_DEFAULT\fR macro in the

-Ghostscript makefile when the executable was built.  When \fBgs\fR is built

-on Unix, \fBGS_LIB_DEFAULT\fR is usually

-"/usr/local/share/ghostscript/#.##:/usr/local/share/ghostscript/fonts"

-where "#.##" represents the Ghostscript version number.

-.PP

-Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter)

-may be either a single directory or a list of directories separated by

-":".

-.SH ENVIRONMENT

-.TP

-.B GS_OPTIONS

-String of options to be processed before the command line options

-.TP

-.B GS_DEVICE

-Used to specify an output device

-.TP

-.B GS_FONTPATH

-Path names used to search for fonts

-.TP

-.B GS_LIB

-Path names for initialization files and fonts

-.TP

-.B  TEMP

-Where temporary files are made

-.SH X RESOURCES

-Ghostscript, or more properly the X11 display device, looks for the

-following resources under the program name "Ghostscript":

-.TP

-.B borderWidth

-The border width in pixels (default = 1).

-.TP

-.B borderColor

-The name of the border color (default = black).

-.TP

-.B geometry

-The window size and placement, WxH+X+Y (default is NULL).

-.TP

-.B xResolution

-The number of x pixels per inch (default is computed from \fBWidthOfScreen\fR

-and \fBWidthMMOfScreen\fR).

-.TP

-.B yResolution

-The number of y pixels per inch (default is computed from

-\fBHeightOfScreen\fR and \fBHeightMMOfScreen\fR).

-.TP

-.B useBackingPixmap

-Determines whether backing store is to be used for saving display window

-(default = true).

-.PP

-See the usage document for a more complete list of resources.  To set these

-resources on Unix, put them in a file such as "~/.Xresources" in the

-following form:

-.PP

-.nf

-	Ghostscript*geometry:	 612x792\-0+0

-	Ghostscript*xResolution: 72

-	Ghostscript*yResolution: 72

-.fi

-.PP

-Then merge these resources into the X server's resource database:

-.PP

-.nf

-	% xrdb \-merge ~/.Xresources

-.fi

-.SH SEE ALSO

-The various Ghostscript document files (above), especially \fBUse.htm\fR.

-.SH BUGS

-See the Usenet news group comp.lang.postscript.

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-Russell J. Lang, gsview at ghostgum.com.au, is the author of most of the

-MS Windows code in Ghostscript.

--- /dev/null

+++ b/sys/src/cmd/gs/man/gs.1.man

@@ -1,0 +1,404 @@

+.\" $Id: gs.1,v 1.38 2005/10/20 19:46:55 ray Exp $

+.TH GS 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+gs \- Ghostscript (PostScript and PDF language interpreter and previewer)

+.SH SYNOPSIS

+\fBgs\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(Unix, VMS)\fR

+.br

+\fBgswin32c\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows)\fR

+.br

+\fBgswin32\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows 3.1)\fR

+.br

+\fBgsos2\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(OS/2)\fR

+.de TQ

+.br

+.ns

+.TP \\$1

+..

+.SH DESCRIPTION

+The \fBgs\fR (\fBgswin32c\fR, \fBgswin32\fR, \fBgsos2\fR)

+command invokes \fBGhostscript\fR, an interpreter of Adobe Systems'

+\fBPostScript\fR(tm) and \fBPortable Document Format\fR (PDF) languages.

+\fBgs\fR reads "files" in sequence and executes them as Ghostscript

+programs. After doing this, it reads further input from the standard input

+stream (normally the keyboard), interpreting each line separately. The

+interpreter exits gracefully when it encounters the "quit" command (either

+in a file or from the keyboard), at end-of-file, or at an interrupt signal

+(such as Control-C at the keyboard).

+.PP

+The interpreter recognizes many option switches, some of which are described

+below. Please see the usage documenation for complete information. Switches

+may appear anywhere in the command line and apply to all files thereafter.

+Invoking Ghostscript with the \fB\-h\fR or \fB\-?\fR switch produces a

+message which shows several useful switches, all the devices known to

+that executable, and the search path for fonts; on Unix it also shows the

+location of detailed documentation.

+.PP

+Ghostscript may be built to use many different output devices.  To see

+which devices your executable includes, run "\fBgs -h\fR".  Unless you

+specify a particular device, Ghostscript normally opens the first one of

+those and directs output to it, so if the first one in the list is the one

+you want to use, just issue the command

+.PP

+.nf

+	gs myfile.ps

+.fi

+.PP

+You can also check the set of available devices from within Ghostscript:

+invoke Ghostscript and type

+.PP

+.nf

+	devicenames ==

+.fi

+.PP

+but the first device on the resulting list may not be the default device

+you determine with "\fBgs -h\fR".  To specify "AbcXyz" as the

+initial output device, include the switch

+.PP

+.nf

+	\-sDEVICE=AbcXyz

+.fi

+.PP

+For example, for output to an Epson printer you might use the command

+.PP

+.nf

+	gs \-sDEVICE=epson myfile.ps

+.fi

+.PP

+The "\-sDEVICE=" switch must precede the first mention of a file to print,

+and only the switch's first use has any effect.

+.PP

+Finally, you can specify a default device in the environment variable

+\fBGS_DEVICE\fR.  The order of precedence for these alternatives from

+highest to lowest (Ghostscript uses the device defined highest in the list)

+is:

+.PP

+Some devices can support different resolutions (densities).  To specify

+the resolution on such a printer, use the "\-r" switch:

+.PP

+.nf

+	gs \-sDEVICE=<device> \-r<xres>x<yres>

+.fi

+.PP

+For example, on a 9-pin Epson-compatible printer, you get the

+lowest-density (fastest) mode with

+.PP

+.nf

+	gs \-sDEVICE=epson \-r60x72

+.fi

+.PP

+and the highest-density (best output quality) mode with

+.PP

+.nf

+	gs \-sDEVICE=epson \-r240x72.

+.fi

+.PP

+If you select a printer as the output device, Ghostscript also allows you

+to choose where Ghostscript sends the output \-\- on Unix systems, usually

+to a temporary file.  To send the output to a file "foo.xyz",

+use the switch

+.PP

+.nf

+	\-sOutputFile=foo.xyz

+.fi

+.PP

+You might want to print each page separately.  To do this, send the output

+to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile="

+switch with "%d" in a filename template:

+.PP

+.nf

+	\-sOutputFile=foo%d.xyz

+.fi

+.PP

+Each resulting file receives one page of output, and the files are numbered

+in sequence.  "%d" is a printf format specification; you can also use a

+variant like "%02d".

+.PP

+On Unix and MS Windows systems you can also send output to a pipe.  For example, to

+pipe output to the "\fBlpr\fR" command (which, on many Unix systems,

+directs it to a printer), use the option

+.PP

+.nf

+	\-sOutputFile=%pipe%lpr

+.fi

+.PP

+Note that the '%' characters need to be doubled on MS Windows to avoid

+mangling by the command interpreter.

+.PP

+You can also send output to standard output:

+.PP

+.nf

+	\-sOutputFile=\-

+.fi

+or

+.nf

+	\-sOutputFile=%stdout%

+.fi

+.PP

+In this case you must also use the \fB\-q\fR switch, to prevent Ghostscript

+from writing messages to standard output.

+.PP

+To select a specific paper size, use the command line switch

+.PP

+.nf

+	-sPAPERSIZE=<paper_size>

+.fi

+.PP

+for instance

+.PP

+.nf

+	-sPAPERSIZE=a4

+.fi

+or

+.nf

+	-sPAPERSIZE=legal

+.fi

+.PP

+Most ISO and US paper sizes are recognized. See the usage documenatation for

+a full list, or the definitions in the initialization file "gs_statd.ps".

+.PP

+Ghostscript can do many things other than print or view PostScript and

+PDF files.  For example, if you want to know the bounding box of a

+PostScript (or EPS) file, Ghostscript provides a special "device" that

+just prints out this information.

+.PP

+For example, using one of the example files distributed with Ghostscript,

+.PP

+.nf

+	gs \-sDEVICE=bbox golfer.ps

+.fi

+.PP

+prints out

+.PP

+.nf

+	%%BoundingBox: 0 25 583 732

+	%%HiResBoundingBox: 0.808497 25.009496 582.994503 731.809445

+.fi

+.SH OPTIONS

+.TP

+.BI \-\- " filename arg1 ..."

+Takes the next argument as a file name as usual, but takes all remaining

+arguments (even if they have the syntactic form of switches) and defines

+the name "ARGUMENTS" in "userdict" (not "systemdict") as an

+array of those strings, \fBbefore\fR running the file.  When Ghostscript

+finishes executing the file, it exits back to the shell.

+.TP

+.BI \-D name = token

+.TQ

+.BI \-d name = token

+Define a name in "systemdict" with the given definition.  The token must be

+exactly one token (as defined by the "token" operator) and may contain no

+whitespace.

+.TP

+.BI \-D name

+.TQ

+.BI \-d name

+Define a name in "systemdict" with value=null.

+.TP

+.BI \-S name = string

+.TQ

+.BI \-s name = string

+Define a name in "systemdict" with a given string as value.  This is

+different from \fB\-d\fR.  For example, \fB\-dname=35\fR is equivalent to the

+program fragment

+.br

+	/name 35 def

+.br

+whereas \fB\-sname=35\fR is equivalent to

+.br

+	/name (35) def

+.TP

+.B \-q

+Quiet startup: suppress normal startup messages, and also do the

+equivalent of \fB\-dQUIET\fR.

+.TP

+.BI \-g number1 x number2

+Equivalent to \fB\-dDEVICEWIDTH=\fR\fInumber1\fR and

+\fB\-dDEVICEHEIGHT=\fR\fInumber2\fR.  This is for the benefit of devices

+(such as X11 windows) that require (or allow) width and height to be

+specified.

+.TP

+.BI \-r number

+.TQ

+.BI \-r number1 x number2

+Equivalent to \fB\-dDEVICEXRESOLUTION=\fR\fInumber1\fR and

+\fB\-dDEVICEYRESOLUTION=\fR\fInumber2\fR.  This is for the benefit of

+devices such as printers that support multiple X and Y resolutions.  If

+only one number is given, it is used for both X and Y resolutions.

+.TP

+.BI \-I directories

+Adds the designated list of directories at the head of the

+search path for library files.

+.TP

+.B \-

+This is not really a switch, but indicates to Ghostscript that standard

+input is coming from a file or a pipe and not interactively from the

+command line.  Ghostscript reads from standard input until it reaches

+end-of-file, executing it like any other file, and then continues with

+processing the command line.  When the command line has been entirely

+processed, Ghostscript exits rather than going into its interactive mode.

+.PP

+Note that the normal initialization file "gs_init.ps" makes "systemdict"

+read-only, so the values of names defined with \fB\-D\fR, \fB\-d\fR,

+\fB\-S\fR, or \fB\-s\fR cannot be changed (although, of course, they can be

+superseded by definitions in "userdict" or other dictionaries.)

+.SH "SPECIAL NAMES"

+.TP

+.B \-dDISKFONTS

+Causes individual character outlines to be loaded from the disk

+the first time they are encountered.  (Normally Ghostscript loads all the

+character outlines when it loads a font.)  This may allow loading more

+fonts into RAM, at the expense of slower rendering.

+.TP

+.B \-dNOCACHE

+Disables character caching.  Useful only for debugging.

+.TP

+.B \-dNOBIND

+Disables the "bind" operator.  Useful only for debugging.

+.TP

+.B \-dNODISPLAY

+Suppresses the normal initialization of the output device.

+This may be useful when debugging.

+.TP

+.B \-dNOPAUSE

+Disables the prompt and pause at the end of each page.  This may be

+desirable for applications where another program is driving Ghostscript.

+.TP

+.B \-dNOPLATFONTS

+Disables the use of fonts supplied by the underlying platform (for instance

+X Windows). This may be needed if the platform fonts look undesirably

+different from the scalable fonts.

+.TP

+.B \-dSAFER

+Disables the "deletefile" and "renamefile" operators and the ability to

+open files in any mode other than read-only.  This strongly recommended for

+spoolers, conversion scripts or other sensitive environments where a badly

+written or malicious PostScript program code must be prevented from changing

+important files.

+.TP

+.B \-dWRITESYSTEMDICT

+Leaves "systemdict" writable.  This is necessary when running special

+utility programs such as \fBfont2c\fR and \fBpcharstr\fR, which must bypass

+normal PostScript access protection.

+.TP

+.BI \-sDEVICE= device

+Selects an alternate initial output device, as described above.

+.TP

+.BI \-sOutputFile= filename

+Selects an alternate output file (or pipe) for the initial output

+device, as described above.

+.SH FILES

+.PP

+The locations of many Ghostscript run-time files are compiled into the

+executable when it is built.  On Unix these are typically based in

+\fB/usr/local\fR, but this may be different on your system.  Under DOS they

+are typically based in \fBC:\\GS\fR, but may be elsewhere, especially if

+you install Ghostscript with \fBGSview\fR.  Run "\fBgs -h\fR" to find the

+location of Ghostscript documentation on your system, from which you can

+get more details.

+.TP

+.B /usr/local/share/ghostscript/#.##/*

+Startup files, utilities, and basic font definitions

+.TP

+.B /usr/local/share/ghostscript/fonts/*

+More font definitions

+.TP

+.B /usr/local/share/ghostscript/#.##/examples/*

+Ghostscript demonstration files

+.TP

+.B /usr/local/share/ghostscript/#.##/doc/*

+Diverse document files

+.SH "INITIALIZATION FILES"

+When looking for the initialization files "gs_*.ps", the files related to

+fonts, or the file for the "run" operator, Ghostscript first tries to open

+the file with the name as given, using the current working directory if no

+directory is specified.  If this fails, and the file name doesn't specify

+an explicit directory or drive (for instance, doesn't contain "/" on Unix

+systems or "\\" on MS Windows systems), Ghostscript tries directories in this

+order:

+.TP 4

+1.

+the directories specified by the \fB\-I\fR switches in the command

+line (see below), if any;

+.TP

+2.

+the directories specified by the \fBGS_LIB\fR environment variable,

+if any;

+.TP

+3.

+the directories specified by the \fBGS_LIB_DEFAULT\fR macro in the

+Ghostscript makefile when the executable was built.  When \fBgs\fR is built

+on Unix, \fBGS_LIB_DEFAULT\fR is usually

+"/usr/local/share/ghostscript/#.##:/usr/local/share/ghostscript/fonts"

+where "#.##" represents the Ghostscript version number.

+.PP

+Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter)

+may be either a single directory or a list of directories separated by

+":".

+.SH ENVIRONMENT

+.TP

+.B GS_OPTIONS

+String of options to be processed before the command line options

+.TP

+.B GS_DEVICE

+Used to specify an output device

+.TP

+.B GS_FONTPATH

+Path names used to search for fonts

+.TP

+.B GS_LIB

+Path names for initialization files and fonts

+.TP

+.B  TEMP

+Where temporary files are made

+.SH X RESOURCES

+Ghostscript, or more properly the X11 display device, looks for the

+following resources under the program name "Ghostscript":

+.TP

+.B borderWidth

+The border width in pixels (default = 1).

+.TP

+.B borderColor

+The name of the border color (default = black).

+.TP

+.B geometry

+The window size and placement, WxH+X+Y (default is NULL).

+.TP

+.B xResolution

+The number of x pixels per inch (default is computed from \fBWidthOfScreen\fR

+and \fBWidthMMOfScreen\fR).

+.TP

+.B yResolution

+The number of y pixels per inch (default is computed from

+\fBHeightOfScreen\fR and \fBHeightMMOfScreen\fR).

+.TP

+.B useBackingPixmap

+Determines whether backing store is to be used for saving display window

+(default = true).

+.PP

+See the usage document for a more complete list of resources.  To set these

+resources on Unix, put them in a file such as "~/.Xresources" in the

+following form:

+.PP

+.nf

+	Ghostscript*geometry:	 612x792\-0+0

+	Ghostscript*xResolution: 72

+	Ghostscript*yResolution: 72

+.fi

+.PP

+Then merge these resources into the X server's resource database:

+.PP

+.nf

+	% xrdb \-merge ~/.Xresources

+.fi

+.SH SEE ALSO

+The various Ghostscript document files (above), especially \fBUse.htm\fR.

+.SH BUGS

+See the Usenet news group comp.lang.postscript.

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+Russell J. Lang, gsview at ghostgum.com.au, is the author of most of the

+MS Windows code in Ghostscript.

--- a/sys/src/cmd/gs/man/gslp.1

+++ /dev/null

@@ -1,100 +1,0 @@

-.\" $Id: gslp.1,v 1.37 2005/10/20 19:46:55 ray Exp $

-.TH GSLP 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-gslp \- Format and print text using ghostscript

-.br

-gsbj \- Format and print text for BubbleJet printer using ghostscript

-.br

-gsdj \- Format and print text for DeskJet printer using ghostscript

-.br

-gsdj500 \- Format and print text for DeskJet 500 BubbleJet using ghostscript

-.br

-gslj \- Format and print text for LaserJet printer using ghostscript

-.SH SYNOPSIS

-.na

-\fBgslp\fB

-\-12BclqRr \-b<header> \-f<font> \-F<hfont> \-L<lines> \-p<outfile>

-\-T<n>

-\-\-add\-to\-space\ <units>

-\-\-add\-to\-width\ <units>

-\-\-columns\ <n>

-\-\-detect

-\-\-first\-page\ <n>

-\-\-kern\ <file.afm>

-\-\-last\-page\ <n>

-\-\-(heading|footing)\-(left|center|right)\ <string>

-\-\-margin\-(top|bottom|left|right)\ <inches>

-\-\-no\-eject\-(file|formfeed)

-\-\-spacing\ <n>

-[gs\ options] [files]

-.ad

-.br

-\fBgsbj\fR [options] [files]

-.br

-\fBgsdj\fR [options] [files]

-.br

-\fBgsdj500\fR [options] [files]

-.br

-\fBgslj\fR [options] [files]

-.SH DESCRIPTION

-This utility provides functionality approximately equivalent to the Unix

-.BR enscript (1)

-program.  It prints plain text files using a single font.

-It currently handles tabs and formfeeds, but not backspaces.

-It will line-wrap when using fixed-pitch fonts.

-It will also do kerning and width adjustment.

-.PP

-The default device (\-sDEVICE=) and resolution (\-r) are as follows:

-.nf

-.na

-      gslp      epson      180

-      gsbj      bj10e      180

-      gsdj      deskjet    300

-      gsdj500   djet500    300

-      gslj      laserjet   300

-.ad

-.fi

-By default the current date is formatted as the center header.

-.SH OPTIONS

-.IP "Standard switches implemented:"

--12BclqRr -b<header> -f<font> -F<hfont> -L<lines> -p<outfile>

-.IP "Sun switches implemented:"

--T<n>	set tab width

-.IP "Switches ignored:"

--GghKkmow -# -C -d -J -n -P -S -s -t -v

-.IP "Switches added:"

-.RS

-.IP "--add-to-space <units>"

-add the given number of 1/72" units to the width of each

-space (may be negative)

-.IP "--add-to-width <units>"

-add the given number of 1/72" units to the width of each

-character (may be negative)

-.IP "--columns <n>"

-print in <n> columns

-.IP "--detect"

-treat the file as PostScript if it starts with %!

-.IP "--first-page <n>"

-start printing at page <n>

-.IP "--kern <file.afm>"

-kern using information from the given .AFM file

-.IP "--last-page <n>"

-stop printing after page <n>

-.IP "--(heading|footing)-(left|center|right) <string>"

-set the heading/footing fields; use -B first to clear

-.IP "--margin-(top|bottom|left|right) <inches>"

-set a margin

-.IP "--no-eject-(file|formfeed)"

-end-of-file/FF only starts a new column, not a new sheet

-.IP "--spacing <n>"

-use double (n=2), triple (n=3), etc. spacing

-.RE

-Also, the string %# in a heading or footing is replaced with the page #.

-.SH SEE ALSO

-gs(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/gslp.1.man

@@ -1,0 +1,100 @@

+.\" $Id: gslp.1,v 1.37 2005/10/20 19:46:55 ray Exp $

+.TH GSLP 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+gslp \- Format and print text using ghostscript

+.br

+gsbj \- Format and print text for BubbleJet printer using ghostscript

+.br

+gsdj \- Format and print text for DeskJet printer using ghostscript

+.br

+gsdj500 \- Format and print text for DeskJet 500 BubbleJet using ghostscript

+.br

+gslj \- Format and print text for LaserJet printer using ghostscript

+.SH SYNOPSIS

+.na

+\fBgslp\fB

+\-12BclqRr \-b<header> \-f<font> \-F<hfont> \-L<lines> \-p<outfile>

+\-T<n>

+\-\-add\-to\-space\ <units>

+\-\-add\-to\-width\ <units>

+\-\-columns\ <n>

+\-\-detect

+\-\-first\-page\ <n>

+\-\-kern\ <file.afm>

+\-\-last\-page\ <n>

+\-\-(heading|footing)\-(left|center|right)\ <string>

+\-\-margin\-(top|bottom|left|right)\ <inches>

+\-\-no\-eject\-(file|formfeed)

+\-\-spacing\ <n>

+[gs\ options] [files]

+.ad

+.br

+\fBgsbj\fR [options] [files]

+.br

+\fBgsdj\fR [options] [files]

+.br

+\fBgsdj500\fR [options] [files]

+.br

+\fBgslj\fR [options] [files]

+.SH DESCRIPTION

+This utility provides functionality approximately equivalent to the Unix

+.BR enscript (1)

+program.  It prints plain text files using a single font.

+It currently handles tabs and formfeeds, but not backspaces.

+It will line-wrap when using fixed-pitch fonts.

+It will also do kerning and width adjustment.

+.PP

+The default device (\-sDEVICE=) and resolution (\-r) are as follows:

+.nf

+.na

+      gslp      epson      180

+      gsbj      bj10e      180

+      gsdj      deskjet    300

+      gsdj500   djet500    300

+      gslj      laserjet   300

+.ad

+.fi

+By default the current date is formatted as the center header.

+.SH OPTIONS

+.IP "Standard switches implemented:"

+-12BclqRr -b<header> -f<font> -F<hfont> -L<lines> -p<outfile>

+.IP "Sun switches implemented:"

+-T<n>	set tab width

+.IP "Switches ignored:"

+-GghKkmow -# -C -d -J -n -P -S -s -t -v

+.IP "Switches added:"

+.RS

+.IP "--add-to-space <units>"

+add the given number of 1/72" units to the width of each

+space (may be negative)

+.IP "--add-to-width <units>"

+add the given number of 1/72" units to the width of each

+character (may be negative)

+.IP "--columns <n>"

+print in <n> columns

+.IP "--detect"

+treat the file as PostScript if it starts with %!

+.IP "--first-page <n>"

+start printing at page <n>

+.IP "--kern <file.afm>"

+kern using information from the given .AFM file

+.IP "--last-page <n>"

+stop printing after page <n>

+.IP "--(heading|footing)-(left|center|right) <string>"

+set the heading/footing fields; use -B first to clear

+.IP "--margin-(top|bottom|left|right) <inches>"

+set a margin

+.IP "--no-eject-(file|formfeed)"

+end-of-file/FF only starts a new column, not a new sheet

+.IP "--spacing <n>"

+use double (n=2), triple (n=3), etc. spacing

+.RE

+Also, the string %# in a heading or footing is replaced with the page #.

+.SH SEE ALSO

+gs(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/man/gsnd.1

+++ /dev/null

@@ -1,20 +1,0 @@

-.\" $Id: gsnd.1,v 1.37 2005/10/20 19:46:55 ray Exp $

-.TH GSND 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-gsnd \- Run ghostscript (PostScript and PDF engine) without display

-.SH SYNOPSIS

-\fBgsnd\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ...

-.SH DESCRIPTION

-This script simply invokes

-.BR gs (1)

-with the

-.B -NODISPLAY

-flag, followed by any other arguments from the command-line.

-.SH SEE ALSO

-gs(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/gsnd.1.man

@@ -1,0 +1,20 @@

+.\" $Id: gsnd.1,v 1.37 2005/10/20 19:46:55 ray Exp $

+.TH GSND 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+gsnd \- Run ghostscript (PostScript and PDF engine) without display

+.SH SYNOPSIS

+\fBgsnd\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ...

+.SH DESCRIPTION

+This script simply invokes

+.BR gs (1)

+with the

+.B -NODISPLAY

+flag, followed by any other arguments from the command-line.

+.SH SEE ALSO

+gs(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/man/pdf2dsc.1

+++ /dev/null

@@ -1,34 +1,0 @@

-.\" $Id: pdf2dsc.1,v 1.36 2005/10/20 19:46:55 ray Exp $

-.TH PDF2DSC 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

-.SH NAME

-pdf2dsc \- generate a PostScript page list of a PDF document

-.SH SYNOPSIS

-\fBpdf2dsc\fR \fIinput.pdf\fR [ \fIoutput.dsc\fR ]

-.SH DESCRIPTION

-\fBpdf2dsc\fR uses \fBgs\fR(1) to read an Adobe \fBPortable Document

-Format\fR (PDF) document "input.pdf" and create a \fBPostScript\fR(tm)

-document "output.dsc" that conforms to Adobe's \fBDocument Structuring

-Conventions\fR (DSC) requirements.

-.PP

-This new document simply tells Ghostscript to read the PDF file and to

-display pages one at a time.  The generated document can then be viewed

-with any PostScript viewer based on Ghostscript, like \fBghostview\fR(1) on

-Unix or \fBGSview\fR on Windows, with which the user can browse through the

-pages of the PDF document in any order.

-.PP

-If no output file is named on the command line, the name of the output file

-is that of the input file with any extension removed, followed by the

-extension "\.dsc".

-.SH CAVEATS

-The DSC document uses Ghostscript-specific procedures.  In addition, the

-original PDF document must be accessible when the DSC document is

-processed.

-.PP

-You need the file "pdf2dsc.ps" (originally by Russell Lang) supplied with

-Ghostscript since release 3.53.

-.SH SEE ALSO

-gs(1), ghostview(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-Yves Arrouye <[email protected]> and Russell Lang gsview at ghostgum.com.au

--- /dev/null

+++ b/sys/src/cmd/gs/man/pdf2dsc.1.man

@@ -1,0 +1,34 @@

+.\" $Id: pdf2dsc.1,v 1.36 2005/10/20 19:46:55 ray Exp $

+.TH PDF2DSC 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

+.SH NAME

+pdf2dsc \- generate a PostScript page list of a PDF document

+.SH SYNOPSIS

+\fBpdf2dsc\fR \fIinput.pdf\fR [ \fIoutput.dsc\fR ]

+.SH DESCRIPTION

+\fBpdf2dsc\fR uses \fBgs\fR(1) to read an Adobe \fBPortable Document

+Format\fR (PDF) document "input.pdf" and create a \fBPostScript\fR(tm)

+document "output.dsc" that conforms to Adobe's \fBDocument Structuring

+Conventions\fR (DSC) requirements.

+.PP

+This new document simply tells Ghostscript to read the PDF file and to

+display pages one at a time.  The generated document can then be viewed

+with any PostScript viewer based on Ghostscript, like \fBghostview\fR(1) on

+Unix or \fBGSview\fR on Windows, with which the user can browse through the

+pages of the PDF document in any order.

+.PP

+If no output file is named on the command line, the name of the output file

+is that of the input file with any extension removed, followed by the

+extension "\.dsc".

+.SH CAVEATS

+The DSC document uses Ghostscript-specific procedures.  In addition, the

+original PDF document must be accessible when the DSC document is

+processed.

+.PP

+You need the file "pdf2dsc.ps" (originally by Russell Lang) supplied with

+Ghostscript since release 3.53.

+.SH SEE ALSO

+gs(1), ghostview(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+Yves Arrouye <[email protected]> and Russell Lang gsview at ghostgum.com.au

--- a/sys/src/cmd/gs/man/pdf2ps.1

+++ /dev/null

@@ -1,21 +1,0 @@

-.\" $Id: pdf2ps.1,v 1.38 2005/10/20 19:46:55 ray Exp $

-.TH PDF2PS 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

-.SH NAME

-pdf2ps \- Ghostscript PDF to PostScript translator

-.SH SYNOPSIS

-\fBpdf2ps\fR [ \fIoptions\fR ] \fIinput.pdf [output.ps]\fR

-.SH DESCRIPTION

-\fBpdf2ps\fR uses \fBgs\fR(1) to convert the Adobe \fBPortable Document

-Format\fR (PDF) file "input.pdf" to \fBPostScript\fR(tm) in "output.ps".

-Normally the output is allowed to use PostScript Level 2 (but not PostScript

-LanguageLevel 3) constructs; the \fB-dLanguageLevel=1\fR option restricts

-the output to Level 1, while \fB-dLanguageLevel=3\fR allows using

-LanguageLevel 3 in the output.

-.SH FILES

-Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

-system, from which you can get more details.

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

--- /dev/null

+++ b/sys/src/cmd/gs/man/pdf2ps.1.man

@@ -1,0 +1,21 @@

+.\" $Id: pdf2ps.1,v 1.38 2005/10/20 19:46:55 ray Exp $

+.TH PDF2PS 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

+.SH NAME

+pdf2ps \- Ghostscript PDF to PostScript translator

+.SH SYNOPSIS

+\fBpdf2ps\fR [ \fIoptions\fR ] \fIinput.pdf [output.ps]\fR

+.SH DESCRIPTION

+\fBpdf2ps\fR uses \fBgs\fR(1) to convert the Adobe \fBPortable Document

+Format\fR (PDF) file "input.pdf" to \fBPostScript\fR(tm) in "output.ps".

+Normally the output is allowed to use PostScript Level 2 (but not PostScript

+LanguageLevel 3) constructs; the \fB-dLanguageLevel=1\fR option restricts

+the output to Level 1, while \fB-dLanguageLevel=3\fR allows using

+LanguageLevel 3 in the output.

+.SH FILES

+Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

+system, from which you can get more details.

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

--- a/sys/src/cmd/gs/man/pdfopt.1

+++ /dev/null

@@ -1,27 +1,0 @@

-.\" $Id: pdfopt.1,v 1.36 2005/10/20 19:46:55 ray Exp $

-.TH PDFOPT 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

-.SH NAME

-pdfopt \- Ghostscript PDF Optimizer

-.SH SYNOPSIS

-\fBpdfopt\fR [ \fIoptions\fR ] \fIinput.pdf output.pdf\fR

-.SH DESCRIPTION

-\fBpdfopt\fR uses \fBgs\fR(1) to convert the Adobe \fBPortable Document

-Format\fR (PDF) file "input.pdf" to a so-called optimized form in

-"output.pdf".  Optimization puts the elements of the file into a more linear

-order and adds "hint" pointers, allowing Adobe's Acrobat(TM) products to

-display individual pages of the file more quickly when accessing the file

-through a network.

-.PP

-Note: input.pdf and output.pdf must not be the same.  If they are, the file

-will probably be destroyed.  \fBpdfopt\fR currently does not check for this.

-.SH FILES

-Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

-system, from which you can get more details.

-.SH SEE ALSO

-"Linearized PDF" in Adobe's PDF reference manual,

-http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

--- /dev/null

+++ b/sys/src/cmd/gs/man/pdfopt.1.man

@@ -1,0 +1,27 @@

+.\" $Id: pdfopt.1,v 1.36 2005/10/20 19:46:55 ray Exp $

+.TH PDFOPT 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

+.SH NAME

+pdfopt \- Ghostscript PDF Optimizer

+.SH SYNOPSIS

+\fBpdfopt\fR [ \fIoptions\fR ] \fIinput.pdf output.pdf\fR

+.SH DESCRIPTION

+\fBpdfopt\fR uses \fBgs\fR(1) to convert the Adobe \fBPortable Document

+Format\fR (PDF) file "input.pdf" to a so-called optimized form in

+"output.pdf".  Optimization puts the elements of the file into a more linear

+order and adds "hint" pointers, allowing Adobe's Acrobat(TM) products to

+display individual pages of the file more quickly when accessing the file

+through a network.

+.PP

+Note: input.pdf and output.pdf must not be the same.  If they are, the file

+will probably be destroyed.  \fBpdfopt\fR currently does not check for this.

+.SH FILES

+Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

+system, from which you can get more details.

+.SH SEE ALSO

+"Linearized PDF" in Adobe's PDF reference manual,

+http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

--- a/sys/src/cmd/gs/man/pf2afm.1

+++ /dev/null

@@ -1,23 +1,0 @@

-.\" $Id: pf2afm.1,v 1.37 2005/10/20 19:46:55 ray Exp $

-.TH PF2AFM 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-pf2afm \- Make an AFM file from Postscript (PFB/PFA/PFM) font files using ghostscript

-.SH SYNOPSIS

-\fBpf2afm\fR  \fIfontfilename\fR

-.SH DESCRIPTION

-This script invokes

-.BR gs (1)

-to make an AFM file from PFB / PFA and (optionally) PFM files.

-Output goes to

-.IR fontfilename.afm ,

-which must not already exist.

-.SH SEE ALSO

-gs(1)

-.br

-pf2afm.ps in the Ghostscript lib directory.

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/pf2afm.1.man

@@ -1,0 +1,23 @@

+.\" $Id: pf2afm.1,v 1.37 2005/10/20 19:46:55 ray Exp $

+.TH PF2AFM 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+pf2afm \- Make an AFM file from Postscript (PFB/PFA/PFM) font files using ghostscript

+.SH SYNOPSIS

+\fBpf2afm\fR  \fIfontfilename\fR

+.SH DESCRIPTION

+This script invokes

+.BR gs (1)

+to make an AFM file from PFB / PFA and (optionally) PFM files.

+Output goes to

+.IR fontfilename.afm ,

+which must not already exist.

+.SH SEE ALSO

+gs(1)

+.br

+pf2afm.ps in the Ghostscript lib directory.

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/man/pfbtopfa.1

+++ /dev/null

@@ -1,18 +1,0 @@

-.\" $Id: pfbtopfa.1,v 1.38 2005/10/20 19:46:55 ray Exp $

-.TH PFBTOPFA 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-pfbtopfa \- Convert Postscript .pfb fonts to .pfa format using ghostscript

-.SH SYNOPSIS

-\fBpfbtopfa\fR \fIinput.pfb\fR \fI[output.pfa]\fR

-.SH DESCRIPTION

-This script invokes

-.BR gs (1)

-to convert a .pfb file into a .pfa file.

-.SH SEE ALSO

-gs(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/pfbtopfa.1.man

@@ -1,0 +1,18 @@

+.\" $Id: pfbtopfa.1,v 1.38 2005/10/20 19:46:55 ray Exp $

+.TH PFBTOPFA 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+pfbtopfa \- Convert Postscript .pfb fonts to .pfa format using ghostscript

+.SH SYNOPSIS

+\fBpfbtopfa\fR \fIinput.pfb\fR \fI[output.pfa]\fR

+.SH DESCRIPTION

+This script invokes

+.BR gs (1)

+to convert a .pfb file into a .pfa file.

+.SH SEE ALSO

+gs(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/man/printafm.1

+++ /dev/null

@@ -1,19 +1,0 @@

-.\" $Id: printafm.1,v 1.37 2005/10/20 19:46:55 ray Exp $

-.TH PRINTAFM 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-printafm \- Print the metrics from a Postscript font in AFM format using ghostscript

-.SH SYNOPSIS

-\fBprintafm\fR \fIfontname\fR

-.SH DESCRIPTION

-This script invokes

-.BR gs (1)

-to print the metrics from a font in AFM format.

-Output goes to stdout.

-.SH SEE ALSO

-gs(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/printafm.1.man

@@ -1,0 +1,19 @@

+.\" $Id: printafm.1,v 1.37 2005/10/20 19:46:55 ray Exp $

+.TH PRINTAFM 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+printafm \- Print the metrics from a Postscript font in AFM format using ghostscript

+.SH SYNOPSIS

+\fBprintafm\fR \fIfontname\fR

+.SH DESCRIPTION

+This script invokes

+.BR gs (1)

+to print the metrics from a font in AFM format.

+Output goes to stdout.

+.SH SEE ALSO

+gs(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/man/ps2ascii.1

+++ /dev/null

@@ -1,31 +1,0 @@

-.\" $Id: ps2ascii.1,v 1.37 2005/10/20 19:46:55 ray Exp $

-.TH PS2ASCII 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

-.SH NAME

-ps2ascii \- Ghostscript translator from PostScript or PDF to ASCII

-.SH SYNOPSIS

-\fBps2ascii\fR [ \fIinput.ps\fR [ \fIoutput.txt\fR ] ]

-.br

-\fBps2ascii\fR \fIinput.pdf\fR [ \fIoutput.txt\fR ]

-.SH DESCRIPTION

-\fBps2ascii\fR uses \fBgs\fR(1) to extract ASCII text from

-\fBPostScript\fR(tm) or Adobe \fBPortable Document Format\fR (PDF)

-files. If no files are specified on the command line, \fBgs\fR reads from

-standard input; but PDF input must come from an explicitly-named file, not

-standard input.  If no output file is specified, the ASCII text is written

-to standard output.

-.PP

-\fBps2ascii\fR doesn't look at font encoding, and isn't very good at

-dealing with kerning, so for PostScript (but not currently PDF), you might

-consider \fBpstotext\fR (see below).

-.SH FILES

-Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

-system, from which you can get more details.

-.SH SEE ALSO

-pstotext(1), http://www.research.digital.com/SRC/virtualpaper/pstotext.html

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-David M. Jones <[email protected]> made substantial improvements

-to \fBps2ascii\fR.

--- /dev/null

+++ b/sys/src/cmd/gs/man/ps2ascii.1.man

@@ -1,0 +1,31 @@

+.\" $Id: ps2ascii.1,v 1.37 2005/10/20 19:46:55 ray Exp $

+.TH PS2ASCII 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

+.SH NAME

+ps2ascii \- Ghostscript translator from PostScript or PDF to ASCII

+.SH SYNOPSIS

+\fBps2ascii\fR [ \fIinput.ps\fR [ \fIoutput.txt\fR ] ]

+.br

+\fBps2ascii\fR \fIinput.pdf\fR [ \fIoutput.txt\fR ]

+.SH DESCRIPTION

+\fBps2ascii\fR uses \fBgs\fR(1) to extract ASCII text from

+\fBPostScript\fR(tm) or Adobe \fBPortable Document Format\fR (PDF)

+files. If no files are specified on the command line, \fBgs\fR reads from

+standard input; but PDF input must come from an explicitly-named file, not

+standard input.  If no output file is specified, the ASCII text is written

+to standard output.

+.PP

+\fBps2ascii\fR doesn't look at font encoding, and isn't very good at

+dealing with kerning, so for PostScript (but not currently PDF), you might

+consider \fBpstotext\fR (see below).

+.SH FILES

+Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

+system, from which you can get more details.

+.SH SEE ALSO

+pstotext(1), http://www.research.digital.com/SRC/virtualpaper/pstotext.html

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+David M. Jones <[email protected]> made substantial improvements

+to \fBps2ascii\fR.

--- a/sys/src/cmd/gs/man/ps2epsi.1

+++ /dev/null

@@ -1,66 +1,0 @@

-.\" $Id: ps2epsi.1,v 1.35 2005/10/20 19:46:55 ray Exp $

-.TH PS2EPSI 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

-.SH NAME

-ps2epsi \- generate conforming Encapsulated PostScript

-.SH SYNOPSIS

-\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ] \fB(Unix)\fR

-.br

-\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epi\fR ] \fB(DOS)\fR

-.SH DESCRIPTION

-\fBps2epsi\fR uses \fBgs\fR(1) to process a \fBPostScript\fR(tm) file and

-generate as output a new file which conforms to Adobe's \fBEncapsulated

-PostScript Interchange\fR (EPSI) format.  EPSI is a special form of

-encapsulated PostScript (EPS) which adds to the beginning of the file in

-the form of PostScript comments a bitmapped version of the final displayed

-page.  Programs which understand EPSI (usually word processors or DTP

-programs) can use this bitmap to give a preview version on screen of the

-PostScript.  The displayed quality is often not very good (e.g., low

-resolution, no colours), but the final printed version uses the real

-PostScript, and thus has the normal PostScript quality.

-.SH USAGE

-On Unix systems invoke \fBps2epsi\fR like this:

-.PP

-.br

-	\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ]

-.PP

-where "infile.ps" is the input file and "outfile.epsi" is the resulting

-EPSI file.  If the output filename is omitted, it is generated from the

-input filename.  When a standard extension (".ps", ".cps", ".eps" or

-".epsf") is used, it is replaced with the output extension ".epsi".  On

-DOS systems the command is:

-.PP

-.br

-	\fBps2epsi\fR \fIinfile.ps outfile.epi\fR

-.PP

-where "infile.ps" is the original PostScript file, and "outfile.epi"

-is the name of the output file.

-.SH LIMITATIONS

-Not every PostScript file can be encapsulated successfully, because there

-are restrictions on what PostScript constructs a correct encapsulated file

-may contain.  \fBps2epsi\fR does a little extra work to try to help

-encapsulation, and it automatically calculates the bounding box required

-for all encapsulated PostScript files, so most of the time it does a pretty

-good job. There are certain to be cases, however, where the encapsulation

-does not work because of the content of the original PostScript file.

-.SH COMPATIBILITY

-The \fBFramemaker\fR DTP system is one application which understands EPSI

-files, and \fBps2epsi\fR has been tested on a number of PostScript diagrams

-from a variety of sources, using Framemaker 3.0 on a Sun workstation.

-Framemaker on other platforms should be able to use these files, although I

-have not been able to test this.

-.SH FILES

-.TS

-tab(>);

-l l.

-ps2epsi>Unix shell script

-ps2epsi.bat>DOS batch file

-ps2epsi.ps>the Ghostscript program which does the work

-.TE

-.fi

-.SH SEE ALSO

-gs (1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-However, the content may be obsolete, or inconsistent with ps2epsi.txt.

-.SH AUTHOR

-George Cameron

--- /dev/null

+++ b/sys/src/cmd/gs/man/ps2epsi.1.man

@@ -1,0 +1,66 @@

+.\" $Id: ps2epsi.1,v 1.35 2005/10/20 19:46:55 ray Exp $

+.TH PS2EPSI 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

+.SH NAME

+ps2epsi \- generate conforming Encapsulated PostScript

+.SH SYNOPSIS

+\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ] \fB(Unix)\fR

+.br

+\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epi\fR ] \fB(DOS)\fR

+.SH DESCRIPTION

+\fBps2epsi\fR uses \fBgs\fR(1) to process a \fBPostScript\fR(tm) file and

+generate as output a new file which conforms to Adobe's \fBEncapsulated

+PostScript Interchange\fR (EPSI) format.  EPSI is a special form of

+encapsulated PostScript (EPS) which adds to the beginning of the file in

+the form of PostScript comments a bitmapped version of the final displayed

+page.  Programs which understand EPSI (usually word processors or DTP

+programs) can use this bitmap to give a preview version on screen of the

+PostScript.  The displayed quality is often not very good (e.g., low

+resolution, no colours), but the final printed version uses the real

+PostScript, and thus has the normal PostScript quality.

+.SH USAGE

+On Unix systems invoke \fBps2epsi\fR like this:

+.PP

+.br

+	\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ]

+.PP

+where "infile.ps" is the input file and "outfile.epsi" is the resulting

+EPSI file.  If the output filename is omitted, it is generated from the

+input filename.  When a standard extension (".ps", ".cps", ".eps" or

+".epsf") is used, it is replaced with the output extension ".epsi".  On

+DOS systems the command is:

+.PP

+.br

+	\fBps2epsi\fR \fIinfile.ps outfile.epi\fR

+.PP

+where "infile.ps" is the original PostScript file, and "outfile.epi"

+is the name of the output file.

+.SH LIMITATIONS

+Not every PostScript file can be encapsulated successfully, because there

+are restrictions on what PostScript constructs a correct encapsulated file

+may contain.  \fBps2epsi\fR does a little extra work to try to help

+encapsulation, and it automatically calculates the bounding box required

+for all encapsulated PostScript files, so most of the time it does a pretty

+good job. There are certain to be cases, however, where the encapsulation

+does not work because of the content of the original PostScript file.

+.SH COMPATIBILITY

+The \fBFramemaker\fR DTP system is one application which understands EPSI

+files, and \fBps2epsi\fR has been tested on a number of PostScript diagrams

+from a variety of sources, using Framemaker 3.0 on a Sun workstation.

+Framemaker on other platforms should be able to use these files, although I

+have not been able to test this.

+.SH FILES

+.TS

+tab(>);

+l l.

+ps2epsi>Unix shell script

+ps2epsi.bat>DOS batch file

+ps2epsi.ps>the Ghostscript program which does the work

+.TE

+.fi

+.SH SEE ALSO

+gs (1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+However, the content may be obsolete, or inconsistent with ps2epsi.txt.

+.SH AUTHOR

+George Cameron

--- a/sys/src/cmd/gs/man/ps2pdf.1

+++ /dev/null

@@ -1,53 +1,0 @@

-.\" $Id: ps2pdf.1,v 1.42 2005/10/20 19:46:55 ray Exp $

-.TH PS2PDF 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-ps2pdf \- Convert PostScript to PDF using ghostscript

-.br

-ps2pdf12 \- Convert PostScript to PDF\ 1.2 (Acrobat\ 3-and-later compatible) using ghostscript

-.br

-ps2pdf13 \- Convert PostScript to PDF\ 1.3 (Acrobat\ 4-and-later compatible) using ghostscript

-.SH SYNOPSIS

-\fBps2pdf\fR  [options...] {input.[e]ps|-} [output.pdf|-]

-.br

-\fBps2pdf12\fR  [options...] {input.[e]ps|-} [output.pdf|-]

-.br

-\fBps2pdf13\fR  [options...] {input.[e]ps|-} [output.pdf|-]

-.SH DESCRIPTION

-The

-.B ps2pdf

-scripts are work-alikes for nearly all the functionality (but not the

-user interface) of Adobe's Acrobat(TM) Distiller(TM) product: they

-convert PostScript files to Portable Document Format (PDF) files.

-.PP

-The three scripts differ as follows:

-.IP -

-.B ps2pdf12

-will always produce PDF 1.2 output (Acrobat 3-and-later compatible).

-.IP -

-.B ps2pdf13

-will always produce PDF 1.3 output (Acrobat 4-and-later compatible).

-.IP -

-.B ps2pdf

-per se currently produces PDF 1.2 output (Acrobat 3-and-later

-compatible). However, this may change in the future. If you care about

-the compatibility level of the output, use

-.B ps2pdf12

-or

-.BR ps2pdf13 ,

-or use the

-.B \-dCompatibility=1.x

-switch in the command line.

-.PP

-There are some limitations in

-.BR ps2pdf 's

-conversion. See the HTML documentation for more information.

-.SH SEE ALSO

-gs(1), ps2pdfwr(1),

-.br

-Ps2pdf.htm in the Ghostscript documentation

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/ps2pdf.1.man

@@ -1,0 +1,53 @@

+.\" $Id: ps2pdf.1,v 1.42 2005/10/20 19:46:55 ray Exp $

+.TH PS2PDF 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+ps2pdf \- Convert PostScript to PDF using ghostscript

+.br

+ps2pdf12 \- Convert PostScript to PDF\ 1.2 (Acrobat\ 3-and-later compatible) using ghostscript

+.br

+ps2pdf13 \- Convert PostScript to PDF\ 1.3 (Acrobat\ 4-and-later compatible) using ghostscript

+.SH SYNOPSIS

+\fBps2pdf\fR  [options...] {input.[e]ps|-} [output.pdf|-]

+.br

+\fBps2pdf12\fR  [options...] {input.[e]ps|-} [output.pdf|-]

+.br

+\fBps2pdf13\fR  [options...] {input.[e]ps|-} [output.pdf|-]

+.SH DESCRIPTION

+The

+.B ps2pdf

+scripts are work-alikes for nearly all the functionality (but not the

+user interface) of Adobe's Acrobat(TM) Distiller(TM) product: they

+convert PostScript files to Portable Document Format (PDF) files.

+.PP

+The three scripts differ as follows:

+.IP -

+.B ps2pdf12

+will always produce PDF 1.2 output (Acrobat 3-and-later compatible).

+.IP -

+.B ps2pdf13

+will always produce PDF 1.3 output (Acrobat 4-and-later compatible).

+.IP -

+.B ps2pdf

+per se currently produces PDF 1.2 output (Acrobat 3-and-later

+compatible). However, this may change in the future. If you care about

+the compatibility level of the output, use

+.B ps2pdf12

+or

+.BR ps2pdf13 ,

+or use the

+.B \-dCompatibility=1.x

+switch in the command line.

+.PP

+There are some limitations in

+.BR ps2pdf 's

+conversion. See the HTML documentation for more information.

+.SH SEE ALSO

+gs(1), ps2pdfwr(1),

+.br

+Ps2pdf.htm in the Ghostscript documentation

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/man/ps2pdfwr.1

+++ /dev/null

@@ -1,31 +1,0 @@

-.\" $Id: ps2pdfwr.1,v 1.41 2005/10/20 19:46:55 ray Exp $

-.TH PS2PDFWR 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-ps2pdfwr \- Convert PostScript to PDF without specifying CompatibilityLevel, using ghostscript

-.SH SYNOPSIS

-\fBps2pdfwr\fR  [options...] {input.[e]ps|-} [output.pdf|-]

-.SH DESCRIPTION

-This wrapper script invokes

-.BR gs (1)

-with following arguments

-.ce

-.B -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite

-as well as the appropriate

-.B -dOutputFile

-argument, all preceded and followed by any command-line arguments. Finally, the security option

-.B -dSAFER

-is prepended before all the other options.

-The version-specific

-.B ps2pdf

-scripts all invoke this one with the addition of the respective compatibility level option.

-.SH SEE ALSO

-gs(1), ps2pdf(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/ps2pdfwr.1.man

@@ -1,0 +1,31 @@

+.\" $Id: ps2pdfwr.1,v 1.41 2005/10/20 19:46:55 ray Exp $

+.TH PS2PDFWR 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+ps2pdfwr \- Convert PostScript to PDF without specifying CompatibilityLevel, using ghostscript

+.SH SYNOPSIS

+\fBps2pdfwr\fR  [options...] {input.[e]ps|-} [output.pdf|-]

+.SH DESCRIPTION

+This wrapper script invokes

+.BR gs (1)

+with following arguments

+.ce

+.B -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite

+as well as the appropriate

+.B -dOutputFile

+argument, all preceded and followed by any command-line arguments. Finally, the security option

+.B -dSAFER

+is prepended before all the other options.

+The version-specific

+.B ps2pdf

+scripts all invoke this one with the addition of the respective compatibility level option.

+.SH SEE ALSO

+gs(1), ps2pdf(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/man/ps2ps.1

+++ /dev/null

@@ -1,33 +1,0 @@

-.\" $Id: ps2ps.1,v 1.44 2005/10/20 19:46:55 ray Exp $

-.TH PS2PS 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

-.SH NAME

-ps2ps, eps2eps \- Ghostscript PostScript "distiller"

-.SH SYNOPSIS

-\fBps2ps\fR [ \fIoptions\fR ] \fIinput.ps output.ps\fR

-.br

-\fBeps2eps\fR [ \fIoptions\fR ] \fIinput.eps output.eps\fR

-.SH DESCRIPTION

-\fBps2ps\fR uses \fIgs\fR(1) to convert \fBPostScript\fR(tm) file

-"input.ps" to simpler, normalized and (usually) faster PostScript in

-"output.ps".  Normally the output is allowed to use PostScript Level 2

-or Level 3 constructs, but the \fB\-dLanguageLevel=1\fR option restricts

-the output to Level 1.

-.PP

-\fBeps2eps\fR performs the equivalent optimization for Encapsulated

-PostScript (EPS) files.

-.PP

-Both accept any general Ghostscript command line options, and

-respectively options specific to the pswrite and epswrite devices.

-.SH FILES

-Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

-system, from which you can get more details.

-.SH BUGS

-The pswrite device used by both \fBps2ps\fR and \fBeps2eps\fR produces much

-lower level output than is desirable. Use with caution.

-.SH SEE ALSO

-ps2pdf(1), ps2ascii(1), ps2epsi(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software are the primary maintainers of Ghostscript.

-Please send bug reports to <[email protected]>.

--- /dev/null

+++ b/sys/src/cmd/gs/man/ps2ps.1.man

@@ -1,0 +1,33 @@

+.\" $Id: ps2ps.1,v 1.44 2005/10/20 19:46:55 ray Exp $

+.TH PS2PS 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*-

+.SH NAME

+ps2ps, eps2eps \- Ghostscript PostScript "distiller"

+.SH SYNOPSIS

+\fBps2ps\fR [ \fIoptions\fR ] \fIinput.ps output.ps\fR

+.br

+\fBeps2eps\fR [ \fIoptions\fR ] \fIinput.eps output.eps\fR

+.SH DESCRIPTION

+\fBps2ps\fR uses \fIgs\fR(1) to convert \fBPostScript\fR(tm) file

+"input.ps" to simpler, normalized and (usually) faster PostScript in

+"output.ps".  Normally the output is allowed to use PostScript Level 2

+or Level 3 constructs, but the \fB\-dLanguageLevel=1\fR option restricts

+the output to Level 1.

+.PP

+\fBeps2eps\fR performs the equivalent optimization for Encapsulated

+PostScript (EPS) files.

+.PP

+Both accept any general Ghostscript command line options, and

+respectively options specific to the pswrite and epswrite devices.

+.SH FILES

+Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your

+system, from which you can get more details.

+.SH BUGS

+The pswrite device used by both \fBps2ps\fR and \fBeps2eps\fR produces much

+lower level output than is desirable. Use with caution.

+.SH SEE ALSO

+ps2pdf(1), ps2ascii(1), ps2epsi(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software are the primary maintainers of Ghostscript.

+Please send bug reports to <[email protected]>.

--- a/sys/src/cmd/gs/man/wftopfa.1

+++ /dev/null

@@ -1,20 +1,0 @@

-.\" $Id: wftopfa.1,v 1.37 2005/10/20 19:46:55 ray Exp $

-.TH WFTOPFA 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

-.SH NAME

-wftopfa \- Convert a Wadalab base font to Postscript .PFA (or .PFB)

-format using ghostscript

-.SH SYNOPSIS

-\fBwftopfa\fR \fIfontname\fR

-.SH DESCRIPTION

-This script invokes

-.BR gs (1)

-to convert a Wadalab base font to Postscript .PFA (or .PFB)

-format.

-.SH SEE ALSO

-gs(1)

-.SH VERSION

-This document was last revised for Ghostscript version 8.53.

-.SH AUTHOR

-artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

-primary maintainers of Ghostscript.

-This manpage by George Ferguson.

--- /dev/null

+++ b/sys/src/cmd/gs/man/wftopfa.1.man

@@ -1,0 +1,20 @@

+.\" $Id: wftopfa.1,v 1.37 2005/10/20 19:46:55 ray Exp $

+.TH WFTOPFA 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*-

+.SH NAME

+wftopfa \- Convert a Wadalab base font to Postscript .PFA (or .PFB)

+format using ghostscript

+.SH SYNOPSIS

+\fBwftopfa\fR \fIfontname\fR

+.SH DESCRIPTION

+This script invokes

+.BR gs (1)

+to convert a Wadalab base font to Postscript .PFA (or .PFB)

+format.

+.SH SEE ALSO

+gs(1)

+.SH VERSION

+This document was last revised for Ghostscript version 8.53.

+.SH AUTHOR

+artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the

+primary maintainers of Ghostscript.

+This manpage by George Ferguson.

--- a/sys/src/cmd/gs/zlib/zlib.3

+++ /dev/null

@@ -1,159 +1,0 @@

-.TH ZLIB 3 "3 October 2004"

-.SH NAME

-zlib \- compression/decompression library

-.SH SYNOPSIS

-[see

-.I zlib.h

-for full description]

-.SH DESCRIPTION

-The

-.I zlib

-library is a general purpose data compression library.

-The code is thread safe.

-It provides in-memory compression and decompression functions,

-including integrity checks of the uncompressed data.

-This version of the library supports only one compression method (deflation)

-but other algorithms will be added later

-and will have the same stream interface.

-.LP

-Compression can be done in a single step if the buffers are large enough

-(for example if an input file is mmap'ed),

-or can be done by repeated calls of the compression function.

-In the latter case,

-the application must provide more input and/or consume the output

-(providing more output space) before each call.

-.LP

-The library also supports reading and writing files in

-.IR gzip (1)

-(.gz) format

-with an interface similar to that of stdio.

-.LP

-The library does not install any signal handler.

-The decoder checks the consistency of the compressed data,

-so the library should never crash even in case of corrupted input.

-.LP

-All functions of the compression library are documented in the file

-.IR zlib.h .

-The distribution source includes examples of use of the library

-in the files

-.I example.c

-and

-.IR minigzip.c .

-.LP

-Changes to this version are documented in the file

-.I ChangeLog

-that accompanies the source,

-and are concerned primarily with bug fixes and portability enhancements.

-.LP

-A Java implementation of

-.I zlib

-is available in the Java Development Kit 1.1:

-.IP

-http://www.javasoft.com/products/JDK/1.1/docs/api/Package-java.util.zip.html

-.LP

-A Perl interface to

-.IR zlib ,

-written by Paul Marquess ([email protected]),

-is available at CPAN (Comprehensive Perl Archive Network) sites,

-including:

-.IP

-http://www.cpan.org/modules/by-module/Compress/

-.LP

-A Python interface to

-.IR zlib ,

-written by A.M. Kuchling ([email protected]),

-is available in Python 1.5 and later versions:

-.IP

-http://www.python.org/doc/lib/module-zlib.html

-.LP

-A

-.I zlib

-binding for

-.IR tcl (1),

-written by Andreas Kupries ([email protected]),

-is availlable at:

-.IP

-http://www.westend.com/~kupries/doc/trf/man/man.html

-.LP

-An experimental package to read and write files in .zip format,

-written on top of

-.I zlib

-by Gilles Vollant ([email protected]),

-is available at:

-.IP

-http://www.winimage.com/zLibDll/unzip.html

-and also in the

-.I contrib/minizip

-directory of the main

-.I zlib

-web site.

-.SH "SEE ALSO"

-The

-.I zlib

-web site can be found at either of these locations:

-.IP

-http://www.zlib.org

-.br

-http://www.gzip.org/zlib/

-.LP

-The data format used by the zlib library is described by RFC

-(Request for Comments) 1950 to 1952 in the files:

-.IP

-http://www.ietf.org/rfc/rfc1950.txt (concerning zlib format)

-.br

-http://www.ietf.org/rfc/rfc1951.txt (concerning deflate format)

-.br

-http://www.ietf.org/rfc/rfc1952.txt (concerning gzip format)

-.LP

-These documents are also available in other formats from:

-.IP

-ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html

-.LP

-Mark Nelson ([email protected]) wrote an article about

-.I zlib

-for the Jan. 1997 issue of  Dr. Dobb's Journal;

-a copy of the article is available at:

-.IP

-http://dogma.net/markn/articles/zlibtool/zlibtool.htm

-.SH "REPORTING PROBLEMS"

-Before reporting a problem,

-please check the

-.I zlib

-web site to verify that you have the latest version of

-.IR zlib ;

-otherwise,

-obtain the latest version and see if the problem still exists.

-Please read the

-.I zlib

-FAQ at:

-.IP

-http://www.gzip.org/zlib/zlib_faq.html

-.LP

-before asking for help.

-Send questions and/or comments to [email protected],

-or (for the Windows DLL version) to Gilles Vollant ([email protected]).

-.SH AUTHORS

-Version 1.2.2

-Copyright (C) 1995-2004 Jean-loup Gailly ([email protected])

-and Mark Adler ([email protected]).

-.LP

-This software is provided "as-is,"

-without any express or implied warranty.

-In no event will the authors be held liable for any damages

-arising from the use of this software.

-See the distribution directory with respect to requirements

-governing redistribution.

-The deflate format used by

-.I zlib

-was defined by Phil Katz.

-The deflate and

-.I zlib

-specifications were written by L. Peter Deutsch.

-Thanks to all the people who reported problems and suggested various

-improvements in

-.IR zlib ;

-who are too numerous to cite here.

-.LP

-UNIX manual page by R. P. C. Rodgers,

-U.S. National Library of Medicine ([email protected]).

-.\" end of man page

--- /dev/null

+++ b/sys/src/cmd/gs/zlib/zlib.3.man

@@ -1,0 +1,159 @@

+.TH ZLIB 3 "3 October 2004"

+.SH NAME

+zlib \- compression/decompression library

+.SH SYNOPSIS

+[see

+.I zlib.h

+for full description]

+.SH DESCRIPTION

+The

+.I zlib

+library is a general purpose data compression library.

+The code is thread safe.

+It provides in-memory compression and decompression functions,

+including integrity checks of the uncompressed data.

+This version of the library supports only one compression method (deflation)

+but other algorithms will be added later

+and will have the same stream interface.

+.LP

+Compression can be done in a single step if the buffers are large enough

+(for example if an input file is mmap'ed),

+or can be done by repeated calls of the compression function.

+In the latter case,

+the application must provide more input and/or consume the output

+(providing more output space) before each call.

+.LP

+The library also supports reading and writing files in

+.IR gzip (1)

+(.gz) format

+with an interface similar to that of stdio.

+.LP

+The library does not install any signal handler.

+The decoder checks the consistency of the compressed data,

+so the library should never crash even in case of corrupted input.

+.LP

+All functions of the compression library are documented in the file

+.IR zlib.h .

+The distribution source includes examples of use of the library

+in the files

+.I example.c

+and

+.IR minigzip.c .

+.LP

+Changes to this version are documented in the file

+.I ChangeLog

+that accompanies the source,

+and are concerned primarily with bug fixes and portability enhancements.

+.LP

+A Java implementation of

+.I zlib

+is available in the Java Development Kit 1.1:

+.IP

+http://www.javasoft.com/products/JDK/1.1/docs/api/Package-java.util.zip.html

+.LP

+A Perl interface to

+.IR zlib ,

+written by Paul Marquess ([email protected]),

+is available at CPAN (Comprehensive Perl Archive Network) sites,

+including:

+.IP

+http://www.cpan.org/modules/by-module/Compress/

+.LP

+A Python interface to

+.IR zlib ,

+written by A.M. Kuchling ([email protected]),

+is available in Python 1.5 and later versions:

+.IP

+http://www.python.org/doc/lib/module-zlib.html

+.LP

+A

+.I zlib

+binding for

+.IR tcl (1),

+written by Andreas Kupries ([email protected]),

+is availlable at:

+.IP

+http://www.westend.com/~kupries/doc/trf/man/man.html

+.LP

+An experimental package to read and write files in .zip format,

+written on top of

+.I zlib

+by Gilles Vollant ([email protected]),

+is available at:

+.IP

+http://www.winimage.com/zLibDll/unzip.html

+and also in the

+.I contrib/minizip

+directory of the main

+.I zlib

+web site.

+.SH "SEE ALSO"

+The

+.I zlib

+web site can be found at either of these locations:

+.IP

+http://www.zlib.org

+.br

+http://www.gzip.org/zlib/

+.LP

+The data format used by the zlib library is described by RFC

+(Request for Comments) 1950 to 1952 in the files:

+.IP

+http://www.ietf.org/rfc/rfc1950.txt (concerning zlib format)

+.br

+http://www.ietf.org/rfc/rfc1951.txt (concerning deflate format)

+.br

+http://www.ietf.org/rfc/rfc1952.txt (concerning gzip format)

+.LP

+These documents are also available in other formats from:

+.IP

+ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html

+.LP

+Mark Nelson ([email protected]) wrote an article about

+.I zlib

+for the Jan. 1997 issue of  Dr. Dobb's Journal;

+a copy of the article is available at:

+.IP

+http://dogma.net/markn/articles/zlibtool/zlibtool.htm

+.SH "REPORTING PROBLEMS"

+Before reporting a problem,

+please check the

+.I zlib

+web site to verify that you have the latest version of

+.IR zlib ;

+otherwise,

+obtain the latest version and see if the problem still exists.

+Please read the

+.I zlib

+FAQ at:

+.IP

+http://www.gzip.org/zlib/zlib_faq.html

+.LP

+before asking for help.

+Send questions and/or comments to [email protected],

+or (for the Windows DLL version) to Gilles Vollant ([email protected]).

+.SH AUTHORS

+Version 1.2.2

+Copyright (C) 1995-2004 Jean-loup Gailly ([email protected])

+and Mark Adler ([email protected]).

+.LP

+This software is provided "as-is,"

+without any express or implied warranty.

+In no event will the authors be held liable for any damages

+arising from the use of this software.

+See the distribution directory with respect to requirements

+governing redistribution.

+The deflate format used by

+.I zlib

+was defined by Phil Katz.

+The deflate and

+.I zlib

+specifications were written by L. Peter Deutsch.

+Thanks to all the people who reported problems and suggested various

+improvements in

+.IR zlib ;

+who are too numerous to cite here.

+.LP

+UNIX manual page by R. P. C. Rodgers,

+U.S. National Library of Medicine ([email protected]).

+.\" end of man page