libtiff: Merge branch 'manpage_re-entrant_error_handler' into 'master'

From a2c551ee06bc5f07b50795d14415c7baaeb74361 Mon Sep 17 00:00:00 2001
From: Su Laus <[EMAIL REDACTED]>
Date: Mon, 28 Nov 2022 23:16:00 +0000
Subject: [PATCH] manpage update for re-entrant error handler TIFFErrorExtR(),
 TIFFOpenExt() and...

---
 doc/functions.rst                             |  1 +
 doc/functions/TIFFClose.rst                   |  4 +-
 doc/functions/TIFFCreateDirectory.rst         |  4 +-
 doc/functions/TIFFCustomDirectory.rst         |  4 +-
 doc/functions/TIFFDeferStrileArrayWriting.rst |  4 +-
 doc/functions/TIFFError.rst                   | 79 +++++++++++++------
 doc/functions/TIFFFlush.rst                   |  2 +-
 doc/functions/TIFFGetField.rst                |  2 +-
 doc/functions/TIFFOpen.rst                    | 68 +++++++---------
 doc/functions/TIFFOpenOptions.rst             | 69 ++++++++++++++++
 doc/functions/TIFFRGBAImage.rst               |  2 +-
 doc/functions/TIFFReadDirectory.rst           |  4 +-
 doc/functions/TIFFReadEncodedStrip.rst        |  2 +-
 doc/functions/TIFFReadEncodedTile.rst         |  2 +-
 doc/functions/TIFFReadFromUserBuffer.rst      |  2 +-
 doc/functions/TIFFReadRGBAImage.rst           |  2 +-
 doc/functions/TIFFReadRGBAStrip.rst           |  2 +-
 doc/functions/TIFFReadRGBATile.rst            |  2 +-
 doc/functions/TIFFReadRawStrip.rst            |  2 +-
 doc/functions/TIFFReadRawTile.rst             |  2 +-
 doc/functions/TIFFReadScanline.rst            |  2 +-
 doc/functions/TIFFReadTile.rst                |  2 +-
 doc/functions/TIFFSetDirectory.rst            |  2 +-
 doc/functions/TIFFSetField.rst                |  2 +-
 doc/functions/TIFFStrileQuery.rst             |  4 +-
 doc/functions/TIFFWarning.rst                 | 55 +++++++++----
 doc/functions/TIFFWriteDirectory.rst          |  2 +-
 doc/functions/TIFFWriteEncodedStrip.rst       |  2 +-
 doc/functions/TIFFWriteEncodedTile.rst        |  2 +-
 doc/functions/TIFFWriteRawStrip.rst           |  2 +-
 doc/functions/TIFFWriteRawTile.rst            |  2 +-
 doc/functions/TIFFWriteScanline.rst           |  2 +-
 doc/functions/TIFFWriteTile.rst               |  2 +-
 doc/functions/TIFFstrip.rst                   |  4 +-
 doc/functions/libtiff.rst                     | 60 ++++++++++----
 35 files changed, 274 insertions(+), 130 deletions(-)
 create mode 100644 doc/functions/TIFFOpenOptions.rst

diff --git a/doc/functions.rst b/doc/functions.rst
index 774bb412..8b721e33 100644
--- a/doc/functions.rst
+++ b/doc/functions.rst
@@ -30,6 +30,7 @@ TIFF Functions Overview
     functions/TIFFmemory
     functions/TIFFMergeFieldInfo
     functions/TIFFOpen
+    functions/TIFFOpenOptions
     functions/TIFFPrintDirectory
     functions/TIFFProcFunctions
     functions/TIFFquery
