Provided by: sg3-utils_1.48-2ubuntu1_amd64 
NAME
sg_decode_sense - decode SCSI sense and related data
SYNOPSIS
sg_decode_sense [--binary=BFN] [--cdb] [--err=ES] [--file=HFN] [--help] [--hex] [--inhex=HFN]
[--ignore-first] [--json[=JO]] [--js-file=JFN] [--nodecode] [--nospace] [--status=SS] [--verbose]
[--version] [--write=WFN] [H1 H2 H3 ...]
DESCRIPTION
This utility takes SCSI sense data in binary or as a sequence of ASCII hexadecimal bytes and decodes it.
The primary reference for the decoding is SPC-5 ANSI INCITS 502-2020 and the most recent draft SPC-6
revision 6 which can be found at https://www.t10.org and other locations on the internet.
SCSI sense data is often found in kernel log files as a result of something going wrong or may be an
informative warning. It is often shown as a sequence of hexadecimal bytes, starting with 70, 71, 72, 73,
f0 or f1. Sense data could be up to 252 bytes long but typically is much shorter than that, 18 bytes
long is often seen and is usually associated with the older "fixed" format sense data.
The sense data can be provided on the command line or in a file. If given on the command line the sense
data should be a sequence of hexadecimal bytes separated by space. Alternatively a file can be given with
the contents in binary or ASCII hexadecimal bytes. The latter form can contain several lines each with
none, one or more ASCII hexadecimal bytes separated by space (comma or tab). The hash symbol may appear
and it and the rest of the line is ignored making it useful for comments.
If the --cdb option is given then rather than viewing the given hex arguments as sense data, it is viewed
as a SCSI command descriptor block (CDB). In this case the command name is printed out. That name is
based on the first hex byte given (know as the opcode) and optionally on another field called the
"service action".
Another alternate action is when the --err=ES is given. ES is assumed to be an "exit status" value
between 0 and 255 from one of the utilities in this package. A descriptive string is printed. Other
options are ignored apart from --verbose.
When the --nodecode option is given, this utility may be used to convert a binary file to hexadecimal or
vice versa. The data converted does not need to be related to SCSI sense data nor CDBs.
OPTIONS
Arguments to long options are mandatory for short options as well.
-b, --binary=BFN
the data is read in binary from a file called BFN. The option cannot be given with --file=HFN or
--inhex=HFN as they contradict. The data is assumed to be sense data unless the fI--nodecode is
given.
-c, --cdb
treat the given string of hex arguments as bytes in a SCSI CDB and decode the command name.
-e, --err=ES
ES should be an "exit status" value between 0 and 255 that is available from the shell (i.e. the
utility's execution context) after the utility is finished. By default an indicative error message
is printed to stdout; and if the --verbose option is given once (or an odd number of times) then
the message is instead printed to stderr. If --verbose is given two or more times a longer form of
the message is output. In all cases the message is less than 128 characters long with one trailing
line feed. All other command line options and arguments are ignored.
-f, --file=HFN
the sense data is read in ASCII hexadecimal from a file called HFN. The sense data should appear
as a sequence of bytes separated by space, comma, tab, hyphen or newline. Everything from and
including a hash symbol to the end of that line is ignored. If --nospace is set then no separator
is required between the ASCII hexadecimal digits in HFN with bytes decoded from pairs of ASCII
hexadecimal digits.
-h, --help
output the usage message then exit.
-H, --hex
this option is used once in conjunction with --write=WFN in order to change the output written to
WFN to lines of ASCII hex bytes suitable for a C language compiler. Each line contains up to 16
bytes (e.g. a line starting with "0x3b,0x07,0x00,0xff").
In other cases (i.e. when --write=WFN is not given, or this option is given more than once) then
the output is as described in the sg3_utils(8) manpage.
The combination of --inhex=HFN and this option used three times can be useful to converting
hexadecimal bytes (e.g. hyphen separated) into a more regular form. The short option form is more
convenient for invoking this option three times (e.g. '-HHH').
-i, --inhex=HFN
same action as --file=HFN. This option was added for compatibility with other utilities in this
package that have a --inhex= option.
-I, --ignore-first
many programs that output hex bytes (e.g. 'hexdump -C') have a running count (or index) in the
first column of each line. This option ignores the first hexadecimal value on each line. This
option has no effect if --binary=BFN or --nospace are given. Blank lines and any character from
and after "#" on a line are ignored. Useful with the --file=HFN and --nodecode options.
-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.
-N, --nodecode
Do not decode the given data as sense or a cdb. Useful when arbitrary data is given (e.g. when
converting hex to binary or vice versa).
-n, --nospace
expect ASCII hexadecimal to be a string of hexadecimal digits with no spaces between them. Bytes
are decoded by taking two hexadecimal digits at a time, so an even number of digits is expected.
The string of hexadecimal digits may be on the command line (replacing "H1 H2 H3") or spread
across multiple lines the HFN given to --file=. On the command line, spaces (or other whitespace
characters) between sequences of hexadecimal digits are ignored; the maximum command line hex
string is 1023 characters long.
-s, --status=SS
where SS is a SCSI status byte value, given in hexadecimal. The SCSI status byte is related to,
but distinct from, sense data.
-v, --verbose
increase the degree of verbosity (debug messages).
-V, --version
output version string then exit.
-w, --write=WFN
writes the sense data out to a file called WFN. If necessary WFN is created. If WFN exists then it
is truncated prior to writing the sense data to it. If the --hex option is also given then ASCII
hex is written to WFN (see the --hex option description); otherwise binary is written to WFN. This
option is a convenience and may be helpful in converting the ASCII hexadecimal representation of
sense data (or anything else) into the equivalent binary or a compilable ASCII hex form.
NOTES
Unlike most utilities in this package, this utility does not access a SCSI device (logical unit). This
utility accesses a library associated with this package. Amongst other things the library decodes SCSI
sense data.
The sg_raw utility takes a ASCII hexadecimal sequence representing a SCSI CDB. When sg_raw is given the
'-vvv' option, it will attempt to decode the CDB name.
Using the option combination: "--inhex=HFN --nodecode --write=WFN" may be used to convert hexadecimal (as
produced by this and other utilities in this package) to binary where the output file is WFN.
Unlike many other utilities there is no --raw option. However binary data can be input using the
--binary=BFN option while binary data can be output using the --write=WFN option (in the absence of the
--hex option).
EXAMPLES
Sense data is often printed out in kernel logs and sometimes on the command line when verbose or debug
flags are given. It will be at least 8 bytes long, often 18 bytes long but may be longer. A sense data
string might look like this:
f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00
00 00
Cut and paste it after the sg_decode_sense command:
sg_decode_sense f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00 00 00
and for this sense data the output should look like this:
Fixed format, current; Sense key: Medium Error
Additional sense: Unrecovered read error
Info fld=0x1234 [4660]
For a medium error the Info field is the logical block address (LBA) of the lowest numbered block that
the associated SCSI command was not able to read (verify or write).
To convert arbitrary binary data to hex, suitable to be parsed by other sg3_utils utilities. The
--nodecode option is used in this case:
sg_decode_sense -N -i vpd_zbdc.hex -w vpd_zbdc.bin
The '-HHH' will output hex to the console (stdout) in a form suitable for other utilities in this package
to parse as input. And sg_decode_sense can also be used to convert from arbitrary hex to binary with:
sg_decode_sense -N -b vpd_zbdc.raw -HHH
Note that tools like hexdump and od place a counter (i.e. an index starting at 0) at the beginning of
each line which is a pain when parsing hex. The '/-HHH' option(s) does not output that leading counter
on each line.
EXIT STATUS
The exit status of sg_decode_sense 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 © 2010-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.
SEE ALSO
sg_requests,sg_raw(sg3_utils)
sg3_utils-1.48 May 2023 SG_DECODE_SENSE(8)