'\" te
.\" Copyright (c) 2004, 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 ldi_open_by_dev 9F "9 Aug 2004" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ldi_open_by_dev, ldi_open_by_name, ldi_open_by_devid, ldi_close \- open and
close devices
.SH SYNOPSIS
.LP
.nf
#include <sys/sunldi.h> 

\fBint\fR \fBldi_open_by_dev\fR(\fBdev_t *\fR\fIdevp\fR, \fBint\fR \fIotyp\fR, \fBint\fR \fIflag\fR, \fBcred_t  *\fR\fIcr\fR, 
     \fBldi_handle_t *\fR\fIlhp\fR, \fBldi_ident_t\fR \fIli\fR);
.fi

.LP
.nf
\fBint\fR \fBldi_open_by_name\fR(\fBchar  *\fR\fIpathname\fR, \fBint\fR \fIflag\fR, \fBcred_t *\fR\fIcr\fR, 
     \fBldi_handle_t *\fR\fIlhp\fR, \fBldi_ident_t\fR \fIli\fR);
.fi

.LP
.nf
\fBint\fR \fBldi_open_by_devid\fR(\fBddi_devid_t\fR \fIdevid\fR, \fBchar  *\fR\fIminor_name\fR, \fBint\fR \fIflag\fR,
     \fBcred_t *\fR\fIcr\fR, \fBldi_handle_t *\fR\fIlhp\fR, \fBldi_ident_t\fR \fIli\fR);
.fi

