diff --git a/ChangeLog b/ChangeLog
index 786a6bb9..dba5edd9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -54,6 +54,7 @@
- gtk-doc comments for header
- im_printlines(), im_debugim() deprecated (use im_vips2csv() instead)
- callback gtkdocs
+- error gtkdocs
25/3/09 started 7.18.0
- revised version numbers
diff --git a/doc/reference/libvips-docs.sgml.in b/doc/reference/libvips-docs.sgml.in
index b14df8c6..a0efbfac 100644
--- a/doc/reference/libvips-docs.sgml.in
+++ b/doc/reference/libvips-docs.sgml.in
@@ -20,6 +20,7 @@
+
diff --git a/libvips/include/vips/Makefile.am b/libvips/include/vips/Makefile.am
index 21d59ae7..f207979a 100644
--- a/libvips/include/vips/Makefile.am
+++ b/libvips/include/vips/Makefile.am
@@ -8,6 +8,7 @@ pkginclude_HEADERS = \
format.h \
header.h \
callback.h \
+ error.h \
fmask.h \
mosaic.h \
interpolate.h \
diff --git a/libvips/include/vips/error.h b/libvips/include/vips/error.h
new file mode 100644
index 00000000..84838369
--- /dev/null
+++ b/libvips/include/vips/error.h
@@ -0,0 +1,61 @@
+/* Error handling.
+ */
+
+/*
+
+ Copyright (C) 1991-2005 The National Gallery
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+ */
+
+/*
+
+ These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk
+
+ */
+
+#ifndef IM_ERROR_H
+#define IM_ERROR_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif /*__cplusplus*/
+
+const char *im_error_buffer( void );
+void im_error_clear( void );
+
+void im_error( const char *domain, const char *fmt, ... )
+ __attribute__((format(printf, 2, 3)));
+void im_verror( const char *domain, const char *fmt, va_list ap );
+void im_error_system( int err, const char *domain, const char *fmt, ... )
+ __attribute__((format(printf, 3, 4)));
+void im_verror_system( int err, const char *domain,
+ const char *fmt, va_list ap );
+void im_warn( const char *domain, const char *fmt, ... )
+ __attribute__((format(printf, 2, 3)));
+void im_vwarn( const char *domain, const char *fmt, va_list ap );
+void im_diag( const char *domain, const char *fmt, ... )
+ __attribute__((format(printf, 2, 3)));
+void im_vdiag( const char *domain, const char *fmt, va_list ap );
+
+void error_exit( const char *fmt, ... )
+ __attribute__((noreturn, format(printf, 1, 2)));
+
+#ifdef __cplusplus
+}
+#endif /*__cplusplus*/
+
+#endif /*!IM_ERROR_H*/
diff --git a/libvips/include/vips/proto.h b/libvips/include/vips/proto.h
index eb9ca278..101bb4b4 100644
--- a/libvips/include/vips/proto.h
+++ b/libvips/include/vips/proto.h
@@ -146,24 +146,6 @@ int im_existsf( const char *name, ... )
__attribute__((format(printf, 1, 2)));
int im_isvips( const char * );
-void error_exit( const char *, ... )
- __attribute__((noreturn, format(printf, 1, 2)));
-const char *im_error_buffer( void );
-void im_error_clear( void );
-void im_verror( const char *domain, const char *fmt, va_list ap );
-void im_error( const char *domain, const char *fmt, ... )
- __attribute__((format(printf, 2, 3)));
-void im_verror_system( int err, const char *domain,
- const char *fmt, va_list ap );
-void im_error_system( int err, const char *domain, const char *fmt, ... )
- __attribute__((format(printf, 3, 4)));
-void im_vdiag( const char *domain, const char *fmt, va_list ap );
-void im_warn( const char *domain, const char *fmt, ... )
- __attribute__((format(printf, 2, 3)));
-void im_vwarn( const char *domain, const char *fmt, va_list ap );
-void im_diag( const char *domain, const char *fmt, ... )
- __attribute__((format(printf, 2, 3)));
-
int im_bits_of_fmt( VipsBandFmt fmt );
const char *im_Type2char( VipsType type );
const char *im_BandFmt2char( VipsBandFmt fmt );
diff --git a/libvips/include/vips/vips.h b/libvips/include/vips/vips.h
index 5d29b93a..564b6069 100644
--- a/libvips/include/vips/vips.h
+++ b/libvips/include/vips/vips.h
@@ -125,6 +125,7 @@ typedef struct im__DOUBLEMASK {
#include
#include
#include
+#include
#include
#include
/* #include */
diff --git a/libvips/iofuncs/Makefile.am b/libvips/iofuncs/Makefile.am
index b46477f1..27c469e2 100644
--- a/libvips/iofuncs/Makefile.am
+++ b/libvips/iofuncs/Makefile.am
@@ -9,7 +9,6 @@ libiofuncs_la_SOURCES = \
debug.c \
dispatch_types.c \
error.c \
- error_exit.c \
im_binfile.c \
im_bits_of_fmt.c \
im_close.c \
diff --git a/libvips/iofuncs/error.c b/libvips/iofuncs/error.c
index ac472daa..f94659ab 100644
--- a/libvips/iofuncs/error.c
+++ b/libvips/iofuncs/error.c
@@ -9,6 +9,9 @@
* - lock around error buffer changes
* 20/2/08
* - lock around warnings and diagnostics too, why not
+ * 2/10/09
+ * - error_exit() moved here
+ * - gtkdoc comments
*/
/*
@@ -61,6 +64,43 @@
#include
#endif /*WITH_DMALLOC*/
+/**
+ * SECTION: error
+ * @short_description: error messages and error handling
+ * @stability: Stable
+ * @include: vips/vips.h
+ *
+ * VIPS maintains an error buffer (a log of localised text messages),
+ * a set of functions
+ * for adding messages, and a way to access and clear the buffer.
+ *
+ * The error buffer is global, that is, it is shared between all threads. You
+ * can add to the buffer from any thread (there is a lock to prevent
+ * corruption), but it's sensible to only read and clear the buffer from the
+ * main thread of execution.
+ *
+ * The general principle is: if you detect an error, log a message for the
+ * user. If a function you call detects an error, just propogate it and don't
+ * add another message.
+ *
+ * |[
+ * IMAGE *im;
+ *
+ * if( !(im = im_open( filename, "r" )) )
+ * // im_open will set a mmessage, we don't need to
+ * return( -1 );
+ *
+ * if( im->Xsize < 100 ) {
+ * // we have detected an error, we must set a message
+ * im_error( "myprogram", "%s", _( "XSize too small" ) );
+ * return( -1 );
+ * }
+ * ]|
+ *
+ * The domain argument most of these functions take is not localised and is
+ * supposed to indicate the component which failed.
+ */
+
/* Make global array to keep the error message buffer.
*/
#define IM_MAX_ERROR (10240)
@@ -70,6 +110,16 @@ static VipsBuf im_error_buf = VIPS_BUF_STATIC( im_error_text );
#define IM_DIAGNOSTICS "IM_DIAGNOSTICS"
#define IM_WARNING "IM_WARNING"
+/**
+ * im_error_buffer:
+ *
+ * Get a pointer to the start of the error buffer as a C string.
+ * The string is owned by the error system and must not be freed.
+ *
+ * Returns: the error buffer as a C string which must not be freed
+ *
+ * See also: im_error_clear().
+ */
const char *
im_error_buffer( void )
{
@@ -82,6 +132,16 @@ im_error_buffer( void )
return( msg );
}
+/**
+ * im_verror:
+ * @domain: the source of the error
+ * @fmt: printf()-style format string for the error
+ * @ap: arguments to the format string
+ *
+ * Append a message to the error buffer.
+ *
+ * See also: im_error().
+ */
void
im_verror( const char *domain, const char *fmt, va_list ap )
{
@@ -92,6 +152,16 @@ im_verror( const char *domain, const char *fmt, va_list ap )
g_mutex_unlock( im__global_lock );
}
+/**
+ * im_error:
+ * @domain: the source of the error
+ * @fmt: printf()-style format string for the error
+ * @Varargs: arguments to the format string
+ *
+ * Format the string in the style of printf() and append to the error buffer.
+ *
+ * See also: im_error_system(), im_verror().
+ */
void
im_error( const char *domain, const char *fmt, ... )
{
@@ -102,6 +172,19 @@ im_error( const char *domain, const char *fmt, ... )
va_end( ap );
}
+/**
+ * im_verror_system:
+ * @err: the system error code
+ * @domain: the source of the error
+ * @fmt: printf()-style format string for the error
+ * @ap: arguments to the format string
+ *
+ * Format the string in the style of printf() and append to the error buffer.
+ * Then create and append a localised message based on the system error code,
+ * usually the value of errno.
+ *
+ * See also: im_error_system().
+ */
void
im_verror_system( int err, const char *domain, const char *fmt, va_list ap )
{
@@ -134,6 +217,19 @@ im_verror_system( int err, const char *domain, const char *fmt, va_list ap )
#endif /*OS_WIN32*/
}
+/**
+ * im_error_system:
+ * @err: the system error code
+ * @domain: the source of the error
+ * @fmt: printf()-style format string for the error
+ * @Varargs: arguments to the format string
+ *
+ * Format the string in the style of printf() and append to the error buffer.
+ * Then create and append a localised message based on the system error code,
+ * usually the value of errno.
+ *
+ * See also: im_verror_system().
+ */
void
im_error_system( int err, const char *domain, const char *fmt, ... )
{
@@ -144,6 +240,14 @@ im_error_system( int err, const char *domain, const char *fmt, ... )
va_end( ap );
}
+/**
+ * im_error_clear:
+ *
+ * Clear and reset the error buffer. This is typically called after presentng
+ * an error to the user.
+ *
+ * See also: im_error_buffer().
+ */
void
im_error_clear( void )
{
@@ -152,6 +256,20 @@ im_error_clear( void )
g_mutex_unlock( im__global_lock );
}
+/**
+ * im_vdiag:
+ * @domain: the source of the diagnostic message
+ * @fmt: printf()-style format string for the message
+ * @ap: arguments to the format string
+ *
+ * Sends a formatted diagnostic message to stderr. If you define the
+ * environment variable IM_DIAGNOSTICS, these message are surpressed.
+ *
+ * Diagnostic messages are used to report details about the operation of
+ * functions.
+ *
+ * See also: im_diag(), im_warn().
+ */
void
im_vdiag( const char *domain, const char *fmt, va_list ap )
{
@@ -165,6 +283,20 @@ im_vdiag( const char *domain, const char *fmt, va_list ap )
}
}
+/**
+ * im_diag:
+ * @domain: the source of the diagnostic message
+ * @fmt: printf()-style format string for the message
+ * @Varargs: arguments to the format string
+ *
+ * Sends a formatted diagnostic message to stderr. If you define the
+ * environment variable IM_DIAGNOSTICS, these message are surpressed.
+ *
+ * Diagnostic messages are used to report details about the operation of
+ * functions.
+ *
+ * See also: im_vdiag(), im_warn().
+ */
void
im_diag( const char *domain, const char *fmt, ... )
{
@@ -175,6 +307,19 @@ im_diag( const char *domain, const char *fmt, ... )
va_end( ap );
}
+/**
+ * im_vwarn:
+ * @domain: the source of the warning message
+ * @fmt: printf()-style format string for the message
+ * @ap: arguments to the format string
+ *
+ * Sends a formatted warning message to stderr. If you define the
+ * environment variable IM_WARNING, these message are surpressed.
+ *
+ * Warning messages are used to report things like overflow counts.
+ *
+ * See also: im_diag(), im_warn().
+ */
void
im_vwarn( const char *domain, const char *fmt, va_list ap )
{
@@ -188,6 +333,19 @@ im_vwarn( const char *domain, const char *fmt, va_list ap )
}
}
+/**
+ * im_warn:
+ * @domain: the source of the warning message
+ * @fmt: printf()-style format string for the message
+ * @Varargs: arguments to the format string
+ *
+ * Sends a formatted warning message to stderr. If you define the
+ * environment variable IM_WARNING, these message are surpressed.
+ *
+ * Warning messages are used to report things like overflow counts.
+ *
+ * See also: im_diag(), im_vwarn().
+ */
void
im_warn( const char *domain, const char *fmt, ... )
{
@@ -197,3 +355,28 @@ im_warn( const char *domain, const char *fmt, ... )
im_vwarn( domain, fmt, ap );
va_end( ap );
}
+
+/**
+ * error_exit:
+ * @fmt: printf()-style format string for the message
+ * @Varargs: arguments to the format string
+ *
+ * Sends a formatted error message to stderr, then sends the contents of the
+ * error buffer, if any, then terminates the program with an error code.
+ */
+void
+error_exit( const char *fmt, ... )
+{
+ va_list ap;
+
+ fprintf( stderr, "%s: ", g_get_prgname() );
+
+ va_start( ap, fmt );
+ (void) vfprintf( stderr, fmt, ap );
+ va_end( ap );
+
+ fprintf( stderr, "\n" );
+ fprintf( stderr, "%s", im_error_buffer() );
+
+ exit( 1 );
+}
diff --git a/libvips/iofuncs/error_exit.c b/libvips/iofuncs/error_exit.c
deleted file mode 100644
index 370c848d..00000000
--- a/libvips/iofuncs/error_exit.c
+++ /dev/null
@@ -1,75 +0,0 @@
-/* @(#) print error mesg on stderr and exit(1)
- * @(#) It also prints any additional error messages set by the routines
- * @(#)
- * @(#) Usage:
- * @(#) void error_exit(variable_arg_list)
- *
- * Copyright: N. Dessipris
- * Written on: 19/03/1991
- * Modified on:
- * 11/5/93 J.Cupitt
- * - strange extra newlines removed - see im_errormsg()
- * - strange tests removed
- * 28-4-99 JC
- * - ansified
- * 2/8/06
- * - print prgname
- */
-
-/*
-
- This file is part of VIPS.
-
- VIPS is free software; you can redistribute it and/or modify
- it under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-
- */
-
-/*
-
- These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk
-
- */
-
-#ifdef HAVE_CONFIG_H
-#include
-#endif /*HAVE_CONFIG_H*/
-#include
-
-#include
-#include
-#include
-
-#include
-
-#ifdef WITH_DMALLOC
-#include
-#endif /*WITH_DMALLOC*/
-
-void
-error_exit( const char *fmt, ... )
-{
- va_list ap;
-
- fprintf( stderr, "%s: ", g_get_prgname() );
-
- va_start( ap, fmt );
- (void) vfprintf( stderr, fmt, ap );
- va_end( ap );
-
- fprintf( stderr, "\n" );
- fprintf( stderr, "%s", im_error_buffer() );
-
- exit( 1 );
-}
diff --git a/libvips/iofuncs/header.c b/libvips/iofuncs/header.c
index a73bf1b2..8fcec6a8 100644
--- a/libvips/iofuncs/header.c
+++ b/libvips/iofuncs/header.c
@@ -66,7 +66,7 @@
* SECTION: header
* @short_description: get, set and walk image headers
* @stability: Stable
- * @see_also: meta
+ * @see_also: meta
* @include: vips/vips.h
*
* These functions let you get at image header data (including metadata) in a