.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "TIFFWARNING" "3tiff" "Nov 26, 2023" "4.6" "LibTIFF"
.SH NAME
TIFFWarning \- library warning interface
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#include <tiffio.h>
#include <stdarg.h>
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B void TIFFWarning(const char *module, const char *fmt, \&...) 
.UNINDENT
.INDENT 0.0
.TP
.B void TIFFWarningExt(thandle_t fd, const char *module, const char *fmt, \&...) 
.UNINDENT
.INDENT 0.0
.TP
.B void TIFFWarningExtR(TIFF *tif, const char *module, const char *fmt, \&...) 
.UNINDENT
.INDENT 0.0
.TP
.B typedef void (*TIFFWarningHandler)(const char *module, const char *fmt, va_list ap) 
.UNINDENT
.INDENT 0.0
.TP
.B typedef void (*TIFFWarningHandlerExt)(thandle_t fd, const char *module, const char *fmt, va_list ap) 
.UNINDENT
.INDENT 0.0
.TP
.B typedef int (*TIFFWarningHandlerExtR)(TIFF *tif, void *user_data, const char *module, const char *fmt, va_list ap) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TIFFWarningHandler\fP TIFFSetWarningHandler(\fI\%TIFFWarningHandler\fP handler) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TIFFWarningHandlerExt\fP TIFFSetWarningHandlerExt(\fI\%TIFFWarningHandlerExt\fP handler) 
.UNINDENT
.SH DESCRIPTION
.sp
\fI\%TIFFWarning()\fP invokes the library\-wide warning handler function
to (normally) write a warning message to the \fBstderr\fP\&.
The \fIfmt\fP parameter is a \fBprintf()\fP format string, and any number
arguments can be supplied. The \fImodule\fP 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.
.sp
Applications that desire to capture control in the event of a warning
should use \fI\%TIFFSetWarningHandler()\fP to override the default
warning handler. A \fBNULL\fP (0) warning handler function may be
installed to suppress warning messages.
.sp
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.
\fI\%TIFFWarningExt()\fP and \fI\%TIFFWarningExtR()\fP if the application
intends to call the handler with those extended parameters.
.sp
\fI\%TIFFWarningExt()\fP provides a file handle as parameter.
Within \fBlibtiff\fP \fI\%TIFFWarningExt()\fP is called passing \fBtif\->tif_clientdata\fP
as \fIfd\fP, which represents the TIFF file handle (file descriptor).
The application\-specific and library\-wide handler for \fI\%TIFFWarningExt()\fP
is setup with \fI\%TIFFSetWarningHandlerExt()\fP\&.
.sp
\fI\%TIFFWarningExtR()\fP (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:
\fI\%TIFFOpenExt()\fP, \fI\%TIFFOpenWExt()\fP, \fI\%TIFFFdOpenExt()\fP
or \fI\%TIFFClientOpenExt()\fP\&.
Furthermore, a \fBcustom defined data structure\fP \fIuser_data\fP for the
warning handler can be given along.
.SH NOTE
.sp
Both functions \fI\%TIFFWarning()\fP and \fI\%TIFFWarningExt()\fP
each attempt to call both handler functions if they are defined.
First \fI\%TIFFWarningHandler()\fP is called and then \fI\%TIFFWarningHandlerExt()\fP\&.
However, \fI\%TIFFWarning()\fP passes a \(dq0\(dq as a file handle to
\fI\%TIFFWarningHandlerExt()\fP\&.
.sp
\fI\%TIFFWarningExtR()\fP tries first to call the per\-TIFF handle defined
warning handler. If \fI\%TIFFWarningHandlerExtR()\fP is not defined or
returns 0, \fI\%TIFFWarningHandler()\fP and then \fI\%TIFFWarningHandlerExt()\fP
are called. From libtiff 4.5 onwards \fI\%TIFFWarningExtR()\fP is used
within the \fBlibtiff\fP library.
.SH RETURN VALUES
.sp
\fI\%TIFFSetWarningHandler()\fP and \fI\%TIFFSetWarningHandlerExt()\fP
returns a reference to the previous warning handler function.
.sp
\fI\%TIFFWarningHandlerExtR()\fP returns an integer as \(dqstop\(dq to control the call
of furhter warning handler functions within \fI\%TIFFWarningExtR()\fP:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
0: both functions \fI\%TIFFWarningHandler()\fP and \fI\%TIFFWarningHandlerExt()\fP are called.
.IP \(bu 2
non\-zero: no further warning message function is called.
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fI\%TIFFError\fP (3tiff),
\fI\%TIFFOpen\fP (3tiff),
\fI\%libtiff\fP (3tiff),
printf (3)
.SH AUTHOR
LibTIFF contributors
.SH COPYRIGHT
1988-2023, LibTIFF contributors
.\" Generated by docutils manpage writer.
.