<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC 
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd" [
<!ENTITY homepage      "http://catb.org/~esr/">
<!ENTITY email         "esr@thyrsus.com">
]>
<article><title>The GIFLIB Library</title>

<articleinfo>

<author>
  <firstname>Eric</firstname>
  <othername>Steven</othername>
  <surname>Raymond</surname>
  <affiliation>
    <orgname><ulink url="&homepage;">
    Thyrsus Enterprises</ulink></orgname> 
    <address>
    <email>&email;</email>
    </address>
  </affiliation>
</author>
<copyright>
  <year>2012</year>
  <holder role="mailto:&email;">Eric S. Raymond</holder> 
</copyright>

</articleinfo>

<!--
Gershon Elber, May 1991
Eric S. Raymond, Sep 1992
Toshio Kuratomi, May 2004
-->

<sect1><title>Introduction</title>

<para>The Graphics Interchange Format(c) is the Copyright property of
CompuServe Incorporated.  GIF(sm) is a Service Mark property of CompuServe
Incorporated.</para>

<para>Gershon wrote: "This library was written because I couldn't find
anything similar and I wanted one.  I was inspired by the RLE Utah tool kit,
which I hoped to port to an IBM PC, but found it to be too machine specific,
and its compression ratio too low.  I compromised on the GIF format, but I am
not sure how long 8 bits per pixel will be enough."</para>

<para>This document explains the GIF library code in directory `lib'.  The
code is collected into libgif.a which is used in all the utilities in
`util'.  It can be used in any application needs to read/write the GIF
file format.  This document does <emphasis>not</emphasis> explain the GIF file
format and assumes you know it, at least to the level of the GIF file
structure.</para>

<para>When a GIF file is opened, a GIF file descriptor is created which
is a pointer to GifFileType structure as follows:</para>

<programlisting>
typedef struct GifFileType {
    int SWidth, SHeight,			       /* Screen dimensions. */
	SColorResolution, 		 /* How many colors can we generate? */
	SBackGroundColor;		/* I hope you understand this one... */
    ColorMapObject *SColorMap;			      /* NULL if not exists. */
    int ImageCount;				  /* Number of current image */
    GifImageDesc Image;			   /* Block describing current image */
    struct SavedImage *SavedImages;	/* Use this to accumulate file state */
    VoidPtr Private;	  /* The regular user should not mess with this one! */
} GifFileType;
</programlisting>

<para>This structure was copied from gif_lib.h - the header file for the GIF
library.  Any application program that uses the libgif.a library should
include it.  Members beginning with S refer to GIF Screen; others hold
properties of the current image (a GIF file may have more than one image)
or point to allocated store used by various routines.</para>

<para>The user almost never writes into this structure (exception: it may
occasionally useful to alter things in the SavedImages array), but can read
any of these items at any time it is valid (image information is invalid
until first image was read).</para>

<para>As the library needs to keep its own internal data, a Private pointer
to hidden data is included. Applications should ignore this item.</para>

<para>The library has no static data. This means that it is fully reentrant
and any number of GIF files (up to memory limits) can be opened for
read/write. Instead of the static data, internal structure pointed by the
Private pointer is used.</para>

<para>The library allocates its own memory dynamically, on opening of files,
and releases that once closed.  The user is never required to allocate
any memory for any of the functions of this library nor to free them
directly.</para>

<para>In order to reduce disk access, the file buffer is increased to
FILE_BUFFER_SIZE (defined in gif_lib.h).</para>

<para>Here is a module summary:</para>

<variablelist>
<varlistentry>
<term>egif_lib.c</term>
<listitem>
<para>Encoding routines, all prefixed with E.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>dgif_lib.c</term>
<listitem>
<para>Decoding routines, all prefixed with D.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>gifalloc.c</term>
<listitem>
<para>Routines for colormap handling and GIF record allocation.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>gif_font.c</term>
<listitem>
<para>The 8x8 font table for the GIF utility font.</para>
</listitem>
</varlistentry>
</variablelist>

<para>The library includes a sixth file of hash-function code which is accessed
internally only.</para>

