share/man/man3devinfo/di_walk_node.3devinfo

   1 '\" te
   2 .\" Copyright (c) 2009, 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 DI_WALK_NODE 3DEVINFO "Jan 16, 2009"
   7 .SH NAME
   8 di_walk_node \- traverse libdevinfo device nodes
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ]
  13 #include <libdevinfo.h>
  14
  15 \fBint\fR \fBdi_walk_node\fR(\fBdi_node_t\fR \fIroot\fR, \fBuint_t\fR \fIflag\fR, \fBvoid *\fR\fIarg\fR,
  16      \fBint\fR \fI(*node_callback)\fR(\fBdi_node_t\fR \fInode\fR, \fBvoid *\fR\fIarg\fR));
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBdi_walk_node()\fR function visits all nodes in the subtree rooted at
  23 \fIroot\fR. For each node found, the caller-supplied function
  24 \fInode_callback\fR() is invoked. The return value of \fInode_callback\fR()
  25 specifies subsequent walking behavior.
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIarg\fR\fR
  31 .ad
  32 .RS 8n
  33 Pointer to caller-specific data.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIflag\fR\fR
  40 .ad
  41 .RS 8n
  42 Specifies walking order, either \fBDI_WALK_CLDFIRST\fR (depth first) or
  43 \fBDI_WALK_SIBFIRST\fR (breadth first). \fBDI_WALK_CLDFIRST\fR is the default.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fInode\fR\fR
  50 .ad
  51 .RS 8n
  52 The node being visited.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fIroot\fR\fR
  59 .ad
  60 .RS 8n
  61 The handle to the root node of the subtree to visit.
  62 .RE
  63
  64 .SH RETURN VALUES
  65 .sp
  66 .LP
  67 Upon successful completion, \fBdi_walk_node()\fR returns 0. Otherwise, \fB-1\fR
  68 is returned and \fIerrno\fR is set to indicate the error.
  69 .sp
  70 .LP
  71 The \fInode_callback\fR() function can return one of the following:
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBDI_WALK_CONTINUE\fR\fR
  76 .ad
  77 .RS 22n
  78 Continue walking.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBDI_WALK_PRUNESIB\fR\fR
  85 .ad
  86 .RS 22n
  87 Continue walking, but skip siblings and their child nodes.
  88 .RE
  89
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBDI_WALK_PRUNECHILD\fR\fR
  94 .ad
  95 .RS 22n
  96 Continue walking, but skip subtree rooted at current node.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBDI_WALK_TERMINATE\fR\fR
 103 .ad
 104 .RS 22n
 105 Terminate the walk immediately.
 106 .RE
 107
 108 .SH ERRORS
 109 .sp
 110 .LP
 111 The \fBdi_walk_node()\fR function will fail if:
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBEINVAL\fR\fR
 116 .ad
 117 .RS 10n
 118 Invalid argument.
 119 .RE
 120
 121 .SH ATTRIBUTES
 122 .sp
 123 .LP
 124 See \fBattributes\fR(5)  for descriptions of the following attributes:
 125 .sp
 126
 127 .sp
 128 .TS
 129 box;
 130 c | c
 131 l | l .
 132 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 133 _
 134 Interface Stability     Committed
 135 _
 136 MT-Level        Safe
 137 .TE
 138
 139 .SH SEE ALSO
 140 .sp
 141 .LP
 142 \fBdi_init\fR(3DEVINFO), \fBlibdevinfo\fR(3LIB), \fBattributes\fR(5)
 143 .sp
 144 .LP
 145 \fIWriting Device Drivers\fR