src/tiff/html/man/TIFFOpen.3tiff.html

   1 <!-- Creator     : groff version 1.18.1 -->
   2 <!-- CreationDate: Mon Mar 13 18:03:08 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>TIFFOpen</title>
   8 </head>
   9 <body>
  10
  11 <h1 align=center>TIFFOpen</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="#OPTIONS">OPTIONS</a><br>
  16 <a href="#BYTE ORDER">BYTE ORDER</a><br>
  17 <a href="#RETURN VALUES">RETURN VALUES</a><br>
  18 <a href="#DIAGNOSTICS">DIAGNOSTICS</a><br>
  19 <a href="#SEE ALSO">SEE ALSO</a><br>
  20
  21 <hr>
  22 <a name="NAME"></a>
  23 <h2>NAME</h2>
  24 <!-- INDENTATION -->
  25 <table width="100%" border=0 rules="none" frame="void"
  26        cols="2" cellspacing="0" cellpadding="0">
  27 <tr valign="top" align="left">
  28 <td width="8%"></td>
  29 <td width="91%">
  30 <p>TIFFOpen, TIFFFdOpen, TIFFClientOpen &minus; open a
  31 <small>TIFF</small> file for reading or writing</p>
  32 </td>
  33 </table>
  34 <a name="SYNOPSIS"></a>
  35 <h2>SYNOPSIS</h2>
  36 <!-- INDENTATION -->
  37 <table width="100%" border=0 rules="none" frame="void"
  38        cols="2" cellspacing="0" cellpadding="0">
  39 <tr valign="top" align="left">
  40 <td width="8%"></td>
  41 <td width="91%">
  42 <p><b>#include &lt;tiffio.h&gt;</b></p>
  43 <!-- INDENTATION -->
  44 <p><b>TIFF* TIFFOpen(const char *</b><i>filename</i><b>,
  45 const char *</b><i>mode</i><b>)<br>
  46 TIFF* TIFFFdOpen(const int</b> <i>fd</i><b>, const char
  47 *</b><i>filename</i><b>, const char
  48 *</b><i>mode</i><b>)</b></p>
  49 <!-- INDENTATION -->
  50 <p><b>typedef tsize_t (*TIFFReadWriteProc)(thandle_t,
  51 tdata_t, tsize_t);<br>
  52 typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int);<br>
  53 typedef int (*TIFFCloseProc)(thandle_t);<br>
  54 typedef toff_t (*TIFFSizeProc)(thandle_t);<br>
  55 typedef int (*TIFFMapFileProc)(thandle_t, tdata_t*,
  56 toff_t*);<br>
  57 typedef void (*TIFFUnmapFileProc)(thandle_t, tdata_t,
  58 toff_t);</b></p>
  59 <!-- INDENTATION -->
  60 <p><b>TIFF* TIFFClientOpen(const char
  61 *</b><i>filename</i><b>, const char *</b><i>mode</i><b>,
  62 thandle_t</b> <i>clientdata</i><b>, TIFFReadWriteProc</b>
  63 <i>readproc</i><b>, TIFFReadWriteProc</b>
  64 <i>writeproc</i><b>, TIFFSeekProc</b> <i>seekproc</i><b>,
  65 TIFFCloseProc</b> <i>closeproc</i><b>, TIFFSizeProc</b>
  66 <i>sizeproc</i><b>, TIFFMapFileProc</b> <i>mapproc</i><b>,
  67 TIFFUnmapFileProc</b> <i>unmapproc</i><b>)</b></p>
  68 </td>
  69 </table>
  70 <a name="DESCRIPTION"></a>
  71 <h2>DESCRIPTION</h2>
  72 <!-- INDENTATION -->
  73 <table width="100%" border=0 rules="none" frame="void"
  74        cols="2" cellspacing="0" cellpadding="0">
  75 <tr valign="top" align="left">
  76 <td width="8%"></td>
  77 <td width="91%">
  78 <p><i>TIFFOpen</i> opens a <small>TIFF</small> file whose
  79 name is <i>filename</i> and returns a handle to be used in
  80 subsequent calls to routines in <i>libtiff</i>. If the open
  81 operation fails, then zero is returned. The <i>mode</i>
  82 parameter specifies if the file is to be opened for reading
  83 (&lsquo;&lsquo;r&rsquo;&rsquo;), writing
  84 (&lsquo;&lsquo;w&rsquo;&rsquo;), or appending
  85 (&lsquo;&lsquo;a&rsquo;&rsquo;) and, optionally, whether to
  86 override certain default aspects of library operation (see
  87 below). When a file is opened for appending, existing data
  88 will not be touched; instead new data will be written as
  89 additional subfiles. If an existing file is opened for
  90 writing, all previous data is overwritten.</p>
  91 <!-- INDENTATION -->
  92 <p>If a file is opened for reading, the first
  93 <small>TIFF</small> directory in the file is automatically
  94 read (also see <i>TIFFSetDirectory</i>(3TIFF) for reading
  95 directories other than the first). If a file is opened for
  96 writing or appending, a default directory is automatically
  97 created for writing subsequent data. This directory has all
  98 the default values specified in <small>TIFF</small> Revision
  99 6.0: <i>BitsPerSample</i>=1, <i>ThreshHolding</i>=bilevel
 100 art scan, <i>FillOrder</i>=1 (most significant bit of each
 101 data byte is filled first), <i>Orientation</i>=1 (the 0th
 102 row represents the visual top of the image, and the 0th
 103 column represents the visual left hand side),
 104 <i>SamplesPerPixel</i>=1, <i>RowsPerStrip</i>=infinity,
 105 <i>ResolutionUnit</i>=2 (inches), and <i>Compression</i>=1
 106 (no compression). To alter these values, or to define values
 107 for additional fields, <i>TIFFSetField</i>(3TIFF) must be
 108 used.</p>
 109 <!-- INDENTATION -->
 110 <p><i>TIFFFdOpen</i> is like <i>TIFFOpen</i> except that it
 111 opens a <small>TIFF</small> file given an open file
 112 descriptor <i>fd</i>. The file&rsquo;s name and mode must
 113 reflect that of the open descriptor. The object associated
 114 with the file descriptor <b>must support random
 115 access</b>.</p>
 116 <!-- INDENTATION -->
 117 <p><i>TIFFClientOpen</i> is like <i>TIFFOpen</i> except that
 118 the caller supplies a collection of functions that the
 119 library will use to do <small>UNIX</small> -like I/O
 120 operations. The <i>readproc</i> and <i>writeproc</i> are
 121 called to read and write data at the current file position.
 122 <i>seekproc</i> is called to change the current file
 123 position a la <i>lseek</i>(2). <i>closeproc</i> is invoked
 124 to release any resources associated with an open file.
 125 <i>sizeproc</i> is invoked to obtain the size in bytes of a
 126 file. <i>mapproc</i> and <i>unmapproc</i> are called to map
 127 and unmap a file&rsquo;s contents in memory; c.f.
 128 <i>mmap</i>(2) and <i>munmap</i>(2). The <i>clientdata</i>
 129 parameter is an opaque &lsquo;&lsquo;handle&rsquo;&rsquo;
 130 passed to the client-specified routines passed as parameters
 131 to <i>TIFFClientOpen</i>.</p>
 132 </td>
 133 </table>
 134 <a name="OPTIONS"></a>
 135 <h2>OPTIONS</h2>
 136 <!-- INDENTATION -->
 137 <table width="100%" border=0 rules="none" frame="void"
 138        cols="2" cellspacing="0" cellpadding="0">
 139 <tr valign="top" align="left">
 140 <td width="8%"></td>
 141 <td width="91%">
 142 <p>The open mode parameter can include the following flags
 143 in addition to the &lsquo;&lsquo;r&rsquo;&rsquo;,
 144 &lsquo;&lsquo;w&rsquo;&rsquo;, and
 145 &lsquo;&lsquo;a&rsquo;&rsquo; flags. Note however that
 146 option flags must follow the read-write-append
 147 specification.</p>
 148 </td>
 149 </table>
 150 <!-- TABS -->
 151 <table width="100%" border=0 rules="none" frame="void"
 152        cols="5" cellspacing="0" cellpadding="0">
 153 <tr valign="top" align="left">
 154 <td width="10%"></td>
 155 <td width="2%">
 156
 157 <p><b>l</b></p>
 158 </td>
 159 <td width="6%"></td>
 160 <td width="80%">
 161
 162 <p>When creating a new file force information be written
 163 with Little-Endian byte order (but see below). By default
 164 the library will create new files using the native
 165 <small>CPU</small> byte order.</p>
 166 </td>
 167 <td width="0%">
 168 </td>
 169 <tr valign="top" align="left">
 170 <td width="10%"></td>
 171 <td width="2%">
 172
 173 <p><b>b</b></p>
 174 </td>
 175 <td width="6%"></td>
 176 <td width="80%">
 177
 178 <p>When creating a new file force information be written
 179 with Big-Endian byte order (but see below). By default the
 180 library will create new files using the native
 181 <small>CPU</small> byte order.</p>
 182 </td>
 183 <td width="0%">
 184 </td>
 185 <tr valign="top" align="left">
 186 <td width="10%"></td>
 187 <td width="2%">
 188
 189 <p><b>L</b></p>
 190 </td>
 191 <td width="6%"></td>
 192 <td width="80%">
 193
 194 <p>Force image data that is read or written to be treated
 195 with bits filled from Least Significant Bit (
 196 <small>LSB</small> ) to Most Significant Bit (
 197 <small>MSB</small> ). Note that this is the opposite to the
 198 way the library has worked from its inception.</p>
 199 </td>
 200 <td width="0%">
 201 </td>
 202 <tr valign="top" align="left">
 203 <td width="10%"></td>
 204 <td width="2%">
 205
 206 <p><b>B</b></p>
 207 </td>
 208 <td width="6%"></td>
 209 <td width="80%">
 210
 211 <p>Force image data that is read or written to be treated
 212 with bits filled from Most Significant Bit (
 213 <small>MSB</small> ) to Least Significant Bit (
 214 <small>LSB</small> ); this is the default.</p>
 215 </td>
 216 <td width="0%">
 217 </td>
 218 <tr valign="top" align="left">
 219 <td width="10%"></td>
 220 <td width="2%">
 221
 222 <p><b>H</b></p>
 223 </td>
 224 <td width="6%"></td>
 225 <td width="80%">
 226
 227 <p>Force image data that is read or written to be treated
 228 with bits filled in the same order as the native
 229 <small>CPU.</small></p>
 230 </td>
 231 <td width="0%">
 232 </td>
 233 <tr valign="top" align="left">
 234 <td width="10%"></td>
 235 <td width="2%">
 236
 237 <p><b>M</b></p>
 238 </td>
 239 <td width="6%"></td>
 240 <td width="80%">
 241
 242 <p>Enable the use of memory-mapped files for images opened
 243 read-only. If the underlying system does not support
 244 memory-mapped files or if the specific image being opened
 245 cannot be memory-mapped then the library will fallback to
 246 using the normal system interface for reading information.
 247 By default the library will attempt to use memory-mapped
 248 files.</p>
 249 </td>
 250 <td width="0%">
 251 </td>
 252 <tr valign="top" align="left">
 253 <td width="10%"></td>
 254 <td width="2%">
 255
 256 <p><b>m</b></p>
 257 </td>
 258 <td width="6%"></td>
 259 <td width="80%">
 260
 261 <p>Disable the use of memory-mapped files.</p>
 262 </td>
 263 <td width="0%">
 264 </td>
 265 <tr valign="top" align="left">
 266 <td width="10%"></td>
 267 <td width="2%">
 268
 269 <p><b>C</b></p>
 270 </td>
 271 <td width="6%"></td>
 272 <td width="80%">
 273
 274 <p>Enable the use of &lsquo;&lsquo;strip
 275 chopping&rsquo;&rsquo; when reading images that are
 276 comprised of a single strip or tile of uncompressed data.
 277 Strip chopping is a mechanism by which the library will
 278 automatically convert the single-strip image to multiple
 279 strips, each of which has about 8 Kilobytes of data. This
 280 facility can be useful in reducing the amount of memory used
 281 to read an image because the library normally reads each
 282 strip in its entirety. Strip chopping does however alter the
 283 apparent contents of the image because when an image is
 284 divided into multiple strips it looks as though the
 285 underlying file contains multiple separate strips. Finally,
 286 note that default handling of strip chopping is a
 287 compile-time configuration parameter. The default behaviour,
 288 for backwards compatibility, is to enable strip
 289 chopping.</p>
 290 </td>
 291 <td width="0%">
 292 </td>
 293 <tr valign="top" align="left">
 294 <td width="10%"></td>
 295 <td width="2%">
 296
 297 <p><b>c</b></p>
 298 </td>
 299 <td width="6%"></td>
 300 <td width="80%">
 301
 302 <p>Disable the use of strip chopping when reading
 303 images.</p>
 304 </td>
 305 <td width="0%">
 306 </td>
 307 <tr valign="top" align="left">
 308 <td width="10%"></td>
 309 <td width="2%">
 310
 311 <p><b>h</b></p>
 312 </td>
 313 <td width="6%"></td>
 314 <td width="80%">
 315
 316 <p>Read TIFF header only, do not load the first image
 317 directory. That could be useful in case of the broken first
 318 directory. We can open the file and proceed to the other
 319 directories.</p>
 320 </td>
 321 <td width="0%">
 322 </td>
 323 </table>
 324 <a name="BYTE ORDER"></a>
 325 <h2>BYTE ORDER</h2>
 326 <!-- INDENTATION -->
 327 <table width="100%" border=0 rules="none" frame="void"
 328        cols="2" cellspacing="0" cellpadding="0">
 329 <tr valign="top" align="left">
 330 <td width="8%"></td>
 331 <td width="91%">
 332 <p>The <small>TIFF</small> specification (<b>all
 333 versions</b>) states that compliant readers <i>must be
 334 capable of reading images written in either byte order</i>.
 335 Nonetheless some software that claims to support the reading
 336 of <small>TIFF</small> images is incapable of reading images
 337 in anything but the native <small>CPU</small> byte order on
 338 which the software was written. (Especially notorious are
 339 applications written to run on Intel-based machines.) By
 340 default the library will create new files with the native
 341 byte-order of the <small>CPU</small> on which the
 342 application is run. This ensures optimal performance and is
 343 portable to any application that conforms to the TIFF
 344 specification. To force the library to use a specific
 345 byte-order when creating a new file the
 346 &lsquo;&lsquo;b&rsquo;&rsquo; and
 347 &lsquo;&lsquo;l&rsquo;&rsquo; option flags may be included
 348 in the call to open a file; for example,
 349 &lsquo;&lsquo;wb&rsquo;&rsquo; or
 350 &lsquo;&lsquo;wl&rsquo;&rsquo;.</p>
 351 </td>
 352 </table>
 353 <a name="RETURN VALUES"></a>
 354 <h2>RETURN VALUES</h2>
 355 <!-- INDENTATION -->
 356 <table width="100%" border=0 rules="none" frame="void"
 357        cols="2" cellspacing="0" cellpadding="0">
 358 <tr valign="top" align="left">
 359 <td width="8%"></td>
 360 <td width="91%">
 361 <p>Upon successful completion <i>TIFFOpen</i>,
 362 <i>TIFFFdOpen</i>, and <i>TIFFClientOpen</i> return a
 363 <small>TIFF</small> pointer. Otherwise, NULL is
 364 returned.</p>
 365 </td>
 366 </table>
 367 <a name="DIAGNOSTICS"></a>
 368 <h2>DIAGNOSTICS</h2>
 369 <!-- INDENTATION -->
 370 <table width="100%" border=0 rules="none" frame="void"
 371        cols="2" cellspacing="0" cellpadding="0">
 372 <tr valign="top" align="left">
 373 <td width="8%"></td>
 374 <td width="91%">
 375 <p>All error messages are directed to the
 376 <i>TIFFError</i>(3TIFF) routine. Likewise, warning messages
 377 are directed to the <i>TIFFWarning</i>(3TIFF) routine.</p>
 378 <!-- INDENTATION -->
 379 <p><b>&quot;%s&quot;: Bad mode</b>. The specified
 380 <i>mode</i> parameter was not one of
 381 &lsquo;&lsquo;r&rsquo;&rsquo; (read),
 382 &lsquo;&lsquo;w&rsquo;&rsquo; (write), or
 383 &lsquo;&lsquo;a&rsquo;&rsquo; (append).</p>
 384 <!-- INDENTATION -->
 385 <p><b>%s: Cannot open</b>. <i>TIFFOpen</i>() was unable to
 386 open the specified filename for read/writing.</p>
 387 <!-- INDENTATION -->
 388 <p><b>Cannot read TIFF header</b>. An error occurred while
 389 attempting to read the header information.</p>
 390 <!-- INDENTATION -->
 391 <p><b>Error writing TIFF header</b>. An error occurred while
 392 writing the default header information for a new file.</p>
 393 <!-- INDENTATION -->
 394 <p><b>Not a TIFF file, bad magic number %d (0x%x)</b>. The
 395 magic number in the header was not (hex) 0x4d4d or (hex)
 396 0x4949.</p>
 397 <!-- INDENTATION -->
 398 <p><b>Not a TIFF file, bad version number %d (0x%x)</b>. The
 399 version field in the header was not 42 (decimal).</p>
 400 <!-- INDENTATION -->
 401 <p><b>Cannot append to file that has opposite byte
 402 ordering</b>. A file with a byte ordering opposite to the
 403 native byte ordering of the current machine was opened for
 404 appending (&lsquo;&lsquo;a&rsquo;&rsquo;). This is a
 405 limitation of the library.</p>
 406 </td>
 407 </table>
 408 <a name="SEE ALSO"></a>
 409 <h2>SEE ALSO</h2>
 410 <!-- INDENTATION -->
 411 <table width="100%" border=0 rules="none" frame="void"
 412        cols="2" cellspacing="0" cellpadding="0">
 413 <tr valign="top" align="left">
 414 <td width="8%"></td>
 415 <td width="91%">
 416 <p><i>libtiff</i>(3TIFF), <i>TIFFClose</i>(3TIFF)</p>
 417 </td>
 418 </table>
 419 <hr>
 420 </body>
 421 </html>