path: root/usr/src/man/man3devinfo/di_init.3devinfo

'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH di_init 3DEVINFO "15 May 2008" "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 <libdevinfo.h>

\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\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 <stdio.h>
#include <libdevinfo.h>

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 <stdio.h>
#include <libdevinfo.h>
#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\fR