'\" te .\" Copyright (c) 2008, 2015, Oracle and/or its affiliates. All rights reserved. .TH di_init 3DEVINFO "23 Sep 2015" "SunOS 5.11" "Device Information Library Functions" .SH NAME di_init, di_fini \- create and destroy a snapshot of kernel device tree .SH SYNOPSIS .LP .nf \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ] #include \fBdi_node_t\fR \fBdi_init\fR(\fBconst char *\fR\fIphys_path\fR, \fBuint_t\fR \fIflags\fR); .fi .LP .nf \fBvoid\fR \fBdi_fini\fR(\fBdi_node_t\fR \fIroot\fR); .fi .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIflags\fR\fR .ad .RS 13n .rt Snapshot content specification. The possible values can be a bitwise OR of at least one of the following: .sp .ne 2 .mk .na \fB\fBDINFOCACHE\fR\fR .ad .RS 16n .rt This flag returns cached device information. It is incompatible with all the other flags. .sp Most callers should use this flag since it avoids device tree traversals which can negatively impact system performance. .sp The cached snapshot will contain device information for all the devices discovered by the system at this time, where as other flags may not return information for devices that are not currently attached. .sp The cached snapshot includes information about each configured device, including paths, minor nodes, and properties. .sp System operations that configure or remove a device, a path to a device, or a device's minor nodes will all result in a cache update. Some property value updates also trigger cache updates. For dynamic properties updated by a driver's \fBprop_op\fR(9E) implementation, the cached value will always be stale. .RE .sp .ne 2 .mk .na \fB\fBDINFOSUBTREE\fR\fR .ad .RS 16n .rt Include subtree. .RE .sp .ne 2 .mk .na \fB\fBDINFOPROP\fR\fR .ad .RS 16n .rt Include properties. .RE .sp .ne 2 .mk .na \fB\fBDINFOMINOR\fR\fR .ad .RS 16n .rt Include minor node data. .RE .sp .ne 2 .mk .na \fB\fBDINFOCPYALL\fR\fR .ad .RS 16n .rt Include all of the above. .RE .sp .ne 2 .mk .na \fB\fBDINFOPATH\fR\fR .ad .RS 16n .rt Include multipath path node data. .RE .sp .ne 2 .mk .na \fB\fBDINFOLYR\fR\fR .ad .RS 16n .rt Include device layering data. .RE .sp .ne 2 .mk .na \fB\fBDINFOCPYONE\fR\fR .ad .RS 16n .rt Include only a single node without properties, minor nodes, or path nodes. .RE .RE .sp .ne 2 .mk .na \fB\fIphys_path\fR\fR .ad .RS 13n .rt Physical path of the \fIroot\fR device node of the snapshot. See \fBdi_devfs_path\fR(3DEVINFO). .RE .sp .ne 2 .mk .na \fB\fIroot\fR\fR .ad .RS 13n .rt Handle obtained by calling \fBdi_init()\fR. .RE .SH DESCRIPTION .sp .LP The \fBdi_init()\fR function creates a snapshot of the kernel device tree and returns a handle of the \fIroot\fR device node. The caller specifies the contents of the snapshot by providing \fIflag\fR and \fIphys_path\fR. .sp .LP The \fBdi_fini()\fR function destroys the snapshot of the kernel device tree and frees the associated memory. All handles associated with this snapshot become invalid after the call to \fBdi_fini()\fR. .SH RETURN VALUES .sp .LP Upon success, \fBdi_init()\fR returns a handle. Otherwise, \fBDI_NODE_NIL\fR is returned and \fIerrno\fR is set to indicate the error. .SH ERRORS .sp .LP The \fBdi_init()\fR function can set \fIerrno\fR to any error code that can also be set by \fBopen\fR(2), \fBioctl\fR(2) or \fBmmap\fR(2). The most common error codes include: .sp .ne 2 .mk .na \fB\fBEACCES\fR\fR .ad .RS 10n .rt Insufficient privilege for accessing device configuration data. .RE .sp .ne 2 .mk .na \fB\fBENXIO\fR\fR .ad .RS 10n .rt Either the device named by \fIphys_path\fR is not present in the system, or the \fBdevinfo\fR(7D) driver is not installed properly. .RE .sp .ne 2 .mk .na \fB\fBEINVAL\fR\fR .ad .RS 10n .rt Either \fIphys_path\fR is incorrectly formed or the \fIflags\fR argument is invalid. .RE .SH EXAMPLES .LP \fBExample 1 \fRUsing the \fBlibdevinfo\fR Interfaces To Print All Device Tree Node Names .sp .LP The following is an example using the \fBlibdevinfo\fR interfaces to print all device tree device node names: .sp .in +2 .nf /* * Code to print all device tree device node names */ #include #include int prt_nodename(di_node_t node, void *arg) { printf("%s\en", di_node_name(node)); return (DI_WALK_CONTINUE); } main() { di_node_t root_node; if((root_node = di_init("/", DINFOSUBTREE)) == DI_NODE_NIL) { fprintf(stderr, "di_init() failed\en"); exit(1); } di_walk_node(root_node, DI_WALK_CLDFIRST, NULL, prt_nodename); di_fini(root_node); } .fi .in -2 .LP \fBExample 2 \fRUsing the \fBlibdevinfo\fR Interfaces To Print The Physical Path Of SCSI Disks .sp .LP The following example uses the \fBlibdevinfo\fR interfaces to print the physical path of SCSI disks: .sp .in +2 .nf /* * Code to print physical path of scsi disks */ #include #include #define DISK_DRIVER "sd" /* driver name */ void prt_diskinfo(di_node_t node) { int instance; char *phys_path; /* * If the device node exports no minor nodes, * there is no physical disk. */ if (di_minor_next(node, DI_MINOR_NIL) == DI_MINOR_NIL) { return; } instance = di_instance(node); phys_path = di_devfs_path(node); printf("%s%d: %s\en", DISK_DRIVER, instance, phys_path); di_devfs_path_free(phys_path); } void walk_disknodes(di_node_t node) { node = di_drv_first_node(DISK_DRIVER, node); while (node != DI_NODE_NIL) { prt_diskinfo(node); node = di_drv_next_node(node); } } main() { di_node_t root_node; if ((root_node = di_init("/", DINFOCPYALL)) == DI_NODE_NIL) { fprintf(stderr, "di_init() failed\en"); exit(1); } walk_disknodes(root_node); di_fini(root_node); } .fi .in -2 .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSafe .TE .SH SEE ALSO .sp .LP \fBopen\fR(2), \fBioctl\fR(2), \fBmmap\fR(2), \fBlibdevinfo\fR(3LIB), \fBattributes\fR(5) .sp .LP \fIWriting Device Drivers for Oracle Solaris 11.2\fR