SCIOCMD SCSI Adapter Device Driver ioctl Operation

Purpose

Provides a means to issue any SCSI command to a SCSI device.

Description

The SCIOCMD operation allows the caller to issue a SCSI command to a selected adapter. This command can be used by system management routines to aid in the configuration of SCSI devices.

The arg parameter for the SCIOCMD operation is the address of a sc_passthru structure, which is defined in the /usr/include/sys/scsi.h field. The sc_passthru parameter allows the caller to select which SCSI and LUN IDS to send the command.

The SCSI status byte and the adapter status bytes are returned through the sc_passthru structure. If the SCIOCMD operation returns a value of -1 and the errno global variable is set to a nonzero value, the requested operation has failed. If it happens, the caller must evaluate the returned status bytes to determine why the operation failed and what recovery actions must be taken.

If the SCIOCMD operation fails because a field in the sc_passthru structure has an invalid value, the subroutine returns a value of -1, the errno global variable is set to EINVAL, and the einval_arg field is set to the field number (starting with 1 for the version field) of the field that had an invalid value. A value of 0 for the einval_arg field indicates that no additional information is available.

The version field of the sc_passthru structure can be set to the value of SC_VERSION_2 in the /usr/include/sys/scsi.h file, and the user can provide the following fields:
  • variable_cdb_ptr is a pointer to a buffer that contains the Variable SCSI cdb.
  • variable_cdb_length determines the length of the cdb variable to which the variable_cdb_ptr field points.
On completion of the SCIOCMD ioctl request, the residual field indicates the leftover data that device did not fully satisfy for this request. On a successful completion, the residual field would indicate that the device does not have the all data that is requested or the device has less than the amount of data that is requested. On a failure completion, the user must check the status_validity field to determine whether a valid SCSI bus problem exists. In this case, the residual field would indicate the number bytes that the device failed to complete for this request.

The devinfo structure defines the maximum transfer size for the command. If an attempt is made to transfer more than the maximum transfer size, the subroutine returns a value of -1, sets the errno global variable to a value of EINVAL, and sets the einval_arg field to a value of 18.

Refer to the Small Computer System Interface (SCSI) Specification to find out the format of the request-sense data for a particular device.

Return Values

The SCIOCMD operation returns a value of 0 when successfully completed. If unsuccessful, a value of -1 is returned, and the errno global variable is set to one of the following values:
Item Description
EIO A system error occurred. Consider trying the operation several (three) times because another attempt might be successful. If an EIO error occurs and the status_validity field is set to SC_SCSI_ERROR, the scsi_status field has a valid value and must be inspected.

If the status_validity field is zero and remains so on successive trials, an unrecoverable error occurred.

If the status_validity field is SC_SCSI_ERROR and the scsi_status field contains a Check Condition status, a SCSI request sense must be issued by using the SCIOCMD ioctl to recover the sense data.
EFAULT A user process copy failed.
EINVAL The device is not opened, or the caller set a field in the sc_passthru structure to an invalid value.
EACCES The adapter is in diagnostics mode.
ENOMEM A memory request failed.
ETIMEDOUT The command timed out. Consider trying the operation several times because another attempt might be successful.
ENODEV The device is not responding.
ETIMEDOUT The operation did not complete before the timeout value was exceeded.

Files

Item Description
/dev/scsi0, /dev/scsi1, ... /dev/scsin Provides an interface for all SCSI device drivers to access SCSI devices or adapters.