SG_GET_ELEM_STATUS(8)

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

🌸 sg_get_elem_status 💅 (that's the sg3_utils girlies, section 8 btw)

okay so bestie, real talk: sg_get_elem_status is the little utility that sends the SCSI GET PHYSICAL ELEMENT STATUS command. yes that's a lot of capital letters, we love that for it. sit down, hydrate, let's go 🫶

✨ SYNOPSIS ✨

sg_get_elem_status [--brief] [--filter=FLT] [--help] [--hex]
[--inhex=FN] [--json[=JO]] [--js-file=JFN] [--maxlen=LEN] [--raw]
[--readonly] [--report-type=RT] [--starting=ELEM] [--verbose]
[--version] DEVICE

💖 DESCRIPTION 💖

So the whole vibe is: you send the SCSI GET PHYSICAL ELEMENT STATUS command to DEVICE, and it spits back a response that you then output. That command? Brand new, literally only introduced in the (draft) SBC-4 revision 16. baby command energy 👑

Now, T10 drafts (the standard-writing girlies) talk about both 'physical' and 'storage' elements. Storage is the more specific term — like, storage elements are a sub-set of physical elements — and it refers to disk resources that control user data storage. Iconic example of a storage element: the user data associated with a head on a spinning hard disk. 🌀 When a storage element has been "depopulated", its former storage that you used to access via LBAs is simply not available anymore, gone, bye. 😭 Physical elements are the more general category — they include storage elements and might also include disk resources used for "saved" mode page settings, amongst other things.

Default action of this utility? It decodes the response into a header plus up to 32 physical element status descriptors, and those descriptors come out one per line. If that's too much word-vomit for you, the --brief option reduces the amount of output. slay.

But wait, there's a plot twist 🎭 — instead of sending this SCSI command to DEVICE at all, if you give it the --inhex=FN option, then the contents of the file named FN get decoded as ASCII hex (or as binary if --raw is also given 😌), and then processed as if it was the response of the GET PHYSICAL ELEMENT STATUS command. fake it till you make it, literally.

🎀 OPTIONS 🎀

Arguments to long options are mandatory for short options as well. (yes, fr fr, keep that in mind.)

  • -b, --brief — when used once, the output of each physical element status descriptor is abbreviated compared to when this option isn't given. Also, the term "associated capacity: not specified;" gets dropped, because honestly it doesn't convey much information 💀. When used twice, the output of each physical element status descriptor is reduced all the way down to: <element_id>: <element_type>,<element_health> . All three of those are output as decimal integers. When used twice, the "Element descriptors:" line that introduces the status descriptors is not output either. And when used three or more times? Only the response header is output. minimalism era.
  • -f, --filter=FLT — FLT gets placed in a two bit field called FILTER in the GET PHYSICAL ELEMENT STATUS command. Only two values are defined for that field: 0 for all element descriptors; 1 for those element descriptors that are outside 'spec' or have depopulation information to report. In both cases the REPORT TYPE and STARTING ELEMENT fields may further restrict (reduce) the number of element descriptors returned. Default value is zero. 🧚
  • -h, --help — outputs the usage message, then exits. the classic.
  • -H, --hex — output the response to this command in ASCII hex. Each line of 16 bytes is preceded by an address or index, starting at 0, and that address is also in hex. If given twice, an ASCII rendering of each byte is appended to the line output. If given three or more times, then only the ASCII hex of each byte is output, 16 bytes per line (so: no leading address, no trailing ASCII rendering). This latter form is suitable for placing in a file and being used with the --inhex=FN option in a later invocation. 🦋 clever girlie behaviour.
  • -i, --inhex=FN — 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 they 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.
  • -m, --maxlen=LEN — LEN is the (maximum) response length in bytes. It gets placed in the cdb's "allocation length" field. If not given then 1056 is used. 1056 is enough space for the response header plus 32 physical element status descriptors. LEN should be a multiple of 32 (e.g. 32, 64, and 96 are suitable). do the math bestie ✨
  • -r, --raw — output the 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). don't get it twisted 🙈
  • -R, --readonly — open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write. safety first 🎀
  • -t, --report-type=RT — RT gets placed in the REPORT TYPE field of the GET PHYSICAL ELEMENT STATUS command. Currently only two values are defined: 0 for 'physical element' and 1 for 'storage element'. The default value is 0 .
  • -s, --starting=ELEM — ELEM gets placed in the STARTING ELEMENT field of the GET PHYSICAL ELEMENT STATUS command. Only physical elements with identifiers greater than, or equal to ELEM are returned. The default value is zero which — okay, while it isn't a valid element identifier (since they must be non-zero) — is given in an example in Annex L of SBC-4 revision 17. So an ELEM of zero is assumed to be valid in this context. lore. 📜
  • -v, --verbose — increase the level of verbosity (i.e. debug output). Additional output caused by this option is sent to stderr. 👀
  • -V, --version — print the version string, then exit.

🔥 NOTES 🔥

The "Warning - physical element status change" additional sense code [0xb, 0x14] is special — it should prompt an application client to call the GET PHYSICAL ELEMENT STATUS command. How that warning gets triggered depends on the settings in the Informational Exceptions Control mode page [0xc, 0x0]. iykyk 🌈

After detecting one or more out-of-spec storage elements, the disk in question should either be decommissioned or have the REMOVE ELEMENT AND TRUNCATE (or ... AND MODIFY ZONES) command invoked to repair (and reduce the storage capacity) of the disk. this is the serious part, bestie, don't skip it 💀

⭐ EXIT STATUS ⭐

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

👑 AUTHORS 👑

Written by Douglas Gilbert. (the icon, the legend 💅)

📢 REPORTING BUGS 📢

Report bugs to dgilbert at interlog dot com. he wants to hear about it, fr fr.

Copyright © 2019-2022 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. (say it louder for the people in the back 😤)

🦋 SEE ALSO 🦋

sg_get_lba_status, sg3_utils, sg3_utils_json(sg3_utils)

and that's the whole page, bestie 🎀 mwah. this one's from sg3_utils-1.48, dated June 2023 — go forth and get those element statuses, you absolute main character 🌟💖

📦 where this page comes from