.\" @(#)PEXGetAncestors.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXGetAncestors 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXGetAncestors - Get Ancestors
.SH SYNTAX
.HP
PEXStructurePath *PEXGetAncestors\^(\^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 RETURNS
An array of structure paths defining the ancestors of the specified
.I structure;
a null pointer if unsuccessful.
.SH DESCRIPTION
.\" indexing
.IX PEXGetAncestors
.LP
This function returns a list of structure network paths which reference the
specified
.I structure.
Paths are returned as lists of element references, each of which is represented
as a 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 list of 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.  A path depth of 2 returns two
elements, and so on.
.LP
Specifying a path depth of 0 and a path part of
.B PEXTopPart
returns the unique top parts of all paths to structure.
Specifying a path depth of 1 and a path part of
.B PEXTopPart
returns the root structure of all
structure networks which contain
.I structure.
A path depth of 2 and path part of
.B PEXBottomPart
returns all of
the structure's immediate ancestors.  Determine the number
of references to
.I structure
by setting the path depth to 1 and the path part to
.B PEXBottomPart.
.LP
PEXlib allocates memory for the returned ancestor 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
.I 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 PEXGetDescendants (3)
.fi