SGI Techpubs Library

Linux  »  Man Pages
find in page

sg_dd


SYNOPSIS

       sg_dd [append=0|1] [blk_sgio=0|1] [bpt=<n>] [bs=<n>] [cdbsz=6|10|12|16]
       [coe=0|1] [count=<n>] [dio=0|1]  [fua=0|1|2|3]  [ibs=<n>]  [if=<ifile>]
       [obs=<n>]  [odir=0|1]  [of=<ofile>]  [seek=<n>]  [skip=<n>]  [sync=0|1]
       [time=0|1] [--version]


DESCRIPTION

       Copy data to and from Linux SCSI generic (sg) devices, raw devices  and
       those  block devices that support the SG_IO ioctl (which are only found
       in the lk 2.6 series). Data may be copied to and from normal  files  as
       well.   Similar  syntax and semantics to dd(1) but does not perform any
       conversions.

       append=0 | 1
              when set to 1 the output will be appended  to  the  normal  file
              given to the "of=<name>" argument. Appending only takes place to
              normal files: not pipes nor raw files nor sg devices. Error mes-
              sage produced if append=1 and seek=<n> where <n> > 0. Default is
              0 which starts output at offset  of a normal  file  (subject  to
              the "seek=" argument).

       blk_sgio=0 | 1
              when  set  to  0  block devices (e.g. /dev/sda) are treated like
              normal files. When set to 1 block devices are assumed to  accept
              the  SG_IO  ioctl;  this is only appropriate for kernels from lk
              2.6.0 .  Default is 0.

       bpt=BLOCKS
              each IO transaction will be made using this number of blocks (or
              less  if  near  the end of count). Default is 128. So for bs=512
              the reads and writes will each convey 64KB of  data  by  default
              (less if near the end of the transfer or memory restrictions).

       bs=BYTES
              this  must  be  the block size of the physical device. Note that
              this differs from dd(1) which permits "bs"  to  be  an  integral
              multiple.  Default is 512 which is usually correct for disks but
              incorrect for cdroms (which normally have 2048 byte blocks).

       cdbsz=6 | 10 | 12 | 16
              size of SCSI READ and/or WRITE  commands  issued  on  sg  device
              names.   Default is 10 byte SCSI command blocks (unless calcula-
              tions indicate that a 4 byte block number may  be  exceeded,  in
              which case it defaults to 16 byte SCSI commands)

       coe=0 | 1
              set to 1 for continue on error: if reading assume zeros read, if
              writing then ignore and continue. Only applies to errors  on  sg
              devices  (e.g.   errors  on normal files will stop sg_dd). Error
              messages are still sent to stderr. Similar to "conv=noerror"  in
              dd(1) command. Default is 0 which implies stop on error.

       count=BLOCKS
              copy  this  number of blocks. Default is the minimum number that
              sg devices return from READ CAPACITY. Other device  types  (e.g.
              normal  files)  are _not_ probed for their size. Thus if neither

       fua=0 | 1 | 2 | 3
              force unit access bit. When 3, fua is set on both "if" and "of",
              when  2,  fua is set on "if", when 1, fua is set on "of", when 0
              (default), fua is cleared on both. 6 byte SCSI  READ  and  WRITE
              commands  (cdbsz=6)  do not support the fua bit. Only active for
              sg device file names

       ibs=BYTES
              if given must be the same as bs

       if=FILE
              read from FILE instead of stdin. A file name of - is taken to be
              stdin

       obs=BYTES
              if given must be the same as bs

       odir=0 | 1
              when  set  to  one  opens block devices (e.g. /dev/sda) with the
              O_DIRECT flag. User memory buffers are aligned to the page  size
              when set. The default is 0 (i.e. the O_DIRECT flag is not used).
              The blk_sgio flag takes precedence if it is  also  set.  Has  no
              effect on sg, normal or raw files.

       of=FILE
              write to FILE instead of stdout. A file name of - is taken to be
              stdout.  If FILE is /dev/null then no  actual  writes  are  per-
              formed.  If  FILE is .  (period) then it is treated the same way
              as /dev/null (this is a shorthand notation).

       seek=BLOCKS
              skip BLOCKS bs-sized blocks at start of output

       skip=BLOCKS
              skip BLOCKS bs-sized blocks at start of input

       sync=0 | 1
              when 1, does SYNCHRONIZE CACHE command on "of" at the end of the
              transfer.  Only active when "of" is a sg device file name

       time=0 | 1
              when  1,  times  transfer  and does throughput calculation, out-
              putting the results (to stderr) at completion. When 0  (default)
              doesn’t perform timing

       --version
              outputs version number information and exits

       A raw device must be bound to a block device prior to using sg_dd.  See
       raw(8) for more information about binding raw devices. To be safe,  the
       sg  device  mapping  to  SCSI block devices should be checked with "cat
       /proc/scsi/scsi", or sg_map before use.

       The count is only deduced for sg devices (minimum > 0 if both input and
       output  are sg devices) otherwise it defaults to 0. This is for safety!
       either "0x" or "0X". When hex numbers are given multipliers  cannot  be
       used.

       The  count,  skip and seek parameters can take 64 bit values (i.e. very
       big numbers). Other values are limited to what can fit in a  signed  32
       bit number.

       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 (write operations reverse this sequence).
       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  configura-
       tion  change  to  activate  it.  This  is typically done with "echo 1 >
       /proc/scsi/sg/allow_dio".

       All informative, warning and error output is sent  to  stderr  so  that
       dd’s output file can be stdout and remain unpolluted. If no options are
       given, then the usage message is output and nothing else happens.


