Index for Section 3

Alphabetical listing for I

Bottom of page

id_foreach(3)
NAME
  id_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
  idset
      Specifies a ID set whose members are to be enumerated.

  flags
      Control the processing of set members. The flags parameter can be one
      or more (a logical OR operation) of the following flags:

      SET_CURSOR_FIRST
	  Initializes the cursor to the first member of the set before
	  scanning.

      SET_CURSOR_WRAP
	  Wraps around to the beginning of the set when scanning for members.

      SET_CURSOR_CONSUME
	  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().

  cursor
      Points to an opaque type that records the position in a set for
      subsequent 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)

Index for Section 3

Alphabetical listing for I

Top of page