File Manager - sh-3ll

Current Directory: /usr/share/doc/libtiff-devel/html/man
Viewing File: /usr/share/doc/libtiff-devel/html/man/TIFFOpenOptions.3tiff.html
<!-- Creator     : groff version 1.22.4 -->
<!-- CreationDate: Sun Nov  2 19:00:00 2025 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
       p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
       pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
       table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
       h1      { text-align: center }
</style>
<title>TIFFOPENOPTIONS</title>

</head>
<body>

<h1 align="center">TIFFOPENOPTIONS</h1>

<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#EXAMPLE">EXAMPLE</a><br>
<a href="#NOTE">NOTE</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#AUTHOR">AUTHOR</a><br>
<a href="#COPYRIGHT">COPYRIGHT</a><br>

<hr>


<h2>NAME
<a name="NAME"></a>
</h2>



<p style="margin-left:11%; margin-top: 1em">TIFFOpenOptions
&minus; open a TIFF file for reading or writing</p>

<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>


<pre style="margin-left:15%; margin-top: 1em">#include &lt;tiffio.h&gt;</pre>


<p style="margin-left:11%;"><b>typedef</b>
<i>TIFFOpenOptions</i> <b>TIFFOpenOptions</b> <i><br>
TIFFOpenOptions</i> <b>*TIFFOpenOptionsAlloc(void) <br>
void TIFFOpenOptionsFree(</b><i>TIFFOpenOptions</i><b>*)
<br>
void
TIFFOpenOptionsSetMaxSingleMemAlloc(</b><i>TIFFOpenOptions</i>
<b>*opts, <br>
tmsize_t max_single_mem_alloc) <br>
void
TIFFOpenOptionsSetMaxCumulatedMemAlloc(</b><i>TIFFOpenOptions</i>
<b>*opts, <br>
tmsize_t max_cumulated_mem_alloc) <br>
void
TIFFOpenOptionsSetErrorHandlerExtR(</b><i>TIFFOpenOptions</i>
<b>*opts, -</b> <i><br>
TIFFErrorHandlerExtR</i> <b>handler, void
*errorhandler_user_data) <br>
void
TIFFOpenOptionsSetWarningHandlerExtR(</b><i>TIFFOpenOptions</i>
<b>*opts, -</b> <i><br>
TIFFErrorHandlerExtR</i> <b>handler, void
*warnhandler_user_data) <br>
void
TIFFOpenOptionsSetWarnAboutUnknownTags(</b><i>TIFFOpenOptions</i>
<b>*opts, int <br>
warn_about_unknown_tags)</b></p>

<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>



<p style="margin-left:11%; margin-top: 1em"><b><i>TIFFOpenOptions</i></b>
is an opaque structure which can be passed to the TIFF
open&quot;Ext&quot; functions to define some <b>libtiff</b>
internal settings. The settings are the maximum single
memory allocation limit and per&minus;TIFF handle
(re&minus;entrant) error handler and warning handler
functions. For those handler a pointer to a <b>custom
defined data structure</b> <i>user_data</i> can be given
along.</p>


<p style="margin-left:11%; margin-top: 1em"><i>TIFFOpenOptionsAlloc()</i>
allocates memory for the <i>TIFFOpenOptions</i> opaque
structure and returns a <i>TIFFOpenOptions</i> pointer.</p>


<p style="margin-left:11%; margin-top: 1em"><i>TIFFOpenOptionsFree()</i>
releases the allocated memory for <i>TIFFOpenOptions</i>.
The allocated memory for <i>TIFFOpenOptions</i> can be
released straight after successful execution of the related
TIFFOpen&quot;Ext&quot; functions like
<i>TIFFOpenExt()</i>.</p>


<p style="margin-left:11%; margin-top: 1em"><i>TIFFOpenOptionsSetMaxSingleMemAlloc()</i>
(added in libtiff 4.5.0) sets the value for the maximum
single memory limit in byte that <b>libtiff</b> internal
memory allocation functions are allowed to request per
call.</p>


<p style="margin-left:11%; margin-top: 1em"><b>NOTE:</b></p>

<p style="margin-left:15%;">However, the <b>libtiff</b>
external functions <i>_TIFFmalloc()</i> and -
<i>_TIFFrealloc()</i> <b>do not apply</b> this internal
memory allocation limit set by
<i>TIFFOpenOptionsSetMaxSingleMemAlloc()</i>!</p>


<p style="margin-left:11%; margin-top: 1em"><i>TIFFOpenOptionsSetMaxCumulatedMemAlloc()</i>
(added in libtiff 4.6.1) sets the maximum cumulated memory
allocations in byte, for a given TIFF handle, that
<b>libtiff</b> internal memory allocation functions are
allowed.</p>


<p style="margin-left:11%; margin-top: 1em"><b>NOTE:</b></p>

<p style="margin-left:15%;">However, the <b>libtiff</b>
external functions <i>_TIFFmalloc()</i> and -
<i>_TIFFrealloc()</i> <b>do not apply</b> this internal
memory allocation limit set by
<i>TIFFOpenOptionsSetMaxCumulatedMemAlloc()</i>!</p>


<p style="margin-left:11%; margin-top: 1em"><i>TIFFOpenOptionsSetErrorHandlerExtR()</i>
sets the function pointer to an application&minus;specific
and per&minus;TIFF handle (re&minus;entrant) error handler.
Furthermore, a pointer to a <b>custom defined data
structure</b> <i>errorhandler_user_data</i> can be passed.
This error handler is invoked through <i>TIFFErrorExtR()</i>
and the <i>errorhandler_user_data</i> pointer is given
along. The <i>errorhandler_user_data</i> argument may be
NULL.</p>


<p style="margin-left:11%; margin-top: 1em"><i>TIFFOpenOptionsSetWarningHandlerExtR()</i>
works like <i>TIFFOpenOptionsSetErrorHandlerExtR()</i> but
for the warning handler, which is invoked through
<i>TIFFWarningExtR()</i></p>


<p style="margin-left:11%; margin-top: 1em"><i>TIFFOpenOptionsSetWarnAboutUnknownTags()</i>
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).</p>

<h2>EXAMPLE
<a name="EXAMPLE"></a>
</h2>

<pre style="margin-left:15%; margin-top: 1em">#include &quot;tiffio.h&quot;

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, &amp;user_data);
    TIFF *tif = TIFFOpenExt(&quot;foo.tif&quot;, &quot;r&quot;, opts);
    TIFFOpenOptionsFree(opts);
    /* ... go on here ... */

    TIFFClose(tif);
}</pre>

<h2>NOTE
<a name="NOTE"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">This
functionality was introduced with libtiff 4.5.</p>

<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em"><i>libtiff</i>
(3tiff), <i>TIFFOpen</i> (3tiff), <i>TIFFError</i> (3tiff),
<i>TIFFWarning</i> (3tiff)</p>

<h2>AUTHOR
<a name="AUTHOR"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">LibTIFF
contributors</p>

<h2>COPYRIGHT
<a name="COPYRIGHT"></a>
</h2>


<p style="margin-left:11%; margin-top: 1em">1988-2025,
LibTIFF contributors</p>
<hr>
</body>
</html>