1SG_DD(8)                           SG3_UTILS                          SG_DD(8)
2
3
4

NAME

6       sg_dd  -  copy  data  to  and  from  files and devices, especially SCSI
7       devices
8

SYNOPSIS

10       sg_dd   [bs=BS]   [conv=CONV]   [count=COUNT]    [ibs=BS]    [if=IFILE]
11       [iflag=FLAGS] [obs=BS] [of=OFILE] [oflag=FLAGS] [seek=SEEK] [skip=SKIP]
12       [--help] [--version]
13
14       [blk_sgio={0|1}]   [bpt=BPT]    [cdbsz={6|10|12|16}]    [coe={0|1|2|3}]
15       [coe_limit=CL]  [dio={0|1}]  [odir={0|1}]  [of2=OFILE2]  [retries=RETR]
16       [sync={0|1}] [time={0|1}] [verbose=VERB] [-V]
17

DESCRIPTION

19       Copy data to and from any files. Specialized for "files" that are Linux
20       SCSI  generic  (sg)  devices, raw devices or other devices that support
21       the SG_IO ioctl (which are only found in the lk  2.6  series).  Similar
22       syntax and semantics to dd(1) command.
23
24       The  first  group in the synopsis above are "standard" Unix dd(1) oper‐
25       ands. The second group are extra options added by this  utility.   Both
26       groups are defined below.
27
28       This utility is only supported on Linux whereas most other utilities in
29       the sg3_utils package have been ported to other  operating  systems.  A
30       utility  called  "ddpt"  has similar syntax and functionality to sg_dd.
31       ddpt drops some Linux specific features while adding some other generic
32       features. This allows ddpt to be ported to other operating systems.
33

OPTIONS