diff --git a/doc/functions/TIFFClose.rst b/doc/functions/TIFFClose.rst
index 9e84b9eb..cc9f8886 100644
--- a/doc/functions/TIFFClose.rst
+++ b/doc/functions/TIFFClose.rst
@@ -31,8 +31,8 @@ calling :c:func:`TIFFCleanup`, if you will need these ones to close the file.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
-Likewise, warning messages are directed to the :c:func:`TIFFWarning` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
+Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFCreateDirectory.rst b/doc/functions/TIFFCreateDirectory.rst
index 5a427656..5e7377e5 100644
--- a/doc/functions/TIFFCreateDirectory.rst
+++ b/doc/functions/TIFFCreateDirectory.rst
@@ -66,8 +66,8 @@ Be aware:
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
-Likewise, warning messages are directed to the :c:func:`TIFFWarning` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
+Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFCustomDirectory.rst b/doc/functions/TIFFCustomDirectory.rst
index d26679d2..2881a20f 100644
--- a/doc/functions/TIFFCustomDirectory.rst
+++ b/doc/functions/TIFFCustomDirectory.rst
@@ -193,8 +193,8 @@ directory contents.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
-Likewise, warning messages are directed to the :c:func:`TIFFWarning` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
+Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFDeferStrileArrayWriting.rst b/doc/functions/TIFFDeferStrileArrayWriting.rst
index 77f4ffb2..60ee7469 100644
--- a/doc/functions/TIFFDeferStrileArrayWriting.rst
+++ b/doc/functions/TIFFDeferStrileArrayWriting.rst
@@ -58,8 +58,8 @@ Returns
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
-Likewise, warning messages are directed to the :c:func:`TIFFWarning` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
+Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFError.rst b/doc/functions/TIFFError.rst
index 797c1c0e..99924adc 100644
--- a/doc/functions/TIFFError.rst
+++ b/doc/functions/TIFFError.rst
@@ -15,10 +15,14 @@ Synopsis
 
 .. c:function:: void TIFFErrorExt(thandle_t fd, const char* module, const char* fmt, ...)
 
+.. c:function:: void TIFFErrorExtR(TIFF *tif, const char* module, const char* fmt, ...)
+
 .. c:type:: void (*TIFFErrorHandler)(const char * module, const char* fmt, va_list ap)
 
 .. c:type:: void (*TIFFErrorHandlerExt)(thandle_t fd, const char * module, const char* fmt, va_list ap)
 
+.. c:type:: int (*TIFFErrorHandlerExtR)(TIFF* tif, void* user_data, const char* module, const char* fmt, va_list ap)
+
 .. c:function:: TIFFErrorHandler TIFFSetErrorHandler(TIFFErrorHandler handler)
 
 .. c:function:: TIFFErrorHandlerExt TIFFSetErrorHandlerExt(TIFFErrorHandlerExt handler)
@@ -26,30 +30,40 @@ Synopsis
 Description
 -----------
 
-:c:func:`TIFFError` invokes the library-wide error handling function to
-(normally) write an error message to ``stderr``.  The *fmt* parameter is
-a :c:func:`printf` format string, and any number arguments can be supplied.
-The *module* parameter, if non-zero, is printed before the message; it
-typically is used to identify the software module in which an error is detected.
-
-Applications that desire to capture control in the event of an error should use
-:c:func:`TIFFSetErrorHandler` to override the default error handler. A :c:macro:`NULL`
-(0) error handling function may be installed to suppress error messages.
-
-The function :c:func:`TIFFErrorExt` provides a file handle.
+:c:func:`TIFFError` invokes the library-wide error handler function
+to (normally) write an error message to ``stderr``.
+The *fmt* parameter is a :c:func:`printf` format string, and any number
+arguments can be supplied. The *module* parameter is interpreted as a
+string that, if non-zero, should be printed before the message; it
+typically is used to identify the software module in which an error is
+detected.
+
+Applications that desire to capture control in the event of an error
+should use :c:func:`TIFFSetErrorHandler` to override the default
+error handler. A :c:macro:`NULL` (0) error handler function may be
+installed to suppress error messages.
+
+Two more application-specific error handler callbacks are available,
+each with different call parameters and passing parameters to the handler.
+Each handler is also linked with an error message function, i.e.
+:c:func:`TIFFErrorExt` and :c:func:`TIFFErrorExtR` if the application
+intends to call the handler with those extended parameters.
+
+:c:func:`TIFFErrorExt`  provides a file handle as parameter.
 Within ``libtiff`` :c:func:`TIFFErrorExt` is called passing ``tif->tif_clientdata``
 as *fd*, which represents the TIFF file handle (file descriptor).
