NAME

       TIFFError - library error handling interface

SYNOPSIS

          #include <tiffio.h>
          #include <stdarg.h>

       void TIFFError(const char *module, const char *fmt, ...)

       void TIFFErrorExt(thandle_t fd, const char *module, const char *fmt, ...)

       void TIFFErrorExtR(TIFF *tif, const char *module, const char *fmt, ...)

       typedef void (*TIFFErrorHandler)(const char *module, const char *fmt, va_list ap)

       typedef void (*TIFFErrorHandlerExt)(thandle_t fd, const char *module, const char *fmt, va_list ap)

       typedef int (*TIFFErrorHandlerExtR)(TIFF *tif, void *user_data, const char *module, const char *fmt,
       va_list ap)

       TIFFErrorHandler TIFFSetErrorHandler(TIFFErrorHandler handler)

       TIFFErrorHandlerExt TIFFSetErrorHandlerExt(TIFFErrorHandlerExt handler)

DESCRIPTION

       TIFFError()  invokes  the  library-wide  error  handler  function to (normally) write an error message to
       stderr.  The fmt parameter is a 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 TIFFSetErrorHandler()  to
       override  the default error handler. A 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.
       TIFFErrorExt() and TIFFErrorExtR() if the application intends to call the  handler  with  those  extended
       parameters.

       TIFFErrorExt()   provides  a  file  handle as parameter.  Within libtiff TIFFErrorExt() is called passing
       tif->tif_clientdata  as  fd,  which  represents  the   TIFF   file   handle   (file   descriptor).    The
       application-specific and library-wide handler for TIFFErrorExt() is setup with TIFFSetErrorHandlerExt().

       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:  TIFFOpenExt(),  TIFFOpenWExt(),  TIFFFdOpenExt()  or TIFFClientOpenExt().
       Furthermore, a custom defined data structure user_data for the error handler can be given along.

       Please refer to TIFFOpenOptions for how to setup the application-specific handler introduced with libtiff
       4.5.

NOTE

       Both functions TIFFError() and TIFFErrorExt() each attempt to call both handler  functions  if  they  are
       defined.  First TIFFErrorHandler() is called and then TIFFErrorHandlerExt().  However, TIFFError() passes
       a "0" as a file handle to TIFFErrorHandlerExt().

       TIFFErrorExtR()  tries first to call the per-TIFF handle defined error handler. If TIFFErrorHandlerExtR()
       is not defined or returns 0, TIFFErrorHandler() and then TIFFErrorHandlerExt() are called.  From  libtiff
       4.5  onwards  TIFFErrorExtR()  is  used  within  the  libtiff library where the TIFF handle is available.
       Otherwise, TIFFErrorExt() is used!

RETURN VALUES

       TIFFSetErrorHandler() and TIFFSetErrorHandlerExt() returns a reference  to  the  previous  error  handler
       function.

       TIFFErrorHandlerExtR()  returns  an  integer  as  "stop"  to  control  the  call of further error handler
       functions within TIFFErrorExtR():

          • 0: both functions TIFFErrorHandler() and TIFFErrorHandlerExt() are called.

          • non-zero: no further error message function is called.

SEE ALSO

       TIFFWarning (3tiff), TIFFOpen (3tiff), libtiff (3tiff), printf (3)

AUTHOR

       LibTIFF contributors

COPYRIGHT

       1988-2024, LibTIFF contributors

4.5                                               Sep 05, 2024                                  TIFFERROR(3tiff)