'\" 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_DEVLINK_INIT 3DEVINFO "Jul 21, 2008"
.SH NAME
di_devlink_init, di_devlink_fini \- create and destroy a snapshot of devlinks
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ]
#include <libdevinfo.h>

\fBdi_devlink_handle_t\fR \fBdi_devlink_init\fR(\fBconst char *\fR\fIname\fR,
     \fBuint_t\fR \fIflags\fR);
.fi

.LP
.nf
\fBint\fR \fBdi_devlink_fini\fR(\fBdi_devlink_handle_t *\fR\fIhdlp\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIflags\fR\fR
.ad
.RS 9n
The following values are supported:
.sp
.ne 2
.na
\fB\fBDI_MAKE_LINK\fR\fR
.ad
.RS 16n
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.
.RE

.RE

.sp
.ne 2
.na
\fB\fIname\fR\fR
.ad
.RS 9n
If flags is \fBDI_MAKE_LINK\fR, \fIname\fR determines which devlink management
activity must complete prior to snapshot.
.RS +4
.TP
.ie t \(bu
.el o
If \fIname\fR is \fINULL\fR then all devlink management activities must
complete. The devlink snapshot returned accurately reflects the entire kernel
device tree.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fIname\fR is a driver name, devlink management activities associated with
nodes bound to that driver must complete.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fIname\fR is a path to a node in the kernel device tree (no
"\fB/devices\fR" prefix), devlink management activities below node must
complete.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fIname\fR is a path to a minor node in the kernel device tree (no
"\fB/devices\fR"prefix), devlink management activities on that minor node must
complete.
.RE
.RE

.sp
.ne 2
.na
\fB\fIhdlp\fR\fR
.ad
.RS 9n
The handle to the snapshot obtained by calling \fBdi_devlink_init()\fR.
.RE

.SH DESCRIPTION
.sp
.LP
System management applications often need to map a "\fB/devices\fR" path to a
minor node to a public "\fB/dev\fR" device name. The \fBdi_devlink_*()\fR
functions provide an efficient way to accomplish this.
.sp
.LP
The \fBdi_devlink_init()\fR function takes a snapshot of devlinks and returns a
handle to this snapshot.
.sp
.LP
The \fBdi_devlink_fini()\fR function destroys the devlink snapshot and frees
the associated memory.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBdi_devlink_init()\fR returns a handle to a
devlink snapshot. Otherwise, \fBDI_LINK_NIL\fR is returned and \fBerrno\fR is
set to indicate the error.
.sp
.LP
Upon successful completion, \fBdi_devlink_fini()\fR returns 0. Otherwise, -1 is
returned and \fBerrno\fR is set to indicate the error.
.SH ERRORS
.sp
.LP
The \fBdi_devlink_init()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
One or more arguments is invalid.
.RE

.sp
.LP
The \fBdi_devlink_init()\fR function with \fBDI_MAKE_LINK\fR can also fail if:
.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 9n
The user does no have appropriate privileges.
.RE

.sp
.LP
The \fBdi_devlink_init()\fR function can set \fBerrno\fR to any error value
that can also be set by \fBmalloc\fR(3C), \fBopen\fR(2), \fBioctl\fR(2), or
\fBmmap\fR(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
\fBioctl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBdi_devlink_path\fR(3DEVINFO),
\fBdi_devlink_walk\fR(3DEVINFO), \fBlibdevinfo\fR(3LIB), \fBmalloc\fR(3C),
\fBattributes\fR(5)