diff options
Diffstat (limited to 'doc/sg_seek.8')
-rw-r--r-- | doc/sg_seek.8 | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/doc/sg_seek.8 b/doc/sg_seek.8 new file mode 100644 index 00000000..52ced593 --- /dev/null +++ b/doc/sg_seek.8 @@ -0,0 +1,146 @@ +.TH SG_SEEK "8" "September 2018" "sg3_utils\-1.43" SG3_UTILS +.SH NAME +sg_seek \- send SCSI SEEK, PRE-FETCH(10) or PRE-FETCH(16) command +.SH SYNOPSIS +.B sg_seek +[\fI\-\-10\fR] [\fI\-\-count=NC\fR] [\fI\-\-grpnum=GN\fR] [\fI\-\-help\fR] +[\fI\-\-immed\fR] [\fI\-\-lba=LBA\fR] [\fI\-\-num\-blocks=NUM\fR] +[\fI\-\-pre\-fetch\fR] [\fI\-\-readonly\fR] [\fI\-\-skip=SB\fR] +[\fI\-\-time\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] +[\fI\-\-wrap\-offset=WO\fR] \fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Sends a SCSI SEEK(10), PRE\-FETCH(10) or PRE\-FETCH(16) command to the +\fIDEVICE\fR. The SEEK command has been obsolete since SBC\-2 (2005) but +still is supported on some hard disks and even some SSDs (solid state +disks). The PRE\-FETCH command can be viewed as SEEK's modern replacement. +Instead of talking about moving the disk heads to the track containing +the sort after LBA, it talks about bringing the sort after LBA (and a +given number of blocks) into the disk's cache. Also the PRE\-FETCH commands +have an IMMED field. +.PP +The PRE\-FETCH commands can report "real" errors but usually they will report +one of two "good" statuses. To do this they return the rarely used CONDITION +MET status. If the number of blocks does actually fit in the cache (when +IMMED=0) or there is enough room in the cache when the command arrives (when +IMMED=1) then a CONDITION MET status is returned. If the requested number of +blocks did not fit (IMMED=0) or would not fit (IMMED=1) then status GOOD +is returned. So if a disk has a large cache and PRE\-FETCH is used sparingly +then the command is more likely to return CONDITION MET than GOOD. This +presents some SCSI sub\-systems with problems as due to its rareness they +mishandle CONDITION MET and treat it as an error (see NOTES section below). +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-T\fR, \fB\-\-10\fR +use a 10 byte cdb command, either SEEK(10) or PRE\-FETCH(10) command. In +the absence of the \fI\-\-pre\-fetch\fR option, the SEEK(10) command is +used. If the \fI\-\-pre\-fetch\fR option is given without this option +then a PRE\-FETCH(16) command is used. +.TP +\fB\-c\fR, \fB\-\-count\fR=\fINC\fR +\fINC\fR is the number of commands (one of SEEK(10), PRE\-FETCH(10) or +PRE\-FETCH(16)) that will be executed. The default value is 1. If an error +occurs it is noted and the program continues until \fINC\fR is exhausted. +If \fINC\fR is 0 then options are checked and the \fIDEVICE\fR is opened +but no commands are sent. +.TP +\fB\-g\fR, \fB\-\-grpnum\fR=\fIGN\fR +\fIGN\fR is the group number, a value between 0 and 63 (in hex: 0x3f). The +default value is 0. This option is ignored if the selected command is +SEEK(10). +.TP +\fB\-h\fR, \fB\-\-help\fR +output the usage message then exit. +.TP +\fB\-i\fR, \fB\-\-immed\fR +this option only applies to PRE\-FETCH(10) and PRE\-FETCH(16), setting +the IMMED bit. Without this option, the \fIDEVICE\fR returns after it has +completed transferring all, or part of, the requested blocks into the +cache. If this option is given the \fIDEVICE\fR returns after it has done +sanity checks on the cdb (e.g. making sure the \fILBA\fR is greater than +the number of available blocks) and before it does the transfer into the +cache. +.br +Note that even when this option is given, the return status from the +PRE\-FETCH commands is still either CONDITION MET status (if the cache seems +to have enough free space for the transfer) or a GOOD status (if the cache +does not seem to have enough free space). +.TP +\fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR +\fILBA\fR is the starting logical block address that is placed in the +command descriptor block (cdb) of the selected command. Note that the +\fILBA\fR field in SEEK(10) and PRE\-FETCH(10) is a 32 bit quantity, +while with PRE\-FETCH(16) it is a 64 bit quantity. The default value is +0 . +.TP +\fB\-n\fR, \fB\-\-num\-blocks\fR=\fINUM\fR +\fINUM\fR is the number of blocks, starting at and including \fILBA\fR, +to place in the \fIDEVICE\fR's cache. The SEEK(10) command does not use +the \fINUM\fR value. For PRE\-FETCH(10) \fINUM\fR is a 16 bit quantity, +while for PRE\-FETCH(16) it is a 32 bit quantity. The default value is +1 . If \fINUM\fR is 0 then the \fIDEVICE\fR will attempt to transfer all +blocks from the given \fILBA\fR to the end of the medium. +.TP +\fB\-p\fR, \fB\-\-pre\-fetch\fR +this option selects either PRE\-FETCH(10) or PRE\-FETCH(16) commands. With +the \fI\-\-10\fR also given, the PRE\-FETCH(10) command is selected; without +that option PRE\-FETCH(16) is selected. The default (in the absence of this +and other 'selecting' options) the SEEK(10) command is selected. +.TP +\fB\-r\fR, \fB\-\-readonly\fR +this option sets a 'read\-only' flag when the underlying operating system +opens the given \fIDEVICE\fR. This may not work since operating systems can +not easily determine whether a pass\-through is a logical read or write +operation so they take a risk averse stance and require read\-write type +\fIDEVICE\fR opens irrespective of what is performed by the pass\-through. +.TP +\fB\-s\fR, \fB\-\-skip\fR=\fISB\fR +\fISB\fR is the number of logical block addresses to skip, between repeated +commands when \fINC\fR is greater than 1. The default value of \fISB\fR is +1 . \fISB\fR may be set to 0 so that all \fINC\fR PRE\-FETCH commands use +the same \fILBA\fR. +.TP +\fB\-t\fR, \fB\-\-time\fR +if given the elapsed time to execute \fINC\fR commands is recorded. This is +printed out before this utility exits. If \fINC\fR is greater than 1 then +the the "per command" time is also printed. +.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. +.TP +\fB\-w\fR, \fB\-\-wrap\-offset\fR=\fIWO\fR +\fIWO\fR is the number of blocks, relative to \fILBA\fR, that when exceeded, +set the next command's logical block address back to \fILBA\fR. Whether +this "reset\-to\-LBA" action occurs depends on the values \fINC\fR and +\fISB\fR. +.SH NOTES +Prior to Linux kernel 4.17 the CONDITION MET status was logged as an error. +Recent versions of FreeBSD handle the CONDITION MET status properly. +.PP +If either the \fI\-\-count=NC\fR or \fI\-\-verbose\fR option is given then +a summary line like the following is output: +.PP + Command count=5, number of condition_mets=3, number of goods=2 +.PP +before the utility exits. +.SH EXIT STATUS +The exit status of sg_seek is 0 (GOOD) or 25 (CONDITION_MET) when this +utility is successful. If multiple commands are executed (e.g. when \fINC\fR +is greater than 1) then the result of the last executed SEEK or PRE\-FETCH +command sets the exit status. Otherwise see the sg3_utils(8) man page. +.SH AUTHORS +Written by Douglas Gilbert. +.SH "REPORTING BUGS" +Report bugs to <dgilbert at interlog dot com>. +.SH COPYRIGHT +Copyright \(co 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 sg_vpd(sg3_utils); sdparm(sdparm) |