## error

error — error messages and error handling

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    const char *        vips_error_buffer                   (void);
    void                vips_error_clear                    (void);
    void                vips_error                          (const char *domain,
                                                             const char *fmt,
                                                             ...);
    void                vips_verror                         (const char *domain,
                                                             const char *fmt,
                                                             va_list ap);
    void                vips_error_system                   (int err,
                                                             const char *domain,
                                                             const char *fmt,
                                                             ...);
    void                vips_verror_system                  (int err,
                                                             const char *domain,
                                                             const char *fmt,
                                                             va_list ap);
    void                vips_error_g                        (GError **error);
    void                vips_warn                           (const char *domain,
                                                             const char *fmt,
                                                             ...);
    void                vips_vwarn                          (const char *domain,
                                                             const char *fmt,
                                                             va_list ap);
    void                vips_diag                           (const char *domain,
                                                             const char *fmt,
                                                             ...);
    void                vips_vdiag                          (const char *domain,
                                                             const char *fmt,
                                                             va_list ap);
    void                vips_error_exit                     (const char *fmt,
                                                             ...);
    int                 vips_check_uncoded                  (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_coding_known             (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_coding_labq              (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_coding_rad               (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_coding_noneorlabq        (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_coding_same              (const char *domain,
                                                             VipsImage *im1,
                                                             VipsImage *im2);
    int                 vips_check_mono                     (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_bands_1or3               (const char *domain,
                                                             VipsImage *in);
    int                 vips_check_bands                    (const char *domain,
                                                             VipsImage *im,
                                                             int bands);
    int                 vips_check_bands_1orn               (const char *domain,
                                                             VipsImage *im1,
                                                             VipsImage *im2);
    int                 vips_check_bands_1orn_unary         (const char *domain,
                                                             VipsImage *im,
                                                             int n);
    int                 vips_check_bands_same               (const char *domain,
                                                             VipsImage *im1,
                                                             VipsImage *im2);
    int                 vips_check_bandno                   (const char *domain,
                                                             VipsImage *im,
                                                             int bandno);
    int                 vips_check_int                      (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_uint                     (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_uintorf                  (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_noncomplex               (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_complex                  (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_format                   (const char *domain,
                                                             VipsImage *im,
                                                             VipsBandFormat fmt);
    int                 vips_check_u8or16                   (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_8or16                    (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_u8or16orf                (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_format_same              (const char *domain,
                                                             VipsImage *im1,
                                                             VipsImage *im2);
    int                 vips_check_size_same                (const char *domain,
                                                             VipsImage *im1,
                                                             VipsImage *im2);
    int                 vips_check_vector                   (const char *domain,
                                                             int n,
                                                             VipsImage *im);
    int                 vips_check_hist                     (const char *domain,
                                                             VipsImage *im);
    int                 vips_check_imask                    (const char *domain,
                                                             INTMASK *mask);
    int                 vips_check_dmask                    (const char *domain,
                                                             DOUBLEMASK *mask);
    int                 vips_check_dmask_1d                 (const char *domain,
                                                             DOUBLEMASK *mask);

## 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 = vips_image_new_from_file( filename )) )
      // 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.

## Details

### 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 presentng an error to the user.

See also: `vips_error_buffer()`.

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

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

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

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

`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 also: `g_set_error()`.

`error` : | glib error pointer

### vips_warn ()

    void                vips_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: `vips_diag()`, `vips_vwarn()`.

`domain` : | the source of the warning message
`fmt` : | printf()-style format string for the message
`...` : | arguments to the format string

### vips_vwarn ()

    void                vips_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: `vips_diag()`, `vips_warn()`.

`domain` : | the source of the warning message
`fmt` : | printf()-style format string for the message
`ap` : | arguments to the format string

### vips_diag ()

    void                vips_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: `vips_vdiag()`, `vips_warn()`.

`domain` : | the source of the diagnostic message
`fmt` : | printf()-style format string for the message
`...` : | arguments to the format string

### vips_vdiag ()

    void                vips_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: `vips_diag()`, `vips_warn()`.

`domain` : | the source of the diagnostic message
`fmt` : | printf()-style format string for the message
`ap` : | arguments to the format string

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

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

`domain` : | the originating domain for the error message
`im` : | image to check
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()`.

`domain` : | the originating domain for the error message
`im` : | image to check
Returns : | 0 on OK, or -1 on error.

### vips_check_coding_labq ()

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

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

See also: `vips_error()`.

`domain` : | the originating domain for the error message
`im` : | image to check
Returns : | 0 on OK, or -1 on error.

### vips_check_coding_rad ()

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

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

See also: `vips_error()`.

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

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

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

`domain` : | the originating domain for the error message
`im` : | image to check
Returns : | 0 if OK, -1 otherwise.

### vips_check_bands_1or3 ()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`domain` : | the originating domain for the error message
`im` : | image to check
Returns : | 0 if OK, -1 otherwise.

### vips_check_imask ()

    int                 vips_check_imask                    (const char *domain,
                                                             INTMASK *mask);

Sanity-check a mask parameter.

See also: `vips_error()`.

`domain` : | the originating domain for the error message
`mask` : | mask to check
Returns : | 0 if OK, -1 otherwise.

### vips_check_dmask ()

    int                 vips_check_dmask                    (const char *domain,
                                                             DOUBLEMASK *mask);

Sanity-check a mask parameter.

See also: `vips_error()`.

`domain` : | the originating domain for the error message
`mask` : | mask to check
Returns : | 0 if OK, -1 otherwise.

### vips_check_dmask_1d ()

    int                 vips_check_dmask_1d                 (const char *domain,
                                                             DOUBLEMASK *mask);

A mask must be one-dimensional (width or height 1).

See also: `vips_error()`.

`domain` : | the originating domain for the error message
`mask` : | mask to check
Returns : | 0 if OK, -1 otherwise.