Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sg_decode_sense (8)

Name

sg_decode_sense - decode SCSI sense data

Synopsis

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

Description

SG_DECODE_SENSE(8)                 SG3_UTILS                SG_DECODE_SENSE(8)



NAME
       sg_decode_sense - decode SCSI sense data

SYNOPSIS
       sg_decode_sense  [--binary=FN] [--file=FN] [--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 decod-
       ing is SPC-3 ANSI INCITS 408-2005 and the most recent draft SPC-4 revi-
       sion 37 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 some-
       thing  going  wrong but may just be informative. 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  hexa-
       decimal  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.

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

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

       -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").

       -f, --file=FN
              the sense data is read in ASCII hexadecimal from a  file  called
              FN.   The  sense data should appear as a sequence of bytes sepa-
              rated by space, comma,  tab  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 FN with bytes decoded from pairs of ASCII
              hexadecimal digits.

       -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
              FN  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 charac-
              ters 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 represen-
              tation  of  sense  data  (or  anything else) into the equivalent
              binary or a compilable ASCII hex form.


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | system/storage/sg3_utils |
       +---------------+--------------------------+
       |Stability      | Pass-through uncommitted |
       +---------------+--------------------------+
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.

       T10  defined  SCSI  command  names given a CDB can be decoded using the
       sg_raw utility with the '-vvv' 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).

EXIT STATUS
       The  exit  status of sg_decode_sense is 0 when it is successful. Other-
       wise 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-2014 Douglas Gilbert
       This software is distributed under a FreeBSD license. There is NO  war-
       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
       POSE.

SEE ALSO
       sg_requests,sg_raw(sg3_utils)


       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  http://sg.danny.cz/sg/p/sg3_utils-1.42.tgz

       Further information about this software can be found on the open source
       community website at http://sg.danny.cz/sg/sg3_utils.html.



sg3_utils-1.40                    August 2014               SG_DECODE_SENSE(8)