<para>Most of the routines return GIF_ERROR (see gif_lib.h) if something
went wrong, GIF_OK otherwise.  After an error return, the code in the
gif_err.c module can be used to do something about it.</para>

<para>In addition, a module to parse command line arguments is supplied.
This module is called getarg.c and its headers are in getarg.h.  See the header
of getarg.c for details on its usage.</para>

</sect1>
<sect1><title>Decoding (dgif_lib.c)</title>

<para>The following functions are used to set up input from a GIF:</para>

<programlisting id="DGifOpenFileName">
GifFileType *DGifOpenFileName(char *GifFileName)
</programlisting>

<para>Open a new GIF file using the given GifFileName, and read its Screen
information.</para>

<para>If any error occurs, NULL is returned and the error handler can be
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<programlisting id="DGifOpenFileHandle">
GifFileType *DGifOpenFileHandle(int GifFileHandle)
</programlisting>

<para>Open a new GIF file using the given GifFileHandle, and read its Screen
information.</para>

<para>If any error occurs, NULL is returned and the error handler can be 
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<para>Once you have acquired a handle on a GIF, there are two ways to
read it in.  The high-level function</para>

<programlisting id="DGifSlurp">
int DGifSlurp(GifFileType)
</programlisting>

<para>reads the rest of a complete (possibly multi-image) GIF file from the
indicated file handle into in-core allocated structures.  It returns
GIF_OK on success, GIF_ERROR on failure.</para>

<para>Once you have done this, all image, raster, and extension-block
data in the GIF is accessable in the SavedImages member (see the
structures in gif_lib.h).  When you have modified the image to taste,
write it out with EGifSpew().</para>

<para>If you are handling large images on a memory-limited machine, you may need
to use the following functions for sequential read.</para>

<programlisting id="DGifGetScreenDesc">
int DGifGetScreenDesc(GifFileType *GifFile)
</programlisting>

<para>Reads the screen information into the GifFile structure. Note this
routine is automatically called once a file is opened, and therefore
usually need not be called explicitly.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifGetRecordType">
int DGifGetRecordType(GifFileType *GifFile, GifRecordType *GifType)
</programlisting>

<para>As the GIF file can have different records in arbitrary order, this
routine should be called once the file was open to detect the next
record type, and act upon it.  It can return these types in GifType:</para>

<variablelist>
<varlistentry>
<term>1. UndefinedRecordType </term>
<listitem>
<para>something is wrong!</para>
</listitem>
</varlistentry>

<varlistentry>
<term>2. ScreenDescRecordType </term>
<listitem>
<para>screen information.  As the screen info is automatically read in when the file is open, this should not happen.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>3. ImageDescRecordType </term>
<listitem>
<para> next record is an image descriptor.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>4. ExtensionRecordType</term>
<listitem>
<para> next record is extension block.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>5. TerminateRecordType</term>
<listitem>
<para>last record reached, can close the file.</para>
</listitem>
</varlistentry>
</variablelist>

<para>The first two types can usually be ignored. The function
returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifGetImageDesc">
int DGifGetImageDesc(GifFileType *GifFile)
</programlisting>

<para>Reads image information into the GifFile structure.
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifGetLine">
int DGifGetLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)
</programlisting>

<para>Load a block of pixels from the GIF file.  The line can be
of any length.  More than that, this routine may be interleaved with
DGifGetPixel until all pixels have been read.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting>
int DGifGetPixel(GifFileType *GifFile, PixelType GifPixel)
</programlisting>

<para>Loads one pixel from the GIF file.  This routine may be interleaved
with <link linkend="DGifGetLine">DGifGetLine()</link>, until all pixels are
read.  Because of the overhead per each call, use of this routine is
not recommended.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifGetComment">
int DGifGetComment(GifFileType *GifFile, char *GifComment)
</programlisting>

<para>Load a comment from the GIF file.  Because DGifGetRecordType will
only tell if the record is of type extension, this routine should be
called iff it is known %100 that is must be a comment.</para>

<para>For the definition of a comment, see <link
linkend="EGifPutComment">EGifPutComment()</link>.  Returns GIF_ERROR
if something went wrong, GIF_OK otherwise.</para>

