sg_timestamp: new, to report or set timestamp

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

3 files changed, 128 insertions, 7 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 730dfa8c..43852c4f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -10,9 +10,9 @@ man_MANS = \
 	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_senddiag.8 sg_ses.8 sg_ses_microcode.8 sg_start.8 sg_stpg.8 \
-	sg_sync.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_zone.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_zone.8
 CLEANFILES =
 
 if OS_LINUX
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 95261c62..4e981418 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -278,10 +278,10 @@ man_MANS = scsi_mandat.8 scsi_readcap.8 scsi_ready.8 scsi_satl.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_senddiag.8 sg_ses.8 sg_ses_microcode.8 sg_start.8 sg_stpg.8 \
-	sg_sync.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_zone.8 $(am__append_1) $(am__append_3) \
-	$(am__append_5)
+	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_zone.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_timestamp.8 b/doc/sg_timestamp.8
new file mode 100644
index 00000000..f8dd19dc
--- /dev/null
+++ b/doc/sg_timestamp.8
@@ -0,0 +1,121 @@
+.TH SG_TIMESTAMP "8" "November 2015" "sg3_utils\-1.42" SG3_UTILS
+.SH NAME
+sg_timestamp \- report or set timestamp on SCSI device
+.SH SYNOPSIS
+.B sg_timestamp
+[\fI\-\-help\fR] [\fI\-\-milliseconds=MS\fR] [\fI\-\-origin\fR]
+[\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-seconds=SEC\fR] [\fI\-\-srep\fR]
+[\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Sends a SCSI REPORT TIMESTAMP or SET TIMESTAMP command to the \fIDEVICE\fR.
+These commands are found in the SPC\-5 draft standard revision
+7 (spc5r07.pdf).
+.PP
+If either the \fI\-\-milliseconds=MS\fR or \fI\-\-seconds=SEC\fR option is
+given (and both can't be given) then the SET TIMESTAMP command is sent;
+otherwise the REPORT TIMESTAMP command is sent.
+.PP
+The timestamp is sent and received from the \fIDEVICE\fR as the number of
+milliseconds since the epoch of 1970-01-01 00:00:00 UTC and is held in a 48
+bit unsigned integer. That same epoch is used by Unix machines, but they
+usually hold the number of seconds since that epoch. The Unix date command
+and especally its "+%s" format is useful in converting to and from
+timestamps and more humanly readable forms. See the EXAMPLES section below.
+.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\-m\fR, \fB\-\-milliseconds\fR=\fIMS\fR
+where \fIMS\fR is the number of milliseconds since 1970-01-01 00:00:00 UTC
+to set in the \fIDEVICE\fR with the SCSI SET TIMESTAMP command.
+.TP
+\fB\-o\fR, \fB\-\-origin\fR
+the REPORT TIMESTAMP returned parameter data contains a "timestamp origin"
+field. When this option is given, that field is decoded and printed out
+before the timestamp value is output. The default action (i.e. when the
+option is not given) is not to print out this decoded field.
+.TP
+\fB\-r\fR, \fB\-\-raw\fR
+output the SCSI REPORT TIMESTAMP response (i.e. the data-out buffer) in
+binary (to stdout). Note that the \fI\-\-origin\fR and \fI\-\-srep\fR
+options are ignored when this option is given. Also all error and
+verbose messages are output to stderr.
+.TP
+\fB\-R\fR, \fB\-\-readonly\fR
+open the \fIDEVICE\fR read\-only. The default action is to open the
+\fIDEVICE\fR read\-write.
+.TP
+\fB\-s\fR, \fB\-\-seconds\fR=\fISEC\fR
+where \fISEC\fR is the number of seconds since 1970-01-01 00:00:00 UTC
+to set in the \fIDEVICE\fR with the SCSI SET TIMESTAMP command. \fISEC\fR
+is multiplied by 1000 before being used in the SET TIMESTAMP command.
+.TP
+\fB\-S\fR, \fB\-\-srep\fR
+report the number of seconds since 1970-01-01 00:00:00 UTC. This is done
+by dividing by 1000 the value returned by the SCSI REPORT TIMESTAMP command.
+.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_timestamp is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.SH NOTES
+The TCMOS and the SCSIP bits in the Control extension mode page (see sdparm)
+modify the actions of the timestamp held by a \fIDEVICE\fR.
+.PP
+Currently only the "Utilization usage rate based on date and time" parameters
+within the Utilization log page (sbc4r09.pdf) use timestamps. See the sg_logs
+utility. Vendor specific commands and pages may also be using timestamps.
+.SH EXAMPLES
+On Unix machines (e.g. Linux, FreeBSD and Solaris) the date command is useful
+when working with timestamps.
+.PP
+To fetch the timestamp from a \fIDEVICE\fR and display it in a humanly
+readable form the following could be used:
+.PP
+   # sg_timestamp -S /dev/sdb
+.br
+1448993950
+.br
+   # date --date="@1448993950"
+.br
+Tue Dec  1 13:19:10 EST 2015
+.br
+   # date -R --date="@1448993950"
+.br
+Tue, 01 Dec 2015 13:19:10 -0500
+.PP
+The latter two date commands show different forms of the same date (i.e.
+1448993950 seconds since 1970-01-01 00:00:00 UTC).
+.PP
+To set the timestamp on the \fIDEVICE\fR to now (approximately) the
+following could be used:
+.PP
+   # date +%s
+.br
+1448993955
+.br
+   # sg_timestamp --seconds=1448993955 /dev/sdb
+.PP
+Those two command lines could be combined into one by using backquotes:
+.PP
+   # sg_timestamp --seconds=`date +%s` /dev/sdb
+.PP
+.SH AUTHORS
+Written by Douglas Gilbert.
+.SH "REPORTING BUGS"
+Report bugs to <dgilbert at interlog dot com>.
+.SH COPYRIGHT
+Copyright \(co 2015 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 sdparm(sdparm), sg_logs(sg3_utils)