error

error — error messages and error handling

Stability Level

Stable, unless otherwise indicated

Includes

#include <vips/vips.h>

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.

1
2
3
4
5
6
7
8
9
10
11
IMAGE *im;

if( !(im = vips_image_new_from_file( filename, NULL )) )
  // vips_image_new_from_file() will set a message, we don't need to
  return( -1 );

if( vips_image_get_width( im ) < 100 ) {
  // we have detected an error, we must set a message
  vips_error( "myprogram", "%s", _( "width too small" ) );
  return( -1 );
}

The domain argument most of these functions take is not localised and is supposed to indicate the component which failed.

libvips uses g_warning() and g_info() to send warning and information messages to the user. You can use the usual glib mechanisms to display or divert these messages. For example, info messages are hidden by default, but you can see them with:

1
2
3
4
5
6
7
8
9
10
11
12
$ G_MESSAGES_DEBUG=VIPS vipsthumbnail k2.jpg 
VIPS-INFO: thumbnailing k2.jpg
VIPS-INFO: selected loader is VipsForeignLoadJpegFile
VIPS-INFO: input size is 1450 x 2048
VIPS-INFO: loading jpeg with factor 8 pre-shrink
VIPS-INFO: converting to processing space srgb
VIPS-INFO: residual reducev by 0.5
VIPS-INFO: 13 point mask
VIPS-INFO: using vector path
VIPS-INFO: residual reduceh by 0.5
VIPS-INFO: 13 point mask
VIPS-INFO: thumbnailing k2.jpg as ./tn_k2.jpg

Functions

vips_error_buffer ()

const char *
vips_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: vips_error_clear().

Returns

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


vips_error_clear ()

void
vips_error_clear (void);

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

See also: vips_error_buffer().


vips_error_freeze ()

void
vips_error_freeze (void);

Stop errors being logged. Use vips_error_thaw() to unfreeze. You can nest freeze/thaw pairs.


vips_error_thaw ()

void
vips_error_thaw (void);

Reenable error logging.


vips_error ()

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

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

See also: vips_error_system(), vips_verror().

Parameters

domain

the source of the error

 

fmt

printf()-style format string for the error

 

...

arguments to the format string

 

vips_verror ()

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

Append a message to the error buffer.

See also: vips_error().

Parameters

domain

the source of the error

 

fmt

printf()-style format string for the error

 

ap

arguments to the format string

 

vips_error_system ()

void
vips_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: vips_verror_system().

Parameters

err

the system error code

 

domain

the source of the error

 

fmt

printf()-style format string for the error

 

...

arguments to the format string

 

vips_verror_system ()

void
vips_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: vips_error_system().

Parameters

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

 

vips_error_g ()

void
vips_error_g (GError **error);

This function sets the glib error pointer from the vips error buffer and clears it. It's handy for returning errors to glib functions from vips.

See vips_g_error() for the inverse operation.

See also: g_set_error(), vips_g_error().

Parameters

error

glib error pointer.

[out]

vips_g_error ()

void
vips_g_error (GError **error);

This function adds the GError to the vips error buffer and clears it. It's the opposite of vips_error_g().

See also: vips_error_g().

Parameters

error

glib error pointer

 

vips_error_exit ()

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

Sends a formatted error message to stderr, then sends the contents of the error buffer, if any, then shuts down vips and terminates the program with an error code.

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

See also: vips_error().

Parameters

fmt

printf()-style format string for the message

 

...

arguments to the format string

 

vips_check_uncoded ()

int
vips_check_uncoded (const char *domain,
                    VipsImage *im);

Check that the image is not coded. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 on OK, or -1 on error.


vips_check_coding ()

int
vips_check_coding (const char *domain,
                   VipsImage *im,
                   VipsCoding coding);

Check that the image has the required coding . If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

coding

required coding

 

Returns

0 on OK, or -1 on error.


vips_check_coding_known ()

int
vips_check_coding_known (const char *domain,
                         VipsImage *im);

Check that the image is uncoded, LABQ coded or RAD coded. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 on OK, or -1 on error.


vips_check_coding_noneorlabq ()

int
vips_check_coding_noneorlabq (const char *domain,
                              VipsImage *im);

Check that the image is uncoded or LABQ coded. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 on OK, or -1 on error.


vips_check_coding_same ()

int
vips_check_coding_same (const char *domain,
                        VipsImage *im1,
                        VipsImage *im2);

Check that the images have the same coding. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im1

first image to check

 

im2

second image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_mono ()

int
vips_check_mono (const char *domain,
                 VipsImage *im);

Check that the image has exactly one band. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_bands ()

int
vips_check_bands (const char *domain,
                  VipsImage *im,
                  int bands);

Check that the image has bands bands. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

bands

must have this many bands

 

Returns

0 if OK, -1 otherwise.


vips_check_bands_1or3 ()

int
vips_check_bands_1or3 (const char *domain,
                       VipsImage *im);

Check that the image has either one or three bands. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_bands_atleast ()

int
vips_check_bands_atleast (const char *domain,
                          VipsImage *im,
                          int bands);

Check that the image has at least bands bands. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

bands

at least this many bands

 

Returns

0 if OK, -1 otherwise.


vips_check_bands_1orn ()

