TIFFSetDirectory
================

Synopsis
--------

.. highlight:: c

::

    #include <tiffio.h>

.. c:function:: int TIFFSetDirectory(TIFF* tif, tdir_t dirnum)

.. c:function:: int TIFFSetSubDirectory(TIFF* tif, uint64_t diroff)

Description
-----------

:c:func:`TIFFSetDirectory` changes the current directory and reads its
contents with :c:func:`TIFFReadDirectory`.  The parameter *dirnum*
specifies the subfile/directory as an integer number, with the first
directory numbered zero.

:c:func:`TIFFSetSubDirectory` acts like :c:func:`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.

a. The ``SubIFD`` tag contains an array with all offsets of the SubIFDs.
b. 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 :c:func:`TIFFSetSubDirectory()`, :c:func:`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.
:c:func:`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 :c:func:`TIFFCurrentDirectory`,
:c:func:`TIFFCurrentDirOffset`, :c:func:`TIFFLastDirectory` and
:c:func:`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 :c:func:`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
--------

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