src/tiff/man/TIFFOpen.3tiff

   1 .\" $Id: TIFFOpen.3tiff,v 1.2 2005-07-01 12:36:22 dron Exp $
   2 .\"
   3 .\" Copyright (c) 1988-1997 Sam Leffler
   4 .\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
   5 .\"
   6 .\" Permission to use, copy, modify, distribute, and sell this software and
   7 .\" its documentation for any purpose is hereby granted without fee, provided
   8 .\" that (i) the above copyright notices and this permission notice appear in
   9 .\" all copies of the software and related documentation, and (ii) the names of
  10 .\" Sam Leffler and Silicon Graphics may not be used in any advertising or
  11 .\" publicity relating to the software without the specific, prior written
  12 .\" permission of Sam Leffler and Silicon Graphics.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
  15 .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
  16 .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  17 .\"
  18 .\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
  19 .\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
  20 .\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  21 .\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
  22 .\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  23 .\" OF THIS SOFTWARE.
  24 .\"
  25 .if n .po 0
  26 .TH TIFFOpen 3TIFF "July 1, 2005" "libtiff"
  27 .SH NAME
  28 TIFFOpen, TIFFFdOpen, TIFFClientOpen \- open a
  29 .SM TIFF
  30 file for reading or writing
  31 .SH SYNOPSIS
  32 .B "#include <tiffio.h>"
  33 .sp
  34 .BI "TIFF* TIFFOpen(const char *" filename ", const char *" mode ")"
  35 .br
  36 .BI "TIFF* TIFFFdOpen(const int " fd ", const char *" filename ", const char *" mode ")"
  37 .sp
  38 .B "typedef tsize_t (*TIFFReadWriteProc)(thandle_t, tdata_t, tsize_t);"
  39 .br
  40 .B "typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int);"
  41 .br
  42 .B "typedef int (*TIFFCloseProc)(thandle_t);"
  43 .br
  44 .B "typedef toff_t (*TIFFSizeProc)(thandle_t);"
  45 .br
  46 .B "typedef int (*TIFFMapFileProc)(thandle_t, tdata_t*, toff_t*);"
  47 .br
  48 .B "typedef void (*TIFFUnmapFileProc)(thandle_t, tdata_t, toff_t);"
  49 .sp
  50 .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 ")"
  51 .SH DESCRIPTION
  52 .IR TIFFOpen
  53 opens a
  54 .SM TIFF
  55 file whose name is
  56 .I filename
  57 and returns a handle to be used in subsequent calls to routines in
  58 .IR libtiff .
  59 If the open operation fails, then zero is returned.
  60 The
  61 .I mode
  62 parameter specifies if the file is to be opened for reading (``r''),
  63 writing (``w''), or appending (``a'') and, optionally, whether
  64 to override certain default aspects of library operation (see below).
  65 When a file is opened for appending, existing data will not
  66 be touched; instead new data will be written as additional subfiles.
  67 If an existing file is opened for writing, all previous data is
  68 overwritten.
  69 .PP
  70 If a file is opened for reading, the first
  71 .SM TIFF
  72 directory in the file is automatically read
  73 (also see
  74 .IR TIFFSetDirectory (3TIFF)
  75 for reading directories other than the first).
  76 If a file is opened for writing or appending, a default directory
  77 is automatically created for writing subsequent data.
  78 This directory has all the default values specified in
  79 .SM TIFF
  80 Revision 6.0:
  81 .IR BitsPerSample =1,
  82 .IR ThreshHolding "=bilevel art scan,"
  83 .IR FillOrder =1
  84 (most significant bit of each data byte is filled first),
  85 .IR Orientation =1
  86 (the 0th row represents the visual top of the image, and the 0th
  87 column represents the visual left hand side),
  88 .IR SamplesPerPixel =1,
  89 .IR RowsPerStrip =infinity,
  90 .IR ResolutionUnit =2
  91 (inches), and
  92 .IR Compression =1
  93 (no compression).
  94 To alter these values, or to define values for additional fields,
  95 .IR TIFFSetField (3TIFF)
  96 must be used.
  97 .PP
  98 .IR TIFFFdOpen
  99 is like
 100 .IR TIFFOpen
 101 except that it opens a
 102 .SM TIFF
 103 file given an open file descriptor
 104 .IR fd .
 105 The file's name and mode must reflect that of the open descriptor.
 106 The object associated with the file descriptor
 107 .BR "must support random access" .
 108 .PP
 109 .IR TIFFClientOpen
 110 is like
 111 .IR TIFFOpen
 112 except that the caller supplies a collection of functions that the
 113 library will use to do \s-1UNIX\s+1-like I/O operations.
 114 The
 115 .I readproc
 116 and
 117 .I writeproc
 118 are called to read and write data at the current file position.
 119 .I seekproc
 120 is called to change the current file position a la
 121 .IR lseek (2).
 122 .I closeproc
 123 is invoked to release any resources associated with an open file.
 124 .I sizeproc
 125 is invoked to obtain the size in bytes of a file.
 126 .I mapproc
 127 and
 128 .I unmapproc
 129 are called to map and unmap a file's contents in memory; c.f.
 130 .IR mmap (2)
 131 and
 132 .IR munmap (2).
 133 The
 134 .I clientdata
 135 parameter is an opaque ``handle'' passed to the client-specified
 136 routines passed as parameters to
 137 .IR TIFFClientOpen .
 138 .SH OPTIONS
 139 The open mode parameter can include the following flags in
 140 addition to the ``r'', ``w'', and ``a'' flags.
 141 Note however that option flags must follow the read-write-append
 142 specification.
 143 .TP
 144 .B l
 145 When creating a new file force information be written with
 146 Little-Endian byte order (but see below).
 147 By default the library will create new files using the native
 148 .SM CPU
 149 byte order.
 150 .TP
 151 .B b
 152 When creating a new file force information be written with
 153 Big-Endian byte order (but see below).
 154 By default the library will create new files using the native
 155 .SM CPU
 156 byte order.
 157 .TP
 158 .B L
 159 Force image data that is read or written to be treated with
 160 bits filled from Least Significant Bit (\s-1LSB\s+1) to
 161 Most Significant Bit (\s-1MSB\s+1).
 162 Note that this is the opposite to the way the library has
 163 worked from its inception.
 164 .TP
 165 .B B
 166 Force image data that is read or written to be treated with
 167 bits filled from Most Significant Bit (\s-1MSB\s+1) to
 168 Least Significant Bit (\s-1LSB\s+1); this is the default.
 169 .TP
 170 .B H
 171 Force image data that is read or written to be treated with
 172 bits filled in the same order as the native
 173 .SM CPU.
 174 .TP
 175 .B M
 176 Enable the use of memory-mapped files for images opened read-only.
 177 If the underlying system does not support memory-mapped files
 178 or if the specific image being opened cannot be memory-mapped
 179 then the library will fallback to using the normal system interface
 180 for reading information.
 181 By default the library will attempt to use memory-mapped files.
 182 .TP
 183 .B m
 184 Disable the use of memory-mapped files.
 185 .TP
 186 .B C
 187 Enable the use of ``strip chopping'' when reading images
 188 that are comprised of a single strip or tile of uncompressed data.
 189 Strip chopping is a mechanism by which the library will automatically
 190 convert the single-strip image to multiple strips,
 191 each of which has about 8 Kilobytes of data.
 192 This facility can be useful in reducing the amount of memory used
 193 to read an image because the library normally reads each strip
 194 in its entirety.
 195 Strip chopping does however alter the apparent contents of the
 196 image because when an image is divided into multiple strips it
 197 looks as though the underlying file contains multiple separate
 198 strips.
 199 Finally, note that default handling of strip chopping is a compile-time
 200 configuration parameter.
 201 The default behaviour, for backwards compatibility, is to enable
 202 strip chopping.
 203 .TP
 204 .B c
 205 Disable the use of strip chopping when reading images.
 206 .TP
 207 .B h
 208 Read TIFF header only, do not load the first image directory. That could be
 209 useful in case of the broken first directory. We can open the file and proceed
 210 to the other directories.
 211 .SH "BYTE ORDER"
 212 The
 213 .SM TIFF
 214 specification (\fBall versions\fP) states that compliant readers
 215 .IR "must be capable of reading images written in either byte order" .
 216 Nonetheless some software that claims to support the reading of
 217 .SM TIFF
 218 images is incapable of reading images in anything but the native
 219 .SM CPU
 220 byte order on which the software was written.
 221 (Especially notorious
 222 are applications written to run on Intel-based machines.)
 223 By default the library will create new files with the native
 224 byte-order of the
 225 .SM CPU
 226 on which the application is run.
 227 This ensures optimal performance and is portable to any application
 228 that conforms to the TIFF specification.
 229 To force the library to use a specific byte-order when creating
 230 a new file the ``b'' and ``l'' option flags may be included in
 231 the call to open a file; for example, ``wb'' or ``wl''.
 232 .SH "RETURN VALUES"
 233 Upon successful completion
 234 .IR TIFFOpen ,
 235 .IR TIFFFdOpen ,
 236 and
 237 .IR TIFFClientOpen
 238 return a
 239 .SM TIFF
 240 pointer.
 241 Otherwise, NULL is returned.
 242 .SH DIAGNOSTICS
 243 All error messages are directed to the
 244 .IR TIFFError (3TIFF)
 245 routine.
 246 Likewise, warning messages are directed to the
 247 .IR TIFFWarning (3TIFF)
 248 routine.
 249 .PP
 250 \fB"%s": Bad mode\fP.
 251 The specified
 252 .I mode
 253 parameter was not one of ``r'' (read), ``w'' (write), or ``a'' (append).
 254 .PP
 255 .BR "%s: Cannot open" .
 256 .IR TIFFOpen ()
 257 was unable to open the specified filename for read/writing.
 258 .PP
 259 .BR "Cannot read TIFF header" .
 260 An error occurred while attempting to read the header information.
 261 .PP
 262 .BR "Error writing TIFF header" .
 263 An error occurred while writing the default header information
 264 for a new file.
 265 .PP
 266 .BR "Not a TIFF file, bad magic number %d (0x%x)" .
 267 The magic number in the header was not (hex)
 268 0x4d4d or (hex) 0x4949.
 269 .PP
 270 .BR "Not a TIFF file, bad version number %d (0x%x)" .
 271 The version field in the header was not 42 (decimal).
 272 .PP
 273 .BR "Cannot append to file that has opposite byte ordering" .
 274 A file with a byte ordering opposite to the native byte
 275 ordering of the current machine was opened for appending (``a'').
 276 This is a limitation of the library.
 277 .SH "SEE ALSO"
 278 .IR libtiff (3TIFF),
 279 .IR TIFFClose (3TIFF)