1SG_DECODE_SENSE(8) SG3_UTILS SG_DECODE_SENSE(8)
2
6 sg_decode_sense - decode SCSI sense data
7
9 sg_decode_sense [--binary=FN] [--file=FN] [--help] [--hex] [--nospace]
10 [--status=SS] [--verbose] [--version] [--write=WFN] [H1 H2 H3 ...]
11
13 This utility takes SCSI sense data in binary or as a sequence of ASCII
14 hexadecimal bytes and decodes it. The primary reference for the decod‐
15 ing is SPC-3 ANSI INCITS 408-2005 and the most recent draft SPC-4 revi‐
16 sion 37 which can be found at http://www.t10.org and other locations on
17 the internet.
18 SCSI sense data is often found in kernel log files as a result of some‐
20 thing going wrong but may just be informative. It is often shown as a
21 sequence of hexadecimal bytes, starting with 70, 71, 72, 73, f0 or f1.
22 Sense data could be up to 252 bytes long but typically is much shorter
23 than that, 18 bytes long is often seen and is usually associated with
24 the older "fixed" format sense data.
25 The sense data can be provided on the command line or in a file. If
27 given on the command line the sense data should be a sequence of hexa‐
28 decimal bytes separated by space. Alternatively a file can be given
29 with the contents in binary or ASCII hexadecimal bytes. The latter form
30 can contain several lines each with none, one or more ASCII hexadecimal
31 bytes separated by space (comma or tab). The hash symbol may appear and
32 it and the rest of the line is ignored making it useful for comments.
33
35 Arguments to long options are mandatory for short options as well.
36 -b, --binary=FN
38 the sense data is read in binary from a file called FN.
39 -h, --help
41 output the usage message then exit.
42 -H, --hex
44 this option is used in conjunction with --write=WFN in order to
45 change the output written to WFN to lines of ASCII hex bytes
46 suitable for a C language compiler. Each line contains up to 16
47 bytes (e.g. a line starting with "0x3b,0x07,0x00,0xff").
48 -f, --file=FN
50 the sense data is read in ASCII hexadecimal from a file called
51 FN. The sense data should appear as a sequence of bytes sepa‐
52 rated by space, comma, tab or newline. Everything from and
53 including a hash symbol to the end of that line is ignored. If
54 --nospace is set then no separator is required between the ASCII
55 hexadecimal digits in FN with bytes decoded from pairs of ASCII
56 hexadecimal digits.
57 -n, --nospace
59 expect ASCII hexadecimal to be a string of hexadecimal digits
60 with no spaces between them. Bytes are decoded by taking two
61 hexadecimal digits at a time, so an even number of digits is
62 expected. The string of hexadecimal digits may be on the command
63 line (replacing "H1 H2 H3") or spread across multiple lines the
64 FN given to --file=. On the command line, spaces (or other
65 whitespace characters) between sequences of hexadecimal digits
66 are ignored; the maximum command line hex string is 1023 charac‐
67 ters long.
68 -s, --status=SS
70 where SS is a SCSI status byte value, given in hexadecimal. The
71 SCSI status byte is related to but distinct from sense data.
72 -v, --verbose
74 increase the degree of verbosity (debug messages).
75 -V, --version
77 output version string then exit.
78 -w, --write=WFN
80 writes the sense data out to a file called WFN. If necessary WFN
81 is created. If WFN exists then it is truncated prior to writing
82 the sense data to it. If the --hex option is also given then
83 ASCII hex is written to WFN (see the --hex option description);
84 otherwise binary is written to WFN. This option is a convenience
85 and may be helpful in converting the ASCII hexadecimal represen‐
86 tation of sense data (or anything else) into the equivalent
87 binary or a compilable ASCII hex form.
88
90 Unlike most utilities in this package, this utility does not access a
91 SCSI device (logical unit). This utility accesses a library associated
92 with this package. Amongst other things the library decodes SCSI sense
93 data.
94 T10 defined SCSI command names given a CDB can be decoded using the
96 sg_raw utility with the '-vvv' option.
97
99 Sense data is often printed out in kernel logs and sometimes on the
100 command line when verbose or debug flags are given. It will be at least
101 8 bytes long, often 18 bytes long but may be longer. A sense data
102 string might look like this:
103 f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00
105 00 00
106 Cut and paste it after the sg_decode_sense command:
108 sg_decode_sense f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00 00 00
110 and for this sense data the output should look like this:
112 Fixed format, current; Sense key: Medium Error
114 Additional sense: Unrecovered read error
115 Info fld=0x1234 [4660]
116 For a medium error the Info field is the logical block address (LBA) of
118 the lowest numbered block that the associated SCSI command was not able
119 to read (verify or write).
120
122 The exit status of sg_decode_sense is 0 when it is successful. Other‐
123 wise see the sg3_utils(8) man page.
124
126 Written by Douglas Gilbert.
127
129 Report bugs to <dgilbert at interlog dot com>.
130
132 Copyright © 2010-2014 Douglas Gilbert
133 This software is distributed under a FreeBSD license. There is NO war‐
134 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
135 POSE.
136
138 sg_requests,sg_raw(sg3_utils)
139sg3_utils-1.40 August 2014 SG_DECODE_SENSE(8)