#ident	"@(#)di_init.3devinfo.txt.changebar 1.1     09/07/26 SMI"

  Device Information Library Functions            di_init(3DEVINFO)



  NAME
     di_init, di_fini - create and destroy a snapshot  of  kernel
     device tree

  SYNOPSIS
     cc [ flag... ] file... -ldevinfo [ library... ]
     #include <libdevinfo.h>

     di_node_t di_init(const char *phys_path, uint_t flags);


     void di_fini(di_node_t root);


  PARAMETERS
     flags        Snapshot content  specification.  The  possible
                  values  can  be a bitwise OR of at least one of
                  the following:

                  DINFOSUBTREE    Include subtree.


                  DINFOPROP       Include properties.


                  DINFOMINOR      Include minor node data.


                  DINFOCPYALL     Include all of the above.


                  DINFOPATH       Include  multipath  path   node
                                  data.


                  DINFOLYR        Include device layering data.

|
|                 DINFOHP         Include hotplug connection data.
|

                  DINFOCPYONE     Include  only  a  single   node
                                  without    properties,    minor
                                  nodes, or path nodes.



     phys_path    Physical path of the root device  node  of  the
                  snapshot. See di_devfs_path(3DEVINFO).


     root         Handle obtained by calling di_init().


  DESCRIPTION
     The di_init() function creates a snapshot of the kernel dev-
     ice  tree  and returns a handle of the root device node. The
     caller specifies the contents of the snapshot  by  providing
     flag and phys_path.


     The di_fini() 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 di_fini().

  RETURN VALUES
     Upon  success,  di_init()  returns  a   handle.   Otherwise,
     DI_NODE_NIL  is  returned  and  errno is set to indicate the
     error.

  ERRORS
     The di_init() function can set errno to any error code  that
     can  also  be  set by open(2), ioctl(2) or mmap(2). The most
     common error codes include:

     EACCES    Insufficient privilege for accessing device confi-
               guration data.


     ENXIO     Either  the  device  named  by  phys_path  is  not
               present  in  the system, or the devinfo(7D) driver
               is not installed properly.


     EINVAL    Either phys_path  is  incorrectly  formed  or  the
               flags argument is invalid.


  EXAMPLES
     Example 1 Using the libdevinfo Interfaces To Print All  Dev-
     ice Tree Node Names


     The following is an example using the libdevinfo  interfaces
     to print all device tree device node names:


       /*
        * 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\n", 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\n");
                  exit(1);
            }
            di_walk_node(root_node, DI_WALK_CLDFIRST, NULL, prt_nodename);
            di_fini(root_node);
       }


     Example 2 Using the libdevinfo Interfaces To Print The  Phy-
     sical Path Of SCSI Disks


     The following example  uses  the  libdevinfo  interfaces  to
     print the physical path of SCSI disks:


       /*
        * 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\n", 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\n");
               exit(1);
           }
               walk_disknodes(root_node);
               di_fini(root_node);
       }


  ATTRIBUTES
     See attributes(5)  for descriptions of the following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


  SEE ALSO
     open(2), ioctl(2), mmap(2), libdevinfo(3LIB), attributes(5)


     Writing Device Drivers