SG_SAT_DATETIME(8)

📦
version 1.49 · 2 versions
, in arch rolling, nixpkgs unstable

✨ SG_SAT_DATETIME(8) ✨

okay bestie, so this is a page from the sg3_utils manual set — sg_sat_datetime — and it's genuinely one of the cutest little utilities in the whole toolbox. It's all about asking your ATA drive what time it thinks it is, or telling it what time it actually is. Let's get into it 🫶

🌸 NAME 🌸

sg_sat_datetime — report or set the date and time on an ATA device. That's the whole vibe, no cap.

🦋 SYNOPSIS 🦋

sg_sat_datetime [--dma] [--elapsed] [--format] [--help] [--hex]
[--milliseconds=MS] [--readonly] [--seconds=SECS] [--srep] [--verbose]
[--version] DEVICE

💅 DESCRIPTION 💅

So what actually happens under the hood? This sends a SET DATE & TIME EXT command, or a READ LOG [DMA] EXT command, to the ATA DEVICE — either to set the date and time, or to read it out of the Device Statistics log at address 04h, General Statistics page (01h). Both of these commands live in the ATA Command Set (ACS-5) standard, and the ATA commands get sent using ATA PASS-THROUGH SCSI commands. Nested, but it works 💖

Here's the logic, and it's lowkey simple:

  • If you give either --milliseconds=MS or --seconds=SECS — and bestie, you literally cannot give both — then the SET DATE & TIME command is sent.
  • Otherwise, the READ LOG EXT command goes out. Or, if you passed --dma, it's the READ LOG DMA EXT command instead.

Now for the fun part 🎀 The date and time get sent to and received from the DEVICE generally as the number of milliseconds since the epoch of 1970-01-01 00:00:00 UTC, stored in a 48 bit unsigned integer. That's the exact same epoch Unix machines use, except Unix usually counts seconds since then. So the Unix date command — and especially its +%s format — is your bestie for converting between timestamps and humanly readable forms. There's a whole EXAMPLES section below for this, iykyk.

Real talk though: if the date and time is not set after a power-on reset, the value is the same as the device power-on hours in milliseconds. Not a clock, just a counter. Periodt.

✨ OPTIONS ✨

Heads up boo: arguments to long options are mandatory for short options as well.

  • -d, --dma — use READ LOG DMA EXT to read the date and time value from the device. Ignored if you're setting the date and time (so don't stress about it then).
  • -e, --elapsed — assume the date and time from READ LOG [DMA] EXT is an elapsed time from some event like 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 inclusive). If the number of days is 0 then '0 days' is not output — unless you give this option two or more times 👀. This one's especially useful if the date and time has not been set, because per ACS-5, when it's not set the date and time is initialized to the power-on hours of the device in milliseconds.
  • -f, --format — output the date and time formatted using the default locale. Cute and readable 💐
  • -h, --help — output the usage message then exit. The classic.
  • -H, --hex — output the date and time in ASCII hexadecimal. Raw numbers, no filter 😌
  • -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 ATA SET DATE & TIME EXT command.
  • -R, --readonly — open the DEVICE read-only. The default action is to open the DEVICE read-write, jsyk.
  • -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 ATA SET DATE & TIME command. SECS gets multiplied by 1000 before being used in that command (math! we love her).
  • -S, --srep — report the number of seconds since 1970-01-01 00:00:00 UTC. This is done by dividing the value returned by the ATA READ LOG [DMA] EXT command by 1000.
  • -v, --verbose — increase the level of verbosity (i.e. debug output). For the nosy girlies 🕵️‍♀️
  • -V, --version — print the version string and then exit.

🎀 EXIT STATUS 🎀

The exit status of sg_sat_datetime is 0 when it is successful. Otherwise, see the sg3_utils(8) man page — it's got the full breakdown.

💜 NOTES 💜

The DEVICE should immediately start accumulating time after the date and time is set. Like, ie. if you set it and then retrieve it, the returned values will likely have increased. She's ticking, bestie ⏰

The ACS-5 standard makes no provision for a power-safe date and time storage. Unless the device has vendor-specific power-safe capability, after a power-on reset, per ACS-5, the date and time should be the power-on hours of the device returned in milliseconds (or seconds if the --srep option is used). So don't be shocked when it comes back weird. That's just how it is 😭

🌈 EXAMPLES 🌈

On Unix machines (e.g. Linux, FreeBSD, and Solaris) the date command is useful when working with timestamps. Here's the whole flow ✨

To fetch the timestamp from a DEVICE and display it in a humanly readable form, the following could be used:

# sg_sat_datetime -S /dev/sg2
1681156506

# date --date=@1681156506
Mon Apr 10 02:55:06 PM CDT 2023

# date -R --date="@1681156506"
Mon, 10 Apr 2023 14:55:06 -0500

The latter two date commands show different forms of the same date (i.e. 1681156506 seconds since 1970-01-01 00:00:00 UTC). And the sg_sat_datetime and date commands can be combined using backquotes:

# date -R --date=@`sg_sat_datetime -S /dev/sg2`
Mon, 10 Apr 2023 14:55:06 -0500

Alternatively, the --format option can be used to format the date and time using the default locale.

# sg_sat_datetime --format /dev/sg2
Mon Apr 10 15:02:54 2023

To set the date and time on the DEVICE to now (approximately) the following could be used:

# date +%s
1681157099

# sg_sat_datetime --seconds=1681157099 /dev/sg0

And those two command lines could be combined into one by using backquotes:

# sg_sat_datetime --seconds=`date +%s` /dev/sg0

Iconic. Ate. No notes 💅

👑 AUTHORS 👑

Written by Jeremy Bauer and Daniel Woeste with extensive use of sg_timestamp and sg_sat_read_gplog by Douglas Gilbert. Shoutout to the whole team 🫶

🐛 REPORTING BUGS 🐛

Report bugs to <dgilbert at interlog dot com>.

Copyright © 2023 Jeremy Bauer and Daniel Woeste of Western Digital Corporation

This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

⭐ SEE ALSO ⭐

  • sdparm(sdparm)
  • sg_logs(sg3_utils)
  • sg_timestamp(sg3_utils)
  • sg_sat_read_gplog(sg3_utils)

okay that's the whole page bestie, go set some clocks 🕰️💖 — this was sg3_utils-1.48, dated May 2023, and that's the SG_SAT_DATETIME(8) sign-off from me to you 🌈🎀

📦 where this page comes from