138 lines
6.5 KiB
Groff
138 lines
6.5 KiB
Groff
.TH SG_GET_ELEM_STATUS "8" "November 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 storage 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)
|