.TH IM_SYSTEM 3 "7 Mar 2000"
.SH NAME
im_system \- run a command on an image
.SH SYNOPSIS
#include <vips/vips.h>

int
im_system(im, cmd, out)
.br
IMAGE *im;
.br
const char *cmd;
.br
char **out;

.SH DESCRIPTION
.B im_system()
runs a command on an image, returning the command's output as a string. This
string should be freed with 
.B im_free()
when you've finished with it.

The command is executed with the 
.B system(3)
call; the first '%s' in the command being substituted for a filename.

For example:

im_system( im, "vips2dj %s | lpr", &result )

will run the command vips2dj(1) on the image, piping the result to the
printer.

If the IMAGE is a file on disc, then the filename will be the name of the real
file. If the image is in memory, or the result of a computation, then a new
file is created in the temporary area called something like "vips_XXXXXX", and
that filename given to the command. The file is deleted when the command
finishes.

The environment variable TMPDIR can be used to set the temporary directory. If
it is not set, it defaults to "/tmp".

.SH RETURN VALUE
The function returns 0 on success and -1 on error.
.SH SEE ALSO
system(3), vips2dj(1)
.SH COPYRIGHT
2000 The National Gallery and Birkbeck College