Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, February 9, 2022

sg_timestamp (8)


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)

       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

       Sends  a  SCSI REPORT TIMESTAMP or SET TIMESTAMP command to the DEVICE.
       These commands are  found  in  the  SPC-5  draft  standard  revision  7

       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.

       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.

       The  exit  status of sg_timestamp is 0 when it is successful. Otherwise
       see the sg3_utils(8) man page.

       See attributes(7) for descriptions of the following attributes:

       |Availability   | system/storage/sg3_utils |
       |Stability      | Pass-through uncommitted |

       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-

       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.

       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
          # 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
          # 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

       Written by Douglas Gilbert.

       Report bugs to <dgilbert at interlog dot com>.

       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-

       sdparm(sdparm), sg_logs(sg3_utils)

sg3_utils-1.43                    April 2018                   SG_TIMESTAMP(8)