'\" te
.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved.
.TH picl_walk_tree_by_class 3PICL "1 Aug 2000" "SunOS 5.11" "PICL Library Functions"
.SH NAME
picl_walk_tree_by_class \- walk subtree by class
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lpicl\fR [ \fIlibrary\fR... ] 
#include <picl.h>

\fBint\fR \fBpicl_walk_tree_by_class\fR(\fBpicl_nodehdl_t\fR \fIrooth\fR,
     \fBconst char *\fR\fIclassname\fR, \fBvoid *\fR\fIc_args\fR,
     \fBint (*\fR\fIcallback\fR)(picl_nodehdl_t \fInodeh\fR, \fBvoid *\fR\fIc_args\fR));
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpicl_walk_tree_by_class()\fR function visits all the nodes of the subtree under the node specified by \fIrooth\fR. The PICL class name of the visited node is compared with the class name specified by \fIclassname\fR. If the class names match, then the callback function specified by \fIcallback\fR is called with the matching node handle and the argument provided in \fIc_args\fR. If the class name specified in \fIclassname\fR is \fINULL\fR, then the callback function is invoked for all the nodes.
.sp
.LP
The return value from the callback function is used to determine whether to continue or terminate the tree walk. The callback function returns \fBPICL_WALK_CONTINUE\fR or \fBPICL_WALK_TERMINATE\fR to continue or terminate the tree walk.
.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_STALEHANDLE\fR is returned if the handle is no longer valid. This occurs if the PICL tree was refreshed or reinitialized.
.sp
.LP
\fBPICL_INVALIDHANDLE\fR is returned if the specified handle never existed.  This error may be returned for a previously valid handle if the daemon was brought down and restarted. When this occurs a client must revalidate any saved handles.
.SH ERRORS
.sp
.ne 2
.mk
.na
\fB\fBPICL_NOTINITIALIZED\fR\fR
.ad
.RS 23n
.rt  
Session not initialized
.RE

.sp
.ne 2
.mk
.na
\fB\fBPICL_NORESPONSE\fR\fR
.ad
.RS 23n
.rt  
Daemon not responding
.RE

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

.sp
.ne 2
.mk
.na
\fB\fBPICL_INVALIDHANDLE\fR\fR
.ad
.RS 23n
.rt  
Invalid handle specified
.RE

.sp
.ne 2
.mk
.na
\fB\fBPICL_STALEHANDLE\fR\fR
.ad
.RS 23n
.rt  
Stale handle specified
.RE

.sp
.ne 2
.mk
.na
\fB\fBPICL_FAILURE\fR\fR
.ad
.RS 23n
.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
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBpicl_get_propval_by_name\fR(3PICL), \fBattributes\fR(5)