| .TH SG_TIMESTAMP "8" "December 2015" "sg3_utils\-1.42" SG3_UTILS |
| .SH NAME |
| sg_timestamp \- report or set timestamp on SCSI device |
| .SH SYNOPSIS |
| .B sg_timestamp |
| [\fI\-\-help\fR] [\fI\-\-milliseconds=MS\fR] [\fI\-\-origin\fR] |
| [\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-seconds=SEC\fR] [\fI\-\-srep\fR] |
| [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR |
| .SH DESCRIPTION |
| .\" Add any additional description here |
| .PP |
| Sends a SCSI REPORT TIMESTAMP or SET TIMESTAMP command to the \fIDEVICE\fR. |
| These commands are found in the SPC\-5 draft standard revision |
| 7 (spc5r07.pdf). |
| .PP |
| If either the \fI\-\-milliseconds=MS\fR or \fI\-\-seconds=SEC\fR option is |
| given (and both can't be given) then the SET TIMESTAMP command is sent; |
| otherwise the REPORT TIMESTAMP command is sent. |
| .PP |
| The timestamp is sent and received from the \fIDEVICE\fR 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 especally its "+%s" format is useful in converting to and from |
| timestamps and more humanly readable forms. See the EXAMPLES section below. |
| .SH OPTIONS |
| Arguments to long options are mandatory for short options as well. |
| .TP |
| \fB\-h\fR, \fB\-\-help\fR |
| output the usage message then exit. |
| .TP |
| \fB\-m\fR, \fB\-\-milliseconds\fR=\fIMS\fR |
| where \fIMS\fR is the number of milliseconds since 1970\-01\-01 00:00:00 UTC |
| to set in the \fIDEVICE\fR with the SCSI SET TIMESTAMP command. |
| .TP |
| \fB\-o\fR, \fB\-\-origin\fR |
| 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. |
| .TP |
| \fB\-r\fR, \fB\-\-raw\fR |
| output the SCSI REPORT TIMESTAMP response (i.e. the data\-out buffer) in |
| binary (to stdout). Note that the \fI\-\-origin\fR and \fI\-\-srep\fR |
| options are ignored when this option is given. Also all error and |
| verbose messages are output to stderr. |
| .TP |
| \fB\-R\fR, \fB\-\-readonly\fR |
| open the \fIDEVICE\fR read\-only. The default action is to open the |
| \fIDEVICE\fR read\-write. |
| .TP |
| \fB\-s\fR, \fB\-\-seconds\fR=\fISEC\fR |
| where \fISEC\fR is the number of seconds since 1970\-01\-01 00:00:00 UTC |
| to set in the \fIDEVICE\fR with the SCSI SET TIMESTAMP command. \fISEC\fR |
| is multiplied by 1000 before being used in the SET TIMESTAMP command. |
| .TP |
| \fB\-S\fR, \fB\-\-srep\fR |
| 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. |
| .TP |
| \fB\-v\fR, \fB\-\-verbose\fR |
| increase the level of verbosity, (i.e. debug output). |
| .TP |
| \fB\-V\fR, \fB\-\-version\fR |
| print the version string and then exit. |
| .SH EXIT STATUS |
| The exit status of sg_timestamp is 0 when it is successful. Otherwise see |
| the sg3_utils(8) man page. |
| .SH NOTES |
| The TCMOS and the SCSIP bits in the Control extension mode page (see sdparm) |
| modify the actions of the timestamp held by a \fIDEVICE\fR. |
| .PP |
| Currently only the "Utilization usage rate based on date and time" parameters |
| within the Utilization log page (sbc4r09.pdf) use timestamps. See the sg_logs |
| utility. Vendor specific commands and pages may also be using timestamps. |
| .SH EXAMPLES |
| On Unix machines (e.g. Linux, FreeBSD and Solaris) the date command is useful |
| when working with timestamps. |
| .PP |
| To fetch the timestamp from a \fIDEVICE\fR and display it in a humanly |
| readable form the following could be used: |
| .PP |
| # sg_timestamp \-S /dev/sdb |
| .br |
| 1448993950 |
| .br |
| # date \-\-date="@1448993950" |
| .br |
| Tue Dec 1 13:19:10 EST 2015 |
| .br |
| # date \-R \-\-date="@1448993950" |
| .br |
| Tue, 01 Dec 2015 13:19:10 \-0500 |
| .PP |
| 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 sg_timestamp and |
| date commands can be combined using backquotes: |
| .PP |
| # date \-R \-\-date="@`sg_timestamp \-S /dev/sdc`" |
| .br |
| Wed, 16 Dec 2015 20:12:59 \-0500 |
| .PP |
| To set the timestamp on the \fIDEVICE\fR to now (approximately) the |
| following could be used: |
| .PP |
| # date +%s |
| .br |
| 1448993955 |
| .br |
| # sg_timestamp \-\-seconds=1448993955 /dev/sdb |
| .PP |
| Those two command lines could be combined into one by using backquotes: |
| .PP |
| # sg_timestamp \-\-seconds=`date +%s` /dev/sdb |
| .PP |
| .SH AUTHORS |
| Written by Douglas Gilbert. |
| .SH "REPORTING BUGS" |
| Report bugs to <dgilbert at interlog dot com>. |
| .SH COPYRIGHT |
| Copyright \(co 2015 Douglas Gilbert |
| .br |
| This software is distributed under a FreeBSD license. There is NO |
| warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| .SH "SEE ALSO" |
| .B sdparm(sdparm), sg_logs(sg3_utils) |
