156 lines
6.1 KiB
Groff
156 lines
6.1 KiB
Groff
.TH SG_TIMESTAMP "8" "April 2018" "sg3_utils\-1.43" SG3_UTILS
|
|
.SH NAME
|
|
sg_timestamp \- report or set timestamp on SCSI device
|
|
.SH SYNOPSIS
|
|
.B sg_timestamp
|
|
[\fI\-\-elapsed\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR]
|
|
[\fI\-\-milliseconds=MS\fR] [\fI\-\-no\-timestamp\fR] [\fI\-\-origin\fR]
|
|
[\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-seconds=SECS\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=SECS\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 especially 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\-e\fR, \fB\-\-elapsed\fR
|
|
assume the timestamp in the REPORT TIMESTAMP is an elapsed time from an
|
|
event such as a power cycle or hard reset and format the output as '<n>
|
|
days hh:mm:ss.xxx' where hh is hours (00 to 23 inclusive); mm is
|
|
minutes (00 to 59 inclusive); ss is seconds (00 to 59 inclusive) and xxx
|
|
is milliseconds (000 to 999 inclusive). If the number of days is 0
|
|
then '0 days' is not output unless this option is given two or more times.
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
output the usage message then exit.
|
|
.TP
|
|
\fB\-H\fR, \fB\-\-hex\fR
|
|
output the response to REPORT TIMESTAMP in ASCII hexadecimal on stderr. The
|
|
response is not decoded.
|
|
.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\-N\fR, \fB\-\-no\-timestamp\fR
|
|
when REPORT TIMESTAMP is called this option suppress the output of the
|
|
timestamp value (in either seconds or milliseconds). This may be useful
|
|
in uncluttering the output when trying to decode the timestamp origin (see
|
|
the \fI\-\-origin\fR option).
|
|
.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.
|
|
.br
|
|
T10 defines this field as "the most recent event that initialized the
|
|
returned device clock". The value 0 indicates a power up of hard reset
|
|
initialized the clock; 2 indicates a SET TIMESTAMP initialized the
|
|
clock while 3 indicates some other method initialized the clock.
|
|
.br
|
|
When used once a descriptive string is output (in a line before the
|
|
timestamp value). When used twice the value of the TIMESTAMP ORIGIN
|
|
field is output (in decimal, a value between 0 and 7 inclusive). When
|
|
used thrice a line of the form 'TIMESTAMP_ORIGIN=<value>' is output.
|
|
.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=\fISECS\fR
|
|
where \fISECS\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. \fISECS\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\-2018 Douglas Gilbert
|
|
.br
|
|
This software is distributed under a BSD\-2\-Clause 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)
|