doc/sg_timestamp.8 - platform/external/sg3_utils - Git at Google

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