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

NAME

6       sg_read - read blocks of data continually from same offset
7

SYNOPSIS

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

DESCRIPTION

14       Read  data  from  a Linux SCSI generic (sg) device, a block device or a
15       normal file with each read command issued to the same offset or logical
16       block  address  (lba). This can be used to test (or time) disk caching,
17       SCSI (or some other) transport throughput, and/or  SCSI  command  over‐
18       head.
19
20       When  the  COUNT value is positive, then up to BPT blocks are read at a
21       time, until the COUNT is exhausted. Each read operation starts  at  the
22       same  lba  which, if SKIP is not given, is the beginning of the file or
23       device.
24
25       The COUNT value may be negative when IFILE is a sg device or is a block
26       device  with  'blk_sgio=1'  set. Alternatively 'bpt=0' may be given. In
27       these cases |COUNT| "zero block" SCSI READ commands are  issued.  "Zero
28       block"  means  "do  nothing"  for SCSI READ 10, 12 and 16 byte commands
29       (but not for the 6 byte variant). In practice "zero  block"  SCSI  READ
30       commands  have  low  latency and so are one way to measure SCSI command
31       overhead.
32

OPTIONS

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

NOTES

129       BYTES  and  BLOCKS  may be followed by one of these multiplicative suf‐
130       fixes: c C *1; w W *2; b B *512; k K KiB *1,024; KB  *1,000;  m  M  MiB
131       *1,048,576; MB *1,000,000; g G Gib *(2**30); GB *(10**9). Also a suffix
132       of the form "x<n>" multiplies the leading number by <n>.  These  multi‐
133       plicative  suffixes  are  compatible with GNU's dd command (since 2002)
134       which claims compliance with SI and with IEC 60027-2.
135
136       Alternatively numerical values can be given in hexadecimal preceded  by
137       either  "0x"  or "0X" (or with a trailing "h" or "H"). When hex numbers
138       are given, multipliers cannot be used.
139
140       Data usually gets to the user space in a 2  stage  process:  first  the
141       SCSI  adapter  DMAs  into  kernel buffers and then the sg driver copies
142       this data into user memory.  This is called "indirect IO" and there  is
143       a  "dio" option to select "direct IO" which will DMA directly into user
144       memory. Due to some issues "direct IO" is disabled in the sg driver and
145       needs  a  configuration  change  to activate it. This is typically done
146       with "echo 1 > /proc/scsi/sg/allow_dio". An alternate way to avoid  the
147       2 stage copy is to select memory mapped IO with 'mmap=1'.
148

SIGNALS

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

EXAMPLES

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

EXIT STATUS

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

AUTHORS

179       Written by Doug Gilbert.
180

REPORTING BUGS

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

SEE ALSO

191       To  time  streaming  media  read  or  write  time  see  sg_dd is in the
192       sg3_utils package. The lmbench package  contains  lmdd  which  is  also
193       interesting.  raw(8), dd(1)
194
195
196
197sg3_utils-1.23                   January 2007                       SG_READ(8)
Impressum