src/tiff/html/man/TIFFReadDirectory.3tiff.html

   1 <!-- Creator     : groff version 1.18.1 -->
   2 <!-- CreationDate: Mon Mar 13 18:03:09 2006 -->
   3 <html>
   4 <head>
   5 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   6 <meta name="Content-Style" content="text/css">
   7 <title>TIFFReadDirectory</title>
   8 </head>
   9 <body>
  10
  11 <h1 align=center>TIFFReadDirectory</h1>
  12 <a href="#NAME">NAME</a><br>
  13 <a href="#SYNOPSIS">SYNOPSIS</a><br>
  14 <a href="#DESCRIPTION">DESCRIPTION</a><br>
  15 <a href="#NOTES">NOTES</a><br>
  16 <a href="#RETURN VALUES">RETURN VALUES</a><br>
  17 <a href="#DIAGNOSTICS">DIAGNOSTICS</a><br>
  18 <a href="#SEE ALSO">SEE ALSO</a><br>
  19
  20 <hr>
  21 <a name="NAME"></a>
  22 <h2>NAME</h2>
  23 <!-- INDENTATION -->
  24 <table width="100%" border=0 rules="none" frame="void"
  25        cols="2" cellspacing="0" cellpadding="0">
  26 <tr valign="top" align="left">
  27 <td width="8%"></td>
  28 <td width="91%">
  29 <p><big>TIFFReadDirectory &minus; get the contents of the
  30 next directory in an open</big> TIFF <big>file</big></p>
  31 </td>
  32 </table>
  33 <a name="SYNOPSIS"></a>
  34 <h2>SYNOPSIS</h2>
  35 <!-- INDENTATION -->
  36 <table width="100%" border=0 rules="none" frame="void"
  37        cols="2" cellspacing="0" cellpadding="0">
  38 <tr valign="top" align="left">
  39 <td width="8%"></td>
  40 <td width="91%">
  41 <p><big><b>#include &lt;tiffio.h&gt;</b></big></p>
  42 <!-- INDENTATION -->
  43 <p><big><b>int TIFFReadDirectory(TIFF
  44 *</b><i>tif</i><b>)</b></big></p>
  45 </td>
  46 </table>
  47 <a name="DESCRIPTION"></a>
  48 <h2>DESCRIPTION</h2>
  49 <!-- INDENTATION -->
  50 <table width="100%" border=0 rules="none" frame="void"
  51        cols="2" cellspacing="0" cellpadding="0">
  52 <tr valign="top" align="left">
  53 <td width="8%"></td>
  54 <td width="91%">
  55 <p><big>Read the next directory in the specified file and
  56 make it the current directory. Applications only need to
  57 call <i>TIFFReadDirectory</i> to read multiple subfiles in a
  58 single</big> TIFF <big>file&mdash; the first directory in a
  59 file is automatically read when <i>TIFFOpen</i> is
  60 called.</big></p>
  61 </td>
  62 </table>
  63 <a name="NOTES"></a>
  64 <h2>NOTES</h2>
  65 <!-- INDENTATION -->
  66 <table width="100%" border=0 rules="none" frame="void"
  67        cols="2" cellspacing="0" cellpadding="0">
  68 <tr valign="top" align="left">
  69 <td width="8%"></td>
  70 <td width="91%">
  71 <p><big>If the library is compiled with</big>
  72 STRIPCHOP_SUPPORT <big>enabled, then images that have a
  73 single uncompressed strip or tile of data are automatically
  74 treated as if they were made up of multiple strips or tiles
  75 of approximately 8 kilobytes each. This operation is done
  76 only in-memory; it does not alter the contents of the file.
  77 However, the construction of the &lsquo;&lsquo;chopped
  78 strips&rsquo;&rsquo; is visible to the application through
  79 the number of strips [tiles] returned by
  80 <i>TIFFNumberOfStrips</i>
  81 [<i>TIFFNumberOfTiles</i>].</big></p>
  82 </td>
  83 </table>
  84 <a name="RETURN VALUES"></a>
  85 <h2>RETURN VALUES</h2>
  86 <!-- INDENTATION -->
  87 <table width="100%" border=0 rules="none" frame="void"
  88        cols="2" cellspacing="0" cellpadding="0">
  89 <tr valign="top" align="left">
  90 <td width="8%"></td>
  91 <td width="91%">
  92 <p><big>If the next directory was successfully read, 1 is
  93 returned. Otherwise, 0 is returned if an error was
  94 encountered, or if there are no more directories to be
  95 read.</big></p>
  96 </td>
  97 </table>
  98 <a name="DIAGNOSTICS"></a>
  99 <h2>DIAGNOSTICS</h2>
 100 <!-- INDENTATION -->
 101 <table width="100%" border=0 rules="none" frame="void"
 102        cols="2" cellspacing="0" cellpadding="0">
 103 <tr valign="top" align="left">
 104 <td width="8%"></td>
 105 <td width="91%">
 106 <p><big>All error messages are directed to the
 107 <i>TIFFError</i>(3TIFF) routine. All warning messages are
 108 directed to the <i>TIFFWarning</i>(3TIFF) routine.</big></p>
 109 <!-- INDENTATION -->
 110 <p><big><b>Seek error accessing TIFF directory</b>. An error
 111 occurred while positioning to the location of the
 112 directory.</big></p>
 113 <!-- INDENTATION -->
 114 <p><big><b>Wrong data type %d for field &quot;%s&quot;</b>.
 115 The tag entry in the directory had an incorrect data type.
 116 For example, an <i>ImageDescription</i> tag with a</big>
 117 SHORT <big>data type.</big></p>
 118 <!-- INDENTATION -->
 119 <p><big><b>TIFF directory is missing required &quot;%s&quot;
 120 field</b>. The specified tag is required to be present by
 121 the</big> TIFF <big>5.0 specification, but is missing. The
 122 directory is (usually) unusable.</big></p>
 123 <!-- INDENTATION -->
 124 <p><big><b>%s: Rational with zero denominator</b>. A
 125 directory tag has a</big> RATIONAL <big>value whose
 126 denominator is zero.</big></p>
 127 <!-- INDENTATION -->
 128 <p><big><b>Incorrect count %d for field &quot;%s&quot; (%lu,
 129 expecting %lu); tag ignored</b>. The specified tag&rsquo;s
 130 count field is bad. For example, a count other than 1 for a
 131 <i>SubFileType</i> tag.</big></p>
 132 <!-- INDENTATION -->
 133 <p><big><b>Cannot handle different per-sample values for
 134 field &quot;%s&quot;</b>. The tag has <i>SamplesPerPixel</i>
 135 values and they are not all the same; e.g.
 136 <i>BitsPerSample</i>. The library is unable to handle images
 137 of this sort.</big></p>
 138 <!-- INDENTATION -->
 139 <p><big><b>Count mismatch for field &quot;%s&quot;;
 140 expecting %d, got %d</b>. The count field in a tag does not
 141 agree with the number expected by the library. This should
 142 never happen, so if it does, the library refuses to read the
 143 directory.</big></p>
 144 <!-- INDENTATION -->
 145 <p><big><b>Invalid TIFF directory; tags are not sorted in
 146 ascending order</b>. The directory tags are not properly
 147 sorted as specified in the</big> TIFF <big>5.0
 148 specification. This error is not fatal.</big></p>
 149 <!-- INDENTATION -->
 150 <p><big><b>Ignoring unknown field with tag %d (0x%x)</b>. An
 151 unknown tag was encountered in the directory; the library
 152 ignores all such tags.</big></p>
 153 <!-- INDENTATION -->
 154 <p><big><b>TIFF directory is missing requred
 155 &quot;ImageLength&quot; field</b>. The image violates the
 156 specification by not having a necessary field. There is no
 157 way for the library to recover from this error.</big></p>
 158 <!-- INDENTATION -->
 159 <p><big><b>TIFF directory is missing requred
 160 &quot;PlanarConfig&quot; field</b>. The image violates the
 161 specification by not having a necessary field. There is no
 162 way for the library to recover from this error.</big></p>
 163 <!-- INDENTATION -->
 164 <p><big><b>TIFF directory is missing requred
 165 &quot;StripOffsets&quot; field</b>. The image has multiple
 166 strips, but is missing the tag that specifies the file
 167 offset to each strip of data. There is no way for the
 168 library to recover from this error.</big></p>
 169 <!-- INDENTATION -->
 170 <p><big><b>TIFF directory is missing requred
 171 &quot;TileOffsets&quot; field</b>. The image has multiple
 172 tiles, but is missing the tag that specifies the file offset
 173 to each tile of data. There is no way for the library to
 174 recover from this error.</big></p>
 175 <!-- INDENTATION -->
 176 <p><big><b>TIFF directory is missing required
 177 &quot;StripByteCounts&quot; field</b>. The image has
 178 multiple strips, but is missing the tag that specifies the
 179 size of each strip of data. There is no way for the library
 180 to recover from this error.</big></p>
 181 <!-- INDENTATION -->
 182 <p><big><b>TIFF directory is missing required
 183 &quot;StripByteCounts&quot; field, calculating from
 184 imagelength</b>. The image violates the specification by not
 185 having a necessary field. However, when the image is
 186 comprised of only one strip or tile, the library will
 187 estimate the missing value based on the file size.</big></p>
 188 <!-- INDENTATION -->
 189 <p><big><b>Bogus &quot;StripByteCounts&quot; field, ignoring
 190 and calculating from imagelength</b>. Certain vendors
 191 violate the specification by writing zero for the
 192 StripByteCounts tag when they want to leave the value
 193 unspecified. If the image has a single strip, the library
 194 will estimate the missing value based on the file
 195 size.</big></p>
 196 </td>
 197 </table>
 198 <a name="SEE ALSO"></a>
 199 <h2>SEE ALSO</h2>
 200 <!-- INDENTATION -->
 201 <table width="100%" border=0 rules="none" frame="void"
 202        cols="2" cellspacing="0" cellpadding="0">
 203 <tr valign="top" align="left">
 204 <td width="8%"></td>
 205 <td width="91%">
 206 <p><big><b>TIFFOpen</b>(3TIFF),
 207 <b>TIFFWriteDirectory</b>(3TIFF),
 208 <b>TIFFSetDirectory</b>(3TIFF),
 209 <b>TIFFSetSubDirectory</b>(3TIFF),
 210 <b>libtiff</b>(3TIFF)</big></p>
 211 <!-- INDENTATION -->
 212 <p><big>Libtiff library home page:
 213 <b>http://www.remotesensing.org/libtiff/</b></big></p>
 214 </td>
 215 </table>
 216 <hr>
 217 </body>
 218 </html>