NAME

       TIFFWarning - library warning interface

SYNOPSIS

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

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

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

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

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

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

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

       TIFFWarningHandler TIFFSetWarningHandler(TIFFWarningHandler handler)

       TIFFWarningHandlerExt TIFFSetWarningHandlerExt(TIFFWarningHandlerExt handler)

DESCRIPTION

       TIFFWarning() invokes the library-wide warning handler function to (normally) write a warning message  to
       the 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 a warning is detected.

       Applications  that desire to capture control in the event of a warning should use TIFFSetWarningHandler()
       to override the default warning handler. A NULL (0) warning handler function may be installed to suppress
       warning messages.

       Two  more  application-specific  warning  handler  callbacks  are  available,  each  with  different call
       parameters and passing parameters to the handler.  Each handler is also linked  with  a  warning  message
       function,  i.e.   TIFFWarningExt()  and  TIFFWarningExtR() if the application intends to call the handler
       with those extended parameters.

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

       TIFFWarningExtR()  (introduced  with libtiff 4.5) is called with its TIFF handle and thus provides access
       to a per-TIFF handle (re-entrant) warning handler. That  means  for  different  TIFF  handles,  different
       warning  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 warning handler can
       be given along.

NOTE

       Both functions TIFFWarning() and TIFFWarningExt() each attempt to call both handler functions if they are
       defined.   First TIFFWarningHandler() is called and then TIFFWarningHandlerExt().  However, TIFFWarning()
       passes a "0" as a file handle to TIFFWarningHandlerExt().

       TIFFWarningExtR()  tries  first   to   call   the   per-TIFF   handle   defined   warning   handler.   If
       TIFFWarningHandlerExtR()    is    not    defined    or   returns   0,   TIFFWarningHandler()   and   then
       TIFFWarningHandlerExt() are called. From libtiff 4.5 onwards TIFFWarningExtR() is used within the libtiff
       library.

RETURN VALUES

       TIFFSetWarningHandler()  and  TIFFSetWarningHandlerExt()  returns  a  reference  to  the previous warning
       handler function.

       TIFFWarningHandlerExtR() returns an integer as "stop" to control the  call  of  furhter  warning  handler
       functions within TIFFWarningExtR():

          • 0: both functions TIFFWarningHandler() and TIFFWarningHandlerExt() are called.

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

SEE ALSO

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

AUTHOR

       LibTIFF contributors

COPYRIGHT

       1988-2024, LibTIFF contributors