error

error — error messages and error handling

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

const char *        im_error_buffer                     (void);
void                im_error_clear                      (void);
void                im_error                            (const char *domain,
                                                         const char *fmt,
                                                         ...);
void                im_verror                           (const char *domain,
                                                         const char *fmt,
                                                         va_list ap);
void                im_error_system                     (int err,
                                                         const char *domain,
                                                         const char *fmt,
                                                         ...);
void                im_verror_system                    (int err,
                                                         const char *domain,
                                                         const char *fmt,
                                                         va_list ap);
void                im_warn                             (const char *domain,
                                                         const char *fmt,
                                                         ...);
void                im_vwarn                            (const char *domain,
                                                         const char *fmt,
                                                         va_list ap);
void                im_diag                             (const char *domain,
                                                         const char *fmt,
                                                         ...);
void                im_vdiag                            (const char *domain,
                                                         const char *fmt,
                                                         va_list ap);
void                error_exit                          (const char *fmt,
                                                         ...);

Description

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.

Details

im_error_buffer ()

const char *        im_error_buffer                     (void);

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.

See also: im_error_clear().

Returns :

the error buffer as a C string which must not be freed

im_error_clear ()

void                im_error_clear                      (void);

Clear and reset the error buffer. This is typically called after presentng an error to the user.

See also: im_error_buffer().


im_error ()

void                im_error                            (const char *domain,
                                                         const char *fmt,
                                                         ...);

Format the string in the style of printf() and append to the error buffer.

See also: im_error_system(), im_verror().

domain :

the source of the error

fmt :

printf()-style format string for the error

... :

arguments to the format string

im_verror ()

void                im_verror                           (const char *domain,
                                                         const char *fmt,
                                                         va_list ap);

Append a message to the error buffer.

See also: im_error().

domain :

the source of the error

fmt :

printf()-style format string for the error

ap :

arguments to the format string

im_error_system ()

void                im_error_system                     (int err,
                                                         const char *domain,
                                                         const char *fmt,
                                                         ...);

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().

err :

the system error code

domain :

the source of the error

fmt :

printf()-style format string for the error

... :

arguments to the format string

im_verror_system ()

void                im_verror_system                    (int err,
                                                         const char *domain,
                                                         const char *fmt,
                                                         va_list ap);

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().

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

im_warn ()

void                im_warn                             (const char *domain,
                                                         const char *fmt,
                                                         ...);

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().

domain :

the source of the warning message

fmt :

printf()-style format string for the message

... :

arguments to the format string

im_vwarn ()

void                im_vwarn                            (const char *domain,
                                                         const char *fmt,
                                                         va_list ap);

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().

domain :

the source of the warning message

fmt :

printf()-style format string for the message

ap :

arguments to the format string

im_diag ()

void                im_diag                             (const char *domain,
                                                         const char *fmt,
                                                         ...);

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().

domain :

the source of the diagnostic message

fmt :

printf()-style format string for the message

... :

arguments to the format string

im_vdiag ()

void                im_vdiag                            (const char *domain,
                                                         const char *fmt,
                                                         va_list ap);

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().

domain :

the source of the diagnostic message

fmt :

printf()-style format string for the message

ap :

arguments to the format string

error_exit ()

void                error_exit                          (const char *fmt,
                                                         ...);

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.

fmt may be NULL, in which case only the error buffer is printed before exiting.

See also: im_error().

fmt :

printf()-style format string for the message

... :

arguments to the format string