share/man/man3devinfo/di_init.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_INIT 3DEVINFO "May 15, 2008"
   7 .SH NAME
   8 di_init, di_fini \- create and destroy a snapshot of kernel device tree
   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 \fBdi_node_t\fR \fBdi_init\fR(\fBconst char *\fR\fIphys_path\fR, \fBuint_t\fR \fIflags\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBvoid\fR \fBdi_fini\fR(\fBdi_node_t\fR \fIroot\fR);
  21 .fi
  22
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIflags\fR\fR
  28 .ad
  29 .RS 13n
  30 Snapshot content specification. The possible values can be a bitwise OR of at
  31 least one of the following:
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fBDINFOSUBTREE\fR\fR
  36 .ad
  37 .RS 16n
  38 Include subtree.
  39 .RE
  40
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fBDINFOPROP\fR\fR
  45 .ad
  46 .RS 16n
  47 Include properties.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBDINFOMINOR\fR\fR
  54 .ad
  55 .RS 16n
  56 Include minor node data.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fBDINFOCPYALL\fR\fR
  63 .ad
  64 .RS 16n
  65 Include all of the above.
  66 .RE
  67
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fBDINFOPATH\fR\fR
  72 .ad
  73 .RS 16n
  74 Include multipath path node data.
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBDINFOLYR\fR\fR
  81 .ad
  82 .RS 16n
  83 Include device layering data.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBDINFOCPYONE\fR\fR
  90 .ad
  91 .RS 16n
  92 Include only a single node without properties, minor nodes, or path nodes.
  93 .RE
  94
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fIphys_path\fR\fR
 101 .ad
 102 .RS 13n
 103 Physical path of the \fIroot\fR device node of the snapshot. See
 104 \fBdi_devfs_path\fR(3DEVINFO).
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fIroot\fR\fR
 111 .ad
 112 .RS 13n
 113 Handle obtained by calling \fBdi_init()\fR.
 114 .RE
 115
 116 .SH DESCRIPTION
 117 .sp
 118 .LP
 119 The \fBdi_init()\fR function creates a snapshot of the kernel device tree and
 120 returns a handle of the \fIroot\fR device node. The caller specifies the
 121 contents of the snapshot by providing \fIflag\fR and \fIphys_path\fR.
 122 .sp
 123 .LP
 124 The \fBdi_fini()\fR function destroys the snapshot of the kernel device tree
 125 and frees the associated memory. All  handles associated with this snapshot
 126 become invalid after the call to \fBdi_fini()\fR.
 127 .SH RETURN VALUES
 128 .sp
 129 .LP
 130 Upon success, \fBdi_init()\fR returns a handle. Otherwise, \fBDI_NODE_NIL\fR is
 131 returned and \fIerrno\fR is set to indicate the error.
 132 .SH ERRORS
 133 .sp
 134 .LP
 135 The \fBdi_init()\fR function can set \fIerrno\fR to any error code that can
 136 also be set by \fBopen\fR(2), \fBioctl\fR(2) or \fBmmap\fR(2). The most common
 137 error codes include:
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBEACCES\fR\fR
 142 .ad
 143 .RS 10n
 144 Insufficient privilege for accessing device configuration data.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBENXIO\fR\fR
 151 .ad
 152 .RS 10n
 153 Either the device named by \fIphys_path\fR is not present in the system, or the
 154 \fBdevinfo\fR(7D) driver is not installed properly.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBEINVAL\fR\fR
 161 .ad
 162 .RS 10n
 163 Either \fIphys_path\fR is incorrectly formed or the \fIflags\fR argument is
 164 invalid.
 165 .RE
 166
 167 .SH EXAMPLES
 168 .LP
 169 \fBExample 1 \fRUsing the \fBlibdevinfo\fR Interfaces To Print All Device Tree
 170 Node Names
 171 .sp
 172 .LP
 173 The following is an example using the \fBlibdevinfo\fR interfaces to print all
 174 device tree device node names:
 175
 176 .sp
 177 .in +2
 178 .nf
 179 /*
 180  * Code to print all device tree device node names
 181  */
 182
 183 #include <stdio.h>
 184 #include <libdevinfo.h>
 185
 186 int
 187 prt_nodename(di_node_t node, void *arg)
 188 {
 189      printf("%s\en", di_node_name(node));
 190      return (DI_WALK_CONTINUE);
 191 }
 192
 193 main()
 194 {
 195      di_node_t root_node;
 196      if((root_node = di_init("/", DINFOSUBTREE)) == DI_NODE_NIL) {
 197            fprintf(stderr, "di_init() failed\en");
 198            exit(1);
 199      }
 200      di_walk_node(root_node, DI_WALK_CLDFIRST, NULL, prt_nodename);
 201      di_fini(root_node);
 202 }
 203 .fi
 204 .in -2
 205
 206 .LP
 207 \fBExample 2 \fRUsing the \fBlibdevinfo\fR Interfaces To Print The Physical
 208 Path Of SCSI Disks
 209 .sp
 210 .LP
 211 The following example uses the \fBlibdevinfo\fR interfaces to print the
 212 physical path of SCSI disks:
 213
 214 .sp
 215 .in +2
 216 .nf
 217 /*
 218  * Code to print physical path of scsi disks
 219  */
 220
 221 #include <stdio.h>
 222 #include <libdevinfo.h>
 223 #define DISK_DRIVER     "sd"    /* driver name */
 224
 225 void
 226 prt_diskinfo(di_node_t node)
 227 {
 228     int instance;
 229         char *phys_path;
 230
 231     /*
 232      * If the device node exports no minor nodes,
 233      * there is no physical disk.
 234      */
 235      if (di_minor_next(node, DI_MINOR_NIL) == DI_MINOR_NIL) {
 236               return;
 237          }
 238
 239          instance = di_instance(node);
 240          phys_path = di_devfs_path(node);
 241          printf("%s%d: %s\en", DISK_DRIVER, instance, phys_path);
 242          di_devfs_path_free(phys_path);
 243 }
 244
 245 void
 246 walk_disknodes(di_node_t node)
 247 {
 248         node = di_drv_first_node(DISK_DRIVER, node);
 249         while (node != DI_NODE_NIL) {
 250              prt_diskinfo(node);
 251              node = di_drv_next_node(node);
 252         }
 253 }
 254
 255 main()
 256 {
 257     di_node_t root_node;
 258     if ((root_node = di_init("/", DINFOCPYALL)) == DI_NODE_NIL) {
 259         fprintf(stderr, "di_init() failed\en");
 260         exit(1);
 261     }
 262         walk_disknodes(root_node);
 263         di_fini(root_node);
 264 }
 265 .fi
 266 .in -2
 267
 268 .SH ATTRIBUTES
 269 .sp
 270 .LP
 271 See \fBattributes\fR(5)  for descriptions of the following attributes:
 272 .sp
 273
 274 .sp
 275 .TS
 276 box;
 277 c | c
 278 l | l .
 279 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 280 _
 281 Interface Stability     Committed
 282 _
 283 MT-Level        Safe
 284 .TE
 285
 286 .SH SEE ALSO
 287 .sp
 288 .LP
 289 \fBopen\fR(2), \fBioctl\fR(2), \fBmmap\fR(2), \fBlibdevinfo\fR(3LIB),
 290 \fBattributes\fR(5)
 291 .sp
 292 .LP
 293 \fIWriting Device Drivers\fR