~ubuntu-branches/ubuntu/dapper/sg3-utils/dapper-backports

.TH SG_READ "8" "July 2006" "sg3_utils-1.21" SG3_UTILS
.SH NAME
sg_read \- read blocks of data continually from same offset
.SH SYNOPSIS
.B sg_read
[\fIblk_sgio=0|1\fR] [\fIbpt=<n>\fR] [\fIbs=<n>\fR] [\fIcdbsz=6|10|12|16\fR]
\fIcount=<n>\fR [\fIdio=0|1\fR] [\fIdpo=0|1\fR] [\fIfua=0|1\fR]
\fIif=<ifile>\fR [\fImmap=0|1\fR] [\fIno_dxfer=0|1\fR] [\fIodir=0|1\fR]
[\fIskip=<n>\fR] [\fItime=<n>\fR] [\fI--help\fR] [\fI--version\fR]
.SH DESCRIPTION
.\" Add any additional description here
.PP
Read data from a Linux SCSI generic (sg) device, a block device or
a normal file with each read command issued to the same offset or
logical block address (lba). This can be used to test (or time) disk
caching, SCSI (or some other) transport throughput, and/or SCSI
command overhead.
.PP
When the 'count' argument is positive, then up to 'bpt' blocks are read
at a time, until the 'count' is exhausted. Each read operation
starts at the same lba which, if 'skip' is not given, is the beginning
of the file or device.
.PP
The 'count' argument may be negative when '<ifile>' is a sg device
or is a block device with 'blk_sgio=1' set. Alternatively 'bpt=0'
may be given. In these cases |'count'| "zero block" SCSI READ commands
are issued. "Zero block" means "do nothing" for SCSI READ 10, 12 and
16 byte commands (but not for the 6 byte variant). In practice "zero
block" SCSI READ commands have low latency and so are one way to measure
SCSI command overhead.
.TP
blk_sgio=0 | 1
The default action of this utility is to use the Unix read() command when
the <ifile> is a block device. In lk 2.6 many block devices can handle
SCSI commands issued via the SG_IO ioctl. So when this option is set
the SG_IO ioctl sends SCSI READ commands to <ifile> if it is a block
device.
.TP
bpt=BLOCKS
each read operation will be made using this number of blocks (or less if 
near the end of 'count'). Default is 128. Note also that each read
operation starts at the same lba (as given by 'skip=<n>' or 0). If 'bpt=0'
then the 'count' is interpreted as the number of zero block READ SCSI
commands to issue.
.TP
bs=BYTES
this
.B must
be the block size of the physical device (defaults to 512) if SCSI commands
are being issued to <ifile>.
.TP
cdbsz=6 | 10 | 12 | 16
size of SCSI READ commands issued on sg device names, or block devices
if 'blk_sgio=1' is given. Default is 10 byte SCSI READ cdbs.
.TP
count=BLOCKS
read this number of blocks when BLOCKS is a positive number. When BLOCKS is
negative then |BLOCKS| SCSI READ commands are performed requesting zero blocks
to be transferred. The 'count=' argument must be given.
.TP
dio=0 | 1
default is 0 which selects indirect IO. Value of 1 attempts direct
IO which, if not available, falls back to indirect IO and notes this
at completion. This option is only active if <ifile> is an sg device.
If direct IO is selected and /proc/scsi/sg/allow_dio
has the value of 0 then a warning is issued (and indirect IO is performed)
.TP
dpo=0 | 1
when set the disable page out (DPO) bit in SCSI READ commands is set.
Otherwise the DPO bit is cleared (default).
.TP
fua=0 | 1
when set the force unit access (FUA) bit in SCSI READ commands is set.
Otherwise the FUA bit is cleared (default).
.TP
if=<ifile>
read from this <ifile>. This argument must be given. If the <ifile> is a
normal file then it must be seekable (if ('count' > 'bpt') or 'skip' is
given). Hence stdin is not acceptable (and giving "-" as the <ifile>
argument is reported as an error).
.TP
mmap= 0 | 1
default is 0 which selects indirect IO. Value of 1 causes memory mapped
IO to be performed. Selecting both dio and mmap is an error. This option
is only active if <ifile> is an sg device.
.TP
no_dxfer= 0 | 1
when set then DMA transfers from the device are made into kernel buffers
but no further (i.e. there is no second copy into the user space). The
default value is 0 in which case transfers are made into the user space.
When neither mmap nor dio is set then data transfer are copied via
kernel buffers (i.e. a double copy). Mainly for testing.
.TP
odir= 0 | 1
when set opens an <ifile> which is a block device with an additional
O_DIRECT flag. The default value is 0 (i.e. don't open block devices
O_DIRECT).
.TP
skip=BLOCKS
all read operations will start offset by BLOCKS bs-sized blocks 
from the start of input file (or device).
.TP
time=<n>
When 0 (default) doesn't perform timing.
When 1, times transfer and does throughput calculation, starting at the
first issued command until completion. When 2, times transfer and does 
throughput calculation, starting at the second issued command until 
completion. When 3 times from third command, etc. An average number of
commands (SCSI READs or Unix read()s) executed per second is also
output.
.TP
--help
Output the usage message then exit.
.TP
--version
Output the version string then exit.
.PP
BYTES and BLOCKS may be followed by one of these multiplicative suffixes:
c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576;
MB *1,000,000; g G Gib *(2**30); GB *(10**9). Also a suffix of
the form "x<n>" multiplies the leading number by <n>. These multiplicative
suffixes are compatible with GNU's dd command (since 2002) which claims
compliance with SI and with IEC 60027-2.
.PP
Alternatively numerical values can be given in hexadecimal preceded by
either "0x" or "0X" (or with a trailing "h" or "H"). When hex numbers are
given, multipliers cannot be used.
.PP
Data usually gets to the user space in a 2 stage process: first the
SCSI adapter DMAs into kernel buffers and then the sg driver copies
this data into user memory.
This is called "indirect IO" and there is a "dio" option to select
"direct IO" which will DMA directly into user memory. Due to some
issues "direct IO" is disabled in the sg driver and needs a 
configuration change to activate it. This is typically done with
"echo 1 > /proc/scsi/sg/allow_dio". An alternate way to avoid the
2 stage copy is to select memory mapped IO with 'mmap=1'.
.SH SIGNALS
The signal handling has been borrowed from dd: SIGINT, SIGQUIT and
SIGPIPE output the number of remaining blocks to be transferred;
then they have their default action.
SIGUSR1 causes the same information to be output yet the copy continues.
All output caused by signals is sent to stderr.
.SH EXAMPLES
.PP
Let us assume that /dev/sg0 is a disk and we wish to time the disk's
cache performance.
.PP
   sg_read if=/dev/sg0 bs=512 count=1MB mmap=1 time=2
.PP
This command will continually read 128  512 byte blocks from block 0. 
The "128" is the default value for 'bpt' while "block 0" is chosen 
because the 'skip' argument was not given. This will continue until 
1,000,000 blocks are read. The idea behind using 'time=2' is that the 
first 64 KiB read operation will involve reading the magnetic media
while the remaining read operations will "hit" the disk's cache. The 
output of third command will look like this:
.PP
  time from second command to end was 4.50 secs, 113.70 MB/sec
.br
  Average number of READ commands per second was 1735.27
.br
  1000000+0 records in, SCSI commands issued: 7813
.SH EXIT STATUS
The exit status of sg_read is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH AUTHORS
Written by Doug Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2000-2006 Douglas Gilbert
.br
This software is distributed under the GPL version 2. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
To time streaming media read or write time see
.B sg_dd
is in the sg3_utils package. The lmbench package contains
.B lmdd
which is also interesting.
.B raw(8), dd(1)