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 Various numeric arguments (e.g. SKIP) may include multiplicative suf‐
130 fixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
131 in the sg3_utils(8) man page.
132 Data usually gets to the user space in a 2 stage process: first the
134 SCSI adapter DMAs into kernel buffers and then the sg driver copies
135 this data into user memory. This is called "indirect IO" and there is
136 a "dio" option to select "direct IO" which will DMA directly into user
137 memory. Due to some issues "direct IO" is disabled in the sg driver and
138 needs a configuration change to activate it. This is typically done
139 with "echo 1 > /proc/scsi/sg/allow_dio". An alternate way to avoid the
140 2 stage copy is to select memory mapped IO with 'mmap=1'.
141
143 The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIG‐
144 PIPE output the number of remaining blocks to be transferred; then they
145 have their default action. SIGUSR1 causes the same information to be
146 output yet the copy continues. All output caused by signals is sent to
147 stderr.
148
150 Let us assume that /dev/sg0 is a disk and we wish to time the disk's
151 cache performance.
152 sg_read if=/dev/sg0 bs=512 count=1MB mmap=1 time=2
154 This command will continually read 128 512 byte blocks from block 0.
156 The "128" is the default value for 'bpt' while "block 0" is chosen
157 because the 'skip' argument was not given. This will continue until
158 1,000,000 blocks are read. The idea behind using 'time=2' is that the
159 first 64 KiB read operation will involve reading the magnetic media
160 while the remaining read operations will "hit" the disk's cache. The
161 output of third command will look like this:
162 time from second command to end was 4.50 secs, 113.70 MB/sec
164 Average number of READ commands per second was 1735.27
165 1000000+0 records in, SCSI commands issued: 7813
166
168 The exit status of sg_read is 0 when it is successful. Otherwise see
169 the sg3_utils(8) man page.
170
172 Written by Doug Gilbert.
173
175 Report bugs to <dgilbert at interlog dot com>.
176
178 Copyright © 2000-2009 Douglas Gilbert
179 This software is distributed under the GPL version 2. There is NO war‐
180 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
181 POSE.
182
184 To time streaming media read or write time see sg_dd is in the
185 sg3_utils package. The lmbench package contains lmdd which is also
186 interesting. raw(8), dd(1)
187sg3_utils-1.27 March 2009 SG_READ(8)