Provided by: sg3-utils_1.17-2_i386 bug

NAME

       sgm_dd  -  copies  data  to and from files and devices. Specialized for
       devices that understand the SCSI command set  and  does  memory  mapped
       transfers from sg devices.

SYNOPSIS

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

DESCRIPTION

       Copy data to and from any files. Specialized for "files" that are Linux
       SCSI generic (sg) devices and raw devices. Uses memory mapped transfers
       on  sg  devices.  Similar  syntax  and  semantics to dd(1) but does not
       perform any conversions.

       Will only perform memory mapped transfers when <ifile> or  <ofile>  are
       SCSI  generic  (sg) devices. If both <ifile> and <ofile> are sg devices
       then memory mapped transfers are only performed on <ifile>.

       bpt=BLOCKS
              each IO transaction will be made using this number of blocks (or
              less if near the end of count). Default is 128.

       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 (or block devices when "blk_sgio=1" is given).  Default is
              10 byte SCSI command blocks (unless calculations indicate that a
              4  byte  block number may be exceeded, in which case it defaults
              to 16 byte SCSI commands).

       count=BLOCKS
              copy this number of blocks from ’if’ to  ’of’.  Default  is  the
              minimum  (of  ’if’  and  ’of’)  number of blocks that sg devices
              return from READ CAPACITY SCSI commands or  that  block  devices
              (or  their  partitions)  report. Normal files are not probed for
              their size. If ’skip’ or ’seek’  are  given  and  the  count  is
              derived  (i.e.  not  explicitly given) then the derived count is
              scaled back so that the copy will not overrun the device. If the
              file  name  is  a  block device partition and count is not given
              then the size of the partition rather than the size of the whole
              device is used. If count is not given and cannot be derived then
              an error message is issued and no copy takes place.

       dio=0 | 1
              permits direct IO to be selected on the write-side (i.e.  "of").
              Only allowed when the read-side (i.e. "if") is a sg device. When
              1 there may be a "zero copy" copy (i.e. mmap-ed transfer on  the
              read  into the user space and direct IO from there on the write,
              potentially two DMAs and no data copying from the CPU).  Default
              is 0

       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
              (the  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 which is the default. A file
              name of "-"  is  taken  to  be  stdin.  Starts  reading  at  the
              beginning of FILE unless "skip" is given.

       obs=BYTES
              if given must be the same as bs

       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
              performed.  If  FILE  is .  (period) then it is treated the same
              way as /dev/null (this is a shorthand notation)

       seek=BLOCKS
              start writing BLOCKS bs-sized  blocks  from  the  start  of  the
              output file.  Default is block 0 (i.e. start of file).

       skip=BLOCKS
              start  reading  BLOCKS  bs-sized  blocks from the start of input
              file.  Default is block 0 (i.e. start of file).

       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,
              outputting  the  results  (to  stderr)  at  completion.  When  0
              (default) doesn’t perform timing

       verbose=<n>
              as  <n>  increases  so  does  the amount of debug output sent to
              stderr.  Default value is zero which yields the  minimum  amount
              of debug output.  A value of 1 reports extra information that is
              not repetitive. A value 2 reports cdbs and  responses  for  SCSI
              commands  that  are  not  repetitive  (i.e.  other that READ and
              WRITE). Error processing is not considered repetitive. Values of
              3  and 4 yield output for all SCSI commands (and Unix read() and
              write() calls) so there can be a lot of output.

       --version
              outputs version number information and exits

       A raw device must be bound to a block device  prior  to  using  sgm_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" before use.

       Raw  device partition information can often be found with fdisk(8) [the
       "-ul" argument is useful in this respect].

       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 . This pattern continues  for  "G",  "T"  and
       "P".  The latter two suffixes can only be used for count, skip and seek
       values). 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.

       Alternatively  numerical values can be given in hexadecimal preceded by
       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).
       With memory mapped transfers a kernel buffer reserved by sg  is  memory
       mapped  (see the mmap(2) system call) into the user space. When this is
       done the second (redundant) copy from kernel buffers to user  space  is
       not needed. Hence the transfer is faster and requires less "grunt" from
       the CPU.

       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

       See the examples given in the man page for sg_dd(8).

NOTE

       For sg devices this utility issues READ and WRITE (SBC)  SCSI  commands
       which  are  appropriate for disks and reading from CD/DVD drives. Those
       commands are not formatted correctly for tape devices so sgm_dd  should
       not be used on tape devices.

SIGNALS

       The  signal  handling  has  been  borrowed from dd: SIGINT, SIGQUIT and
       SIGPIPE 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 at interlog dot com>.

COPYRIGHT

       Copyright © 2000-2005 Douglas Gilbert
       This  software  is  distributed  under  the  GPL version 2. There is NO
       warranty; not even for MERCHANTABILITY  or  FITNESS  FOR  A  PARTICULAR
       PURPOSE.

SEE ALSO

       The  simplest variant of this utility is called sg_dd.  A POSIX threads
       version of this utility called sgp_dd is in the sg3_utils package.  The
       lmbench package contains lmdd which is also interesting.  raw(8), dd(1)