summaryrefslogtreecommitdiff
path: root/tiff/man/TIFFOpen.3tiff
diff options
context:
space:
mode:
Diffstat (limited to 'tiff/man/TIFFOpen.3tiff')
-rw-r--r--tiff/man/TIFFOpen.3tiff279
1 files changed, 279 insertions, 0 deletions
diff --git a/tiff/man/TIFFOpen.3tiff b/tiff/man/TIFFOpen.3tiff
new file mode 100644
index 0000000..dfb4c45
--- /dev/null
+++ b/tiff/man/TIFFOpen.3tiff
@@ -0,0 +1,279 @@
+.\" $Id: TIFFOpen.3tiff,v 1.2 2005/07/01 12:36:22 dron Exp $
+.\"
+.\" Copyright (c) 1988-1997 Sam Leffler
+.\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
+.\"
+.\" Permission to use, copy, modify, distribute, and sell this software and
+.\" its documentation for any purpose is hereby granted without fee, provided
+.\" that (i) the above copyright notices and this permission notice appear in
+.\" all copies of the software and related documentation, and (ii) the names of
+.\" Sam Leffler and Silicon Graphics may not be used in any advertising or
+.\" publicity relating to the software without the specific, prior written
+.\" permission of Sam Leffler and Silicon Graphics.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
+.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
+.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
+.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
+.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
+.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+.\" OF THIS SOFTWARE.
+.\"
+.if n .po 0
+.TH TIFFOpen 3TIFF "July 1, 2005" "libtiff"
+.SH NAME
+TIFFOpen, TIFFFdOpen, TIFFClientOpen \- open a
+.SM TIFF
+file for reading or writing
+.SH SYNOPSIS
+.B "#include <tiffio.h>"
+.sp
+.BI "TIFF* TIFFOpen(const char *" filename ", const char *" mode ")"
+.br
+.BI "TIFF* TIFFFdOpen(const int " fd ", const char *" filename ", const char *" mode ")"
+.sp
+.B "typedef tsize_t (*TIFFReadWriteProc)(thandle_t, tdata_t, tsize_t);"
+.br
+.B "typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int);"
+.br
+.B "typedef int (*TIFFCloseProc)(thandle_t);"
+.br
+.B "typedef toff_t (*TIFFSizeProc)(thandle_t);"
+.br
+.B "typedef int (*TIFFMapFileProc)(thandle_t, tdata_t*, toff_t*);"
+.br
+.B "typedef void (*TIFFUnmapFileProc)(thandle_t, tdata_t, toff_t);"
+.sp
+.BI "TIFF* TIFFClientOpen(const char *" filename ", const char *" mode ", thandle_t " clientdata ", TIFFReadWriteProc " readproc ", TIFFReadWriteProc " writeproc ", TIFFSeekProc " seekproc ", TIFFCloseProc " closeproc ", TIFFSizeProc " sizeproc ", TIFFMapFileProc " mapproc ", TIFFUnmapFileProc " unmapproc ")"
+.SH DESCRIPTION
+.IR TIFFOpen
+opens a
+.SM TIFF
+file whose name is
+.I filename
+and returns a handle to be used in subsequent calls to routines in
+.IR libtiff .
+If the open operation fails, then zero is returned.
+The
+.I mode
+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.
+.PP
+If a file is opened for reading, the first
+.SM TIFF
+directory in the file is automatically read
+(also see
+.IR TIFFSetDirectory (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
+.SM TIFF
+Revision 6.0:
+.IR BitsPerSample =1,
+.IR ThreshHolding "=bilevel art scan,"
+.IR FillOrder =1
+(most significant bit of each data byte is filled first),
+.IR Orientation =1
+(the 0th row represents the visual top of the image, and the 0th
+column represents the visual left hand side),
+.IR SamplesPerPixel =1,
+.IR RowsPerStrip =infinity,
+.IR ResolutionUnit =2
+(inches), and
+.IR Compression =1
+(no compression).
+To alter these values, or to define values for additional fields,
+.IR TIFFSetField (3TIFF)
+must be used.
+.PP
+.IR TIFFFdOpen
+is like
+.IR TIFFOpen
+except that it opens a
+.SM TIFF
+file given an open file descriptor
+.IR fd .
+The file's name and mode must reflect that of the open descriptor.
+The object associated with the file descriptor
+.BR "must support random access" .
+.PP
+.IR TIFFClientOpen
+is like
+.IR TIFFOpen
+except that the caller supplies a collection of functions that the
+library will use to do \s-1UNIX\s+1-like I/O operations.
+The
+.I readproc
+and
+.I writeproc
+are called to read and write data at the current file position.
+.I seekproc
+is called to change the current file position a la
+.IR lseek (2).
+.I closeproc
+is invoked to release any resources associated with an open file.
+.I sizeproc
+is invoked to obtain the size in bytes of a file.
+.I mapproc
+and
+.I unmapproc
+are called to map and unmap a file's contents in memory; c.f.
+.IR mmap (2)
+and
+.IR munmap (2).
+The
+.I clientdata
+parameter is an opaque ``handle'' passed to the client-specified
+routines passed as parameters to
+.IR TIFFClientOpen .
+.SH OPTIONS
+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.
+.TP
+.B l
+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
+.SM CPU
+byte order.
+.TP
+.B b
+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
+.SM CPU
+byte order.
+.TP
+.B L
+Force image data that is read or written to be treated with
+bits filled from Least Significant Bit (\s-1LSB\s+1) to
+Most Significant Bit (\s-1MSB\s+1).
+Note that this is the opposite to the way the library has
+worked from its inception.
+.TP
+.B B
+Force image data that is read or written to be treated with
+bits filled from Most Significant Bit (\s-1MSB\s+1) to
+Least Significant Bit (\s-1LSB\s+1); this is the default.
+.TP
+.B H
+Force image data that is read or written to be treated with
+bits filled in the same order as the native
+.SM CPU.
+.TP
+.B M
+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.
+.TP
+.B m
+Disable the use of memory-mapped files.
+.TP
+.B C
+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.
+.TP
+.B c
+Disable the use of strip chopping when reading images.
+.TP
+.B h
+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.
+.SH "BYTE ORDER"
+The
+.SM TIFF
+specification (\fBall versions\fP) states that compliant readers
+.IR "must be capable of reading images written in either byte order" .
+Nonetheless some software that claims to support the reading of
+.SM TIFF
+images is incapable of reading images in anything but the native
+.SM CPU
+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
+.SM CPU
+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''.
+.SH "RETURN VALUES"
+Upon successful completion
+.IR TIFFOpen ,
+.IR TIFFFdOpen ,
+and
+.IR TIFFClientOpen
+return a
+.SM TIFF
+pointer.
+Otherwise, NULL is returned.
+.SH DIAGNOSTICS
+All error messages are directed to the
+.IR TIFFError (3TIFF)
+routine.
+Likewise, warning messages are directed to the
+.IR TIFFWarning (3TIFF)
+routine.
+.PP
+\fB"%s": Bad mode\fP.
+The specified
+.I mode
+parameter was not one of ``r'' (read), ``w'' (write), or ``a'' (append).
+.PP
+.BR "%s: Cannot open" .
+.IR TIFFOpen ()
+was unable to open the specified filename for read/writing.
+.PP
+.BR "Cannot read TIFF header" .
+An error occurred while attempting to read the header information.
+.PP
+.BR "Error writing TIFF header" .
+An error occurred while writing the default header information
+for a new file.
+.PP
+.BR "Not a TIFF file, bad magic number %d (0x%x)" .
+The magic number in the header was not (hex)
+0x4d4d or (hex) 0x4949.
+.PP
+.BR "Not a TIFF file, bad version number %d (0x%x)" .
+The version field in the header was not 42 (decimal).
+.PP
+.BR "Cannot append to file that has opposite byte ordering" .
+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.
+.SH "SEE ALSO"
+.IR libtiff (3TIFF),
+.IR TIFFClose (3TIFF)