35       blk_sgio={0|1}
36              when  set  to  0, block devices (e.g. /dev/sda) are treated like
37              normal files (i.e.  read(2) and write(2) are used for IO).  When
38              set  to  1,  block devices are assumed to accept the SG_IO ioctl
39              and SCSI commands are issued for IO. This is only supported  for
40              2.6  series  kernels. Note that ATAPI devices (e.g. cd/dvd play‐
41              ers) use the SCSI command set but ATA disks do not (unless there
42              is a protocol conversion as often occurs in the USB mass storage
43              class). If the input or output device is a block  device  parti‐
44              tion (e.g. /dev/sda3) then setting this option causes the parti‐
45              tion information to be ignored (since access is directly to  the
46              underlying device). Default is 0. See the 'sgio' flag.
47
48       bpt=BPT
49              each  IO  transaction  will be made using BPT blocks (or less if
50              near the end of the copy). Default is 128 for block  sizes  less
51              that  2048 bytes, otherwise the default is 32. So for bs=512 the
52              reads and writes will each convey 64  KiB  of  data  by  default
53              (less  if  near the end of the transfer or memory restrictions).
54              When cd/dvd drives are accessed, the  block  size  is  typically
55              2048  bytes  and  bpt  defaults to 32 which again implies 64 KiB
56              transfers. The block layer when the blk_sgio=1  option  is  used
57              has  relatively low upper limits for transfer sizes (compared to
58              sg device nodes, see  /sys/block/<dev_name>/queue/max_sectors_kb
59              ).
60
61       bs=BS  where  BS  must  be  the  block  size of the physical device (if
62              either the input or output files  are  accessed  via  SCSI  com‐
63              mands). Note that this differs from dd(1) which permits BS to be
64              an integral multiple. Default is 512 which  is  usually  correct
65              for  disks  but  incorrect  for cdroms (which normally have 2048
66              byte blocks). For this utility the maximum size of each individ‐
67              ual IO operation is BS * BPT bytes.
68
69       cdbsz={6|10|12|16}
70              size  of  SCSI  READ  and/or  WRITE commands issued on sg device
71              names (or block devices when 'iflag=sgio' and/or 'oflag=sgio' is
72              given).  Default is 10 byte SCSI command blocks (unless calcula‐
73              tions indicate that a 4 byte block number may be exceeded or BPT
74              is greater than 16 bits (65535), in which case it defaults to 16
75              byte SCSI commands).
76
77       coe={0|1|2|3}
78              set to 1 or more for continue on error. Only applies  to  errors
79              on  sg  devices  or block devices with the 'sgio' flag set. Thus
80              errors on other files  will  stop  sg_dd.  Default  is  0  which
81              implies  stop on any error. See the 'coe' flag for more informa‐
82              tion.
83
84       coe_limit=CL
85              where CL is the maximum number of consecutive bad blocks stepped
86              over  (due to "coe>0") on reads before the copy terminates. This
87              only applies when IFILE is accessed via  the  SG_IO  ioctl.  The
88              default  is  0  which is interpreted as no limit. This option is
89              meant to stop the copy soon after unrecorded media  is  detected
90              while still offering "continue on error" capability.
91
92       conv=sparse
93              see the CONVERSIONS section below.
94
95       count=COUNT
96              copy  COUNT  blocks  from IFILE to OFILE. Default is the minimum
97              (of IFILE and OFILE) number of blocks  that  sg  devices  report
98              from SCSI READ CAPACITY commands or that block devices (or their
99              partitions) report. Normal files are not probed for their  size.
100              If  skip=SKIP  or  skip=SEEK  are given and the count is derived
101              (i.e.  not explicitly given) then the derived  count  is  scaled
102              back  so  that the copy will not overrun the device. If the file
103              name is a block device partition and COUNT is not given then the
104              size  of  the partition rather than the size of the whole device
105              is used. If COUNT is not  given  (or  count=-1)  and  cannot  be
106              derived then an error message is issued and no copy takes place.
107
108       dio={0|1}
109              default is 0 which selects indirect (buffered) IO on sg devices.
110              Value of 1 attempts direct IO which,  if  not  available,  falls
111              back  to  indirect IO and notes this at completion. If direct IO
112              is selected and /proc/scsi/sg/allow_dio has the value of 0  then
113              a  warning  is issued (and indirect IO is performed).  For finer
114              grain control use 'iflag=dio' or 'oflag=dio'.
115
116       ibs=BS if given must be the same as BS given to 'bs=' option.
117
118       if=IFILE
119              read from IFILE instead of stdin. If IFILE is '-' then stdin  is
120              read.  Starts  reading  at the beginning of IFILE unless SKIP is
121              given.
122
123       iflag=FLAGS
124              where FLAGS is a comma separated list of one or more flags  out‐
125              lined  below.   These  flags  are  associated with IFILE and are
126              ignored when IFILE is stdin.
127
128       obs=BS if given must be the same as BS given to 'bs=' option.
129
130       odir={0|1}
131              when set to one opens block devices  (e.g.  /dev/sda)  with  the
132              O_DIRECT  flag. User memory buffers are aligned to the page size
133              when set. The default is 0 (i.e. the O_DIRECT flag is not used).
134              Has  no  effect  on sg, normal or raw files. If blk_sgio is also
135              set then both are honoured: block devices are  opened  with  the
136              O_DIRECT flag and SCSI commands are issued via the SG_IO ioctl.
137
138       of=OFILE
139              write to OFILE instead of stdout. If OFILE is '-' then writes to
140              stdout.  If OFILE is /dev/null then no actual  writes  are  per‐
141              formed.   If  OFILE  is '.' (period) then it is treated the same
142              way as /dev/null (this is a shorthand notation). If OFILE exists
143              then  it is _not_ truncated; it is overwritten from the start of
144              OFILE unless 'oflag=append' or SEEK is given.
145
146       of2=OFILE2
147              write output to OFILE2. The default action is  not  to  do  this
148              additional write (i.e. when this option is not given). OFILE2 is
149              assumed to be a normal file or  a  fifo  (i.e.  a  named  pipe).
150              OFILE2  is  opened for writing, created if necessary, and closed
151              at the end of the transfer. If OFILE2 is  a  fifo  (named  pipe)
152              then  some  other  command  should  be consuming that data (e.g.
153              'md5sum OFILE2'), otherwise this utility will block.
154
155       oflag=FLAGS
156              where FLAGS is a comma separated list of one or more flags  out‐
157              lined  below.   These  flags  are  associated with OFILE and are
158              ignored when OFILE is /dev/null, '.' (period), or stdout.
159
160       retries=RETR
161              sometimes retries at the host are useful, for example when there
162              is  a  transport error. When RETR is greater than zero then SCSI
163              READs and WRITEs are retried on error, RETR times. Default value
164              is zero.
165
166       seek=SEEK
167              start  writing  SEEK  bs-sized  blocks  from the start of OFILE.
168              Default is block 0 (i.e. start of file).
169
170       skip=SKIP
171              start reading SKIP bs-sized blocks  from  the  start  of  IFILE.
172              Default is block 0 (i.e. start of file).
173
174       sync={0|1}
175              when  1,  does  SYNCHRONIZE CACHE command on OFILE at the end of
176              the transfer. Only active when OFILE is a sg device file name or
177              a block device and 'blk_sgio=1' is given.
178
179       time={0|1}
180              when  1,  times  transfer  and does throughput calculation, out‐
181              putting the results (to stderr) at completion. When 0  (default)
182              doesn't perform timing.
183
184       verbose=VERB
185              as  VERB  increases  so  does the amount of debug output sent to
186              stderr.  Default value is zero which yields the  minimum  amount
187              of debug output.  A value of 1 reports extra information that is
188              not repetitive. A value 2 reports cdbs and  responses  for  SCSI
189              commands  that  are  not  repetitive  (i.e.  other that READ and
190              WRITE). Error processing is not considered repetitive. Values of
191              3  and 4 yield output for all SCSI commands (and Unix read() and
192              write() calls) so there can be  a  lot  of  output.   This  only
193              occurs  for scsi generic (sg) devices and block devices when the
194              'blk_sgio=1' option is set.
195
196       --help outputs usage message and exits.
197
198       --version
199              outputs version number information and exits.
200
201       -V     outputs version number information and exits.
202

