8322 nl: misleading-indentation
[unleashed/tickless.git] / usr / src / man / man3picl / picl_find_node.3picl
blob10e6fdb0416238d0e2788d7c3da21efe62b2a06a
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH PICL_FIND_NODE 3PICL "Feb 5, 2004"
7 .SH NAME
8 picl_find_node \- find node with given property and value
9 .SH SYNOPSIS
10 .LP
11 .nf
12 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-l\fR [ \fIlibrary\fR\&.\|.\|. ]
13 #include <picl.h>
15 \fBint\fR \fBpicl_find_node\fR(\fBpicl_nodehdl_t\fR\fIrooth\fR, \fBchar *\fR\fIpname\fR,
16      \fBpicl_prop_type_t\fR \fIptype\fR, \fBvoid *\fR\fIpval\fR, \fBsize_t\fR \fIvalsize\fR,
17      \fBpicl_nodehdl_t *\fR\fIretnodeh\fR);
18 .fi
20 .SH DESCRIPTION
21 .sp
22 .LP
23 The \fBpicl_find_node()\fR function visits the nodes in the subtree under the
24 node specified by \fIrooth\fR. The handle of the node that has the property
25 whose name, type, and value matches the name, type, and value specified in
26 \fIpname\fR, \fIptype\fR, and \fIpval\fR respectively, is returned in the
27 location given by \fIretnodeh\fR. The \fIvalsize\fR argument specifies the size
28 of the value in \fIpval\fR. The first \fIvalsize\fR number of bytes of the
29 property value is compared with \fIpval\fR.
30 .SH RETURN VALUES
31 .sp
32 .LP
33 Upon successful completion, 0 is returned. Otherwise a non-negative integer is
34 returned to indicate an error.
35 .sp
36 .LP
37 The value \fBPICL_NODENOTFOUND\fR is returned if no node that matches the
38 property criteria can be found.
39 .SH ERRORS
40 .sp
41 .ne 2
42 .na
43 \fB\fBPICL_FAILURE\fR\fR
44 .ad
45 .RS 22n
46 General system failure
47 .RE
49 .sp
50 .ne 2
51 .na
52 \fB\fBPICL_INVALIDHANDLE\fR\fR
53 .ad
54 .RS 22n
55 Invalid handle
56 .RE
58 .sp
59 .ne 2
60 .na
61 \fB\fBPICL_NODENOTFOUND\fR\fR
62 .ad
63 .RS 22n
64 Node not found
65 .RE
67 .sp
68 .ne 2
69 .na
70 \fB\fBPICL_NOTNODE\fR\fR
71 .ad
72 .RS 22n
73 Not a node
74 .RE
76 .sp
77 .ne 2
78 .na
79 \fB\fBPICL_STALEHANDLE\fR\fR
80 .ad
81 .RS 22n
82 Stale handle
83 .RE
85 .SH ATTRIBUTES
86 .sp
87 .LP
88 See \fBattributes\fR(5) for descriptions of the following attributes:
89 .sp
91 .sp
92 .TS
93 box;
94 c | c
95 l | l .
96 ATTRIBUTE TYPE  ATTRIBUTE VALUE
98 Interface Stability     Evolving
100 MT-Level        MT-Safe
103 .SH SEE ALSO
106 \fBpicl_get_propinfo\fR(3PICL), \fBpicl_get_propval\fR(3PICL),
107 \fBpicl_get_propval_by_name\fR(3PICL), \fBpicl_get_prop_by_name\fR(3PICL),
108 \fBattributes\fR(5)