sg_readcap - send SCSI READ CAPACITY command
sg_readcap [--16] [--brief] [--help] [--hex] [--lba=LBA] [--long] [--pmi] [--raw] [--readonly] [--verbose] [--version] [--zbc] DEVICE sg_readcap [-16] [-b] [-h] [-H] [-lba=LBA] [-pmi] [-r] [-R] [-v] [-V] [-z] DEVICE
SG_READCAP(8) SG3_UTILS SG_READCAP(8)
NAME
sg_readcap - send SCSI READ CAPACITY command
SYNOPSIS
sg_readcap [--16] [--brief] [--help] [--hex] [--lba=LBA] [--long]
[--pmi] [--raw] [--readonly] [--verbose] [--version] [--zbc] DEVICE
sg_readcap [-16] [-b] [-h] [-H] [-lba=LBA] [-pmi] [-r] [-R] [-v] [-V]
[-z] DEVICE
DESCRIPTION
The normal action of the SCSI READ CAPACITY command is to fetch the
number of blocks (and block size) from the DEVICE.
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 num-
ber 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.
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.
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).
If sg_readcap is called without the --long option then the 10 byte cdb
version (i.e. READ CAPACITY (10)) is sent to the DEVICE. If the number
of blocks in the response is reported as 0xffffffff (i.e. (2**32 - 1) )
and the --hex option has not been given, then READ CAPACITY (16) is
called and its response is output.
This utility supports two command line syntaxes, the preferred one is
shown first in the synopsis and explained in this section. A later sec-
tion on the old command line syntax outlines the second group of
options.
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.
--16 Use the 16 byte cdb variant of the READ CAPACITY command. See
the '--long' option. -b, --brief outputs two hex numbers (pre-
fixed 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.
-h, --help
print out the usage message then exit.
-H, --hex
output the response to the READ CAPACITY command (either the 10
or 16 byte cdb variant) in ASCII hexadecimal on stdout.
-L, --lba=LBA
used in conjunction with --pmi option. This variant of READ
CAPACITY will yield the last block address after LBA prior to a
delay. For a disk, given a LBA it yields the highest numbered
block on the same cylinder (i.e. before the heads need to move).
LBA 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.
-l, --long
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).
-O, --old
Switch to older style options. Please use as first option.
-p, --pmi
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 --lba=LBA
option. This option was made obsolete in SBC-3 revision 26.
-r, --raw
output response in binary to stdout.
-R, --readonly
open the DEVICE 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.
-v, --verbose
increase level of verbosity. Can be used multiple times.
-V, --version
outputs version string then exits.
-z, --zbc
additionally prints out the extra ZBC field (RC_BASIS) in the
READ CAPACITY response. Using the option implicitly sets the
--16 option.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | system/storage/sg3_utils |
+---------------+--------------------------+
|Stability | Pass-through uncommitted |
+---------------+--------------------------+
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 initializa-
tion 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.
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://sg.danny.cz/sg/p/sg3_utils-1.46.tgz.
Further information about this software can be found on the open source
community website at http://sg.danny.cz/sg/sg3_utils.html.
EXIT STATUS
The exit status of sg_readcap is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
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 --old (or -O) as
the first option. See the ENVIRONMENT VARIABLES section for another way
to force the use of these older command line options.
-16 Use the 16 byte cdb variant of the READ CAPACITY command.
Equivalent to --long in the main description.
-b 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 --brief in the main description.
-h output the usage message then exit. Giving the -? option also
outputs the usage message then exits.
-H output the response to the READ CAPACITY command (either the 10
or 16 byte cdb variant) in ASCII hexadecimal on stdout.
-lba=LBA
used in conjunction with -pmi option. This variant of READ
CAPACITY will yield the last block address after LBA prior to a
delay. Equivalent to --lba=LBA in the main description.
-N, --new
Switch to the newer style options.
-pmi 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 --pmi in the main description.
-r output response in binary (to stdout).
-R Equivalent to --readonly in the main description.
-v verbose: print out cdb of issued commands prior to execution.
'-vv' and '-vvv' are also accepted yielding greater verbosity.
-V outputs version string then exits.
-R Equivalent to --zbc in the main description.
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 environ-
ment variable is equivalent to using --old (or -O) as the first command
line option.
AUTHORS
Written by Douglas Gilbert
COPYRIGHT
Copyright (C) 1999-2020 Douglas Gilbert
This software is distributed under the GPL version 2. There is NO war-
ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
POSE.
SEE ALSO
sg_inq(sg3_utils)
sg3_utils-1.45 January 2020 SG_READCAP(8)