EXAMPLES

       Looks quite similar in usage to dd:

          sg_dd if=/dev/sg0 of=t bs=512 count=1M

       This will copy 1 million 512 byte blocks  from  the  device  associated
       with  /dev/sg0  (which should have 512 byte blocks) to a file called t.
       Assuming /dev/sda and /dev/sg0 are the same device then  the  above  is
       equivalent to:

          dd if=/dev/sda of=t bs=512 count=0xf4240

       although dd’s speed may improve if bs was larger and count was suitably
       reduced. Using a raw device to do something similar on a IDE disk:

          raw /dev/raw/raw1 /dev/hda
          sg_dd if=/dev/raw/raw1 of=t bs=512 count=1M

       To copy a SCSI disk partition to an IDE disk partition:

          raw /dev/raw/raw2 /dev/hda3
          sg_dd if=/dev/sg0 skip=10123456 of=/dev/raw/raw2 bs=512

       This assumes a valid partition is found on the SCSI disk at  the  given
       skip block address (past the 5 GB point of that disk) and that the par-
       tition goes to the end of the SCSI disk. An explicit count is  probably
       a safer option. The partition is copied to /dev/hda3 which is an offset
       into the IDE disk /dev/hda . The  exact  number  of  blocks  read  from
       /dev/sg0 are written to /dev/hda (i.e. no padding).

       To time a streaming read of the first 1 GB on a disk this command could
       be used:

          sg_dd if=/dev/sg0 of=/dev/null bs=512 count=2m time=1

       On completion this will output a line like: "time to transfer data  was


SIGNALS

       The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIG-
       PIPE output the number of remaining blocks to be  transferred  and  the
       records  in + out counts; 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.


AUTHORS

       Written by Doug Gilbert and Peter Allworth.


REPORTING BUGS

       Report bugs to <dgilbert@interlog.com>.


COPYRIGHT

       Copyright © 2000-2003 Douglas Gilbert
       This  software is distributed under the GPL version 2. There is NO war-
       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR-
       POSE.


SEE ALSO

       A  POSIX  threads  version  of  this  command  called  sgp_dd is in the
       sg3_utils package. Another version from that package is  called  sgm_dd
       and  it  uses memory mapped IO to speed transfers from sg devices.  The
       lmbench package contains lmdd which is  also  interesting.  For  moving
       data  to  and  from  tapes  see  dt  which  is found at http://www.bit-
       net.com/~rmiller/dt.html. See also raw(8), dd(1)

sg3_utils-1.05                   November 2003                        SG_DD(8)

Output converted with man2html


home/search | what's new | help