c3402403ea
be used if build directory is not the same as source directory.
* man/{TIFFGetField.3tiff, man/TIFFSetField.3tiff}: Documented
TIFFTAG_PHOTOSHOP, TIFFTAG_RICHTIFFIPTC, and TIFFTAG_XMLPACKET,
and re-sorted tag names in alphabetical order.
399 lines
13 KiB
HTML
399 lines
13 KiB
HTML
<!-- 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">
|
|
<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>
|
|
<a href="#OPTIONS">OPTIONS</a><br>
|
|
<a href="#BYTE ORDER">BYTE ORDER</a><br>
|
|
<a href="#RETURN VALUES">RETURN VALUES</a><br>
|
|
<a href="#DIAGNOSTICS">DIAGNOSTICS</a><br>
|
|
<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
|
|
<small>TIFF</small> file for reading or writing</p>
|
|
|
|
<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>
|
|
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>
|
|
typedef int (*TIFFMapFileProc)(thandle_t, tdata_t*,
|
|
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>
|
|
<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>
|
|
|
|
<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
|
|
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
|
|
(‘‘r’’), writing
|
|
(‘‘w’’), or appending
|
|
(‘‘a’’) and, optionally, whether to
|
|
override certain default aspects of library operation (see
|
|
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),
|
|
<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>
|
|
|
|
<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’’,
|
|
‘‘w’’, and
|
|
‘‘a’’ flags. Note however that
|
|
option flags must follow the read-write-append
|
|
specification.</p>
|
|
|
|
<table width="100%" border=0 rules="none" frame="void"
|
|
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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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">Disable the use of
|
|
memory-mapped files.</p></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>
|
|
<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>
|
|
<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>
|
|
</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
|
|
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
|
|
byte-order of the <small>CPU</small> on which the
|
|
application is run. This ensures optimal performance and is
|
|
portable to any application that conforms to the TIFF
|
|
specification. To force the library to use a specific
|
|
byte-order when creating a new file the
|
|
‘‘b’’ and
|
|
‘‘l’’ option flags may be included
|
|
in the call to open a file; for example,
|
|
‘‘wb’’ or
|
|
‘‘wl’’.</p>
|
|
|
|
<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>
|
|
|
|
<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),
|
|
‘‘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>
|
|
|
|
<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>
|
|
<hr>
|
|
</body>
|
|
</html>
|