<programlisting>
int DGifGetExtension(
        GifFileType *GifFile,
        int *GifExtCode,
        ByteType **GifExtension)
</programlisting>

<para>Loads an extension block from the GIF file.  Extension blocks
are optional in GIF files.  This routine should be followed by
<link linkend="DGifGetExtensionNext">DGifGetExtensionNext</link>.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<para><programlisting id="DGifGetExtensionNext">
int DGifGetExtensionNext(GifFileType *GifFile, ByteType **GifExtension)
</programlisting>

As extensions may contain more than one block, use this routine to
continue after DGifGetExtension, until *GifExtension is NULL.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting>
int DGifGetCode(
        GifFileType *GifFile, 
        int *GifCodeSize, ByteType **GifCodeBlock)
</programlisting>

<para>It sometimes may be desired to read the compressed code as is
without decoding it.  This routine does exactly that (with
DGifGetCodeNext), and can be used instead of DGifGetLine.</para>

<para>This compressed code information can be written out using the
EGifPutCode/EGifPutCodeNext sequence (see gifpos.c for example).
Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifGetCodeNext">
int DGifGetCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)
</programlisting>

<para>See DGifGetCode above.</para>
	  
<programlisting id="DGifGetLZCodes">
int DGifGetLZCodes(GifFileType *GifFile, int *GifCode)
</programlisting>

<para>This routine can be called instead of DGifGetLine/DGifGetPixel or
DGifGetCode/DGifGetCodeNext to get the 12 bits LZ codes of the images.
It will be used mainly for debugging purposes (see GifText.c for
example).</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="DGifCloseFile">
int DGifCloseFile(GifFileType *GifFile)
</programlisting>

<para>Close GIF file and free all memory allocated for it. GifFile should
not be used after this routine has been called.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<para>There is one more way to read from a GIF file: through a
function hook. Initialize with </para>

<programlisting id="DGifOpen">
GifFileType *DGifOpen(void *userPtr, InputFunc readFunc)
</programlisting>

<para>and see the library header file for the type of InputFunc.</para>

</sect1>
<sect1><title>Encoding (egif_lib.c)</title>

<para>There are two ways to write out a GIF.  The high-level function</para>

<programlisting id="EGifSpew">
int EGifSpew(GifFileType *GifFile, int GifFileHandle)
</programlisting>

<para>Writes a complete (possibly multi-image) GIF file to the indicated file
handle from in-core allocated structures created by a previous DGifSlurp()
or equivalent operations.  Its arguments are a GIF file descriptor (as
above) and an ordinary output file descriptor.</para>

<para>The file is written with a GIF87 stamp unless it contains one of the four
special extension blocks defined in GIF89, in which case it is written
with a GIF89 stamp.</para>

<para>If you are handling large images on a memory-limited machine, you may need
to use the following functions for sequential write.</para>

<programlisting id="EGifOpenFileName">
GifFileType *EGifOpenFileName(char *GifFileName, bool GifTestExistance)
</programlisting>

<para>Open a new GIF file using the given GifFileName.  If GifTestExistance
is TRUE, and file exists, the file is not destroyed, and NULL
returned.</para>

<para>If any error occurs, NULL is returned and the error handler can be
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<programlisting id="EGifOpenFileHandle">
GifFileType *EGifOpenFileHandle(int GifFileHandle)
</programlisting>

<para>Open a new GIF file using the given GifFileHandle.</para>

<para>If any error occurs, NULL is returned and the error handler can be
used to get the exact error (see gif_err.c).</para>

<para>The file is opened in binary mode, and its buffer size is set to
FILE_BUFFER_SIZE bytes.</para>

<programlisting id="EGifSetGifVersion">
void EGifSetGifVersion(char *Version)
</programlisting>

<para>Sets the GIF version of all files opened, until another call to this
routine is made.  Version is a 3 characters string of the form "87a"
or "89a".  No test is made to validate this string. </para>

<para>Before this call is made, or after it has been made with a
zero-length string as argument, the library computes the right version
to use by looking at the GIF's extension blocks. (Older versions of
the library defaulted to GIF87)</para>

