1
.\" $Id: TIFFGetField.3tiff,v 1.4 2006/01/02 23:50:44 bfriesen Exp $
3
.\" Copyright (c) 1988-1997 Sam Leffler
4
.\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
6
.\" Permission to use, copy, modify, distribute, and sell this software and
7
.\" its documentation for any purpose is hereby granted without fee, provided
8
.\" that (i) the above copyright notices and this permission notice appear in
9
.\" all copies of the software and related documentation, and (ii) the names of
10
.\" Sam Leffler and Silicon Graphics may not be used in any advertising or
11
.\" publicity relating to the software without the specific, prior written
12
.\" permission of Sam Leffler and Silicon Graphics.
14
.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
15
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
16
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
18
.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
19
.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
20
.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
21
.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
22
.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
26
.TH TIFFGetField 3TIFF "March 18, 2005" "libtiff"
28
TIFFGetField, TIFFVGetField \- get the value(s) of a tag in an open
32
.B "#include <tiffio.h>"
34
.BI "int TIFFGetField(TIFF *" tif ", ttag_t " tag ", " ... ")"
36
.B "#include <stdarg.h>"
38
.BI "int TIFFVGetField(TIFF *" tif ", ttag_t " tag ", va_list " ap ")"
40
.BI "int TIFFGetFieldDefaulted(TIFF *" tif ", ttag_t " tag ", " ... ")"
42
.BI "int TIFFVGetFieldDefaulted(TIFF *" tif ", ttag_t " tag ", va_list " ap ")"
45
returns the value of a tag or pseudo-tag associated with the the current
46
directory of the opened
52
is a parameter that is used to control the operation of the
54
library but whose value is not read or written to the underlying file.) The
55
file must have been previously opened with
57
The tag is identified by
59
one of the values defined in the include file
61
(see also the table below). The type and number of values returned is
62
dependent on the tag being requested. The programming interface uses a
63
variable argument list as prescribed by the
65
interface. The returned values should only be interpreted if
70
is functionally equivalent to
72
except that it takes a pointer to a variable argument list.
74
is useful for layering interfaces on top of the functionality provided by
77
.IR TIFFGetFieldDefaulted
79
.IR TIFFVGetFieldDefaulted
84
except that if a tag is not defined in the current directory and it has a
85
default value, then the default value is returned.
87
The tags understood by
89
the number of parameter values, and the types for the returned values are
90
shown below. The data types are specified as in C and correspond to the types
91
used to specify tag values to
92
.IR TIFFSetField (3TIFF).
95
returns parameter values, so all the listed data types are pointers to storage
96
where values should be returned.
99
specification (or relevant industry specification) for information on the
100
meaning of each tag and their possible values.
103
.ta \w'TIFFTAG_CONSECUTIVEBADFAXLINES'u+2n +\w'Count'u+2n +\w'TIFFFaxFillFunc*'u+2n
104
\fITag Name\fP \fICount\fP \fITypes\fP \fINotes\fP
106
TIFFTAG_ARTIST 1 char**
107
TIFFTAG_BADFAXLINES 1 uint32*
108
TIFFTAG_BITSPERSAMPLE 1 uint16*
109
TIFFTAG_CLEANFAXDATA 1 uint16*
110
TIFFTAG_COLORMAP 3 uint16** 1<<BitsPerSample arrays
111
TIFFTAG_COMPRESSION 1 uint16*
112
TIFFTAG_CONSECUTIVEBADFAXLINES 1 uint32*
113
TIFFTAG_COPYRIGHT 1 char**
114
TIFFTAG_DATATYPE 1 uint16*
115
TIFFTAG_DATETIME 1 char**
116
TIFFTAG_DOCUMENTNAME 1 char**
117
TIFFTAG_DOTRANGE 2 uint16*
118
TIFFTAG_EXTRASAMPLES 2 uint16*,uint16** count & types array
119
TIFFTAG_FAXFILLFUNC 1 TIFFFaxFillFunc* G3/G4 compression pseudo-tag
120
TIFFTAG_FAXMODE 1 int* G3/G4 compression pseudo-tag
121
TIFFTAG_FILLORDER 1 uint16*
122
TIFFTAG_GROUP3OPTIONS 1 uint32*
123
TIFFTAG_GROUP4OPTIONS 1 uint32*
124
TIFFTAG_HALFTONEHINTS 2 uint16*
125
TIFFTAG_HOSTCOMPUTER 1 char**
126
TIFFTAG_ICCPROFILE 2 uint32*,void** count, profile data
127
TIFFTAG_IMAGEDEPTH 1 uint32*
128
TIFFTAG_IMAGEDESCRIPTION 1 char**
129
TIFFTAG_IMAGELENGTH 1 uint32*
130
TIFFTAG_IMAGEWIDTH 1 uint32*
131
TIFFTAG_INKNAMES 1 char**
132
TIFFTAG_INKSET 1 uint16*
133
TIFFTAG_JPEGCOLORMODE 1 int* JPEG pseudo-tag
134
TIFFTAG_JPEGQUALITY 1 int* JPEG pseudo-tag
135
TIFFTAG_JPEGTABLES 2 uint32*,void** count & tables
136
TIFFTAG_JPEGTABLESMODE 1 int* JPEG pseudo-tag
137
TIFFTAG_MAKE 1 char**
138
TIFFTAG_MATTEING 1 uint16*
139
TIFFTAG_MAXSAMPLEVALUE 1 uint16*
140
TIFFTAG_MINSAMPLEVALUE 1 uint16*
141
TIFFTAG_MODEL 1 char**
142
TIFFTAG_ORIENTATION 1 uint16*
143
TIFFTAG_PAGENAME 1 char**
144
TIFFTAG_PAGENUMBER 2 uint16*
145
TIFFTAG_PHOTOMETRIC 1 uint16*
146
TIFFTAG_PHOTOSHOP 2 uint32*,void** count, data
147
TIFFTAG_PLANARCONFIG 1 uint16*
148
TIFFTAG_PREDICTOR 1 uint16*
149
TIFFTAG_PRIMARYCHROMATICITIES 1 float** 6-entry array
150
TIFFTAG_REFERENCEBLACKWHITE 1 float** 2*SamplesPerPixel array
151
TIFFTAG_RESOLUTIONUNIT 1 uint16*
152
TIFFTAG_RICHTIFFIPTC 2 uint32*,void** count, data
153
TIFFTAG_ROWSPERSTRIP 1 uint32*
154
TIFFTAG_SAMPLEFORMAT 1 uint16*
155
TIFFTAG_SAMPLESPERPIXEL 1 uint16*
156
TIFFTAG_SMAXSAMPLEVALUE 1 double*
157
TIFFTAG_SMINSAMPLEVALUE 1 double*
158
TIFFTAG_SOFTWARE 1 char**
159
TIFFTAG_STONITS 1 double**
160
TIFFTAG_STRIPBYTECOUNTS 1 uint32**
161
TIFFTAG_STRIPOFFSETS 1 uint32**
162
TIFFTAG_SUBFILETYPE 1 uint32*
163
TIFFTAG_SUBIFD 2 uint16*,uint32** count & offsets array
164
TIFFTAG_TARGETPRINTER 1 char**
165
TIFFTAG_THRESHHOLDING 1 uint16*
166
TIFFTAG_TILEBYTECOUNTS 1 uint32**
167
TIFFTAG_TILEDEPTH 1 uint32*
168
TIFFTAG_TILELENGTH 1 uint32*
169
TIFFTAG_TILEOFFSETS 1 uint32**
170
TIFFTAG_TILEWIDTH 1 uint32*
171
TIFFTAG_TRANSFERFUNCTION 1 or 3\(dg uint16**1<<BitsPerSample entry arrays
172
TIFFTAG_WHITEPOINT 1 float** 2-entry array
173
TIFFTAG_XMLPACKET 2 uint32*,void** count, data
174
TIFFTAG_XPOSITION 1 float*
175
TIFFTAG_XRESOLUTION 1 float*
176
TIFFTAG_YCBCRCOEFFICIENTS 1 float** 3-entry array
177
TIFFTAG_YCBCRPOSITIONING 1 uint16*
178
TIFFTAG_YCBCRSUBSAMPLING 2 uint16*
179
TIFFTAG_YPOSITION 1 float*
180
TIFFTAG_YRESOLUTION 1 float*\(dd
184
is one, then a single array is returned; otherwise three arrays are returned.
186
\(dd The contents of this field are quite complex. See
187
.IR "The ICC Profile Format Specification" ,
188
Annex B.3 "Embedding ICC Profiles in TIFF Files" (available at
189
http://www.color.org) for an explanation.
190
.SH AUTOREGISTERED TAGS
191
If you can't find the tag in the table above that means this is unsupported
192
tag. But you still be able to read it's value if you know the data type of
193
that tag. For example, if you want to read the LONG value from the tag 33424
194
and ASCII string from the tag 36867 you can use the following code:
201
TIFFGetField(tiff, 33424, &count, &data);
202
printf("Tag %d: %d, count %d\n", 33424, *(uint32 *)data, count);
203
TIFFGetField(tiff, 36867, &count, &data);
204
printf("Tag %d: %s, count %d\n", 36867, (char *)data, count);
214
1 is returned if the tag is defined in the current directory; otherwise a 0 is
217
All error messages are directed to the
218
.BR TIFFError (3TIFF)
221
.BR "Unknown field, tag 0x%x" .
222
An unknown tag was supplied.
224
.BR TIFFOpen (3TIFF),
225
.BR TIFFSetField (3TIFF),
226
.BR TIFFSetDirectory (3TIFF),
227
.BR TIFFReadDirectory (3TIFF),
228
.BR TIFFWriteDirectory (3TIFF)
231
Libtiff library home page:
232
.BR http://www.remotesensing.org/libtiff/