libtiff: Merge branch 'manpage_621_TIFFOpenOptionsSetMaxSingleMemAlloc' into 'master'

From 335947359ce2dd3862cd9f7c49f92eba065dfed4 Mon Sep 17 00:00:00 2001
From: Su_Laus <[EMAIL REDACTED]>
Date: Wed, 8 Nov 2023 23:04:53 +0100
Subject: [PATCH 1/2] manpage: Update TIFF documentation about
 TIFFOpenOptions.rst and TIFFOpenOptionsSetMaxSingleMemAlloc() usage and some
 other small fixes.

---
 doc/functions/TIFFDeferStrileArrayWriting.rst |  5 +++
 doc/functions/TIFFError.rst                   |  3 ++
 doc/functions/TIFFOpen.rst                    | 11 +++--
 doc/functions/TIFFOpenOptions.rst             | 44 ++++++++++++++++++-
 doc/functions/TIFFStrileQuery.rst             |  5 +++
 doc/libtiff.rst                               | 31 ++++++++++++-
 6 files changed, 90 insertions(+), 9 deletions(-)

diff --git a/doc/functions/TIFFDeferStrileArrayWriting.rst b/doc/functions/TIFFDeferStrileArrayWriting.rst
index 60ee7469..705aebc2 100644
--- a/doc/functions/TIFFDeferStrileArrayWriting.rst
+++ b/doc/functions/TIFFDeferStrileArrayWriting.rst
@@ -61,6 +61,11 @@ Diagnostics
 All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
 
+Note
+----
+
+This functionality was introduced with libtiff 4.1.
+
 See also
 --------
 
diff --git a/doc/functions/TIFFError.rst b/doc/functions/TIFFError.rst
index 99924adc..cf4b37cb 100644
--- a/doc/functions/TIFFError.rst
+++ b/doc/functions/TIFFError.rst
@@ -65,6 +65,9 @@ or :c:func:`TIFFClientOpenExt`.
 Furthermore, a **custom defined data structure** *user_data* for the
 error handler can be given along.
 
+Please refer to :doc:`/functions/TIFFOpenOptions` for how to setup the
+application-specific handler introduced with libtiff 4.5.
+
 Note
 ----
 
diff --git a/doc/functions/TIFFOpen.rst b/doc/functions/TIFFOpen.rst
index db79d7bc..e186f7b0 100644
--- a/doc/functions/TIFFOpen.rst
+++ b/doc/functions/TIFFOpen.rst
@@ -94,8 +94,9 @@ 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
-with the *opts* argument. The *opts* argument may be NULL. 
+but options, such as re-entrant error and warning handlers and a limit in byte
+that libtiff internal memory allocation functions are allowed to request per call
+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
@@ -105,9 +106,7 @@ can be released straight after successful execution of the related
 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
-with the *opts* argument. The *opts* argument may be NULL. 
-Refer to :doc:`TIFFOpenOptions` for filling the *opts* argument.
+but options argument *opts* like for :c:func:`TIFFOpenExt` can be passed.
 
 :c:func:`TIFFSetFileName` sets the file name in the tif-structure
 and returns the old file name.
@@ -326,5 +325,5 @@ See also
 
 :doc:`libtiff` (3tiff),
 :doc:`TIFFClose` (3tiff),
-:doc:`TIFFStrileQuery`,
+:doc:`TIFFStrileQuery` (3tiff),
 :doc:`TIFFOpenOptions`
\ No newline at end of file
diff --git a/doc/functions/TIFFOpenOptions.rst b/doc/functions/TIFFOpenOptions.rst
index 5c675667..23f29753 100644
--- a/doc/functions/TIFFOpenOptions.rst
+++ b/doc/functions/TIFFOpenOptions.rst
@@ -38,12 +38,17 @@ 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`.
+TIFFOpen"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.
 
+.. note::
+    However, the ``libtiff`` external functions :c:func:`_TIFFmalloc`
+    and :c:func:`_TIFFrealloc` **do not apply** this internal memory
+    allocation limit set by :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc`!
+
 :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* 
@@ -55,6 +60,43 @@ The *errorhandler_user_data* argument may be NULL.
 :c:func:`TIFFOpenOptionsSetErrorHandlerExtR` but for the warning handler,
 which is invoked through  :c:func:`TIFFWarningExtR`
 
+Example
+-------
+
+::
+
+    #include "tiffio.h"
+
+    typedef struct MyErrorHandlerUserDataStruct
+    {
+        /* ... any user data structure ... */
+    } MyErrorHandlerUserDataStruct;
+
+    static int myErrorHandler(TIFF *tiff, void *user_data, const char *module,
+                          const char *fmt, va_list ap)
+    {
+        MyErrorHandlerUserDataStruct *errorhandler_user_data =
+            (MyErrorHandlerUserDataStruct *)user_data;
+        /*... code of myErrorHandler ...*/
+        return 1;
+    }
+
+
+    main()
+    {
+        tmsize_t limit = (256 * 1024 * 1024);
+        MyErrorHandlerUserDataStruct user_data = { /* ... any data ... */};
+
+        TIFFOpenOptions *opts = TIFFOpenOptionsAlloc();
+        TIFFOpenOptionsSetMaxSingleMemAlloc(opts, limit);
+        TIFFOpenOptionsSetErrorHandlerExtR(opts, myErrorHandler, &user_data);
+        TIFF *tif = TIFFOpenExt("foo.tif", "r", opts);
+        TIFFOpenOptionsFree(opts);
+        /* ... go on here ... */
+
+        TIFFClose(tif);
+    }
+
 Note
 ----
 
