vips: libvips Reference Manual

## vips vips — startup, shutdown, version |

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | VIPS_INIT()
int | vips_init ()
const char * | vips_get_argv0 ()
const char * | vips_get_prgname ()
void | vips_shutdown ()
void | vips_thread_shutdown ()
void | vips_add_option_entries ()
void | vips_leak_set ()
void | vips_block_untrusted_set ()
const char * | vips_version_string ()
int | vips_version ()
const char * | vips_guess_prefix ()
const char * | vips_guess_libdir ()

## Includes

    #include <vips/vips.h>

## Description

Start VIPS up, shut VIPS down, get version information, relocation.

VIPS is a relocatable package, meaning you can move the directory tree you compiled it to at runtime and it will still be able to find all data files. This is required for OS X and Windows, but slightly unusual in the Unix world. See `vips_init()` and `vips_guess_prefix()`.

## Functions

### VIPS_INIT()

    #define             VIPS_INIT(ARGV0)

VIPS_INIT() starts up the world of VIPS. You should call this on program startup before using any other VIPS operations. If you do not call `VIPS_INIT()`, VIPS will call it for you when you use your first VIPS operation, but it may not be able to get hold of `ARGV0` and VIPS may therefore be unable to find its data files. It is much better to call this macro yourself.

`ARGV0` is used to help discover message catalogues if libvips has been relocated. If you don't need a relocatable package, you can just pass `""` and it'll be fine.

Additionally, `VIPS_INIT()` can be run from any thread, but it must not be called from more than one thread at the same time. This is much easier to guarantee if you call it yourself.

VIPS_INIT() is a macro, since it tries to check ABI compatibility between the caller and the library. You can also call `vips_init()`, the non-macro version, if macros are not available to you.

You may call `VIPS_INIT()` many times and `vips_shutdown()` many times, but you must not call `VIPS_INIT()` after `vips_shutdown()`. In other words, you cannot stop and restart vips.

Use the environment variable `VIPS_MIN_STACK_SIZE` to set the minimum stack size. For example, `2m` for a minimum of two megabytes of stack. This can be important for systems like musl where the default stack is very small.

VIPS_INIT() does approximately the following:

- checks that the libvips your program is expecting is binary-compatible with the vips library you're running against

- sets a minimum stack size, see above

- initialises any libraries that VIPS is using, including GObject and the threading system, if necessary

- guesses where the VIPS data files are and sets up internationalisation --- see `vips_guess_prefix()`

- creates the main vips types, including VipsImage and friends

- loads any plugins from $libdir/vips-x.y/, where x and y are the major and minor version numbers for this VIPS.

Example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    int main(int argc, char **argv)
    {
        if (VIPS_INIT(argv[0]))
            vips_error_exit("unable to start VIPS");

        vips_shutdown();

        return 0;
    }

See also: `vips_shutdown()`, `vips_add_option_entries()`, `vips_version()`, `vips_guess_prefix()`, `vips_guess_libdir()`.

#### Parameters

ARGV0 | name of application |

#### Returns

0 on success, -1 otherwise

### vips_init ()

    int
    vips_init (const char *argv0);

This function starts up libvips, see `VIPS_INIT()`.

This function is for bindings which need to start up vips. C programs should use the `VIPS_INIT()` macro, which does some extra checks.

See also: `VIPS_INIT()`.

#### Parameters

argv0 | name of application |

#### Returns

0 on success, -1 otherwise

### vips_get_argv0 ()

    const char *
    vips_get_argv0 (void);

See also: `VIPS_INIT()`.

#### Returns

a pointer to an internal copy of the argv0 string passed to `VIPS_INIT()`. Do not free this value.

[transfer none]

### vips_get_prgname ()

    const char *
    vips_get_prgname (void);

Return the program name. This can be useful for the user tio see,.

See also: `VIPS_INIT()`.

#### Returns

a pointer to an internal copy of the program name. Do not free this value.

[transfer none]

