add forwarded sense descriptor; new sg_decode_sense utility

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@365 6180dd3e-e324-4e3e-922d-17de1ae2f315

4 files changed, 93 insertions, 14 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 2c4f75e3..fa6ecec0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -8,7 +8,7 @@ if OS_LINUX
 # sg_scan is shared by Linux and Win32
 
 man_MANS = \
-	sg3_utils.8 \
+	sg3_utils.8 sg_decode_sense.8 \
 	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 	sg_dd.8 sg_emc_trespass.8 sg_format.8 sg_get_config.8 \
 	sg_get_lba_status.8 sg_ident.8 sginfo.8 sg_inq.8 sg_logs.8 \
@@ -34,7 +34,7 @@ endif
 if OS_WIN32_MINGW
 
 man_MANS = \
-	sg3_utils.8 \
+	sg3_utils.8 sg_decode_sense.8 \
 	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 	sg_inq.8 sg_logs.8 sg_luns.8 sg_modes.8 sg_opcodes.8 sg_persist.8 \
@@ -58,7 +58,7 @@ endif
 if OS_WIN32_CYGWIN
 
 man_MANS = \
-	sg3_utils.8 \
+	sg3_utils.8 sg_decode_sense.8 \
 	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 	sg_inq.8 sg_logs.8 sg_luns.8 sg_modes.8 sg_opcodes.8 \
@@ -82,7 +82,7 @@ endif
 if OS_FREEBSD
 
 man_MANS = \
-	sg3_utils.8 \
+	sg3_utils.8 sg_decode_sense.8 \
 	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 	sg_inq.8 sg_logs.8 sg_luns.8 \
@@ -100,7 +100,7 @@ endif
 if OS_SOLARIS
 
 man_MANS = \
-	sg3_utils.8 \
+	sg3_utils.8 sg_decode_sense.8 \
 	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 	sg_inq.8 sg_logs.8 sg_luns.8 \
@@ -118,7 +118,7 @@ endif
 if OS_OSF
 
 man_MANS = \
-	sg3_utils.8 \
+	sg3_utils.8 sg_decode_sense.8 \
 	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 	sg_inq.8 sg_logs.8 sg_luns.8 \
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 53b5c908..e0c47634 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -186,7 +186,7 @@ top_build_prefix = @top_build_prefix@
 top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
 @OS_FREEBSD_TRUE@man_MANS = \
-@OS_FREEBSD_TRUE@	sg3_utils.8 \
+@OS_FREEBSD_TRUE@	sg3_utils.8 sg_decode_sense.8 \
 @OS_FREEBSD_TRUE@	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 @OS_FREEBSD_TRUE@	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 @OS_FREEBSD_TRUE@	sg_inq.8 sg_logs.8 sg_luns.8 \
@@ -205,7 +205,7 @@ top_srcdir = @top_srcdir@
 #
 # sg_scan is shared by Linux and Win32
 @OS_LINUX_TRUE@man_MANS = \
-@OS_LINUX_TRUE@	sg3_utils.8 \
+@OS_LINUX_TRUE@	sg3_utils.8 sg_decode_sense.8 \
 @OS_LINUX_TRUE@	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 @OS_LINUX_TRUE@	sg_dd.8 sg_emc_trespass.8 sg_format.8 sg_get_config.8 \
 @OS_LINUX_TRUE@	sg_get_lba_status.8 sg_ident.8 sginfo.8 sg_inq.8 sg_logs.8 \
@@ -220,7 +220,7 @@ top_srcdir = @top_srcdir@
 @OS_LINUX_TRUE@	sg_write_buffer.8 sg_write_long.8 sg_write_same.8 sg_wr_mode.8
 
 @OS_OSF_TRUE@man_MANS = \
-@OS_OSF_TRUE@	sg3_utils.8 \
+@OS_OSF_TRUE@	sg3_utils.8 sg_decode_sense.8 \
 @OS_OSF_TRUE@	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 @OS_OSF_TRUE@	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 @OS_OSF_TRUE@	sg_inq.8 sg_logs.8 sg_luns.8 \
@@ -233,7 +233,7 @@ top_srcdir = @top_srcdir@
 @OS_OSF_TRUE@	sg_write_buffer.8 sg_write_long.8 sg_write_same.8 sg_wr_mode.8
 
 @OS_SOLARIS_TRUE@man_MANS = \
-@OS_SOLARIS_TRUE@	sg3_utils.8 \
+@OS_SOLARIS_TRUE@	sg3_utils.8 sg_decode_sense.8 \
 @OS_SOLARIS_TRUE@	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 @OS_SOLARIS_TRUE@	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 @OS_SOLARIS_TRUE@	sg_inq.8 sg_logs.8 sg_luns.8 \
@@ -246,7 +246,7 @@ top_srcdir = @top_srcdir@
 @OS_SOLARIS_TRUE@	sg_write_buffer.8 sg_write_long.8 sg_write_same.8 sg_wr_mode.8
 
 @OS_WIN32_CYGWIN_TRUE@man_MANS = \
