pt_open(3X)


pt_open -- initiate Host Bus Adapter (HBA) pass-through access

Synopsis

cc [options] file -lsdi
#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

On success, pt_open returns 0, and a handle to the open device to be used in subsequent pass-through operations.

Errors

On failure, pt_open returns an errno to reflect the reason for the failure.

Usage

Applications initiate pass-through access to a storage device by a call to pt_open. The handle returned by pt_open is used in subsequent calls to pt_send, which uses a SCSI command block to send SCSI commands to the device. The application then closes the storage device with a call to pt_close.

Compatibility

Application use of the open/close/ioctl pass-through mechanism is supported for compatibility with existing applications. Starting with Release 7.1, applications should use the SCSI pass-through interface documented on pt_open(3X), pt_send(3X), and pt_close(3X) to send commands to SCSI Device Interface Host Bus Adapters (HBA)s that support the SDI pass-through interface.

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

This routine is not part of any industry standard.

References

pt_close(3X), pt_send(3X), sdi(7)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004