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`