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