TIFFCUSTOMDIRECTORY(3tiff)

💖 TIFFCUSTOMDIRECTORY 💖

hey bestie 🫶 welcome to the TIFFCUSTOMDIRECTORY(3tiff) page — that's the LibTIFF manual, section 3, and yes we're about to make custom TIFF directories together like the iconic little hackers we are. no gatekeeping, let's go ✨

---

✨ NAME ✨

TIFFCustomDirectory — the routines that create a custom directory. that's it, that's the whole vibe. 💅

---

✨ 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 ✨

so the whole squad of routines here does two things: create a custom directory, and pull info back out about directories inside a TIFF file you already have open. lowkey iconic.

TIFFCreateCustomDirectory(), TIFFCreateEXIFDirectory() and TIFFCreateGPSDirectory() will set up 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(). yes bestie, the handle is now pointing at your new directory. main character energy.

TIFFWriteCustomDirectory() will write the contents of the current custom directory to the file and return the offset to that directory in pdiroff. and that offset? it has to be written to the main-IFD, no cap:

/* 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 set the context of the TIFF-handle tif to that custom directory, for functions like TIFFReadField(). the TIFFFieldArray infoarray has to match the layout of the custom directory — like, it has to be according to it, fr fr. for the predefined EXIF and GPS directories, the relevant TIFFFieldArray definitions are hidden away inside the functions TIFFReadEXIFDirectory() and TIFFReadGPSDirectory(). the code is very similar to TIFFReadDirectory(). and 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. just handing you the whole list. obsessed. 🦋

---

⚠️ NOTES ⚠️

be aware, bestie. like, actually aware. 🙈

• that until a directory is not written to file AND read back, the query functions won't retrieve the correct information!
• that the newly created directory will not exist on the file till TIFFWriteDirectory(), TIFFCheckpointDirectory(), TIFFFlush() or TIFFClose() has been called.
• that TIFFCreateDirectory() and TIFFWriteDirectory() create a new directory, free the *tif structure and set up a new one.
• that unlike TIFFWriteDirectory(), TIFFCheckpointDirectory() does not free up the directory data structures in memory.
• 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 — and this is the good part — 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 release the directory part of the tif structure by calling TIFFFreeDirectory() — which should have been called by the user application before creating a new directory. so like, do that. 🫡

---

🌈 HINTS AND DETAILED INSTRUCTIONS 🌈

writing TIFF files with more than one directory (IFD) is not easy, bestie, because some side effects need to be known. this is the part where we hold hands. 🤝

the main point here is that there can only be one tif structure in the main memory for a file, and it 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 be included in the new directory. this can be done either by creating a new, empty tif structure or by reading in a 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. that's the whole deal — one or zero, no in-between. 🎯

---

🩺 DIAGNOSTICS 🩺

all error messages are directed to the TIFFErrorExtR() routine. likewise, warning messages are directed to the TIFFWarningExtR() routine. they're just sitting there catching everything for you, bestie. 🫶

---

👀 SEE ALSO 👀

• libtiff (3tiff)
• TIFFCreateDirectory (3tiff)
• TIFFquery (3tiff)
• TIFFSetDirectory (3tiff)
• TIFFWriteDirectory (3tiff)

---

💜 AUTHOR 💜

LibTIFF contributors — the collective, the icons, the group chat that actually ships.

---

©️ COPYRIGHT ©️

1988-2025, LibTIFF contributors

---

and that's a wrap, gorgeous 💅 this was version 4.7, dated Jun 27, 2026, brought to you by the LibTIFF contributors. go forth and write those custom directories, you absolute legend. periodt. 👑✨