share/man/man3devinfo/di_path_client_next_path.3devinfo

   1 '\" te
   2 .\" Copyright (c) 2008, 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_PATH_CLIENT_NEXT_PATH 3DEVINFO "May 15, 2008"
   7 .SH NAME
   8 di_path_client_next_path, di_path_phci_next_path \- libdevinfo path node
   9 traversal functions
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ]
  14 #include <libdevinfo.h>
  15
  16 \fBdi_path_t\fR \fBdi_path_client_next_path\fR(\fBdi_node_t node\fR \fInode\fR,
  17      \fBdi_path_t\fR \fIpath\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBdi_path_t\fR \fBdi_path_phci_next_path\fR(\fBdi_node_t node\fR \fInode\fR,
  23      \fBdi_path_t\fR \fIpath\fR);
  24 .fi
  25
  26 .SH PARAMETERS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fInode\fR\fR
  31 .ad
  32 .RS 8n
  33 The handle to a device node in a \fBdi_init\fR(3DEVINFO) snapshot.  For
  34 \fBdi_path_client_next_path()\fR, \fInode\fR must be a client device node.  For
  35 \fBdi_path_phci_next_path()\fR, \fInode\fR must be a pHCI device node.
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIpath\fR\fR
  42 .ad
  43 .RS 8n
  44 \fBDI_PATH_NIL\fR, or the handle to a path node in a snapshot.
  45 .RE
  46
  47 .SH DESCRIPTION
  48 .sp
  49 .LP
  50 Each path node is an element in a pHCI-client matrix. The matrix is implemented
  51 by dual linked lists: one list links path nodes related to a common client
  52 head, and the other links path nodes related to a common pHCI head.
  53 .sp
  54 .LP
  55 The \fBdi_path_client_next_path()\fR function is called on a
  56 multipathing 'client' device node, where a 'client' is the child of a vHCI device node, and
  57 is associated with a specific endpoint device identity (independent of physical
  58 paths).  If the path argument is \fINULL\fR, \fBdi_path_client_next_path()\fR
  59 returns the first path node associated with the client. To walk all path nodes
  60 associated with a client, returned \fBdi_path_t\fR values are fed back into
  61 \fBdi_path_client_next_path()\fR, via the \fIpath\fR argument, until a null
  62 path node is returned.  For each path node, \fBdi_path_bus_addr\fR(3DEVINFO)
  63 returns the pHCI child path node unit-address.
  64 .sp
  65 .LP
  66 The \fBdi_path_phci_next_path()\fR function is called on a multipathing pHCI
  67 device node. If the path argument is \fINULL\fR, \fBdi_path_phci_next_path()\fR
  68 returns the first path node associated with the pHCI. To walk all path nodes
  69 associated with a pHCI, returned \fBdi_path_t\fR values are fed back into
  70 \fBdi_path_phci_next_path()\fR, via the \fIpath\fR argument, until a null path
  71 node is returned.  For each path node, \fBdi_path_client_node\fR(3DEVINFO)
  72 provides a pointer to the associated client device node.
  73 .sp
  74 .LP
  75 A device node can be a client device node of one multipathing class and a pHCI
  76 device node of another class.
  77 .SH RETURN VALUES
  78 .sp
  79 .LP
  80 Upon successful completion, a handle to the next path node is returned.
  81 Otherwise, \fBDI_PATH_NIL\fR is returned and \fBerrno\fR is set to indicate the
  82 error.
  83 .SH ERRORS
  84 .sp
  85 .LP
  86 These functions will fail if:
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBEINVAL\fR\fR
  91 .ad
  92 .RS 11n
  93 One or more argument was invalid.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBENOTSUP\fR\fR
 100 .ad
 101 .RS 11n
 102 Path node information is not available in the snapshot.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBENXIO\fR\fR
 109 .ad
 110 .RS 11n
 111 The end of the path node list was reached.
 112 .RE
 113
 114 .SH ATTRIBUTES
 115 .sp
 116 .LP
 117 See \fBattributes\fR(5)  for descriptions of the following attributes:
 118 .sp
 119
 120 .sp
 121 .TS
 122 box;
 123 c | c
 124 l | l .
 125 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 126 _
 127 Interface Stability     Committed
 128 _
 129 MT-Level        Safe
 130 .TE
 131
 132 .SH SEE ALSO
 133 .sp
 134 .LP
 135 \fBdi_init\fR(3DEVINFO), \fBdi_path_bus_addr\fR(3DEVINFO),
 136 \fBdi_path_client_node\fR(3DEVINFO), \fBlibdevinfo\fR(3LIB),
 137 \fBattributes\fR(5)
 138 .sp
 139 .LP
 140 \fIWriting Device Drivers\fR