CONVERSIONS

204       One or more conversions can be given to the  "conv="  option.  If  more
205       than  one is given, they should be comma separated. sg_dd does not per‐
206       form the traditional dd conversions (e.g. ASCII  to  EBCDIC).  Recently
207       added  conversions  overlap somewhat with the flags so some conversions
208       are now supported by sg_dd.
209
210       noerror
211              this conversion is very close to "iflag=coe" and is  treated  as
212              such.  See the "coe" flag. Note that an error on OFILE will stop
213              the copy.
214
215       notrunc
216              this conversion is accepted for compatibilty with dd and ignored
217              since  the  default  action  of  this utility is not to truncate
218              OFILE.
219
220       null   has no affect, just a placeholder.
221
222       sparse FreeBSD supports "conv=sparse" so the same syntax  is  supported
223              in  sg_dd.  See "sparse" in the FLAGS sections for more informa‐
224              tion.
225
226       sync   is ignored by sg_dd. With dd it means supply zero  fill  (rather
227              than  skip)  and is typically used like this "conv=noerror,sync"
228              to have the same functionality as sg_dd's "iflag=coe".
229

FLAGS

231       Here is a list of flags and their meanings:
232
233       append causes the O_APPEND flag to be added to the open of  OFILE.  For
234              regular  files this will lead to data appended to the end of any
235              existing data.  Cannot  be  used  together  with  the  seek=SEEK
236              option  as they conflict.  The default action of this utility is
237              to overwrite any existing data from the beginning  of  the  file
238              or, if SEEK is given, starting at block SEEK. Note that attempt‐
239              ing to 'append' to a device file (e.g.  a disk) will usually  be
240              ignored or may cause an error to be reported.
241
242       coe    continue  on error. Only active for sg devices and block devices
243              that have the 'sgio' flag set. 'iflag=coe oflag=coe' and 'coe=1'
244              are  equivalent.  Use  this flag twice (e.g. 'iflag=coe,coe') to
245              have the same action as the 'coe=2'. A medium, hardware or blank
246              check  error  while reading will re-read blocks prior to the bad
247              block, then try to recover the bad  block,  supplying  zeros  if
248              that fails, and finally reread the blocks after the bad block. A
249              medium, hardware or blank check error while writing is noted and
250              ignored.  The  recovery  of  the bad block when reading uses the
251              SCSI READ LONG command if 'coe' given twice or more  (also  with
252              the  command  line  option 'coe=2'). Further, the READ LONG will
253              set its CORRCT bit if 'coe' given thrice. SCSI disks  may  auto‐
254              matically try and remap faulty sectors (see the AWRE and ARRE in
255              the read write error recovery mode page (the sdparm utility  can
256              access  and possibly change these attributes)). Errors occurring
257              on other files types will stop sg_dd.  Error messages  are  sent
258              to stderr. This flag is similar
259               o 'conv=noerror,sync' in the dd(1) utility. See note about READ
260              LONG below.
261
262       dio    request the sg device node associated with this flag does direct
263              IO.   If  direct  IO is not available, falls back to indirect IO
264              and notes this at completion.  If  direct  IO  is  selected  and
265              /proc/scsi/sg/allow_dio  has  the  value  of 0 then a warning is
266              issued (and indirect IO is performed).
267
268       direct causes the O_DIRECT flag to be added to the open of IFILE and/or
269              OFILE.  This  flag  requires  some memory alignment on IO. Hence
270              user memory buffers are aligned to the page size. Has no  effect
271              on  sg, normal or raw files. If 'iflag=sgio' and/or 'oflag=sgio'
272              is also set then both are honoured:  block  devices  are  opened
273              with  the  O_DIRECT  flag  and  SCSI commands are issued via the
274              SG_IO ioctl.
275
276       dpo    set the DPO bit (disable page out) in SCSI READ and  WRITE  com‐
277              mands.  Not supported for 6 byte cdb variants of READ and WRITE.
278              Indicates that data is unlikely to be required to stay in device
279              (e.g.  disk)  cache.   May speed media copy and/or cause a media
280              copy to have less impact on other device users.
281
282       dsync  causes the O_SYNC flag to be added to the open of  IFILE  and/or
283              OFILE.  The  'd'  is  prepended  to  lower  confusion  with  the
284              'sync=0|1' option which has another action (i.e. a  synchronisa‐
285              tion to media at the end of the transfer).
286
287       excl   causes  the  O_EXCL flag to be added to the open of IFILE and/or
288              OFILE.
289
290       flock  after opening the associated file (i.e. IFILE and/or  OFILE)  an
291              attempt  is  made  to  get  an  advisory exclusive lock with the
292              flock()  system  call.  The  flock  arguments  are  "FLOCK_EX  |
293              FLOCK_NB"  which  will  cause  the lock to be taken if available
294              else a "temporarily unavailable" error  is  generated.  An  exit
295              status of 90 is produced in the latter case and no copy is done.
296
297       fua    causes  the  FUA  (force unit access) bit to be set in SCSI READ
298              and/or WRITE commands. This only has an effect with  sg  devices
299              or block devices that have the 'sgio' flag set. The 6 byte vari‐
300              ants of the SCSI READ and WRITE commands do not support the  FUA
301              bit.
302
303       nocache
304              use  posix_fadvise()  to  advise  corresponding file there is no
305              need to fill the file  buffer  with  recently  read  or  written
306              blocks.
307
308       null   has no affect, just a placeholder.
309
310       sgio   causes  block  devices to be accessed via the SG_IO ioctl rather
311              than standard UNIX read() and write() commands. When  the  SG_IO
312              ioctl is used the SCSI READ and WRITE commands are used directly
313              to move data. sg devices always use the SG_IO ioctl.  This  flag
314              offers  finer  grain control compared to the otherwise identical
315              'blk_sgio=1' option.
316
317       sparse after each BS * BPT byte segment is read from the input,  it  is
318              checked  for  being  all zeros. If so, nothing is written to the
319              output file unless this is the last  segment  of  the  transfer.
320              This  flag  is  only  active with the oflag option. It cannot be
321              used when the output  is  not  seekable  (e.g.  stdout).  It  is
322              ignored  if the output file is /dev/null .  Note that this util‐
323              ity does not remove the OFILE prior to starting to write to  it.
324              Hence  it may be advantageous to manually remove the OFILE if it
325              is large prior to using oflag=sparse. The last segment is always
326              written  so  regular files will show the same length and so pro‐
327              grams like md5sum and  sha1sum  will  generate  the  same  value
328              regardless  of whether oflag=sparse is given or not. This option
329              may be used when the OFILE is a raw device but is probably  only
330              useful if the device is known to contain zeros (e.g. a SCSI disk
331              after a FORMAT command).
332

