share/man/man3devinfo/di_walk_minor.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_MINOR 3DEVINFO "Jan 14, 2009"
   7 .SH NAME
   8 di_walk_minor \- traverse libdevinfo minor 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_minor\fR(\fBdi_node_t\fR \fIroot\fR, \fBconst char *\fR\fIminor_nodetype\fR,
  16      \fBuint_t\fR \fIflag\fR, \fBvoid *\fR\fIarg\fR, \fBint\fR (\fI*minor_callback\fR)(di_node_t \fInode\fR,
  17      di_minor_t \fIminor\fR, void *\fIarg\fR));
  18 .fi
  19
  20 .SH PARAMETERS
  21 .sp
  22 .ne 2
  23 .na
  24 \fB\fIarg\fR\fR
  25 .ad
  26 .RS 18n
  27 Pointer to caller- specific user data.
  28 .RE
  29
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fIflag\fR\fR
  34 .ad
  35 .RS 18n
  36 Specify 0. Reserved for future use.
  37 .RE
  38
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIminor\fR\fR
  43 .ad
  44 .RS 18n
  45 The minor node visited.
  46 .RE
  47
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fIminor_nodetype\fR\fR
  52 .ad
  53 .RS 18n
  54 A character string specifying the minor data type, which may be one of the
  55 types defined by the Solaris DDI framework, for example, \fBDDI_NT_BLOCK\fR.
  56 \fBNULL\fR matches all \fIminor_node\fR  types. See
  57 \fBddi_create_minor_node\fR(9F).
  58 .RE
  59
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fInode\fR\fR
  64 .ad
  65 .RS 18n
  66 The device node with which to  the minor node is associated.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIroot\fR\fR
  73 .ad
  74 .RS 18n
  75 Root of subtree to visit.
  76 .RE
  77
  78 .SH DESCRIPTION
  79 .sp
  80 .LP
  81 The \fBdi_walk_minor()\fR function visits all minor nodes attached to device
  82 nodes in a subtree rooted at \fIroot\fR. For each  minor node that matches
  83 \fIminor_nodetype\fR, the caller-supplied function \fIminor_callback\fR() is
  84 invoked. The walk terminates immediately when \fIminor_callback\fR() returns
  85 \fBDI_WALK_TERMINATE\fR.
  86 .SH RETURN VALUES
  87 .sp
  88 .LP
  89 Upon successful completion, \fBdi_walk_minor()\fR returns 0. Otherwise, -1 is
  90 returned and errno is set to indicate the error.
  91 .sp
  92 .LP
  93 The \fBminor_callback()\fR function returns one of the following:
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBDI_WALK_CONTINUE\fR\fR
  98 .ad
  99 .RS 21n
 100 Continue to visit subsequent minor data nodes.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBDI_WALK_TERMINATE\fR\fR
 107 .ad
 108 .RS 21n
 109 Terminate the walk immediately.
 110 .RE
 111
 112 .SH ERRORS
 113 .sp
 114 .LP
 115 The \fBdi_walk_minor()\fR function will fail if:
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBEINVAL\fR\fR
 120 .ad
 121 .RS 10n
 122 Invalid argument.
 123 .RE
 124
 125 .SH ATTRIBUTES
 126 .sp
 127 .LP
 128 See \fBattributes\fR(5) for descriptions of the following attributes:
 129 .sp
 130
 131 .sp
 132 .TS
 133 box;
 134 c | c
 135 l | l .
 136 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 137 _
 138 Interface Stability     Committed
 139 _
 140 MT-Level        Safe
 141 .TE
 142
 143 .SH SEE ALSO
 144 .sp
 145 .LP
 146 \fBdladm\fR(1M), \fBdi_minor_nodetype\fR(3DEVINFO), dlpi_walk(3DLPI),
 147 \fBlibdevinfo\fR(3LIB), \fBattributes\fR(5), \fBfilesystem\fR(5),
 148 \fBddi_create_minor_node\fR(9F)
 149 .sp
 150 .LP
 151 \fIWriting Device Drivers\fR
 152 .SH NOTES
 153 .sp
 154 .LP
 155 The \fBdi_walk_minor()\fR function is no longer an accurate method for walking
 156 network datalink interfaces on the system. Applications should use
 157 \fBdlpi_walk\fR(3DLPI) instead. It has been common for applications to use
 158 \fBdi_walk_minor()\fR to walk networking devices by passing in a
 159 \fBminor_nodetype\fR of \fBDDI_NT_NET\fR, in most cases to discover the set of
 160 DLPI devices on the system. Solaris now makes a layering distinction between
 161 networking devices (the objects displayed in the \fBDEVICE\fR field by
 162 \fBdladm\fR \fBshow-phys\fR) and network datalink interfaces (the objects
 163 displayed by \fBdladm\fR \fBshow-link\fR). Datalink interfaces are represented
 164 as the set of DLPI device nodes that applications can open by using
 165 \fBdlpi_open\fR(3DLPI) or by opening DLPI nodes out of the \fB/dev/net\fR
 166 filesystem (see \fBfilesystem\fR(5)). The \fBdlpi_walk\fR(3DLPI) function is
 167 the proper function to walk these nodes.