src/tiff/man/TIFFGetField.3tiff

   1 .\" $Id: TIFFGetField.3tiff,v 1.6 2012-05-19 23:15:22 bfriesen Exp $
   2 .\"
   3 .\" Copyright (c) 1988-1997 Sam Leffler
   4 .\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
   5 .\"
   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.
  13 .\"
  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.
  17 .\"
  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
  23 .\" OF THIS SOFTWARE.
  24 .\"
  25 .if n .po 0
  26 .TH TIFFGetField 3TIFF "March 18, 2005" "libtiff"
  27 .SH NAME
  28 TIFFGetField, TIFFVGetField \- get the value(s) of a tag in an open
  29 .SM TIFF
  30 file
  31 .SH SYNOPSIS
  32 .B "#include <tiffio.h>"
  33 .sp
  34 .BI "int TIFFGetField(TIFF *" tif ", ttag_t " tag ", " ... ")"
  35 .sp
  36 .B "#include <stdarg.h>"
  37 .sp
  38 .BI "int TIFFVGetField(TIFF *" tif ", ttag_t " tag ", va_list " ap ")"
  39 .br
  40 .BI "int TIFFGetFieldDefaulted(TIFF *" tif ", ttag_t " tag ", " ... ")"
  41 .br
  42 .BI "int TIFFVGetFieldDefaulted(TIFF *" tif ", ttag_t " tag ", va_list " ap ")"
  43 .SH DESCRIPTION
  44 .IR TIFFGetField
  45 returns the value of a tag or pseudo-tag associated with the the current
  46 directory of the opened
  47 .SM TIFF
  48 file
  49 .IR tif .
  50 (A
  51 .I pseudo-tag
  52 is a parameter that is used to control the operation of the
  53 .SM TIFF
  54 library but whose value is not read or written to the underlying file.) The
  55 file must have been previously opened with
  56 .IR TIFFOpen (3TIFF).
  57 The tag is identified by
  58 .IR tag ,
  59 one of the values defined in the include file
  60 .B tiff.h
  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
  64 .IR stdarg (3)
  65 interface. The returned values should only be interpreted if
  66 .IR TIFFGetField
  67 returns 1.
  68 .PP
  69 .IR TIFFVGetField
  70 is functionally equivalent to
  71 .IR TIFFGetField
  72 except that it takes a pointer to a variable argument list.
  73 .I TIFFVGetField
  74 is useful for layering interfaces on top of the functionality provided by
  75 .IR TIFFGetField .
  76 .PP
  77 .IR TIFFGetFieldDefaulted
  78 and
  79 .IR TIFFVGetFieldDefaulted
  80 are identical to
  81 .IR TIFFGetField
  82 and
  83 .IR TIFFVGetField ,
  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.
  86 .PP
  87 The tags understood by
  88 .IR libtiff(3TIFF),
  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).
  93 Remember that
  94 .IR TIFFGetField
  95 returns parameter values, so all the listed data types are pointers to storage
  96 where values should be returned.
  97 Consult the
  98 .SM TIFF
  99 specification (or relevant industry specification) for information on the
 100 meaning of each tag and their possible values.
 101 .PP
 102 .nf
 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
 105 .sp 5p
 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** 6-entry 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
 181 .fi
 182 \(dg If
 183 .I SamplesPerPixel
 184 is one, then a single array is returned; otherwise three arrays are returned.
 185 .fi
 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 an unsupported
 192 tag and is not directly supported by
 193 .BR libtiff(3TIFF)
 194 library. You will still be able to read it's value if you know the data type of
 195 that tag. For example, if you want to read the LONG value from the tag 33424
 196 and ASCII string from the tag 36867 you can use the following code:
 197 .PP
 198 .RS
 199 .nf
 200 uint32  count;
 201 void    *data;
 202
 203 TIFFGetField(tiff, 33424, &count, &data);
 204 printf("Tag %d: %d, count %d\n", 33424, *(uint32 *)data, count);
 205 TIFFGetField(tiff, 36867, &count, &data);
 206 printf("Tag %d: %s, count %d\n", 36867, (char *)data, count);
 207 .fi
 208 .RE
 209 .PP
 210 .SH RETURN VALUES
 211 1 is returned if the tag is defined in the current directory; otherwise a 0 is
 212 returned.
 213 .SH DIAGNOSTICS
 214 All error messages are directed to the
 215 .BR TIFFError (3TIFF)
 216 routine.
 217 .PP
 218 .BR "Unknown field, tag 0x%x" .
 219 An unknown tag was supplied.
 220 .SH "SEE ALSO"
 221 .BR TIFFOpen (3TIFF),
 222 .BR TIFFSetField (3TIFF),
 223 .BR TIFFSetDirectory (3TIFF),
 224 .BR TIFFReadDirectory (3TIFF),
 225 .BR TIFFWriteDirectory (3TIFF)
 226 .BR libtiff (3TIFF),
 227 .PP
 228 Libtiff library home page:
 229 .BR http://www.remotesensing.org/libtiff/