SG_READCAP(8)

📦

version 1.49 · 4 versions

1.49 · arch rolling, nixpkgs unstable (latest)
1.48~20221101+8.02dda5f · centos-stream 9, opensuse-leap 16.0
1.46 · debian bookworm, ubuntu jammy, ubuntu noble
1.48 · alpine 3.24, centos-stream 10, debian trixie, fedora 43, fedora 44, nixos 26.05, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 sg_readcap(8) 💖

okay so welcome to the SG3_UTILS manual page for sg_readcap, bestie. it's a whole thing about the SCSI READ CAPACITY command and i'm gonna walk you through every single bit of it, no cap. grab a snack. 🍓

✨ NAME ✨

sg_readcap — sends the SCSI READ CAPACITY command. that's it, that's the whole job, and it does it iconically. 💅

🦋 SYNOPSIS 🦋

the preferred glow-up syntax:

sg_readcap [--10] [--16] [--brief] [--help] [--hex] [--inhex=FN]
[--json[=JO]] [--js-file=JFN] [--lba=LBA] [--long] [--pmi] [--raw]
[--readonly] [--verbose] [--version] [--zbc] DEVICE

and the vintage, pre-loved syntax:

sg_readcap [-16] [-b] [-h] [-H] [-lba=LBA] [-pmi] [-r] [-R] [-v] [-V]
[-z] DEVICE

🌸 DESCRIPTION 🌸

so like, the normal everyday action of the SCSI READ CAPACITY command is literally just fetching the number of blocks (and the block size) from the DEVICE. simple. chic. 🎀

but here's the plot twist: the SCSI READ CAPACITY command (both the 10 and 16 byte cdbs) actually hands you the block address of the last block plus the block size. so the number of blocks is one plus the block address of the last block — because blocks are counted origin zero (i.e. starting at block zero). this is the source of so many "off by one" errors, honestly it's giving chaos. 😭

the READ CAPACITY(16) response serves up extra info that the READ CAPACITY(10) response simply does not have. we're talking 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 peek at the READ CAPACITY(16) response. sadly — and i cannot stress this enough — there are horrible SCSI command set implementations in the wild that straight up crash when the READ CAPACITY(16) command is sent to them. 💀

device capacity = number of blocks × block size. this utility outputs that figure in bytes, in MiB (1048576 bytes per MiB), in GB (1000000000 bytes per GB) and, if it's large enough, in TB (1000 GB). slay.

if sg_readcap is called without the --long option then the 10 byte cdb version (i.e. READ CAPACITY (10)) gets sent to the DEVICE. if the number of blocks in the response comes back 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 what you get. ✨

this utility supports two command line syntaxes, bestie. 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. iykyk. 🫶

🔥 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 — organised queen behaviour. 👑

--10 — use the 10 byte cdb variant of the READ CAPACITY command. this is currently the default action of this utility. heads up tho: that default may change to the 16 byte variant, especially if T10 deprecates the 10 byte variant. 🙈
--16 — use the 16 byte cdb variant of the READ CAPACITY command. see the --long option.
-b, --brief — 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. short, sweet, iconic.
-h, --help — print out the usage message then exit. classic.
-H, --hex — 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, an ASCII rendering of the 16 bytes on each line is appended to the right hand side of each line. 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 --inhex=FN option. when given four (or more times) this option adds a comment line (starting with '#') describing the command that caused the output. the way it just keeps escalating?? obsessed. 💅
-i, --inhex=FN — where FN is a file name whose contents are assumed to be ASCII hexadecimal. if DEVICE is also given then DEVICE is ignored, a warning is issued and the utility continues, decoding the file named FN. see the "HEX, BINARY AND JSON FORMATS" section in the sg3_utils manpage for more information. if the --raw option is also given then the contents of FN are treated as binary.
-j[=JO], --json[=JO] — 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 "=". see the sg3_utils_json manpage or use '?' for JO to get a summary.
-J, --js-file=JFN — output is in JSON format and it is sent to a file named JFN. if that file exists then it is truncated. by default, the JSON output is sent to stdout. when this option is given, the --json[=JO] option is implied and need not be given. the --json[=JO] option may still be needed to set the JO parameter to non-default values. main character file output energy. 👑
-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. nice try tho. 😌
-v, --verbose — increase level of verbosity. can be used multiple times. go off, stack them.
-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.

🧚 NOTES 🧚

okay this part is a little lore-heavy but stay with me. 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. literally the plot of a drama. 😭

⭐ EXIT STATUS ⭐

the exit status of sg_readcap is 0 when it is successful. otherwise see the sg3_utils(8) man page. simple as that, bestie.

🌈 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. vintage era, but make it functional. 🎀

-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. the way it just keeps going. 🔥
-V — outputs version string then exits.
-z — 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 environment variable is equivalent to using --old (or -O) as the first command line option. it's giving time travel. 🦋

💜 AUTHORS 💜

written by Douglas Gilbert. we stan. 👑

🎀 COPYRIGHT 🎀

this software is distributed under the GPL version 2. there is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. (that's the serious bit, please actually read it. 🙈)

🌸 SEE ALSO 🌸

sg_inq(sg3_utils)

okay bestie that's the whole page, every last flag and caveat intact, nothing skipped, no invented lore. this was sg3_utils-1.48, dated June 2023, page SG_READCAP(8) — periodt. 💅✨🦋

📦 where this page comes from

arch rolling: sg3_utils 1.49-1 · GPL-2.0-or-later AND BSD-2-Clause
nixpkgs unstable: sg3_utils 1.49
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms