TIFFOpenOptions — LibTIFF 4.7.1 documentation

# TIFFOpenOptions

## Synopsis

    #include <tiffio.h>

typedef TIFFOpenOptions TIFFOpenOptions

TIFFOpenOptions *TIFFOpenOptionsAlloc(void)

void TIFFOpenOptionsFree(TIFFOpenOptions*)

void TIFFOpenOptionsSetMaxSingleMemAlloc(TIFFOpenOptions *opts, tmsize_t max_single_mem_alloc)

void TIFFOpenOptionsSetMaxCumulatedMemAlloc(TIFFOpenOptions *opts, tmsize_t max_cumulated_mem_alloc)

void TIFFOpenOptionsSetErrorHandlerExtR(TIFFOpenOptions *opts, TIFFErrorHandlerExtR handler, void *errorhandler_user_data)

void TIFFOpenOptionsSetWarningHandlerExtR(TIFFOpenOptions *opts, TIFFErrorHandlerExtR handler, void *warnhandler_user_data)

void TIFFOpenOptionsSetWarnAboutUnknownTags(TIFFOpenOptions *opts, int warn_about_unknown_tags)

## Description

`TIFFOpenOptions` is an opaque structure which can be passed to the TIFF open"Ext" functions to define some `libtiff` internal settings. The settings are the maximum single memory allocation limit and per-TIFF handle (re-entrant) error handler and warning handler functions. For those handler a pointer to a custom defined data structure user_data can be given along.

`TIFFOpenOptionsAlloc()` allocates memory for the `TIFFOpenOptions` opaque structure and returns a `TIFFOpenOptions` pointer.

`TIFFOpenOptionsFree()` releases the allocated memory for `TIFFOpenOptions`. The allocated memory for `TIFFOpenOptions` can be released straight after successful execution of the related TIFFOpen"Ext" functions like `TIFFOpenExt()`.

`TIFFOpenOptionsSetMaxSingleMemAlloc()` (added in libtiff 4.5.0) sets the value for the maximum single memory limit in byte that `libtiff` internal memory allocation functions are allowed to request per call.

Note

However, the `libtiff` external functions `_TIFFmalloc()` and `_TIFFrealloc()` do not apply this internal memory allocation limit set by `TIFFOpenOptionsSetMaxSingleMemAlloc()`!

`TIFFOpenOptionsSetMaxCumulatedMemAlloc()` (added in libtiff 4.6.1) sets the maximum cumulated memory allocations in byte, for a given TIFF handle, that `libtiff` internal memory allocation functions are allowed.

Note

However, the `libtiff` external functions `_TIFFmalloc()` and `_TIFFrealloc()` do not apply this internal memory allocation limit set by `TIFFOpenOptionsSetMaxCumulatedMemAlloc()`!

`TIFFOpenOptionsSetErrorHandlerExtR()` sets the function pointer to an application-specific and per-TIFF handle (re-entrant) error handler. Furthermore, a pointer to a custom defined data structure errorhandler_user_data can be passed. This error handler is invoked through `TIFFErrorExtR()` and the errorhandler_user_data pointer is given along. The errorhandler_user_data argument may be NULL.

`TIFFOpenOptionsSetWarningHandlerExtR()` works like `TIFFOpenOptionsSetErrorHandlerExtR()` but for the warning handler, which is invoked through `TIFFWarningExtR()`

`TIFFOpenOptionsSetWarnAboutUnknownTags()` sets whether libtiff should emit a warning when encountering a unknown tag. This function has been added in libtiff 4.7.1 and the default value is FALSE (change of behaviour compared to earlier versions).

## Example

    #include "tiffio.h"

    typedef struct MyErrorHandlerUserDataStruct
    {
        /* ... any user data structure ... */
    } MyErrorHandlerUserDataStruct;

    static int myErrorHandler(TIFF *tiff, void *user_data, const char *module,
                          const char *fmt, va_list ap)
    {
        MyErrorHandlerUserDataStruct *errorhandler_user_data =
            (MyErrorHandlerUserDataStruct *)user_data;
        /*... code of myErrorHandler ...*/
        return 1;
    }

    main()
    {
        tmsize_t limit = (256 * 1024 * 1024);
        MyErrorHandlerUserDataStruct user_data = { /* ... any data ... */};

        TIFFOpenOptions *opts = TIFFOpenOptionsAlloc();
        TIFFOpenOptionsSetMaxSingleMemAlloc(opts, limit);
        TIFFOpenOptionsSetErrorHandlerExtR(opts, myErrorHandler, &user_data);
        TIFF *tif = TIFFOpenExt("foo.tif", "r", opts);
        TIFFOpenOptionsFree(opts);
        /* ... go on here ... */

        TIFFClose(tif);
    }

## Note

This functionality was introduced with libtiff 4.5.

## See also

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