Name

scu − SCSI CAM Utility Program

Syntax

/usr/etc/scu [ -f device-name-path ] [ command [ keywords ...  ] ]
 

Options

−fSpecifies the raw device pathname.  You must specify a character device special file, for example, /dev/rrz3c.

Description

The SCSI utility program, scu, interfaces with the CAM I/O subsystem and the peripherals attached to the SCSI buses.  This utility implements the SCSI commands necessary for normal maintenance and diagnostics of SCSI peripherals and the CAM I/O subsystem.

If the raw device pathname (the −f option) is not specified on the command line, the program checks the environment variable SCU_DEVICE to define the device name. 

The following conventions are used in describing scu utility syntax:

The address-format is an optional parameter available for use with most CDROM Show Audio commands that specify the address format of information returned by the drive.

The possible address formats are:

The syntax of a command using the address-format parameter follows:

scu> command [ address-format { lba | msf } ]

The nexus-information parameter lets users specify values to override the bus, target, and LUN values normally taken from the selected SCSI device. The nexus-information keywords are:

You specify the test-parameters convention for a command using the following syntax:

scu> command [ media-limits ] [ test-control ]

The media-limits parameter controls the device media being tested. The syntax of a command using the media-limits parameter follows:

           { lba n }       { length n  }
scu> command [ { starting n } ] [ { ending n  } ] [ size n ]
                                              { limit  n  }
                                              { records n }

The lba keyword specifies the starting logical block address.  The combination of the starting and ending keywords specifies a range of logical block addresses.  The size keyword specifies the block size in bytes.  The limit keyword specifies the transfer size in logical blocks.  The records keyword specifies the transfer size in terms of the value specified by the size keyword. You can use the alias bs, block size, for size.

The test-control parameter controls the device media being tested. The syntax of a command using the test-control parameter follows:

            { align Align-Offset }
                       { compare { on | off } }
scu> command [ { errors Error-Limit }  ]
                       { passes Pass-Limit }
                       { pattern Data-Pattern }
                       { recovery { on | off } }

An expression is accepted for test-parameters that accept numeric values. The characters accepted as test-parameters values in expressions are:

The following conditions apply to the characters used in expressions:

If value is omitted, the value defaults to one.

Both upper and lower case characters are accepted. 

Spaces and tabs are ignored between operands. 

Expressions are evaluated from right to left without precedence. 

Parentheses grouping is not supported. 

Command Summary

If a command is not entered on the command line, the program prompts for commands until you terminate the program.  Commands and keywords can be abbreviated to the least ambiguous number of characters. 

allow This command allows media removal from the selected device. 

change pages [ mode-page [ pcf page-control-field ] ]
This command changes mode pages for a device.  The program prompts you with those page fields that are marked changeable.  If the mode-page keyword is omitted, all pages supported by the device are requested for changing.  After fields of each page have been entered, the new page parameters are set using a SCSI Mode Select command.

eject This command is used with CDROMs to stop play and eject the caddy. 

exit This command is used to exit the program.  You can use quit as an alias for exit. The program can also be terminated in interactive mode, by entering the end of file character (usually CTRL/D).  The program also exits if the interrupt character (usually CTRL/C) is typed when a command is not currently active.

evaluate expression
This command evaluates the expression and displays values in decimal, hexadecimal, blocks, kilobytes, megabytes, and gigabytes.  The expression accepted is the same as the one described for test-parameter values. The output displayed depends on the setting of the verbose display flag.

format [ density density-type ] [ defects defect-list ]
This command is used to format both hard and flexible disk media. Since this command modifies the disk media, the full command name must be entered to be recognized.

help [ topic ]
This command displays help on topics.  You can use a question mark, ?, as an alias.

mt command [ count ]
This command issues one of the supported mtcommands. mt commands that do not require additional driver information have been implemented.

pause This command is used to pause the playing of a CDROM audio disc. 

play [ keywords ... ]
This command is used to play audio tracks on a CDROM audio disc. If keywords are omitted, all audio tracks are played by default.

prevent This command prevents media removal from the selected device. 

read { media [ test-parameters ] }
This command performs read operations from the selected device.