-@OS_WIN32_CYGWIN_TRUE@	sg3_utils.8 \
+@OS_WIN32_CYGWIN_TRUE@	sg3_utils.8 sg_decode_sense.8 \
 @OS_WIN32_CYGWIN_TRUE@	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 @OS_WIN32_CYGWIN_TRUE@	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 @OS_WIN32_CYGWIN_TRUE@	sg_inq.8 sg_logs.8 sg_luns.8 sg_modes.8 sg_opcodes.8 \
@@ -259,7 +259,7 @@ top_srcdir = @top_srcdir@
 @OS_WIN32_CYGWIN_TRUE@	sg_write_buffer.8 sg_write_long.8 sg_write_same.8 sg_wr_mode.8
 
 @OS_WIN32_MINGW_TRUE@man_MANS = \
-@OS_WIN32_MINGW_TRUE@	sg3_utils.8 \
+@OS_WIN32_MINGW_TRUE@	sg3_utils.8 sg_decode_sense.8 \
 @OS_WIN32_MINGW_TRUE@	scsi_readcap.8  scsi_ready.8  scsi_start.8  scsi_stop.8 \
 @OS_WIN32_MINGW_TRUE@	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
 @OS_WIN32_MINGW_TRUE@	sg_inq.8 sg_logs.8 sg_luns.8 sg_modes.8 sg_opcodes.8 sg_persist.8 \
diff --git a/doc/sg3_utils.8 b/doc/sg3_utils.8
index 586d3db8..20927a46 100644
--- a/doc/sg3_utils.8
+++ b/doc/sg3_utils.8
@@ -1,4 +1,4 @@
-.TH SG3_UTILS "8" "September 2010" "sg3_utils\-1.30" SG3_UTILS
+.TH SG3_UTILS "8" "December 2010" "sg3_utils\-1.31" SG3_UTILS
 .SH NAME
 sg3_utils \- a package of utilities for sending SCSI commands
 .SH SYNOPSIS
@@ -391,7 +391,7 @@ CREDITS file and individual source files (in the 'src' directory).
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 1999\-2010 Douglas Gilbert
+Copyright \(co 1999\-2011 Douglas Gilbert
 .br
 Some utilities are distributed under a GPL version 2 license while
 others, usually more recent ones, are under a FreeBSD license. The files
diff --git a/doc/sg_decode_sense.8 b/doc/sg_decode_sense.8
new file mode 100644
index 00000000..40551b3c
--- /dev/null
+++ b/doc/sg_decode_sense.8
@@ -0,0 +1,79 @@
+.TH SG_DECODE_SENSE "8" "December 2010" "sg3_utils\-1.31" SG3_UTILS
+.SH NAME
+sg_decode_sense \- decode SCSI sense data
+.SH SYNOPSIS
+.B sg_decode_sense
+[\fI\-\-binary=FN\fR] [\fI\-\-help\fR] [\fI\-\-hex=FN\fR]
+[\fI\-\-status=SS\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
+[\fI\-\-write=WFN\fR] [H1 H2 H3 ...]
+.SH DESCRIPTION
+.\" Add any additional description here
+This utility takes SCSI sense data in binary or as a sequence of
+ASCII hexadecimal bytes and decodes it. The primary reference for the
+decoding is SPC\-3 ANSI INCITS 408-2005 and the most recent draft
+SPC\-4 revision 28 which can be found at http://www.t10.org .
+.PP
+SCSI sense data is often found in kernel log files as a result of
+something going wrong but may just be informative. It is often shown as
+a sequence of hexadecimal bytes, starting with 70, 71, 72 or 73.
+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.
+.PP
+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
+hexadecimal 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.
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-b\fR, \fB\-\-binary\fR=\fIFN\fR
+the sense data is read in binary from a file called \fIFN\fR.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+output the usage message then exit.
+.TP
+\fB\-H\fR, \fB\-\-in\fR=\fIFN\fR
+the sense data is read in ASCII hexadecimal from a file called \fIFN\fR.
+The sense data should appear as a sequence of bytes separated by space,
+comma, tab or newline. Everything from and including a hash symbol to the
+end of that line is ignored.
+.TP
+\fB\-s\fR, \fB\-\-status\fR=\fISS\fR
+where \fISS\fR is a SCSI status byte value, given in hexadecimal. The
+SCSI status byte is related to but distinct from sense data.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase the degree of verbosity (debug messages).
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+output version string then exit.
+.TP
+\fB\-w\fR, \fB\-\-write\fR=\fIWFN\fR
+writes the sense data out in binary to a file called \fIWFN\fR. If
+necessary \fIWFN\fR is created. If \fIWFN\fR exists then it is
+truncated prior to writing the sense data to it. This option is
+a convenience and may be helpful in converting the ASCII hexadecimal
+representation of sense data into the equivalent binary.
+.SH 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 sense data.
+.SH EXIT STATUS
+The exit status of sg_decode_sense is 0 when it is successful. Otherwise
+see the sg3_utils(8) man page.
+.SH AUTHORS
+Written by Douglas Gilbert.
+.SH "REPORTING BUGS"
+Report bugs to <dgilbert at interlog dot com>.
+.SH COPYRIGHT
+Copyright \(co 2010\-2011 Douglas Gilbert
+.br
+This software is distributed under a FreeBSD license. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.B sg_requests(sg3_utils)