1<!-- Creator : groff version 1.18.1 --> 2<!-- CreationDate: Sat Feb 24 18:37:16 2007 --> 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 − 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 <tiffio.h></b></p> 43<!-- INDENTATION --> 44<p><b>TIFF* TIFFOpen(const char *</b><i>filename</i><b>, 45const char *</b><i>mode</i><b>)<br> 46TIFF* 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, 51tdata_t, tsize_t);<br> 52typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int);<br> 53typedef int (*TIFFCloseProc)(thandle_t);<br> 54typedef toff_t (*TIFFSizeProc)(thandle_t);<br> 55typedef int (*TIFFMapFileProc)(thandle_t, tdata_t*, 56toff_t*);<br> 57typedef void (*TIFFUnmapFileProc)(thandle_t, tdata_t, 58toff_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>, 62thandle_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>, 65TIFFCloseProc</b> <i>closeproc</i><b>, TIFFSizeProc</b> 66<i>sizeproc</i><b>, TIFFMapFileProc</b> <i>mapproc</i><b>, 67TIFFUnmapFileProc</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 79name is <i>filename</i> and returns a handle to be used in 80subsequent calls to routines in <i>libtiff</i>. If the open 81operation fails, then zero is returned. The <i>mode</i> 82parameter specifies if the file is to be opened for reading 83(‘‘r’’), writing 84(‘‘w’’), or appending 85(‘‘a’’) and, optionally, whether to 86override certain default aspects of library operation (see 87below). When a file is opened for appending, existing data 88will not be touched; instead new data will be written as 89additional subfiles. If an existing file is opened for 90writing, 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 94read (also see <i>TIFFSetDirectory</i>(3TIFF) for reading 95directories other than the first). If a file is opened for 96writing or appending, a default directory is automatically 97created for writing subsequent data. This directory has all 98the default values specified in <small>TIFF</small> Revision 996.0: <i>BitsPerSample</i>=1, <i>ThreshHolding</i>=bilevel 100art scan, <i>FillOrder</i>=1 (most significant bit of each 101data byte is filled first), <i>Orientation</i>=1 (the 0th 102row represents the visual top of the image, and the 0th 103column 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 107for additional fields, <i>TIFFSetField</i>(3TIFF) must be 108used.</p> 109<!-- INDENTATION --> 110<p><i>TIFFFdOpen</i> is like <i>TIFFOpen</i> except that it 111opens a <small>TIFF</small> file given an open file 112descriptor <i>fd</i>. The file’s name and mode must 113reflect that of the open descriptor. The object associated 114with the file descriptor <b>must support random 115access</b>.</p> 116<!-- INDENTATION --> 117<p><i>TIFFClientOpen</i> is like <i>TIFFOpen</i> except that 118the caller supplies a collection of functions that the 119library will use to do <small>UNIX</small> -like I/O 120operations. The <i>readproc</i> and <i>writeproc</i> are 121called to read and write data at the current file position. 122<i>seekproc</i> is called to change the current file 123position a la <i>lseek</i>(2). <i>closeproc</i> is invoked 124to release any resources associated with an open file. 125<i>sizeproc</i> is invoked to obtain the size in bytes of a 126file. <i>mapproc</i> and <i>unmapproc</i> are called to map 127and unmap a file’s contents in memory; c.f. 128<i>mmap</i>(2) and <i>munmap</i>(2). The <i>clientdata</i> 129parameter is an opaque ‘‘handle’’ 130passed to the client-specified routines passed as parameters 131to <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 143in addition to the ‘‘r’’, 144‘‘w’’, and 145‘‘a’’ flags. Note however that 146option flags must follow the read-write-append 147specification.</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 163with Little-Endian byte order (but see below). By default 164the 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 179with Big-Endian byte order (but see below). By default the 180library 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 195with 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 198way 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 212with 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 228with 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 243read-only. If the underlying system does not support 244memory-mapped files or if the specific image being opened 245cannot be memory-mapped then the library will fallback to 246using the normal system interface for reading information. 247By default the library will attempt to use memory-mapped 248files.</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 ‘‘strip 275chopping’’ when reading images that are 276comprised of a single strip or tile of uncompressed data. 277Strip chopping is a mechanism by which the library will 278automatically convert the single-strip image to multiple 279strips, each of which has about 8 Kilobytes of data. This 280facility can be useful in reducing the amount of memory used 281to read an image because the library normally reads each 282strip in its entirety. Strip chopping does however alter the 283apparent contents of the image because when an image is 284divided into multiple strips it looks as though the 285underlying file contains multiple separate strips. Finally, 286note that default handling of strip chopping is a 287compile-time configuration parameter. The default behaviour, 288for backwards compatibility, is to enable strip 289chopping.</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 303images.</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 317directory. That could be useful in case of the broken first 318directory. We can open the file and proceed to the other 319directories.</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 333versions</b>) states that compliant readers <i>must be 334capable of reading images written in either byte order</i>. 335Nonetheless some software that claims to support the reading 336of <small>TIFF</small> images is incapable of reading images 337in anything but the native <small>CPU</small> byte order on 338which the software was written. (Especially notorious are 339applications written to run on Intel-based machines.) By 340default the library will create new files with the native 341byte-order of the <small>CPU</small> on which the 342application is run. This ensures optimal performance and is 343portable to any application that conforms to the TIFF 344specification. To force the library to use a specific 345byte-order when creating a new file the 346‘‘b’’ and 347‘‘l’’ option flags may be included 348in the call to open a file; for example, 349‘‘wb’’ or 350‘‘wl’’.</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 364returned.</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 377are directed to the <i>TIFFWarning</i>(3TIFF) routine.</p> 378<!-- INDENTATION --> 379<p><b>"%s": Bad mode</b>. The specified 380<i>mode</i> parameter was not one of 381‘‘r’’ (read), 382‘‘w’’ (write), or 383‘‘a’’ (append).</p> 384<!-- INDENTATION --> 385<p><b>%s: Cannot open</b>. <i>TIFFOpen</i>() was unable to 386open the specified filename for read/writing.</p> 387<!-- INDENTATION --> 388<p><b>Cannot read TIFF header</b>. An error occurred while 389attempting to read the header information.</p> 390<!-- INDENTATION --> 391<p><b>Error writing TIFF header</b>. An error occurred while 392writing 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 395magic number in the header was not (hex) 0x4d4d or (hex) 3960x4949.</p> 397<!-- INDENTATION --> 398<p><b>Not a TIFF file, bad version number %d (0x%x)</b>. The 399version field in the header was not 42 (decimal).</p> 400<!-- INDENTATION --> 401<p><b>Cannot append to file that has opposite byte 402ordering</b>. A file with a byte ordering opposite to the 403native byte ordering of the current machine was opened for 404appending (‘‘a’’). This is a 405limitation 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> 422