Merge branch 'manpage_fix485_file-descriptor_clientdata' into 'master'

manpage: Correct description of file handle/descriptors tif_fd and tif_clientdata. Closes #485.

Closes #485

See merge request libtiff/libtiff!418

9 files changed, 50 insertions, 43 deletions

diff --git a/doc/functions/TIFFError.rst b/doc/functions/TIFFError.rst
index 98f258ca..f03eef8c 100644
--- a/doc/functions/TIFFError.rst
+++ b/doc/functions/TIFFError.rst
@@ -32,31 +32,26 @@ 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
+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 in order
-to write the error message to a file. Within ``libtiff`` :c:func:`TIFFErrorExt`
-is called using ``tif->tif_clientdata`` as file handle.
+The function :c:func:`TIFFErrorExt` provides a file handle.
+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.
-
+With :c:func:`TIFFSetErrorHandlerExt` an extra error handler can be setup.
 
 Note
 ----
 
-In ``libtiff`` only a default error handler is defined, writing the message
-to ``stderr``. For writing error messages to file, an extra *TIFFErrorHandlerExt*
-function has to be set. :c:func:`TIFFError` and :c:func:`TIFFErrorExt`
-will try to call both handler functions if defined. However, :c:func:`TIFFErrorExt`
-will pass "0" as file handle to the extended error handler.
+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`. 
 
 Return values
 -------------
diff --git a/doc/functions/TIFFFieldQuery.rst b/doc/functions/TIFFFieldQuery.rst
index 6b840ebc..644299cb 100644
--- a/doc/functions/TIFFFieldQuery.rst
+++ b/doc/functions/TIFFFieldQuery.rst
@@ -36,7 +36,7 @@ return a pointer to TIFF field information structure `fip` by the tag's
 With dt== :c:macro:`TIFF_ANY` the behaviour is the same than for
 *TIFFFieldWithTag()*.
 
-    .. TODO: Check if libtiff is able to handle tag definitions with two different
+    .. TODO: Check if ``libtiff`` is able to handle tag definitions with two different
              definitions. From the code point of view, I don't believe that.
 
     Such a `TIFFDataType` dependent search could be useful when the same
diff --git a/doc/functions/TIFFOpen.rst b/doc/functions/TIFFOpen.rst
index 42b93c78..29c7cfc6 100644
--- a/doc/functions/TIFFOpen.rst
+++ b/doc/functions/TIFFOpen.rst
@@ -89,10 +89,11 @@ file should be closed using its file descriptor *fd*.
 :c:func:`TIFFSetFileName` sets the file name in the tif-structure
 and returns the old file name.
 
-:c:func:`TIFFSetFileno` sets open file's I/O descriptor,
-and returns the previous value.
+:c:func:`TIFFSetFileno` overwrites a copy of the open file's I/O descriptor,
+that was saved when the TIFF file was first opened,
+and returns the previous value. See note below.
 
-:c:func:`TIFFSetMode` sets the `libtiff` open mode in the tif-structure
+:c:func:`TIFFSetMode` sets the ``libtiff`` open mode in the tif-structure
 and returns the old mode.
 
 :c:func:`TIFFClientOpen` is like :c:func:`TIFFOpen` except that the caller
@@ -107,9 +108,21 @@ 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:`TIFFClientdata` returns open file's clientdata handle.
+: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.
 
 :c:func:`TIFFSetClientdata` sets open file's clientdata, and return previous value.
+The clientdata is used as open file's I/O descriptor within ``libtiff``.
+
+.. note::
+  *clientdata* is used as file descriptor or handle of the opened TIFF file within
+  `libtif`, whereas the file descriptor *fd* (changeable by :c:func:`TIFFSetFileno`)
+  is only set once to the value of *clientdata* converted to an integer
+  (in tif_win32.c as well as in tif_unix.c).
+  When updating the file's clientdata with :c:func:`TIFFSetClientdata`,
+  the *fd* value is **not** updated.
+
 
 Options
 -------
diff --git a/doc/functions/TIFFReadFromUserBuffer.rst b/doc/functions/TIFFReadFromUserBuffer.rst
index 4566e474..f4ab06de 100644
--- a/doc/functions/TIFFReadFromUserBuffer.rst
+++ b/doc/functions/TIFFReadFromUserBuffer.rst
@@ -19,7 +19,7 @@ Use the provided input buffer (`inbuf`, `insize`) and decompress it
 into (`outbuf`, `outsize`). This function replaces the use of
 :c:func:`TIFFReadEncodedStrip` / :c:func:`TIFFReadEncodedTile`
 when the user can provide the buffer for the input data, for example when
-he wants to avoid libtiff to read the strile offset/count values from the
+he wants to avoid ``libtiff`` to read the strile offset/count values from the
 ``StripOffsets`` / ``StripByteCounts`` or ``TileOffsets`` /
 ``TileByteCounts`` arrays. `inbuf` content must be writable
 (if bit reversal is needed).
diff --git a/doc/functions/TIFFSetTagExtender.rst b/doc/functions/TIFFSetTagExtender.rst
index 730b7c3d..001ec1f6 100644
--- a/doc/functions/TIFFSetTagExtender.rst
+++ b/doc/functions/TIFFSetTagExtender.rst
@@ -16,7 +16,7 @@ Description
 -----------
 
 :c:func:`TIFFSetTagExtender` is used to register the merge function
-for user defined tags as an extender callback with libtiff.
+for user defined tags as an extender callback with ``libtiff``.
 A brief description can be found at :ref:`define_application_tags`.
 
 See also
diff --git a/doc/functions/TIFFStrileQuery.rst b/doc/functions/TIFFStrileQuery.rst
index ab0269f7..d08d0cfd 100644
--- a/doc/functions/TIFFStrileQuery.rst
+++ b/doc/functions/TIFFStrileQuery.rst
@@ -23,7 +23,7 @@ Description
 
 Make defer strile offset/bytecount loading available at runtime
 and add per-strile offset/bytecount loading capabilities. Part of
-this commit makes the behaviour that was previously met when libtiff
+this commit makes the behaviour that was previously met when ``libtiff``
 was compiled with ``-DDEFER_STRILE_LOAD`` available for default builds.
 
 When specifying the new ``D`` (Deferred) :c:func:`TIFFOpen` flag,
diff --git a/doc/functions/TIFFWarning.rst b/doc/functions/TIFFWarning.rst
index 7bc63c7c..38bfbf1c 100644
--- a/doc/functions/TIFFWarning.rst
+++ b/doc/functions/TIFFWarning.rst
@@ -39,27 +39,23 @@ 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 in order
-to write the warning message to a file. Within ``libtiff``
-:c:func:`TIFFWarningExt` is called using ``tif->tif_clientdata`` as file
-handle.
+The function :c:func:`TIFFWarningExt` provides a file handle.
+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 in order to write to a file. The file handle needs to be stored in
-``tif->tif_clientdata`` if the ``libtiff`` internal warnings shall also
-be written to that file.
+setup up.
 
 Note
 ----
-In ``libtiff`` only a default warning handler is defined, writing the
-message to ``stderr``. For writing warning messages to file, an extra
-*TIFFWarningHandlerExt* function has to be set. :c:func:`TIFFWarning` and
-:c:func:`TIFFWarningExt` will try to call both handler functions if
-defined. However, :c:func:`TIFFWarning` will pass "0" as file handle to
-the extended warning handler.
+
+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`. 
 
 Return values
 -------------
