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

NAME

6       sg_read  - read multiple blocks of data, optionally with SCSI READ com‐
7       mands
8

SYNOPSIS

10       sg_read [blk_sgio=0|1] [bpt=BPT] [bs=BS] [cdbsz=6|10|12|16] count=COUNT
11       [dio=0|1]   [dpo=0|1]   [fua=0|1]  if=IFILE  [mmap=0|1]  [no_dxfer=0|1]
12       [odir=0|1] [skip=SKIP] [time=TI] [verbose=VERB] [--help] [--version]
13

DESCRIPTION

15       Read data from a Linux SCSI generic (sg) device, a block  device  or  a
16       normal file with each read command issued to the same offset or logical
17       block address (lba). This can be used to test (or time)  disk  caching,
18       SCSI  (or  some  other) transport throughput, and/or SCSI command over‐
19       head.
20
21       When the COUNT value is positive, then up to BPT blocks are read  at  a
22       time,  until  the COUNT is exhausted. Each read operation starts at the
23       same lba which, if SKIP is not given, is the beginning of the  file  or
24       device.
25
26       The COUNT value may be negative when IFILE is a sg device or is a block
27       device with 'blk_sgio=1' set. Alternatively 'bpt=0' may  be  given.  In
28       these  cases  |COUNT| "zero block" SCSI READ commands are issued. "Zero
29       block" means "do nothing" for SCSI READ 10, 12  and  16  byte  commands
30       (but  not  for  the 6 byte variant). In practice "zero block" SCSI READ
31       commands have low latency and so are one way to  measure  SCSI  command
32       overhead.
33
34       Please  note:  this is a very old utility that uses 32 bit integers for
35       disk LBAs and the count. Hence it will not be able to address beyond  2
36       Terabytes  on  a  disk  with  logical  blocks  that are 512 bytes long.
37       Alternatives are the sg_dd and ddpt utilities.
38

OPTIONS

40       blk_sgio=0 | 1
41              The default action of this utility is to  use  the  Unix  read()
42              command  when  the IFILE is a block device. In lk 2.6 many block
43              devices can handle SCSI commands issued via the SG_IO ioctl.  So
44              when this option is set the SG_IO ioctl sends SCSI READ commands
45              to IFILE if it is a block device.
46
47       bpt=BPT
48              where BPT is the maximum number of blocks  each  read  operation
49              fetches.   Fewer blocks will be fetched when the remaining COUNT
50              is less than BPT. The default value for BPT is  128.  Note  that
51              each  read  operation  starts  at  the  same  lba  (as  given by
52              skip=SKIP or 0).  If 'bpt=0' then the COUNT  is  interpreted  as
53              the number of zero block SCSI READ commands to issue.
54
55       bs=BS  where BS is the size (in bytes) of each block read. This must be
56              the block size of the physical device (defaults to 512) if  SCSI
57              commands are being issued to IFILE.
58
59       cdbsz=6 | 10 | 12 | 16
60              size  of  SCSI READ commands issued on sg device names, or block
61              devices if 'blk_sgio=1' is given. Default is 10 byte  SCSI  READ
62              cdbs.
63
64       count=COUNT
65              when  COUNT  is  a  positive number, read that number of blocks,
66              typically with multiple read operations. When COUNT is  negative
67              then  |COUNT|  SCSI  READ commands are performed requesting zero
68              blocks to be transferred. This option is mandatory.
69
70       dio=0 | 1
71              default is 0 which selects indirect  IO.  Value  of  1  attempts
72              direct IO which, if not available, falls back to indirect IO and
73              notes this at completion. This option is only active if IFILE is
74              an    sg    device.     If    direct    IO   is   selected   and
75              /proc/scsi/sg/allow_dio has the value of 0  then  a  warning  is
76              issued (and indirect IO is performed)
77
78       dpo=0 | 1
79              when set the disable page out (DPO) bit in SCSI READ commands is
80              set.  Otherwise the DPO bit is cleared (default).
81
82       fua=0 | 1
83              when set the force unit access (FUA) bit in SCSI  READ  commands
84              is set.  Otherwise the FUA bit is cleared (default).
85
86       if=IFILE
87              read  from this IFILE. This argument must be given. If the IFILE
88              is a normal file then it must be seekable (if (COUNT >  BPT)  or
89              skip=SKIP  is  given). Hence stdin is not acceptable (and giving
90              "-" as the IFILE argument is reported as an error).
91
92       mmap=0 | 1
93              default is 0 which selects indirect IO. Value of 1 causes memory
94              mapped  IO  to  be  performed. Selecting both dio and mmap is an
95              error. This option is only active if IFILE is an sg device.
96
97       no_dxfer=0 | 1
98              when set then DMA transfers from the device are made into kernel
99              buffers  but  no  further (i.e. there is no second copy into the
100              user space). The default value is 0 in which case transfers  are
101              made into the user space.  When neither mmap nor dio is set then
102              data transfer are copied  via  kernel  buffers  (i.e.  a  double
103              copy). Mainly for testing.
104
105       odir=0 | 1
106              when  set  opens  an IFILE which is a block device with an addi‐
107              tional O_DIRECT flag. The default value is 0  (i.e.  don't  open
108              block devices O_DIRECT).
109
110       skip=SKIP
111              all  read  operations  will start offset by SKIP bs-sized blocks
112              from the start of the input file (or device).
113
114       time=TI
115              When TI is 0 (default) doesn't perform timing.   When  1,  times
116              transfer  and does throughput calculation, starting at the first
117              issued command until completion. When 2, times transfer and does
118              throughput  calculation,  starting  at the second issued command
119              until completion. When 3 times from third command, etc. An aver‐
120              age number of commands (SCSI READs or Unix read()s) executed per
121              second is also output.
122
123       verbose=VERB
124              as VERB increases so does the amount of  debug  output  sent  to
125              stderr.   Default  value is zero which yields the minimum amount
126              of debug output.  A value of 1 reports extra information that is
127              not repetitive.
128
129       --help Output the usage message then exit.
130
131       --version
132              Output the version string then exit.
133