RETIRED OPTIONS

334       Here are some retired options that are still present:
335
336       append=0 | 1
337              when set, equivalent to 'oflag=append'. When clear the action is
338              to  overwrite  the  existing  file  (if  it exists); this is the
339              default.  See the 'append' flag.
340
341       fua=0 | 1 | 2 | 3
342              force unit access bit. When 3, fua is  set  on  both  IFILE  and
343              OFILE;  when  2,  fua  is  set  on IFILE;, when 1, fua is set on
344              OFILE; when 0 (default), fua is cleared on both. See  the  'fua'
345              flag.
346

NOTES

348       Block  devices (e.g. /dev/sda and /dev/hda) can be given for IFILE.  If
349       neither '-iflag=direct', 'iflag=sgio' nor 'blk_sgio=1'  is  given  then
350       normal  block  IO involving buffering and caching is performed. If only
351       '-iflag=direct' is given then the buffering  and  caching  is  bypassed
352       (this   is  applicable  to  both  SCSI  devices  and  ATA  disks).   If
353       'iflag=sgio' or 'blk_sgio=1' is given then the SG_IO ioctl is  used  on
354       the  given file causing SCSI commands to be sent to the device and that
355       also bypasses most of the actions performed by the block layer (this is
356       only  applicable  to SCSI devices, not ATA disks). The same applies for
357       block devices given for OFILE.
358
359       Various numeric arguments (e.g. SKIP) may include  multiplicative  suf‐
360       fixes  or  be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
361       in the sg3_utils(8) man page.
362
363       The COUNT, SKIP and SEEK arguments can take 64 bit  values  (i.e.  very
364       big  numbers).  Other values are limited to what can fit in a signed 32
365       bit number.
366
367       Data usually gets to the user space in a 2  stage  process:  first  the
368       SCSI  adapter  DMAs  into  kernel buffers and then the sg driver copies
369       this data into user memory (write operations  reverse  this  sequence).
370       This  is  called  "indirect  IO"  and there is a 'dio' option to select
371       "direct IO" which will DMA directly  into  user  memory.  Due  to  some
372       issues  "direct IO" is disabled in the sg driver and needs a configura‐
373       tion change to activate it. This is  typically  done  with  'echo  1  >
374       /proc/scsi/sg/allow_dio'.
375
376       All  informative,  warning  and  error output is sent to stderr so that
377       dd's output file can be stdout and remain unpolluted. If no options are
378       given, then the usage message is output and nothing else happens.
379
380       Even  if  READ LONG succeeds on a "bad" block when 'coe=2' (or 'coe=3')
381       is given, the recovered data may not be useful. There are no guarantees
382       that the user data will appear "as is" in the first 512 bytes.
383
384       A raw device must be bound to a block device prior to using sg_dd.  See
385       raw(8) for more information about binding raw devices. To be safe,  the
386       sg  device  mapping  to  SCSI block devices should be checked with 'cat
387       /proc/scsi/scsi', or sg_map before use.
388
389       Disk partition information can often be found with fdisk(8) [the  "-ul"
390       argument is useful in this respect].
391
392       For  sg devices (and block devices when blk_sgio=1 is given) this util‐
393       ity issues SCSI READ and WRITE (SBC) commands which are appropriate for
394       disks  and reading from CD/DVD/HD-DVD/BD drives. Those commands are not
395       formatted correctly for tape devices so sg_dd should  not  be  used  on
396       tape  devices.  If  the largest block address of the requested transfer
397       exceeds a 32 bit block number (i.e 0xffff) then a warning is issued and
398       the sg device is accessed via SCSI READ(16) and WRITE(16) commands.
399
400       The   attributes  of  a  block  device  (partition)  are  ignored  when
401       'blk_sgio=1' is used. Hence the whole device is read (rather than  just
402       the second partition) by this invocation:
403
404          sg_dd if=/dev/sdb2 blk_sgio=1 of=t bs=512
405

