STAddTag(3) Impressario 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
Page 1
STAddTag(3) Impressario STAddTag(3)
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 CODESSTAddTag 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 ALSOlibstiff(3)
Page 2
