Ubuntu Manpage: sg_timestamp - report or set timestamp on SCSI device

Provided by: sg3-utils_1.46-3ubuntu4_amd64

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 inclusive). 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 "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.
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.
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.

-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 TIMESTAMP
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.

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 timestamps. See the sg_logs utility. Vendor specific commands and pages  may  also
       be using timestamps.

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 readable 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_timestamp 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 © 2015-2018 Douglas Gilbert
       This software is distributed under a FreeBSD license. There is NO warranty; not even for  MERCHANTABILITY
       or FITNESS FOR A PARTICULAR PURPOSE.