diff options
Diffstat (limited to 'sg3_utils.8')
| -rw-r--r-- | sg3_utils.8 | 175 |
1 files changed, 97 insertions, 78 deletions
diff --git a/sg3_utils.8 b/sg3_utils.8 index 4ba9749b..2a60c35a 100644 --- a/sg3_utils.8 +++ b/sg3_utils.8 @@ -1,57 +1,64 @@ -.TH SG3_UTILS "8" "October 2006" "sg3_utils-1.22" SG3_UTILS +.TH SG3_UTILS "8" "Jamuary 2007" "sg3_utils\-1.23" SG3_UTILS .SH NAME sg3_utils \- a package of utilities for sending SCSI commands .SH SYNOPSIS .B sg_* -[\fI--help\fR] [\fI--verbose\fR] [\fI--version\fR] -\fI<scsi_device>\fR +[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-raw\fR] [\fI\-\-verbose\fR] +[\fI\-\-version\fR] [\fIOTHER_OPTIONS\fR] \fIDEVICE\fR .SH DESCRIPTION .\" Add any additional description here .PP -sg3_utils is a package of utilities that send SCSI commands to -the given <scsi_device> via a SCSI pass through interface -provided by the host operating system. +sg3_utils is a package of utilities that send SCSI commands to the given +\fIDEVICE\fR via a SCSI pass through interface provided by the host +operating system. .PP -The names of all utilities start with "sg" and most start with "sg_" -often followed by the abbreviation of the name of the SCSI command -that they send. For example the "sg_verify" utility sends the SCSI -VERIFY command. A mapping between SCSI commands and the sg3_utils -utilities that issue them is given in the COVERAGE file. +The names of all utilities start with "sg" and most start with "sg_" often +followed by the name or a shortening of the name of the SCSI command that +they send. For example the "sg_verify" utility sends the SCSI VERIFY +command. A mapping between SCSI commands and the sg3_utils utilities that +issue them is shown in the COVERAGE file. .PP -SCSI draft standards can be found at http://www.t10.org . The -standards themselves can be purchased from ANSI and other -standards organizations. A good overview of various SCSI -standards can be seen at http://www.t10.org/scsi-3.htm with the -SCSI command sets in the upper part of the diagram. SCSI commands -in common with all device types can be found in SPC of which SPC-4 -is the latest major version. Block device specific commands (e.g. -as used by disks) can be in SBC, those for tape drives in SSC -and those for CD/DVD drives in MMC. +SCSI draft standards can be found at http://www.t10.org . The standards +themselves can be purchased from ANSI and other standards organizations. +A good overview of various SCSI standards can be seen in +http://www.t10.org/scsi\-3.htm with the SCSI command sets in the upper part +of the diagram. SCSI commands in common with all device types can be found +in SPC of which SPC\-4 is the latest major version. Block device specific +commands (e.g. as used by disks) are in SBC, those for tape drives in +SSC and those for CD/DVD drives in MMC. .PP -There are two generations of command line option usage. The older utilities -such as sg_inq have individual command line processing code (often -found at the top of the main() function) based on a single "-" followed -by one or more characters. If an argument is needed then it follows -a "=" (e.g. '-p=1f' in sg_modes). Various options can be elided as long -as it is not ambiguous (e.g. '-vv' to increase the verbosity). The -<scsi_device> is any device that can receive SCSI commands and is shown -after the options in the synopsis. It may appear between other options. +There are two generations of command line option usage. The newer +utilities (written since July 2004) use the getopt_long() function to parse +command line options. With that function, each option has two representations: +a short form (e.g. '\-v') and a longer form (e.g. '\-\-verbose'). If an +argument is required then it follows a space (optionally) in the short form +and a "=" in the longer form (e.g. in the sg_verify utility '\-l 2a6h' +and '\-\-lba=2a6h' are equivalent). Note that with getopt_long(), short form +options can be elided, for example: '\-all' is equivalent to '\-a \-l \-l'. +The \fIDEVICE\fR argument may appear after, between or prior to any options. .PP -The second generation of newer utilities uses the getopt_long() function -to parse command line options. With that function, each option has two -representations: a short form (e.g. '-v') and a longer -form (e.g. '--verbose'). If an argument is required then it follows a -space in the short form and a "=" in the longer form (e.g. in the -sg_verify utility '-l 2a6h' and '--lba=2a6h' are equivalent). Again -the <scsi_device> argument may appear between or prior to other options. +The older utilities, such as sg_inq, had individual command line processing +code (often found at the top of the main() function) based on a single "\-" +followed by one or more characters. If an argument is needed then it follows +a "=" (e.g. '\-p=1f' in sg_modes). Various options can be elided as long as +it is not ambiguous (e.g. '\-vv' to increase the verbosity). +.PP +Over time the command line interface of these older utilities became messy +and overloaded with options. So in sg3_utils version 1.23 the command line +interface of these older utilities was altered to have both a cleaner +getopt_long() interface and their older interface for backward compatibility. +By default these older utilities use their getopt_long() based interface. +That can be overridden by defining the SG3_UTILS_OLD_OPTS environment +variable or using '\-O' or '\-\-old' as the first command line option. The +man pages of the older utilities documents the details. .PP Several sg3_utils utilities are based on the Unix dd command (e.g. sg_dd) -and share its rather quirky command line interface. +and share dd's rather quirky command line interface. .SH EXIT STATUS -To aid scripts that call these utilities, the exit status is set to -indicate success (0) or failure (1 or more). Note that some of the -lower values correspond to the SCSI sense key values to which they -correspond. The exit status values are: +To aid scripts that call these utilities, the exit status is set to indicate +success (0) or failure (1 or more). Note that some of the lower values +correspond to the SCSI sense key values to which they correspond. The exit +status values are: .TP .B 0 success @@ -61,64 +68,62 @@ syntax error. Either illegal command line options, options with bad arguments or a combination of options that is not permitted. .TP .B 2 -the <scsi_device> reports that it is not ready for the operation +the \fIDEVICE\fR reports that it is not ready for the operation requested. The device may be in the process of becoming ready (e.g. spinning up but not at speed) so the utility may work after a wait. .TP .B 3 -the <scsi_device> reports a medium or hardware error (or a blank -check). For example an attempt to read a corrupted block on a disk -will yield this value. +the \fIDEVICE\fR reports a medium or hardware error (or a blank check). For +example an attempt to read a corrupted block on a disk will yield this value. .TP .B 5 -the <scsi_device> reports an "illegal request" with an additional -sense code other than "invalid operation code". This is often a -supported command with a field set requesting an unsupported -capability. For commands that require a "service action" field -this value can indicate that the command is not supported. +the \fIDEVICE\fR reports an "illegal request" with an additional sense code +other than "invalid operation code". This is often a supported command with +a field set requesting an unsupported capability. For commands that require +a "service action" field this value can indicate that the command with that +service action value is not supported. .TP .B 6 -the <scsi_device> reports a "unit attention" condition. This usually -indicates that something unrelated to the requested command has -occurred (e.g. a device reset) potentially before the current SCSI -command was sent. The requested command has not been executed by the -device. Note that unit attention conditions are usually only reported -once by a device. +the \fIDEVICE\fR reports a "unit attention" condition. This usually indicates +that something unrelated to the requested command has occurred (e.g. a device +reset) potentially before the current SCSI command was sent. The requested +command has not been executed by the device. Note that unit attention +conditions are usually only reported once by a device. .TP .B 9 -the <scsi_device> reports an illegal request with an additional -sense code of "invalid operation code" which means that it doesn't -support the requested command. +the \fIDEVICE\fR reports an illegal request with an additional sense code +of "invalid operation code" which means that it doesn't support the +requested command. .TP .B 11 -the <scsi_device> reports an aborted command. In some cases aborted +the \fIDEVICE\fR reports an aborted command. In some cases aborted commands can be retried immediately (e.g. if the transport aborted the command due to congestion). .TP .B 15 -the utility is unable to open, close or use the given <scsi_device>. +the utility is unable to open, close or use the given \fIDEVICE\fR. The given file name could be incorrect or there may be permission -problems. Adding the '-v' option may give more information. +problems. Adding the '\-v' option may give more information. .TP .B 20 -the <scsi_device> reports it has a check condition but "no sense" -and non-zero information in its additional sense codes. Some polling +the \fIDEVICE\fR reports it has a check condition but "no sense" +and non\-zero information in its additional sense codes. Some polling commands (e.g. REQUEST SENSE) can receive this response. .TP .B 21 -the <scsi_device> reports a "recovered error". The requested command +the \fIDEVICE\fR reports a "recovered error". The requested command was successful. Most likely a utility will report a recovered error to stderr and continue, probably leaving the utility with an exit status of 0 . .TP .B 33 -the command sent to <scsi_device> has timed out. +the command sent to \fIDEVICE\fR has timed out. .TP .B 97 the response to a SCSI command failed sanity checks. .TP .B 98 -the <scsi_device> reports it has a check condition but the error +the \fIDEVICE\fR reports it has a check condition but the error doesn't fit into any of the above categories. .TP .B 99 @@ -128,37 +133,51 @@ after the command has been sent to the device. .PP Most of the error conditions reported above will be repeatable (an example of one that is not is "unit attention") so the utility can -be run again with the '-v' option (or several) to obtain more +be run again with the '\-v' option (or several) to obtain more information. .SH COMMON OPTIONS +Arguments to long options are mandatory for short options as well. In the +short form an argument to an option uses zero or more spaces as a +separator (i.e. the short form does not use "=" as a separator). +.PP +If an option takes a numeric argument then that argument is assumed to +be decimal unless otherwise indicated (e.g. with a leading "0x", a +trailing "h" or as noted in the usage message). .TP ---help | -h | -? -output the usage message then exit. In a few older utilities the '-h' -option requests hexadecimal output. In these cases the '-?' option will +\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR +output the usage message then exit. In a few older utilities the '\-h' +option requests hexadecimal output. In these cases the '\-?' option will output the usage message then exit. .TP ---verbose | -v +\fB\-H\fR, \fB\-\-hex\fR +for SCSI commands that yield a non\-trivial response, print out that +response in ASCII hexadecimal. +.TP +\fB\-r\fR, \fB\-\-raw\fR +for SCSI commands that yield a non\-trivial response, output that response +in binary to stdout. If any error messages or warning are produced they are +usually sent to stderr. Some utilities that consume data to send to the +device along with the SCSI command, use this option to provide that data +or indicate that it can be read from stdin. +.TP +\fB\-v\fR, \fB\-\-verbose\fR increase the level of verbosity, (i.e. debug output). Can be used multiple times to further increase verbosity. The additional output is usually sent to stderr. .TP ---version | -V +\fB\-V\fR, \fB\-\-version\fR print the version string and then exit. Each utility has its own version number and date of last code change. -.PP -Notice that the '--verbose' option can be used multiple times for more -verbose output. Obviously the short form ('-vv') is more convenient than -the longer form ('--verbose --verbose'). .SH AUTHORS Written by Douglas Gilbert. .SH "REPORTING BUGS" Report bugs to <dgilbert at interlog dot com>. .SH COPYRIGHT -Copyright \(co 1999-2006 Douglas Gilbert +Copyright \(co 1999\-2007 Douglas Gilbert .br Some utilities are distributed under a GPL version 2 license while others, usually more recent ones, are under a FreeBSD license. The files -that are common to almost all utilities and thus have the most reusable +that are common to almost all utilities and thus contain the most reusable code, namely sg_lib.[hc], sg_cmds_basic.[hc] and sg_cmds_extra.[hc] are under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |