doc/sg_readcap.8 - main - githubmirror/sg3_utils

doc/sg_readcap.8
235 строк11 KB
Douglas Gilbert
lib/sgj_haj_*() functions: tweak hex_haj argument meaning; escape hyphen in manpages
28 окт 2023, 03:02
28 окт 2023, 03:02f243992
.TH SG_READCAP "8" "June 2023" "sg3_utils\-1.48" SG3_UTILS
.SH NAME
sg_readcap \- send SCSI READ CAPACITY command
.SH SYNOPSIS
.B sg_readcap
[\fI\-\-10\fR] [\fI\-\-16\fR] [\fI\-\-brief\fR] [\fI\-\-help\fR]
[\fI\-\-hex\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-json[=JO]\fR]
[\fI\-\-js\-file=JFN\fR] [\fI\-\-lba=LBA\fR] [\fI\-\-long\fR] [\fI\-\-pmi\fR]
[\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
[\fI\-\-zbc\fR] \fIDEVICE\fR
.PP
.B sg_readcap
[\fI\-16\fR] [\fI\-b\fR] [\fI\-h\fR] [\fI\-H\fR] [\fI\-lba=LBA\fR]
[\fI\-pmi\fR] [\fI\-r\fR] [\fI\-R\fR] [\fI\-v\fR] [\fI\-V\fR] [\fI\-z\fR]
\fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
The normal action of the SCSI READ CAPACITY command is to fetch the number
of blocks (and block size) from the \fIDEVICE\fR.
.PP
The SCSI READ CAPACITY command (both 10 and 16 byte cdbs) actually yield
the block address of the last block and the block size. The number of
blocks is thus one plus the block address of the last block (as blocks
are counted origin zero (i.e. starting at block zero)). This is the source
of many "off by one" errors.
.PP
The READ CAPACITY(16) response provides additional information not found in
the READ CAPACITY(10) response. This includes protection and logical block
provisioning information, plus the number of logical blocks per physical
block. So even though the media size may not exceed what READ CAPACITY(10)
can show, it may still be useful to examine the response to READ
CAPACITY(16). Sadly there are horrible SCSI command set implementations in
the wild that crash when the READ CAPACITY(16) command is sent to them.
.PP
Device capacity is the product of the number of blocks by the block size.
This utility outputs this figure in bytes, MiB (1048576 bytes per MiB),
GB (1000000000 bytes per GB) and, if large enough, TB (1000 GB).
.PP
If sg_readcap is called without the \fI\-\-long\fR option then the 10 byte
cdb version (i.e. READ CAPACITY (10)) is sent to the \fIDEVICE\fR. If the
number of blocks in the response is reported as
0xffffffff (i.e. (2**32 \- 1) ) and the \fI\-\-hex\fR option has not been
given, then READ CAPACITY (16) is called and its response is output.
.PP
This utility supports two command line syntaxes, the preferred one is
shown first in the synopsis and explained in this section. A later section
on the old command line syntax outlines the second group of options.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
The options are arranged in alphabetical order based on the long
option name.
.TP
\fB\-\-10\fR
Use the 10 byte cdb variant of the READ CAPACITY command. This is currently
the default action of this utility. That default may change to the 16 byte
variant, especially if T10 deprecates the 10 byte variant.
.TP
\fB\-\-16\fR
Use the 16 byte cdb variant of the READ CAPACITY command. See the '\-\-long'
option.
\fB\-b\fR, \fB\-\-brief\fR
outputs two hex numbers (prefixed with '0x' and space separated)
to stdout. The first number is the maximum number of blocks on the
device (which is one plus the lba of the last accessible block). The
second number is the size in bytes of each block. If the operation fails
then "0x0 0x0" is written to stdout.
.TP
\fB\-h\fR, \fB\-\-help\fR
print out the usage message then exit.
.TP
\fB\-H\fR, \fB\-\-hex\fR
output the response to the READ CAPACITY command (either the 10 or 16 byte
cdb variant) in ASCII hexadecimal on stdout. Each line starts with a
hexadecimal address or index, starting at 0. If this option is given twice,
and ASCII rendering of the 16 bytes on each line is appended to the right
hand side of each line.
.br
If this option is given three times then 16 bytes of ASCII hexadecimal are
output in each line with no leading address nor ASCII rendering to the right.
This output is suitable for importing into a later invocation of this utility
with the file containing the hex given to the \fI\-\-inhex=FN\fR option.
When given four (or more times) this option adds a comment line (starting
with '#') describing the command that caused the output.
.TP
\fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR
where \fIFN\fR is a file name whose contents are assumed to be ASCII
hexadecimal. If \fIDEVICE\fR is also given then \fIDEVICE\fR is ignored,
a warning is issued and the utility continues, decoding the file named
\fIFN\fR. See the "HEX, BINARY AND JSON FORMATS" section in the
sg3_utils manpage for more information. If the \fI\-\-raw\fR option is
also given then the contents of \fIFN\fR are treated as binary.
.TP
\fB\-j\fR[=\fIJO\fR], \fB\-\-json\fR[=\fIJO\fR]
output is in JSON format instead of plain text form. Note that arguments
to the short and long form are themselves optional and if present start
with "=" and no whitespace is permitted around that "=".
.br
See sg3_utils_json manpage or use '?' for \fIJO\fR to get a summary.
.TP
\fB\-J\fR, \fB\-\-js\-file\fR=\fIJFN\fR
output is in JSON format and it is sent to a file named \fIJFN\fR. If that
file exists then it is truncated. By default, the JSON output is sent to
stdout.
.br
When this option is given, the \fI\-\-json[=JO]\fR option is implied and
need not be given. The \fI\-\-json[=JO]\fR option may still be needed to
set the \fIJO\fR parameter to non\-default values.
.TP
\fB\-L\fR, \fB\-\-lba\fR=\fILBA\fR
used in conjunction with \fI\-\-pmi\fR option. This variant of READ CAPACITY
will yield the last block address after \fILBA\fR prior to a delay. For a
disk, given a \fILBA\fR it yields the highest numbered block on the same
cylinder (i.e. before the heads need to move). \fILBA\fR is assumed to be
decimal unless prefixed by "0x" or it has a trailing "h". Defaults to 0.
This option was made obsolete in SBC\-3 revision 26.
.TP
\fB\-l\fR, \fB\-\-long\fR
Use the 16 byte cdb variant of the READ CAPACITY command. The default
action is to use the 10 byte cdb variant which limits the maximum
block address to (2**32 \- 2). When a 10 byte cdb READ CAPACITY command
is used on a device whose size is too large then a last block address
of 0xffffffff is returned (if the device complies with SBC\-2 or later).
.TP
\fB\-O\fR, \fB\-\-old\fR
Switch to older style options. Please use as first option.
.TP
\fB\-p\fR, \fB\-\-pmi\fR
partial medium indicator: for finding the next block address prior to
some delay (e.g. head movement). In the absence of this option, the
total number of blocks and the block size of the device are output.
Used in conjunction with the \fI\-\-lba=LBA\fR option. This option was
made obsolete in SBC\-3 revision 26.
.TP
\fB\-r\fR, \fB\-\-raw\fR
output response in binary to stdout.
.TP
\fB\-R\fR, \fB\-\-readonly\fR
open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag).
The default for READ CAPACITY(16) is to open it read\-write. The default
for READ CAPACITY(10) is to open it read\-only so this option does not
change anything for this case.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase level of verbosity. Can be used multiple times.
.TP
\fB\-V\fR, \fB\-\-version\fR
outputs version string then exits.
.TP
\fB\-z\fR, \fB\-\-zbc\fR
additionally prints out the extra ZBC field (RC_BASIS) in the READ CAPACITY
response. Using the option implicitly sets the \fI\-\-16\fR option.
.SH NOTES
The response to READ CAPACITY(16) contains a LBPRZ bit in the SBC\-3
standard (ANSI INCITS 514\-2014). There was also a LBPRZ bit with the same
meaning in the Logical block provisioning VPD page (0xb2). Then somewhat
confusingly T10 expanded the LBPRZ bit to a 3 bit field in SBC\-4 draft
revision 7, but only in the LB provisioning VPD page. The reason for the
expansion was to report a new "provisioning initialization pattern"
state (when an unmapped logical block is read). The new state has been
assigned LBPRZ=2 in the VPD page and it re\-uses LBPRZ=0 in the READ
CAPACITY(16) response. LBPRZ=1 retains the same meaning for both variants,
namely that a block of zeroes will be returned when an unmapped logical block
is read.
.SH EXIT STATUS
The exit status of sg_readcap is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH OLDER COMMAND LINE OPTIONS
The options in this section were the only ones available prior to sg3_utils
version 1.23 . Since then this utility defaults to the newer command line
options which can be overridden by using \fI\-\-old\fR (or \fI\-O\fR) as the
first option. See the ENVIRONMENT VARIABLES section for another way to
force the use of these older command line options.
.TP
\fB\-16\fR
Use the 16 byte cdb variant of the READ CAPACITY command.
Equivalent to \fI\-\-long\fR in the main description.
.TP
\fB\-b\fR
utility outputs two hex numbers (prefixed with '0x' and space separated) to
stdout. The first number is the maximum number of blocks on the device (which
is one plus the lba of the last accessible block). The second number is the
size of each block. If the operation fails then "0x0 0x0" is written to
stdout.  Equivalent to \fI\-\-brief\fR in the main description.
.TP
\fB\-h\fR
output the usage message then exit. Giving the \fI\-?\fR option also outputs
the usage message then exits.
.TP
\fB\-H\fR
output the response to the READ CAPACITY command (either the 10 or 16
byte cdb variant) in ASCII hexadecimal on stdout.
.TP
\fB\-lba\fR=\fILBA\fR
used in conjunction with \fI\-pmi\fR option. This variant of READ CAPACITY
will yield the last block address after \fILBA\fR prior to a delay.
Equivalent to \fI\-\-lba=LBA\fR in the main description.
.TP
\fB\-N\fR, \fB\-\-new\fR
Switch to the newer style options.
.TP
\fB\-pmi\fR
partial medium indicator: for finding the next block address prior to
some delay (e.g. head movement). In the absence of this switch, the
total number of blocks and the block size of the device are output.
Equivalent to \fI\-\-pmi\fR in the main description.
.TP
\fB\-r\fR
output response in binary (to stdout).
.TP
\fB\-R\fR
Equivalent to \fI\-\-readonly\fR in the main description.
.TP
\fB\-v\fR
verbose: print out cdb of issued commands prior to execution. '\-vv'
and '\-vvv' are also accepted yielding greater verbosity.
.TP
\fB\-V\fR
outputs version string then exits.
.TP
\fB\-z\fR
Equivalent to \fI\-\-zbc\fR in the main description.
.SH ENVIRONMENT VARIABLES
Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS
can be given. When it is present this utility will expect the older command
line options. So the presence of this environment variable is equivalent to
using \fI\-\-old\fR (or \fI\-O\fR) as the first command line option.
.SH AUTHORS
Written by Douglas Gilbert
.SH COPYRIGHT
Copyright \(co 1999\-2023 Douglas Gilbert
.br
This software is distributed under the GPL version 2. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_inq(sg3_utils)