TIFFError — LibTIFF 4.6.0t documentation

# TIFFError

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