<programlisting>
int EGifPutScreenDesc(GifFileType *GifFile,
        int GifWidth, int GifHeight,
        int GifColorRes, int GifBackGround,
        ColorMapObject *GifColorMap)
</programlisting>

<para>Update the GifFile Screen parameters, in GifFile structure and in
the real file.  If error occurs, returns GIF_ERROR (see gif_lib.h),
otherwise GIF_OK.</para>

<para>This routine should be called immediately after the GIF file was
opened.</para>

<programlisting>
int EGifPutImageDesc(GifFileType *GifFile,
        int GifLeft, int GifTop,
        int Width, int GifHeight,
        bool GifInterlace,
        ColorMapObject *GifColorMap)
</programlisting>

<para>Update GifFile Image parameters, in GifFile structure and in the real
file. if error occurs returns GIF_ERROR (see gif_lib.h), otherwise
GIF_OK.</para>

<para>This routine should be called each time a new image must be
dumped to the file.</para>

<programlisting id="EGifPutLine">
int EGifPutLine(GifFileType *GifFile, PixelType *GifLine, int GifLineLen)
</programlisting>

<para>Dumps a block of pixels out to the GIF file.  The slab can be of
any length.  More than that, this routine may be interleaved with
<link linkend="EGifPutPixel">EGifPutPixel()</link>, until all pixels
have been sent.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="EGifPutPixel">
int EGifPutPixel(GifFileType *GifFile, PixelType GifPixel)
</programlisting>

<para>Dumps one pixel to the GIF file.  This routine may be interleaved with
<link linkend="EGifPutLine">EGifPutLine()</link>, until all pixels were sent.
Because of the overhead for each call, use of this routine is not
recommended.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="EGifPutComment">
int EGifPutComment(GifFileType *GifFile, char *GifComment)
</programlisting>

<para>Uses extension GIF records to save a string as a comment is the file.
The extension code is 'C' (for Comment).</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="EGifPutExtension">
int EGifPutExtension(
        GifFileType *GifFile,
        int GifExtCode,
        int GifExtLen,
        void *GifExtension)
</programlisting>

<para>Dumps the given extension block into the GIF file. Extension blocks
are optional in GIF file. Extension blocks of more than 255 bytes or
more than one block are not supported in this function.  Please use
EGifPutExtensionFirst, EGifPutExtensionNext, and EGifPutExtensionLast
if your extension blocks may fall into this category.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="EGifPutExtensionFirst">
int EGifPutExtensionFirst(
        GifFileType * GifFile,
        int GifExtCode,
        int GifExtLen,
        const VoidPtr GifExtension)
</programlisting>

<para>Dumps the beginning of a GIF extension block to a GIF file.
Extension blocks are optional in GIF files.  This function outputs the
meta information necessary to a GIF extension block and the extension
data described in the GifExtension argument.</para>

<para>Further blocks of the GIF Extension should be dumped using
EGifPutExtensionNext.  When finished with this extension block,
EGifPutExtensionLast should be called to output the block termination.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="EGifPutExtensionNext">
int EGifPutExtensionNext(
        GifFileType * GifFile,
        int GifExtCode,
        int GifExtLen,
        const VoidPtr GifExtension)
</programlisting>

<para>Dumps a subblock of a GIF extension to a GIF File.  Extension
blocks are optional in GIF files.  This function will write the
Extension Data in GifExtension to the file as a subblock of the
preceding Extension Block.  Repeat calling of this function until all
data subblocks have been output.</para>

<para>Note that EGifPutExtensionFirst needs to be called before any
calls to this function.  EGifPutExtensionLast should be called to
finish the Extension block after all data subblocks have been
output.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="EGifPutExtensionLast">
int EGifPutExtensionLast(
        GifFileType * GifFile,
        int GifExtCode,
        int GifExtLen,
        const VoidPtr GifExtension)
</programlisting>

<para>Dumps an optional GIF extension data subblock and the GIF extension block
terminator to a GIF File.  Extension blocks are optional in GIF files.  This
function will write the Extension Data in GifExtension to the file as a
subblock of the preceding Extension Block.  Then it will output the GIF
extension block terminator to end the current Extension block.  As a special
case, if GifExtLen is zero, the function will assume there isn't another
data block to output and will simply write the block terminator.</para>

