1SG_READ(8) SG3_UTILS SG_READ(8)
2
6 sg_read - read blocks of data continually from same offset
7
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
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 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 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
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 --help Output the usage message then exit.
124 --version
126 Output the version string then exit.
127
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 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 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
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
157 Let us assume that /dev/sg0 is a disk and we wish to time the disk's
158 cache performance.
159 sg_read if=/dev/sg0 bs=512 count=1MB mmap=1 time=2
161 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 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
175 The exit status of sg_read is 0 when it is successful. Otherwise see
176 the sg3_utils(8) man page.
177
179 Written by Doug Gilbert.
180
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
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)
194sg3_utils-1.23 January 2007 SG_READ(8)