TIFFSetField(3tiff)TIFFSetField(3tiff)NAME
TIFFSetField, TIFFVSetField - set the value(s) of a tag in a TIFF file
open for writing
SYNOPSIS
#include <tiffio.h>
int TIFFSetField(TIFF* tif, ttag_t tag, ...)
#include <stdarg.h>
int TIFFVSetField(TIFF* tif, ttag_t tag, va_list ap)
TIFFSetField sets the value of a field or pseudo-tag in the current
directory associated with the open TIFF file. A pseudo-tag is a parame‐
ter that is used to control the operation of the TIFF library but whose
value is not read or written to the underlying file.
To set the value of a field, the file must have been previously opened
for writing with TIFFOpen(3tiff). Pseudo-tags can be set whether the
file was opened for reading or writing.
The field is identified by tag, one of the values defined in the
include file tiff.h (see also the table below). The actual value is
specified using a variable argument list as prescribed by the stdarg(3)
interface, or, on some machines, the varargs(3) interface.
EXTENDED DESCRIPTIONTIFFVSetField is functionally equivalent to TIFFSetField except that
TIFFVSetField takes a pointer to a variable argument list. TIFFVSet‐
Field is useful for writing routines that are layered on top of the
functionality provided by TIFFSetField.
The tags understood by libtiff, the number of parameter values, and the
expected types for the parameter values are shown below. The data types
are as follows:
char*
Null-terminated string, corresponds to the ASCII data type
uint16
Unsigned 16-bit value
uint32
Unsigned 32-bit value
uint16*
Array of unsigned 16-bit values
void*
Array of data values of unspecified type
Consult the TIFF specification for information on the meaning of each
tag.
┌───────────────────────────────┬────────────────┬─────────────────┬──────────────────────────────┐
│TAG NAME │ COUNT │ TYPES │ NOTES │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_ARTIST │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_BADFAXLINES │ 1 │ uint32 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_BITSPERSAMPLE │ 1 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_CLEANFAXDATA │ 1 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_COLORMAP │ 3 │ uint16* │ 1<<BitsPerSample arrays │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_COMPRESSION │ 1 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_CONSECUTIVEBADFAXLINES │ 1 │ uint32 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_DATETIME │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_DOCUMENTNAME │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_DOTRANGE │ 2 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_EXTRASAMPLES │ 2 │ uint16,uint16* │ — count and types array │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_FAXMODE │ 1 │ int │ — G3/G4 compression pseudo- │
│ │ │ │ tag │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_FAXFILLFUNC │ 1 │ TIFFFaxFillFunc │ G3/G4 compression pseudo-tag │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_FILLORDER │ 1 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_GROUP3OPTIONS │ 1 │ uint32 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_GROUP4OPTIONS │ 1 │ uint32 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_HALFTONEHINTS │ 2 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_HOSTCOMPUTER │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_IMAGEDEPTH │ 1 │ uint32 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_IMAGEDESCRIPTION │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_IMAGELENGTH │ 1 │ uint32 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_IMAGEWIDTH │ 1 │ uint32 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_INKNAMES │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_INKSET │ 1 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_JPEGTABLES │ 2 │ uint32*,void* │ — count and tables │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_JPEGQUALITY │ 1 │ int │ JPEG pseudo-tag │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_JPEGCOLORMODE │ 1 │ int │ — JPEG pseudo-tag │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_JPEGTABLESMODE │ 1 │ int │ — JPEG pseudo-tag │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_MAKE │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_MATTEING │ 1 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_MAXSAMPLEVALUE │ 1 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_MINSAMPLEVALUE │ 1 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_MODEL │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_ORIENTATION │ 1 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_PAGENAME │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_PAGENUMBER │ 2 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_PHOTOMETRIC │ 1 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_PLANARCONFIG │ 1 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_PREDICTOR │ 1 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_PRIMARYCHROMACITIES │ 1 │ float* │ 6-entry array │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_REFERENCEBLACKWHITE │ 1 │ float* │ - 2*SamplesPerPixel array │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_RESOLUTIONUNIT │ 1 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_ROWSPERSTRIP │ 1 │ uint32 │ — must be greater than 0 │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_SAMPLEFORMAT │ 1 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_SAMPLESPERPIXEL │ 1 │ uint16 │ — value must be <= 4 │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_SMAXSAMPLEVALUE │ 1 │ double │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_SMINSAMPLEVALUE │ 1 │ double │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_SOFTWARE │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_STONITS │ 1 │ double │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_SUBFILETYPE │ 1 │ uint32 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_SUBIFD │ 2 │ uint16,uint32* │ count and offsets array │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_TARGETPRINTER │ 1 │ char* │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_THRESHOLDING │ 1 │ uint16 │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_TILEDEPTH │ 1 │ uint32 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_TILELENGTH │ 1 │ uint32 │ — must be a multiple of 8 │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_TILEWIDTH │ 1 │ uint32 │ — must be a multiple of 8 │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_TRANSFERFUNCTION │ 1 or 3= │ uint16* │ 1<<BitsPerSample entry │
│ │ │ │ arrays │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_WHITEPOINT │ 1 │ float* │ 2-entry array │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_XPOSITION │ 1 │ float │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_XRESOLUTION │ 1 │ float │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_YCBCRCOEFFICIENTS │ 1 │ float* │ - 3-entry array │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_YCBCRPOSITIONING │ 1 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_YCBCRSUBSAMPLING │ 2 │ uint16 │ — │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_YPOSITION │ 1 │ float │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_YRESOLUTION │ 1 │ float │ │
├───────────────────────────────┼────────────────┼─────────────────┼──────────────────────────────┤
│TIFFTAG_ICCPROFILE │ 2 │ uint32,void* │ count, profile data+ │
└───────────────────────────────┴────────────────┴─────────────────┴──────────────────────────────┘
- Tag may not have its values changed once data
is written.
= If SamplesPerPixel is 1, then a single array is
passed. Otherwise, three arrays should be
passed.
+ The contents of this field are quite complex.
See The ICC Profile Format Specification, Annex
B "Embedding ICC Profiles in TIFF Files",
available at http://www.color.org, for an
explanation.
Diagnostics
All error messages are directed to the TIFFError(3tiff) routine.
%s: Cannot modify tag "%Datahihaswralready been written to the file, so
the specified tag value cannot be changed. This
restriction is applied to all tags that affect
the format of written data.
%d: Bad value for "%s". An invalid value was supplied for the named
tag.
1 is returned if the tag is defined in the current directory. Other‐
wise, 0 is returned.
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │image/library/libtiff │
├─────────────────────────────┼─────────────────────────────┤
│Interface stability │Uncommitted │
└─────────────────────────────┴─────────────────────────────┘
libtiff(3), TIFFOpen(3tiff), TIFFGetField(3tiff), TIFFSetDirec‐
tory(3tiff), TIFFReadDirectory(3tiff), TIFFWriteDirectory(3tiff)
This man page was originally written by Sam Leffler. Updated by Breda
McColgan, Sun Microsystems Inc., 2004.
05 Apr 2004 TIFFSetField(3tiff)
