sg_inq+sg_vpd: more JSON work (tpc)

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

7 files changed, 56 insertions, 29 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8a09982e..81f4f52c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,10 +1,10 @@
 
 man_MANS = \
 	scsi_mandat.8 scsi_readcap.8 scsi_ready.8 scsi_satl.8 scsi_start.8 \
-	scsi_stop.8 scsi_temperature.8 sg3_utils.8 sg_bg_ctl.8 \
-	sg_compare_and_write.8 sg_decode_sense.8 sg_format.8 sg_get_config.8 \
-	sg_get_elem_status.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 \
+	scsi_stop.8 scsi_temperature.8 sg3_utils.8 sg3_utils_json.8
+	sg_bg_ctl.8 sg_compare_and_write.8 sg_decode_sense.8 sg_format.8
+	sg_get_config.8 sg_get_elem_status.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 \
 	sg_prevent.8 sg_raw.8 sg_rdac.8 sg_read_attr.8 \
 	sg_read_block_limits.8 sg_read_buffer.8 sg_read_long.8 sg_readcap.8 \
 	sg_reassign.8 sg_referrals.8 sg_rep_density.8 sg_rep_pip.8 \
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 8b8e2820..8a4ba430 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -188,6 +188,7 @@ EGREP = @EGREP@
 ETAGS = @ETAGS@
 EXEEXT = @EXEEXT@
 FGREP = @FGREP@
+FILECMD = @FILECMD@
 GETOPT_O_FILES = @GETOPT_O_FILES@
 GREP = @GREP@
 INSTALL = @INSTALL@
@@ -287,21 +288,7 @@ top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
 man_MANS = scsi_mandat.8 scsi_readcap.8 scsi_ready.8 scsi_satl.8 \
 	scsi_start.8 scsi_stop.8 scsi_temperature.8 sg3_utils.8 \
-	sg_bg_ctl.8 sg_compare_and_write.8 sg_decode_sense.8 \
-	sg_format.8 sg_get_config.8 sg_get_elem_status.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 sg_prevent.8 sg_raw.8 \
-	sg_rdac.8 sg_read_attr.8 sg_read_block_limits.8 \
-	sg_read_buffer.8 sg_read_long.8 sg_readcap.8 sg_reassign.8 \
-	sg_referrals.8 sg_rep_density.8 sg_rep_pip.8 sg_rep_zones.8 \
-	sg_requests.8 sg_reset_wp.8 sg_rmsn.8 sg_rtpg.8 sg_safte.8 \
-	sg_sanitize.8 sg_sat_identify.8 sg_sat_phy_event.8 \
-	sg_sat_read_gplog.8 sg_sat_set_features.8 sg_seek.8 \
-	sg_senddiag.8 sg_ses.8 sg_ses_microcode.8 sg_start.8 sg_stpg.8 \
-	sg_stream_ctl.8 sg_sync.8 sg_timestamp.8 sg_turs.8 sg_unmap.8 \
-	sg_verify.8 sg_vpd.8 sg_wr_mode.8 sg_write_buffer.8 \
-	sg_write_long.8 sg_write_same.8 sg_write_verify.8 sg_write_x.8 \
-	sg_zone.8 sg_z_act_query.8 $(am__append_1) $(am__append_3) \
+	sg3_utils_json.8 $(am__append_1) $(am__append_3) \
 	$(am__append_5)
 CLEANFILES = $(am__append_2) $(am__append_4) $(am__append_6)
 all: all-am
@@ -547,6 +534,19 @@ uninstall-man: uninstall-man8
 
 .PRECIOUS: Makefile
 