-
-
-.. TODO: Check description, how to setup a TIFFErrorExt handler and its file handle.
-
-With :c:func:`TIFFSetErrorHandlerExt` an extra error handler can be setup
-in order to write to a file. The file handle needs to be stored in
-``tif->tif_clientdata`` if the ``libtiff`` internal errors shall also
-be written to that file.
-
-Note that, starting with libtiff 4.5, a per-TIFF handler may also be installed
-with :c:func:`TIFFOpenExt` or :c:func:`TIFFClientOpenExt`
+The application-specific and library-wide handler for :c:func:`TIFFErrorExt`
+is setup with :c:func:`TIFFSetErrorHandlerExt`.
+
+:c:func:`TIFFErrorExtR` (introduced with libtiff 4.5) is called with its
+TIFF handle and thus provides access to a per-TIFF handle (re-entrant)
+error handler. That means for different TIFF handles, different error
+handlers can be setup. This application-specific handler
+can be setup when a TIFF file is opened with one of the following functions:
+:c:func:`TIFFOpenExt`, :c:func:`TIFFOpenWExt`, :c:func:`TIFFFdOpenExt`
+or :c:func:`TIFFClientOpenExt`.
+Furthermore, a **custom defined data structure** *user_data* for the
+error handler can be given along.
 
 Note
 ----
@@ -57,17 +71,32 @@ Note
 Both functions :c:func:`TIFFError` and :c:func:`TIFFErrorExt`
 each attempt to call both handler functions if they are defined.
 First :c:func:`TIFFErrorHandler` is called and then :c:func:`TIFFErrorHandlerExt`.
-However, :c:func:`TIFFError` passes a "0" as a file handle to :c:func:`TIFFErrorHandlerExt`. 
+However, :c:func:`TIFFError` passes a "0" as a file handle to
+:c:func:`TIFFErrorHandlerExt`.
+
+:c:func:`TIFFErrorExtR` tries first to call the per-TIFF handle defined
+error handler. If :c:func:`TIFFErrorHandlerExtR` is not defined or
+returns 0, :c:func:`TIFFErrorHandler` and then :c:func:`TIFFErrorHandlerExt`
+are called. From libtiff 4.5 onwards :c:func:`TIFFErrorExtR` is used
+within the ``libtiff`` library where the TIFF handle is available.
+Otherwise, :c:func:`TIFFErrorExt` is used!
 
 Return values
 -------------
 
-:c:func:`TIFFSetErrorHandler` and :c:func:`TIFFSetErrorHandlerExt` returns
-a reference to the previous error handling function.
+:c:func:`TIFFSetErrorHandler` and :c:func:`TIFFSetErrorHandlerExt`
+returns a reference to the previous error handler function.
+
+:c:func:`TIFFErrorHandlerExtR` returns an integer as "stop" to control the call
+of further error handler functions within :c:func:`TIFFErrorExtR`:
+
+  - 0: both functions :c:func:`TIFFErrorHandler` and :c:func:`TIFFErrorHandlerExt` are called.
+  - non-zero: no further error message function is called.
 
 See also
 --------
 
 :doc:`TIFFWarning` (3tiff),
+:doc:`TIFFOpen` (3tiff),
 :doc:`libtiff` (3tiff),
 printf (3)
diff --git a/doc/functions/TIFFFlush.rst b/doc/functions/TIFFFlush.rst
index 4b3b71f0..6b56148e 100644
--- a/doc/functions/TIFFFlush.rst
+++ b/doc/functions/TIFFFlush.rst
@@ -35,7 +35,7 @@ Return values
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFGetField.rst b/doc/functions/TIFFGetField.rst
index b62c7892..ddd2f68e 100644
--- a/doc/functions/TIFFGetField.rst
+++ b/doc/functions/TIFFGetField.rst
@@ -473,7 +473,7 @@ returned.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``Unknown field, tag 0x%x``:
 
diff --git a/doc/functions/TIFFOpen.rst b/doc/functions/TIFFOpen.rst
index 7566ef62..23eb12a2 100644
--- a/doc/functions/TIFFOpen.rst
+++ b/doc/functions/TIFFOpen.rst
@@ -16,6 +16,12 @@ Synopsis
 
 .. c:function:: TIFF* TIFFFdOpen(const int fd, const char* filename, const char*mode)
 
