10139N/A<!
DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
10139N/A<!--ArborText, Inc., 1988-1999, v.4002-->
10139N/A<!
ENTITY suncopy "Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.">
10139N/A<
refmeta><
refentrytitle>TIFFOpen</
refentrytitle><
manvolnum>3tiff</
manvolnum>
10139N/A<
refmiscinfo class="date">05 Apr 2004</
refmiscinfo>
10139N/A<
refmiscinfo class="sectdesc">&man3;</
refmiscinfo>
10139N/A<
refmiscinfo class="software">&release;</
refmiscinfo>
10139N/A<
refmiscinfo class="arch">generic</
refmiscinfo>
10139N/A<
refmiscinfo class="copyright">&suncopy;</
refmiscinfo>
10139N/A<
indexterm><
primary>TIFFOpen</
primary></
indexterm><
indexterm><
primary>TIFFFdOpen
10139N/A</
primary></
indexterm><
indexterm><
primary>TIFFClientOpen</
primary></
indexterm>
10139N/A<
indexterm><
primary>open a TIFF file for reading or writing</
primary></
indexterm>
10139N/A<
refnamediv id="TIFFOpen-3tiff-name"><
refname>TIFFOpen</
refname><
refname>TIFFFdOpen
10139N/A</
refname><
refname>TIFFClientOpen</
refname><
refpurpose>open a TIFF file for
10139N/Areading or writing</
refpurpose></
refnamediv>
10139N/A<
refsect1 id="TIFFOpen-3tiff-synp"><
title>&synp-tt;</
title>
10139N/ATIFF* TIFFOpen(const char* filename, const char* mode)
10139N/ATIFF* TIFFFdOpen(const int fd, const char* filename, const char* mode)
10139N/Atypedef tsize_t (*TIFFReadWriteProc)(thandle_t, tdata_t, tsize_t);
10139N/Atypedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int);
10139N/Atypedef int (*TIFFCloseProc)(thandle_t);
10139N/Atypedef toff_t (*TIFFSizeProc)(thandle_t);
10139N/Atypedef int (*TIFFMapFileProc)(thandle_t, tdata_t*, toff_t*);
10139N/Atypedef void (*TIFFUnmapFileProc)(thandle_t, tdata_t, toff_t);
10139N/ATIFF* TIFFClientOpen(const char* filename, const char* mode,
10139N/A thandle_t clientdata,TIFFReadWriteProc readproc,
10139N/A TIFFReadWriteProc writeproc, TIFFSeekProc seekproc,
10139N/A TIFFCloseProc closeproc, TIFFSizeProc sizeproc,
10139N/A TIFFMapFileProc mapproc, TIFFUnmapFileProc unmapproc)</
programlisting>
10139N/A<
refsect1 id="TIFFOpen-3tiff-desc"><
title>&desc-tt;</
title>
10139N/A<
para><
literal>TIFFOpen</
literal> opens a TIFF file whose name is <
replaceable>
10139N/Afilename</
replaceable> and returns a handle to be used in subsequent calls
10139N/Ato routines in <
literal>libtiff</
literal>. If the open operation fails, then
10139N/A<
para>The <
literal>mode</
literal> parameter specifies whether the file is
10139N/Ato be opened for reading (“<
literal>r</
literal>”), writing (“<
literal>
10139N/Aw</
literal>”), or appending (“<
literal>a</
literal>”) and,
10139N/Aoptionally, whether to override certain default aspects of library operation
10139N/A(see below). When a file is opened for appending, existing data is not touched.
10139N/AInstead, new data is written as additional subfiles. If an existing file is
10139N/Aopened for writing, all previous data is overwritten.</
para>
10139N/A<
refsect1 id="TIFFOpen-3tiff-exde"><
title>&exde-tt;</
title>
10139N/A<
para>If a file is opened for reading, the first TIFF directory in the file
10139N/Ais automatically read. See also <
literal>TIFFSetDirectory(3tiff)</
literal> for
10139N/Ainformation on how to read directories other than the first. If a file is
10139N/Aopened for writing or appending, a default directory is automatically created
10139N/Afor writing subsequent data. This directory has all of the default values
10139N/Aspecified in TIFF Revision 6.0:</
para>
10139N/A<
listitem><
para><
literal>BitsPerSample=1</
literal></
para></
listitem>
10139N/A<
listitem><
para><
literal>ThreshHolding=bilevel art scan</
literal></
para></
listitem>
10139N/A<
listitem><
para><
literal>FillOrder=1</
literal> (most significant bit of each
10139N/Adata byte is filled first)</
para></
listitem>
10139N/A<
listitem><
para><
literal>Orientation=1</
literal> (the 0th row represents the
10139N/Avisual top of the image, and the 0th column represents the visual left-hand
10139N/A<
listitem><
para><
literal>SamplesPerPixel=1</
literal></
para></
listitem>
10139N/A<
listitem><
para><
literal>RowsPerStrip=infinity</
literal></
para></
listitem>
10139N/A<
listitem><
para><
literal>ResolutionUnit=2 (inches)</
literal></
para></
listitem>
10139N/A<
listitem><
para><
literal>Compression=1 (no compression)</
literal></
para></
listitem>
10139N/A<
para>To alter these values, or to define values for additional fields, <
literal>
10139N/ATIFFSetField(3tiff)</
literal> must be used.</
para>
10139N/A<
para><
literal>TIFFFdOpen</
literal> is like <
literal>TIFFOpen</
literal> except
10139N/Athat <
literal>TIFFFdOpen</
literal> opens a TIFF file given an open file descriptor <
literal>
10139N/Afd</
literal>. The file name and mode must reflect that of the open descriptor.
10139N/AThe object associated with the file descriptor must support random access.
10139N/A<
para><
literal>TIFFClientOpen</
literal> is like <
literal>TIFFOpen</
literal>
10139N/Aexcept that the caller supplies a collection of functions that the library
10139N/Auses to perform UNIX-like I/O operations:</
para>
10139N/A<
listitem><
para><
literal>readproc</
literal> and <
literal>writeproc</
literal>
10139N/Aare called to read and write data at the current file position.</
para></
listitem>
10139N/A<
listitem><
para><
literal>seekproc</
literal> is called to change the current
10139N/Afile position. See also <
literal>lseek(2)</
literal>.</
para></
listitem>
10139N/A<
listitem><
para><
literal>closeproc</
literal> is invoked to release any resources
10139N/Aassociated with an open file.</
para></
listitem>
10139N/A<
listitem><
para><
literal>sizeproc</
literal> is invoked to obtain the size
10139N/Ain bytes of a file.</
para></
listitem>
10139N/A<
listitem><
para><
literal>mapproc</
literal> and <
literal>unmapproc</
literal>
10139N/Aare called to map and unmap the contents of a file in memory. See also <
literal>
10139N/Ammap(2)</
literal> and <
literal>munmap(2)</
literal>.</
para></
listitem>
10139N/A<
listitem><
para>The <
literal>clientdata</
literal> parameter is an opaque “handle”
10139N/Apassed to the client-specified routines that are passed as parameters to <
literal>
10139N/ATIFFClientOpen</
literal>.</
para></
listitem>
10139N/A<
refsect2 id="TIFFOpen-3tiff-exde-byte">
10139N/A<
para>The TIFF specification (all versions) states that compliant readers
10139N/Amust be capable of reading images written in either byte order. However, some
10139N/Asoftware that claims to support the reading of TIFF images is incapable of
10139N/Areading images in anything but the native CPU byte order on which the software
10139N/Awas written. By default, the library creates new files with the native byte-order
10139N/Aof the CPU on which the application is run. This ensures optimal performance
10139N/Aand is portable to any application that conforms to the TIFF specification.
10139N/ATo force the library to use a specific byte-order when creating a new file,
10139N/Athe “<
literal>b</
literal>” and “<
literal>l</
literal>”
10139N/Aoption flags may be included in the call to open a file. For example, “<
literal>
10139N/Awb</
literal>” or “<
literal>wl</
literal>”.</
para>
10139N/A<
refsect2 id="TIFFOpen-3tiff-exde-diags">
10139N/A<
para>All error messages are directed to the <
literal>TIFFError(3tiff)</
literal>
10139N/Aroutine. Likewise, warning messages are directed to the <
literal>TIFFWarning(3tiff)
10139N/A<
varlistentry><
term>"%s": Bad mode.</
term><
listitem><
para>The specified mode
10139N/Aparameter is not one of “<
literal>r</
literal>” (read), “<
literal>
10139N/Aw</
literal>” (write), or “<
literal>a</
literal>” (append).
10139N/A<
varlistentry><
term>%s: Cannot open.</
term><
listitem><
para><
literal>TIFFOpen()
10139N/A</
literal> is unable to open the specified filename for reading or writing.
10139N/A<
varlistentry><
term>Cannot read TIFF header.</
term><
listitem><
para>An error
10139N/Aoccurred while attempting to read the header information.</
para>
10139N/A<
varlistentry><
term>Error writing TIFF header.</
term><
listitem><
para>An error
10139N/Aoccurred while writing the default header information for a new file.</
para>
10139N/A<
varlistentry><
term>Not a TIFF file, bad magic number %d (0x%x).</
term><
listitem>
10139N/A<
para>The magic number in the header was not (hex) <
literal>0x4d4d</
literal>
10139N/Aor (hex) <
literal>0x4949</
literal>.</
para>
10139N/A<
varlistentry><
term>Not a TIFF file, bad version number %d (0x%x).</
term>
10139N/A<
listitem><
para>The version field in the header was not <
literal>42</
literal>
10139N/A<
varlistentry><
term>Cannot append to file that has opposite byte ordering.<?
Pub Caret>
10139N/A</
term><
listitem><
para>A file with a byte ordering opposite to the native
10139N/Abyte ordering of the current machine was opened for appending (“<
literal>
10139N/Aa</
literal>”). This is a limitation of the library.</
para>
10139N/A<
refsect1 id="TIFFOpen-3tiff-opts"><
title>&opts-tt;</
title>
10139N/A<
para>The open <
literal>mode</
literal> parameter can include the following
10139N/Aflags in addition to the “r”, “w”, and “a”
10139N/Aflags. Note however that option flags must follow the read-write-append specification.
10139N/A<
varlistentry><
term><
option role="nodash">B</
option></
term><
listitem><
para>
10139N/AForce image data that is read or written to be treated with bits filled from
10139N/AMost Significant Bit (MSB) to Least Significant Bit (LSB). This is the default.
10139N/A<
varlistentry><
term><
option role="nodash">b</
option></
term><
listitem><
para>
10139N/AWhen creating a new file, force information to be written with Big-Endian
10139N/Abyte order (but see the Byte Order section of this reference page). By default,
10139N/Athe library creates new files using the native CPU byte order.</
para>
10139N/A<
varlistentry><
term><
option role="nodash">C</
option></
term><
listitem><
para>
10139N/AEnable the use of “strip chopping” when reading images that are
10139N/Acomprised of a single strip or tile of uncompressed data. Strip chopping is
10139N/Aa mechanism by which the library automatically converts the single-strip image
10139N/Ato multiple strips, each of which has about 8 Kilobytes of data. This facility
10139N/Acan be useful in reducing the amount of memory used to read an image because
10139N/Athe library normally reads each strip in its entirety. Strip chopping does
10139N/Ahowever alter the apparent contents of the image because when an image is
10139N/Adivided into multiple strips, the image looks as though the underlying file
10139N/Acontains multiple separate strips. Finally, note that default handling of
10139N/Astrip chopping is a compile-time configuration parameter. The default behaviour,
10139N/Afor backwards compatibility, is to enable strip chopping.</
para>
10139N/A<
varlistentry><
term><
option role="nodash">c</
option></
term><
listitem><
para>
10139N/ADisable the use of strip chopping when reading images.</
para>
10139N/A<
varlistentry><
term><
option role="nodash">H</
option></
term><
listitem><
para>
10139N/AForce image data that is read or written to be treated with bits filled in
10139N/Athe same order as the native CPU.</
para>
10139N/A<
varlistentry><
term><
option role="nodash">L</
option></
term><
listitem><
para>
10139N/AForce image data that is read or written to be treated with bits filled from
10139N/ALeast Significant Bit (LSB) to Most Significant Bit (MSB). Note that this
10139N/Ais the opposite to the way that the library has worked from its inception.
10139N/A<
varlistentry><
term><
option role="nodash">l</
option></
term><
listitem><
para>
10139N/AWhen creating a new file, force information to be written with Little-Endian
10139N/Abyte order (but see the Byte Order section of this reference page). By default,
10139N/Athe library creates new files using the native CPU byte order.</
para>
10139N/A<
varlistentry><
term><
option role="nodash">M</
option></
term><
listitem><
para>
10139N/AEnable the use of memory-mapped files for images opened as read-only. If the
10139N/Aunderlying system does not support memory-mapped files, or if the specific
10139N/Aimage being opened cannot be memory-mapped, the library uses the normal system
10139N/Ainterface for reading information. By default, the library attempts to use
10139N/A<
varlistentry><
term><
option role="nodash">m</
option></
term><
listitem><
para>
10139N/ADisable the use of memory-mapped files.</
para>
10139N/A<
refsect1 id="TIFFOpen-3tiff-rtrn"><
title>&rtrn-tt;</
title>
10139N/A<
para>Upon successful completion, <
literal>TIFFOpen</
literal>, <
literal>TIFFFdOpen
10139N/A</
literal>, and <
literal>TIFFClientOpen</
literal> return a TIFF pointer. Otherwise,
10139N/A<
refsect1 id="TIFFOpen-3tiff-attr"><
title>&attr-tt;</
title>
10139N/A<
para>See <
olink targetdocent="REFMAN5" localinfo="attributes-5"><
citerefentry>
10139N/A<
refentrytitle>attributes</
refentrytitle><
manvolnum>5</
manvolnum></
citerefentry></
olink>
10139N/Afor descriptions of the following attributes:</
para>
10139N/A<
tgroup cols="2" colsep="1" rowsep="1"><
colspec colname="COLSPEC0" colwidth="1*">
10139N/A<
colspec colname="COLSPEC1" colwidth="1*">
10139N/A<
row><
entry align="center" valign="middle">ATTRIBUTE TYPE</
entry><
entry align="center" 10139N/Avalign="middle">ATTRIBUTE VALUE</
entry></
row>
10139N/A<
row><
entry colname="COLSPEC0"><
para>Interface stability</
para></
entry><
entry 13623N/Acolname="COLSPEC1"><
para>Uncommitted</
para></
entry></
row>
10139N/A<
refsect1 id="TIFFOpen-3tiff-also"><
title>&also-tt;</
title>
10139N/A<!--Reference to another man page--> 10139N/A<!--Reference to a Help manual--> 10139N/A<
para><
citerefentry><
refentrytitle>libtiff</
refentrytitle><
manvolnum>3</
manvolnum>
10139N/A</
citerefentry>, <
citerefentry><
refentrytitle>TIFFClose</
refentrytitle><
manvolnum>
10139N/A3tiff</
manvolnum></
citerefentry></
para>
10139N/A<
refsect1 id="TIFFOpen-3tiff-note"><
title>¬e-tt;</
title>
10139N/A<
para>This man page was originally written by Sam Leffler. Updated by Breda McColgan, Sun Microsystems Inc., 2004.</
para>