sg3_utils man page on YellowDog
[printable version]
SG3_UTILS(8) SG3_UTILS SG3_UTILS(8)
NAME
sg3_utils - a package of utilities for sending SCSI commands
SYNOPSIS
sg_* [--help] [--hex] [--raw] [--verbose] [--version] [OTHER_OPTIONS]
DEVICE
DESCRIPTION
sg3_utils is a package of utilities that send SCSI commands to the
given DEVICE via a SCSI pass through interface provided by the host
operating system.
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.
SCSI draft standards can be found at http://www.t10.org . The standards
themselves can be purchased from ANSI and other standards organiza‐
tions. 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.
There are two generations of command line option usage. The newer util‐
ities (written since July 2004) use the getopt_long() function to parse
command line options. With that function, each option has two represen‐
tations: 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 DEVICE argument may appear after,
between or prior to any options.
The older utilities, such as sg_inq, had individual command line pro‐
cessing 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 with its older inter‐
face). Various options can be elided as long as it is not ambiguous
(e.g. '-vv' to increase the verbosity).
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 docu‐
ments the details.
Several sg3_utils utilities are based on the Unix dd command (e.g.
sg_dd) and share dd's rather quirky command line interface.
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. The exit status
values are:
0 success
1 syntax error. Either illegal command line options, options with
bad arguments or a combination of options that is not permitted.
2 the DEVICE 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.
3 the 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.
5 the DEVICE reports an "illegal request" with an additional sense
code other than "invalid command 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.
6 the 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 exe‐
cuted by the device. Note that unit attention conditions are
usually only reported once by a device.
9 the DEVICE reports an illegal request with an additional sense
code of "invalid command operation code" which means that it
doesn't support the requested command.
11 the DEVICE reports an aborted command. In some cases aborted
commands can be retried immediately (e.g. if the transport
aborted the command due to congestion).
15 the utility is unable to open, close or use the given DEVICE.
The given file name could be incorrect or there may be permis‐
sion problems. Adding the '-v' option may give more information.
20 the DEVICE 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.
21 the DEVICE 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 .
33 the command sent to DEVICE has timed out.
97 the response to a SCSI command failed sanity checks.
98 the DEVICE reports it has a check condition but the error
doesn't fit into any of the above categories.
99 any errors that can't be categorized into values 1 to 98 may
yield this value. This includes transport and operating system
errors after the command has been sent to the device.
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 information.
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).
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).
-h, -?, --help
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.
-H, --hex
for SCSI commands that yield a non-trivial response, print out
that response in ASCII hexadecimal.
-r, --raw
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 com‐
mand, use this option to provide that data or indicate that it
can be read from stdin.
-v, --verbose
increase the level of verbosity, (i.e. debug output). Can be
used multiple times to further increase verbosity. The addi‐
tional output is usually sent to stderr.
-V, --version
print the version string and then exit. Each utility has its own
version number and date of last code change.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 1999-2007 Douglas Gilbert
Some utilities are distributed under a GPL version 2 license while oth‐
ers, usually more recent ones, are under a FreeBSD license. The files
that are common to almost all utilities and thus contain the most reus‐
able 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.
SEE ALSO
sdparm(sdparm)
sg3_utils-1.25 July 2007 SG3_UTILS(8)
[top]
List of man pages available for YellowDog
Copyright (c) for man pages and the logo by the respective OS vendor.
For those who want to learn more, the polarhome community provides shell access and support.
[legal]
[privacy]
[GNU]
[policy]
[cookies]
[netiquette]
[sponsors]
[FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
|
|
Vote for polarhome
|
