SG_REP_ZONES(8)

📦
version 1.49 · 5 versions
, in arch rolling, nixpkgs unstable

🦋 sg_rep_zones(8) — the sg3_utils era 💅

okay bestie, so this is sg_rep_zones from sg3_utils, and it's literally the utility that asks your SCSI device "hey, tell me about your zones" ✨. Sit down, hydrate, we're decoding some CDs — not the music kind 💀

✨ SYNOPSIS ✨

sg_rep_zones [--brief] [--domain] [--find=ZT] [--force] [--help] [--hex]
[--inhex=FN] [--json[=JO]] [--js-file=JFN] [--locator=LBA]
[--maxlen=LEN] [--num=NUM] [--partial] [--raw] [--readonly] [--realm]
[--report=OPT] [--start=LBA] [--statistics] [--verbose] [--version]
[--wp] DEVICE

🌸 DESCRIPTION 🌸

So basically this sends a SCSI REPORT ZONES, REPORT REALMS, or REPORT ZONE DOMAINS command to DEVICE and then decodes the data that comes back — or just spits it out raw if that's your vibe 🫶.

These commands live in the ZBC-2 draft standard, revision 12 (zbc2r12.pdf). Only REPORT ZONES is actually defined in the original ZBC standard (INCITS 536-2017) and that one is the default for this utility, no cap.

Here's the tea on switching commands:

  • give the --domain option → the REPORT ZONE DOMAINS command gets sent (and decoded) 🔥
  • give the --realm option → the REPORT REALMS command gets sent (and decoded) 👑

And listen — you don't even have to talk to a real device 🫣. If you hand it the --inhex=FN option, then instead of sending a SCSI command to DEVICE, the contents of the file named FN are decoded as ASCII hex (or as binary if --raw is also given) and then processed as if it was the response of the command. By default it assumes the REPORT ZONES response; if you give --domain or --realm then the corresponding command's response is assumed instead. iykyk 💅

💖 OPTIONS 💖

Quick heads up first: arguments to long options are mandatory for short options as well. Like, you don't get to skip them, bestie 🌈

  • -b, --brief — even though a ZBC disk will typically limit the size of the response to the REPORT ZONES command (e.g. due to the "allocation length" field), this may still be potentially a lot of output 😭. This option will only decode and output fields found in the response header plus fields from the last descriptor in the current response. Short and sweet, periodt.
  • -d, --domain — send or decode the SCSI REPORT ZONE DOMAINS command 🦋
  • -F, --find=ZT — where ZT is a zone type number or an abbreviation for a zone type. If ZT is prefixed by either - or ! then the check for equality is inverted to be a check for inequality. IOWs it does a: find the first occurrence that is not the given zone type 🙈.

The algorithm used by this option takes into account the --hex, --maxlen=LEN, --num=NUM, --report=OPT and --start=LBA options, if given, and ignores other options. It is only implemented for the Report zones command currently. The algorithm may call the Report zones command repeatedly, with the PARTIAL bit set and the Zone start LBA field being increased as it goes. This continues until either there is a match on the ZT condition, --num=NUM is exhausted or the number of zones is exhausted.

The ZT numbers and abbreviations are listed when the --help option is given twice.

⚠️ Warning, bestie: using ! for inverting the condition may not be so practical as the shell (e.g. bash) may interpret ! as having special meaning. Placing single quotes around ZT fixes the problem for the bash shell (e.g. --find='!c' meaning find the first zone whose type is not conventional). The way that single quote saves you is iconic honestly 💀
  • -f, --force — when decoding the response to this command, certain sanity checks are done and if they fail a message is sent to stderr and a non-zero exit status is set 😬. If this option is given, those sanity checks are bypassed. Use wisely, not recklessly 🫶
  • -h, --help — output the usage message then exit. When given twice, additional usage information is output 👑 (yes, double the help, double the slay)
  • -H, --hex — output the response in hexadecimal to stdout. The levels are giving main character energy:
    • used once → the whole response is output in ASCII hexadecimal with a leading address (starting at 0) on each line ✨
    • used twice → each zone descriptor in the response is output separately in hexadecimal 🎀
    • used thrice → the whole response is output in hexadecimal with no leading address (on each line) 💅

When this option is used twice, it can be useful with either the --brief or --find=ZT option to only output the header and zone descriptor in hex that those two options would otherwise print in ASCII in the absence of the --hex option.

The output format when this option is given thrice is suitable for a later invocation with the --inhex=FN option. Cute little round trip, love that for us 🌀

  • -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.

Note that by default this utility assumes the contents are the response from a REPORT ZONES command. Use the --domain or --realm option for decoding the other two commands, k? 💖

  • -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 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 🌟

  • -l, --locator=LBA — where LBA plays a similar role as it does in --start=LBA. It is the field name used in the REPORT REALMS and REPORT ZONE DOMAINS commands 🎯
  • -m, --maxlen=LEN — where LEN is the (maximum) response length in bytes. It is placed in the cdb's "allocation length" field. If not given (or LEN is zero) then 16384 is used. The maximum allowed value of LEN is 2097152. Big numbers, big vibes 💜
  • -n, --num=NUM — where NUM is the (maximum) number of zone descriptors to print out. The default value is zero which is taken to mean print out all zone descriptors returned by the REPORT ZONES command 🌈
  • -p, --partial — set the PARTIAL bit in the cdb. Okay this one needs a whole storytime:

