1SG_DECODE_SENSE(8) SG3_UTILS SG_DECODE_SENSE(8)
2
6 sg_decode_sense - decode SCSI sense and related data
7
9 sg_decode_sense [--binary=FN] [--cdb] [--err=ES] [--file=FN] [--help]
10 [--hex] [--nospace] [--status=SS] [--verbose] [--version] [--write=WFN]
11 [H1 H2 H3 ...]
12
14 This utility takes SCSI sense data in binary or as a sequence of ASCII
15 hexadecimal bytes and decodes it. The primary reference for the decod‐
16 ing is SPC-4 ANSI INCITS 513-2015 and the most recent draft SPC-5 revi‐
17 sion 19 which can be found at http://www.t10.org and other locations on
18 the internet.
19 SCSI sense data is often found in kernel log files as a result of some‐
21 thing going wrong or may be an informative warning. It is often shown
22 as a sequence of hexadecimal bytes, starting with 70, 71, 72, 73, f0 or
23 f1. Sense data could be up to 252 bytes long but typically is much
24 shorter than that, 18 bytes long is often seen and is usually associ‐
25 ated with the older "fixed" format sense data.
26 The sense data can be provided on the command line or in a file. If
28 given on the command line the sense data should be a sequence of hexa‐
29 decimal bytes separated by space. Alternatively a file can be given
30 with the contents in binary or ASCII hexadecimal bytes. The latter form
31 can contain several lines each with none, one or more ASCII hexadecimal
32 bytes separated by space (comma or tab). The hash symbol may appear and
33 it and the rest of the line is ignored making it useful for comments.
34 If the --cdb option is given then rather than viewing the given hex
36 arguments as sense data, it is viewed as a SCSI command descriptor
37 block (CDB). In this case the command name is printed out. That name is
38 based on the first hex byte given (know as the opcode) and optionally
39 on another field called the "service action".
40 Another alternate action is when the --err=ES is given. ES is assumed
42 to be an "exit status" value between 0 and 255 from one of the utili‐
43 ties in this package. A descriptive string is printed. Other options
44 are ignored apart from --verbose.
45
47 Arguments to long options are mandatory for short options as well.
48 -b, --binary=FN
50 the sense data is read in binary from a file called FN.
51 -c, --cdb
53 treat the given string of hex arguments as bytes in a SCSI CDB
54 and decode the command name.
55 -e, --err=ES
57 ES should be an "exit status" value between 0 and 255 that is
58 available from the shell (i.e. the utility's execution context)
59 after the utility is finished. By default an indicative error
60 message is printed to stdout; and if the --verbose option is
61 given once (or an odd number of times) then the message is
62 instead printed to stderr. If --verbose is given two or more
63 times a longer form of the message is output. In all cases the
64 message is less than 128 characters long with one trailing line
65 feed. All other command line options and arguments are ignored.
66 -f, --file=FN
68 the sense data is read in ASCII hexadecimal from a file called
69 FN. The sense data should appear as a sequence of bytes sepa‐
70 rated by space, comma, tab or newline. Everything from and
71 including a hash symbol to the end of that line is ignored. If
72 --nospace is set then no separator is required between the ASCII
73 hexadecimal digits in FN with bytes decoded from pairs of ASCII
74 hexadecimal digits.
75 -h, --help
77 output the usage message then exit.
78 -H, --hex
80 this option is used in conjunction with --write=WFN in order to
81 change the output written to WFN to lines of ASCII hex bytes
82 suitable for a C language compiler. Each line contains up to 16
83 bytes (e.g. a line starting with "0x3b,0x07,0x00,0xff").
84 -n, --nospace
86 expect ASCII hexadecimal to be a string of hexadecimal digits
87 with no spaces between them. Bytes are decoded by taking two
88 hexadecimal digits at a time, so an even number of digits is
89 expected. The string of hexadecimal digits may be on the command
90 line (replacing "H1 H2 H3") or spread across multiple lines the
91 FN given to --file=. On the command line, spaces (or other
92 whitespace characters) between sequences of hexadecimal digits
93 are ignored; the maximum command line hex string is 1023 charac‐
94 ters long.
95 -s, --status=SS
97 where SS is a SCSI status byte value, given in hexadecimal. The
98 SCSI status byte is related to, but distinct from, sense data.
99 -v, --verbose
101 increase the degree of verbosity (debug messages).
102 -V, --version
104 output version string then exit.
105 -w, --write=WFN
107 writes the sense data out to a file called WFN. If necessary WFN
108 is created. If WFN exists then it is truncated prior to writing
109 the sense data to it. If the --hex option is also given then
110 ASCII hex is written to WFN (see the --hex option description);
111 otherwise binary is written to WFN. This option is a convenience
112 and may be helpful in converting the ASCII hexadecimal represen‐
113 tation of sense data (or anything else) into the equivalent
114 binary or a compilable ASCII hex form.
115
117 Unlike most utilities in this package, this utility does not access a
118 SCSI device (logical unit). This utility accesses a library associated
119 with this package. Amongst other things the library decodes SCSI sense
120 data.
121 The sg_raw utility takes a ASCII hexadecimal sequence representing a
123 SCSI CDB. When sg_raw is given the '-vvv' option, it will attempt to
124 decode the CDB name.
125
127 Sense data is often printed out in kernel logs and sometimes on the
128 command line when verbose or debug flags are given. It will be at least
129 8 bytes long, often 18 bytes long but may be longer. A sense data
130 string might look like this:
131 f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00
133 00 00
134 Cut and paste it after the sg_decode_sense command:
136 sg_decode_sense f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00 00 00
138 and for this sense data the output should look like this:
140 Fixed format, current; Sense key: Medium Error
142 Additional sense: Unrecovered read error
143 Info fld=0x1234 [4660]
144 For a medium error the Info field is the logical block address (LBA) of
146 the lowest numbered block that the associated SCSI command was not able
147 to read (verify or write).
148
150 The exit status of sg_decode_sense is 0 when it is successful. Other‐
151 wise see the sg3_utils(8) man page.
152
154 Written by Douglas Gilbert.
155
157 Report bugs to <dgilbert at interlog dot com>.
158
160 Copyright © 2010-2018 Douglas Gilbert
161 This software is distributed under a FreeBSD license. There is NO war‐
162 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
163 POSE.
164
166 sg_requests,sg_raw(sg3_utils)
167sg3_utils-1.43 August 2018 SG_DECODE_SENSE(8)