.LP
.nf
\fBint\fR \fBldi_close\fR(\fBldi_handle_t\fR \fIlh\fR, \fBint\fR \fIflag\fR, \fBcred_ t *\fR\fIcr\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIlh\fR\fR
.ad
.RS 14n
.rt  
Layered handle
.RE

.sp
.ne 2
.mk
.na
\fB\fIlhp\fR\fR
.ad
.RS 14n
.rt  
Pointer to a layered handle that is returned upon a successful open.
.RE

.sp
.ne 2
.mk
.na
\fB\fIli\fR\fR
.ad
.RS 14n
.rt  
LDI identifier.
.RE

.sp
.ne 2
.mk
.na
\fB\fIcr\fR\fR
.ad
.RS 14n
.rt  
Pointer to the credential structure used to open a device.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdevp\fR\fR
.ad
.RS 14n
.rt  
Pointer to a device number.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpathname\fR\fR
.ad
.RS 14n
.rt  
Pathname to a device.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdevid\fR\fR
.ad
.RS 14n
.rt  
Device ID.
.RE

.sp
.ne 2
.mk
.na
\fB\fIminor_name\fR\fR
.ad
.RS 14n
.rt  
Minor device node name.
.RE

.sp
.ne 2
.mk
.na
\fB\fIotyp\fR\fR
.ad
.RS 14n
.rt  
Flag passed to the driver indicating which interface is open. Valid settings
are:
.sp
.ne 2
.mk
.na
\fBOTYP_BLK\fR
.ad
.RS 12n
.rt  
Open the device block interface.
.RE

.sp
.ne 2
.mk
.na
\fBOTYP_CHR\fR
.ad
.RS 12n
.rt  
Open the device character interface.
.RE

Only one OTYP flag can be specified. To open streams devices, specify
\fBOTYP_CHR\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fIflag\fR\fR
.ad
.RS 14n
.rt  
Bit field that instructs the driver on how to open the device. Valid settings
are:
.sp
.ne 2
.mk
.na
\fBFEXCL\fR
.ad
.RS 11n
.rt  
Open the device with exclusive access; fail all other attempts to open the
device.
.RE

.sp
.ne 2
.mk
.na
\fBFNDELAY\fR
.ad
.RS 11n
.rt  
Open the device and return immediately.  Do not block the open even if
something is wrong.
.RE

.sp
.ne 2
.mk
.na
\fBFREAD\fR
.ad
.RS 11n
.rt  
Open the device with read-only permission. (If ORed with \fBFWRITE\fR, allow
both read and write access).
.RE

.sp
.ne 2
.mk
.na
\fBFWRITE\fR
.ad
.RS 11n
.rt  
Open a device with write-only permission (if ORed with \fBFREAD\fR, then allow
both read and write access).
.RE

.sp
.ne 2
.mk
.na
\fBFNOCTTY\fR
.ad
.RS 11n
.rt  
Open the device. If the device is a tty, do not attempt to open it as a
session-controlling tty.
.RE

.RE

.SH DESCRIPTION
.sp
.LP
The \fBldi_open_by_dev()\fR, \fBldi_open_by_name()\fR and
\fBldi_open_by_devid()\fR functions allow a caller to open a block, character,
or streams device. Upon a successful open, a layered handle to the device is
returned via the layered handle pointed to by \fIlhp\fR. The ldi identifier
passed to these functions is previously allocated with
\fBldi_ident_from_stream\fR(9F), \fBldi_ident_from_dev\fR(9F), and
\fBldi_ident_from_dip\fR(9F).
.sp
.LP
The \fBldi_open_by_dev()\fR function opens a device specified by the dev_t
pointed to by devp.  Upon successful open, the caller should check the value of
the dev_t to see if it has changed. (Cloning devices will change this value
during opens.)   When opening a streams device, otyp must be OTYP_CHR.
.sp
.LP
The \fBldi_open_by_devid()\fR function opens a device by devid. The caller must
specify the minor node name to open.
.sp
.LP
The \fBldi_open_by_name()\fR function opens a device by pathname. Pathname is a
null terminated string in the kernel address space. Pathname must be an
absolute path, meaning that it must begin with '/'. The format of the pathname
supplied to this function is either a \fB/devices\fR path or any other
filesystem path to a device node. Opens utilizing \fB/devices\fR paths are
supported before root is mounted. Opens utilizing other filesystem paths to
device nodes are supported only if root is already mounted.
.sp
.LP
The \fBldi_close()\fR function closes a layered handle that was obtained with
either \fBldi_open_by_dev()\fR, \fBldi_open_by_name()\fR, or
\fBldi_open_by_devid()\fR. After \fBldi_close()\fR returns the layered handle,
the \fIlh\fR that was previously passed in is no longer valid.
.SH RETURN VALUES
.sp
.LP
The \fBldi_close()\fR function returns \fB0\fR for success. \fBEINVAL\fR is
returned for invalid input parameters. Otherwise, any other error number may be
returned by the device.
.sp
.LP
The \fBldi_open_by_dev()\fR and \fBldi_open_by_devid()\fR functions return
\fB0\fR upon success. If a failure occurs before the device is open, possible
return values are shown below. Otherwise any other error number may be returned
by the device.
.sp
.ne 2
.mk
.na
\fBEINVAL\fR
.ad
.RS 10n
.rt  
Invalid input parameters.
.RE

.sp
.ne 2
.mk
.na
\fBENODEV\fR
.ad
.RS 10n
.rt  
Requested device does not exist.
.RE

.sp
.ne 2
.mk
.na
\fBENXIO\fR
.ad
.RS 10n
.rt  
Unsupported device operation or access mode.
.RE

.sp
.LP
The \fBldi_open_by_name()\fR function returns \fB0\fR upon success. If a
failure occurs before the device is open, possible return values are shown
below. Otherwise any other error number may be returned by the device.
.sp
.ne 2
.mk
.na
\fBEINVAL\fR
.ad
.RS 10n
.rt  
Invalid input parameters.
.RE

.sp
.ne 2
.mk
.na
\fBENODEV\fR
.ad
.RS 10n
.rt  
Requested device path does not exist.
.RE

.sp
.ne 2
.mk
.na
\fBEACCES\fR
.ad
.RS 10n
.rt  
Search permission is denied on a component of the path prefix, or the file
exists and the permissions specified by \fIcr\fR are denied.
.RE

.sp
.ne 2
.mk
.na
\fBENXIO\fR
.ad
.RS 10n
.rt  
Unsupported device operation or access mode.
.RE

.SH CONTEXT
.sp
.LP
These functions may be called from user or kernel context.
.sp
.LP
These functions should not be called from a device's attach, detach, or power
entry point. This could result in a system crash or deadlock.
.SH SEE ALSO
.sp
.LP
\fBscsi_vhci\fR(7D), \fBldi_ident_from_dev\fR(9F),
\fBldi_ident_from_dip\fR(9F), \fBldi_ident_from_stream\fR(9F)
.SH NOTES
.sp
.LP
Use only OTYP_CHR or OTYP_BLK options when you use the \fBldi_open_by_dev()\fR
and \fBldi_open_by_devid()\fR functions to open a device. Other flags,
including OTYP_LYR, have been deprecated and should not be used with these
interfaces.
.sp
.LP
The caller should be aware of cases when multiple paths to a single device may
exist.  (This can occur for scsi disk devices if \fBscsi_vhci\fR(7D)) is
disabled or a disk is connected to multiple controllers not supported by
scsi_vhci(7D).
.sp
.LP
In these cases, \fBldi_open_by_devid()\fR returns a device handle that
corresponds to a  particular path to a target device. This path may not be the
same across multiple calls to \fBldi_open_by_devid()\fR.  Device handles
associated  with the same device but different access paths should have
different filesystem device paths and dev_t values.
.sp
.LP
In the cases where multiple paths to a device exist and access to the device
has not been virtualized via MPXIO (as with scsi disk devices not accessed via
\fBscsi_vhci\fR(7D)), the LDI does not provide any path fail-over capabilities.
If the caller wishes to do their own path management and failover they should
open all available paths to a device via \fBldi_open_by_name()\fR.