+	sg_bg_ctl.8 sg_compare_and_write.8 sg_decode_sense.8 sg_format.8
+	sg_get_config.8 sg_get_elem_status.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 \
+	sg_prevent.8 sg_raw.8 sg_rdac.8 sg_read_attr.8 \
+	sg_read_block_limits.8 sg_read_buffer.8 sg_read_long.8 sg_readcap.8 \
+	sg_reassign.8 sg_referrals.8 sg_rep_density.8 sg_rep_pip.8 \
+	sg_rep_zones.8 sg_requests.8 sg_reset_wp.8 sg_rmsn.8 sg_rtpg.8 \
+	sg_safte.8 sg_sanitize.8 sg_sat_identify.8 sg_sat_phy_event.8 \
+	sg_sat_read_gplog.8 sg_sat_set_features.8 sg_seek.8 sg_senddiag.8 \
+	sg_ses.8 sg_ses_microcode.8 sg_start.8 sg_stpg.8 sg_stream_ctl.8 \
+	sg_sync.8 sg_timestamp.8 sg_turs.8 sg_unmap.8 sg_verify.8 sg_vpd.8 \
+	sg_wr_mode.8 sg_write_buffer.8 sg_write_long.8 sg_write_same.8 \
+	sg_write_verify.8 sg_write_x.8 sg_zone.8 sg_z_act_query.8
 @OS_LINUX_TRUE@sg_scan.8: sg_scan.8.linux
 @OS_LINUX_TRUE@	cp -p $< $@
 @OS_WIN32_MINGW_TRUE@sg_scan.8: sg_scan.8.win32
diff --git a/doc/sg3_utils.8 b/doc/sg3_utils.8
index ab592361..1eb2f4af 100644
--- a/doc/sg3_utils.8
+++ b/doc/sg3_utils.8
@@ -1,4 +1,4 @@
-.TH SG3_UTILS "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS
+.TH SG3_UTILS "8" "August 2022" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg3_utils \- a package of utilities for sending SCSI commands
 .SH SYNOPSIS
diff --git a/doc/sg3_utils_json.8 b/doc/sg3_utils_json.8
index be2983a6..788f19c4 100644
--- a/doc/sg3_utils_json.8
+++ b/doc/sg3_utils_json.8
@@ -1,6 +1,6 @@
-.TH SG3_UTILS "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS
+.TH SG3_UTILS_JSON "8" "August 2022" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
-sg3_utils \- JSON output for some utilities
+sg3_utils_json \- JSON output for some sg3_utils utilities
 .SH SYNOPSIS
 .B sg_*
 \fI\-\-json[=JO]\fR [\fIOTHER_OPTIONS\fR] [\fIDEVICE\fR]
diff --git a/doc/sg_decode_sense.8 b/doc/sg_decode_sense.8
index 440cb0b5..ea68eb16 100644
--- a/doc/sg_decode_sense.8
+++ b/doc/sg_decode_sense.8
@@ -4,9 +4,10 @@ sg_decode_sense \- decode SCSI sense and related data
 .SH SYNOPSIS
 .B sg_decode_sense
 [\fI\-\-binary=BFN\fR] [\fI\-\-cdb\fR] [\fI\-\-err=ES\fR] [\fI\-\-file=HFN\fR]
