Ubuntu Manpage: sg_sat_datetime - report or set date and time on a ATA device

Provided by: sg3-utils_1.48-0ubuntu1_amd64

NAME

       sg_sat_datetime - report or set date and time on a ATA device

SYNOPSIS

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

DESCRIPTION

       Sends a SET DATE & TIME EXT or READ LOG [DMA] EXT command to the ATA DEVICE to set the date and  time  or
       read  it  from  the Device Statistics log address(04h), General Statistics page (01h). These commands are
       found in the ATA Command Set (ACS-5) standard.   ATA  commands  are  sent  using  ATA  PASS-THROUGH  SCSI
       commands.

       If  either the --milliseconds=MS or --seconds=SECS option is given (and both can't be given) then the SET
       DATE & TIME command is sent.  Otherwise, the READ LOG EXT command, or if the --dma option  is  used,  the
       READ LOG DMA EXT command is sent to the device.

       The  date and time is sent and received from the DEVICE generally as the number of milliseconds since the
       epoch of 1970-01-01 00:00:00 UTC and is held in a 48 bit unsigned integer. That same  epoch  is  used  by
       Unix  machines,  but  they usually hold the number of seconds since that epoch. The Unix date command and
       especially its "+%s" format is useful in converting to and from  timestamps  and  more  humanly  readable
       forms. See the EXAMPLES section below. If the date and time is not set after power-on reset, the value is
       the same as the device power-on hours in milliseconds.

OPTIONS

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 setting the date
and time.

-e, --elapsed
assume the date and time from READ LOG [DMA] EXT is an elapsed time from an event such as 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
this option is given two or more times.
This option is especially useful if the date and time has not been set. Per ACS-5, when 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.

-h, --help
output the usage message then exit.

-H, --hex
output the date and time in ASCII hexadecimal.

-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.

-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 is multiplied by 1000 before being used in the ATA SET DATE &
TIME command.

-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).

-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.

NOTES

       The DEVICE should immediately start accumulating time after the date and time is set.  ie. If you set and
       then retrieve the date and time, the returned values will likely have increased.

       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 --srep option is used).

EXAMPLES

       On  Unix  machines  (e.g.  Linux,  FreeBSD,  and  Solaris)  the  date command is useful when working with
       timestamps.

       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). 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

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

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

AUTHORS

       Written by Jeremy Bauer and Daniel Woeste with extensive use of  sg_timestamp  and  sg_sat_read_gplog  by
       Douglas Gilbert.

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

       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.