Without the PARTIAL bit set, a ZBC disk will attempt to form a response with all zones from LBA to the end of the disk. If there are a large number of zones (e.g. > 10,000) this large response will be truncated so that it doesn't exceed the "allocation length" field in the cdb (see --maxlen=LEN). The advantage of doing this is that the number of (remaining) zones on the disk can be calculated. The disadvantage is the amount of time that may take 😴

With the PARTIAL bit set in the cdb, only the number of zones implied by the "allocation length" field are fetched. This may be considerably faster than the same command without the PARTIAL bit set 🏎️

When iterating through the zones on a ZBC disk, the process will be faster when the PARTIAL bit is set. Typically --start=LBA is set to zero or the [LBA + zone_length] of the last zone reported in the previous iteration. Chef's kiss iteration loop 👩‍🍳

  • -r, --raw — output response in binary (to stdout) unless the --inhex=FN option is also given. In that case the input file name (FN) is decoded as binary (and the output is _not_ in binary (but may be hex)) 🌀. Yes, the underscore emphasis is doing the heavy lifting there, respect.
  • -R, --readonly — open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write 🫶 safer energy fr fr
  • -e, --realm — send or decode the SCSI REPORT REALMS command 👑
  • -o, --report=OPT — where OPT will become the contents of the REPORTING OPTION field in the cdb. The reporting options differ between REPORT ZONES, REPORT ZONE DOMAINS and REPORT REALMS. If the --help option is given twice (or the equivalent -hh) a list of available reporting options (as of writing) for each command is output 📜

The default value for REPORT ZONES is 0 which means report a list of all zones. Some other values are:

  • 1 for list zones with a zone condition of empty
  • 2 for list zones with a zone condition of implicitly opened
  • 3 for list zones with a zone condition of explicitly opened
  • 4 for list zones with a zone condition of closed
  • 5 for list zones with a zone condition of full
  • 6 for list zones with a zone condition of read only
  • 7 for list zones with a zone condition of offline

Other values are 0x10 for list zones with 'RWP recommended' set to true; 0x11 for list zones with non-sequential write resource active set to true, 0x3e for list zones apart from GAP zones, and 0x3f for list zones with a zone condition of 'not write pointer' ⭐

  • -s, --start=LBA — where LBA is at the start or within the first zone to be reported. The default value is 0. If LBA is not a zone start LBA then the preceding zone start LBA is used for reporting. Assumed to be in decimal unless prefixed with 0x or has a trailing h which indicate hexadecimal 🔢

The zone start LBA field used in the REPORT ZONES command was changed to the zone domain/realm locator field for the two newer ZBC-2 commands. For this utility --locator=LBA and --start=LBA are interchangeable 💅 twins fr

  • -S, --statistics — reviews all or a limited number of report zones, collects statistics and prints them (on stdout) 📊. The number of zones reviewed may be limited by any combination of --num=NUM, --report=OPT and --start=LBA options. The long option name may be abbreviated to --stats ✨
  • -v, --verbose — increase the level of verbosity, (i.e. debug output) 🔍 debug girlies rise
  • -V, --version — print the version string and then exit 👋
  • -w, --wp — print the write pointer (in hex) only. In the absence of errors, then a hex LBA will be printed on each line, one line for each zone. Can be usefully combined with the --num=NUM and --start=LBA options 🎀

💀 EXIT STATUS 💀

The exit status of sg_rep_zones is 0 when it is successful. Otherwise see the sg3_utils(8) man page. That's it, that's the whole rule 🌸

🫶 AUTHORS 🫶

Written by Douglas Gilbert. Legend behaviour honestly 👑

🐛 REPORTING BUGS 🐛

Report bugs to <dgilbert at interlog dot com>. Be nice about it, they're doing the work 🙈

Copyright © 2014-2023 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE 🫶

🦋 SEE ALSO 🦋

okay so if you're done here and you still wanna keep reading about zones (and honestly? same), go peek at these besties:

  • sg_reset_wp — the one that resets write pointers, obvs. very much its own thing, go read it 💅
  • sg_zone — the general-purpose zone command, the main character of the zone-adjacent utilities ngl
  • sg3_utils_json(sg3_utils) — for when you want your zone info in JSON instead of vibes ✨
  • zbd(libzbd) — the libzbd angle on zoned block devices, lowkey essential reading 🎀
  • blkzone(util-linux) — the util-linux take on zones, in case you're living in that ecosystem 🫶
fr fr, these cross-references are your friends — the zone world is a whole little ecosystem and nobody's doing it alone 💖

and that's the whole page, bestie!! you made it to the end, iconic behaviour honestly 👑 this absolute masterpiece of a manpage is from sg3_utils-1.48, dated June 2023 — screenshot it, cite it, frame it, whatever, just go forth and report those zones responsibly 🌸🦋✨

📦 where this page comes from