Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

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

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  decod-
       ing is SPC-4 ANSI INCITS 513-2015 and the most recent draft SPC-5 revi-
       sion 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 some-
       thing 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  typically  is  much
       shorter  than  that, 18 bytes long is often seen and is usually associ-
       ated 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.

       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 status" value between 0 and 255 from one of the utili-
       ties 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 command 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 default  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 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 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 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
              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 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.

       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.

       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       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.46.tgz.

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

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-2019 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)




sg3_utils-1.45                     June 2019                SG_DECODE_SENSE(8)