diff options
Diffstat (limited to 'html/man/TIFFOpen.3tiff.html')
| -rw-r--r-- | html/man/TIFFOpen.3tiff.html | 601 |
1 files changed, 312 insertions, 289 deletions
diff --git a/html/man/TIFFOpen.3tiff.html b/html/man/TIFFOpen.3tiff.html index 10949a10..3d3ca660 100644 --- a/html/man/TIFFOpen.3tiff.html +++ b/html/man/TIFFOpen.3tiff.html @@ -1,24 +1,14 @@ -<!-- Creator : groff version 1.19.2 --> -<!-- CreationDate: Mon Jan 2 17:41:38 2006 --> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" -"http://www.w3.org/TR/html4/loose.dtd"> +<!-- Creator : groff version 1.18.1 --> +<!-- CreationDate: Mon Mar 13 18:03:08 2006 --> <html> <head> <meta name="generator" content="groff -Thtml, see www.gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <meta name="Content-Style" content="text/css"> -<style type="text/css"> - p { margin-top: 0; margin-bottom: 0; } - pre { margin-top: 0; margin-bottom: 0; } - table { margin-top: 0; margin-bottom: 0; } -</style> <title>TIFFOpen</title> - </head> <body> <h1 align=center>TIFFOpen</h1> - <a href="#NAME">NAME</a><br> <a href="#SYNOPSIS">SYNOPSIS</a><br> <a href="#DESCRIPTION">DESCRIPTION</a><br> @@ -29,59 +19,64 @@ <a href="#SEE ALSO">SEE ALSO</a><br> <hr> - - <a name="NAME"></a> <h2>NAME</h2> - - -<p style="margin-left:11%; margin-top: 1em">TIFFOpen, -TIFFFdOpen, TIFFClientOpen − open a +<!-- INDENTATION --> +<table width="100%" border=0 rules="none" frame="void" + cols="2" cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="8%"></td> +<td width="91%"> +<p>TIFFOpen, TIFFFdOpen, TIFFClientOpen − open a <small>TIFF</small> file for reading or writing</p> - +</td> +</table> <a name="SYNOPSIS"></a> <h2>SYNOPSIS</h2> - - -<p style="margin-left:11%; margin-top: 1em"><b>#include -<tiffio.h></b></p> - -<p style="margin-left:11%; margin-top: 1em"><b>TIFF* -TIFFOpen(const char *</b><i>filename</i><b>, const char -*</b><i>mode</i><b>) <br> +<!-- INDENTATION --> +<table width="100%" border=0 rules="none" frame="void" + cols="2" cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="8%"></td> +<td width="91%"> +<p><b>#include <tiffio.h></b></p> +<!-- INDENTATION --> +<p><b>TIFF* TIFFOpen(const char *</b><i>filename</i><b>, +const char *</b><i>mode</i><b>)<br> TIFF* TIFFFdOpen(const int</b> <i>fd</i><b>, const char *</b><i>filename</i><b>, const char *</b><i>mode</i><b>)</b></p> - -<p style="margin-left:11%; margin-top: 1em"><b>typedef -tsize_t (*TIFFReadWriteProc)(thandle_t, tdata_t, tsize_t); -<br> -typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int); <br> -typedef int (*TIFFCloseProc)(thandle_t); <br> -typedef toff_t (*TIFFSizeProc)(thandle_t); <br> +<!-- INDENTATION --> +<p><b>typedef tsize_t (*TIFFReadWriteProc)(thandle_t, +tdata_t, tsize_t);<br> +typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int);<br> +typedef int (*TIFFCloseProc)(thandle_t);<br> +typedef toff_t (*TIFFSizeProc)(thandle_t);<br> typedef int (*TIFFMapFileProc)(thandle_t, tdata_t*, -toff_t*); <br> +toff_t*);<br> typedef void (*TIFFUnmapFileProc)(thandle_t, tdata_t, toff_t);</b></p> - -<p style="margin-left:11%; margin-top: 1em"><b>TIFF* -TIFFClientOpen(const char *</b><i>filename</i><b>, const -char *</b><i>mode</i><b>, thandle_t</b> -<i>clientdata</i><b>, TIFFReadWriteProc</b> +<!-- INDENTATION --> +<p><b>TIFF* TIFFClientOpen(const char +*</b><i>filename</i><b>, const char *</b><i>mode</i><b>, +thandle_t</b> <i>clientdata</i><b>, TIFFReadWriteProc</b> <i>readproc</i><b>, TIFFReadWriteProc</b> <i>writeproc</i><b>, TIFFSeekProc</b> <i>seekproc</i><b>, TIFFCloseProc</b> <i>closeproc</i><b>, TIFFSizeProc</b> <i>sizeproc</i><b>, TIFFMapFileProc</b> <i>mapproc</i><b>, TIFFUnmapFileProc</b> <i>unmapproc</i><b>)</b></p> - +</td> +</table> <a name="DESCRIPTION"></a> <h2>DESCRIPTION</h2> - - - -<p style="margin-left:11%; margin-top: 1em"><i>TIFFOpen</i> -opens a <small>TIFF</small> file whose name is -<i>filename</i> and returns a handle to be used in +<!-- INDENTATION --> +<table width="100%" border=0 rules="none" frame="void" + cols="2" cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="8%"></td> +<td width="91%"> +<p><i>TIFFOpen</i> opens a <small>TIFF</small> file whose +name is <i>filename</i> and returns a handle to be used in subsequent calls to routines in <i>libtiff</i>. If the open operation fails, then zero is returned. The <i>mode</i> parameter specifies if the file is to be opened for reading @@ -93,233 +88,253 @@ below). When a file is opened for appending, existing data will not be touched; instead new data will be written as additional subfiles. If an existing file is opened for writing, all previous data is overwritten.</p> - -<p style="margin-left:11%; margin-top: 1em">If a file is -opened for reading, the first <small>TIFF</small> directory -in the file is automatically read (also see -<i>TIFFSetDirectory</i>(3TIFF) for reading directories other -than the first). If a file is opened for writing or -appending, a default directory is automatically created for -writing subsequent data. This directory has all the default -values specified in <small>TIFF</small> Revision 6.0: -<i>BitsPerSample</i>=1, <i>ThreshHolding</i>=bilevel art -scan, <i>FillOrder</i>=1 (most significant bit of each data -byte is filled first), <i>Orientation</i>=1 (the 0th row -represents the visual top of the image, and the 0th column -represents the visual left hand side), +<!-- INDENTATION --> +<p>If a file is opened for reading, the first +<small>TIFF</small> directory in the file is automatically +read (also see <i>TIFFSetDirectory</i>(3TIFF) for reading +directories other than the first). If a file is opened for +writing or appending, a default directory is automatically +created for writing subsequent data. This directory has all +the default values specified in <small>TIFF</small> Revision +6.0: <i>BitsPerSample</i>=1, <i>ThreshHolding</i>=bilevel +art scan, <i>FillOrder</i>=1 (most significant bit of each +data byte is filled first), <i>Orientation</i>=1 (the 0th +row represents the visual top of the image, and the 0th +column represents the visual left hand side), <i>SamplesPerPixel</i>=1, <i>RowsPerStrip</i>=infinity, <i>ResolutionUnit</i>=2 (inches), and <i>Compression</i>=1 (no compression). To alter these values, or to define values for additional fields, <i>TIFFSetField</i>(3TIFF) must be used.</p> - - -<p style="margin-left:11%; margin-top: 1em"><i>TIFFFdOpen</i> -is like <i>TIFFOpen</i> except that it opens a -<small>TIFF</small> file given an open file descriptor -<i>fd</i>. The file’s name and mode must reflect that -of the open descriptor. The object associated with the file -descriptor <b>must support random access</b>.</p> - - -<p style="margin-left:11%; margin-top: 1em"><i>TIFFClientOpen</i> -is like <i>TIFFOpen</i> except that the caller supplies a -collection of functions that the library will use to do -<small>UNIX</small> -like I/O operations. The -<i>readproc</i> and <i>writeproc</i> are called to read and -write data at the current file position. <i>seekproc</i> is -called to change the current file position a la -<i>lseek</i>(2). <i>closeproc</i> is invoked to release any -resources associated with an open file. <i>sizeproc</i> is -invoked to obtain the size in bytes of a file. -<i>mapproc</i> and <i>unmapproc</i> are called to map and -unmap a file’s contents in memory; c.f. <i>mmap</i>(2) -and <i>munmap</i>(2). The <i>clientdata</i> parameter is an -opaque ‘‘handle’’ passed to the -client-specified routines passed as parameters to -<i>TIFFClientOpen</i>.</p> - +<!-- INDENTATION --> +<p><i>TIFFFdOpen</i> is like <i>TIFFOpen</i> except that it +opens a <small>TIFF</small> file given an open file +descriptor <i>fd</i>. The file’s name and mode must +reflect that of the open descriptor. The object associated +with the file descriptor <b>must support random +access</b>.</p> +<!-- INDENTATION --> +<p><i>TIFFClientOpen</i> is like <i>TIFFOpen</i> except that +the caller supplies a collection of functions that the +library will use to do <small>UNIX</small> -like I/O +operations. The <i>readproc</i> and <i>writeproc</i> are +called to read and write data at the current file position. +<i>seekproc</i> is called to change the current file +position a la <i>lseek</i>(2). <i>closeproc</i> is invoked +to release any resources associated with an open file. +<i>sizeproc</i> is invoked to obtain the size in bytes of a +file. <i>mapproc</i> and <i>unmapproc</i> are called to map +and unmap a file’s contents in memory; c.f. +<i>mmap</i>(2) and <i>munmap</i>(2). The <i>clientdata</i> +parameter is an opaque ‘‘handle’’ +passed to the client-specified routines passed as parameters +to <i>TIFFClientOpen</i>.</p> +</td> +</table> <a name="OPTIONS"></a> <h2>OPTIONS</h2> - - -<p style="margin-left:11%; margin-top: 1em">The open mode -parameter can include the following flags in addition to the -‘‘r’’, +<!-- INDENTATION --> +<table width="100%" border=0 rules="none" frame="void" + cols="2" cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="8%"></td> +<td width="91%"> +<p>The open mode parameter can include the following flags +in addition to the ‘‘r’’, ‘‘w’’, and ‘‘a’’ flags. Note however that option flags must follow the read-write-append specification.</p> - +</td> +</table> +<!-- TABS --> <table width="100%" border=0 rules="none" frame="void" - cellspacing="0" cellpadding="0"> + cols="5" cellspacing="0" cellpadding="0"> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>l</b></p></td> <td width="10%"></td> -<td width="78%"> - - -<p style="margin-top: 1em" valign="top">When creating a new -file force information be written with Little-Endian byte -order (but see below). By default the library will create -new files using the native <small>CPU</small> byte -order.</p> </td> +<td width="2%"> + +<p><b>l</b></p> +</td> +<td width="6%"></td> +<td width="80%"> + +<p>When creating a new file force information be written +with Little-Endian byte order (but see below). By default +the library will create new files using the native +<small>CPU</small> byte order.</p> +</td> +<td width="0%"> +</td> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>b</b></p></td> <td width="10%"></td> -<td width="78%"> - - -<p style="margin-top: 1em" valign="top">When creating a new -file force information be written with Big-Endian byte order -(but see below). By default the library will create new -files using the native <small>CPU</small> byte order.</p></td> +<td width="2%"> + +<p><b>b</b></p> +</td> +<td width="6%"></td> +<td width="80%"> + +<p>When creating a new file force information be written +with Big-Endian byte order (but see below). By default the +library will create new files using the native +<small>CPU</small> byte order.</p> +</td> +<td width="0%"> +</td> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>L</b></p></td> <td width="10%"></td> -<td width="78%"> - - -<p style="margin-top: 1em" valign="top">Force image data -that is read or written to be treated with bits filled from -Least Significant Bit ( <small>LSB</small> ) to Most -Significant Bit ( <small>MSB</small> ). Note that this is -the opposite to the way the library has worked from its -inception.</p> </td> +<td width="2%"> + +<p><b>L</b></p> +</td> +<td width="6%"></td> +<td width="80%"> + +<p>Force image data that is read or written to be treated +with bits filled from Least Significant Bit ( +<small>LSB</small> ) to Most Significant Bit ( +<small>MSB</small> ). Note that this is the opposite to the +way the library has worked from its inception.</p> +</td> +<td width="0%"> +</td> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>B</b></p></td> <td width="10%"></td> -<td width="78%"> - - -<p style="margin-top: 1em" valign="top">Force image data -that is read or written to be treated with bits filled from -Most Significant Bit ( <small>MSB</small> ) to Least -Significant Bit ( <small>LSB</small> ); this is the -default.</p> </td> +<td width="2%"> + +<p><b>B</b></p> +</td> +<td width="6%"></td> +<td width="80%"> + +<p>Force image data that is read or written to be treated +with bits filled from Most Significant Bit ( +<small>MSB</small> ) to Least Significant Bit ( +<small>LSB</small> ); this is the default.</p> +</td> +<td width="0%"> +</td> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>H</b></p></td> <td width="10%"></td> -<td width="78%"> - - -<p style="margin-top: 1em" valign="top">Force image data -that is read or written to be treated with bits filled in -the same order as the native <small>CPU.</small></p></td> +<td width="2%"> + +<p><b>H</b></p> +</td> +<td width="6%"></td> +<td width="80%"> + +<p>Force image data that is read or written to be treated +with bits filled in the same order as the native +<small>CPU.</small></p> +</td> +<td width="0%"> +</td> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>M</b></p></td> <td width="10%"></td> -<td width="78%"> - - -<p style="margin-top: 1em" valign="top">Enable the use of -memory-mapped files for images opened read-only. If the -underlying system does not support memory-mapped files or if -the specific image being opened cannot be memory-mapped then -the library will fallback to using the normal system -interface for reading information. By default the library -will attempt to use memory-mapped files.</p></td> +<td width="2%"> + +<p><b>M</b></p> +</td> +<td width="6%"></td> +<td width="80%"> + +<p>Enable the use of memory-mapped files for images opened +read-only. If the underlying system does not support +memory-mapped files or if the specific image being opened +cannot be memory-mapped then the library will fallback to +using the normal system interface for reading information. +By default the library will attempt to use memory-mapped +files.</p> +</td> +<td width="0%"> +</td> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>m</b></p></td> <td width="10%"></td> -<td width="78%"> +<td width="2%"> +<p><b>m</b></p> +</td> +<td width="6%"></td> +<td width="80%"> -<p style="margin-top: 1em" valign="top">Disable the use of -memory-mapped files.</p></td> +<p>Disable the use of memory-mapped files.</p> +</td> +<td width="0%"> +</td> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>C</b></p></td> <td width="10%"></td> -<td width="78%"> - - -<p style="margin-top: 1em" valign="top">Enable the use of -‘‘strip chopping’’ when reading -images that are comprised of a single strip or tile of -uncompressed data. Strip chopping is a mechanism by which -the library will automatically convert the single-strip -image to multiple strips, each of which has about 8 -Kilobytes of data. This facility can be useful in reducing -the amount of memory used to read an image because the -library normally reads each strip in its entirety. Strip -chopping does however alter the apparent contents of the -image because when an image is divided into multiple strips -it looks as though the underlying file contains multiple -separate strips. Finally, note that default handling of -strip chopping is a compile-time configuration parameter. -The default behaviour, for backwards compatibility, is to -enable strip chopping.</p></td> +<td width="2%"> + +<p><b>C</b></p> +</td> +<td width="6%"></td> +<td width="80%"> + +<p>Enable the use of ‘‘strip +chopping’’ when reading images that are +comprised of a single strip or tile of uncompressed data. +Strip chopping is a mechanism by which the library will +automatically convert the single-strip image to multiple +strips, each of which has about 8 Kilobytes of data. This +facility can be useful in reducing the amount of memory used +to read an image because the library normally reads each +strip in its entirety. Strip chopping does however alter the +apparent contents of the image because when an image is +divided into multiple strips it looks as though the +underlying file contains multiple separate strips. Finally, +note that default handling of strip chopping is a +compile-time configuration parameter. The default behaviour, +for backwards compatibility, is to enable strip +chopping.</p> +</td> +<td width="0%"> +</td> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>c</b></p></td> <td width="10%"></td> -<td width="78%"> - - -<p style="margin-top: 1em" valign="top">Disable the use of -strip chopping when reading images.</p></td> +<td width="2%"> + +<p><b>c</b></p> +</td> +<td width="6%"></td> +<td width="80%"> + +<p>Disable the use of strip chopping when reading +images.</p> +</td> +<td width="0%"> +</td> <tr valign="top" align="left"> -<td width="11%"></td> -<td width="1%"> - - -<p style="margin-top: 1em" valign="top"><b>h</b></p></td> <td width="10%"></td> -<td width="78%"> - - -<p style="margin-top: 1em" valign="top">Read TIFF header -only, do not load the first image directory. That could be -useful in case of the broken first directory. We can open -the file and proceed to the other directories.</p></td> +<td width="2%"> + +<p><b>h</b></p> +</td> +<td width="6%"></td> +<td width="80%"> + +<p>Read TIFF header only, do not load the first image +directory. That could be useful in case of the broken first +directory. We can open the file and proceed to the other +directories.</p> +</td> +<td width="0%"> +</td> </table> - <a name="BYTE ORDER"></a> <h2>BYTE ORDER</h2> - - -<p style="margin-left:11%; margin-top: 1em">The -<small>TIFF</small> specification (<b>all versions</b>) -states that compliant readers <i>must be capable of reading -images written in either byte order</i>. Nonetheless some -software that claims to support the reading of -<small>TIFF</small> images is incapable of reading images in -anything but the native <small>CPU</small> byte order on +<!-- INDENTATION --> +<table width="100%" border=0 rules="none" frame="void" + cols="2" cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="8%"></td> +<td width="91%"> +<p>The <small>TIFF</small> specification (<b>all +versions</b>) states that compliant readers <i>must be +capable of reading images written in either byte order</i>. +Nonetheless some software that claims to support the reading +of <small>TIFF</small> images is incapable of reading images +in anything but the native <small>CPU</small> byte order on which the software was written. (Especially notorious are applications written to run on Intel-based machines.) By default the library will create new files with the native @@ -333,66 +348,74 @@ byte-order when creating a new file the in the call to open a file; for example, ‘‘wb’’ or ‘‘wl’’.</p> - +</td> +</table> <a name="RETURN VALUES"></a> <h2>RETURN VALUES</h2> - - -<p style="margin-left:11%; margin-top: 1em">Upon successful -completion <i>TIFFOpen</i>, <i>TIFFFdOpen</i>, and -<i>TIFFClientOpen</i> return a <small>TIFF</small> pointer. -Otherwise, NULL is returned.</p> - +<!-- INDENTATION --> +<table width="100%" border=0 rules="none" frame="void" + cols="2" cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="8%"></td> +<td width="91%"> +<p>Upon successful completion <i>TIFFOpen</i>, +<i>TIFFFdOpen</i>, and <i>TIFFClientOpen</i> return a +<small>TIFF</small> pointer. Otherwise, NULL is +returned.</p> +</td> +</table> <a name="DIAGNOSTICS"></a> <h2>DIAGNOSTICS</h2> - - -<p style="margin-left:11%; margin-top: 1em">All error -messages are directed to the <i>TIFFError</i>(3TIFF) -routine. Likewise, warning messages are directed to the -<i>TIFFWarning</i>(3TIFF) routine.</p> - - -<p style="margin-left:11%; margin-top: 1em"><b>"%s": -Bad mode</b>. The specified <i>mode</i> parameter was not -one of ‘‘r’’ (read), +<!-- INDENTATION --> +<table width="100%" border=0 rules="none" frame="void" + cols="2" cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="8%"></td> +<td width="91%"> +<p>All error messages are directed to the +<i>TIFFError</i>(3TIFF) routine. Likewise, warning messages +are directed to the <i>TIFFWarning</i>(3TIFF) routine.</p> +<!-- INDENTATION --> +<p><b>"%s": Bad mode</b>. The specified +<i>mode</i> parameter was not one of +‘‘r’’ (read), ‘‘w’’ (write), or ‘‘a’’ (append).</p> - -<p style="margin-left:11%; margin-top: 1em"><b>%s: Cannot -open</b>. <i>TIFFOpen</i>() was unable to open the specified -filename for read/writing.</p> - -<p style="margin-left:11%; margin-top: 1em"><b>Cannot read -TIFF header</b>. An error occurred while attempting to read -the header information.</p> - -<p style="margin-left:11%; margin-top: 1em"><b>Error -writing TIFF header</b>. An error occurred while writing the -default header information for a new file.</p> - -<p style="margin-left:11%; margin-top: 1em"><b>Not a TIFF -file, bad magic number %d (0x%x)</b>. The magic number in -the header was not (hex) 0x4d4d or (hex) 0x4949.</p> - -<p style="margin-left:11%; margin-top: 1em"><b>Not a TIFF -file, bad version number %d (0x%x)</b>. The version field in -the header was not 42 (decimal).</p> - -<p style="margin-left:11%; margin-top: 1em"><b>Cannot -append to file that has opposite byte ordering</b>. A file -with a byte ordering opposite to the native byte ordering of -the current machine was opened for appending -(‘‘a’’). This is a limitation of the -library.</p> - +<!-- INDENTATION --> +<p><b>%s: Cannot open</b>. <i>TIFFOpen</i>() was unable to +open the specified filename for read/writing.</p> +<!-- INDENTATION --> +<p><b>Cannot read TIFF header</b>. An error occurred while +attempting to read the header information.</p> +<!-- INDENTATION --> +<p><b>Error writing TIFF header</b>. An error occurred while +writing the default header information for a new file.</p> +<!-- INDENTATION --> +<p><b>Not a TIFF file, bad magic number %d (0x%x)</b>. The +magic number in the header was not (hex) 0x4d4d or (hex) +0x4949.</p> +<!-- INDENTATION --> +<p><b>Not a TIFF file, bad version number %d (0x%x)</b>. The +version field in the header was not 42 (decimal).</p> +<!-- INDENTATION --> +<p><b>Cannot append to file that has opposite byte +ordering</b>. A file with a byte ordering opposite to the +native byte ordering of the current machine was opened for +appending (‘‘a’’). This is a +limitation of the library.</p> +</td> +</table> <a name="SEE ALSO"></a> <h2>SEE ALSO</h2> - - - -<p style="margin-left:11%; margin-top: 1em"><i>libtiff</i>(3TIFF), -<i>TIFFClose</i>(3TIFF)</p> +<!-- INDENTATION --> +<table width="100%" border=0 rules="none" frame="void" + cols="2" cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="8%"></td> +<td width="91%"> +<p><i>libtiff</i>(3TIFF), <i>TIFFClose</i>(3TIFF)</p> +</td> +</table> <hr> </body> </html> |