sergiotarxz
/
libvips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

add gtkdocs for error

This commit is contained in:
John Cupitt 2009-10-02 15:40:52 +00:00
parent caa84d3deb
commit 1588dd3288
10 changed files with 249 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
ChangeLog
View File

@ -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

1
doc/reference/libvips-docs.sgml.in
View File

@ -20,6 +20,7 @@
<xi:include href="xml/image.xml"/>
<xi:include href="xml/header.xml"/>
<xi:include href="xml/callback.xml"/>
<xi:include href="xml/error.xml"/>
<xi:include href="xml/meta.xml"/>
<xi:include href="xml/buf.xml"/>
</chapter>

1
libvips/include/vips/Makefile.am
View File

@ -8,6 +8,7 @@ pkginclude_HEADERS = \
format.h \
header.h \
callback.h \
error.h \
fmask.h \
mosaic.h \
interpolate.h \

61
libvips/include/vips/error.h Normal file
View File

@ -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*/

18
libvips/include/vips/proto.h
View File

@ -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 );

1
libvips/include/vips/vips.h
View File

@ -125,6 +125,7 @@ typedef struct im__DOUBLEMASK {
#include <vips/image.h>
#include <vips/almostdeprecated.h>
#include <vips/callback.h>
#include <vips/error.h>
#include <vips/util.h>
#include <vips/colour.h>
/* #include <vips/vector.h> */

1
libvips/iofuncs/Makefile.am
View File

@ -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 \

183
libvips/iofuncs/error.c
View File

@ -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 <dmalloc.h>
#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 );
}

75
libvips/iofuncs/error_exit.c
View File

@ -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 <config.h>
#endif /*HAVE_CONFIG_H*/
#include <vips/intl.h>
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
#include <vips/vips.h>
#ifdef WITH_DMALLOC
#include <dmalloc.h>
#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 );
}

2
libvips/iofuncs/header.c
View File

@ -66,7 +66,7 @@
* SECTION: header
* @short_description: get, set and walk image headers
* @stability: Stable
* @see_also: meta
* @see_also: <link linkend="libvips-meta">meta</link>
* @include: vips/vips.h
*
* These functions let you get at image header data (including metadata) in a