diff options
Diffstat (limited to 'doc/sg_timestamp.8')
| -rw-r--r-- | doc/sg_timestamp.8 | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/doc/sg_timestamp.8 b/doc/sg_timestamp.8 new file mode 100644 index 00000000..dbc1ef16 --- /dev/null +++ b/doc/sg_timestamp.8 @@ -0,0 +1,155 @@ +.TH SG_TIMESTAMP "8" "April 2018" "sg3_utils\-1.43" SG3_UTILS +.SH NAME +sg_timestamp \- report or set timestamp on SCSI device +.SH SYNOPSIS +.B sg_timestamp +[\fI\-\-elapsed\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] +[\fI\-\-milliseconds=MS\fR] [\fI\-\-no\-timestamp\fR] [\fI\-\-origin\fR] +[\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-seconds=SECS\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=SECS\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 especially 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\-e\fR, \fB\-\-elapsed\fR +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. +.TP +\fB\-h\fR, \fB\-\-help\fR +output the usage message then exit. +.TP +\fB\-H\fR, \fB\-\-hex\fR +output the response to REPORT TIMESTAMP in ASCII hexadecimal on stderr. The +response is not decoded. +.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\-N\fR, \fB\-\-no\-timestamp\fR +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 \fI\-\-origin\fR option). +.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. +.br +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 indicates a SET TIMESTAMP initialized the +clock while 3 indicates some other method initialized the clock. +.br +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 'TIMESTAMP_ORIGIN=<value>' is output. +.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=\fISECS\fR +where \fISECS\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. \fISECS\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\-2018 Douglas Gilbert +.br +This software is distributed under a BSD\-2\-Clause 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) |