sg_get_elem_status - send SCSI GET PHYSICAL ELEMENT STATUS command

       Written by Douglas Gilbert.

       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.

       Send the SCSI GET PHYSICAL ELEMENT STATUS command to the DEVICE and output the response. That command was
       introduced in (draft) SBC-4 revision 16.

       T10 drafts now speak of both 'physical' and 'storage' elements. The latter term is  more  specific  (i.e.
       storage  elements are a sub-set of physical elements) and refers to disk resources that control user data
       storage. An example of a storage element is the user data associated with a head on a spinning hard disk.
       When a storage element has been  "depopulated"  its  former  storage  accessed  via  LBAs  is  no  longer
       available.  Physical  elements  are  more  general  and  includes storage elements and might include disk
       resources used for "saved" mode page settings amongst other things.

       The default action of this utility is to decode the response into a header and up to 32 physical  element
       status  descriptors.  The status descriptors are output one per line. The amount of output can be reduced
       by the --brief option.

       Rather than send this SCSI command to DEVICE, if the --inhex=FN option is given, then the contents of the
       file named FN are decoded as ASCII hex (or binary if --raw is also given) and then processed as if it was
       the response of the GET PHYSICAL ELEMENT STATUS command.

       The exit status of sg_get_elem_status is 0 when it is successful.  Otherwise  see  the  sg3_utils(8)  man
       page.

       sg_get_elem_status - send SCSI GET PHYSICAL ELEMENT STATUS command

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

       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.

       Arguments to long options are mandatory for short options as well.

       -b, --brief
              when used once, the output of each physical element status descriptor is reduced to: <element_id>:
              <element_type>,<element_health> . All three are output as decimal integers. When  used  twice  the
              "Element  descriptors:"  line introducing the status descriptors is not output. When used three or
              more times only the response header is output.

       -f, --filter=FLT
              where FLT is 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. The default value is zero.

       -h, --help
              output the usage message then exit.

       -H, --hex
              output response to this command in ASCII hex. Each line of 16 bytes is preceded by an  address  or
              index,  starting  at  0  and the address is also in hex. If given twice then 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 (i.e. so no leading address nor 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.

       -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 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
              where LEN is the (maximum) response length in bytes. It is 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).

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

       -R, --readonly
              open the DEVICE read-only (e.g. in Unix with the O_RDONLY  flag).   The  default  is  to  open  it
              read-write.

       -t, --report-type=RT
              where  RT  will  be  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
              where  ELEM  is  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, 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.

       -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 and then exit.

       Report bugs to <dgilbert at interlog dot com>.

sg_get_lba_status,sg3_utils,sg3_utils_json(sg3_utils)

sg3_utils-1.48                                      June 2023                              SG_GET_ELEM_STATUS(8)

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