1SG_TIMESTAMP(8) SG3_UTILS SG_TIMESTAMP(8)
2
6 sg_timestamp - report or set timestamp on SCSI device
7
9 sg_timestamp [--elapsed] [--help] [--hex] [--milliseconds=MS]
10 [--no-timestamp] [--origin] [--raw] [--readonly] [--seconds=SECS]
11 [--srep] [--verbose] [--version] DEVICE
12
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 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 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 especially its "+%s" format is useful in converting to
27 and from timestamps and more humanly readable forms. See the EXAMPLES
28 section below.
29
31 Arguments to long options are mandatory for short options as well.
32 -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 -h, --help
43 output the usage message then exit.
44 -H, --hex
46 output the response to REPORT TIMESTAMP in ASCII hexadecimal on
47 stderr. The response is not decoded.
48 -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 -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 -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 in‐
73 clusive). When used thrice a line of the form 'TIMESTAMP_ORI‐
74 GIN=<value>' is output.
75 -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 -R, --readonly
83 open the DEVICE read-only. The default action is to open the DE‐
84 VICE read-write.
85 -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 -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 RE‐
95 PORT TIMESTAMP command.
96 -v, --verbose
98 increase the level of verbosity, (i.e. debug output).
99 -V, --version
101 print the version string and then exit.
102
104 The exit status of sg_timestamp is 0 when it is successful. Otherwise
105 see the sg3_utils(8) man page.
106
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 Currently only the "Utilization usage rate based on date and time" pa‐
112 rameters within the Utilization log page (sbc4r09.pdf) use timestamps.
113 See the sg_logs utility. Vendor specific commands and pages may also be
114 using timestamps.
115
117 On Unix machines (e.g. Linux, FreeBSD and Solaris) the date command is
118 useful when working with timestamps.
119 To fetch the timestamp from a DEVICE and display it in a humanly read‐
121 able form the following could be used:
122 # 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 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 # date -R --date=@`sg_timestamp -S /dev/sdc`
135 Wed, 16 Dec 2015 20:12:59 -0500
136 To set the timestamp on the DEVICE to now (approximately) the following
138 could be used:
139 # date +%s
141 1448993955
142 # sg_timestamp --seconds=1448993955 /dev/sdb
143 Those two command lines could be combined into one by using backquotes:
145 # sg_timestamp --seconds=`date +%s` /dev/sdb
147
149 Written by Douglas Gilbert.
150
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
161 sdparm(sdparm), sg_logs(sg3_utils)
162sg3_utils-1.43 April 2018 SG_TIMESTAMP(8)