+.. c:function:: TIFF* TIFFOpenExt(const char* filename, const char* mode, TIFFOpenOptions* opts)
+
+.. c:function:: TIFF* TIFFOpenWExt(const wchar_t* name, const char* mode, TIFFOpenOptions* opts)
+
+.. c:function:: TIFF* TIFFFdOpenExt(const int fd, const char* filename, const char*mode, TIFFOpenOptions* opts)
+
 .. c:function:: const char * TIFFSetFileName(TIFF* tif)
 
 .. c:function:: int TIFFSetFileno(TIFF* tif, int fd)
@@ -31,26 +37,12 @@ Synopsis
 
 .. c:function:: TIFF* TIFFClientOpen(const char* filename, const char* mode, thandle_t clientdata, TIFFReadWriteProc readproc, TIFFReadWriteProc writeproc, TIFFSeekProc seekproc, TIFFCloseProc closeproc, TIFFSizeProc sizeproc, TIFFMapFileProc mapproc, TIFFUnmapFileProc unmapproc)
 
+.. c:function:: TIFF* TIFFClientOpenExt(const char* filename, const char* mode, thandle_t clientdata, TIFFReadWriteProc readproc, TIFFReadWriteProc writeproc, TIFFSeekProc seekproc, TIFFCloseProc closeproc, TIFFSizeProc sizeproc, TIFFMapFileProc mapproc, TIFFUnmapFileProc unmapproc, TIFFOpenOptions* opts)
+
 .. c:function:: thandle_t TIFFClientdata(TIFF* tif)
 
 .. c:function:: thandle_t TIFFSetClientdata(TIFF* tif, thandle_t newvalue)
 
-.. c:function:: TIFFOpenOptions* TIFFOpenOptionsAlloc(void)
-
-.. c:function:: void TIFFOpenOptionsFree(TIFFOpenOptions*);
-
-.. c:function:: void TIFFOpenOptionsSetErrorHandlerExtR(TIFFOpenOptions* opts, TIFFErrorHandlerExtR handler, void* errorhandler_user_data)
-
-.. c:function:: void TIFFOpenOptionsSetWarningHandlerExtR(TIFFOpenOptions* opts, TIFFErrorHandlerExtR handler, void* warnhandler_user_data)
-
-.. c:function:: TIFF* TIFFOpenExt(const char* filename, const char* mode, TIFFOpenOptions* opts)
-
-.. c:function:: TIFF* TIFFOpenWExt(const wchar_t* name, const char* mode, TIFFOpenOptions* opts)
-
-.. c:function:: TIFF* TIFFFdOpenExt(const int fd, const char* filename, const char*mode, TIFFOpenOptions* opts)
-
-.. c:function:: TIFF* TIFFClientOpenExt(const char* filename, const char* mode, thandle_t clientdata, TIFFReadWriteProc readproc, TIFFReadWriteProc writeproc, TIFFSeekProc seekproc, TIFFCloseProc closeproc, TIFFSizeProc sizeproc, TIFFMapFileProc mapproc, TIFFUnmapFileProc unmapproc, TIFFOpenOptions* opts)
-
 Description
 -----------
 
@@ -102,23 +94,21 @@ 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:`TIFFOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFOpen`, but options,
-such as re-entrant error and warning handlers may be passed. The opts argument
-may be NULL. Note that in the early stages of the execution of the function,
-the TIFF* argument passed to the re-entrant error handler (specified in opts)
-may be NULL.
+:c:func:`TIFFOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFOpen`,
+but options, such as re-entrant error and warning handlers may be passed
+with the *opts* argument. The *opts* argument may be NULL. 
+Refer to :doc:`TIFFOpenOptions` for allocating and filling the *opts* argument
+parameters. The allocated memory for :c:type:`TIFFOpenOptions`
+can be released straight after successful execution of the related
+"TIFFOpenExt" functions.
 
