SG_TIMESTAMP(8)

🎀 Manual: sg_timestamp, section 8, from SG3_UTILS 🦋

✨ NAME ✨

okay so sg_timestamp is the tool that lets you report or set the timestamp on a SCSI device 💖

✨ SYNOPSIS ✨

sg_timestamp [--elapsed] [--help] [--hex] [--milliseconds=MS]
[--no-timestamp] [--origin] [--raw] [--readonly] [--seconds=SECS]
[--srep] [--verbose] [--version] DEVICE

✨ DESCRIPTION ✨

bestie, this thing sends a SCSI REPORT TIMESTAMP or SET TIMESTAMP command to the DEVICE 💅 Both of these commands live in the SPC-5 draft standard revision 7 (spc5r07.pdf), so you know it's legit 🔥

if you give either --milliseconds=MS or --seconds=SECS (but you can't give both, no cap) then it sends SET TIMESTAMP. otherwise it sends REPORT TIMESTAMP ✨

the timestamp goes to and from the DEVICE as the number of milliseconds since the epoch, which is 1970-01-01 00:00:00 UTC 🌈 it's stored in a 48 bit unsigned integer, and it's giving very specific. Unix machines use that same epoch too, except they usually count in seconds instead 🧚 The Unix date command, especially its "+%s" format, is seriously iconic for converting to and from timestamps and making them readable for humans. check the EXAMPLES section below 💜

there's also a companion utility called sg_sat_datetime that has similar options and lets you get or set the date and time on an ATA device (usually a SATA disk) 🫶 it sends its ATA commands through the SCSI to ATA Translation (SAT) layer.

✨ OPTIONS ✨

ok the rule here is that arguments to long options are required for short options too 🙈

• -e, --elapsed — treats the timestamp in REPORT TIMESTAMP as an elapsed time since something like a power cycle or hard reset, and formats it as <n> days hh:mm:ss.xxx. 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, the 0 days part gets skipped unless you pass this option two or more times 💀
• -h, --help — prints the usage message and then exits 🌸
• -H, --hex — prints the REPORT TIMESTAMP response in ASCII hexadecimal to stderr. nothing gets decoded, it's raw vibes 🔥
• -m, --milliseconds=MS — MS is the number of milliseconds since 1970-01-01 00:00:00 UTC that you want to set on the DEVICE with the SCSI SET TIMESTAMP command ✨
• -N, --no-timestamp — when REPORT TIMESTAMP runs, this option stops the timestamp value (in seconds or milliseconds) from being printed. it can help declutter the output when you're trying to figure out the timestamp origin (see the --origin option) 🧚
• -o, --origin — the REPORT TIMESTAMP response has a "timestamp origin" field in it. with this option, that field gets decoded and printed before the timestamp value. by default it doesn't get printed at all 👑 T10 describes this field as "the most recent event that initialized the returned device clock". a value of 0 means a power up or hard reset initialized the clock, 2 means a SET TIMESTAMP initialized it, and 3 means some other method did 🦋 if you use it once, you get a descriptive string on a line before the timestamp value. if you use it twice, you get the TIMESTAMP ORIGIN value in decimal (somewhere between 0 and 7 inclusive). if you use it three times, you get a line that looks like TIMESTAMP_ORIGIN=<value> 💖
• -r, --raw — dumps the SCSI REPORT TIMESTAMP response (the data-out buffer) in binary to stdout. heads up, --origin and --srep get ignored when you use this one. all the error and verbose messages go to stderr too 🙈
• -R, --readonly — opens the DEVICE read-only. the default is read-write 🫶
• -s, --seconds=SECS — SECS is the number of seconds since 1970-01-01 00:00:00 UTC that you want to set on the DEVICE with the SCSI SET TIMESTAMP command. SECS gets multiplied by 1000 before it's used in SET TIMESTAMP 🌈
• -S, --srep — reports the number of seconds since 1970-01-01 00:00:00 UTC. it does this by dividing the value from the SCSI REPORT TIMESTAMP command by 1000 💅
• -v, --verbose — turns up the verbosity, aka debug output 🍓
• -V, --version — prints the version string and then exits ⭐

✨ EXIT STATUS ✨

sg_timestamp exits with 0 when it works. otherwise, check out the sg3_utils(8) man page for the rest 🎀

✨ NOTES ✨

the TCMOS and SCSIP bits in the Control extension mode page (see sdparm) change how the timestamp held by a DEVICE behaves 🔥

right now, only the "Utilization usage rate based on date and time" parameters in the Utilization log page (sbc4r09.pdf) use timestamps. check out the sg_logs utility for that. vendor specific commands and pages might use timestamps too, so keep an eye out 👀

✨ EXAMPLES ✨

on Unix machines (like Linux, FreeBSD and Solaris) the date command is super useful when you're dealing with timestamps 💅

to grab the timestamp from a DEVICE and show it in a human-readable form, you could do something like this 🦋

# 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 last two date commands show two different looks for the same date (aka 1448993950 seconds since 1970-01-01 00:00:00 UTC) 🌸 you can also mash sg_timestamp and date together with 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 roughly right now, you could do this 🧚

# date +%s
1448993955
# sg_timestamp --seconds=1448993955 /dev/sdb

and you can squish those two command lines into one with backquotes too 💖

# sg_timestamp --seconds=`date +%s` /dev/sdb

✨ AUTHORS ✨

written by Douglas Gilbert, the legend himself 👑

✨ REPORTING BUGS ✨

send bugs to <dgilbert at interlog dot com> 💌

✨ COPYRIGHT ✨

Copyright © 2015-2018 Douglas Gilbert this software is distributed under a BSD-2-Clause license. there is NO warranty, not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE 🙈

✨ SEE ALSO ✨

sdparm(sdparm), sg_logs(sg3_utils), sg_sat_datetime(sg3_utils) 🫶

---

bestie, that's the whole tea ☕ this is sg3_utils 1.43 from April 2018, and it's a whole vibe 🌈💜🦋