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

 .TH SG_TURS "8" "November 2022" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg_turs \- send one or more SCSI TEST UNIT READY commands
 .SH SYNOPSIS
 .B sg_turs
 [\fI\-\-delay=MS\fR] [\fI\-\-help\fR] [\fI\-\-low\fR] [\fI\-\-num=NUM\fR]
 [\fI\-\-number=NUM\fR] [\fI\-\-progress\fR] [\fI\-\-time\fR]
 [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
 .PP
 .B sg_turs
 [\fI\-d=MS\fR] [\fI\-n=NUM\fR] [\fI\-p\fR]  [\fI\-t\fR] [\fI\-v\fR] [\fI\-V\fR]
 \fIDEVICE\fR
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
 This utility sends one or more SCSI TEST UNIT READY commands to the
 \fIDEVICE\fR. This may be useful for timing the per command overhead.
 Note that TEST UNIT READY has no associated data, just a 6 byte
 command (with each byte a zero) and a returned SCSI status value.
 .PP
 This utility supports two command line syntaxes, the preferred one is
 shown first in the synopsis and explained in this section. A later section
 on the old command line syntax outlines the second group of options.
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 .TP
 \fB\-d\fR, \fB\-\-delay\fR=\fIMS\fR
 this option causes a delay of \fIMS\fR milliseconds to occur before each
 TEST UNIT READY command is issued.
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 print out the usage message then exit.
 .TP
 \fB\-l\fR, \fB\-\-low\fR
 when [\fI\-\-progress\fR] is not being used, this utility tries to complete
 the SCSI TEST UNIT READY command(s) as quickly as possible. Usually it
 calls a library function to do each TUR (sg_ll_test_unit_ready). With this
 option it uses the lower level sg_pt interface (see sg_pt.h) to save a
 little time on each TUR.
 .TP
 \fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
 performs TEST UNIT READY \fINUM\fR times. If not given defaults to 1.
 These suffix multipliers are permitted: c C *1; w W *2; b B *512;
 k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB *1,000,000;
 g G GiB *1,073,741,824; and GB *1,000,000,000 . Also a suffix of the
 form "x<n>" multiplies the leading number by <n>. Alternatively a hex
 number may be given, prefixed by either '0x' or has a trailing 'h'.
 .TP
 \fB\-\-number\fR=\fINUM\fR
 same as \fI\-\-num=NUM\fR. Added for compatibility with sg_requests and
 other utilities in this package. The sg_request utility has taken over the
 role of polling the progress indication which was originally assigned to
 the TEST UNIT READY command. This is a change by T10.
 .TP
 \fB\-O\fR, \fB\-\-old\fR
 Switch to older style options. Please use as first option.
 .TP
 \fB\-p\fR, \fB\-\-progress\fR
 show progress indication (a percentage) if available. If \fI\-\-num=NUM\fR
 is given, \fINUM\fR is greater than 1 and an initial progress indication
 was detected then this utility waits 30 seconds before subsequent checks.
 If the \fI\-\-delay=MS\fR option is given then it will wait for that number
 of milliseconds instead of 30 seconds.
 Exits when \fINUM\fR is reached or there are no more progress indications.
 Ignores \fI\-\-time\fR option. See NOTES section below.
 .TP
 \fB\-t\fR, \fB\-\-time\fR
 after completing the requested number of TEST UNIT READY commands, outputs
 the total duration and the average number of commands executed per second.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 increase level or verbosity.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
 print version string then exit.
 .SH NOTES
 The progress indication is optionally part of the sense data. When a prior
 command that takes a long time to complete (and typically precludes other
 media access commands) is still underway, the progress indication can be used
 to determine how long before the device returns to its normal state. Around
 SPC\-3 T10 changed the preferred command for polling the progress indication
 from TEST UNIT READY to REQUEST SENSE (see the sg_requests utility).
 .PP
 The SCSI FORMAT command for disks used with the IMMED bit set is an example
 of an operation that takes a significant amount of time and precludes other
 media access during that time. The IMMED bit set instructs the FORMAT command
 to return control to the application client once the format has commenced (see
 SBC\-3). Several long duration SCSI commands associated with tape drives also
 use the progress indication (see SSC\-3).
 .PP
 The \fIDEVICE\fR is opened with a read\-only flag (e.g. in Unix with the
 O_RDONLY flag).
 .PP
 Early standards suggested that the SCSI TEST UNIT READY command be used for
 polling the progress indication. More recent standards seem to suggest
 the SCSI REQUEST SENSE command should be used instead.
 .SH EXIT STATUS
 The exit status of sg_turs is 0 when it is successful (e.g. in the case of
 a mechanical disk, it is spun up and ready to accept IO commands). For this
 utility the other exit status values of interest are 2, 12 and 13. 12 is for
 the case when the sense key is "not ready" [0x2] and the additional sense
 code ends with "Target port in standby state" [0x4, 0xb]. 13 is for the
 case when the sense key is "not ready" [0x2] and the additional sense code
 is "Target port in unavailable state" [0x4, 0xc]. All other cases when
 the sense key is "not ready" [0x2] will set the exit status to 2.
 For other exit status values see the sg3_utils(8) man page.
 .SH OLDER COMMAND LINE OPTIONS
 The options in this section were the only ones available prior to sg3_utils
 version 1.23 . Since then this utility defaults to the newer command line
 options which can be overridden by using \fI\-\-old\fR (or \fI\-O\fR) as the
 first option. See the ENVIRONMENT VARIABLES section for another way to
 force the use of these older command line options.
 .TP
 \fB\-d\fR, \fB\-\-delay\fR=\fIMS\fR
 this option causes a delay of \fIMS\fR milliseconds to occur before each
 TEST UNIT READY command is issued.
 .TP
 \fB\-n\fR=\fINUM\fR
 performs TEST UNIT READY \fINUM\fR times. If not given defaults to 1.
 Equivalent to \fI\-\-num=NUM\fR in the main description.
 .TP
 \fB-N\fR, \fB\-\-new\fR
 Switch to the newer style options.
 .TP
 \fB\-p\fR
 show progress indication (a percentage) if available.
 Equivalent to \fI\-\-progress\fR in the main description.
 .TP
 \fB\-t\fR
 after completing the requested number of TEST UNIT READY commands, outputs
 the total duration and the average number of commands executed per second.
 Equivalent to \fI\-\-time\fR in the main description.
 .TP
 \fB\-v\fR
 increase level of verbosity.
 .TP
 \fB\-V\fR
 print out version string then exit.
 .SH ENVIRONMENT VARIABLES
 Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS
 can be given. When it is present this utility will expect the older command
 line options. So the presence of this environment variable is equivalent to
 using \fI\-\-old\fR (or \fI\-O\fR) as the first command line option.
 .SH AUTHORS
 Written by D. Gilbert
 .SH COPYRIGHT
 Copyright \(co 2000\-2022 Douglas Gilbert
 .br
 This software is distributed under the GPL version 2. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 .SH "SEE ALSO"
 .B sg_inq, sg_requests (sg3_utils)
	.TH SG_TURS "8" "November 2022" "sg3_utils\-1.48" SG3_UTILS
	.SH NAME
	sg_turs \- send one or more SCSI TEST UNIT READY commands
	.SH SYNOPSIS
	.B sg_turs
	[\fI\-\-delay=MS\fR] [\fI\-\-help\fR] [\fI\-\-low\fR] [\fI\-\-num=NUM\fR]
	[\fI\-\-number=NUM\fR] [\fI\-\-progress\fR] [\fI\-\-time\fR]
	[\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
	.PP
	.B sg_turs
	[\fI\-d=MS\fR] [\fI\-n=NUM\fR] [\fI\-p\fR] [\fI\-t\fR] [\fI\-v\fR] [\fI\-V\fR]
	\fIDEVICE\fR
	.SH DESCRIPTION
	.\" Add any additional description here
	.PP
	This utility sends one or more SCSI TEST UNIT READY commands to the
	\fIDEVICE\fR. This may be useful for timing the per command overhead.
	Note that TEST UNIT READY has no associated data, just a 6 byte
	command (with each byte a zero) and a returned SCSI status value.
	.PP
	This utility supports two command line syntaxes, the preferred one is
	shown first in the synopsis and explained in this section. A later section
	on the old command line syntax outlines the second group of options.
	.SH OPTIONS
	Arguments to long options are mandatory for short options as well.
	.TP
	\fB\-d\fR, \fB\-\-delay\fR=\fIMS\fR
	this option causes a delay of \fIMS\fR milliseconds to occur before each
	TEST UNIT READY command is issued.
	.TP
	\fB\-h\fR, \fB\-\-help\fR
	print out the usage message then exit.
	.TP
	\fB\-l\fR, \fB\-\-low\fR
	when [\fI\-\-progress\fR] is not being used, this utility tries to complete
	the SCSI TEST UNIT READY command(s) as quickly as possible. Usually it
	calls a library function to do each TUR (sg_ll_test_unit_ready). With this
	option it uses the lower level sg_pt interface (see sg_pt.h) to save a
	little time on each TUR.
	.TP
	\fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
	performs TEST UNIT READY \fINUM\fR times. If not given defaults to 1.
	These suffix multipliers are permitted: c C 1; w W 2; b B *512;
	k K KiB 1,024; KB 1,000; m M MiB 1,048,576; MB 1,000,000;
	g G GiB 1,073,741,824; and GB 1,000,000,000 . Also a suffix of the
	form "x<n>" multiplies the leading number by <n>. Alternatively a hex
	number may be given, prefixed by either '0x' or has a trailing 'h'.
	.TP
	\fB\-\-number\fR=\fINUM\fR
	same as \fI\-\-num=NUM\fR. Added for compatibility with sg_requests and
	other utilities in this package. The sg_request utility has taken over the
	role of polling the progress indication which was originally assigned to
	the TEST UNIT READY command. This is a change by T10.
	.TP
	\fB\-O\fR, \fB\-\-old\fR
	Switch to older style options. Please use as first option.
	.TP
	\fB\-p\fR, \fB\-\-progress\fR
	show progress indication (a percentage) if available. If \fI\-\-num=NUM\fR
	is given, \fINUM\fR is greater than 1 and an initial progress indication
	was detected then this utility waits 30 seconds before subsequent checks.
	If the \fI\-\-delay=MS\fR option is given then it will wait for that number
	of milliseconds instead of 30 seconds.
	Exits when \fINUM\fR is reached or there are no more progress indications.
	Ignores \fI\-\-time\fR option. See NOTES section below.
	.TP
	\fB\-t\fR, \fB\-\-time\fR
	after completing the requested number of TEST UNIT READY commands, outputs
	the total duration and the average number of commands executed per second.
	.TP
	\fB\-v\fR, \fB\-\-verbose\fR
	increase level or verbosity.
	.TP
	\fB\-V\fR, \fB\-\-version\fR
	print version string then exit.
	.SH NOTES
	The progress indication is optionally part of the sense data. When a prior
	command that takes a long time to complete (and typically precludes other
	media access commands) is still underway, the progress indication can be used
	to determine how long before the device returns to its normal state. Around
	SPC\-3 T10 changed the preferred command for polling the progress indication
	from TEST UNIT READY to REQUEST SENSE (see the sg_requests utility).
	.PP
	The SCSI FORMAT command for disks used with the IMMED bit set is an example
	of an operation that takes a significant amount of time and precludes other
	media access during that time. The IMMED bit set instructs the FORMAT command
	to return control to the application client once the format has commenced (see
	SBC\-3). Several long duration SCSI commands associated with tape drives also
	use the progress indication (see SSC\-3).
	.PP
	The \fIDEVICE\fR is opened with a read\-only flag (e.g. in Unix with the
	O_RDONLY flag).
	.PP
	Early standards suggested that the SCSI TEST UNIT READY command be used for
	polling the progress indication. More recent standards seem to suggest
	the SCSI REQUEST SENSE command should be used instead.
	.SH EXIT STATUS
	The exit status of sg_turs is 0 when it is successful (e.g. in the case of
	a mechanical disk, it is spun up and ready to accept IO commands). For this
	utility the other exit status values of interest are 2, 12 and 13. 12 is for
	the case when the sense key is "not ready" [0x2] and the additional sense
	code ends with "Target port in standby state" [0x4, 0xb]. 13 is for the
	case when the sense key is "not ready" [0x2] and the additional sense code
	is "Target port in unavailable state" [0x4, 0xc]. All other cases when
	the sense key is "not ready" [0x2] will set the exit status to 2.
	For other exit status values see the sg3_utils(8) man page.
	.SH OLDER COMMAND LINE OPTIONS
	The options in this section were the only ones available prior to sg3_utils
	version 1.23 . Since then this utility defaults to the newer command line
	options which can be overridden by using \fI\-\-old\fR (or \fI\-O\fR) as the
	first option. See the ENVIRONMENT VARIABLES section for another way to
	force the use of these older command line options.
	.TP
	\fB\-d\fR, \fB\-\-delay\fR=\fIMS\fR
	this option causes a delay of \fIMS\fR milliseconds to occur before each
	TEST UNIT READY command is issued.
	.TP
	\fB\-n\fR=\fINUM\fR
	performs TEST UNIT READY \fINUM\fR times. If not given defaults to 1.
	Equivalent to \fI\-\-num=NUM\fR in the main description.
	.TP
	\fB-N\fR, \fB\-\-new\fR
	Switch to the newer style options.
	.TP
	\fB\-p\fR
	show progress indication (a percentage) if available.
	Equivalent to \fI\-\-progress\fR in the main description.
	.TP
	\fB\-t\fR
	after completing the requested number of TEST UNIT READY commands, outputs
	the total duration and the average number of commands executed per second.
	Equivalent to \fI\-\-time\fR in the main description.
	.TP
	\fB\-v\fR
	increase level of verbosity.
	.TP
	\fB\-V\fR
	print out version string then exit.
	.SH ENVIRONMENT VARIABLES
	Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS
	can be given. When it is present this utility will expect the older command
	line options. So the presence of this environment variable is equivalent to
	using \fI\-\-old\fR (or \fI\-O\fR) as the first command line option.
	.SH AUTHORS
	Written by D. Gilbert
	.SH COPYRIGHT
	Copyright \(co 2000\-2022 Douglas Gilbert
	.br
	This software is distributed under the GPL version 2. There is NO
	warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
	.SH "SEE ALSO"
	.B sg_inq, sg_requests (sg3_utils)