man pages section 9: DDI and DKI Kernel Functions

Exit Print View

Updated: July 2014
 
 

ldi_open_by_devid(9F)

Name

ldi_open_by_dev, ldi_open_by_name, ldi_open_by_name_cred, ldi_open_by_devid, ldi_close - open and close devices

Synopsis

#include <sys/sunldi.h> 

int ldi_open_by_dev(dev_t *
devp, int 
otyp, int flag, 
cred_t  *cr, 
     ldi_handle_t *lhp, 
ldi_ident_t li);
int ldi_open_by_name(
char  *pathname, int 
flag, cred_t *cr, 
     ldi_handle_t *lhp, 
ldi_ident_t li);
int ldi_open_by_name_cred(
char  *pathname, int flag, 
cred_t *cr, ldi_handle_t *
lhp, ldi_ident_t li, 
cred_t *lookup_cr);
int ldi_open_by_devid(
ddi_devid_t devid, char  *
minor_name, int flag,
     cred_t *cr, ldi_handle_t *
lhp, ldi_ident_t 
li);
int ldi_close(ldi_handle_t
 lh, int flag
, cred_ t *cr);

Parameters

lh

Layered handle

lhp

Pointer to a layered handle that is returned upon a successful open.

li

LDI identifier.

cr

Pointer to the credential structure used to open a device.

devp

Pointer to a device number.

pathname

Pathname to a device.

devid

Device ID.

minor_name

Minor device node name.

otyp

Flag passed to the driver indicating which interface is open. Valid settings are:

OTYP_BLK

Open the device block interface.

OTYP_CHR

Open the device character interface.

Only one OTYP flag can be specified. To open streams devices, specify OTYP_CHR.

flag

Bit field that instructs the driver on how to open the device. Valid settings are:

FEXCL

Open the device with exclusive access; fail all other attempts to open the device.

FNDELAY

Open the device and return immediately. Do not block the open even if something is wrong.

FREAD

Open the device with read-only permission. (If ORed with FWRITE, allow both read and write access).

FWRITE

Open a device with write-only permission (if ORed with FREAD, then allow both read and write access).

FNOCTTY

Open the device. If the device is a tty, do not attempt to open it as a session-controlling tty.

Description

The ldi_open_by_dev(), ldi_open_by_name (), ldi_open_by_name_cred(), and ldi_open_by_devid () 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 filesystem path to a device node. Opens utilizing /devices paths are supported before root is mounted. Opens utilizing other filesystem paths to device nodes are supported only if root is already mounted. The lookup of the pathname is always done with kernel credentials, regardless of the supplied cred. However, the supplied cred is used to actually open the device.

The ldi_open_by_name_cred() function behaves similarly to the ldi_open_by_name() function, but the lookup of the supplied pathname is done using lookup_cr instead of kernel credentials, starting from the root directory associated with the cred. The lookup may file due to file permissions. Once a lookup succeeds, cred is still passed to the open (9e) routine of the target device.

The ldi_close() function closes a layered handle that was obtained with either ldi_open_by_dev(), ldi_open_by_name(), or ldi_open_by_devid(). After ldi_close() returns the layered handle, the lh that was previously passed in is no longer valid.

Return Values

The ldi_close() function returns 0 for success. EINVAL is returned for invalid input parameters. Otherwise, any other error number may be returned by the device.

The ldi_open_by_dev() and ldi_open_by_devid () functions return 0 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.

EINVAL

Invalid input parameters.

ENODEV

Requested device does not exist.

ENXIO

Unsupported device operation or access mode.

The ldi_open_by_name() and ldi_open_by_name_cred () functions returns 0 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.

EINVAL

Invalid input parameters.

ENODEV

Requested device path does not exist.

EACCES

Search permission is denied on a component of the path prefix, or the file exists and the credentials of lookup_cr are insufficient.

ENXIO

Unsupported device operation or access mode.

Context

These functions may be called from user or kernel context.

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.

See also

scsi_vhci(7D) , ldi_ident_from_dev(9F), ldi_ident_from_dip(9F), ldi_ident_from_stream(9F)

Notes

Use only OTYP_CHR or OTYP_BLK options when you use the ldi_open_by_dev () and ldi_open_by_devid() functions to open a device. Other flags, including OTYP_LYR, have been deprecated and should not be used with these interfaces.

The caller should be aware of cases when multiple paths to a single device may exist. (This can occur for scsi disk devices if scsi_vhci(7D) ) is disabled or a disk is connected to multiple controllers not supported by scsi_vhci(7D).

In these cases, ldi_open_by_devid() 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 ldi_open_by_devid(). Device handles associated with the same device but different access paths should have different filesystem device paths and dev_t values.

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 scsi_vhci (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 ldi_open_by_name() or ldi_open_by_name_cred().