Provided by: ddpt_0.94-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|32}]   [coe={0|1}]   [coe_limit=CL]
       [conv=CONVS]    [count=COUNT]    [delay=MS[,W_MS]]   [ibs=IBS]   [id_usage=LIU]   if=IFILE
       [iflag=FLAGS] [intio={0|1}]  [iseek=SKIP]  [ito=ITO]  [list_id=LID]  [obs=OBS]  [of=OFILE]
       [of2=OFILE2]  [oflag=FLAGS]  [oseek=SEEK]  [prio=PRIO]  [protect=RDP[,WRP]] [retries=RETR]
       [rtf=RTF]  [rtype=RTYPE]  [seek=SEEK]  [skip=SKIP]  [status=STAT]  [to=TO]  [verbose=VERB]
       [--help] [--odx] [--verbose] [--version] [--wscan] [--xcopy]

       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]


       Copies  data  between  files or simply reads data from a file. This utility is specialized
       for "files" that are storage devices, especially those that can use the SCSI command  sets
       (e.g. SATA and SAS disks). It 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.

       This  utility  either  does  direct  copies,  based  on read-write sequences, or offloaded
       copies. In an offloaded copy the data being copied does not necessarily pass  through  the
       memory  of  the  the  machine  originating the copy operation; this can save a significant
       amount of time and lessen CPU usage.

       When doing a direct copy, this utility breaks the copy into segments since computer RAM is
       typically  a  scarce resource. First it reads 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 of  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), WRITE(10) or POPULATE TOKEN 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 and
       /dev/bsg/3:0:1:0 are 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  ddpt  will  only accept that if the force flag is also given (i.e.

       This utility supports two types of offloaded copies. Both are based on the  EXTENDED  COPY
       (XCOPY  or  xcopy) family of SCSI commands. The first uses the XCOPY(LID1) command to do a
       disk to disk copy. LID1 stands for List IDentifier length of 1 byte  and  the  command  is
       described  in  the  SPC-4  drafts  and the earlier SPC-3 and SPC-2 standards. Recent SPC-4
       drafts have added the XCOPY(LID4) sub-family of copy offloaded commands. There is a subset
       of XCOPY(LID4), specialized for offloaded disk to disk copies, that is known by the market
       name: ODX. In the descriptions below "xcopy" refers to copies based on  XCOPY(LID1)  while
       "odx"  refers  to either full or partial ODX copies.  See the XCOPY and ODX sections below
       for more information.


       The dd-like options with the name=value syntax are listed first, sorted by name. Following
       that, options starting with "-" are listed.

              where  BPT  is Blocks Per Transfer. A direct 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. This option is
              treated differently in ODX and is  typically  only  needed  for  testing;  see  ODX
              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.
              odx: may be used to limit the data represented by each ROD. Mainly for testing.

       bs=BS  where  BS  is  the  IFILE and OFILE block size in bytes.  Conflicts with either the
              "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. The default is 512 bytes; note that  newer  disks
              use  4096  byte  blocks  with  perhaps  larger  block  sizes  coming in the future.
              CD/DVD/BD media use a logical block size of 2048 bytes.

              size of SCSI READ and/or WRITE commands issued to pt devices.  The  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 (i.e. more than  65535  blocks),  in
              which case it defaults to 16 byte SCSI commands.

              set  to  1  for  continue  on  error.  Applies to errors on input and output for pt
              devices but only on 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 information.

              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 implies no
              limit. This option is meant to  stop  the  copy  soon  after  unrecorded  media  is
              detected  while  still  offering  "continue  on  error"  capability for infrequent,
              randomly distributed errors.

              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.
              odx: if a gather list is given to skip=SKIP or a scatter list is given to seek=SEEK
              then typically count=COUNT should not be supplied. This is because a scatter gather
              list implies a transfer count.  If both are given then ddpt will exit if  they  are
              unequal, the force option can be used to override this action.

              after each segment is copied (typically every (IBS * BPT) bytes) a delay (sleep) of
              MS milliseconds is performed. The default value for MS is 0 which implies no delay.
              If W_MS is given and greater than 0 (its default value) then there is an additional
              delay of W_MS milliseconds associated with each  actual  write  operation  that  is
              performed.  If MS is greater than 0 then there is not a delay before the first copy
              segment (or after the last); if W_MS is greater than 0 then there is  not  a  delay
              before the first write segment. These delays can be used for a bandwidth limiting.
              odx:  the  MS  delay  is  implemented in the same fashion after each ROD is copied,
              apart from the last. If W_MS is greater than 0 then that delay occurs  before  each
              WUT command, apart from the first.

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

              xcopy:  SCSI  EXTENDED  COPY  parameter list LIST ID USAGE field is set to LIU. The
              default value is 0 or 2 . LIU can be a number  between  0  and  3  inclusive  or  a
              string.  The  strings can be either: 'hold' for 0, 'discard' for 2 or 'disable' for

              read from IFILE. This option must be given (apart from one odx case).  If IFILE  is
              '-'  then  stdin  is  read. Starts reading at the beginning of IFILE unless SKIP is
              odx: the rtf=RTF option may replace the if=IFILE  option  as  input.  See  the  ODX

              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 mostly  ignored  when
              IFILE is stdin.

              set  to  1  for  allow  signals  (SIGINT,  SIGPIPE  and SIGUSR1 (or SIGINFO)) to be
              received during IO from IFILE or IO to OFILE or OFILE2.  Default is 0 which  causes
              these signals to be masked during IO operations with a check for signals prior each
              IO. As long as IO operations don't lock up (e.g. SCSI READ and WRITE commands)  the
              default is the safer option. Even if IO operations do lock up it is best to let the
              kernel take care of that.

              start reading SKIP blocks (each of IBS bytes) from the start of IFILE.  Default  is
              block  0  (i.e.  start  of  file).  This option is a synonym for skip=SKIP, see its

              odx: ITO is the inactivity timeout whose units are seconds. The default value is  0
              which  means  the  copy manager will take the default inactivity timeout value from
              the Block Device ROD Token Limits descriptor in the Third Party Copy VPD page.  ITO
              is  ignored  if  it  it  exceeds  the  maximum inactivity timeout value in the same
              descriptor (unless the force flag is given).

              LID is the xcopy LIST IDENTIFIER field. It is  used  to  associate  an  originating
              xcopy  command  with  follow-up  commands such as RECEIVE ROD TOKEN INFORMATION. If
              given, the LID should not clash with any other xcopy LID currently in use  on  this
              I_T nexus.
              xcopy:  LID  is  a  1  byte  (8  bit)  value  whose  default  value  is  1  or,  if
              id_usage=disable, 0 . LID must not exceed 255.
              odx: LID is a 4 byte (32 bit) value whose default value is 257 (i.e.   0x101)  and,
              if  a  second default is needed, 258 (0x102) is used. If a clash is detected on the
              default list identifier value then the next higher value is tried  (stopping  after
              10 attempts).

              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.
              odx:  if  this  option (of=OFILE) is not given and the rtf=RTF option is given then
              the RTF file may be thought of as receiving the output in the form of one  or  more
              ROD Tokens. See the ODX section.

              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.

              start  writing  SEEK blocks (each of OBS bytes) from the start of OFILE. Default is
              block 0 (i.e. start of file). This option is  a  synonym  for  seek=SEEK,  see  its

              xcopy:  SCSI  EXTENDED  COPY  parameter  list  PRIORITY  field is set to PRIO.  The
              default value is 1 .

              where RDP is the RDPROTECT field in SCSI READ commands and  WRP  is  the  WRPROTECT
              field  in  SCSI  WRITE  commands.  The default value for both is 0 which implies no
              additional protection information will be transferred.  Both RDP  and  WRP  can  be
              from  0  to  7.  If RDP is greater than 0 then IFILE must be a pt device. If WRP is
              greater than 0 then OFILE must be a  pt  device.  See  the  PROTECTION  INFORMATION
              section below.

              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.

              odx:  where  RTF  is a filename. One or more ROD tokens are written to RTF during a
              read to tokens variant or a full copy variant. One or more ROD tokens are read from
              RTF  during a write from token variant.  This option is not required on a full copy
              variant. ROD Tokens are 512 bytes long and an extra  8  byte  (big-endian)  integer
              containing  the  'number  of  bytes  represented' is placed after each ROD Token if
              rtf_len is given.

              odx: where RTYPE is the ROD Type. The default value (0)  indicates  that  the  copy
              manager  (in  the  source)  decides.  RTYPE  can  be a decimal number, a hex number
              (prefixed by  0x  or  with  a  "h"  appended)  or  one  of  "pit-def",  "pit-vuln",
              "pit-pers",  "pit-any"  or  "zero". The final truncated word can be spelt out (e.g.
              "pit-vulnerable"). The "pit-" prefix is a shortening of "point in time"  copy.  The
              "zero" causes a special Block device zero Token to be created.

              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.
              odx: SEEK can be a scatter list: comma separated, in the form seek=A1,N1[,A2,N2...]
              . The scatter list  may  alternatively  be  read  from  a  file  using  this  form:
              seek=@<filename> or read from stdin using this form: seek=- (or seek=@-) . A<n> and
              N<n> are decimal (optionally with a suffix multiplier) unless a hex  indication  is
              given.  Hex  values  are  indicated by either a leading "0x" or a trailing "h". The
              address (i.e. A<n>) is a 64 bit unsigned integer while the number of  blocks  (i.e.
              N<n>)  is  a  32 bit integer.  Thus for a block size of 512 bytes, a single scatter
              gather list element cannot exceed 4 TB ((2**32 - 1) * 512). Note that COUNT is a 64
              bit  unsigned integer and thus does not have this restriction. There can be no more
              than 128 scatter list elements.

              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 the number of
              IBS-sized blocks in IFILE.
              odx: SKIP can be a gather list: comma separated, in the form  skip=A1,N1[,A2,N2...]
              .  The  gather  list  may  alternatively  be  read  from  a  file  using this form:
              skip=@<filename> or read from stdin using this form: skip=- . See the  odx  section
              of the seek=SEEK option for further details.

              the  STAT  value  of  'noxfer'  suppresses  the  throughput speed and the copy time
              reporting at the end of the copy. A STAT value of  'none'  additionally  suppresses
              the  records  in and out reporting after the copy.  So 'status=none' makes ddpt act
              like a traditional Unix command in which "no  news  is  good  news".   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.

       to=TO  odx,  xcopy:  where  TO  is  am  xcopy originating command timeout in seconds.  The
              default value is 0 which is converted internally to 600 seconds (10 minutes).  Best
              to  set  this  timeout value well above the expected copy time.  In a odx full copy
              this timeout is applied to both the POPULATE TOKEN and WRITE USING TOKEN commands.

              as VERB increases so does the amount of debug reporting sent  to  stderr.   Default
              value  is  zero  which  yields the minimum amount of debug reporting.  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
              reporting  for  all SCSI commands, plus Unix read() and write() calls, so there can
              be a lot of output.  If VERB is "-1" then reporting that would have  been  sent  to
              stderr is redirected to /dev/null essentially throwing it away.

       -h, --help
              reports usage message then exits.

       -o, --odx
              indicates  to this utility that one of the four odx variants is requested.  See ODX

       -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
              reports version number information then 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.

       -x, --xcopy
              this  option  will  attempt  to  call  the SCSI EXTENDED COPY(LID1) command. In the
              absence of another indication the xcopy command will be  sent  to  the  destination
              (i.e. OFILE). See the section on ENVIRONMENT VARIABLES below.


       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. After a regular file to regular file copy the length of
       OFILE will be the same as IFILE unless OFILE existed and its length  was  already  greater
       than  that of IFILE. To get a copy like the standard Unix cp command, use oflag=trunc with

       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 inherited from GNU's dd overlap somewhat with
       the some of ddpt flags.

              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

              equivalent to "oflag=no_del_tkn".

              this conversion is very close to "iflag=coe" and is treated as such. See the  "coe"
              flag.  Note  that  an  error  on a block device or regular file OFILE will stop the

              this conversion is accepted for compatibility with dd and ignored since the default
              action of this utility is not to truncate OFILE.

       null   has no affect, just a placeholder.

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

              equivalent to "oflag=rtf_len".

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

       sparse FreeBSD's  dd  supports  "conv=sparse"  and  now  GNU's dd does as well so the same
              syntax is  supported  in  ddpt.  See  "sparse"  in  the  FLAGS  sections  for  more

       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" "pt", "odx", or "xcopy". These
       indicate whether the flag applies to a regular file, a block  device  (accessed  via  Unix
       read() and write() commands, a pass-through device, an ODX offloaded copy or a XCOPY(LID1)
       offloaded copy respectively.  Other special file types that are sometimes referred to  are
       "fifo" and "tape".

       append [o] [reg], [io] [odx]
              causes  the  O_APPEND flag to be added to the open of OFILE. For regular files this
              will lead to data being 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.
              odx: if the rtf=RTF option is given, RTF exists, is a regular file and this utility
              wants  to  write to RTF then new ROD Tokens are appended to RTF. The default action
              is to truncate RTF before new ROD Tokens are written to it.

       block [io] [pt]
              pass-through file opens are non-blocking by default and may report the pt device is
              busy.  Use  this  flag  to  open blocking so utility may wait until another process
              locking (or with an exclusive open) is complete before continuing.

       cat [io] [xcopy]
              xcopy: set CAT (residual data handling) bit in EXTENDED COPY(LID1)  parameter  list
              segment descriptor header. May appear in either flag list when xcopy is being used.
              Works with the PAD bit for handling residual data on the destination side. See  the
              XCOPY section below.

       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 reported in the summary at the end of the copy.

              This paragraph concerns coe on pt devices. A medium, hardware or blank check  error
              during  a  read operation will will cause the following: first re-read blocks prior
              to the bad block, then try to recover  the  bad  block  (supplying  zeros  if  that
              fails),  and  finally re-read the blocks after the bad block. A medium, hardware or
              blank check error while writing is reported but otherwise 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 reported.

              This paragraph concerns 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.

       dc [io] [blk,pt]
              xcopy:  set  DC  (destination  counter)  bit  in EXTENDED COPY(LID1) parameter list
              segment descriptor header. May appear in either flag list when xcopy is being used.

       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 reported 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] [xcopy,odx]
              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.
              xcopy and odx: various limits imposed by associated VPD pages or the  RECEIVE  COPY
              OPERATING  PARAMETERS  command  can  be overridden (i.e.  exceeded) if this flag is
              given. Note that the copy manager will probably object.

       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. The
              FUA_NV bit was made obsolete in SBC-3 revision 35d.

       ignoreew [o] [tape]
              ignore the early warning indication (of end of tape) when  writing  to  tape.   See
              TAPE section.

       immed [io] [odx]
              sets the IMMED bit in the POPULATE TOKEN (when [i]) or WRITE USING TOKEN (when [o])
              command. That command  should  return  status  promptly  after  starting  the  data
              transfer.  The  RECEIVE  ROD  TOKEN  INFORMATION  command  is then used to poll for
              completion. SCSI command timeouts should not be exceeded, even for very large RODs,
              if this flag is used.

       nocache [io] [reg,blk]
              use  posix_fadvise(POSIX_FADV_DONTNEED)  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.

       no_del_tkn [o] [odx]
              will  clear the DEL_TKN bit on the last WRITE USING TOKEN command of each ROD Token
              in a odx full copy. In a large odx full copy several ROD Tokens may  be  used  (one
              after  the  other).  The  default  action is to set the DEL_TKN bit on the last WUT
              command of each ROD. Either way it should not make much difference because the copy
              manager  deletes  a ROD Token after a copy is completed. The copy manager will also
              delete/invalidate a ROD Token if the inactivity timeout is reached.

       nofm [o] [tape]
              no File Mark (FM) on close when writing to tape. See TAPE section.

       nopad [o] [tape]
              when the block to be written to a tape drive contains less  than  OBS  bytes,  then
              this  option causes the partial block to be written as is. The default action for a
              tape in this case is to pad the block. See TAPE section.

       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.

       odx [io] [odx]
              indicates  to  this  utility  that  one  of  the  four  variants  of an odx copy is
              requested. Using any of the --odx, rtf=RTF or rtype=RTYPE  options  also  indicates
              that odx is requested. See the ODX section.

       pad [o] [reg,blk,pt], [io] [xcopy]
              when  the  block  to  be  written (typically the last block) contains less than OBS
              bytes, then this option causes the block to be padded with  zeros  (i.e.  bytes  of
              binary  zero).  The default action for a regular file and a fifo is to do a partial
              write. The default action of a block and a pt  device  is  to  ignore  the  partial
              write.  The default action of a tape is to pad, so this flag is not needed (see the
              nopad flag).
              xcopy: sets the PAD bit in the CSCD descriptor of the associated IFILE or OFILE. Is
              associated  with  residual  data handling and works together with the cat flag. See
              the XCOPY section below.

       prealloc [o] [reg]
              use the fallocate() call prior to starting a copy to  set  OFILE  to  its  expected

       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* and some  /dev/bsg/*  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.

       rarc [i] [pt]
              bit  set  in  READ(10, 12, 16 and 32) to suppress RAID rebuild functions when a bad
              (or recovered after difficulties) block is detected.

       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.

       rtf_len [io] [odx]
              odx:  with  the  'read  to  tokens'  variant, after 512 bytes of each ROD Token are
              written to IRTF an additional 8 byte (big endian) integer is written. That  integer
              is  the number of bytes the associated ROD represents.  The draft standards say for
              standard ROD types the ROD Token holds this  value.  However  vendor  specific  ROD
              types  may  be  used or the vendors may choose not to comply. Either way the 'write
              from tokens' variant needs to know the size of the ROD it is writing from.

       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".

       unmap [io] [pt]
              same as the trim flag.

       xcopy [io] [pt]
              invoke  SCSI  XCOPY(LID1)  logic  and send the XCOPY command to the either IFILE or
              OFILE depending on which flag this called. If both are given  (i.e.  an  invocation
              including 'iflag=xcopy  oflag=xcopy') then send the XCOPY(LID1) to OFILE.


       This section describes XCOPY(LID1) support with this utility. For ODX support (XCOPY(LID4)
       subset) see the ODX section.

       A device (logical unit (LU)) that supports XCOPY operations should set the 3PC field  (3PC
       stands  for  Third  Party Copy) in its standard INQUIRY response. That is not checked when
       this utility does an xcopy operation but if it fails, that is one thing that the user  may
       want to check.

       If  the  xcopy starts and fails while underway, then 'sg_copy_results -s' may be useful to
       view the copy status. It might also be used from a different process  with  the  same  I_T
       nexus (i.e. the same machine) to check status during an xcopy operation.

       The  pad and cat flags control the handling of residual data. As the data can be specified
       either in terms of source or target block size and both might have different  block  sizes
       residual data is likely to happen in these cases.  If both block sizes are identical these
       bits have no effect as residual data will not occur.

       If neither of these flags are  set,  the  EXTENDED  COPY  command  will  be  aborted  with
       additional sense 'UNEXPECTED INEXACT SEGMENT'.

       If  only  the  cat  flag  is set the residual data will be retained and made available for
       subsequent segment descriptors. Residual data will  be  discarded  for  the  last  segment

       If  the  pad flag is set for the source descriptor only, any residual data for both source
       or destination will be discarded.

       If the pad flag is set for the target descriptor only any residual  source  data  will  be
       handled  as  if  the  cat flag is set, but any residual destination data will be padded to
       make a whole block transfer.

       If the pad flag is set for both source  and  target  any  residual  source  data  will  be
       discarded, and any residual destination data will be padded.

       There     is     a     web     page     discussing     ddpt,     XCOPY    and    ODX    at


       This section describes  ODX  support  (an  XCOPY(LID4)  subset)  for  this  utility.   ODX
       descriptions  use  the  following  command  name  abbreviations: PT for the POPULATE TOKEN
       command, RRTI for the READ ROD TOKEN INFORMATION command, and  WUT  for  the  WRITE  USING
       TOKEN command.

       A device (logical unit (LU)) that supports ODX operations is required to set the 3PC field
       (3PC stands for Third Party Copy) in its standard INQUIRY response and support  the  Third
       Party Copy VPD page. If this utility generates errors noting the absence of these then the
       device in question probably does not support ODX.

       There a four variants of ODX supported by ddpt:
         full copy : ddpt --odx if=/dev/sg3 bs=512 of=/dev/sg4
         zero output blocks : ddpt if=/dev/null rtype=zero bs=512 of=/dev/sg4
         read to tokens : ddpt if=/dev/sg3 bs=512 skip=@gath.lst rtf=a.rt
         write from tokens : ddpt rtf=a.rt bs=512 of=/dev/sg4 seek=@scat.lst

       The full copy will call PT and WUT commands repeatedly until the copy  is  complete.  More
       precisely  the  full  copy  will make the largest single call to PT allowed by the input's
       Third  Party  Copy  VPD  page  (and,  if  given,  allowed  by  the  BPT  argument  in  the
       bpt=BPT[,OBPC]  option).  Then  one  or  more WUT calls are made to write out from the ROD
       created by the PT step. The largest single WUT call is constrained by the  output's  Third
       Party  Copy  VPD  page  (and, if given, allowed by the OBPC argument in the bpt=BPT[,OBPC]
       option). This sequence continues until the requested copy is complete.

       The zero output blocks variant is a special case of the full copy in which only WUT  calls
       are  made.  ODX  defines  a special ROD Token to zero blocks. That special ROD Token has a
       fixed pattern (shown in SBC-3) and does not need to be created by a PT command like normal
       ROD Tokens.

       The  read to tokens and the write from tokens variants are designed to be the read (input)
       and write (output) sides respectively of a  network  copy.   Each  can  run  on  different
       machines  by sending the RTF file from the machine doing the read to the machine doing the
       write. The read to tokens will make one or more PT calls  and  output  the  resulting  ROD
       Tokens to the RTF file. RTF might be a regular file or a named pipe.

       All  four variants can have the immed flag set. Then the PT and/or WUT commands are issued
       with the IMMED bit set and the RRTI command is used to  poll  for  completion.  The  delay
       between  the  polls  is as suggested by the RRTI command (or if no suggestion is made, 500
       milliseconds). Either iflag=immed, oflag=immed or both can be given but are only effective
       if the corresponding IFILE or OFILE sends a PT or WUT command.

       Typically  there  is  no  need to give the list_id=LID option. If this option is not given
       then 257 is chosen. If that is busy then 258 is tried.  That continues until a usable  LID
       is  found  or  10  LIDs  have  been tried. In the latter case ddpt exits with status of 55
       (operation in progress). If the user gives list_id=LID option and LID is  busy  then  ddpt
       exits with exit status 55.

       If  the  block  size  of the input and output are different (i.e. IBS is not equal to OBS)
       then one must be a multiple of the other. So an input block  size  of  512  bytes  and  an
       output block size of 4096 bytes (or vice versa) is acceptable.

       The  four  ODX  variants  are distinguished as follows: if OFILE is a pass-through device,
       if=/dev/null (or equivalent) and  rtype=zero  then  the  zero  output  blocks  variant  is
       selected. If both IFILE and OFILE are pass-through devices and there is some indication of
       an ODX request (e.g.  the --odx option), then the full copy variant is selected. The  read
       to  tokens  and  the  write  from  token variants are indicated by the absence of either a
       of=OFILE or a if=IFILE option, respectively, plus the presence of a rtf=RTF option.

       The helper utility ddptctl contains options to issue  a  single  PT,  RRTI,  WUT  or  COPY
       OPERATION  ABORT  command.  It  can  also  issue a series of polling RRTI commands. It can
       decode information in ROD Tokens (which is not as informative as it should be)  and  print
       the  number  of blocks and block size of a disk, plus protection information if available.
       See ddptctl.

       There    is    a    web     page     discussing     ddpt,     XCOPY     and     ODX     at


       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
       typically spew binary data  on  the  console.  So  ddpt  has  changed  its  defaults:  the
       "if=IFILE"  is  now mandatory for direct copies 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.

       ddpt  adds  two  types  of disk to disk, offloaded copies: XCOPY(LID1) first introduced in
       SPC-2 (standardized in 2001), and ODX which is a subset of XCOPY(LID4) first introduced in
       SPC-4 draft (revision 34, 2012).


       This  section  is  about  protection  information  which  is  typically  an  extra 8 bytes
       associated with each logical block. Those 8 byte are divided into 3 fields: logical  block
       guard (16 bit (2 byte) CRC), logical block application tag (2 bytes) and the logical block
       reference tag (4 bytes). The acronym DIF is sometimes used for protection information.

       The feature to read and/or write protection information  by  using  the  protect=RDP[,WRP]
       option is currently experimental. It should be used with care and may not "play well" with
       some other features such as write sparing and sparse writing. It should be  used  to  copy
       user  data  plus the associated protection information to or from a regular file. It could
       also be used for a device to device copy assuming the "pt" interface  is  used  for  both.
       Also only modern SCSI disks support protection information.

       When  RDP  or  WRP is greater than 0 then a copy with associated protection information is
       active. In this state IBS and OBS must be the same and equal to the logical block size  of
       the  device(s) formatted with protection information. If a SCSI disk with 512 byte logical
       block size has protection information then the actual number of bytes transferred for each
       logical  block  is  typically  520  bytes.  For  such  a disk BS=512 is required even when
       additional protection information is being transferred.


       By default numeric arguments to options are assumed to  be  decimal.  Almost  all  numeric
       arguments  to  options  (e.g.  COUNT  in  the count=COUNT option) 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 64 bit values. Some numeric arguments are limited to 32  bit
       values  (e.g.  BSin  the  bs=BS  option).  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 indicated by either  a  leading
       "0x"  or "0X", or by a trailing "h" or "H". When hex numbers are given, suffix multipliers
       cannot be used.

       If a numeric argument is required to fit in 32 bits and is too  large  then  an  error  is
       reported.  Usually negative numbers are not permitted but "count=-1" is a special case and
       means "all available"; "verbose=-1" is another special case.


       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 reported 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.

       All informative, warning and error reports are sent to stderr so that dd's output file can
       be  stdout  and  remain unpolluted. If no options are given, then no copying (nor reading)
       takes place and a brief message is sent to stderr inviting the user to invoke  ddpt  again
       but with '--help' option to get the usage message.

       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 drives so ddpt cannot be used on tape drives via a pt  device.  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 pt device is accessed via SCSI  READ(16)  and
       WRITE(16) commands.

       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  SCSI  READ(32)  and WRITE(32) commands are restricted to media that is formatted with
       protection type 2. This is a T10 restriction.


       The signal handling has been borrowed from GNU's dd: SIGINT, SIGQUIT  and  SIGPIPE  report
       the  number  of  remaining  blocks to be transferred and the records in + out counts; then
       they have their default action. SIGUSR1 (or SIGINFO) causes the  same  information  to  be
       output and the copy continues.  All output caused by signals is sent to stderr.

       Like  GNU's  dd,  ddpt  respects  the signal disposition of "ignored" (SIG_IGN) set by the
       shell, script or other program that invokes ddpt. So in that  case  it  will  ignore  such
       signals.  Further  dd  ignores  SIGUSR1 if the environment variable POSIXLY_CORRECT is set
       because POSIX defines dd will only act on SIGINFO (and Linux has  no  such  signal);  ddpt
       ignores  the  POSIXLY_CORRECT environment variable. As recommended by Susv3, ddpt does not
       expect the signal (blocking) mask to be blocking SIGUSR1 (SIGINFO), SIGINT or  SIGPIPE  on

       Unix  system calls that do IO can be interrupted by signal processing, typically returning
       an EINTR error number. The dd utility (and many  other  Unix  utilities)  restart  the  IO
       operation  that  was  interrupted. While this will work most of the time for disk IO it is
       problematic for tape drives because the implicit position pointer on  the  tape  may  have
       moved.  So the default (i.e. "intio=0") in this utility is to mask those signals during IO
       operations and only check them prior to starting an IO operation.  Most low level IO (e.g.
       using SCSI command to write to a disk) will timeout if there is a low level error. However
       NFS (the Network File System) will potentially wait for a  long  time  (e.g.  expecting  a
       network problem will soon be fixed) and in this case using "intio=1" may be best.


       There  is  support  for copies to and from tape drives in Linux. Only the st driver device
       names can be used (e.g. /dev/st0 and /dev/nst2). Hence use of  Linux  pass-through  device
       names  (e.g. /dev/sg2) for tape drives is not supported. On Debian-based distributions, it
       is suggested that the mt-st package is installed as  it  provides  a  more  fully-featured
       version of the "mt" tape control program.

       Tape  drives can operate in fixed- or variable-length block modes. In variable-block mode,
       each write to the tape writes a single block of that size. In fixed-block mode, each write
       to the tape must be a multiple of the previously-selected block size.

       The block size/mode can be set with the mt command prior to invoking ddpt.  For example:
         # mt -f /dev/nst0 setblk 0
       sets variable-block mode, and
         # mt -f /dev/nst0 setblk 32768
       sets fixed-block mode with block size 32768 bytes.

       Note that some tape drives support only fixed-block mode, and possibly even only one block
       size. (For example, QIC-150 tapes use a fixed block size of 512 bytes.) There may also  be
       restrictions on the block size, e.g.  it may have to be even.

       When using ddpt to write to tape, if the final read from the input is less than OBS, it is
       padded to OBS bytes before writing to tape to ensure that all blocks of the tape file  are
       the  same  length.  Having a shorter final block would fail if the drive is in fixed-block
       mode, and could create interchange problems. It is common to expect all blocks in  a  file
       on  tape  to  be  the  same  length. However, to tell ddpt to not pad the final block, use

       The st tape driver normally writes a filemark when the file (e.g. /dev/nst0) is closed. To
       not  have  the filemark written, use 'oflag=nofm'. One use case for that might be if using
       ddpt several times in succession to append more data to the same file  on  tape.  In  that
       case  it is probably desirable to write the filemark at the end of the sequence. So either
       omit 'oflag=nofm' on the last ddpt invocation, or manually write a filemark using mt after
       ddpt exits:
         # mt -f /dev/nst0 weof 1

       For  reading  from  an  unknown  tape  where  the  block  size(s)  is  not  known, read in
       variable-block mode specifying a large IBS. The st driver returns a smaller amount of data
       if the size of the block read is smaller. Thus a command like:
         # ddpt if=/dev/nst0 of=output.bin bs=262144
       should  read  the file from tape regardless of the block size used (assuming no blocks are
       larger than 256KB). ddpt's verbose option will display what the actual block size(s) is.


       If the command line invocation  of  an  xcopy  does  not  explicitly  (and  unambiguously)
       indicate  whether  the  XCOPY  SCSI  command should be sent to IFILE (i.e.  the source) or
       OFILE (i.e. the destination) then a check is made for the presence of the XCOPY_TO_SRC and
       XCOPY_TO_DST  environment variables. If either one exists (but not both) then it indicates
       where the SCSI XCOPY command will be sent. By default the XCOPY command is sent to OFILE.

       The ODX write from tokens variant is very complex to implement if the amount of data  held
       in  each  ROD is not known. The value should be found in the "number of bytes represented"
       field in the ROD Token but that is not well supported yet by vendors.  So  for  such  case
       that number can be appended as a big endian 8 byte integer following each ROD Token in the
       RTF file. The conv=rtf_len will cause that length to be appended. Specifying  that  option
       on  each  read  to  tokens and write from tokens invocation can be a nuisance. Setting the
       environment variable ODX_RTF_LEN will cause this utility to act  as  if  the  conv=rtf_len
       option has been given.


       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.

       51     a  command  received  'illegal field in parameter list'. This may occur with an odx
              copy  if  some  combination  of  parameters  is  illegal  or  not  supported  (e.g.

       55     a  command  received  'operation in progress'. This may occur with an odx copy when
              the given LID is already being used by another process (e.g. also using odx) on the
              same machine. Choose another LID.

       70     a  command received 'invalid token operation, cause not reportable'. This may occur
              with an odx operation when the given ROD Token is invalid. One reason for that  may
              be  the  inactivity timeout has been reached and the copy manager has cancelled the
              ROD Token.

       71-89  these status values provide more information than exit status 70. See SPC-4 ASC and
              ASCQ  assignments  (currently in Annex F.2), specifically the entries for asc=23h .
              For example exit status 72 corresponds to asc=23h, ascq=2h which  implies  the  odx
              copy  manager  does  not  support  copies between LUs in different targets. That is
              optional; an odx copy manager is required to support copies between LUs  (that  are
              block devices) in the same target.

       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.


       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 UNIT command or an ATA SECURITY ERASE command a disk may be all

          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  containing examples called ddpt_examples.txt in the "doc" directory of this
       package's distribution tarball.


       Written by Doug Gilbert


       Report bugs to <dgilbert at interlog dot com>.


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


       This utility has a companion/helper utility called ddptctl(8)
       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  verify  the  data on the media or to verify it against some other copy of the data see

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

       Additional    references:    dd(1),    open(2),    flock(2),     sg_xcopy,sg_copy_results,