SCIOEVENT (Event) SCSI Adapter Device Driver ioctl Operation

Purpose

Registers the selected SCSI device instance to receive asynchronous event notification.

Description

The SCIOEVENT operation registers the selected initiator or target-mode device for receiving asynchronous event notification. Only kernel mode processes or device drivers can call this function. If a user-mode process attempts an SCIOEVENT operation, the ioctl command is unsuccessful and the errno global value is set to EPERM.

The arg parameter to the SCIOEVENT operation should be set to the address of an sc_event_struct structure, which is in the /usr/include/sys/scsi.h file. If this is a target-mode instance, the SCIOSTARTTGT operation was used to open the device session; the caller then fills in the ID field with the SCSI ID of the SCSI initiator and sets the logical unit number (LUN) field to a value of 0. If this is an initiator-mode instance, the SCIOSTART operation was used to open the device session; the ID field is then set to the SCSI ID of the SCSI target, and the LUN is set to the LUN ID of the SCSI target. The device must have been previously opened using one of the start ioctls for this operation to succeed. If the device session is not opened, the ioctl command is unsuccessful and the returned errno global value is set to EINVAL.

The event registration performed by this ioctl is only allowed once per device session; only the first SCIOEVENT operation is accepted after the device is opened. Succeeding SCIOEVENT operations are unsuccessful, and the errno global value is set to EINVAL. The event registration is cancelled automatically when the device session is closed.

The caller fills in the mode field with one of the following values, which are defined in the /usr/include/sys/scsi.h file:

#define SC_IM_MODE   /* this is an initiator mode device */

#define SC_TM_MODE   /* this is a target mode device     */

The async_func field is filled in with the address of a pinned routine (in the calling program) that should be called by the SCSI adapter device driver whenever asynchronous event status is available for a registered device. The struct sc_event_info structure, defined in the /usr/include/sys/scsi.h file, is passed by address to the caller's async_func routine.

The async_correlator field can optionally be used by the caller to provide an efficient means of associating event information with the appropriate device. This field is saved by the SCSI adapter device driver and is returned, unchanged, with information passed back to the caller's async_func routine.

Reserved fields must be set to 0 by the caller.

Return Values

When completed successfully, this operation returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to one of the following values:

Files