manpage update for re-entrant error handler TIFFErrorExtR(), TIFFOpenExt() and...

35 files changed, 274 insertions, 130 deletions

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, :c:func:`TIFFWarningHandler` and then :c:func:`TIFFWarningHandlerExt`
+are called. From libtiff 4.5 onwards :c:func:`TIFFWarningExtR` is used
+within the ``libtiff`` library.
 
 Return values
 -------------
 
 :c:func:`TIFFSetWarningHandler` and :c:func:`TIFFSetWarningHandlerExt`
-returns a reference to the previous warning handling function.
+returns a reference to the previous warning handler function.
+
+:c:func:`TIFFWarningHandlerExtR` returns an integer as "stop" to control the call
+of furhter warning handler functions within :c:func:`TIFFWarningExtR`:
+
+  - 0: both functions :c:func:`TIFFWarningHandler` and :c:func:`TIFFWarningHandlerExt` are called.
+  - non-zero: no further warning message function is called.
 
 See also
 --------
 
 :doc:`TIFFError` (3tiff),
+:doc:`TIFFOpen` (3tiff),
 :doc:`libtiff` (3tiff),
 printf (3)
diff --git a/doc/functions/TIFFWriteDirectory.rst b/doc/functions/TIFFWriteDirectory.rst
index 98836106..8682d5f0 100644
--- a/doc/functions/TIFFWriteDirectory.rst
+++ b/doc/functions/TIFFWriteDirectory.rst
@@ -72,7 +72,7 @@ the directory contents.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``"Error post-encoding before directory write"``:
 
diff --git a/doc/functions/TIFFWriteEncodedStrip.rst b/doc/functions/TIFFWriteEncodedStrip.rst
index 7eca8162..24fe8d89 100644
--- a/doc/functions/TIFFWriteEncodedStrip.rst
+++ b/doc/functions/TIFFWriteEncodedStrip.rst
@@ -43,7 +43,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.
 
 ``%s: File not open for writing``:
 
diff --git a/doc/functions/TIFFWriteEncodedTile.rst b/doc/functions/TIFFWriteEncodedTile.rst
index 62cfdfe4..efb07ba9 100644
--- a/doc/functions/TIFFWriteEncodedTile.rst
+++ b/doc/functions/TIFFWriteEncodedTile.rst
@@ -40,7 +40,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.
 
 ``%s: File not open for writing``:
 
diff --git a/doc/functions/TIFFWriteRawStrip.rst b/doc/functions/TIFFWriteRawStrip.rst
index 3b6c59bd..73845ee4 100644
--- a/doc/functions/TIFFWriteRawStrip.rst
+++ b/doc/functions/TIFFWriteRawStrip.rst
@@ -34,7 +34,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.
 
 ``%s: File not open for writing``:
 
diff --git a/doc/functions/TIFFWriteRawTile.rst b/doc/functions/TIFFWriteRawTile.rst
index f4ead80c..ba547b5f 100644
--- a/doc/functions/TIFFWriteRawTile.rst
+++ b/doc/functions/TIFFWriteRawTile.rst
@@ -26,7 +26,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.
 
 ``%s: File not open for writing``:
 
diff --git a/doc/functions/TIFFWriteScanline.rst b/doc/functions/TIFFWriteScanline.rst
index 89ec635d..548442d9 100644
--- a/doc/functions/TIFFWriteScanline.rst
+++ b/doc/functions/TIFFWriteScanline.rst
@@ -58,7 +58,7 @@ error and 1 for a successful write.
 Diagnostics
 -----------
 
-All error messages are directed to the :c:func:`TIFFError` routine.
+All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 
 ``%s: File not open for writing``:
 
diff --git a/doc/functions/TIFFWriteTile.rst b/doc/functions/TIFFWriteTile.rst
index 5044d0e0..db8afd16 100644
--- a/doc/functions/TIFFWriteTile.rst
+++ b/doc/functions/TIFFWriteTile.rst
@@ -37,7 +37,7 @@ the number of bytes in the 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/TIFFstrip.rst b/doc/functions/TIFFstrip.rst
index e5eda82f..9d61f1fa 100644
--- a/doc/functions/TIFFstrip.rst
+++ b/doc/functions/TIFFstrip.rst
@@ -77,9 +77,7 @@ if data are organized in separate planes (``PlanarConfiguration`` = 2).
 
 :c:func:`TIFFNumberOfStrips` returns the number of strips in the image.
 
