## memory

memory — memory utilities

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    #define             VIPS_FREEF                          (F,
                                                             S)
    #define             VIPS_FREE                           (S)
    #define             VIPS_SETSTR                         (S,
                                                             V)
    #define             VIPS_NEW                            (IM,
                                                             T)
    #define             VIPS_ARRAY                          (IM,
                                                             N,
                                                             T)
    void *              vips_malloc                         (VipsImage *image,
                                                             size_t size);
    int                 vips_free                           (void *s);
    char *              vips_strdup                         (VipsImage *image,
                                                             const char *str);

## Description

Simple memory allocation utilities. These functions and macros help allocate and free memory. Most of VIPS uses them, though some parts use the `g_malloc()` system instead, confusingly.

If you compile with `DEBUGM` it will track allocations for you, though valgrind or dmalloc are better solutions.

## Details

### VIPS_FREEF()

    #define             VIPS_FREEF( F, S )

### VIPS_FREE()

    #define             VIPS_FREE( S )

### VIPS_SETSTR()

    #define             VIPS_SETSTR( S, V )

### VIPS_NEW()

    #define VIPS_NEW( IM, T ) ((T *) vips_malloc( (IM), sizeof( T )))

`IM` : | allocate memory local to `IM`, or `NULL` for no auto-free
`T` : | type of thing to allocate
Returns : | A pointer of type `T` *, or `NULL` on error.

### VIPS_ARRAY()

    #define VIPS_ARRAY( IM, N, T ) ((T *) vips_malloc( (IM), (N) * sizeof( T )))

`IM` : | allocate memory local to `IM`, or `NULL` for no auto-free
`N` : | number of `T` 's to allocate
`T` : | type of thing to allocate
Returns : | A pointer of type `T` *, or `NULL` on error.

### vips_malloc ()

    void *              vips_malloc                         (VipsImage *image,
                                                             size_t size);

Malloc local to `im`, that is, the memory will be automatically freed for you when the image is closed. If `im` is `NULL`, you need to free the memory explicitly with `vips_free()`. If allocation fails `vips_malloc()` returns `NULL` and sets an error message.

If two threads try to allocate local to the same `im` at the same time, you can get heap corruption.

`image` : | allocate memory local to this VipsImage, or `NULL`
`size` : | number of bytes to allocate
Returns : | a pointer to the allocated memory, or `NULL` on error.

### vips_free ()

    int                 vips_free                           (void *s);

VIPS free function. VIPS tries to use this instead of `free()`. It always returns zero, so it can be used as a callback handler.

Only use it to free memory that was previously allocated with `vips_malloc()` with a `NULL` first argument.

`s` : | memory to free

### vips_strdup ()

    char *              vips_strdup                         (VipsImage *image,
                                                             const char *str);