1SG_READ(8) SG3_UTILS SG_READ(8)
2
6 sg_read - read multiple blocks of data, optionally with SCSI READ com‐
7 mands
8
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
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 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 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 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
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 --help Output the usage message then exit.
130 --version
132 Output the version string then exit.
133
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 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
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
156 Let us assume that /dev/sg0 is a disk and we wish to time the disk's
157 cache performance.
158 sg_read if=/dev/sg0 bs=512 count=1MB mmap=1 time=2
160 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 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
174 The exit status of sg_read is 0 when it is successful. Otherwise see
175 the sg3_utils(8) man page.
176
178 Written by Douglas Gilbert.
179
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
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)
193sg3_utils-1.45 September 2019 SG_READ(8)