error: libvips Reference Manual

## error error |

## Functions

const char * | vips_error_buffer ()
char * | vips_error_buffer_copy ()
void | vips_error_clear ()
void | vips_error_freeze ()
void | vips_error_thaw ()
void | vips_error ()
void | vips_verror ()
void | vips_error_system ()
void | vips_verror_system ()
void | vips_error_g ()
void | vips_g_error ()
void | vips_error_exit ()
int | vips_check_uncoded ()
int | vips_check_coding ()
int | vips_check_coding_known ()
int | vips_check_coding_noneorlabq ()
int | vips_check_coding_same ()
int | vips_check_mono ()
int | vips_check_bands ()
int | vips_check_bands_1or3 ()
int | vips_check_bands_atleast ()
int | vips_check_bands_1orn ()
int | vips_check_bands_1orn_unary ()
int | vips_check_bands_same ()
int | vips_check_bandno ()
int | vips_check_int ()
int | vips_check_uint ()
int | vips_check_uintorf ()
int | vips_check_noncomplex ()
int | vips_check_complex ()
int | vips_check_twocomponents ()
int | vips_check_format ()
int | vips_check_u8or16 ()
int | vips_check_8or16 ()
int | vips_check_u8or16orf ()
int | vips_check_format_same ()
int | vips_check_size_same ()
int | vips_check_oddsquare ()
int | vips_check_vector_length ()
int | vips_check_vector ()
int | vips_check_hist ()
int | vips_check_matrix ()
int | vips_check_separable ()
int | vips_check_precision_intfloat ()

## Includes

    #include <vips/vips.h>

## Description

## 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_buffer_copy ()

    char *
    vips_error_buffer_copy (void);

Return a copy of the vips error buffer, and clear it.

#### Returns

a copy of the libvips error buffer

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

Re-enable 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, or a 1-band image and a many-element vector.

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.