SG_GET_ELEM_STATUS(8) SG3_UTILS SG_GET_ELEM_STATUS(8) NAME sg_get_elem_status - send SCSI GET PHYSICAL ELEMENT STATUS command SYNOPSIS sg_get_elem_status [--brief] [--filter=FLT] [--help] [--hex] [--inhex=FN] [--json[=JO]] [--js-file=JFN] [--maxlen=LEN] [--raw] [--readonly] [--re- port-type=RT] [--starting=ELEM] [--verbose] [--version] DEVICE DESCRIPTION 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 ele- ments) and refers to disk resources that control user data storage. An ex- ample 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 for- mer 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. OPTIONS Arguments to long options are mandatory for short options as well. -b, --brief when used once, the output of each physical element status descrip- tor is reduced to: <element_id>: <element_type>,<element_health> . All three are output as decimal integers. When used twice the "Ele- ment 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 de- scriptors 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 re- turned. 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 hexa- decimal. 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 argu- ments 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 ele- ment 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 PHYSI- CAL 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 revi- sion 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. NOTES 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 ques- tion should either be decommissioned or have the REMOVE ELEMENT AND TRUN- CATE (or ... AND MODIFY ZONES) command invoked to repair (and reduce the storage capacity) of the disk. EXIT STATUS The exit status of sg_get_elem_status is 0 when it is successful. Otherwise see the sg3_utils(8) man page. AUTHORS Written by Douglas Gilbert. REPORTING BUGS Report bugs to <dgilbert at interlog dot com>. COPYRIGHT Copyright (C) 2019-2022 Douglas Gilbert This software is distributed under a BSD-2-Clause license. There is NO war- ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SEE ALSO sg_get_lba_status,sg3_utils,sg3_utils_json(sg3_utils) sg3_utils-1.48 June 2023 SG_GET_ELEM_STATUS(8)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | EXIT STATUS | AUTHORS | REPORTING BUGS | COPYRIGHT | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=sg_get_elem_status&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>