NAME

TIFFCreateDirectory - routines to create a directory and retrieve information about directories

SYNOPSIS

#include <tiffio.h>

int TIFFCreateDirectory(TIFF *tif)

int TIFFFreeDirectory(TIFF *tif)

int TIFFUnlinkDirectory(TIFF *tif, tdir_t dirn)

DESCRIPTION

The following routines create or release a directory.

TIFFCreateDirectory() setup for a directory in a open TIFF file. The newly created directory will not exist on the file till TIFFWriteDirectory(), TIFFCheckpointDirectory(), TIFFFlush() or TIFFClose() is called. TIFFWriteDirectory() also creates a new directory, frees the *tif structure and sets up a new one.

TIFFFreeDirectory() releases allocated storage associated with a directory, especially custom-fields. However, the main part of the directory is not touched. Routine TIFFCleanup() calls TIFFFreeDirectory() to release the directory part of the tif structure.

TIFFUnlinkDirectory() unlink the specified directory from the directory chain. The parameter dirn specifies the subfile/directory as an integer number, with the first directory numbered one (1). This is different to TIFFSetDirectory() or TIFFCurrentDirectory() where the first directory starts with zero (0).

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!

NOTES

Be 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.

After libtiff version 4.6.0 TIFFCreateDirectory() 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.

DIAGNOSTICS

All error messages are directed to the TIFFErrorExtR() routine. Likewise, warning messages are directed to the TIFFWarningExtR() routine.

AUTHOR

LibTIFF contributors

COPYRIGHT

1988-2022, LibTIFF contributors