### vips_shutdown ()

    void
    vips_shutdown (void);

Call this to drop caches, close plugins, terminate background threads, and finalize any internal library testing.

vips_shutdown() is optional. If you don't call it, your platform will clean up for you. The only negative consequences are that the leak checker and the profiler will not work.

You may call `VIPS_INIT()` many times and `vips_shutdown()` many times, but you must not call `VIPS_INIT()` after `vips_shutdown()`. In other words, you cannot stop and restart libvips.

See also: `vips_profile_set()`, `vips_leak_set()`.

### vips_thread_shutdown ()

    void
    vips_thread_shutdown (void);

Free any thread-private data and flush any profiling information.

This function needs to be called when a thread that has been using vips exits. It is called for you by `vips_shutdown()` and for any threads created within the VipsThreadPool.

You will need to call it from threads created in other ways or there will be memory leaks. If you do not call it, vips will generate a warning message.

It may be called many times, and you can continue using vips after calling it. Calling it too often will reduce performance.

### vips_add_option_entries ()

    void
    vips_add_option_entries (GOptionGroup *option_group);

Add the standard vips `GOptionEntry` to a `GOptionGroup`.

See also: `g_option_group_new()`.

#### Parameters

option_group | group to add to |

### vips_leak_set ()

    void
    vips_leak_set (gboolean leak);

Turn on or off vips leak checking. See also --vips-leak, `vips_add_option_entries()` and the `VIPS_LEAK` environment variable.

You should call this very early in your program.

#### Parameters

leak | turn leak checking on or off |

### vips_block_untrusted_set ()

    void
    vips_block_untrusted_set (gboolean state);

Set the block state on all untrusted operations.

    1
    vips_block_untrusted_set(TRUE);

Will block all untrusted operations from running.

Use `vips -l` at the command-line to see the class hierarchy and which operations are marked as untrusted.

Set the environment variable `VIPS_BLOCK_UNTRUSTED` to block all untrusted operations on `vips_init()`.

#### Parameters

state | the block state to set |

### vips_version_string ()

    const char *
    vips_version_string (void);

Get the VIPS version as a static string, including a build date and time. Do not free.

#### Returns

a static version string.

[transfer none]

### vips_version ()

    int
    vips_version (int flag);

Get the major, minor or micro library version, with `flag` values 0, 1 and 2.

Get the ABI current, revision and age (as used by Meson) with `flag` values 3, 4, 5.

#### Parameters

flag | which field of the version to get |

#### Returns

library version number

### vips_guess_prefix ()

    const char *
    vips_guess_prefix (const char *argv0,
                       const char *env_name);

vips_guess_prefix() tries to guess the install directory. You should pass in the value of argv[0] (the name your program was run as) as a clue to help it out, plus the name of the environment variable you let the user override your package install area with (eg. "VIPSHOME").

On success, `vips_guess_prefix()` returns the prefix it discovered, and as a side effect, sets the environment variable (if it's not set).

Don't free the return string!

See also: `vips_guess_libdir()`.

#### Parameters

argv0 | program name (typically argv[0]) |
env_name | save prefix in this environment variable |

#### Returns

the install prefix as a static string, do not free.

[transfer none]

### vips_guess_libdir ()

    const char *
    vips_guess_libdir (const char *argv0,
                       const char *env_name);

vips_guess_libdir() tries to guess the install directory (usually the configure libdir, or $prefix/lib). You should pass in the value of argv[0] (the name your program was run as) as a clue to help it out, plus the name of the environment variable you let the user override your package install area with (eg. "VIPSHOME").

On success, `vips_guess_libdir()` returns the libdir it discovered, and as a side effect, sets the prefix environment variable (if it's not set).

Don't free the return string!

See also: `vips_guess_prefix()`.

#### Parameters

argv0 | program name (typically argv[0]) |
env_name | save prefix in this environment variable |

#### Returns

the libdir as a static string, do not free.

[transfer none]

## See Also

<link linkend="VipsOperation">VipsOperation</link>