reassign lba logical-block
This command reassigns a defective block on a disk device.  Since this command modifies the disk media, the full command name must be entered to be recognized.

release { device | simqueue } [ nexus-information ]
This command releases a reserved SCSI device or releases a frozen SIM queue (which occurs after an error).

reserve device
This command issues a SCSI Reserve command to the selected device. The entire logical unit is reserved for the exclusive use of the initiator. Extent reservation for direct access devices is not implemented.

resume This command is used with CDROMs to resume play after being paused. 

reset { bus | device } [ nexus-information ]
The command is used to reset the SCSI bus or the selected SCSI device.

scan { edt [ [nexus-information] [ report-format ] ] } { media [ test-parameters ] }
This command is used to scan device media or the CAM Equipment Device Table (EDT).

set [ parameters ... ]
This command is used to set parameters for a device or the program.

show [ parameters ... ]
This command is used to display parameters for a device or the program.

source input-file
This command allows you to source input from an external command file. If any errors occur during command parsing or execution, then the command file is closed at that point.

start This command issues a SCSI Start Unit command to the selected device.  This enables the selected device to allow media access operations. 

stop This command issues a SCSI Stop Unit command to the selected device.  This disables the selected device from allowing media access operations. 

switch [ device-name ]
This command switches to another device or to a previous device.  If the device name is omitted, this command acts as a toggle and simply switches to the previous device (if one exists).  Otherwise, the device specified is validated and if successful, it becomes the active device.

test [ controller | drive | memory | selftest ]
This command performs tests on a controller.  This involves issuing send and receive diagnostic commands or write and read buffer commands (for memory test) to the selected device.  The default is to perform the self test that is supported by most controllers.

tur This command issues a SCSI Test Unit Ready command to determine whether a device is ready.  On failures, the sense data is automatically reported. 

verify { media [ test-parameters ] }
This command performs verify operations on the selected device.

write { media [ test-parameters ] }
This command performs write operations to the selected device.

Return Values

For all commands, scu runs and exits with 0 for success, 1 for warning, or -1 for failure status.

Restrictions

Commands that modify device data or device parameters require write access to the device entry.  Applications that change the volume level of the CDROM must open the device for write access since a SCSI Mode Select command is used to modify the volume level. 

Examples

To format an RX26 diskette at extra density, enter:

scu> format density ED

To verify 1024 blocks starting at block 1000, enter:

scu> verify media starting 1000 length 1024

To display all changeable mode pages for a device, enter:

scu> show page error pcf changeable

To display inquiry information for all devices on the first SCSI bus at lun 0 in the Equipment Device Table (EDT), enter:

scu> show edt bus 0 lun 0 full

To reassign logical block address ???, enter:

scu> reassign lba ???

Errors

When a SCSI device error occurs, both the sense key and the addition sense code or qualifier are decoded and displayed as follows:

scu: Sense Key = 0x5 = ILLEGAL REQUEST - Illegal request or CDB parameter,
     Sense Code/Qualifier = (0x20, 0) = Invalid command operation code

This error indicates that you have issued a command that is not supported by the selected device.  This can happen for optional commands that are not supported by all devices. 

If the character special device /dev/cam doesn’t exist, the scu utility displays the following error message:

scu: Unable to open device ’/dev/cam’, ENOENT (2) - No such file or device

In this case, you need to create /dev/cam as follows:

# mknod /dev/cam c 95 0
# chmod 600 /dev/cam

Files

/usr/etc/scu
The SCSI Utility executable file.

/dev/cam
The device entry for the CAM User Agent driver.

/usr/etc/scu.hlp
Contains the scu help information.

See Also

Commands:  file(1), more(1). 

Functions:  open(2), close(2), ioctl(2), fopen(3), fgets(3), fputs(3), popen(3), pclose(3), malloc(3), printf(3), fprintf(3). 

American National Standard for Information Systems, Small Computer Systems Interface - 2 (SCSI - 2), X3.131-199X

American National Standard for Information Systems, SCSI-2 Common Access Method: Transport and SCSI Interface Module, working draft, X3T9.2/90-186