sg_timestamp - report or set timestamp on SCSI device
sg_timestamp [--elapsed] [--help] [--hex] [--milliseconds=MS] [--no-timestamp] [--origin] [--raw] [--readonly] [--seconds=SECS] [--srep] [--verbose] [--version] DEVICE
SG_TIMESTAMP(8) SG3_UTILS SG_TIMESTAMP(8)
NAME
sg_timestamp - report or set timestamp on SCSI device
SYNOPSIS
sg_timestamp [--elapsed] [--help] [--hex] [--milliseconds=MS]
[--no-timestamp] [--origin] [--raw] [--readonly] [--seconds=SECS]
[--srep] [--verbose] [--version] DEVICE
DESCRIPTION
Sends a SCSI REPORT TIMESTAMP or SET TIMESTAMP command to the DEVICE.
These commands are found in the SPC-5 draft standard revision 7
(spc5r07.pdf).
If either the --milliseconds=MS or --seconds=SECS option is given (and
both can't be given) then the SET TIMESTAMP command is sent; otherwise
the REPORT TIMESTAMP command is sent.
The timestamp is sent and received from the DEVICE 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.
OPTIONS
Arguments to long options are mandatory for short options as well.
-e, --elapsed
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 inclu-
sive). If the number of days is 0 then '0 days' is not output
unless this option is given two or more times.
-h, --help
output the usage message then exit.
-H, --hex
output the response to REPORT TIMESTAMP in ASCII hexadecimal on
stderr. The response is not decoded.
-m, --milliseconds=MS
where MS is the number of milliseconds since 1970-01-01 00:00:00
UTC to set in the DEVICE with the SCSI SET TIMESTAMP command.
-N, --no-timestamp
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 --origin option).
-o, --origin
the REPORT TIMESTAMP returned parameter data contains a "time-
stamp 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.
T10 defines this field as "the most recent event that initial-
ized the returned device clock". The value 0 indicates a power
up of hard reset initialized the clock; 2 indicates a SET TIME-
STAMP initialized the clock while 3 indicates some other method
initialized the clock.
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_ORI-
GIN=<value>' is output.
-r, --raw
output the SCSI REPORT TIMESTAMP response (i.e. the data-out
buffer) in binary (to stdout). Note that the --origin and --srep
options are ignored when this option is given. Also all error
and verbose messages are output to stderr.
-R, --readonly
open the DEVICE read-only. The default action is to open the
DEVICE read-write.
-s, --seconds=SECS
where SECS is the number of seconds since 1970-01-01 00:00:00
UTC to set in the DEVICE with the SCSI SET TIMESTAMP command.
SECS is multiplied by 1000 before being used in the SET TIME-
STAMP command.
-S, --srep
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.
-v, --verbose
increase the level of verbosity, (i.e. debug output).
-V, --version
print the version string and then exit.
EXIT STATUS
The exit status of sg_timestamp is 0 when it is successful. Otherwise
see the sg3_utils(8) man page.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | system/storage/sg3_utils |
+---------------+--------------------------+
|Stability | Pass-through uncommitted |
+---------------+--------------------------+
NOTES
The TCMOS and the SCSIP bits in the Control extension mode page (see
sdparm) modify the actions of the timestamp held by a DEVICE.
Currently only the "Utilization usage rate based on date and time"
parameters within the Utilization log page (sbc4r09.pdf) use time-
stamps. See the sg_logs utility. Vendor specific commands and pages may
also be using timestamps.
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://sg.danny.cz/sg/p/sg3_utils-1.46.tgz.
Further information about this software can be found on the open source
community website at http://sg.danny.cz/sg/sg3_utils.html.
EXAMPLES
On Unix machines (e.g. Linux, FreeBSD and Solaris) the date command is
useful when working with timestamps.
To fetch the timestamp from a DEVICE and display it in a humanly read-
able form the following could be used:
# sg_timestamp -S /dev/sdb
1448993950
# date --date=@1448993950
Tue Dec 1 13:19:10 EST 2015
# date -R --date="@1448993950"
Tue, 01 Dec 2015 13:19:10 -0500
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_time-
stamp and date commands can be combined using backquotes:
# date -R --date=@`sg_timestamp -S /dev/sdc`
Wed, 16 Dec 2015 20:12:59 -0500
To set the timestamp on the DEVICE to now (approximately) the following
could be used:
# date +%s
1448993955
# sg_timestamp --seconds=1448993955 /dev/sdb
Those two command lines could be combined into one by using backquotes:
# sg_timestamp --seconds=`date +%s` /dev/sdb
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright (C) 2015-2018 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO war-
ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
POSE.
SEE ALSO
sdparm(sdparm), sg_logs(sg3_utils)
sg3_utils-1.43 April 2018 SG_TIMESTAMP(8)