SG_DECODE_SENSE(8) - phpMan

SG_DECODE_SENSE(8) SG3_UTILS SG_DECODE_SENSE(8)

NAME
sg_decode_sense - decode SCSI sense and related data

SYNOPSIS
sg_decode_sense [--binary=BFN] [--cdb] [--err=ES] [--file=HFN] [--help] [--hex]
[--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-4 ANSI INCITS 513-2015 and
the most recent draft SPC-5 revision 19 which can be found at http://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 typ-
ically 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. Alterna-
tively 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 sta-
tus" 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.

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

-b, --binary=BFN
the sense data is read in binary from a file called BFN.

-c, --cdb
treat the given string of hex arguments as bytes in a SCSI CDB and decode the com-
mand 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 de-
fault 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 or newline. Ev-
erything 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 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").

-n, --nospace
expect ASCII hexadecimal to be a string of hexadecimal digits with no spaces be-
tween 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 op-
tion is also given then ASCII hex is written to WFN (see the --hex option descrip-
tion); 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 any-
thing 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.

EXAMPLES
Sense data is often printed out in kernel logs and sometimes on the command line when ver-
bose 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 num-
bered block that the associated SCSI command was not able to read (verify or write).

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 (C) 2010-2019 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO warranty; not even for
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.