path: root/doc/sg_get_elem_status.8

.TH SG_GET_ELEM_STATUS "8" "August 2022" "sg3_utils\-1.48" SG3_UTILS
.SH NAME
sg_get_elem_status \- send SCSI GET PHYSICAL ELEMENT STATUS command
.SH SYNOPSIS
.B sg_get_elem_status
[\fI\-\-brief\fR] [\fI\-\-filter=FLT\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR]
[\fI\-\-inhex=FN\fR] [\fI\-\-json[=JO\fR]] [\fI\-\-maxlen=LEN\fR]
[\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-report\-type=RT\fR]
[\fI\-\-starting=ELEM\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
\fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
Send the SCSI GET PHYSICAL ELEMENT STATUS command to the \fIDEVICE\fR and
output the response. That command was introduced in (draft) SBC\-4 revision
16.
.PP
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.
.PP
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
\fI\-\-brief\fR option.
.PP
Rather than send this SCSI command to \fIDEVICE\fR, if the \fI\-\-inhex=FN\fR
option is given, then the contents of the file named \fIFN\fR are decoded
as ASCII hex (or binary if \fI\-\-raw\fR is also given) and then processed
as if it was the response of the GET PHYSICAL ELEMENT STATUS command.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
.TP
\fB\-b\fR, \fB\-\-brief\fR
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.
.TP
\fB\-f\fR, \fB\-\-filter\fR=\fIFLT\fR
where \fIFLT\fR 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.
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit.
.TP
\fB\-H\fR, \fB\-\-hex\fR
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 \fI\-\-inhex=FN\fR option in a later invocation.
.TP
\fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR
where \fIFN\fR is a file name whose contents are assumed to be ASCII
hexadecimal. If \fIDEVICE\fR is also given then \fIDEVICE\fR is ignored,
a warning is issued and the utility continues, decoding the file named
\fIFN\fR. See the "FORMAT OF FILES CONTAINING ASCII HEX" section in the
sg3_utils manpage for more information. If the \fI\-\-raw\fR option is
also given then the contents of \fIFN\fR are treated as binary.
.TP
\fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR]
output is in JSON format instead of human readable form. See sg3_utils_json
manpage or use '?' for \fIJO\fR for a summary.
.TP
\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
where \fILEN\fR 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. \fILEN\fR should be a multiple of 32 (e.g. 32, 64, and 96 are
suitable).
.TP
\fB\-r\fR, \fB\-\-raw\fR
output response in binary (to stdout) unless the \fI\-\-inhex=FN\fR option
is also given. In that case the input file name (\fIFN\fR) is decoded as
binary (and the output is _not_ in binary).
.TP
\fB\-R\fR, \fB\-\-readonly\fR
open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag).
The default is to open it read\-write.
.TP
\fB\-t\fR, \fB\-\-report\-type\fR=\fIRT\fR
where \fIRT\fR 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 .
.TP
\fB\-s\fR, \fB\-\-starting\fR=\fIELEM\fR
where \fIELEM\fR is placed in the STARTING ELEMENT field of the GET PHYSICAL
ELEMENT STATUS command. Only physical elements with identifiers greater
than, or equal to \fIELEM\fR 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 \fIELEM\fR of zero is assumed to be valid in this context.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the level of verbosity, (i.e. debug output). Additional output
caused by this option is sent to stderr.
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit.
.SH 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].
.PP
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 storge capacity) of the disk.
.SH EXIT STATUS
The exit status of sg_get_elem_status is 0 when it is successful. Otherwise
see the sg3_utils(8) man page.
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2019\-2022 Douglas Gilbert
.br
This software is distributed under a BSD\-2\-Clause license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_get_lba_status,sg3_utils,sg3_utils_json(sg3_utils)