-:c:func:`TIFFOpenWExt` (added in libtiff 4.5) is like :c:func:`TIFFOpenW`, but options,
-such as re-entrant error and warning handlers may be passed. The opts argument
-may be NULL. Note that in the early stages of the execution of the function,
-the TIFF* argument passed to the re-entrant error handler (specified in opts)
-may be NULL.
+:c:func:`TIFFOpenWExt` (added in libtiff 4.5) is like :c:func:`TIFFOpenExt`,
+but opens a TIFF file with a Unicode filename.
 
-:c:func:`TIFFFdOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFFdOpen`, but options,
-such as re-entrant error and warning handlers may be passed. The opts argument
-may be NULL. Note that in the early stages of the execution of the function,
-the TIFF* argument passed to the re-entrant error handler (specified in opts)
-may be NULL.
+:c:func:`TIFFFdOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFFdOpen`,
+but options, such as re-entrant error and warning handlers may be passed
+with the *opts* argument. The *opts* argument may be NULL. 
+Refer to :doc:`TIFFOpenOptions` for filling the *opts* argument.
 
 :c:func:`TIFFSetFileName` sets the file name in the tif-structure
 and returns the old file name.
@@ -142,6 +132,9 @@ memory; c.f. :c:func:`mmap` (2) and :c:func:`munmap` (2).
 The *clientdata* parameter is an opaque "handle" passed to the client-specified
 routines passed as parameters to :c:func:`TIFFClientOpen`.
 
+:c:func:`TIFFClientOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFClientOpen`,
+but options argument *opts* like for :c:func:`TIFFOpenExt` can be passed.
+
 :c:func:`TIFFClientdata` returns open file's clientdata handle,
 which is the real open file's I/O descriptor used by ``libtiff``.
 Note: Within tif_unix.c this handle is converted into an integer file descriptor.
@@ -157,12 +150,6 @@ The clientdata is used as open file's I/O descriptor within ``libtiff``.
   When updating the file's clientdata with :c:func:`TIFFSetClientdata`,
   the *fd* value is **not** updated.
 
-:c:func:`TIFFClientOpenExt` (added in libtiff 4.5) is like :c:func:`TIFFClientOpen`, but options,
-such as re-entrant error and warning handlers may be passed. The opts argument
-may be NULL. Note that in the early stages of the execution of the function,
-the TIFF* argument passed to the re-entrant error handler (specified in opts)
-may be NULL.
-
 Options
 -------
 
@@ -294,8 +281,8 @@ Diagnostics
 -----------
 
 
-All error messages are directed to the :c:func:`TIFFError` routine.
-Likewise, warning messages are directed to the :c:func:`TIFFWarning` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
+Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
 
 ``"%s": Bad mode``:
 
@@ -335,4 +322,5 @@ See also
 
 :doc:`libtiff` (3tiff),
 :doc:`TIFFClose` (3tiff),
