'\" te
.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved.
.TH ptree_get_node_by_path 3PICLTREE "1 Aug 2000" "SunOS 5.11" "PICL Plug-In Library Functions"
.SH NAME
ptree_get_node_by_path \- get handle of node specified by PICL tree path
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lpicltree\fR [ \fIlibrary\fR... ]
#include <picltree.h>

\fBint\fR \fBptree_get_node_by_path\fR(\fBconst char *\fR\fIptreepath\fR,
     \fBpicl_nodehdl_t *\fR\fInodeh\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBptree_get_node_by_path()\fR function copies the handle of the node in the PICL tree specified by the path given in \fIptreepath\fR into the location \fInodeh\fR.
.sp
.LP
The syntax of a PICL tree path is:
.sp
.in +2
.nf
[\fIdef_propname\fR:]/[\fIdef_propval\fR[\fImatch_cond\fR] \&.\|.\|. ]
.fi
.in -2

.sp
.LP
where \fIdef_propname\fR prefix is a shorthand notation to specify the name of the property whose value is specified in \fIdef_propval\fR, and the \fImatch_cond\fR expression specifies the matching criteria for that node in the form of one or more pairs of property names and values such as
.sp
.in +2
.nf
[@\fIaddress\fR][?\fIprop_name\fR[=\fIprop_val\fR] \&.\|.\|. ]
.fi
.in -2

.sp
.LP
where '@' is a shorthand notation to refer to the device address, which is followed by the device addres value address. The address value is matched with the value of the property "bus-addr" if it exists. If no "bus-addr" property exists, then it is matched with the value of the property "UnitAddress". Use the '?' notation to limit explicitly the comparison to "bus-addr" or "UnitAddress" property.  The expression following '?' specifies matching property name and value pairs, where \fIprop_name\fR gives the property name and \fIprop_val\fR gives the property value for non \fBPICL_PTYPE_VOID \fRproperties. The values for properties of type \fBPICL_PTYPE_TABLE\fR, \fBPICL_PTYPE_BYTEARRAY\fR, and \fBPICL_PTYPE_REFERENCE\fR cannot be specified in the \fImatch_cond\fR expression.
.sp
.LP
A "_class" property value of "picl" may be used to match nodes of all PICL classes.
.sp
.LP
All valid paths must start at the root node denoted by '/'.
.sp
.LP
If no prefix is specified for the path, then the prefix defaults to the "name" property.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fB0\fR is returned. On failure, a non-negative integer is returned to indicate an error.
.sp
.LP
\fBPICL_NOTNODE\fR is returned if there is no node corresponding to the specified path.
.SH ERRORS
.sp
.ne 2
.mk
.na
\fB\fBPICL_INVALIDARG\fR\fR
.ad
.RS 19n
.rt  
Invalid argument
.RE

.sp
.ne 2
.mk
.na
\fB\fBPICL_NOTNODE\fR\fR
.ad
.RS 19n
.rt  
Not a node
.RE

.sp
.ne 2
.mk
.na
\fB\fBPICL_FAILURE\fR\fR
.ad
.RS 19n
.rt  
General system failure
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBptree_get_propval_by_name\fR(3PICLTREE), \fBattributes\fR(5)