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