-:doc:`TIFFStrileQuery`
+:doc:`TIFFStrileQuery`,
+:doc:`TIFFOpenOptions`
\ No newline at end of file
diff --git a/doc/functions/TIFFOpenOptions.rst b/doc/functions/TIFFOpenOptions.rst
new file mode 100644
index 00000000..5c675667
--- /dev/null
+++ b/doc/functions/TIFFOpenOptions.rst
@@ -0,0 +1,69 @@
+TIFFOpenOptions
+===============
+
+Synopsis
+--------
+
+.. highlight:: c
+
+::
+
+    #include <tiffio.h>
+
+.. c:type:: TIFFOpenOptions TIFFOpenOptions
+
+.. c:function:: TIFFOpenOptions* TIFFOpenOptionsAlloc(void)
+
+.. c:function:: void TIFFOpenOptionsFree(TIFFOpenOptions*)
+
+.. c:function:: void TIFFOpenOptionsSetMaxSingleMemAlloc(TIFFOpenOptions* opts, tmsize_t max_single_mem_alloc)
+
+.. c:function:: void TIFFOpenOptionsSetErrorHandlerExtR(TIFFOpenOptions* opts, TIFFErrorHandlerExtR handler, void* errorhandler_user_data)
+
+.. c:function:: void TIFFOpenOptionsSetWarningHandlerExtR(TIFFOpenOptions* opts, TIFFErrorHandlerExtR handler, void* warnhandler_user_data)
+
+Description
+-----------
+
+:c:type:`TIFFOpenOptions` is an opaque structure which can be passed
+to the TIFF open"Ext" functions to define some ``libtiff`` internal settings.
+The settings are the maximum single memory allocation limit and 
+per-TIFF handle (re-entrant) error handler and warning handler functions.
+For those handler a pointer to a **custom defined data structure** *user_data* 
+can be given along.
+
+:c:func:`TIFFOpenOptionsAlloc` allocates memory for the :c:type:`TIFFOpenOptions`
+opaque structure and returns a :c:type:`TIFFOpenOptions` pointer. 
+
+:c:func:`TIFFOpenOptionsFree` releases the allocated memory for
+:c:type:`TIFFOpenOptions`. The allocated memory for :c:type:`TIFFOpenOptions`
+can be released straight after successful execution of the related
+TIFF open"Ext" functions like :c:func:`TIFFOpenExt`.
+
+:c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc` sets parameter for the
+maximum single memory limit in byte that ``libtiff`` internal memory allocation
+functions are allowed to request per call.
+
+:c:func:`TIFFOpenOptionsSetErrorHandlerExtR` sets the function pointer to
+an application-specific and per-TIFF handle (re-entrant) error handler.
+Furthermore, a pointer to a **custom defined data structure** *errorhandler_user_data* 
+can be passed. This error handler is invoked through :c:func:`TIFFErrorExtR`
+and the *errorhandler_user_data* pointer is given along.
+The *errorhandler_user_data* argument may be NULL.
+
+:c:func:`TIFFOpenOptionsSetWarningHandlerExtR` works like
+:c:func:`TIFFOpenOptionsSetErrorHandlerExtR` but for the warning handler,
+which is invoked through  :c:func:`TIFFWarningExtR`
+
+Note
+----
+
+This functionality was introduced with libtiff 4.5.
+
+See also
+--------
+
+:doc:`libtiff` (3tiff),
+:doc:`TIFFOpen` (3tiff),
+:doc:`TIFFError` (3tiff),
+:doc:`TIFFWarning` (3tiff)
diff --git a/doc/functions/TIFFRGBAImage.rst b/doc/functions/TIFFRGBAImage.rst
index aa1440ef..119d3efd 100644
--- a/doc/functions/TIFFRGBAImage.rst
+++ b/doc/functions/TIFFRGBAImage.rst
@@ -164,7 +164,7 @@ Otherwise, 0 is returned if an error was encountered and
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``"Sorry, can not handle %d-bit pictures"``:
 
diff --git a/doc/functions/TIFFReadDirectory.rst b/doc/functions/TIFFReadDirectory.rst
index 2bb103e8..3ffaf7b8 100644
--- a/doc/functions/TIFFReadDirectory.rst
+++ b/doc/functions/TIFFReadDirectory.rst
@@ -41,8 +41,8 @@ be read.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
-All warning messages are directed to the :c:func:`TIFFWarning` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
+Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
 
 ``Seek error accessing TIFF directory``:
 
diff --git a/doc/functions/TIFFReadEncodedStrip.rst b/doc/functions/TIFFReadEncodedStrip.rst
index df2d025c..cd75ce39 100644
--- a/doc/functions/TIFFReadEncodedStrip.rst
+++ b/doc/functions/TIFFReadEncodedStrip.rst
@@ -45,7 +45,7 @@ The actual number of bytes of data that were placed in *buf* is returned;
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFReadEncodedTile.rst b/doc/functions/TIFFReadEncodedTile.rst
index b0acfc56..8c99dcf6 100644
--- a/doc/functions/TIFFReadEncodedTile.rst
+++ b/doc/functions/TIFFReadEncodedTile.rst
@@ -45,7 +45,7 @@ The actual number of bytes of data that were placed in *buf* is returned;
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFReadFromUserBuffer.rst b/doc/functions/TIFFReadFromUserBuffer.rst
index f4ab06de..09807eca 100644
--- a/doc/functions/TIFFReadFromUserBuffer.rst
+++ b/doc/functions/TIFFReadFromUserBuffer.rst
@@ -33,7 +33,7 @@ Returns 1 in case of success, 0 otherwise.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFErrorExt` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFReadRGBAImage.rst b/doc/functions/TIFFReadRGBAImage.rst
index caee57b6..1bb99bfa 100644
--- a/doc/functions/TIFFReadRGBAImage.rst
+++ b/doc/functions/TIFFReadRGBAImage.rst
@@ -103,7 +103,7 @@ Otherwise, 0 is returned if an error was encountered and
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``"Sorry, can not handle %d-bit pictures"``:
 