EXAMPLES

407       Looks quite similar in usage to dd:
408
409          sg_dd if=/dev/sg0 of=t bs=512 count=1MB
410
411       This  will  copy  1  million 512 byte blocks from the device associated
412       with /dev/sg0 (which should have 512 byte blocks) to a file  called  t.
413       Assuming  /dev/sda  and  /dev/sg0 are the same device then the above is
414       equivalent to:
415
416          dd if=/dev/sda iflag=direct of=t bs=512 count=1000000
417
418       although dd's speed may improve if bs was larger and count was suitably
419       reduced.  The  use  of the 'iflag=direct' option bypasses the buffering
420       and caching that is usually done on a block device.
421
422       Using a raw device to do something similar on a ATA disk:
423
424          raw /dev/raw/raw1 /dev/hda
425          sg_dd if=/dev/raw/raw1 of=t bs=512 count=1MB
426
427       To copy a SCSI disk partition to an ATA disk partition:
428
429          raw /dev/raw/raw2 /dev/hda3
430          sg_dd if=/dev/sg0 skip=10123456 of=/dev/raw/raw2 bs=512
431
432       This assumes a valid partition is found on the SCSI disk at  the  given
433       skip block address (past the 5 GB point of that disk) and that the par‐
434       tition goes to the end of the SCSI disk. An explicit count is  probably
435       a safer option. The partition is copied to /dev/hda3 which is an offset
436       into the ATA disk /dev/hda . The  exact  number  of  blocks  read  from
437       /dev/sg0 are written to /dev/hda (i.e. no padding).
438
439       To  time  a  streaming read of the first 1 GB (2 ** 30 bytes) on a disk
440       this utility could be used:
441
442          sg_dd if=/dev/sg0 of=/dev/null bs=512 count=2m time=1
443
444       On completion this will output a line like: "time to transfer data  was
445       18.779506  secs,  57.18 MB/sec". The "MB/sec" in this case is 1,000,000
446       bytes per second.
447
448       The 'of2=' option can be used to copy data and  take  a  md5sum  of  it
449       without needing to re-read the data:
450
451         mkfifo fif
452         md5sum fif &
453         sg_dd if=/dev/sg3 iflag=coe of=sg3.img oflag=sparse of2=fif bs=512
454
455       This  will  image  /dev/sg3 (e.g. an unmounted disk) and place the con‐
456       tents in the (sparse) file sg3.img . Without  re-reading  the  data  it
457       will also perform a md5sum calculation on the image.
458

