sg_seek(8)

1SG_SEEK(8)                         SG3_UTILS                        SG_SEEK(8)
2
3
4

NAME

6       sg_seek - send SCSI SEEK, PRE-FETCH(10) or PRE-FETCH(16) command
7

SYNOPSIS

9       sg_seek    [--10]   [--count=NC]   [--grpnum=GN]   [--help]   [--immed]
10       [--lba=LBA] [--num-blocks=NUM] [--pre-fetch]  [--readonly]  [--skip=SB]
11       [--time] [--verbose] [--version] [--wrap-offset=WO] DEVICE
12

DESCRIPTION

14       Sends  a  SCSI  SEEK(10), PRE-FETCH(10) or PRE-FETCH(16) command to the
15       DEVICE. The SEEK command has been obsolete since SBC-2 (2005) but still
16       is supported on some hard disks and even some SSDs (solid state disks).
17       The PRE-FETCH command can  be  viewed  as  SEEK's  modern  replacement.
18       Instead  of talking about moving the disk heads to the track containing
19       the sort after LBA, it talks about bringing the sort after LBA  (and  a
20       given  number of blocks) into the disk's cache. Also the PRE-FETCH com‐
21       mands have an IMMED field.
22
23       The PRE-FETCH commands can report "real" errors but usually  they  will
24       report  one  of  two "good" statuses. To do this they return the rarely
25       used CONDITION MET status. If the number of blocks does actually fit in
26       the  cache (when IMMED=0) or there is enough room in the cache when the
27       command arrives (when IMMED=1) then a CONDITION MET status is returned.
28       If  the  requested  number of blocks did not fit (IMMED=0) or would not
29       fit (IMMED=1) then status GOOD is returned. So if a disk  has  a  large
30       cache  and  PRE-FETCH is used sparingly then the command is more likely
31       to return CONDITION MET than GOOD. This presents some SCSI  sub-systems
32       with  problems  as due to its rareness they mishandle CONDITION MET and
33       treat it as an error (see NOTES section below).
34

OPTIONS

36       Arguments to long options are mandatory for short options as well.
37
38       -T, --10
39              use a 10 byte cdb command, either SEEK(10) or PRE-FETCH(10) com‐
40              mand.  In  the  absence  of the --pre-fetch option, the SEEK(10)
41              command is used. If the --pre-fetch option is given without this
42              option then a PRE-FETCH(16) command is used.
43
44       -c, --count=NC
45              NC  is the number of commands (one of SEEK(10), PRE-FETCH(10) or
46              PRE-FETCH(16)) that will be executed. The default value is 1. If
47              an  error  occurs it is noted and the program continues until NC
48              is exhausted.  If NC is 0  then  options  are  checked  and  the
49              DEVICE is opened but no commands are sent.
50
51       -g, --grpnum=GN
52              GN is the group number, a value between 0 and 63 (in hex: 0x3f).
53              The default value is 0. This option is ignored if  the  selected
54              command is SEEK(10).
55
56       -h, --help
57              output the usage message then exit.
58
59       -i, --immed
60              this  option  only  applies  to PRE-FETCH(10) and PRE-FETCH(16),
61              setting the IMMED bit. Without this option, the  DEVICE  returns
62              after  it  has  completed  transferring  all,  or  part  of, the
63              requested blocks into the cache. If this  option  is  given  the
64              DEVICE  returns after it has done sanity checks on the cdb (e.g.
65              making sure the LBA is greater  than  the  number  of  available
66              blocks) and before it does the transfer into the cache.
67              Note that even when this option is given, the return status from
68              the PRE-FETCH commands is still either CONDITION MET status  (if
69              the cache seems to have enough free space for the transfer) or a
70              GOOD status (if the cache does not  seem  to  have  enough  free
71              space).
72
73       -l, --lba=LBA
74              LBA  is the starting logical block address that is placed in the
75              command descriptor block (cdb) of  the  selected  command.  Note
76              that  the  LBA  field  in SEEK(10) and PRE-FETCH(10) is a 32 bit
77              quantity, while with PRE-FETCH(16) it is a 64 bit quantity.  The
78              default value is 0 .
79
80       -n, --num-blocks=NUM
81              NUM  is  the number of blocks, starting at and including LBA, to
82              place in the DEVICE's cache. The SEEK(10) command does  not  use
83              the NUM value. For PRE-FETCH(10) NUM is a 16 bit quantity, while
84              for PRE-FETCH(16) it is a 32 bit quantity. The default value  is
85              1  .  If  NUM  is 0 then the DEVICE will attempt to transfer all
86              blocks from the given LBA to the end of the medium.
87
88       -p, --pre-fetch
89              this option selects either PRE-FETCH(10) or  PRE-FETCH(16)  com‐
90              mands.  With  the  --10 also given, the PRE-FETCH(10) command is
91              selected; without that option  PRE-FETCH(16)  is  selected.  The
92              default  (in  the absence of this and other 'selecting' options)
93              the SEEK(10) command is selected.
94
95       -r, --readonly
96              this option sets a 'read-only' flag when the underlying  operat‐
97              ing system opens the given DEVICE. This may not work since oper‐
98              ating systems can not easily determine whether a pass-through is
99              a  logical  read  or  write operation so they take a risk averse
100              stance and require read-write type DEVICE opens irrespective  of
101              what is performed by the pass-through.
102
103       -s, --skip=SB
104              SB  is  the  number  of logical block addresses to skip, between
105              repeated commands when NC is greater than 1. The  default  value
106              of  SB  is  1 . SB may be set to 0 so that all NC PRE-FETCH com‐
107              mands use the same LBA.
108
109       -t, --time
110              if given the elapsed time to execute NC  commands  is  recorded.
111              This  is printed out before this utility exits. If NC is greater
112              than 1 then the the "per command" time is also printed.
113
114       -v, --verbose
115              increase the level of verbosity, (i.e. debug output).
116
117       -V, --version
118              print the version string and then exit.
119
120       -w, --wrap-offset=WO
121              WO is the number of blocks, relative to LBA, that when exceeded,
122              set  the  next  command's  logical  block  address  back to LBA.
123              Whether this "reset-to-LBA" action occurs depends on the  values
124              NC and SB.
125

NOTES

127       Prior  to  Linux  kernel 4.17 the CONDITION MET status was logged as an
128       error.  Recent versions of FreeBSD  handle  the  CONDITION  MET  status
129       properly.
130
131       If  either  the  --count=NC or --verbose option is given then a summary
132       line like the following is output:
133
134           Command count=5, number of condition_mets=3, number of goods=2
135
136       before the utility exits.
137

EXIT STATUS

139       The exit status of sg_seek is 0 (GOOD) or 25 (CONDITION_MET) when  this
140       utility  is successful. If multiple commands are executed (e.g. when NC
141       is greater than 1) then  the  result  of  the  last  executed  SEEK  or
142       PRE-FETCH  command sets the exit status. Otherwise see the sg3_utils(8)
143       man page.
144

AUTHORS

146       Written by Douglas Gilbert.
147

REPORTING BUGS

149       Report bugs to <dgilbert at interlog dot com>.
150

COPYRIGHT

152       Copyright © 2018 Douglas Gilbert
153       This software is distributed under a FreeBSD license. There is NO  war‐
154       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
155       POSE.
156