diff --git a/doc/functions/TIFFReadRGBAStrip.rst b/doc/functions/TIFFReadRGBAStrip.rst
index 75e29f39..41ebbfc3 100644
--- a/doc/functions/TIFFReadRGBAStrip.rst
+++ b/doc/functions/TIFFReadRGBAStrip.rst
@@ -71,7 +71,7 @@ Otherwise, 0 is returned if an error was encountered.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``"Sorry, can not handle %d-bit pictures"``:
 
diff --git a/doc/functions/TIFFReadRGBATile.rst b/doc/functions/TIFFReadRGBATile.rst
index b66eb6e1..14a3e3c6 100644
--- a/doc/functions/TIFFReadRGBATile.rst
+++ b/doc/functions/TIFFReadRGBATile.rst
@@ -73,7 +73,7 @@ Otherwise, 0 is returned if an error was encountered.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``"Sorry, can not handle %d-bit pictures"``:
 
diff --git a/doc/functions/TIFFReadRawStrip.rst b/doc/functions/TIFFReadRawStrip.rst
index bd235636..70bc00aa 100644
--- a/doc/functions/TIFFReadRawStrip.rst
+++ b/doc/functions/TIFFReadRawStrip.rst
@@ -31,7 +31,7 @@ The actual number of bytes of data that were placed in *buf* is returned;
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFReadRawTile.rst b/doc/functions/TIFFReadRawTile.rst
index ef334808..9be65043 100644
--- a/doc/functions/TIFFReadRawTile.rst
+++ b/doc/functions/TIFFReadRawTile.rst
@@ -33,7 +33,7 @@ The actual number of bytes of data that were placed in *buf* is returned;
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFReadScanline.rst b/doc/functions/TIFFReadScanline.rst
index ecca8b92..7a484e0b 100644
--- a/doc/functions/TIFFReadScanline.rst
+++ b/doc/functions/TIFFReadScanline.rst
@@ -46,7 +46,7 @@ returned.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``"Compression algorithm does not support random access"``:
 
diff --git a/doc/functions/TIFFReadTile.rst b/doc/functions/TIFFReadTile.rst
index 22c47832..a61fa6b1 100644
--- a/doc/functions/TIFFReadTile.rst
+++ b/doc/functions/TIFFReadTile.rst
@@ -45,7 +45,7 @@ number of bytes in the decoded tile is returned.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFSetDirectory.rst b/doc/functions/TIFFSetDirectory.rst
index cda54939..61aea5c4 100644
--- a/doc/functions/TIFFSetDirectory.rst
+++ b/doc/functions/TIFFSetDirectory.rst
@@ -60,7 +60,7 @@ encountered while reading the directory's contents.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``"%s: Error fetching directory count"``:
 
diff --git a/doc/functions/TIFFSetField.rst b/doc/functions/TIFFSetField.rst
index 7271ef43..2283d3e6 100644
--- a/doc/functions/TIFFSetField.rst
+++ b/doc/functions/TIFFSetField.rst
@@ -378,7 +378,7 @@ Otherwise, 0 is returned if an error was detected.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``%s: Cannot modify tag "%s" while writing``:
 
diff --git a/doc/functions/TIFFStrileQuery.rst b/doc/functions/TIFFStrileQuery.rst
index d08d0cfd..f8631afd 100644
--- a/doc/functions/TIFFStrileQuery.rst
+++ b/doc/functions/TIFFStrileQuery.rst
@@ -63,8 +63,8 @@ which is set to "0" for successful return or to "1" for an error return.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
-Likewise, warning messages are directed to the :c:func:`TIFFWarning` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
+Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
 
 See also
 --------
