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