Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TIFFOpen(3TIFF)						       TIFFOpen(3TIFF)

NAME
       TIFFOpen,  TIFFFdOpen, TIFFClientOpen - open a TIFF file	for reading or
       writing

SYNOPSIS
       #include	<tiffio.h>

       TIFF* TIFFOpen(const char *filename, const char *mode)
       TIFF* TIFFFdOpen(const int fd, const char *filename, const char *mode)

       typedef tsize_t (*TIFFReadWriteProc)(thandle_t, tdata_t,	tsize_t);
       typedef toff_t (*TIFFSeekProc)(thandle_t, toff_t, int);
       typedef int (*TIFFCloseProc)(thandle_t);
       typedef toff_t (*TIFFSizeProc)(thandle_t);
       typedef int (*TIFFMapFileProc)(thandle_t, tdata_t*, toff_t*);
       typedef void (*TIFFUnmapFileProc)(thandle_t, tdata_t, toff_t);

       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)

DESCRIPTION
       TIFFOpen	 opens a TIFF file whose name is filename and returns a	handle
       to be used in subsequent	calls to routines in libtiff.  If the open op-
       eration	fails, then zero is returned.  The mode	parameter specifies if
       the file	is to be opened	for reading (``r''), writing (``w''),  or  ap-
       pending	(``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.

       If  a  file is opened for reading, the first TIFF directory in the file
       is automatically	read (also see TIFFSetDirectory(3TIFF) for reading di-
       rectories  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 TIFF Revision	6.0: BitsPerSample=1, ThreshHolding=bilevel art	 scan,
       FillOrder=1  (most  significant bit of each data	byte is	filled first),
       Orientation=1 (the 0th row represents the visual	top of the image,  and
       the  0th	 column	 represents  the  visual  left hand side), SamplesPer-
       Pixel=1,	RowsPerStrip=infinity, ResolutionUnit=2	(inches), and Compres-
       sion=1  (no  compression).   To alter these values, or to define	values
       for additional fields, TIFFSetField(3TIFF) must be used.

       TIFFFdOpen is like TIFFOpen except that it opens	a TIFF file  given  an
       open file descriptor fd.	 The file's name and mode must reflect that of
       the open	descriptor.  The object	associated with	 the  file  descriptor
       must support random access.

       TIFFClientOpen  is like TIFFOpen	except that the	caller supplies	a col-
       lection of functions that the library will use to do UNIX-like I/O  op-
       erations.  The readproc and writeproc are called	to read	and write data
       at the current file position.  seekproc is called to change the current
       file  position  a la lseek(2).  closeproc is invoked to release any re-
       sources associated with an open file.  sizeproc is  invoked  to	obtain
       the  size  in bytes of a	file.  mapproc and unmapproc are called	to map
       and unmap a file's contents in memory;  c.f.   mmap(2)  and  munmap(2).
       The  clientdata parameter is an opaque ``handle'' passed	to the client-
       specified routines passed as parameters to TIFFClientOpen.

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.

       l      When creating a new file force information be written with  Lit-
	      tle-Endian  byte	order (but see below).	By default the library
	      will create new files using the native CPU byte order.

       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	CPU byte order.

       L      Force image data that is read or written to be treated with bits
	      filled  from Least Significant Bit (LSB) to Most Significant Bit
	      (MSB).  Note that	this is	the opposite to	the  way  the  library
	      has worked from its inception.

       B      Force image data that is read or written to be treated with bits
	      filled from Most Significant Bit (MSB) to	Least Significant  Bit
	      (LSB); this is the default.

       H      Force image data that is read or written to be treated with bits
	      filled in	the same order as the native CPU.

       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.

       m      Disable the use of memory-mapped files.

       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 automat-
	      ically 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	behav-
	      iour, for	backwards compatibility, is to enable strip chopping.

       c      Disable the use of strip chopping	when reading images.

       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.

BYTE ORDER
       The  TIFF  specification	 (all  versions) states	that compliant readers
       must be capable of reading images written in either byte	order.	 None-
       theless some software that claims to support the	reading	of TIFF	images
       is incapable of reading images in anything but the native CPU byte  or-
       der  on	which the software was written.	 (Especially notorious are ap-
       plications written to run on Intel-based	machines.)  By default the li-
       brary  will  create  new	files with the native byte-order of the	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''.

RETURN VALUES
       Upon successful completion TIFFOpen, TIFFFdOpen,	and TIFFClientOpen re-
       turn a TIFF pointer.  Otherwise,	NULL is	returned.

DIAGNOSTICS
       All error messages are directed to the TIFFError(3TIFF) routine.	 Like-
       wise, warning messages are directed to the TIFFWarning(3TIFF) routine.

       "%s": Bad mode.	The specified mode parameter  was  not	one  of	 ``r''
       (read), ``w'' (write), or ``a'' (append).

       %s:  Cannot open.  TIFFOpen() was unable	to open	the specified filename
       for read/writing.

       Cannot read TIFF	header.	 An error occurred while  attempting  to  read
       the header information.

       Error writing TIFF header.  An error occurred while writing the default
       header information for a	new file.

       Not a TIFF file,	bad magic number %d (0x%x).  The magic number  in  the
       header was not (hex) 0x4d4d or (hex) 0x4949.

       Not  a  TIFF  file, bad version number %d (0x%x).  The version field in
       the header was not 42 (decimal).

       Cannot append to	file that has opposite byte ordering.  A file  with  a
       byte  ordering  opposite	to the native byte ordering of the current ma-
       chine was opened	for appending (``a'').	This is	a  limitation  of  the
       library.

SEE ALSO
       libtiff(3TIFF), TIFFClose(3TIFF)

libtiff				 July 1, 2005		       TIFFOpen(3TIFF)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | BYTE ORDER | RETURN VALUES | DIAGNOSTICS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=TIFFFdOpen&sektion=3tiff&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help