diff --git a/doc/functions/TIFFWarning.rst b/doc/functions/TIFFWarning.rst
index 2006696c..48467d79 100644
--- a/doc/functions/TIFFWarning.rst
+++ b/doc/functions/TIFFWarning.rst
@@ -15,9 +15,13 @@ Synopsis
 
 .. c:function:: void TIFFWarningExt(thandle_t fd, const char* module, const char* fmt, ...)
 
-.. c:type:: void (*TIFFWarningHandler)(const char* module, const char* fmt, va_list ap);
+.. c:function:: void TIFFWarningExtR(TIFF *tif, const char* module, const char* fmt, ...)
 
-.. c:type:: void (*TIFFWarningHandlerExt)(thandle_t fd, const char* module, const char* fmt, va_list ap);
+.. c:type:: void (*TIFFWarningHandler)(const char * module, const char* fmt, va_list ap)
+
+.. c:type:: void (*TIFFWarningHandlerExt)(thandle_t fd, const char* module, const char* fmt, va_list ap)
+
+.. c:type:: int (*TIFFWarningHandlerExtR)(TIFF* tif, void* user_data, const char* module, const char* fmt, va_list ap)
 
 .. c:function:: TIFFWarningHandler TIFFSetWarningHandler(TIFFWarningHandler handler)
 
@@ -39,18 +43,27 @@ should use :c:func:`TIFFSetWarningHandler` to override the default
 warning handler. A :c:macro:`NULL` (0) warning handler function may be
 installed to suppress warning messages.
 
-The function :c:func:`TIFFWarningExt` provides a file handle.
+Two more application-specific warning handler callbacks are available,
+each with different call parameters and passing parameters to the handler.
+Each handler is also linked with a warning message function, i.e.
+:c:func:`TIFFWarningExt` and :c:func:`TIFFWarningExtR` if the application
+intends to call the handler with those extended parameters.
+
+:c:func:`TIFFWarningExt` provides a file handle as parameter.
 Within ``libtiff`` :c:func:`TIFFWarningExt` is called passing ``tif->tif_clientdata``
 as *fd*, which represents the TIFF file handle (file descriptor).
-
-.. TODO: Check description, how to setup a TIFFWarningExt handler and
-   its file handle.
-
-With :c:func:`TIFFSetWarningHandlerExt` an extra warning handler can be
-setup up.
-
-Note that, starting with libtiff 4.5, a per-TIFF handler may also be installed
-with :c:func:`TIFFOpenExt` or :c:func:`TIFFClientOpenExt`
+The application-specific and library-wide handler for :c:func:`TIFFWarningExt`
+is setup with :c:func:`TIFFSetWarningHandlerExt`.
+
+:c:func:`TIFFWarningExtR` (introduced with libtiff 4.5) is called with its
+TIFF handle and thus provides access to a per-TIFF handle (re-entrant)
+warning handler. That means for different TIFF handles, different warning
+handlers can be setup. This application-specific handler
+can be setup when a TIFF file is opened with one of the following functions:
+:c:func:`TIFFOpenExt`, :c:func:`TIFFOpenWExt`, :c:func:`TIFFFdOpenExt`
+or :c:func:`TIFFClientOpenExt`.
+Furthermore, a **custom defined data structure** *user_data* for the
+warning handler can be given along.
 
 Note
 ----
@@ -58,17 +71,31 @@ Note
 Both functions :c:func:`TIFFWarning` and :c:func:`TIFFWarningExt`
 each attempt to call both handler functions if they are defined.
 First :c:func:`TIFFWarningHandler` is called and then :c:func:`TIFFWarningHandlerExt`.
-However, :c:func:`TIFFWarning` passes a "0" as a file handle to :c:func:`TIFFWarningHandlerExt`. 
+However, :c:func:`TIFFWarning` passes a "0" as a file handle to
+:c:func:`TIFFWarningHandlerExt`.
+
+:c:func:`TIFFWarningExtR` tries first to call the per-TIFF handle defined
+warning handler. If :c:func:`TIFFWarningHandlerExtR` is not defined or
+returns 0

(Patch may be truncated, please check the link at the top of this post.)