-[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-inhex=HFN\fR] [\fI\-\-nodecode\fR]
-[\fI\-\-nospace\fR] [\fI\-\-status=SS\fR] [\fI\-\-verbose\fR]
-[\fI\-\-version\fR] [\fI\-\-write=WFN\fR] [H1 H2 H3 ...]
+[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-inhex=HFN\fR]
+[\fI\-\-ignore\-first\fR] [\fI\-\-nodecode\fR] [\fI\-\-nospace\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
@@ -97,6 +98,14 @@ this option three times (e.g. '\-HHH').
 same action as \fI\-\-file=HFN\fR. This option was added for compatibility
 with other utilities in this package that have a \fI\-\-inhex=\fR option.
 .TP
+\fB\-I\fR, \fB\-\-ignore\-first\fR
+many programs that output hex bytes (e.g. 'hexdump \-C') have a running
+count (or index) in the first column of each line. This option ignores the
+first hexadecimal value on each line. This option has no effect if
+\fI\-\-binary=BFN\fR or \fI\-\-nospace\fR are given. Blank lines and any
+character from and after "#" on a line are ignored. Useful with the
+\fI\-\-file=HFN\fR and \fI\-\-nodecode\fR options.
+.TP
 \fB\-N\fR, \fB\-\-nodecode\fR
 Do not decode the given data as sense or a cdb. Useful when arbitrary data
 is given (e.g. when converting hex to binary or vice versa).
diff --git a/doc/sg_inq.8 b/doc/sg_inq.8
index 0f02d2a3..76a5d97f 100644
--- a/doc/sg_inq.8
+++ b/doc/sg_inq.8
@@ -25,7 +25,9 @@ This utility, when \fIDEVICE\fR is given, sends a SCSI INQUIRY command to it
 then outputs the response. All SCSI devices are meant to respond to
 a "standard" INQUIRY command with at least a 36 byte response (in SCSI 2 and
 higher). An INQUIRY is termed as "standard" when both the EVPD and CmdDt (now
-obsolete) bits are clear.
+obsolete) bits are clear. Formally (i.e. as per SPC stardards) the name of
+a standard INQUIRY response is the "standard INQUIRY data format" but here
+the "standard INQUIRY response" is used as it is shorter and more descriptive.
 .PP
 Alternatively the \fI\-\-inhex=FN\fR option can be given. In this case
 \fIFN\fR is assumed to be a file name ('\-' for stdin) containing ASCII
@@ -125,7 +127,8 @@ page is given it prints out information in the form:
 useful for tools like udev(7) in Linux.
 .TP
 \fB\-E\fR, \fB\-x\fR, \fB\-\-extended\fR
-prints the extended INQUIRY VPD page [0x86].
+prints the extended INQUIRY VPD page [0x86]. It has the same effect
+as giving the \fI\-\-page=ei\fR option.
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 print out the usage message then exit. When used twice, after the
@@ -148,7 +151,8 @@ later invocation with the \fI\-\-inhex=FN\fR option, use the '\-HHHH'
 option (e.g. 'sg_inq \-p di \-HHHH /dev/sg3 > dev_id.hex').
 .TP
 \fB\-i\fR, \fB\-\-id\fR
-prints the device identification VPD page [0x83].
+prints the device identification VPD page [0x83]. It has the same effect
+as giving the \fI\-\-page=di\fR option.
 .TP
 \fB\-I\fR, \fB\-\-inhex\fR=\fIFN\fR
 \fIFN\fR is expected to be a file name (or '\-' for stdin) which contains
@@ -338,6 +342,20 @@ get the controller's Identify decoded use the \fI\-\-only\fR option.
 It is possible that even though the \fIDEVICE\fR presents as a NVMe device,
 it has a SNTL and accepts SCSI commands. In this case to send a SCSI INQUIRY
 command (and fetch its VPD pages) use the sg_vpd(8) utility.
+.SH SG_INQ and SG_VPD
+Both these utilities have much in common since VPD pages are fetched with the
+SCSI INQUIRY command. As more VPD pages have been added (and existing pages
+expanded) the newer ones were only decoded with sg_vpd. Recently with the
+optional JSON output work, it was decided to place all VPD page decoding in
+a source file called sg_vpd_common.c that is linked in by both sg_inq and
+sg_vpd.
+.PP
+This means that the VPD page decoding capabilities of both sg_inq and sg_vpd
+will be the same. Their default actions remain as they were, namely when
+sg_inq is used without command line options, it decodes the "standard INQUIRY
+data format" (usually called the "standard INQUIRY response") response while
+when sg_vpd is used without options, it decodes the "Supported VPD pages" VPD
+page.
 .SH EXIT STATUS
 The exit status of sg_inq is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page.
diff --git a/doc/sg_vpd.8 b/doc/sg_vpd.8
index 7f681604..45f496c3 100644
--- a/doc/sg_vpd.8
+++ b/doc/sg_vpd.8
@@ -1,4 +1,4 @@
-.TH SG_VPD "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS
+.TH SG_VPD "8" "August 2022" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg_vpd \- fetch SCSI VPD page and/or decode its response
 .SH SYNOPSIS