sg_rep_density: new utility for decoding the response of Report density support command [ssc (tape)]

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

4 files changed, 112 insertions, 15 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 3cb12ebf..8a09982e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -7,9 +7,9 @@ man_MANS = \
 	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_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_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 \
diff --git a/doc/Makefile.in b/doc/Makefile.in
index c1e2bdbd..b69648e5 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -293,15 +293,15 @@ man_MANS = scsi_mandat.8 scsi_readcap.8 scsi_ready.8 scsi_satl.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_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) \
+	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) \
 	$(am__append_5)
 CLEANFILES = $(am__append_2) $(am__append_4) $(am__append_6)
 all: all-am
diff --git a/doc/sg_rep_density.8 b/doc/sg_rep_density.8
new file mode 100644
index 00000000..6734796a
--- /dev/null
+++ b/doc/sg_rep_density.8
@@ -0,0 +1,97 @@
+.TH SG_REP_DENSITY "8" "January 2022" "sg3_utils\-1.48" SG3_UTILS
+.SH NAME
+sg_rep_density \- send SCSI REPORT DENSITY SUPPORT command
+.SH SYNOPSIS
+.B sg_rep_density
+[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-maxlen=LEN\fR]
+[\fI\-\-media\fR] [\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-typem\fR]
+[\fI\-\-verbose\fR] [\fI\-\-version\fR]
+\fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Sends a SCSI REPORT DENSITY command to \fIDEVICE\fR and outputs the data
+returned. This command is tape drive specific. This command is found in
+the SSC\-5 draft standard, revision 6 (ssc5r06.pdf). This command was
+present in the SSC\-2 standard (ANSI INCITS 380\-2003).
+.PP
+By default this utility requests the density code descriptors supported by
+the \fIDEVICE\fR (e.g. a tape drive) and decodes the response. If the
+\fI\-\-typem\fR option is given it fetches the medium type descriptors
+supported by the \fIDEVICE\fR and decodes the response. When the
+\fI\-\-media\fR option is given the density code or medium type descriptors
+supported by the media inside the \fIDEVICE\fR (e.g. a tape cartridge) are
+fetched.
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+output the usage message then exit.
+.TP
+\fB\-H\fR, \fB\-\-hex\fR
+output the response in hexadecimal to stdout. When used once the whole
+response is output in ASCII hexadecimal, prefixed by an address (starting at
+0) on each line. When used twice the whole response is output in hexadecimal
+with no leading address (on each line).
+.br
+Using this option three times will produce output that can be redirected to
+a file and later given to another invocation using the \fI\-\-inhex=FN\fR
+option.
+.TP
+\fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR
+where \fIFN\fR is a file name whose contents are assumed to be ASCII
+hexadecimal. If \fIDEVICE\fR is also given then \fIDEVICE\fR is ignored,
+a warning is issued and the utility continues, decoding the file named
+\fIFN\fR. See the "FORMAT OF FILES CONTAINING ASCII HEX" section in the
+sg3_utils manpage for more information. If the \fI\-\-raw\fR option is
+also given then the contents of \fIFN\fR are treated as binary.
+.TP
+\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
+where \fILEN\fR is the (maximum) response length in bytes. It is placed in
+the cdb's "allocation length" field. If not given (or \fILEN\fR is zero)
+then 8192 is used. The maximum allowed value of \fILEN\fR is 65535.
+.TP
+\fB\-M\fR, \fB\-\-media\fR
+sets the MEDIA bit in the cdb which causes the density codes (or medium
+types) supported by the tape cartridge in the drive to be placed in the
+response. The default is to request the density codes (or medium types)
+supported by the tape drive itself.
+.br
+If there is no "medium" (e.g. tape cartridge) present in the drive the SCSI
+command will fail with a "not ready" sense key.
+.TP
+\fB\-r\fR, \fB\-\-raw\fR
+output the SCSI response (i.e. the data\-out buffer) in binary (to stdout)
+unless the \fI\-\-inhex=FN\fR option is given.
+.br
+When used together with the \fI\-\-inhex=FN\fR option then the contents of
+\fIFN\fR are treated as binary (rather than hexadecimal).
+.TP
+\fB\-R\fR, \fB\-\-readonly\fR
+open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag).
+The default is to open it read\-write.
+.TP
+\fB\-t\fR, \fB\-\-typem\fR
+sets the MEDIUM TYPE bit in the cdb which causes the medium types supported
+by the tape drive (or tape cartridge) to be placed in the response. The
+default is to request the density codes.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase the level of verbosity, (i.e. debug output).
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print the version string and then exit.
+.SH EXIT STATUS
+The exit status of sg_rep_density 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 2022 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 sg3_utils(sg3_utils)
diff --git a/doc/sg_rep_pip.8 b/doc/sg_rep_pip.8
index d054cd2b..fb615ee7 100644
--- a/doc/sg_rep_pip.8
+++ b/doc/sg_rep_pip.8
@@ -1,4 +1,4 @@
-.TH SG_REP_PIP "8" "July 2020" "sg3_utils\-1.46" SG3_UTILS
+.TH SG_REP_PIP "8" "January 2022" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg_rep_pip \- send SCSI REPORT PROVISIONING INITIALIZATION PATTERN command
 .SH SYNOPSIS
@@ -11,7 +11,7 @@ sg_rep_pip \- send SCSI REPORT PROVISIONING INITIALIZATION PATTERN command
 .PP
 Sends a SCSI REPORT PROVISIONING INITIALIZATION PATTERN command to
 \fIDEVICE\fR and outputs the data returned. This command is found in the
-SBC\-4 draft standard, revision 21 (sbc\4r21.pdf).
+SBC\-4 draft standard, revision 21 (sbc4r21.pdf).
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 .TP
@@ -50,7 +50,7 @@ Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2020 Douglas Gilbert
+Copyright \(co 2020\-2022 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.