-.. TODO: Explain the function
-
-:c:func:`TIFFSetupStrips`  ?????
+:c:func:`TIFFSetupStrips` setup  or reset strip parameters and strip array memory.
 
 Diagnostics
 -----------
diff --git a/doc/functions/libtiff.rst b/doc/functions/libtiff.rst
index e259b846..54a08614 100644
--- a/doc/functions/libtiff.rst
+++ b/doc/functions/libtiff.rst
@@ -144,6 +144,9 @@ will work.
         the file descriptor used within ``libtiff``.
     * - :c:func:`TIFFClientOpen`
       - open a file for reading or writing
+    * - :c:func:`TIFFClientOpenExt`
+      - open a file for reading or writing with options,
+        such as re-entrant error and warning handlers may be passed
     * - :c:func:`TIFFClose`
       - close a previously opened TIFF file
     * - :c:func:`TIFFComputeStrip`
@@ -183,11 +186,19 @@ will work.
         and must be used in a particular sequence together with
         TIFFForceStrileArrayWriting() (see description)
     * - :c:func:`TIFFError`
-      - library error handler printing to ``stderr``
+      - library-wide error handling function printing to ``stderr``
     * - :c:func:`TIFFErrorExt`
-      - library error handler printing to ``stderr`` and/or a file
+      - user-specific library-wide error handling function that can be passed
+        a file handle, which is set to the open TIFF file within ``libtiff``
+    * - :c:func:`TIFFErrorExtR`
+      - user-specific re-entrant library error handling function,
+        to which its TIFF structure is passed
+        containing the pointer to a user-specific data object
     * - :c:func:`TIFFFdOpen`
       - open a file for reading or writing
+    * - :c:func:`TIFFFdOpenExt`
+      - open a file for reading or writing with options,
+        such as re-entrant error and warning handlers may be passed
     * - :c:func:`TIFFFieldDataType`
       - get data type from field information
     * - :c:func:`TIFFFieldIsAnonymous`
@@ -300,12 +311,28 @@ will work.
       - return number of tiles in an image
     * - :c:func:`TIFFOpen`
       - open a file for reading or writing
+    * - :c:func:`TIFFOpenExt`
+      - open a file for reading or writing  with options,
+        such as re-entrant error and warning handlers may be passed
     * - :c:func:`TIFFOpenW`
       - opens a TIFF file with a Unicode filename, for read/writing
