xref: /illumos-gate/usr/src/man/man3devinfo/di_devlink_init.3devinfo (revision 8682d1ef2a0960ed5a9f05b9448eaa3e68ac931f) 
 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]
 di_devlink_init 3DEVINFO "21 Jul 2008" "SunOS 5.11" "Device Information Library Functions"
 NAME
di_devlink_init, di_devlink_fini - create and destroy a snapshot of devlinks

 SYNOPSIS


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

di_devlink_handle_t di_devlink_init(const char *name,
 uint_t flags);






int di_devlink_fini(di_devlink_handle_t *hdlp);




 PARAMETERS

flags


The following values are supported:


DI_MAKE_LINK


Synchronize with devlink management before taking the snapshot. The name
argument determines which devlink management activities must complete before
taking a devlink snapshot. Appropriate privileges are required to use this
flag.








name


If flags is DI_MAKE_LINK, name determines which devlink management
activity must complete prior to snapshot.




If name is NULL then all devlink management activities must
complete. The devlink snapshot returned accurately reflects the entire kernel
device tree.






If name is a driver name, devlink management activities associated with
nodes bound to that driver must complete.






If name is a path to a node in the kernel device tree (no
"/devices" prefix), devlink management activities below node must
complete.






If name is a path to a minor node in the kernel device tree (no
"/devices"prefix), devlink management activities on that minor node must
complete.







hdlp


The handle to the snapshot obtained by calling di_devlink_init().




 DESCRIPTION

System management applications often need to map a "/devices" path to a
minor node to a public "/dev" device name. The di_devlink_*()
functions provide an efficient way to accomplish this.


The di_devlink_init() function takes a snapshot of devlinks and returns a
handle to this snapshot.


The di_devlink_fini() function destroys the devlink snapshot and frees
the associated memory.

 RETURN VALUES

Upon successful completion, di_devlink_init() returns a handle to a
devlink snapshot. Otherwise, DI_LINK_NIL is returned and errno is
set to indicate the error.


Upon successful completion, di_devlink_fini() returns 0. Otherwise, -1 is
returned and errno is set to indicate the error.

 ERRORS

The di_devlink_init() function will fail if:


EINVAL


One or more arguments is invalid.





The di_devlink_init() function with DI_MAKE_LINK can also fail if:


EPERM


The user does no have appropriate privileges.





The di_devlink_init() function can set errno to any error value
that can also be set by malloc(3C), open(2), ioctl(2), or
mmap(2).

 ATTRIBUTES

See attributes(5) for descriptions of the following attributes:







ATTRIBUTE TYPEATTRIBUTE VALUE
Interface StabilityCommitted
MT-LevelSafe



 SEE ALSO

ioctl(2), mmap(2), open(2), di_devlink_path(3DEVINFO),
di_devlink_walk(3DEVINFO), libdevinfo(3LIB), malloc(3C),
attributes(5)