TIFFCUSTOMDIRECTORY(3tiff) LibTIFF TIFFCUSTOMDIRECTORY(3tiff)
TIFFCustomDirectory - routines to create a custom directory
#include <tiffio.h>
int TIFFCreateCustomDirectory(TIFF *tif, const TIFFFieldArray
*infoarray)
int TIFFCreateEXIFDirectory(TIFF *tif)
int TIFFCreateGPSDirectory(TIFF *tif)
int TIFFWriteCustomDirectory(TIFF *tif, uint64 *pdiroff)
int TIFFReadCustomDirectory(TIFF *tif, toff_t diroff, const
TIFFFieldArray *infoarray)
int TIFFReadEXIFDirectory(TIFF *tif, toff_t diroff)
int TIFFReadGPSDirectory(TIFF *tif, toff_t diroff)
const TIFFFieldArray *_TIFFGetExifFields(void)
const TIFFFieldArray *_TIFFGetGpsFields(void)
The following routines create a custom directory and retrieve
information about directories in an open TIFF file.
TIFFCreateCustomDirectory(), TIFFCreateEXIFDirectory(),
TIFFCreateGPSDirectory() will setup a custom directory or one of the
predefined EXIF or GPS directories and set the context of the
TIFF-handle tif to that custom directory for functions like
TIFFSetField().
TIFFWriteCustomDirectory() will write the contents of the current
custom directory to the file and return the offset to that directory
in pdiroff. That offset has to be written to the main-IFD:
/* Go back to the first directory, and add the EXIFIFD pointer. */
TIFFSetDirectory(tif, 0);
TIFFSetField(tif, TIFFTAG_EXIFIFD, pdiroff);
TIFFReadCustomDirectory() will read the custom directory from the
arbitrary offset into the infoarray and sets the context of the
TIFF-handle tif to that custom directory for functions like
TIFFReadField(). The TIFFFieldArray infoarray has to be according the
layout of the custom directory. For the predefined EXIF and GPS
directories, the relevant TIFFFieldArray definitions are hidden
within the functions TIFFReadEXIFDirectory() and
TIFFReadGPSDirectory() The code is very similar to
TIFFReadDirectory(). The offset to the custom directory diroff has
to be read from the relative TIFF tag first.
_TIFFGetExifFields() and _TIFFGetGpsFields() will return a pointer
to the libtiff internal definition list of the EXIF and GPS tags,
respectively.
Be aware
+o that until a directory is not written to file AND read back, the
query functions won't retrieve the correct information!
+o that the newly created directory will not exist on the file till
TIFFWriteDirectory(), TIFFCheckpointDirectory(), TIFFFlush() or
TIFFClose() has been called.
+o that TIFFCreateDirectory() and TIFFWriteDirectory() create a new
directory, free the *tif structure and set up a new one.
+o that unlike TIFFWriteDirectory(), TIFFCheckpointDirectory() does
not free up the directory data structures in memory.
+o that LibTiff does not support custom directory chains (NextIFD
pointing to another IFD). NextIFD of custom directories is always
set to zero and should be zero when reading.
Unfortunately to create or read custom directories with predefined
fields it is necessary to include the private tif_dir.h. However, for
EXIF and GPS directories, which have a predefined schema within
libtiff, this is not necessary. There are some test programmes that
briefly demonstrate the creation and reading of EXIF, GPS and custom
directories. See test/custom_dir.c and test/custom_dir_EXIF_231.c
After libtiff version 4.6.0 TIFFCreateCustomDirectory(),
TIFFCreateEXIFDirectory() and TIFFCreateGPSDirectory() also releases
the directory part of the tif structure by calling
TIFFFreeDirectory(), which should have been called by the user
application before creating a new directory.
Writing TIFF files with more than one directory (IFD) is not easy
because some side effects need to be known.
The main point here is that there can only be one tif structure in
the main memory for a file, which can only hold the tags of one
directory at a time. It is useless to work with two different
tiffOut1, tiffOut2 pointers, because there is only ONE TIFF object
(TIFF directory) within the libtiff. If you want to address a second
directory in the file, the tags of the current directory must first
be saved in the file, otherwise they will be lost (overwritten or
mixed). Then the tif structure in the main memory must be tidied up,
otherwise the old tags will beincluded in the new directory. This
can be done either by creating a new, empty tif structure or by
reading in an directory previously saved in the file.
A sequence to handle a second (or third) TIFF directory - in this
case the GPS IFD - is as follows:
1. Create TIFF file
2. Complete the "normal" metadata
3. Set the tag for the custom directory with a "dummy" value in order
to get the tag reserved. The final value will be inserted lateron.
This prevents the main directory from being written to the file
again at an additional area, leaving the first memory area unused:
TIFFSetField(tiffOut, TIFFTAG_GPSIFD, dir_offset);
4. Save current TIFF-directory to file. Otherwise, it will be lost.
Remember also the number of the current directory:
TIFFWriteDirectory(tiffOut);
dirNum = TIFFCurrentDirectory(tiffOut);
5. Create the second TIFF-directory (e.g. custom directory) and set
its fields. The TIFFFieldArray infoarray has to be specified
beforehand somewhere in your private include files. An example is
given for the EXIF directory in tif_dirinfo.c
TIFFCreateCustomDirectory(tiffOut, infoarray); /* for a real custom directory */
/* or alternatively, use GPS or EXIF with pre-defined TIFFFieldArray IFD field structure */
TIFFCreateGPSDirectory(tiffOut);
TIFFSetField(tiffOut, GPSTAG_VERSIONID, gpsVersion); /* set fields of the custom directory */
Be aware that every TIFFCreateDirectory() or TIFFWriteDirectory()
apparently frees the *tif structure and sets up a new one!
6. Write custom directory to file. The offset to that directory in
the file is returned in dir_offset.
TIFFWriteCustomDirectory(tiffOut, &dir_offset);
7. Reload the first directory (i.e. the original TIFF directory).
Apparently, this reads the data back from file.
TIFFSetDirectory(tiffOut, dirNum);
8. Set the correct offset value of the custom directory IFD tag and
save that changes to file.
TIFFSetField(tiffOut, TIFFTAG_GPSIFD, dir_offset);
TIFFWriteDirectory(tiffOut);
1 is returned when the contents are successfully written to the file.
Otherwise, 0 is returned if an error was encountered when writing the
directory contents.
All error messages are directed to the TIFFErrorExtR() routine.
Likewise, warning messages are directed to the TIFFWarningExtR()
routine.
libtiff (3tiff), TIFFCreateDirectory (3tiff), TIFFquery (3tiff),
TIFFSetDirectory (3tiff), TIFFWriteDirectory (3tiff)
LibTIFF contributors
1988-2025, LibTIFF contributors
4.7 March 7, 2026 TIFFCUSTOMDIRECTORY(3tiff)
NAME
TIFFCustomDirectory - routines to create a custom directory
SYNOPSIS
#include <tiffio.h>
int TIFFCreateCustomDirectory(TIFF *tif, const TIFFFieldArray
*infoarray)
int TIFFCreateEXIFDirectory(TIFF *tif)
int TIFFCreateGPSDirectory(TIFF *tif)
int TIFFWriteCustomDirectory(TIFF *tif, uint64 *pdiroff)
int TIFFReadCustomDirectory(TIFF *tif, toff_t diroff, const
TIFFFieldArray *infoarray)
int TIFFReadEXIFDirectory(TIFF *tif, toff_t diroff)
int TIFFReadGPSDirectory(TIFF *tif, toff_t diroff)
const TIFFFieldArray *_TIFFGetExifFields(void)
const TIFFFieldArray *_TIFFGetGpsFields(void)
DESCRIPTION
The following routines create a custom directory and retrieve
information about directories in an open TIFF file.
TIFFCreateCustomDirectory(), TIFFCreateEXIFDirectory(),
TIFFCreateGPSDirectory() will setup a custom directory or one of the
predefined EXIF or GPS directories and set the context of the
TIFF-handle tif to that custom directory for functions like
TIFFSetField().
TIFFWriteCustomDirectory() will write the contents of the current
custom directory to the file and return the offset to that directory
in pdiroff. That offset has to be written to the main-IFD:
/* Go back to the first directory, and add the EXIFIFD pointer. */
TIFFSetDirectory(tif, 0);
TIFFSetField(tif, TIFFTAG_EXIFIFD, pdiroff);
TIFFReadCustomDirectory() will read the custom directory from the
arbitrary offset into the infoarray and sets the context of the
TIFF-handle tif to that custom directory for functions like
TIFFReadField(). The TIFFFieldArray infoarray has to be according the
layout of the custom directory. For the predefined EXIF and GPS
directories, the relevant TIFFFieldArray definitions are hidden
within the functions TIFFReadEXIFDirectory() and
TIFFReadGPSDirectory() The code is very similar to
TIFFReadDirectory(). The offset to the custom directory diroff has
to be read from the relative TIFF tag first.
_TIFFGetExifFields() and _TIFFGetGpsFields() will return a pointer
to the libtiff internal definition list of the EXIF and GPS tags,
respectively.
NOTES
Be aware
+o that until a directory is not written to file AND read back, the
query functions won't retrieve the correct information!
+o that the newly created directory will not exist on the file till
TIFFWriteDirectory(), TIFFCheckpointDirectory(), TIFFFlush() or
TIFFClose() has been called.
+o that TIFFCreateDirectory() and TIFFWriteDirectory() create a new
directory, free the *tif structure and set up a new one.
+o that unlike TIFFWriteDirectory(), TIFFCheckpointDirectory() does
not free up the directory data structures in memory.
+o that LibTiff does not support custom directory chains (NextIFD
pointing to another IFD). NextIFD of custom directories is always
set to zero and should be zero when reading.
Unfortunately to create or read custom directories with predefined
fields it is necessary to include the private tif_dir.h. However, for
EXIF and GPS directories, which have a predefined schema within
libtiff, this is not necessary. There are some test programmes that
briefly demonstrate the creation and reading of EXIF, GPS and custom
directories. See test/custom_dir.c and test/custom_dir_EXIF_231.c
After libtiff version 4.6.0 TIFFCreateCustomDirectory(),
TIFFCreateEXIFDirectory() and TIFFCreateGPSDirectory() also releases
the directory part of the tif structure by calling
TIFFFreeDirectory(), which should have been called by the user
application before creating a new directory.
HINTS AND DETAILED INSTRUCTIONS
Writing TIFF files with more than one directory (IFD) is not easy
because some side effects need to be known.
The main point here is that there can only be one tif structure in
the main memory for a file, which can only hold the tags of one
directory at a time. It is useless to work with two different
tiffOut1, tiffOut2 pointers, because there is only ONE TIFF object
(TIFF directory) within the libtiff. If you want to address a second
directory in the file, the tags of the current directory must first
be saved in the file, otherwise they will be lost (overwritten or
mixed). Then the tif structure in the main memory must be tidied up,
otherwise the old tags will beincluded in the new directory. This
can be done either by creating a new, empty tif structure or by
reading in an directory previously saved in the file.
A sequence to handle a second (or third) TIFF directory - in this
case the GPS IFD - is as follows:
1. Create TIFF file
2. Complete the "normal" metadata
3. Set the tag for the custom directory with a "dummy" value in order
to get the tag reserved. The final value will be inserted lateron.
This prevents the main directory from being written to the file
again at an additional area, leaving the first memory area unused:
TIFFSetField(tiffOut, TIFFTAG_GPSIFD, dir_offset);
4. Save current TIFF-directory to file. Otherwise, it will be lost.
Remember also the number of the current directory:
TIFFWriteDirectory(tiffOut);
dirNum = TIFFCurrentDirectory(tiffOut);
5. Create the second TIFF-directory (e.g. custom directory) and set
its fields. The TIFFFieldArray infoarray has to be specified
beforehand somewhere in your private include files. An example is
given for the EXIF directory in tif_dirinfo.c
TIFFCreateCustomDirectory(tiffOut, infoarray); /* for a real custom directory */
/* or alternatively, use GPS or EXIF with pre-defined TIFFFieldArray IFD field structure */
TIFFCreateGPSDirectory(tiffOut);
TIFFSetField(tiffOut, GPSTAG_VERSIONID, gpsVersion); /* set fields of the custom directory */
Be aware that every TIFFCreateDirectory() or TIFFWriteDirectory()
apparently frees the *tif structure and sets up a new one!
6. Write custom directory to file. The offset to that directory in
the file is returned in dir_offset.
TIFFWriteCustomDirectory(tiffOut, &dir_offset);
7. Reload the first directory (i.e. the original TIFF directory).
Apparently, this reads the data back from file.
TIFFSetDirectory(tiffOut, dirNum);
8. Set the correct offset value of the custom directory IFD tag and
save that changes to file.
TIFFSetField(tiffOut, TIFFTAG_GPSIFD, dir_offset);
TIFFWriteDirectory(tiffOut);
RETURN VALUES
1 is returned when the contents are successfully written to the file.
Otherwise, 0 is returned if an error was encountered when writing the
directory contents.
DIAGNOSTICS
All error messages are directed to the TIFFErrorExtR() routine.
Likewise, warning messages are directed to the TIFFWarningExtR()
routine.
SEE ALSO
libtiff (3tiff), TIFFCreateDirectory (3tiff), TIFFquery (3tiff),
TIFFSetDirectory (3tiff), TIFFWriteDirectory (3tiff)
AUTHOR
LibTIFF contributors
COPYRIGHT
1988-2025, LibTIFF contributors
4.7 March 7, 2026 TIFFCUSTOMDIRECTORY(3tiff)