.TH SG_TIMESTAMP "8" "December 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). The sg_timestamp and
date commands can be combined using backquotes:
.PP
   # date \-R \-\-date="@`sg_timestamp \-S /dev/sdc`"
.br
Wed, 16 Dec 2015 20:12:59 \-0500
.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)