int
vips_check_bands_1orn (const char *domain,
                       VipsImage *im1,
                       VipsImage *im2);

Check that the images have the same number of bands, or that one of the images has just 1 band. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im1

first image to check

 

im2

second image to check

 

Returns

0 on OK, or -1 on error.


vips_check_bands_1orn_unary ()

int
vips_check_bands_1orn_unary (const char *domain,
                             VipsImage *im,
                             int n);

Check that an image has 1 or n bands. Handy for unary operations, cf. vips_check_bands_1orn(). If not, set an error message and return non-zero.

See also: vips_check_bands_1orn().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

n

number of bands, or 1

 

Returns

0 on OK, or -1 on error.


vips_check_bands_same ()

int
vips_check_bands_same (const char *domain,
                       VipsImage *im1,
                       VipsImage *im2);

Check that the images have the same number of bands. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im1

first image to check

 

im2

second image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_bandno ()

int
vips_check_bandno (const char *domain,
                   VipsImage *im,
                   int bandno);

bandno should be a valid band number (ie. 0 to im->Bands - 1), or can be -1, meaning all bands. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

bandno

band number

 

Returns

0 if OK, -1 otherwise.


vips_check_int ()

int
vips_check_int (const char *domain,
                VipsImage *im);

Check that the image is in one of the integer formats. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_uint ()

int
vips_check_uint (const char *domain,
                 VipsImage *im);

Check that the image is in one of the unsigned integer formats. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_uintorf ()

int
vips_check_uintorf (const char *domain,
                    VipsImage *im);

Check that the image is unsigned int or float. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_noncomplex ()

int
vips_check_noncomplex (const char *domain,
                       VipsImage *im);

Check that the image is not complex. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_complex ()

int
vips_check_complex (const char *domain,
                    VipsImage *im);

Check that the image is complex. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_twocomponents ()

int
vips_check_twocomponents (const char *domain,
                          VipsImage *im);

Check that the image is has two "components", ie. is a one-band complex or a two-band non-complex. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_format ()

int
vips_check_format (const char *domain,
                   VipsImage *im,
                   VipsBandFormat fmt);

Check that the image has the specified format. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

fmt

format to test for

 

Returns

0 if OK, -1 otherwise.


vips_check_u8or16 ()

int
vips_check_u8or16 (const char *domain,
                   VipsImage *im);

Check that the image is 8 or 16-bit unsigned integer. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_8or16 ()

int
vips_check_8or16 (const char *domain,
                  VipsImage *im);

Check that the image is 8 or 16-bit integer, signed or unsigned. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_u8or16orf ()

int
vips_check_u8or16orf (const char *domain,
                      VipsImage *im);

Check that the image is 8 or 16-bit unsigned integer, or float. Otherwise set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_format_same ()

int
vips_check_format_same (const char *domain,
                        VipsImage *im1,
                        VipsImage *im2);

Check that the images have the same format. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im1

first image to check

 

im2

second image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_size_same ()

int
vips_check_size_same (const char *domain,
                      VipsImage *im1,
                      VipsImage *im2);

Check that the images have the same size. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im1

first image to check

 

im2

second image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_oddsquare ()

int
vips_check_oddsquare (const char *domain,
                      VipsImage *im);

Check that the image is square and that the sides are odd. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_vector_length ()

int
vips_check_vector_length (const char *domain,
                          int n,
                          int len);

Check that n == len .

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

n

number of elements in vector

 

len

number of elements vector should have

 

Returns

0 if OK, -1 otherwise.


vips_check_vector ()

int
vips_check_vector (const char *domain,
                   int n,
                   VipsImage *im);

Operations with a vector constant need a 1-element vector, or a vector with the same number of elements as there are bands in the image.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

n

number of elements in vector

 

im

image to check against

 

Returns

0 if OK, -1 otherwise.


vips_check_hist ()

int
vips_check_hist (const char *domain,
                 VipsImage *im);

Histogram images must have width or height 1, and must not have more than 65536 elements. Return 0 if the image will pass as a histogram, or -1 and set an error message otherwise.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_matrix ()

int
vips_check_matrix (const char *domain,
                   VipsImage *im,
                   VipsImage **out);

Matrix images must have width and height less than 100000 and have 1 band.

Return 0 if the image will pass as a matrix, or -1 and set an error message otherwise.

out is set to be im cast to double and stored in memory. Use VIPS_MATRIX() to address values in out .

You must unref out when you are done with it.

See also: VIPS_MATRIX(), vips_object_local()

Parameters

domain

the originating domain for the error message

 

im

image to check

 

out

put image as in-memory doubles here.

[out]

Returns

0 if OK, -1 otherwise.


vips_check_separable ()

int
vips_check_separable (const char *domain,
                      VipsImage *im);

Separable matrix images must have width or height 1. Return 0 if the image will pass, or -1 and set an error message otherwise.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

im

image to check

 

Returns

0 if OK, -1 otherwise.


vips_check_precision_intfloat ()

int
vips_check_precision_intfloat (const char *domain,
                               VipsPrecision precision);

Check that prec image is either float or int. If not, set an error message and return non-zero.

See also: vips_error().

Parameters

domain

the originating domain for the error message

 

precision

precision to check

 

Returns

0 on OK, or -1 on error.

Types and Values