src/tiff/man/TIFFReadDirectory.3tiff

   1 .\" $Id: TIFFReadDirectory.3tiff,v 1.3 2010-12-12 01:45:35 faxguy 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 TIFFReadDirectory 3TIFF "October 15, 1995" "libtiff"
  27 .SH NAME
  28 TIFFReadDirectory \- get the contents of the next directory in an open
  29 .SM TIFF
  30 file
  31 .SH SYNOPSIS
  32 .B "#include <tiffio.h>"
  33 .sp
  34 .BI "int TIFFReadDirectory(TIFF *" tif ")"
  35 .SH DESCRIPTION
  36 Read the next directory in the specified file and make it the current
  37 directory. Applications only need to call
  38 .I TIFFReadDirectory
  39 to read multiple subfiles in a single
  40 .SM TIFF
  41 file\(em
  42 the first directory in a file is automatically read when
  43 .IR TIFFOpen
  44 is called.
  45 .SH NOTES
  46 If the library is compiled with
  47 .SM STRIPCHOP_SUPPORT
  48 enabled, then images that have a single uncompressed strip or tile of data are
  49 automatically treated as if they were made up of multiple strips or tiles of
  50 approximately 8 kilobytes each. This operation is done only in-memory; it does
  51 not alter the contents of the file. However, the construction of the ``chopped
  52 strips'' is visible to the application through the number of strips [tiles]
  53 returned by
  54 .I TIFFNumberOfStrips
  55 [\c
  56 .IR TIFFNumberOfTiles ].
  57 .SH "RETURN VALUES"
  58 If the next directory was successfully read, 1 is returned. Otherwise, 0 is
  59 returned if an error was encountered, or if there are no more directories to
  60 be read.
  61 .SH DIAGNOSTICS
  62 All error messages are directed to the
  63 .IR TIFFError (3TIFF)
  64 routine.
  65 All warning messages are directed to the
  66 .IR TIFFWarning (3TIFF)
  67 routine.
  68 .PP
  69 \fBSeek error accessing TIFF directory\fP.
  70 An error occurred while positioning to the location of the
  71 directory.
  72 .PP
  73 \fBWrong data type %d for field "%s"\fP.
  74 The tag entry in the directory had an incorrect data type.
  75 For example, an
  76 .I ImageDescription
  77 tag with a
  78 .SM SHORT
  79 data type.
  80 .PP
  81 \fBTIFF directory is missing required "%s" field\fP.
  82 The specified tag is required to be present by the
  83 .SM TIFF
  84 5.0 specification, but is missing.
  85 The directory is (usually) unusable.
  86 .PP
  87 \fB%s: Rational with zero denominator\fP.
  88 A directory tag has a
  89 .SM RATIONAL
  90 value whose denominator is zero.
  91 .PP
  92 \fBIncorrect count %d for field "%s" (%lu, expecting %lu); tag ignored\fP.
  93 The specified tag's count field is bad.
  94 For example, a count other than 1 for a
  95 .I SubFileType
  96 tag.
  97 .PP
  98 \fBCannot handle different per-sample values for field "%s"\fP.
  99 The tag has
 100 .I SamplesPerPixel
 101 values and they are not all the same; e.g.
 102 .IR BitsPerSample .
 103 The library is unable to handle images of this sort.
 104 .PP
 105 \fBCount mismatch for field "%s"; expecting %d, got %d\fP.
 106 The count field in a
 107 tag does not agree with the number expected by the library.
 108 This should never happen, so if it does, the library refuses to
 109 read the directory.
 110 .PP
 111 \fBInvalid TIFF directory; tags are not sorted in ascending order\fP.
 112 The directory tags are not properly sorted as specified
 113 in the
 114 .SM TIFF
 115 5.0 specification.
 116 This error is not fatal.
 117 .PP
 118 \fBIgnoring unknown field with tag %d (0x%x)\fP.
 119 An unknown tag was encountered in the directory;
 120 the library ignores all such tags.
 121 .PP
 122 \fBTIFF directory is missing required "ImageLength" field\fP.
 123 The image violates the specification by not having a necessary field.
 124 There is no way for the library to recover from this error.
 125 .PP
 126 \fBTIFF directory is missing required "PlanarConfig" field\fP.
 127 The image violates the specification by not having a necessary field.
 128 There is no way for the library to recover from this error.
 129 .PP
 130 \fBTIFF directory is missing required "StripOffsets" field\fP.
 131 The image has multiple strips, but is missing the tag that
 132 specifies the file offset to each strip of data.
 133 There is no way for the library to recover from this error.
 134 .PP
 135 \fBTIFF directory is missing required "TileOffsets" field\fP.
 136 The image has multiple tiles, but is missing the tag that
 137 specifies the file offset to each tile of data.
 138 There is no way for the library to recover from this error.
 139 .PP
 140 \fBTIFF directory is missing required "StripByteCounts" field\fP.
 141 The image has multiple strips, but is missing the tag that
 142 specifies the size of each strip of data.
 143 There is no way for the library to recover from this error.
 144 .PP
 145 \fBTIFF directory is missing required "StripByteCounts" field, calculating from imagelength\fP.
 146 The image violates the specification by not having a necessary field.
 147 However, when the image is comprised of only one strip or tile, the
 148 library will estimate the missing value based on the file size.
 149 .PP
 150 \fBBogus "StripByteCounts" field, ignoring and calculating from imagelength\fP.
 151 Certain vendors violate the specification by writing zero for
 152 the StripByteCounts tag when they want to leave the value
 153 unspecified.
 154 If the image has a single strip, the library will estimate
 155 the missing value based on the file size.
 156 .SH "SEE ALSO"
 157 .BR TIFFOpen (3TIFF),
 158 .BR TIFFWriteDirectory (3TIFF),
 159 .BR TIFFSetDirectory (3TIFF),
 160 .BR TIFFSetSubDirectory (3TIFF),
 161 .BR libtiff (3TIFF)
 162 .PP
 163 Libtiff library home page:
 164 .BR http://www.remotesensing.org/libtiff/