Provided by: ddpt_0.92-1_amd64 bug


       ddpt  - copies data between files and storage devices. Support for devices that understand
       the SCSI command set.


       ddpt [bpt=BPT[,OBPC]] [bs=BS]  [cdbsz=6|10|12|16]  [coe=0|1]  [coe_limit=CL]  [conv=CONVS]
       [count=COUNT]   [ibs=IBS]   if=IFILE   [iflag=FLAGS]   [obs=OBS]  [of=OFILE]  [of2=OFILE2]
       [oflag=FLAGS] [retries=RETR] [seek=SEEK] [skip=SKIP] [status=STAT] [verbose=VERB] [--help]
       [--verbose] [--version] [--wscan]

       For comparison here is the synopsis for GNU's dd command:

       dd   [bs=BS]  [cbs=CBS]  [conv=CONVS]  [count=COUNT]  [ibs=IBS]  [if=IFILE]  [iflag=FLAGS]
       [obs=OBS]  [of=OFILE]  [oflag=FLAGS]  [seek=SEEK]   [skip=SKIP]   [status=STAT]   [--help]


       Copy data between files or read data from a file. Specialized for "files" that are storage
       devices, especially those that can use the SCSI command sets (e.g.  SATA  and  SAS  disks,
       plus  DVD drives). Can issue SCSI commands in pass-through ("pt") mode. Similar syntax and
       semantics to the Unix dd(1) command.

       For comparison, the SYNOPSIS section above  shows  both  the  ddpt  command  line  options
       followed  by  GNU's  dd(1) command line options. Broadly speaking ddpt can be considered a
       super-set of dd. See the section on DD DIFFERENCES  for  significant  differences  between
       ddpt and dd.

       ddpt does a segmented copy, first reading in BPT*IBS bytes from IFILE (or less if near the
       end of the copy) into a copy buffer. In the absence of the various options and  conditions
       that  bypass  the  write operation, the copy buffer is then written out to OFILE. The copy
       process continues working its way along IFILE and OFILE until either COUNT  is  exhausted,
       an  end  of  file  is  detected,  or  an  error occurs. If IBS and OBS are different, ddpt
       restricts the value of OBS such that the copy buffer is an integral number  output  blocks
       (i.e.  (((IBS*BPT)  % OBS) == 0) ). In the following descriptions, "segment" refers to all
       or part of a copy buffer.

       The term "pt device" is used for  a  pass-through  device  to  which  SCSI  commands  like
       READ(10)  and WRITE(10) may be sent. A pt device may only be able to process SCSI commands
       in which case the "pt" flag is assumed. The ability to recognize such a pt only device may
       vary  depending  on the operating system (e.g. in Linux '/dev/sg2' is recognized). However
       if a device can process either normal  UNIX  read()/write()  calls  or  pass-through  SCSI
       commands  then  the  default  is  to  use  UNIX  read()/write() calls. That default can be
       overridden by using the "pt"  flag  (e.g.  "if=/dev/sdc  iflag=pt").  When  pt  access  is
       specified  any  partition  information is ignored.  So "if=/dev/sdc2 iflag=pt skip=3" will
       start at logical block address 3 of '/dev/sdc'. As a protection measure  in  version  0.92
       ddpt will only accept that if the force flag is given in addition to pt.


              where  BPT  is Blocks Per Transfer. The copy is made up of multiple transfers, each
              first reading BPT input blocks (i.e. BPT*IBS bytes) from IFILE into the copy buffer
              and  then  from  that  copy buffer writing BPT*IBS/OBS output blocks to OFILE. This
              continues until the copy is finished, with  the  last  transfer  being  potentially
              shorter.  The default BPT value varies depending on IBS. When IBS < 8, BPT is 8192;
              when IBS < 64, BPT is 1024; when IBS < 1024, BPT is 128; when IBS <  8192,  BPT  is
              16;  when IBS < 32768, BPT is 4; else BPT defaults to 1. If BPT is given as 0 it is
              treated as the default value.  For "bs=512", BPT defaults to 128 so that 64 KiB (or
              less) is read from IFILE into the copy buffer.
              The  optional  OBPC  (Output  Blocks  Per  Check)  argument  controls  controls the
              granularity  of  sparse  writes,  write  sparing  and  trim  checks.   The  default
              granularity  is  the  size  of  the  copy  buffer (i.e. BPT*IBS bytes). That can be
              reduced by specifying OBPC. The finest granularity is when OBPC is 1 which  implies
              the  unit  of  each  check  is OBS bytes. When OBPC is 0, or not given, the default
              granularity is used. Large OBPC values are rounded down so that OBPC*OBS  does  not
              exceed the size of the copy buffer.

       bs=BS  where  BS is the IFILE and OFILE block size in bytes.  Conflicts with either "ibs="
              or "obs=" options. The value of BS is placed in IBS and OBS.  If IFILE or OFILE  is
              a  "pt"  device  then  BS  must be the logical block size of the device. See the DD
              DIFFERENCES section below. Default is 512 which to date has been correct  for  hard
              disks.   Other  logical  block sizes are 2048 bytes for DVDs and 4096 bytes for the
              coming generation of hard disks.

       cdbsz=6 | 10 | 12 | 16
              size of SCSI READ and/or WRITE commands issued on pt devices.  Default is  10  byte
              SCSI command blocks (unless calculations indicate that a 4 byte block number may be
              exceeded or BPT is greater than 16 bits (65535), in which case it  defaults  to  16
              byte SCSI commands).

       coe=0 | 1
              set  to  1  for continue on error. Applies to errors on input and output pt devices
              plus input from block devices or regular files. Errors on  other  files  will  stop
              ddpt.  Default  is  0  which implies stop on any error. See the 'coe' flag for more

              where CL is the maximum number of consecutive  bad  blocks  stepped  over  (due  to
              "coe=1") on reads before the copy terminates. The default is 0 which is interpreted
              as no limit. This option is meant to stop the copy soon after unrecorded  media  is
              detected while still offering "continue on error" capability.

              see the CONVERSIONS section below.

              copy  COUNT input blocks from IFILE to OFILE. If this option is not given (or COUNT
              is '-1') then the COUNT may be deduced from either IFILE or OFILE.  See  the  COUNT
              section below.

              where  IBS is the IFILE block size in bytes. The default value is BS or its default
              (512). Conflicts the "bs=" option (e.g. giving both "bs=512 ibs=512" is  considered
              a syntax error).

              read  from IFILE. This option must be given (i.e. it is mandatory). If IFILE is '-'
              then stdin is read. Starts reading at the beginning of IFILE unless SKIP is given.

              where FLAGS is a comma separated list of one or more flags outlined  in  the  FLAGS
              section below.  These flags are associated with IFILE and are ignored when IFILE is

              where OBS is the OFILE block size in bytes. The default value is BS or its  default
              (512).  Conflicts the "bs=" option (e.g. giving both "bs=512 obs=512" is considered
              a syntax error).  If OBS is given  then  it  has  the  following  restriction:  the
              integer  expression  (((IBS  * BPT) % OBS) == 0) must be true.  Stated another way:
              the copy buffer size must be an integral multiple of OBS. If  of2=OFILE2  is  given
              then OBS is its block size as well.

              write  to  OFILE.  The  default value is /dev/null . If OFILE is '-' then writes to
              stdout. If OFILE is /dev/null then no actual writes are performed. If OFILE is  '.'
              (period)  then it is treated the same way as /dev/null . If OFILE exists then it is
              _not_ truncated unless "oflag=trunc" is given. See section on DD DIFFERENCES.

              write output to OFILE2. The default action is not to do this additional write (i.e.
              when  this  option  is not given). OFILE2 is assumed to be a regular file or a fifo
              (i.e. a named pipe). OFILE2 is opened for writing and is created if  necessary.  If
              OFILE2 is a fifo (named pipe) then some other command should be consuming that data
              (e.g. 'md5sum OFILE2'), otherwise this utility will  block.  The  write  to  OFILE2
              occurs  before  the  write  to  OFILE and prior to sparse writing and write sparing
              logic. So everything read is written to OFILE2.

              where FLAGS is a comma separated list of one or more flags outlined  in  the  FLAGS
              section.  These  flags  are  associated  with  OFILE  and are ignored when OFILE is
              /dev/null, '.' (period), or stdout.

              sometimes retries at the host are useful, for example when  there  is  a  transport
              error.  When  RETR  is  greater than zero then SCSI READs and WRITEs are retried on
              error, RETR times. Default value is zero.  Only applies to errors on pt devices.

              start writing SEEK blocks (each of OBS bytes) from the start of OFILE.  Default  is
              block  0  (i.e.  start  of file). The SEEK value may exceed the number of OBS-sized
              blocks in OFILE.

              start reading SKIP blocks (each of IBS bytes) from the start of IFILE.  Default  is
              block  0  (i.e.  start  of  file). The SKIP value must be less than or equal to the
              number of IBS-sized blocks in IFILE.

              the STAT value of 'noxfer' suppresses the throughput speed and the copy time output
              at the end of the copy. The "status=noxfer" option was recently introduced to GNU's
              dd command. The default action of ddpt is to show the throughput (in megabytes  per
              second)  and the time taken to do the copy after the "records in" and "records out"
              lines at the end of the copy.  As a convenience the value 'null'  is  accepted  for
              STAT and does nothing.

              as VERB 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, plus Unix read() and write() calls, so there can be a lot of output.
              If VERB is "-1" then output otherwise sent to stderr is redirected to /dev/null .

       -h, --help
              outputs usage message and exits.

       -v, --verbose
              equivalent  of  verbose=1.  If  --verbose  appears twice then that is equivalent to
              verbose=2. Also -vv is equivalent to verbose=2.

       -V, --version
              outputs version number information and exits.

       -w, --wscan
              this option is available in Windows only. It lists storage  device  names  and  the
              corresponding  volumes,  if  any.  When  used  twice  it adds the "bus type" of the
              closest transport (e.g. a SATA disk in a USB connected enclosure has bus type Usb).
              When  used  three  times  a SCSI adapter scan is added. When used four times only a
              SCSI adapter scan is shown.  See EXAMPLES section below and the README.win32 file.


       When the count=COUNT option is not given (or COUNT is '-1') then an  attempt  is  made  to
       deduce COUNT as follows.

       When both or either IFILE and OFILE are block devices, then the minimum size, expressed in
       units of input blocks, is used. When both or  either  IFILE  and  OFILE  are  pass-through
       devices, then the minimum size, expressed in units of input blocks, is used.

       If  a  regular  file  is  used as input, its size, expressed in units of input blocks (and
       rounded up if necessary) is used. Note that the rounding  up  of  the  deduced  COUNT  may
       result  in  a  partial  read  of the last input block and a corresponding partial write to
       OFILE if it is a regular file.

       The size of pt devices is deduced from the SCSI READ CAPACITY command.  Block device sizes
       (or their partition sizes) are obtained from the operating system, if available.

       If  skip=SKIP  or skip=SEEK are given and the COUNT is deduced (i.e. not explicitly given)
       then that size is scaled back so that the copy will not overrun the file or device.

       If COUNT is not given and IFILE is a fifo (and stdin is treated as a fifo) then  IFILE  is
       read  until  an  EOF  is  detected.   If  COUNT  is not given and IFILE is a /dev/zero (or
       equivalent) then zeros are read until an error occurs (e.g. file system full).

       If COUNT is not given and cannot be deduced then an error message is issued  and  no  copy
       takes place.


       One  or  more  conversions  can be given to the "conv=" option. If more than one is given,
       they should be comma separated. ddpt does not perform the traditional dd conversions (e.g.
       ASCII  to  EBCDIC).  Recently  added  conversions  overlap somewhat with the flags so some
       conversions are now supported by ddpt.

              equivalent to "oflag=fdatasync". Flushes data associated with the OFILE to  storage
              at the end of the copy. This conversion is for compatibility with GNU's dd.

       fsync  equivalent  to  "oflag=fsync". Flushes data and meta-data associated with the OFILE
              to storage at the end of the copy. This conversion is for compatibility with  GNU's

              this  conversion is very close to "iflag=coe" and is treated as such. See the "coe"
              flag. Note that an error on OFILE will stop the copy.

       null   has no affect, just a placeholder.

       resume See "resume" in the FLAGS sections for more information.

              See "sparing" in the FLAGS sections for more information.

       sparse FreeBSD supports "conv=sparse" so the  same  syntax  is  supported  in  ddpt.   See
              "sparse" in the FLAGS sections for more information.

       sync   is  ignored  by  ddpt.  With dd it means supply zero fill (rather than skip) and is
              typically used like this "conv=noerror,sync" to  have  the  same  functionality  as
              ddpt's "iflag=coe".

       trunc  if OFILE is a regular file then truncate it prior to starting the copy. See "trunc"
              in the FLAGS section.


       A list of flags and their meanings follow. The  flag  name  is  followed  by  one  or  two
       indications  in  square  brackets.  The  first indication is either "[i]", "[o]" or "[io]"
       indicating this flag is active for the IFILE, OFILE or both the IFILE and the  OFILE.  The
       second indication contains some combination of "reg", "blk" or "pt" indicating whether the
       flag applies to a regular file, a block device  (accessed  via  Unix  read()  and  write()
       commands) or a pass-through device respectively.

       append [o] [reg]
              causes  the  O_APPEND flag to be added to the open of OFILE. For regular files this
              will lead to data appended to the end of any existing data. Conflicts the seek=SEEK
              option.  The  default action of this utility is to overwrite any existing data from
              the beginning of OFILE or, if SEEK is given, starting  at  block  SEEK.  Note  that
              attempting  to  'append'  to a device file (e.g. a disk) will usually be ignored or
              may cause an error to be reported.

       coe [io] [pt], [i] [reg,blk]
              continue on error.  'iflag=coe  oflag=coe'  and  'coe=1'  are  equivalent.   Errors
              occurring on output regular or block files will stop ddpt.  Error messages are sent
              to stderr. This flag is  similar  to  'conv=noerror,sync'  in  the  dd(1)  utility.
              Unrecovered errors are counted and output in the summary at the end of the copy.

              This  paragraph is about coe on pt devices. A medium, hardware or blank check error
              while reading will re-read blocks prior to the bad block, then try to  recover  the
              bad  block,  supplying zeros if that fails, and finally reread the blocks after the
              bad block. A medium, hardware or blank check  error  while  writing  is  noted  and
              ignored.   SCSI  disks may automatically try and remap faulty sectors (see the AWRE
              and ARRE in the read write error recovery mode page (the sdparm utility can  access
              these  attributes)).  If  bad LBAs are reported by the pass-through then the LBA of
              the lowest and highest bad block is also output.

              This paragraph is about coe on input regular files and block devices.  When  a  EIO
              or EREMOTEIO error is detected on a normal segment read then the segment is re-read
              one block (i.e. IBS bytes) at a time. Any block that  yields  a  EIO  or  EREMOTEIO
              error  is  replaced  by zeros. Any other error, a short read or an end of file will
              terminate the copy, usually after the data that has been read  is  written  to  the
              output file.

       direct [io] [reg,blk]
              causes  the  O_DIRECT flag to be added to the open of IFILE and/or OFILE. This flag
              requires some memory alignment on IO. Hence user memory buffers are aligned to  the
              page   size.   May   have   no   effect  on  pt  devices.  This  flag  will  bypass
              caching/buffering normally done by block layer. Beware of data coherency issues  if
              the  same  locations  have been recently accessed via the block layer in its normal
              mode (i.e.  non-direct). See open(2) man page.

       dpo [io] [pt]
              set the DPO bit (disable page out) in SCSI READ and WRITE commands.  Not  supported
              for  6  byte  cdb variants of READ and WRITE. Indicates that data is unlikely to be
              required to stay in device (e.g. disk) cache.  May speed media copy and/or cause  a
              media copy to have less impact on other device users.

       errblk [i] [pt] [experimental]
              attempts to create or append to a file called "errblk.txt" in the current directory
              the logical block addresses of blocks that cannot be  read.  The  first  (appended)
              line  is  "#  start <timestamp>". That is followed by the LBAs in hex (and prefixed
              with "0x") of any block that cannot be read, one LBA per line. If  the  sense  data
              does not correctly identify the LBA of the first error in the range it was asked to
              read then a LBA range is output in the form of the lowest and the  highest  LBA  in
              the  range  separated  by  a  "-".  At  the  end  of  the  copy a line with "# stop
              <timestamp>" is appended to "errblk.txt". Typically used with "coe".

       excl [io] [reg,blk]
              causes the O_EXCL flag to be added to the open of IFILE and/or OFILE.  See  open(2)
              man page.

       fdatasync [o] [reg,blk]
              Flushes data associated with the OFILE to storage at the end of the copy.

       flock [io] [reg,blk,pt]
              after  opening  the associated file (i.e. IFILE and/or OFILE) an attempt is made to
              get an advisory exclusive lock with the flock() system call.  The  flock  arguments
              are "FLOCK_EX | FLOCK_NB" which will cause the lock to be taken if available else a
              "temporarily unavailable" error is generated. An exit status of 90 is  produced  in
              the latter case and no copy is done. See flock(2) man page.

       force [io] [pt]
              override  difference  between given block size and the block size found by the SCSI
              READ CAPACITY command. Use the given block size. Without this flag the  copy  would
              not  be  performed. pt access to what appears to be a block partition is aborted in
              version 0.92; that can be overridden by the force flag.  For  related  reasons  the
              'norcap' flag requires this flag when applied to a block device accessed via pt.

       fsync [o] [reg,blk]
              Flushes  data  and  metadata  (describing  the  file)  associated with the OFILE to
              storage at the end of the copy.

       fua [io] [pt]
              causes the FUA (force unit access)  bit  to  be  set  in  SCSI  READ  and/or  WRITE
              commands.  The  6  byte variants of the SCSI READ and WRITE commands do not support
              the FUA bit.

       fua_nv [io] [pt]
              causes the FUA_NV (force unit access non-volatile cache) bit to be set in SCSI READ
              and/or  WRITE  commands.  This  only  has  an  effect  with pt devices.  The 6 byte
              variants of the SCSI READ and WRITE commands do not support the FUA_NV bit.

       nocache [io] [reg,blk]
              use posix_fadvise() to advise corresponding file there is no need to fill the  file
              buffer with recently read or written blocks. If used with "iflag=" it will increase
              the read ahead on IFILE.

       norcap [io] [pt]
              do not perform SCSI READ CAPACITY command on the corresponding pt device.  If  used
              on block device accessed via pt then 'force' flag is also required. This is to warn
              about using pt access on what may be a block device partition.

       nowrite [o] [reg,blk,pt]
              bypass writes to OFILE. The "records out" count is not incremented.  OFILE is still
              opened  but  "oflag=trunc"  if given is ignored. Also the ftruncate call associated
              with the sparse flag is ignored (i.e.  bypassed). Commands such as  trim  and  SCSI
              SYNCHRONIZE CACHE are still sent.

       null [io]
              has no affect, just a placeholder.

       pt [io] [blk,pt]
              causes  a  device  to  be  accessed  in "pt" mode. In "pt" mode SCSI READ and WRITE
              commands are sent to access blocks rather than standard  UNIX  read()  and  write()
              commands.  The  "pt"  mode may be implicit if the device is only capable of passing
              through SCSI commands (e.g. the /dev/sg devices in Linux). This flag is needed  for
              device  nodes  that  can  be  accessed  both  via  standard UNIX read() and write()
              commands as well as SCSI commands.  Such devices default standard UNIX  read()  and
              write() commands in the absence of this flag.

       resume [o] [reg]
              when  a  copy is interrupted (e.g. with Control-C from the keyboard) then using the
              same invocation again with the addition of "oflag=resume" will attempt  to  restart
              the  copy  from  the  point  of  the  interrupt  (or just before that point). It is
              harmless to use "oflag=resume" when OFILE doesn't exist or is zero length.  If  the
              length of OFILE is greater than or equal to the length implied by a ddpt invocation
              that includes "oflag=resume" then no further data is copied.

       self [io] [pt]
              used together with trim flag to do a self trim (trim of segments  of  a  pt  device
              that  contain  all  zeros).  If  OFILE  is not given, then it is set to the same as
              IFILE. If SEEK is not given it set to the same value as SKIP (possibly adjusted  if
              IBS and OBS are different). Implicitly sets "nowrite" flag.

       sparing [o] [reg,blk,pt]
              during the copy each IBS * BPT byte segment is read from IFILE into a buffer. Then,
              instead of writing that buffer to OFILE, the corresponding  segment  is  read  from
              OFILE  into  another buffer. If the two buffers are different, the former buffer is
              written to the OFILE. If the two buffers compare equal then the write to  OFILE  is
              not  performed.  Write  sparing  is  useful when a write operation is significantly
              slower than a read. Under some conditions flash memory  devices  have  slow  writes
              plus  an  upper  limit  on  the number of times the same cell can be rewritten. The
              granularity of the comparison can be reduced  from  the  default  IBS  *  BPT  byte
              segment  with the the OBPC value given to the "bpt=" option. The finest granularity
              is when OBPC is 1 which implies OBS bytes.

       sparse [o] [reg,blk,pt]
              after each IBS * BPT byte segment is read from IFILE, it is checked to see if it is
              all  zeros.  If so, that segment is not written to OFILE. See the section on SPARSE
              WRITES below. The granularity of the  zero  comparison  can  be  reduced  from  the
              default IBS * BPT byte segment with the OBPC value given to the "bpt=" option.

       ssync [o] [pt]
              if  OFILE  is in "pt" mode then the SCSI SYNCHRONIZE CACHE command is sent to OFILE
              at the end of the copy.

       strunc [o] [reg]
              perform a sparse copy with a ftruncate system call to  extend  the  length  of  the
              OFILE if required. See the sparse flag and the section on SPARSE WRITES below.

       sync [io] [reg,blk]
              causes  the  O_SYNC flag to be added to the open of IFILE and/or OFILE. See open(2)
              man page.

       trim [io] [pt] [experimental]
              similar logic to the "sparse" option. However instead of skipping segments that are
              full  of  zeros a "trim" command is sent to OFILE. Usually set as an oflag argument
              but for self trim can be  used  as  an  iflag  argument  (e.g.  "iflag=self,trim").
              Depending  on  the usage this may require the device to support "deterministic read
              zero after trim". See the TRIM, UNMAP AND WRITE SAME section below.

       trunc [o] [reg]
              if OFILE is a regular file then it is truncated prior to starting the copy. If SEEK
              is  not given or 0 then OFILE is truncated to zero length; when SEEK is larger than
              zero the truncation  takes  place  at  file  byte  pointer  SEEK*OBS.   Ignored  if
              "oflag=append". Conflicts with "oflag=sparing".


       Bypassing writes of blocks full of zeros can save a lot of IO. However with regular files,
       bypassed writes at the end of the copy can lead to an OFILE which is shorter than it would
       have  been without sparse writes. This can lead to integrity checking programs like md5sum
       and sha1sum generating different values.

       This utility has two ways of handling this file length problem:  writing  the  last  block
       (even  if  it is full of zeros) or using the ftruncate system call. A third approach is to
       ignore the problem (i.e. leaving OFILE shorter).  The  ftruncate  approach  is  used  when
       "oflag=strunc"  while  the  last  block is written when "oflag=sparse". To ignore the file
       length issue use "oflag=sparse,sparse". Note that if OFILE's length is already correct  or
       longer than required, no action is taken.

       The  support for sparse writing of regular files may depend on the OS, the file system and
       the settings of OFILE. POSIX makes few guarantees when the ftruncate system call  is  used
       to  extend  a  file's  length,  as  may occur when "oflag=strunc". Further, primitive file
       systems like VFAT may not accept sparse writes or simulate the effect by writing blocks of
       zeros. The latter approach will defeat any sparse writing performance gain.


       This  is  a  new  storage  feature  often associated with Solid State Disks (SSDs) or disk
       arrays with "thin provisioning". In the ATA command set (ACS-2) the  relevant  command  is
       DATA  SET  MANAGEMENT  with the TRIM bit set. In the SCSI command set (SBC-3) it is either
       the UNMAP or WRITE SAME command. Note there  is  no  TRIM  command  however  the  term  is
       frequently used in the technical press.

       Trim  is  a way of telling a storage device that blocks are no longer needed.  Keeping the
       pool of unwritten blocks large is important for the write  performance  of  SSDs  and  the
       thrifty  use  of real storage in thin provisioned arrays. Currently file systems in recent
       OSes may issue trims associated with file deletes. The trim option in ddpt may  be  useful
       when  a  partition  or  a  whole  SSD is to be "deleted". Note that ddpt is bypassing file
       systems in that it only offers trim on pass-through (pt) devices.

       This utility issues SCSI commands to pt devices and for "trim"  currently  issues  a  SCSI
       WRITE  SAME(16)  command  with  the  UNMAP  bit  set. If the pt device is a SSD with a ATA
       interface then recent versions of Linux will translate the SCSI WRITE SAME to the ATA DATA
       SET MANAGEMENT command with the TRIM bit set. The maximum size of each "trim" command sent
       is the size of the copy buffer (i.e. IBS * BPT bytes). And that  maximum  can  be  reduced
       with the OBPC argument of the "bpt=" option.

       The  trim  can be used various ways. One way is a copy where the copy buffer (or some part
       of it) is checked for zeros as is done by the sparse oflag. When a zero segment is  found,
       a trim "command" is sent to the OFILE. For example:

          ddpt if=dsk.img bs=512 of=/dev/sdc oflag=pt,trim

       The  copy  buffer  is  64  KiB (since BPT and OBPC default to 128 when "bs=512") and it is
       checked for all zeros. If it is all zeros then a trim command is sent to the corresponding
       location of /dev/sdc which is accessed via the pt interface. If it is not all zeros then a
       SCSI WRITE command is sent. Another way is to trim all or part of a disk. To trim a  whole
       disk (i.e. deleting all its data):

           ddpt if=/dev/zero bs=512 of=/dev/sdc oflag=pt,trim

       A  third  way  is  to "self-trim" which is to only trim those parts of a disk that contain
       segments full of zeros:

           ddpt if=/dev/sdc skip=0x2300 bs=512 iflag=pt,self,trim count=0x1234f0

       The "self" oflag automatically sets up the output side of the copy to send  trim  commands
       (if required) back the the same device (i.e. /dev/sdc).  If this example was self-trimming
       a partition then the partition would start at LBA 0x2300 and be 0x1234f0 blocks long.

       Some random product examples: the Intel X25-M G2 SSDs have trim with recent  firmware  and
       they  do  deterministic  read zero after trim. The Seagate Pulsar SSD has an ATA interface
       which supports the deterministic reads of zero after the DATA SET MANAGEMENT command  with
       the TRIM option.


       dd  defaults  "if="  and  "of=" to stdin and stdout respectively. This follows Unix filter
       conventions. However since dd and ddpt are often used  to  read  binary  data  for  timing
       purposes,  having  to  supply  "of=/dev/null"  can be easily forgotten. Without it dd will
       potentially spew binary data on the  console.  So  ddpt  has  changed  its  defaults:  the
       "if=IFILE"  is now mandatory and to read from stdin "if=-" can be used; "of=OFILE" remains
       optional but its default changes to "/dev/null" (or "NUL" in Windows). To send  output  to
       stdout ddpt accepts "of=-".

       dd truncates OFILE unless "conv=notrunc" is given. When dd truncates, it truncates to zero
       length unless SEEK is greater than zero. ddpt does not truncate OFILE by default. If OFILE
       exists  it  will  be  overwritten.  The  overwrite  starts  at  block  zero unless SEEK or
       "oflag=append" is given. If OFILE is a regular file then "oflag=trunc"  (or  "conv=trunc")
       will truncate OFILE prior to the copy.

       Numeric  arguments to ddpt can be given in hexadecimal, either with a leading "0x" or "0X"
       or with a trailing "h". Note that dd accepts "0x123" but interprets it as "0 * 123"  (i.e.
       zero).  ddpt  will  also interpret "x" as multiplies unless the left operand is zero (e.g.
       "0x123"). So both dd and ddpt will interpret "skip=2x123" as "skip=246".

       Terabyte size disks make it impractical to copy all the data into a buffer before  writing
       it  out. Therefore both dd and ddpt read a relatively small amount of data into a copy (or
       transfer) buffer then write it out to the destination, repeating this  process  until  the
       COUNT is exhausted.

       A  major difference in ddpt is the addition of BPT to control the size of the copy buffer.
       With dd, IBS is the size of the copy buffer and the unit of SKIP and COUNT. With ddpt, IBS
       *  BPT  is  the size of the copy buffer and IBS is the unit of SKIP and COUNT. This allows
       ddpt to have its IBS set to the logical block size of IFILE without unduly restricting the
       size  of  the copy buffer. And setting IBS (and OBS for OFILE) accurately is required when
       the pass-through interface is used since with the SCSI READ and WRITE commands the logical
       block size is implicit.

       The  way  dd  handles  its copy buffer (outlined in SUSv4 description of dd) is relatively
       complex, especially when IBS and OBS are different sizes. The restriction that ddpt places
       on  IBS  and  OBS ( i.e. (((IBS*BPT) % OBS) == 0) ) means that a single copy buffer can be
       used since its size is a multiple of both IBS and OBS. Being able to precisely define  the
       copy  buffer  size in ddpt makes sparse writing, write sparing and trim operations simpler
       to define and the user to control.

       ddpt does not support dd's "cbs=" option (conversion block size). If the "cbs=" option  is
       given to ddpt then it is ignored.


       A  partial  write is a write to the OFILE of less than OBS bytes. This typically occurs at
       the end of a copy. dd can do partial writes. ddpt does partial writes to regular files and
       fifos (including stdout). However ddpt ignores partial writes when OFILE is a block device
       or a pt device. When ddpt ignores a partial write, it  sends  a  warning  to  the  console

       At the end of the copy two lines are output to the console:
          <in_full>+<in_partial> records in
          <out_full>+<out_partial> records out

       The  "records  in"  line  is the number of full input blocks (each of IBS bytes) that have
       been read plus the number of partial blocks ( usually less than IBS bytes) that have  been
       read. Following the lead of dd when 'iflag=coe' is active a block that cannot be read (and
       has zeros substituted for its output) is regarded as a partial  read.  The  "records  out"
       line  is  the number of full output blocks (each of OBS bytes) that have been written plus
       the number of partial blocks (usually less than OBS bytes) that have been written.

       Block  devices  (e.g.  /dev/sda  and  /dev/hda)  can  be  given  for  IFILE.   If  neither
       'iflag=direct'  nor  'iflag=pt'  is  given  then  normal  block IO involving buffering and
       caching is performed. If 'iflag=direct'  is  given  then  the  buffering  and  caching  is
       bypassed (this is applicable to both SCSI devices and ATA disks). When 'iflag=pt' is given
       SCSI commands are sent to the device which bypasses most of the actions performed  by  the
       block layer.  The same applies for block devices given for OFILE.

       BPT,  BS,  COUNT,  IBS,  OBPC,  OBS, SKIP and SEEK may include 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.  Also a suffix of the form "x<n>" multiplies the leading
       number  by  <n>;  however  the combinations "0x" and "0X" are treated differently, see the
       next paragraph. These multiplicative suffixes are compatible with GNU's dd command  (since
       2002) which claims compliance with the SI and with IEC 60027-2 standards.

       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.

       The COUNT, SKIP and SEEK arguments can take 64 bit values (i.e. very big  numbers).  Other
       numerical values are limited to what can fit in a signed 32 bit number.

       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.

       Disk  partition information can often be found with fdisk(8) [the "-ul" argument is useful
       in this respect]. Also parted(8) can be used like this: 'parted /dev/sda unit s print' .

       For pt devices  this  utility  issues  SCSI  READ  and  WRITE  (SBC)  commands  which  are
       appropriate  for disks and reading from CD/DVD/BD drives. Those commands are not formatted
       correctly for tape devices so ddpt should not be used on  tape  devices.  If  the  largest
       block  address  of  the  requested transfer exceeds a 32 bit block number (i.e 0xffffffff)
       then a warning is issued and the sg device is accessed via  SCSI  READ(16)  and  WRITE(16)

       The  attributes  of a block device (e.g. partitions) are ignored when the pt flag is used.
       Hence the whole device is read (rather than just the second partition) by this invocation:

          ddpt if=/dev/sdb2 iflag=pt of=t bs=512

       Assuming /dev/sdb and /dev/sg2 refer to the same device,  then  after  the  following  two
       invocations, the contents of the files "t", "tt" and "ttt" should be same:

          ddpt if=/dev/sdb of=tt bs=512

          ddpt if=/dev/sg2 of=ttt bs=512


       The  examples  in  this  page  use  Linux device names. For suitable device names in other
       supported Operating Systems see this web  page:  .
       The sg3_utils(8) man page in the sg3_utils package also covers device naming.

       ddpt usage looks quite similar to dd:

          ddpt if=/dev/sg0 of=t bs=512 count=1MB

       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 iflag=direct of=t bs=512 count=1000000

       although  dd's  speed may improve if bs was larger and count was suitably reduced. The use
       of the 'iflag=direct' option bypasses the buffering and caching that is usually done on  a
       block device.

       The dd command's bs argument can be thought of as roughly equivalent to ddpt's bs*bpt . dd
       almost assumes buffering on a block device and will work as long as bs is  a  multiple  of
       the  actual logical block size.  Since ddpt can work at a lower level in some cases the bs
       argument must be a disk's actual logical block size. Thus the bpt argument was  introduced
       to make the copy more efficient. So these two invocations are roughly equivalent:

          dd if=/dev/sda of=t bs=8k count=64
          ddpt if=/dev/sda of=t bs=512 bpt=16 count=1k

       In  both  cases  the  total  number  of bytes moved is bs*count . And that will be done by
       reading 8k (8192 bytes) into a buffer then writing out that buffer to the file t. The read
       write sequence continues until the count is complete or an error occurs.

       The  'of2=' option can save time when the input would otherwise need to be read twice. For
       example, to copy data and take a md5sum of it without needing to re-read the data:

         mkfifo fif
         md5sum fif &
         ddpt if=/dev/sg3 iflag=coe of=sg3.img oflag=sparse of2=fif bs=512

       This will image /dev/sg3 (e.g. an unmounted disk) and place the contents in  the  (sparse)
       file  sg3.img  .  Without re-reading the data it will also perform a md5sum calculation on
       the image.

       Now we use sparse writing logic to get some idea of how many blocks on a disk are full  of
       zeros. After a SCSI FORMAT or an ATA SECURITY ERASE command a disk may be all zeros.

          ddpt if=/dev/sdc bs=512 oflag=sparse

       Since no "of=" option is given, output goes to /dev/null so nothing is actually written so
       the "records out" will be zero. However  there  will  be  a  count  of  "records  in"  and
       "bypassed  records  out".  If  /dev/sdc  is  full of zeros then "records in" and "bypassed
       records out" will be the same. Since the  "bpt="  option  is  not  given  it  defaults  to
       "bpt=128,128"  so  the  copy  buffer will be 64 KiB and the sparse check for zeros will be
       done with 64 KiB (128 block) granularity.

       For examples of the trim and self,trim options see the section above on  TRIM,  UNMAP  AND
       WRITE SAME.

       Following  is  an  example  run on a Windows OS using the '--wscan' option which shows the
       available device names (e.g. PD1) and the associated volume name(s):

          ddpt -w
       PD0     [C]     FUJITSU   MHY2160BH         0000
       PD1     [DF]    WD        2500BEV External  1.05  WD-WXE90
       CDROM0  [E]     MATSHITA DVD/CDRW UJDA775  CB03

       So, for example, volumes D: and F: reside on PhysicalDisk1 (abbreviated to "PD1") which is
       manufactured by WD (Western Digital).

       Further  examples  can be found on this web page: .  There
       is a text  file  called  ddpt_examples.txt  in  the  "doc"  directory  of  this  package's
       distribution tarball.


       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 and the copy
       continues.  All output caused by signals is sent to stderr.


       To aid scripts that call ddpt, the exit status is set to indicate success (0)  or  failure
       (1  or  more). Note that some of the lower values correspond to the SCSI sense key values.
       The exit status values are:

       0      success

       1      syntax error. Either illegal command line options, options with bad arguments or  a
              combination of options that is not permitted.

       2      the  device  reports  that it is not ready for the operation requested.  The device
              may be in the process of becoming ready (e.g.  spinning up but not at speed) so the
              utility may work after a wait.

       3      the  device  reports  a medium or hardware error (or a blank check). For example an
              attempt to read a corrupted block on a disk will yield this value.

       5      the device reports an "illegal request" with an additional sense  code  other  than
              "invalid  operation  code".  This  is  often  a  supported command with a field set
              requesting an unsupported capability.

       6      the device reports a  "unit  attention"  condition.  This  usually  indicates  that
              something  unrelated  to  the  requested command has occurred (e.g. a device reset)
              potentially before the current SCSI command was sent. The requested command has not
              been  executed  by the device. Note that unit attention conditions are usually only
              reported once by a device.

       9      the device reports an illegal request with an additional  sense  code  of  "invalid
              operation code" which means that it doesn't support the requested command.

       11     the  device  reports  an  aborted  command.  In  some cases aborted commands can be
              retried immediately (e.g. if the transport aborted the command due to congestion).

       15     the utility is unable to open, close or use the given IFILE  or  OFILE.  The  given
              file  name  could  be  incorrect or there may be permission problems. Adding the -v
              option may give more information.

       20     the device reports it has a check condition but "no sense".  It  is  unlikely  that
              this value will occur as an exit status.

       21     the device reports a "recovered error". The requested command was successful.  Most
              likely a utility will report a recovered error to  stderr  and  continue,  probably
              leaving the utility with an exit status of 0 .

       33     the command sent to device has timed out. This occurs in Linux only; in other ports
              a command timeout will appear as a transport (or OS) error.

       90     the flock flag has been given on a device and some other process holds the advisory
              exclusive lock.

       97     the response to a SCSI command failed sanity checks.

       98     the  device  reports it has a check condition but the error doesn't fit into any of
              the above categories.

       99     any errors that can't be categorized into values 1 to 98 may yield this value. This
              includes  transport  and operating system errors after the command has been sent to
              the device.


       Written by Doug Gilbert


       Report bugs to <dgilbert at interlog dot com>.


       Copyright © 2008-2011 Douglas Gilbert
       This software is distributed under the GPL version 2. There is NO warranty; not  even  for


       There is a web page discussing ddpt at

       The  lmbench  package contains lmdd which is also interesting. For moving data to and from
       tapes see dt which is found at

       To change mode parameters that effect a SCSI  device's  caching  and  error  recovery  see

       To scan and repair disk partitions see TestDisk (testdisk).

       Additional references: dd(1), ddrescue(GNU), open(2), flock(2), sg_dd,sg3_utils(sg3_utils)