sg_decode_sense(8)

1SG_DECODE_SENSE(8)                 SG3_UTILS                SG_DECODE_SENSE(8)
2
3
4

NAME

6       sg_decode_sense - decode SCSI sense data
7

SYNOPSIS

9       sg_decode_sense  [--binary=FN] [--file=FN] [--help] [--hex] [--nospace]
10       [--status=SS] [--verbose] [--version] [--write=WFN] [H1 H2 H3 ...]
11

DESCRIPTION

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 29 which can be found at http://www.t10.org and other locations on
17       the internet.
18
19       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
26       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

OPTIONS

35       Arguments to long options are mandatory for short options as well.
36
37       -b, --binary=FN
38              the sense data is read in binary from a file called FN.
39
40       -h, --help
41              output the usage message then exit.
42
43       -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
49       -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
58       -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=.
65
66       -s, --status=SS
67              where  SS is a SCSI status byte value, given in hexadecimal. The
68              SCSI status byte is related to but distinct from sense data.
69
70       -v, --verbose
71              increase the degree of verbosity (debug messages).
72
73       -V, --version
74              output version string then exit.
75
76       -w, --write=WFN
77              writes the sense data out to a file called WFN. If necessary WFN
78              is  created. If WFN exists then it is truncated prior to writing
79              the sense data to it. If the --hex option  is  also  given  then
80              ASCII  hex is written to WFN (see the --hex option description);
81              otherwise binary is written to WFN. This option is a convenience
82              and may be helpful in converting the ASCII hexadecimal represen‐
83              tation of sense data (or  anything  else)  into  the  equivalent
84              binary or a compilable ASCII hex form.
85

NOTES

87       Unlike  most  utilities in this package, this utility does not access a
88       SCSI device (logical unit). This utility accesses a library  associated
89       with  this package. Amongst other things the library decodes SCSI sense
90       data.
91

EXAMPLES

93       Sense data is often printed out in kernel logs  and  sometimes  on  the
94       command line when verbose or debug flags are given. It will be at least
95       8 bytes long, often 18 bytes long but  may  be  longer.  A  sense  data
96       string might look like this:
97
98       f0 00 03 00 00 12 34 0a  00 00 00 00 11 00 00 00
99       00 00
100
101       Cut and paste it after the sg_decode_sense command:
102
103         sg_decode_sense f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00 00 00
104
105       and for this sense data the output should look like this:
106
107        Fixed format, current;  Sense key: Medium Error
108        Additional sense: Unrecovered read error
109         Info fld=0x1234 [4660]
110
111       For a medium error the Info field is the logical block address (LBA) of
112       the lowest numbered block that the associated SCSI command was not able
113       to read (verify or write).
114

EXIT STATUS

116       The  exit  status of sg_decode_sense is 0 when it is successful. Other‐
117       wise see the sg3_utils(8) man page.
118

AUTHORS

120       Written by Douglas Gilbert.
121

REPORTING BUGS

123       Report bugs to <dgilbert at interlog dot com>.
124

COPYRIGHT

126       Copyright © 2010-2011 Douglas Gilbert
127       This software is distributed under a FreeBSD license. There is NO  war‐
128       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
129       POSE.
130