.\" @(#)PEXGetDescendants.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXGetDescendants 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXGetDescendants - Get Descendants
.SH SYNTAX
.HP
PEXStructurePath *PEXGetDescendants\^(\^Display *\fIdisplay\fP\^, PEXStructure \fIstructure\fP\^, int \fIpath_part\fP\^, unsigned long \fIpath_depth\fP\^, unsigned long *\fIcount_return\fP\^)
.SH PARAMETERS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.IP \fIstructure\fP 1i
The resource identifier of the structure.
.IP \fIpath_part\fP 1i
The part of the path to return (
.B PEXTopPart
or
.B PEXBottomPart
).
.IP \fIpath_depth\fP 1i
The maximum number of structure network path levels
to be returned in each path found.
.IP \fIcount_return\fP 1i
Returns the number of paths found.
.SH DESCRIPTION
.\" indexing
.IX PEXGetDescendants
.LP
This function returns a list of structure network paths referenced by the
specified
.I structure.
The elements of the returned array are of type
.B PEXStructurePath.
Paths are returned as lists of element references, each of which is represented
as a
.I structure
resource identifier and an offset that gives the element's
position in the
.I structure.
Only unique paths are returned; in other words,
there will be no duplicates in the returned paths.
.LP
The path part must be either
.B PEXTopPart ,
which requests that the top of
the structure paths be returned, or
.B PEXBottomPart ,
which
requests that the bottom of the structure paths be returned.
.LP
The path depth specifies the maximum number of element references
to be returned in each path.  If the path depth is 0, the entire
path is returned.  If the path depth is 1, only one element
reference is returned for each path, and so on.
.LP
For instance, specifying a path depth of 0 and a path part of
.B PEXTopPart
returns all paths from
structure to leaf nodes in the
.I structure
network tree in the order they would be traversed.
Specifying a path depth of 1 and a path part of
.B PEXBottomPart
determines the bottom-most structures of the structure network
rooted at
.I structure.
.LP
PEXlib allocates memory for the returned descendant information.
.BR PEXFreeStructurePaths (3)
should be called to deallocate the memory.
.SH DATA STRUCTURES
.LP
.nf
typedef  XID	PEXStructure;
.sp
typedef struct {
	unsigned long		count;		/* number of elements */
	PEXElementRef		*elements;
.br
} PEXStructurePath;
.sp
typedef struct {
	PEXStructure		structure;
	unsigned long		offset;
.br
} PEXElementRef;
.fi
.SH ERRORS
.TP
.SB BadPEXStructure
The specified structure resource identifier is invalid.
.TP
.SB BadValue
The specified value for path part is invalid.
.SH SEE ALSO
.LP
.nf
.BR PEXCreateStructure (3)
.BR PEXGetStructuresInNetwork (3)
.BR PEXGetAncestors (3)
.fi