sg_timestamp(8)

1SG_TIMESTAMP(8)                    SG3_UTILS                   SG_TIMESTAMP(8)
2
3
4

NAME

6       sg_timestamp - report or set timestamp on SCSI device
7

SYNOPSIS

9       sg_timestamp  [--help]  [--milliseconds=MS] [--origin] [--raw] [--read‐
10       only] [--seconds=SEC] [--srep] [--verbose] [--version] DEVICE
11

DESCRIPTION

13       Sends a SCSI REPORT TIMESTAMP or SET TIMESTAMP command to  the  DEVICE.
14       These  commands  are  found  in  the  SPC-5  draft  standard revision 7
15       (spc5r07.pdf).
16
17       If either the --milliseconds=MS or --seconds=SEC option is  given  (and
18       both  can't be given) then the SET TIMESTAMP command is sent; otherwise
19       the REPORT TIMESTAMP command is sent.
20
21       The timestamp is sent and received from the DEVICE  as  the  number  of
22       milliseconds  since the epoch of 1970-01-01 00:00:00 UTC and is held in
23       a 48 bit unsigned integer. That same epoch is used  by  Unix  machines,
24       but  they usually hold the number of seconds since that epoch. The Unix
25       date command and especally its "+%s" format is useful in converting  to
26       and  from  timestamps and more humanly readable forms. See the EXAMPLES
27       section below.
28

OPTIONS

30       Arguments to long options are mandatory for short options as well.
31
32       -h, --help
33              output the usage message then exit.
34
35       -m, --milliseconds=MS
36              where MS is the number of milliseconds since 1970-01-01 00:00:00
37              UTC to set in the DEVICE with the SCSI SET TIMESTAMP command.
38
39       -o, --origin
40              the  REPORT  TIMESTAMP returned parameter data contains a "time‐
41              stamp origin" field. When this option is given,  that  field  is
42              decoded  and  printed  out before the timestamp value is output.
43              The default action (i.e. when the option is not given) is not to
44              print out this decoded field.
45
46       -r, --raw
47              output  the  SCSI  REPORT  TIMESTAMP response (i.e. the data-out
48              buffer) in binary (to stdout). Note that the --origin and --srep
49              options  are  ignored  when this option is given. Also all error
50              and verbose messages are output to stderr.
51
52       -R, --readonly
53              open the DEVICE read-only. The default action  is  to  open  the
54              DEVICE read-write.
55
56       -s, --seconds=SEC
57              where SEC is the number of seconds since 1970-01-01 00:00:00 UTC
58              to set in the DEVICE with the SCSI SET TIMESTAMP command. SEC is
59              multiplied  by  1000 before being used in the SET TIMESTAMP com‐
60              mand.
61
62       -S, --srep
63              report the number of seconds since 1970-01-01 00:00:00 UTC. This
64              is  done  by  dividing  by  1000  the value returned by the SCSI
65              REPORT TIMESTAMP command.
66
67       -v, --verbose
68              increase the level of verbosity, (i.e. debug output).
69
70       -V, --version
71              print the version string and then exit.
72

EXIT STATUS

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

NOTES

78       The  TCMOS  and  the SCSIP bits in the Control extension mode page (see
79       sdparm) modify the actions of the timestamp held by a DEVICE.
80
81       Currently only the "Utilization usage rate  based  on  date  and  time"
82       parameters  within  the  Utilization  log  page (sbc4r09.pdf) use time‐
83       stamps. See the sg_logs utility. Vendor specific commands and pages may
84       also be using timestamps.
85

EXAMPLES

87       On  Unix machines (e.g. Linux, FreeBSD and Solaris) the date command is
88       useful when working with timestamps.
89
90       To fetch the timestamp from a DEVICE and display it in a humanly  read‐
91       able form the following could be used:
92
93          # sg_timestamp -S /dev/sdb
94       1448993950
95          # date --date="@1448993950"
96       Tue Dec  1 13:19:10 EST 2015
97          # date -R --date="@1448993950"
98       Tue, 01 Dec 2015 13:19:10 -0500
99
100       The  latter  two  date  commands  show different forms of the same date
101       (i.e.  1448993950 seconds since 1970-01-01 00:00:00 UTC). The  sg_time‐
102       stamp and date commands can be combined using backquotes:
103
104          # date -R --date="@`sg_timestamp -S /dev/sdc`"
105       Wed, 16 Dec 2015 20:12:59 -0500
106
107       To set the timestamp on the DEVICE to now (approximately) the following
108       could be used:
109
110          # date +%s
111       1448993955
112          # sg_timestamp --seconds=1448993955 /dev/sdb
113
114       Those two command lines could be combined into one by using backquotes:
115
116          # sg_timestamp --seconds=`date +%s` /dev/sdb
117

AUTHORS

119       Written by Douglas Gilbert.
120

REPORTING BUGS

122       Report bugs to <dgilbert at interlog dot com>.
123

COPYRIGHT

125       Copyright © 2015 Douglas Gilbert
126       This software is distributed under a FreeBSD license. There is NO  war‐
127       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
128       POSE.
129