<para>Note that a call to EGifPutExtensionFirst is needed to open the GIF
Extension Block prior to calling this function.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="EGifPutCode">
int EGifPutCode(
        GifFileType *GifFile,
        int *GifCodeSize,
        ByteType **GifCodeBlock)
</programlisting>

<para>It sometimes may be desired to write the compressed code as is
without decoding it.  For example a filter for a GIF file that change
only screen size (GifPos), does not need the exact pixel values.
Piping out the compressed image as is makes this process much
faster.</para>

<para>This routine does exactly that (with EGifPutCodeNext), and can be
used instead of EGifPutLine.  You'll usually use this with the
DGifGetCode/DgifGetCodeNext routines, which reads the compressed
code, while EGifPutCode/EGifPutCodeNext write it out.  See gifpos.c
for example.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<programlisting id="EGifPutCodeNext">
int EGifPutCodeNext(GifFileType *GifFile, ByteType **GifCodeBlock)
</programlisting>

<para>See EGifPutCode above.</para>

<programlisting id="EGifCloseFile">
int EGifCloseFile(GifFileType *GifFile)
</programlisting>

<para>Close a GIF file and free all memory allocated for it.  gif-file
should not be used, once this routine has been called.</para>

<para>Returns GIF_ERROR if something went wrong, GIF_OK otherwise.</para>

<para>There is one more way to write to a GIF file: through a
function hook. Initialize with </para>

<programlisting id="EGifOpen">
GifFileType *EGifOpen(void *userPtr, OutputFunc writeFunc)
</programlisting>

<para>and see the library header file for the type of OutputFunc.</para>
</sect1>
<sect1><title>Color map handling and allocation routines</title>

<programlisting id="MakeMapObject">
ColorMapObject *MakeMapObject(int ColorCount, GifColorType *ColorMap)
</programlisting>

<para>Allocate storage for a color map object with the given number of
RGB triplet slots.  If the second argument is non-NULL, initialize
the color table portion of the new map from it.  Returns NULL if
memory is exhausted or if the size is not a power of 2 &lt;= 256.</para>

<programlisting id="FreeMapObject">
void FreeMapObject(ColorMapObject *Object)
</programlisting>

<para>Free the storage occupied by a ColorMapObject that is no longer
needed.</para>

<programlisting id="UnionColorMap">
ColorMapObject *UnionColorMap(
        ColorMapObject *ColorIn1, ColorMapObject *ColorIn2,
        GifPixelType ColorTransIn2[])
</programlisting>

<para>Create the union of two given color maps and return it.  If the result
won't fit into 256 colors, NULL is returned, the allocated union
otherwise.  ColorIn1 is copied as it to ColorUnion, while colors from
ColorIn2 are copied iff they didn't exist before.  ColorTransIn2 maps
the old ColorIn2 into ColorUnion color map table.</para>

<programlisting id="GifAttachImage">
SavedImage *GifAttachImage(GifFileType *GifFile)
</programlisting>

<para>Add an image block to the SavedImages array.  The image block is
initially zeroed out.  This image block will be seen by any following
EGifSpew() calls.</para>

</sect1>
<sect1><title>Error Handling (gif_err.c)</title>

<programlisting>
int GifError(void)
int GifErrorString(void)
</programlisting>

<para>These functions return the last error reported by a library function,
as a numeric error code and string explanation respectively.</para>

</sect1>
<sect1><title>The GIF Utility Font</title>

<para>The 8x8 utility font used in text2gif and gifcolor lives in the library
module gif_font.c, in a table called AsciiTable.  The library header file
includes suitable externs and defines.</para>

<para>The GIF utility font support includes entry points for drawing legends
on in-core images, drawing boxes and rectangles, and boxing text.
These entry points are as follows:</para>

<programlisting id="DrawText">
void DrawText(
        SavedImage *Image,
        const int x, const int y,
        const char *legend,
        const int color)
</programlisting>

<para>Draw text using the 8x8 utility font on the saved image.  Upper
left corner of the text is at image pixel (x, y).  Use the specified
color index.</para>

