---
name: "im_iterate"
section: "3"
platform: "linux"
package: "libvips-dev"
version: "7.20.7-1+b3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/im_iterate"
---

# im\_iterate(3)

PIO input from image

## NAME

im\_iterate - PIO input from image

## SYNOPSIS

**#include \<vips/vips.h\>**

int im\_iterate( im, start\_fn, scan\_fn, stop\_fn, a, b )\
 IMAGE \*im;\
 void \*(\*start\_fn)();\
 int (\*scan\_fn)();\
 int (\*stop\_fn)();\
 void \*a, \*b;

where, typically,

void \*start\_fn( im, a, b )\
 IMAGE \*im;\
 void \*a, \*b;

int scan\_fn( or, seq, a, b )\
 REGION \*or;\
 void \*seq;\
 void \*a, \*b;

int stop\_fn( seq, a, b )\
 void \*seq;\
 void \*a, \*b;

## DESCRIPTION

[im\_iterate(3)](/im_iterate/3.md) is used for PIO image input. See \`VIPS Library Programmers' guide,' in the accompanying documentation, for an introduction to this function.

[im\_iterate(3)](/im_iterate/3.md) makes one or more regions on im, and starts one or more sequences running over the image. [im\_iterate(3)](/im_iterate/3.md) guarantees that

   \- scan\_fn() will see each of the pels in im exactly once\
    \- start\_fn() and stop\_fn() are both exclusive

See the guide, the man page for [im\_generate(3)](/im_generate/3.md), and the source to [im\_deviate(3)](/im_deviate/3.md) for examples.

On machines with SVR4 threads and several CPUs, [im\_generate(3)](/im_generate/3.md) and [im\_iterate(3)](/im_iterate/3.md) automatically parallelise programs. You can set the desired concurrency level with the environment variable IM\_CONCURRENCY, for example

    example% setenv IM\_CONCURRENCY 2\
     example% stats fred.v

will run stats with enough concurrency to keep 2 CPUs fully occupied. If IM\_CONCURRENCY is not set, then it defaults to 1.

## RETURN VALUE

All functions return 0 on success and non-zero on error.

## SEE ALSO

[im\_generate(3)](/im_generate/3.md).

## COPYRIGHT

National Gallery, 1993

## AUTHOR

J. Cupitt - 23/7/93