STAddTag(3)

NAME
     STAddTag, STRemoveTag, STGetTag, STPrintTags - TIFF tag handling

SYNOPSIS
     #include <stdio.h>
     #include <stiff.h>

     int STAddTag(STStream *st, unsigned short tag,
                  STTagType type, unsigned long len,
                  void *val);

     int STRemoveTag(STStream *st, unsigned short tag);

     int STGetTag(STStream *st, unsigned short tag,
                  STTagType *type, unsigned long *len,
                  void **val);

     int STPrintTags(FILE *fp, STStream *st);

DESCRIPTION
     These functions provide support for the direct handling of TIFF tags.
     Normal use of the libstiff functions to read and write STIFF files does
     not require the direct handling of TIFF tags. The functions listed here
     are optional and are intended for those who need to read specific tags
     from the STIFF stream, write specific tags to the STIFF stream or print
     the TIFF tags contained in a STIFF stream.

     The header file /usr/include/stiff.h lists all TIFF 6.0 and SGI
     proprietary tags. In addition, the header file lists the supported tag
     data types.

     STAddTag adds the specified tag to the STIFF stream output tag list.
     This function is called once for each new tag to be added to the STIFF
     output tag list. The tag list is written to the STIFF stream when
     STWriteImageHeader or PSTWriteImageHeader is called. When the image
     header write function is called the tag list is written to the stream and
     is then cleared. Therefore, if a tag is to be written with each page,
     STAddTag must be called before each page's call to the image header write
     function.  If STAddTag is used to add a tag that already exists on the
     tag list, the old tag is overwritten.

     Use the STGetTag function to determine if a tag is already present on the
     output tag list. st must point to an open STIFF stream. tag is the TIFF
     tag ID number to be added and type is the data type of the tag. len is
     the number of values of type contained in the tag and val is a pointer to
     the len value(s).

     STRemoveTag removes the tag specified by tag from the output tag list.

     STGetTag searches the tag list for the specified TIFF tag. This function
     can be used to determine if a given tag has been added to an output tag
     list or if a given tag has been read from a STIFF stream.  STGetTag
     searches the tag list for the tag specified by tag and, if found, places
     the tag's data type in type and the number of values in len. Storage for
     the value(s) of the tag is allocated by the STGetTag function and a
     pointer to this storage is returned in val. This storage must not be
     deallocated by the caller and the contents of val should be copied to
     caller allocated storage if it is to be preserved across subsequent calls
     to STGetTag.

     For STIFF streams open for reading, use STGetTag after calling
     STReadImageHeader to obtain tag values for the image.  For STIFF streams
     open for writing, use STGetTag before calling STWriteImageHeader to
     verify that application specific tags added with STAddTAg were added
     properly.

     STPrintTags prints the current TIFF tag list for the STIFF stream st to
     the file pointed to by fp.  A typical value of fp would be stdout.  This
     can be used for debugging purposes, and is most useful when called after
     calling STReadImageHeader or after a series of calls to STAddTag.

RETURN VALUE
     All functions return 0 if execution was successful. -1 is returned and
     STerrno is set if an execution error has occurred.

EXECUTION ERROR CODES
     STAddTag will fail under the following circumstances.

     STEBADTAG                Invalid TIFF tag.

     STENOMEM                 Out of memory.

     STGetTag and STRemoveTag will fail under the following circumstances.

     STENOTFOUND              TIFF tag not found.

SEE ALSO
     libstiff(3)