<programlisting id="DrawBox">
void DrawBox(SavedImage *Image,
        const int x, const int y,
        const int w, const int h,
        const int color)
</programlisting>

<para>Draw a box on the saved image.  Upper left corner of the box is at
image pixels (x, y), width is w, height is h.  Use the specified color
index.</para>

<programlisting id="DrawRectangle">
void DrawRectangle(SavedImage *Image,
        const int x, const int y,
        const int w, const int h,
        const int color)
</programlisting>

<para>Draw a (filled) rectangle on the saved image.  Upper left corner of
the box is at image pixels (x, y), width is w, height is h.  Use the
specified color index.</para>

<programlisting id="DrawBoxedText">
void DrawBoxedText(SavedImage *Image,
        const int x, const int y,
        const char *legend,
        const int border,
        const int bg, const int fg)
</programlisting>

<para>Draw text on a filled rectangle.  The rectangle will be sized to fit
the text, with upper left hand corner at (x, y) on the saved image.
The `border' argument specifies a pixel margin around the text.  The
`bg' argument is the color table index to fill the rectangle with;
`fg' is the color table index to draw the text with.</para>

<para>This function interprets some characters in the legend string
specially.  A tab (\t) is interpreted as a command to center the
following text in the box.  A carriage return (\r) is interpreted
as a request for a line break.</para>

</sect1>
<sect1><title>Utility support library</title>

<para>These functions are not part of the core GIF library.  They are part
of the getarg library that supports the utilities.</para>

<sect2><title>Error Handling</title>

<programlisting id="PrintGifError">
void PrintGifError(void)
</programlisting>

<para>Print a one-line diagnostic on the last giflib error to stderr.</para>

<programlisting id="GifLastError">
int GifLastError(void)
</programlisting>

<para>Return the number of the last giflib error, and clear the error.
The error types are defined in gif_lib.h.</para>

<para>Note it is the user's responsibility to call the file closing
routine, so the file will be closed (if was opened), and allocated
memory will be released.</para>

</sect2>
<sect2><title>Command Line Parsing</title>

<programlisting id="GAGetArgs">
bool GAGetArgs(int argc, char **argv, char *CtrlStr, ...)
</programlisting>

<para>Main routine of this module.  Given argc &amp; argv as received by
the main procedure, the command line CtrlStr, and the addresses of
all parameters, parse the command line, and update the parameters.</para>

<para>The CtrlStr defines what types of variables should follow. Look at the
beginning of getarg.c for exact usage.</para>

<para>Returns false if successful, returns true on failure.</para>

<programlisting id="GAPrintErrMsg">
void GAPrintErrMsg(int Error)
</programlisting>

<para>If an error occurred in GAGetARgs, this routine may be used to print
one line diagnostic to stderr.</para>

<programlisting id="GAPrintHowTo">
void GAPrintHowTo(char *CtrlStr)
</programlisting>

<para>Given the same CtrlStr as for GAGetArgs, can be used to print a one line
'how to use'. </para>

</sect2>
</sect1>
<sect1><title>Forward and Backward Compatibility</title>

<para>The library header contains some version #defines you can useif you
need to condition your code so it can compile with different library 
versions</para>

<para>Versions up to 4.1.6 defined a GIF_LIB_VERSION macro that was
string-valued with a tricky format to parse.  This macro has been
retired.</para>

<para>Versions after 4.1.6 define integer-valued GIFLIB_MAJOR, GIFLIB_MINOR,
and GIFLIB_RELEASE macros for the three components of the version. See the
NEWS file in the GIFLIB distribution to track API changes.</para>

<para></para>

</sect1>
<sect1><title>Skeletons of GIF filters</title>

<para>If you are developing on a virtual-memory OS such as most flavors of
UNIX, or are otherwise sure of having enough memory to keep all of GIFs you
need to operate in core, writing a filter is trivial.   See the file
gifspnge.c in util.</para>

<para>A sequential filter skeleton will usually look like the example file
giffiltr.c in util.</para>

<para>Please look at the utilities in the util directory for more ideas once
you feel comfortable with these skeletons.  Also try to follow the coding
standards of this package if you want the maintainer to officially add your new
utility to it.</para>

</sect1>
</article>
