Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

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

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)