sg_seek [--10] [--count=NC]
[--grpnum=GN] [--help] [--immed] [--lba=LBA]
[--num-blocks=NUM] [--pre-fetch] [--readonly]
[--skip=SB] [--time] [--verbose] [--version]
[--wrap-offset=WO] DEVICE
Sends a SCSI SEEK(10), PRE-FETCH(10) or PRE-FETCH(16) command to
the DEVICE. 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.
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).
Arguments to long options are mandatory for short options as
well.
- -T, --10
- use a 10 byte cdb command, either SEEK(10) or PRE-FETCH(10) command. In
the absence of the --pre-fetch option, the SEEK(10) command is
used. If the --pre-fetch option is given without this option then a
PRE-FETCH(16) command is used.
- -c,
--count=NC
- NC 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 NC is exhausted.
If NC is 0 then options are checked and the DEVICE is opened
but no commands are sent.
- -g,
--grpnum=GN
- GN 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).
- -h, --help
- output the usage message then exit.
- -i, --immed
- this option only applies to PRE-FETCH(10) and PRE-FETCH(16), setting the
IMMED bit. Without this option, the DEVICE returns after it has
completed transferring all, or part of, the requested blocks into the
cache. If this option is given the DEVICE returns after it has done
sanity checks on the cdb (e.g. making sure the LBA is greater than
the number of available blocks) and before it does the transfer into the
cache.
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).
- -l,
--lba=LBA
- LBA is the starting logical block address that is placed in the
command descriptor block (cdb) of the selected command. Note that the
LBA 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 .
- -n,
--num-blocks=NUM
- NUM is the number of blocks, starting at and including LBA,
to place in the DEVICE's cache. The SEEK(10) command does not use
the NUM value. For PRE-FETCH(10) NUM is a 16 bit quantity,
while for PRE-FETCH(16) it is a 32 bit quantity. The default value is 1 .
If NUM is 0 then the DEVICE will attempt to transfer all
blocks from the given LBA to the end of the medium.
- -p,
--pre-fetch
- this option selects either PRE-FETCH(10) or PRE-FETCH(16) commands. With
the --10 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.
- -r,
--readonly
- this option sets a 'read-only' flag when the underlying operating system
opens the given DEVICE. 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
DEVICE opens irrespective of what is performed by the
pass-through.
- -s,
--skip=SB
- SB is the number of logical block addresses to skip, between
repeated commands when NC is greater than 1. The default value of
SB is 1 . SB may be set to 0 so that all NC PRE-FETCH
commands use the same LBA.
- -t, --time
- if given the elapsed time to execute NC commands is recorded. This
is printed out before this utility exits. If NC is greater than 1
then the the "per command" time is also printed.
- -v, --verbose
- increase the level of verbosity, (i.e. debug output).
- -V, --version
- print the version string and then exit.
- -w,
--wrap-offset=WO
- WO is the number of blocks, relative to LBA, that when
exceeded, set the next command's logical block address back to LBA.
Whether this "reset-to-LBA" action occurs depends on the values
NC and SB.
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.
If either the --count=NC or --verbose option is
given then a summary line like the following is output:
Command count=5, number of condition_mets=3, number of goods=2
before the utility exits.
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
NC 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.
Written by Douglas Gilbert.
Report bugs to <dgilbert at interlog dot com>.
Copyright © 2018 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO warranty;
not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
sg_vpd(sg3_utils); sdparm(sdparm)