path: root/doc/sg_seek.8

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