'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.TH di_devlink_init 3DEVINFO "21 Jul 2008" "SunOS 5.11" "Device Information Library Functions"
.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
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 9n
.rt  
The following values are supported:
.sp
.ne 2
.mk
.na
\fB\fBDI_MAKE_LINK\fR\fR
.ad
.RS 16n
.rt  
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
.mk
.na
\fB\fIname\fR\fR
.ad
.RS 9n
.rt  
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
.mk
.na
\fB\fIhdlp\fR\fR
.ad
.RS 9n
.rt  
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
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
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
.mk
.na
\fB\fBEPERM\fR\fR
.ad
.RS 9n
.rt  
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
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
\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)