NOTES

135       Various  numeric  arguments (e.g. SKIP) may include multiplicative suf‐
136       fixes or be given in hexadecimal. See the "NUMERIC  ARGUMENTS"  section
137       in the sg3_utils(8) man page.
138
139       Data  usually  gets  to  the user space in a 2 stage process: first the
140       SCSI adapter DMAs into kernel buffers and then  the  sg  driver  copies
141       this  data into user memory.  This is called "indirect IO" and there is
142       a "dio" option to select "direct IO" which will DMA directly into  user
143       memory. Due to some issues "direct IO" is disabled in the sg driver and
144       needs a configuration change to activate it.  This  is  typically  done
145       with  "echo 1 > /proc/scsi/sg/allow_dio". An alternate way to avoid the
146       2 stage copy is to select memory mapped IO with 'mmap=1'.
147

SIGNALS

149       The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIG‐
150       PIPE output the number of remaining blocks to be transferred; then they
151       have their default action.  SIGUSR1 causes the same information  to  be
152       output yet the copy continues.  All output caused by signals is sent to
153       stderr.
154

EXAMPLES

156       Let us assume that /dev/sg0 is a disk and we wish to  time  the  disk's
157       cache performance.
158
159          sg_read if=/dev/sg0 bs=512 count=1MB mmap=1 time=2
160
161       This  command  will continually read 128  512 byte blocks from block 0.
162       The "128" is the default value for 'bpt'  while  "block  0"  is  chosen
163       because  the  'skip'  argument  was not given. This will continue until
164       1,000,000 blocks are read. The idea behind using 'time=2' is  that  the
165       first  64  KiB  read  operation will involve reading the magnetic media
166       while the remaining read operations will "hit" the  disk's  cache.  The
167       output of third command will look like this:
168
169         time from second command to end was 4.50 secs, 113.70 MB/sec
170         Average number of READ commands per second was 1735.27
171         1000000+0 records in, SCSI commands issued: 7813
172

EXIT STATUS

174       The  exit  status  of sg_read is 0 when it is successful. Otherwise see
175       the sg3_utils(8) man page.
176

AUTHORS

178       Written by Douglas Gilbert.
179

REPORTING BUGS

181       Report bugs to <dgilbert at interlog dot com>.
182
184       Copyright © 2000-2019 Douglas Gilbert
185       This software is distributed under the GPL version 2. There is NO  war‐
186       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
187       POSE.
188

SEE ALSO

190       To time streaming media  read  or  write  time  see  sg_dd  is  in  the
191       sg3_utils  package and ddpt in a package of the same name.  The lmbench
192       package contains lmdd which is also interesting.  raw(8), dd(1)
193
194
195
196sg3_utils-1.45                  September 2019                      SG_READ(8)
Impressum