pt_open(3X)

Synopsis

#include <libsdi.h>

int pt_open(pt_address_type_t type, void *address, uint_t flag, pt_handle_t *handle)

Description

type

The address type of the storage device to open. One value for type is currently supported: PASSTHRU_SCSI_ADDRESS.

address

The address argument defines which device of Peripheral Device Type type is opened. It points to a structure of type pt_scsi_address_t, whose elements are:

   int     psa_controller;
   int     psa_bus;
   int     psa_target;
   int     psa_lun;

path

The I/O path used to send the command; used only in a multi-path I/O (MPIO) configuration. In such a configuration, setting path to -1 instructs SDI to choose any active path to the device in question. Setting path to an integer from 0 to n will choose the nth path to the device in question. In the absence of a multi-path I/O configuration, the value of path is ignored. The identity of path n is not guaranteed to persist from system boot to system boot.

flag

By default, pt_open allows other applications pass-through access to the device instance while the current application has the device open for pass-through operations. The following values for flag modify this behavior as described; one or both of these flags may be used:

PT_EXCLUSIVE

No other application may have pass-through access to this device while this application has the device open for pass-through. This type of open fails if the device has already been opened by another application using pt_open.

PT_SUSPEND_IO

Specifies that I/O operations initiated by other agents in the system besides pass-through applications are blocked during this pass-through session. Extreme care should be exercised using PT_SUSPEND_IO. Any kernel function needing access to the device open for pass-through will be blocked when this flag is used, including page swapping. Applications that use this combination must assure that any memory they need is locked in core using mlock(3C) before this type of open is attempted.

handle

A pointer to an opaque handle that the application must use for all subsequent calls to pt_send and pt_close. This handle supplies SDI with identity and state information for the SDI device referenced. Note that handle is not a file descriptor and cannot be treated like one. See ``Compatibility''.

Return values

Errors

Usage

Compatibility

In prior releases, an application used the open(2) system call to open the character special file for the device. Then, it called ioctl(2) with the B_GETDEV command (new applications should use pt_open(3X)).

The device value returned (a file descriptor) would then be used to create a character special file which, when opened, could be used by the application to send a pass-through (SDI_SEND) ioctl command (new applications should use pt_send(3X)).

After completing the pass-through operations, the application would then close the device using close(2) (new applications should use pt_close(3X)).

One exception to directly translating open/ioctl/close sequences to the pass-through library routines is when an application uses fork(2) and the parent and child manipulate the SCSI device independently. The open/ioctl/close functions use file descriptors to the SCSI device. In this model, when a process forks a child, the child receives its own file descriptor to the device, so there's no problem if the parent closes its file descriptor to the device.

The pass-through library interface does not behave in this manner. That is, the handle returned by pt_open and used by pt_send and pt_close is not a file descriptor and is part of the name space of the parent and all its children.

This can present a problem when porting code that uses the ioctl interface to the library interface. For example, an application uses open to open a SCSI device and then forks. The parent then calls close and the child does a subsequent ioctl on the same device; which succeeds because the child has its own file descriptor.

If you simply replace the open/ioctl/close sequence in this application with calls to pt_open/pt_send/pt_close, then the pt_send attempted by the child will fail with errno set to EBADF.

The solution in this particular case would be to either move the parent's pt_close below the point in the code where the child returns, or just remove the pt_close from the parent (and the child). The device will be closed during the exit processing of the parent.

Standards conformance

References