SIGNALS

460       The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIG‐
461       PIPE output the number of remaining blocks to be  transferred  and  the
462       records  in + out counts; then they have their default action.  SIGUSR1
463       causes the same information to be output yet the copy  continues.   All
464       output caused by signals is sent to stderr.
465

EXIT STATUS

467       The  exit status of sg_dd is 0 when it is successful. Otherwise see the
468       sg3_utils(8) man page. Since this utility works at a higher level  than
469       individual  commands, and there are 'coe' and 'retries' flags, individ‐
470       ual SCSI command failures do not necessary cause the process to exit.
471
472       An additional exit status of 90 is generated if the flock flag is given
473       and some other process holds the advisory exclusive lock.
474

AUTHORS

476       Written by Douglas Gilbert and Peter Allworth.
477

REPORTING BUGS

479       Report bugs to <dgilbert at interlog dot com>.
480
482       Copyright © 2000-2013 Douglas Gilbert
483       This  software is distributed under the GPL version 2. There is NO war‐
484       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
485       POSE.
486

SEE ALSO

488       There      is      a      web      page     discussing     sg_dd     at
489       http://sg.danny.cz/sg/sg_dd.html
490
491       A POSIX threads version  of  this  utility  called  sgp_dd  is  in  the
492       sg3_utils  package.  Another version from that package is called sgm_dd
493       and it uses memory mapped IO to speed transfers from sg devices.
494
495       The lmbench package contains lmdd which is also interesting. For moving
496       data  to  and  from  tapes  see  dt  which is found at http://www.scsi
497       faq.org/RMiller_Tools/index.html
498
499       To change mode parameters that effect a SCSI device's caching and error
500       recovery see sdparm(sdparm)
501
502       To verify the data on the media or to verify it against some other copy
503       of the data see sg_verify(sg3_utils)
504
505       See also raw(8), dd(1), ddrescue(GNU), ddpt
506
507
508
509sg3_utils-1.37                     June 2013                          SG_DD(8)
Impressum