+    * - :c:func:`TIFFOpenWExt`
+      - opens a TIFF file with a Unicode filename, for read/writing
+        with options, such as re-entrant error and warning handlers may be passed
+    * - :c:func:`TIFFOpenOptionsAlloc`
+      - allocates memory for :c:type:`TIFFOpenOptions` opaque structure
+    * - :c:func:`TIFFOpenOptionsFree`
+      - releases the allocated memory for :c:type:`TIFFOpenOptions`
+    * - :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc`
+      - limits the maximum single memory allocation within ``libtiff``
+    * - :c:func:`TIFFOpenOptionsSetErrorHandlerExtR`
+      - setup of a user-specific and per-TIFF handle (re-entrant) error handler
+    * - :c:func:`TIFFOpenOptionsSetWarningHandlerExtR`
+      - setup of a user-specific and per-TIFF handle (re-entrant) warning handler
     * - :c:func:`TIFFPrintDirectory`
       - print description of the current directory
     * - :c:func:`TIFFRasterScanlineSize`
-      - eturns the size in bytes of a complete decoded and packed raster scanline
+      - returns the size in bytes of a complete decoded and packed raster scanline
     * - :c:func:`TIFFRasterScanlineSize64`
       - return size as :c:type:`uint64_t`
     * - :c:func:`TIFFRawStripSize`
@@ -340,17 +367,17 @@ will work.
       - read an image into a fixed format raster
     * - :c:func:`TIFFReadRGBAImageOriented`
       - works like :c:func:`TIFFReadRGBAImage` except that the user can specify
-          the raster origin position
+        the raster origin position
     * - :c:func:`TIFFReadRGBAStrip`
       - reads a single strip of a strip-based image into memory, storing the
         result in the user supplied RGBA raster
     * - :c:func:`TIFFReadRGBAStripExt`
-      - same as :c:func:`TIFFReadRGBAStrip` but providing the paramater `stop_on_error`
+      - same as :c:func:`TIFFReadRGBAStrip` but providing the parameter `stop_on_error`
     * - :c:func:`TIFFReadRGBATile`
       - reads a single tile of a tile-based image into memory, storing the
         result in the user supplied RGBA raster
     * - :c:func:`TIFFReadRGBATileExt`
-      - same as :c:func:`TIFFReadRGBATile` but providing the paramater `stop_on_error`
+      - same as :c:func:`TIFFReadRGBATile` but providing the parameter `stop_on_error`
     * - :c:func:`TIFFReadScanline`
       - read and decode a row of data
     * - :c:func:`TIFFReadTile`
@@ -391,19 +418,19 @@ will work.
     * - :c:func:`TIFFSetField`
       - set a tag's value in the current directory
     * - :c:func:`TIFFSetFileName`
-      - sets the file name in the tif-structure and returns the old file name
+      - sets the file name in the TIFF-structure and returns the old file name
     * - :c:func:`TIFFSetFileno`
       - overwrites a copy of the open file's I/O descriptor, and return previous value
         (refer to detailed description)
     * - :c:func:`TIFFSetMode`
-      - sets the ``libtiff`` open mode in the tif-structure and returns the old mode
+      - sets the ``libtiff`` open mode in the TIFF-structure and returns the old mode
     * - :c:func:`TIFFSetSubDirectory`
       - set the current directory
     * - :c:func:`TIFFSetTagExtender`
       - is used to register the merge function for user defined tags as an
         extender callback with ``libtiff``
     * - :c:func:`TIFFSetupStrips`
-      -
+      - setup  or reset strip parameters and strip array memory
     * - :c:func:`TIFFSetWarningHandler`
       - set warning handler function
     * - :c:func:`TIFFSetWarningHandlerExt`
@@ -463,12 +490,17 @@ will work.
     * - :c:func:`TIFFVTileSize`
       - returns the number of bytes in a row-aligned tile with *nrows* of data
     * - :c:func:`TIFFVTileSize64`
-      - returns the number of bytes in a row-alignedtile with *nrows* of data
+      - returns the number of bytes in a row-aligned tile with *nrows* of data
         a :c:type:`uint64_t` number
     * - :c:func:`TIFFWarning`
-      - library warning handler
+      - library-wide warning handling function printing to ``stderr``
     * - :c:func:`TIFFWarningExt`
-      - library warning handler printing to ``stderr`` and a file
+      - user-specific library-wide warning handling function that can be passed
+        a file handle, which is set to the open TIFF file within ``libtiff``
+    * - :c:func:`TIFFWarningExtR`
+      - user-specific re-entrant library warning handling function,
+        to which its TIFF structure is passed
+        containing the pointer to a user-specific data object
     * - :c:func:`TIFFWriteBufferSetup`
       - sets up the data buffer used to write raw (encoded) data to a file
     * - :c:func:`TIFFWriteCheck`
@@ -1090,11 +1122,11 @@ The table below summarizes the defined pseudo-tags.
 Diagnostics
 -----------
 
-All error messages are directed through the :c:func:`TIFFError` routine.
+All error messages are directed through the :c:func:`TIFFErrorExtR` routine.
 By default messages are directed to ``stderr`` in the form:
 ``module: message\n``.
 Warning messages are likewise directed through the
-:c:func:`TIFFWarning` routine.
+:c:func:`TIFFWarningExtR` routine.
 
 See also
 --------