TIFFSetDirectory

Synopsis

#include <tiffio.h>
int TIFFSetDirectory(TIFF *tif, tdir_t dirnum)
int TIFFSetSubDirectory(TIFF *tif, uint64_t diroff)

Description

TIFFSetDirectory() changes the current directory and reads its contents with TIFFReadDirectory(). The parameter dirnum specifies the subfile/directory as an integer number, with the first directory numbered zero.

TIFFSetSubDirectory() acts like TIFFSetDirectory(), except the directory is specified as a file offset instead of an index; this is required for accessing subdirectories linked through a SubIFD tag.

In the case of several SubIFDs of a main image, there are two possibilities that are not even mutually exclusive.

  1. The SubIFD tag contains an array with all offsets of the SubIFDs.

  2. The SubIFDs are concatenated with their NextIFD parameters to a SubIFD chain.

LibTiff does support SubIFD chains partially. When a SubIFD tag is activated with TIFFSetSubDirectory(), TIFFReadDirectory() is able to parse through the SubIFD chain. The tif_curdir is just incremented from its current value and thus gets arbitrary values when parsing through SubIFD chains. TIFFSetDirectory() only works with main-IFD chains because allways starts with the first main-IFD and thus is able to reset the SubIFD reading chain to the main-IFD chain.

Directory query functions TIFFCurrentDirectory(), TIFFCurrentDirOffset(), TIFFLastDirectory() and TIFFNumberOfDirectories() retrieve information about directories in an open TIFF file. Be aware that until a directory is not written to file AND read back, the query functions won't retrieve the correct information!

Return values

On successful return 1 is returned. Otherwise, 0 is returned if dirnum or diroff specifies a non-existent directory, or if an error was encountered while reading the directory's contents.

Diagnostics

All error messages are directed to the TIFFErrorExtR() routine.

"%s: Error fetching directory count":

An error was encountered while reading the "directory count" field.

"%s: Error fetching directory link":

An error was encountered while reading the "link value" that points to the next directory in a file.

See also

TIFFquery (3tiff), TIFFOpen (3tiff), TIFFCreateDirectory (3tiff), TIFFCustomDirectory (3tiff), TIFFWriteDirectory (3tiff), TIFFReadDirectory (3tiff), libtiff (3tiff)