{
    "mode": "man",
    "parameter": "sg_timestamp",
    "section": "8",
    "url": "https://www.chedong.com/phpMan.php/man/sg_timestamp/8/json",
    "generated": "2026-06-16T15:52:57Z",
    "synopsis": "sgtimestamp  [--elapsed]  [--help]  [--hex]  [--milliseconds=MS] [--no-timestamp] [--origin]\n[--raw] [--readonly] [--seconds=SECS] [--srep] [--verbose] [--version] DEVICE",
    "sections": {
        "NAME": {
            "content": "sgtimestamp - report or set timestamp on SCSI device\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "sgtimestamp  [--elapsed]  [--help]  [--hex]  [--milliseconds=MS] [--no-timestamp] [--origin]\n[--raw] [--readonly] [--seconds=SECS] [--srep] [--verbose] [--version] DEVICE\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Sends a SCSI REPORT TIMESTAMP or SET TIMESTAMP command to the  DEVICE.   These  commands  are\nfound in the SPC-5 draft standard revision 7 (spc5r07.pdf).\n\nIf  either  the --milliseconds=MS or --seconds=SECS option is given (and both can't be given)\nthen the SET TIMESTAMP command is sent; otherwise the REPORT TIMESTAMP command is sent.\n\nThe timestamp is sent and received from the DEVICE as the number of  milliseconds  since  the\nepoch of 1970-01-01 00:00:00 UTC and is held in a 48 bit unsigned integer. That same epoch is\nused by Unix machines, but they usually hold the number of seconds since that epoch. The Unix\ndate  command  and especially its \"+%s\" format is useful in converting to and from timestamps\nand more humanly readable forms. See the EXAMPLES section below.\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "Arguments to long options are mandatory for short options as well.\n",
            "subsections": [
                {
                    "name": "-e --elapsed",
                    "content": "assume the timestamp in the REPORT TIMESTAMP is an elapsed time from an event such  as\na  power cycle or hard reset and format the output as '<n> days hh:mm:ss.xxx' where hh\nis hours (00 to 23 inclusive); mm is minutes (00 to 59 inclusive); ss is  seconds  (00\nto 59 inclusive) and xxx is milliseconds (000 to 999 inclusive). If the number of days\nis 0 then '0 days' is not output unless this option is given two or more times.\n",
                    "flag": "-e",
                    "long": "--elapsed"
                },
                {
                    "name": "-h --help",
                    "content": "output the usage message then exit.\n",
                    "flag": "-h",
                    "long": "--help"
                },
                {
                    "name": "-H --hex",
                    "content": "output the response to REPORT TIMESTAMP in ASCII hexadecimal on stderr.  The  response\nis not decoded.\n",
                    "flag": "-H",
                    "long": "--hex"
                },
                {
                    "name": "-m --milliseconds",
                    "content": "where MS is the number of milliseconds since 1970-01-01 00:00:00 UTC to set in the DE‐\nVICE with the SCSI SET TIMESTAMP command.\n",
                    "flag": "-m",
                    "long": "--milliseconds"
                },
                {
                    "name": "-N --no-timestamp",
                    "content": "when REPORT TIMESTAMP is called this option suppress the output of the timestamp value\n(in  either  seconds  or  milliseconds). This may be useful in uncluttering the output\nwhen trying to decode the timestamp origin (see the --origin option).\n",
                    "flag": "-N",
                    "long": "--no-timestamp"
                },
                {
                    "name": "-o --origin",
                    "content": "the REPORT TIMESTAMP returned parameter data contains a \"timestamp origin\" field. When\nthis option is given, that field is decoded and printed out before the timestamp value\nis output. The default action (i.e. when the option is not given) is not to print  out\nthis decoded field.\nT10  defines this field as \"the most recent event that initialized the returned device\nclock\". The value 0 indicates a power up of hard reset initialized the clock; 2  indi‐\ncates  a  SET TIMESTAMP initialized the clock while 3 indicates some other method ini‐\ntialized the clock.\nWhen used once a descriptive string is output (in a line before the timestamp  value).\nWhen used twice the value of the TIMESTAMP ORIGIN field is output (in decimal, a value\nbetween 0 and 7 inclusive). When used  thrice  a  line  of  the  form  'TIMESTAMPORI‐\nGIN=<value>' is output.\n",
                    "flag": "-o",
                    "long": "--origin"
                },
                {
                    "name": "-r --raw",
                    "content": "output  the  SCSI  REPORT  TIMESTAMP response (i.e. the data-out buffer) in binary (to\nstdout). Note that the --origin and --srep options are ignored  when  this  option  is\ngiven. Also all error and verbose messages are output to stderr.\n",
                    "flag": "-r",
                    "long": "--raw"
                },
                {
                    "name": "-R --readonly",
                    "content": "open the DEVICE read-only. The default action is to open the DEVICE read-write.\n",
                    "flag": "-R",
                    "long": "--readonly"
                },
                {
                    "name": "-s --seconds",
                    "content": "where SECS is the number of seconds since 1970-01-01 00:00:00 UTC to set in the DEVICE\nwith the SCSI SET TIMESTAMP command. SECS is multiplied by 1000 before being  used  in\nthe SET TIMESTAMP command.\n",
                    "flag": "-s",
                    "long": "--seconds"
                },
                {
                    "name": "-S --srep",
                    "content": "report  the  number of seconds since 1970-01-01 00:00:00 UTC. This is done by dividing\nby 1000 the value returned by the SCSI REPORT TIMESTAMP command.\n",
                    "flag": "-S",
                    "long": "--srep"
                },
                {
                    "name": "-v --verbose",
                    "content": "increase the level of verbosity, (i.e. debug output).\n",
                    "flag": "-v",
                    "long": "--verbose"
                },
                {
                    "name": "-V --version",
                    "content": "print the version string and then exit.\n",
                    "flag": "-V",
                    "long": "--version"
                }
            ]
        },
        "EXIT STATUS": {
            "content": "The exit status of sgtimestamp is 0 when it is successful. Otherwise  see  the  sg3utils(8)\nman page.\n",
            "subsections": []
        },
        "NOTES": {
            "content": "The  TCMOS  and the SCSIP bits in the Control extension mode page (see sdparm) modify the ac‐\ntions of the timestamp held by a DEVICE.\n\nCurrently only the \"Utilization usage rate based on date and time\" parameters within the Uti‐\nlization log page (sbc4r09.pdf) use timestamps. See the sglogs utility. Vendor specific com‐\nmands and pages may also be using timestamps.\n",
            "subsections": []
        },
        "EXAMPLES": {
            "content": "On Unix machines (e.g. Linux, FreeBSD and Solaris) the date command is  useful  when  working\nwith timestamps.\n\nTo  fetch the timestamp from a DEVICE and display it in a humanly readable form the following\ncould be used:\n\n# sgtimestamp -S /dev/sdb\n1448993950\n# date --date=@1448993950\nTue Dec  1 13:19:10 EST 2015\n# date -R --date=\"@1448993950\"\nTue, 01 Dec 2015 13:19:10 -0500\n\nThe latter two date commands show different forms of the same date (i.e.  1448993950  seconds\nsince  1970-01-01  00:00:00  UTC).  The  sgtimestamp and date commands can be combined using\nbackquotes:\n\n# date -R --date=@`sgtimestamp -S /dev/sdc`\nWed, 16 Dec 2015 20:12:59 -0500\n\nTo set the timestamp on the DEVICE to now (approximately) the following could be used:\n\n# date +%s\n1448993955\n# sgtimestamp --seconds=1448993955 /dev/sdb\n\nThose two command lines could be combined into one by using backquotes:\n\n# sgtimestamp --seconds=`date +%s` /dev/sdb\n",
            "subsections": []
        },
        "AUTHORS": {
            "content": "Written by Douglas Gilbert.\n",
            "subsections": []
        },
        "REPORTING BUGS": {
            "content": "Report bugs to <dgilbert at interlog dot com>.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright © 2015-2018 Douglas Gilbert\nThis software is distributed under a FreeBSD license. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "sdparm(sdparm), sglogs(sg3utils)\n\n\n\nsg3utils-1.43                               April 2018                              SGTIMESTAMP(8)",
            "subsections": []
        }
    },
    "summary": "sgtimestamp - report or set timestamp on SCSI device",
    "flags": [
        {
            "flag": "-e",
            "long": "--elapsed",
            "arg": null,
            "description": "assume the timestamp in the REPORT TIMESTAMP 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."
        },
        {
            "flag": "-h",
            "long": "--help",
            "arg": null,
            "description": "output the usage message then exit."
        },
        {
            "flag": "-H",
            "long": "--hex",
            "arg": null,
            "description": "output the response to REPORT TIMESTAMP in ASCII hexadecimal on stderr. The response is not decoded."
        },
        {
            "flag": "-m",
            "long": "--milliseconds",
            "arg": null,
            "description": "where MS is the number of milliseconds since 1970-01-01 00:00:00 UTC to set in the DE‐ VICE with the SCSI SET TIMESTAMP command."
        },
        {
            "flag": "-N",
            "long": "--no-timestamp",
            "arg": null,
            "description": "when REPORT TIMESTAMP is called this option suppress the output of the timestamp value (in either seconds or milliseconds). This may be useful in uncluttering the output when trying to decode the timestamp origin (see the --origin option)."
        },
        {
            "flag": "-o",
            "long": "--origin",
            "arg": null,
            "description": "the REPORT TIMESTAMP returned parameter data contains a \"timestamp origin\" field. When this option is given, that field is decoded and printed out before the timestamp value is output. The default action (i.e. when the option is not given) is not to print out this decoded field. T10 defines this field as \"the most recent event that initialized the returned device clock\". The value 0 indicates a power up of hard reset initialized the clock; 2 indi‐ cates a SET TIMESTAMP initialized the clock while 3 indicates some other method ini‐ tialized the clock. When used once a descriptive string is output (in a line before the timestamp value). When used twice the value of the TIMESTAMP ORIGIN field is output (in decimal, a value between 0 and 7 inclusive). When used thrice a line of the form 'TIMESTAMPORI‐ GIN=<value>' is output."
        },
        {
            "flag": "-r",
            "long": "--raw",
            "arg": null,
            "description": "output the SCSI REPORT TIMESTAMP response (i.e. the data-out buffer) in binary (to stdout). Note that the --origin and --srep options are ignored when this option is given. Also all error and verbose messages are output to stderr."
        },
        {
            "flag": "-R",
            "long": "--readonly",
            "arg": null,
            "description": "open the DEVICE read-only. The default action is to open the DEVICE read-write."
        },
        {
            "flag": "-s",
            "long": "--seconds",
            "arg": null,
            "description": "where SECS is the number of seconds since 1970-01-01 00:00:00 UTC to set in the DEVICE with the SCSI SET TIMESTAMP command. SECS is multiplied by 1000 before being used in the SET TIMESTAMP command."
        },
        {
            "flag": "-S",
            "long": "--srep",
            "arg": null,
            "description": "report the number of seconds since 1970-01-01 00:00:00 UTC. This is done by dividing by 1000 the value returned by the SCSI REPORT TIMESTAMP command."
        },
        {
            "flag": "-v",
            "long": "--verbose",
            "arg": null,
            "description": "increase the level of verbosity, (i.e. debug output)."
        },
        {
            "flag": "-V",
            "long": "--version",
            "arg": null,
            "description": "print the version string and then exit."
        }
    ],
    "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:",
        "# sgtimestamp -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 latter two date commands show different forms of the same date (i.e.  1448993950  seconds",
        "since  1970-01-01  00:00:00  UTC).  The  sgtimestamp and date commands can be combined using",
        "backquotes:",
        "# date -R --date=@`sgtimestamp -S /dev/sdc`",
        "Wed, 16 Dec 2015 20:12:59 -0500",
        "To set the timestamp on the DEVICE to now (approximately) the following could be used:",
        "# date +%s",
        "1448993955",
        "# sgtimestamp --seconds=1448993955 /dev/sdb",
        "Those two command lines could be combined into one by using backquotes:",
        "# sgtimestamp --seconds=`date +%s` /dev/sdb"
    ],
    "see_also": [
        {
            "name": "sdparm",
            "section": "sdparm",
            "url": "https://www.chedong.com/phpMan.php/man/sdparm/sdparm/json"
        },
        {
            "name": "sglogs",
            "section": "sg3utils",
            "url": "https://www.chedong.com/phpMan.php/man/sglogs/sg3utils/json"
        }
    ]
}