diff --git a/doc/functions/TIFFStrileQuery.rst b/doc/functions/TIFFStrileQuery.rst
index f8631afd..7931fe4a 100644
--- a/doc/functions/TIFFStrileQuery.rst
+++ b/doc/functions/TIFFStrileQuery.rst
@@ -66,6 +66,11 @@ Diagnostics
 All error messages are directed to the :c:func:`TIFFErrorExtR` routine.
 Likewise, warning messages are directed to the :c:func:`TIFFWarningExtR` routine.
 
+Note
+----
+
+This functionality was introduced with libtiff 4.1.
+
 See also
 --------
 
diff --git a/doc/libtiff.rst b/doc/libtiff.rst
index 6a0054c6..d96a8609 100644
--- a/doc/libtiff.rst
+++ b/doc/libtiff.rst
@@ -90,11 +90,15 @@ compatibility on machines with a segmented architecture.
 :c:func:`realloc`, and :c:func:`free` routines in the C library.)
 
 To deal with segmented pointer issues ``libtiff`` also provides
-:c:func:`_TIFFmemcpy`, :c:func:`_TIFFmemset`, and :c:func:`_TIFFmemmove`
+:c:func:`_TIFFmemcpy`, :c:func:`_TIFFmemset`, and :c:func:`_TIFFmemcmp`
 routines that mimic the equivalent ANSI C routines, but that are
 intended for use with memory allocated through :c:func:`_TIFFmalloc`
 and :c:func:`_TIFFrealloc`.
 
+With ``libtiff`` 4.5 a method was introduced to limit the internal
+memory allocation that functions are allowed to request per call
+(see  :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc` and :c:func:`TIFFOpenExt`).
+
 Error Handling
 --------------
 
@@ -106,6 +110,10 @@ routine that can be specified with a call to :c:func:`TIFFSetErrorHandler`.
 Likewise warning messages are directed to a single handler routine
 that can be specified with a call to :c:func:`TIFFSetWarningHandler`
 
+Further application-specific and per-TIFF handle (re-entrant) error handler
+and warning handler can be set. Please refer to :doc:`/functions/TIFFError`
+and :doc:`/functions/TIFFOpenOptions`.
+
 Basic File Handling
 -------------------
 
@@ -139,7 +147,7 @@ a ``"w"`` argument:
     main()
     {
         TIFF* tif = TIFFOpen("foo.tif", "w");
-        ... do stuff ...
+        /* ... do stuff ... */
         TIFFClose(tif);
     }
 
@@ -157,6 +165,25 @@ to always call :c:func:`TIFFClose` or :c:func:`TIFFFlush` to flush any
 buffered information to a file.  Note that if you call :c:func:`TIFFClose`
 you do not need to call :c:func:`TIFFFlush`.
 
+.. warning::
+
+    In order to prevent out-of-memory issues when opening a TIFF file
+    :c:func:`TIFFOpenExt` can be used and then the maximum single memory
+    limit in byte that ``libtiff`` internal memory allocation functions
+    are allowed to request per call can be set with
+    :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc`.
+
+Example
+
+::
+
+    tmsize_t limit = (256 * 1024 * 1024);
+    TIFFOpenOptions *opts = TIFFOpenOptionsAlloc();
+    TIFFOpenOptionsSetMaxSingleMemAlloc(opts, limit);
+    TIFF *tif = TIFFOpenExt("foo.tif", "w", opts);
+    TIFFOpenOptionsFree(opts);
+    /* ... go on here ... */
+
 TIFF Directories
 ----------------
 

From 16ab4a205cfc938c32686e8d697d048fabf97ed4 Mon Sep 17 00:00:00 2001
From: Timothy Lyanguzov <theta682@gmail.com>
Date: Sat, 11 Nov 2023 15:25:38 +0000
Subject: [PATCH 2/2] Fix typo.

---
 doc/libtiff.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/libtiff.rst b/doc/libtiff.rst
index d96a8609..4fedc3ed 100644
--- a/doc/libtiff.rst
+++ b/doc/libtiff.rst
@@ -169,7 +169,7 @@ you do not need to call :c:func:`TIFFFlush`.
 
     In order to prevent out-of-memory issues when opening a TIFF file
     :c:func:`TIFFOpenExt` can be used and then the maximum single memory
-    limit in byte that ``libtiff`` internal memory allocation functions
+    limit in bytes that ``libtiff`` internal memory allocation functions
     are allowed to request per call can be set with
     :c:func:`TIFFOpenOptionsSetMaxSingleMemAlloc`.