From eee54b38ec37b723fdcf904035cbd3d692ffa308 Mon Sep 17 00:00:00 2001
From: Su Laus <[EMAIL REDACTED]>
Date: Sun, 20 Nov 2022 19:39:22 +0000
Subject: [PATCH] manpage: fix28, fix440, update TIFFOpen and SubIFD
---
doc/functions/TIFFClose.rst | 3 ++-
doc/functions/TIFFCreateDirectory.rst | 4 ++++
doc/functions/TIFFCustomDirectory.rst | 4 ++++
doc/functions/TIFFGetField.rst | 2 +-
doc/functions/TIFFOpen.rst | 11 ++++++++++-
doc/functions/TIFFSetDirectory.rst | 16 ++++++++++++++++
doc/functions/TIFFquery.rst | 6 ++++--
doc/tools/tiffcrop.rst | 2 +-
8 files changed, 42 insertions(+), 6 deletions(-)
diff --git a/doc/functions/TIFFClose.rst b/doc/functions/TIFFClose.rst
index df8f0834..9e84b9eb 100644
--- a/doc/functions/TIFFClose.rst
+++ b/doc/functions/TIFFClose.rst
@@ -20,7 +20,8 @@ Description
:c:func:`TIFFClose` closes a file that was previously opened with
:c:func:`TIFFOpen`. Any buffered data are flushed to the file, including
the contents of the current directory (if modified); and all resources
-are reclaimed.
+are reclaimed. :c:func:`TIFFClose` calls :c:func:`TIFFCleanup` and then
+the associated function to close the file handle.
:c:func:`TIFFCleanup` is an auxiliary function to free the TIFF structure.
The given structure will be completely freed, so you should save opened file
diff --git a/doc/functions/TIFFCreateDirectory.rst b/doc/functions/TIFFCreateDirectory.rst
index 7ab16b73..5a427656 100644
--- a/doc/functions/TIFFCreateDirectory.rst
+++ b/doc/functions/TIFFCreateDirectory.rst
@@ -36,6 +36,10 @@ the directory part of the `tif` structure.
:c:func:`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 :c:func:`TIFFSetDirectory` or :c:func:`TIFFCurrentDirectory` where the first
+directory starts with zero (0).
Directory query functions :c:func:`TIFFCurrentDirectory`,
:c:func:`TIFFCurrentDirOffset`, :c:func:`TIFFLastDirectory` and
diff --git a/doc/functions/TIFFCustomDirectory.rst b/doc/functions/TIFFCustomDirectory.rst
index d91517e5..d26679d2 100644
--- a/doc/functions/TIFFCustomDirectory.rst
+++ b/doc/functions/TIFFCustomDirectory.rst
@@ -82,6 +82,10 @@ Be aware
create a new directory, free the ``*tif`` structure and set up a new one.
- that unlike :c:func:`TIFFWriteDirectory`, :c:func:`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, for EXIF and
diff --git a/doc/functions/TIFFGetField.rst b/doc/functions/TIFFGetField.rst
index 59bcb970..b62c7892 100644
--- a/doc/functions/TIFFGetField.rst
+++ b/doc/functions/TIFFGetField.rst
@@ -327,7 +327,7 @@ information on the meaning of each tag and their possible values.
* - :c:macro:`TIFFTAG_STONITS`
- 1
- - :c:expr:`const double**`
+ - :c:expr:`double*`
-
* - :c:macro:`TIFFTAG_STRIPBYTECOUNTS`
diff --git a/doc/functions/TIFFOpen.rst b/doc/functions/TIFFOpen.rst
index 91d4ee27..42b93c78 100644
--- a/doc/functions/TIFFOpen.rst
+++ b/doc/functions/TIFFOpen.rst
@@ -52,7 +52,7 @@ overwritten.
If a file is opened for reading, the first TIFF directory in the file
is automatically read (also see :c:func:`TIFFSetDirectory` for reading
-directories other than the first).
+directories other than the first).
If a file is opened for writing or appending, a default directory
is automatically created for writing subsequent data.
This directory has all the default values specified in TIFF Revision 6.0:
@@ -70,12 +70,21 @@ This directory has all the default values specified in TIFF Revision 6.0:
To alter these values, or to define values for additional fields,
:c:func:`TIFFSetField` must be used.
+A file can also be opened for reading and writing with *mode* (``r+``).
+In this case, the first TIFF directory in the file is automatically read,
+but calls to :c:func:`TIFFSetField` are put into a fresh directory, which
+will be appended when the file is closed.
+
:c:func:`TIFFOpenW` opens a TIFF file with a Unicode filename, for read/writing.
:c:func:`TIFFFdOpen` is like :c:func:`TIFFOpen` except that it opens a
TIFF file given an open file descriptor *fd*.
The file's name and mode must reflect that of the open descriptor.
The object associated with the file descriptor **must support random access**.
+In order to close a TIFF file opened with :c:func:`TIFFFdOpen`
+first :c:func:`TIFFCleanup` should be called to free the internal
+TIFF structure without closing the file handle and afterwards the
+file should be closed using its file descriptor *fd*.
:c:func:`TIFFSetFileName` sets the file name in the tif-structure
and returns the old file name.
diff --git a/doc/functions/TIFFSetDirectory.rst b/doc/functions/TIFFSetDirectory.rst
index 1e8d77a7..cda54939 100644
--- a/doc/functions/TIFFSetDirectory.rst
+++ b/doc/functions/TIFFSetDirectory.rst
@@ -27,6 +27,22 @@ 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
diff --git a/doc/functions/TIFFquery.rst b/doc/functions/TIFFquery.rst
index 58b092ad..6a03c626 100644
--- a/doc/functions/TIFFquery.rst
+++ b/doc/functions/TIFFquery.rst
@@ -51,8 +51,10 @@ The following query routines return status information about the directory
structure of an open TIFF file.
:c:func:`TIFFCurrentDirectory` returns the index of the current directory
-(directories are numbered starting at 0). This number is suitable for use
-with the :c:func:`TIFFSetDirectory` routine.
+(directories are numbered starting at 0). This number is suitable for
+use with the :c:func:`TIFFSetDirectory` routine.
+A value of 65535 (non-existing directory) is returned if the directory
+has not yet been written to the file after opening it.
:c:func:`TIFFCurrentDirOffset` returns the file offset of the current
directory (instead of an index).
diff --git a/doc/tools/tiffcrop.rst b/doc/tools/tiffcrop.rst
index b5e8e744..d7d89ca1 100644
--- a/doc/tools/tiffcrop.rst
+++ b/doc/tools/tiffcrop.rst
@@ -422,7 +422,7 @@ However, not all option combinations are permitted.
Note 2: Any of the -X, -Y, -Z and -z options together with other PAGE_MODE_x options
such as -H, -V, -P, -J or -K are not supported and may cause buffer overflows.
-
+
Examples
--------