id_foreach(3)id_foreach(3)NAMEid_foreach - enumerate members of an ID set (libc library)
SYNOPSIS
#include <idset.h>
id_cursor_t cursor = SET_CURSOR_INIT;
int id_foreach(
idset_t idset,
unsigned int flags,
id_cursor_t *cursor );
PARAMETERS
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 mem‐
bers; 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 set‐
ting 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 subse‐
quent invocations of the id_foreach() function.
DESCRIPTION
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.
NOTES
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.
RETURN VALUES
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.
ERRORS
No errors are defined for the id_foreach() function.
EXAMPLES
See the EXAMPLES section of idsetops(3) for a sample program that uses
the id_foreach() function.
SEE ALSO
Functions: idsetops(3)id_foreach(3)