'\" 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 "May 15, 2008"
.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
.na
\fB\fIflags\fR\fR
.ad
.RS 13n
Snapshot content specification. The possible values can be a bitwise OR of at
least one of the following:
.sp
.ne 2
.na
\fB\fBDINFOSUBTREE\fR\fR
.ad
.RS 16n
Include subtree.
.RE

.sp
.ne 2
.na
\fB\fBDINFOPROP\fR\fR
.ad
.RS 16n
Include properties.
.RE

.sp
.ne 2
.na
\fB\fBDINFOMINOR\fR\fR
.ad
.RS 16n
Include minor node data.
.RE

.sp
.ne 2
.na
\fB\fBDINFOCPYALL\fR\fR
.ad
.RS 16n
Include all of the above.
.RE

.sp
.ne 2
.na
\fB\fBDINFOPATH\fR\fR
.ad
.RS 16n
Include multipath path node data.
.RE

.sp
.ne 2
.na
\fB\fBDINFOLYR\fR\fR
.ad
.RS 16n
Include device layering data.
.RE

.sp
.ne 2
.na
\fB\fBDINFOCPYONE\fR\fR
.ad
.RS 16n
Include only a single node without properties, minor nodes, or path nodes.
.RE

.RE

.sp
.ne 2
.na
\fB\fIphys_path\fR\fR
.ad
.RS 13n
Physical path of the \fIroot\fR device node of the snapshot. See
\fBdi_devfs_path\fR(3DEVINFO).
.RE

.sp
.ne 2
.na
\fB\fIroot\fR\fR
.ad
.RS 13n
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
.na
\fB\fBEACCES\fR\fR
.ad
.RS 10n
Insufficient privilege for accessing device configuration data.
.RE

.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 10n
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
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
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
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.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