src/tiff/man/TIFFGetField.3tiff

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