id_foreach - enumerate members of an ID set (libc library)
#include <idset.h>
id_cursor_t cursor = SET_CURSOR_INIT;
int id_foreach(
idset_t idset,
unsigned int flags,
id_cursor_t *cursor );
Specifies a ID set whose members are to be enumerated.
Control the processing of set members. The flags parameter
can be one or more (a logical OR operation) of the following
flags: Initializes the cursor to the first member of
the set before scanning. Wraps around to the beginning of
the set when scanning for members. Consumes the set members;
that is, removes the member from the set when found.
As shown in the SYNOPSIS, a cursor variable may be initialized
to the value SET_CURSOR_INIT. Initialization of
this variable is equivalent to setting the SET_CURSOR_FIRST
flag on the initial call to id_foreach().
Points to an opaque type that records the position in a
set for subsequent invocations of the id_foreach() function.
The id_foreach() function scans the specified idset,
starting at the position saved in the cursor parameter,
for members of the set and returns the first member found.
If the SET_CURSOR_FIRST flag is set, the cursor is initialized
to the beginning of the set before starting the
scan. If no members are found, the id_foreach() function
will return ID_NONE.
If the SET_CURSOR_WRAP flag is set, the scan will wrap
from the end of the set to the beginning searching for a
member to return. Otherwise, a one pass scan is performed,
and when the end of the set is reached, the cursor
is positioned at the end of the set. From then on, the
id_foreach() function will continue to return ID_NONE
until the cursor is reinitialized (by specifying the
SET_CURSOR_FIRST orSET_CURSOR_WRAP flag).
If the SET_CURSOR_CONSUME flag is set, the member
returned, if any, will be removed from the set.
Although the preceding description discusses the "beginning"
and "end" of the set, and wrapping from the end to
the beginning, ID sets are conceptually unordered. Thus,
these end points are arbitrary points in the set that
exist to ensure that each member is returned only once per
pass through the set. Therefore, applications should not
depend on a specific numeric order of the returned member
IDs.
The id_foreach() function returns the next member in the
set starting at the position of the cursor. If no more
members are found, ID_NONE is returned. This function
always completes successfully.
No errors are defined for the id_foreach() function.
See the EXAMPLES section of idsetops(3) for a sample program
that uses the id_foreach() function.
Functions: idsetops(3)
id_foreach(3)
[ Back ] | 