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    [--elapsed]    [--help]   [--hex]   [--milliseconds=MS]
10       [--no-timestamp]  [--origin]  [--raw]   [--readonly]   [--seconds=SECS]
11       [--srep] [--verbose] [--version] DEVICE
12

DESCRIPTION

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

OPTIONS

31       Arguments to long options are mandatory for short options as well.
32
33       -e, --elapsed
34              assume  the timestamp in the REPORT TIMESTAMP is an elapsed time
35              from an event such as a power cycle or hard reset and format the
36              output  as  '<n>  days hh:mm:ss.xxx' where hh is hours (00 to 23
37              inclusive); mm is minutes (00 to 59 inclusive);  ss  is  seconds
38              (00  to 59 inclusive) and xxx is milliseconds (000 to 999 inclu‐
39              sive). If the number of days is 0 then '0 days'  is  not  output
40              unless this option is given two or more times.
41
42       -h, --help
43              output the usage message then exit.
44
45       -H, --hex
46              output  the response to REPORT TIMESTAMP in ASCII hexadecimal on
47              stderr. The response is not decoded.
48
49       -m, --milliseconds=MS
50              where MS is the number of milliseconds since 1970-01-01 00:00:00
51              UTC to set in the DEVICE with the SCSI SET TIMESTAMP command.
52
53       -N, --no-timestamp
54              when  REPORT TIMESTAMP is called this option suppress the output
55              of the timestamp value (in either seconds or milliseconds). This
56              may  be  useful in uncluttering the output when trying to decode
57              the timestamp origin (see the --origin option).
58
59       -o, --origin
60              the REPORT TIMESTAMP returned parameter data contains  a  "time‐
61              stamp  origin"  field.  When this option is given, that field is
62              decoded and printed out before the timestamp  value  is  output.
63              The default action (i.e. when the option is not given) is not to
64              print out this decoded field.
65              T10 defines this field as "the most recent event  that  initial‐
66              ized  the  returned device clock". The value 0 indicates a power
67              up of hard reset initialized the clock; 2 indicates a SET  TIME‐
68              STAMP  initialized the clock while 3 indicates some other method
69              initialized the clock.
70              When used once a descriptive string is output (in a line  before
71              the timestamp value). When used twice the value of the TIMESTAMP
72              ORIGIN field is output (in decimal, a  value  between  0  and  7
73              inclusive).  When used thrice a line of the form 'TIMESTAMP_ORI‐
74              GIN=<value>' is output.
75
76       -r, --raw
77              output the SCSI REPORT TIMESTAMP  response  (i.e.  the  data-out
78              buffer) in binary (to stdout). Note that the --origin and --srep
79              options are ignored when this option is given.  Also  all  error
80              and verbose messages are output to stderr.
81
82       -R, --readonly
83              open  the  DEVICE  read-only.  The default action is to open the
84              DEVICE read-write.
85
86       -s, --seconds=SECS
87              where SECS is the number of seconds  since  1970-01-01  00:00:00
88              UTC  to  set  in the DEVICE with the SCSI SET TIMESTAMP command.
89              SECS is multiplied by 1000 before being used in  the  SET  TIME‐
90              STAMP command.
91
92       -S, --srep
93              report the number of seconds since 1970-01-01 00:00:00 UTC. This
94              is done by dividing by 1000  the  value  returned  by  the  SCSI
95              REPORT TIMESTAMP command.
96
97       -v, --verbose
98              increase the level of verbosity, (i.e. debug output).
99
100       -V, --version
101              print the version string and then exit.
102

EXIT STATUS

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

NOTES

108       The TCMOS and the SCSIP bits in the Control extension  mode  page  (see
109       sdparm) modify the actions of the timestamp held by a DEVICE.
110
111       Currently  only  the  "Utilization  usage  rate based on date and time"
112       parameters within the Utilization  log  page  (sbc4r09.pdf)  use  time‐
113       stamps. See the sg_logs utility. Vendor specific commands and pages may
114       also be using timestamps.
115

EXAMPLES

117       On Unix machines (e.g. Linux, FreeBSD and Solaris) the date command  is
118       useful when working with timestamps.
119
120       To  fetch the timestamp from a DEVICE and display it in a humanly read‐
121       able form the following could be used:
122
123          # sg_timestamp -S /dev/sdb
124       1448993950
125          # date --date=@1448993950
126       Tue Dec  1 13:19:10 EST 2015
127          # date -R --date="@1448993950"
128       Tue, 01 Dec 2015 13:19:10 -0500
129
130       The latter two date commands show different  forms  of  the  same  date
131       (i.e.   1448993950 seconds since 1970-01-01 00:00:00 UTC). The sg_time‐
132       stamp and date commands can be combined using backquotes:
133
134          # date -R --date=@`sg_timestamp -S /dev/sdc`
135       Wed, 16 Dec 2015 20:12:59 -0500
136
137       To set the timestamp on the DEVICE to now (approximately) the following
138       could be used:
139
140          # date +%s
141       1448993955
142          # sg_timestamp --seconds=1448993955 /dev/sdb
143
144       Those two command lines could be combined into one by using backquotes:
145
146          # sg_timestamp --seconds=`date +%s` /dev/sdb
147

AUTHORS

149       Written by Douglas Gilbert.
150

REPORTING BUGS

152       Report bugs to <dgilbert at interlog dot com>.
153
155       Copyright © 2015-2018 Douglas Gilbert
156       This  software is distributed under a FreeBSD license. There is NO war‐
157       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
158       POSE.
159

SEE ALSO

161       sdparm(sdparm), sg_logs(sg3_utils)
162
163
164
165sg3_utils-1.43                    April 2018                   SG_TIMESTAMP(8)
Impressum