TIFFWarning — LibTIFF 4.7.0 documentation

# TIFFWarning

## 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)