diff --git a/doc/functions/TIFFcolor.rst b/doc/functions/TIFFcolor.rst
index d0f43afb..3dbd4f7c 100644
--- a/doc/functions/TIFFcolor.rst
+++ b/doc/functions/TIFFcolor.rst
@@ -26,7 +26,7 @@ Description
 TIFF supports several color spaces for images stored in that format. There is
 usually a problem of application to handle the data properly and convert
 between different colorspaces for displaying and printing purposes. To
-simplify this task libtiff implements several color conversion routines
+simplify this task ``libtiff`` implements several color conversion routines
 itself. In particular, these routines used in the :doc:`TIFFRGBAImage`
 interface.
 
diff --git a/doc/functions/libtiff.rst b/doc/functions/libtiff.rst
index 7b5f5e8c..e259b846 100644
--- a/doc/functions/libtiff.rst
+++ b/doc/functions/libtiff.rst
@@ -140,7 +140,8 @@ will work.
     * - :c:func:`TIFFCleanup`
       - auxiliary function to free the TIFF structure
     * - :c:func:`TIFFClientdata`
-      - return open file's clientdata handle
+      - return open file's clientdata handle, which represents
+        the file descriptor used within ``libtiff``.
     * - :c:func:`TIFFClientOpen`
       - open a file for reading or writing
     * - :c:func:`TIFFClose`
@@ -375,7 +376,8 @@ will work.
     * - :c:func:`TIFFScanlineSize64`
       - return size of a scanline as :c:type:`uint64_t`
     * - :c:func:`TIFFSetClientdata`
-      - set open file's clientdata, and return previous value
+      - set open file's clientdata (file descriptor/handle),
+        and return previous value
     * - :c:func:`TIFFSetClientInfo`
       - adds or replaces an entry in the clientinfo-list
     * - :c:func:`TIFFSetCompressionScheme`
@@ -391,14 +393,15 @@ will work.
     * - :c:func:`TIFFSetFileName`
       - sets the file name in the tif-structure and returns the old file name
     * - :c:func:`TIFFSetFileno`
-      - sets open file's I/O descriptor, and return previous value
+      - 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 tif-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
+        extender callback with ``libtiff``
     * - :c:func:`TIFFSetupStrips`
       -
     * - :c:func:`TIFFSetWarningHandler`
@@ -508,9 +511,9 @@ will work.
     * - :c:func:`_TIFFfree`
       - free memory buffer
     * - :c:func:`_TIFFGetExifFields`
-      - return a pointer to the libtiff internal definition list of the EXIF tags
+      - return a pointer to the ``libtiff`` internal definition list of the EXIF tags
     * - :c:func:`_TIFFGetGpsFields`
-      - return a pointer to the libtiff internal definition list of the GPS tags
+      - return a pointer to the ``libtiff`` internal definition list of the GPS tags
     * - :c:func:`_TIFFmalloc`
       - dynamically allocate memory buffer
     * - :c:func:`_TIFFmemcmp`