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

NAME

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

SYNOPSIS

10       sgm_dd [bs=BS] [count=COUNT] [ibs=BS] [if=IFILE] [iflag=FLAGS] [obs=BS]
11       [of=OFILE] [oflag=FLAGS] [seek=SEEK] [skip=SKIP] [--help] [--version]
12
13       [bpt=BPT]  [cdbsz=6|10|12|16]  [dio=0|1]  [sync=0|1]  [time=0|1]  [ver‐
14       bose=VERB]
15

DESCRIPTION

17       Copy data to and from any files. Specialized for "files" that are Linux
18       SCSI generic (sg) devices and raw devices. Uses memory mapped transfers
19       on sg devices. Similar syntax and semantics to dd(1) but does not  per‐
20       form any conversions.
21
22       Will  only perform memory mapped transfers when IFILE or OFILE are SCSI
23       generic (sg) devices.
24
25       If both IFILE and OFILE are sg devices then memory mapped transfers are
26       performed on IFILE. If no other flags are specified then indirect IO is
27       performed on OFILE. If 'oflag=dio' is given then direct IO is attempted
28       on OFILE. If 'oflag=smmap' is given then shared mmap-ed IO (sharing the
29       mmap-ed reserve buffer associated with IFILE)  is  attempted.  In  both
30       latter  cases  if the faster IO option is not available, they fall back
31       to indirect IO and report this at the end of the copy.
32
33       The first group in the synopsis above are "standard" Unix  dd(1)  oper‐
34       ands.  The  second group are extra options added by this utility.  Both
35       groups are defined below.
36

OPTIONS

38       bpt=BPT
39              each IO transaction will be made using BPT blocks  (or  less  if
40              near  the  end of the copy). Default is 128 for block sizes less
41              that 2048 bytes, otherwise the default is 32. So for bs=512  the
42              reads  and  writes  will  each  convey 64 KiB of data by default
43              (less if near the end of the transfer or  memory  restrictions).
44              When  cd/dvd  drives  are  accessed, the block size is typically
45              2048 bytes and bpt defaults to 32 which  again  implies  64  KiB
46              transfers.
47
48       bs=BS  where  BS  must  be  the block size of the physical device. Note
49              that this differs from dd(1) which permits BS to be an  integral
50              multiple.  Default is 512 which is usually correct for disks but
51              incorrect for cdroms (which normally have 2048 byte blocks). For
52              this utility the maximum size of each individual IO operation is
53              BS * BPT bytes.
54
55       cdbsz=6 | 10 | 12 | 16
56              size of SCSI READ and/or WRITE  commands  issued  on  sg  device
57              names.   Default is 10 byte SCSI command blocks (unless calcula‐
58              tions indicate that a 4 byte block number may  be  exceeded,  in
59              which case it defaults to 16 byte SCSI commands).
60
61       count=COUNT
62              copy  COUNT  blocks  from IFILE to OFILE. Default is the minimum
63              (of IFILE and OFILE) number of blocks  that  sg  devices  report
64              from SCSI READ CAPACITY commands or that block devices (or their
65              partitions) report. Normal files are not probed for their  size.
66              If  skip=SKIP  or  skip=SEEK  are given and the count is derived
67              (i.e.  not explicitly given) then the derived  count  is  scaled
68              back  so  that the copy will not overrun the device. If the file
69              name is a block device partition and COUNT is not given then the
70              size  of  the partition rather than the size of the whole device
71              is used. If COUNT is not given and cannot  be  derived  then  an
72              error message is issued and no copy takes place.
73
74       dio=0 | 1
75              permits  direct  IO  to  be  selected on the write-side (i.e. on
76              OFILE).  Only allowed when the read-side (i.e. IFILE)  is  a  sg
77              device.  When  1  there  may be a "zero copy" copy (i.e. mmap-ed
78              transfer on the read into the user  space  and  direct  IO  from
79              there  on  the  write,  potentially two DMAs and no data copying
80              from the CPU). Default is 0.  The same action as 'dio=1' is also
81              available with 'oflag=dio'.
82
83       ibs=BS if given must be the same as BS given to 'bs=' option.
84
85       if=IFILE
86              read  from IFILE instead of stdin. If IFILE is '-' then stdin is
87              read. Starts reading at the beginning of IFILE  unless  SKIP  is
88              given.
89
90       iflag=FLAGS
91              where  FLAGS is a comma separated list of one or more flags out‐
92              lined below.  These flags are  associated  with  IFILE  and  are
93              ignored when IFILE is stdin.
94
95       obs=BS if given must be the same as BS given to 'bs=' option.
96
97       of=OFILE
98              write to OFILE instead of stdout. If OFILE is '-' then writes to
99              stdout. If OFILE is /dev/null then no  actual  writes  are  per‐
100              formed.   If  OFILE  is '.' (period) then it is treated the same
101              way as /dev/null (this is a shorthand notation). If OFILE exists
102              then  it is _not_ truncated; it is overwritten from the start of
103              OFILE unless 'oflag=append' or SEEK is given.
104
105       oflag=FLAGS
106              where FLAGS is a comma separated list of one or more flags  out‐
107              lined  below.   These  flags  are  associated with OFILE and are
108              ignored when OFILE is /dev/null, '.' (period), or stdout.
109
110       seek=SEEK
111              start writing SEEK bs-sized blocks  from  the  start  of  OFILE.
112              Default is block 0 (i.e. start of file).
113
114       skip=SKIP
115              start  reading  SKIP  bs-sized  blocks  from the start of IFILE.
116              Default is block 0 (i.e. start of file).
117
118       sync=0 | 1
119              when 1, does SYNCHRONIZE CACHE command on OFILE at  the  end  of
120              the transfer. Only active when OFILE is a sg device file name.
121
122       time=0 | 1
123              when  1,  times  transfer  and does throughput calculation, out‐
124              putting the results (to stderr) at completion. When 0  (default)
125              doesn't perform timing.
126
127       verbose=VERB
128              as  VERB  increases  so  does the amount of debug output sent to
129              stderr.  Default value is zero which yields the  minimum  amount
130              of debug output.  A value of 1 reports extra information that is
131              not repetitive. A value 2 reports cdbs and  responses  for  SCSI
132              commands  that  are  not  repetitive  (i.e.  other that READ and
133              WRITE). Error processing is not considered repetitive. Values of
134              3  and 4 yield output for all SCSI commands (and Unix read() and
135              write() calls) so there can be a lot of output.
136
137       --help outputs usage message and exits.
138
139       --version
140              outputs version number information and exits.
141

FLAGS

143       Here is a list of flags and their meanings:
144
145       append causes the O_APPEND flag to be added to the open of  OFILE.  For
146              normal  files  this will lead to data appended to the end of any
147              existing data.  Cannot  be  used  together  with  the  seek=SEEK
148              option  as they conflict.  The default action of this utility is
149              to overwrite any existing data from the beginning  of  the  file
150              or, if SEEK is given, starting at block SEEK. Note that attempt‐
151              ing to 'append' to a device file (e.g.  a disk) will usually  be
152              ignored or may cause an error to be reported.
153
154       dio    is  only  active  with  oflag  (i.e. 'oflag=dio'). Its action is
155              described in the 'dio=1' option description above.
156
157       direct causes the O_DIRECT flag to be added to the open of IFILE and/or
158              OFILE.  This  flag  requires  some memory alignment on IO. Hence
159              user memory buffers are aligned to the page size. Has no  effect
160              on sg, normal or raw files.
161
162       dpo    set  the  DPO bit (disable page out) in SCSI READ and WRITE com‐
163              mands. Not supported for 6 byte cdb variants of READ and  WRITE.
164              Indicates that data is unlikely to be required to stay in device
165              (e.g. disk) cache.  May speed media copy and/or  cause  a  media
166              copy to have less impact on other device users.
167
168       dsync  causes  the  O_SYNC flag to be added to the open of IFILE and/or
169              OFILE.  The  "d"  is  prepended  to  lower  confusion  with  the
170              'sync=0|1'  option which has another action (i.e. a synchronisa‐
171              tion to media at the end of the transfer).
172
173       excl   causes the O_EXCL flag to be added to the open of  IFILE  and/or
174              OFILE.
175
176       fua    causes  the  FUA  (force unit access) bit to be set in SCSI READ
177              and/or WRITE commands. This only has effect with sg devices. The
178              6  byte variants of the SCSI READ and WRITE commands do not sup‐
179              port the FUA bit.  Only active for sg device file names.
180
181       null   has no affect, just a placeholder.
182
183       smmap  is only active for oflag. It sets shared mmap IO usage on  OFILE
184              if  it  is  a  sg  device  node. The IFILE also needs to be a sg
185              device node (or there is no mmap-ed reserve buffer to share).
186

RETIRED OPTIONS

188       Here are some retired options that are still present:
189
190       fua=0 | 1 | 2 | 3
191              force unit access bit. When 3, fua is  set  on  both  IFILE  and
192              OFILE; when 2, fua is set on IFILE; when 1, fua is set on OFILE;
193              when 0 (default), fua is cleared on both. See the 'fua' flag.
194

NOTES

196       A raw device must be bound to a block device  prior  to  using  sgm_dd.
197       See  raw(8) for more information about binding raw devices. To be safe,
198       the sg device mapping to SCSI block devices should be checked with 'cat
199       /proc/scsi/scsi' before use.
200
201       Raw  device partition information can often be found with fdisk(8) [the
202       "-ul" argument is useful in this respect].
203
204       Various numeric arguments (e.g. SKIP) may include  multiplicative  suf‐
205       fixes  or  be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
206       in the sg3_utils(8) man page.
207
208       The count, skip and seek parameters can take 64 bit values  (i.e.  very
209       big  numbers).  Other values are limited to what can fit in a signed 32
210       bit number.
211
212       Data usually gets to the user space in a 2  stage  process:  first  the
213       SCSI  adapter  DMAs  into  kernel buffers and then the sg driver copies
214       this data into user memory (write operations  reverse  this  sequence).
215       With  memory  mapped transfers a kernel buffer reserved by sg is memory
216       mapped (see the mmap(2) system call) into the user space. When this  is
217       done  the  second (redundant) copy from kernel buffers to user space is
218       not needed. Hence the transfer is faster and requires less "grunt" from
219       the CPU.
220
221       All  informative,  warning  and  error output is sent to stderr so that
222       dd's output file can be stdout and remain unpolluted. If no options are
223       given, then the usage message is output and nothing else happens.
224
225       For  sg  devices this utility issues SCSI READ and WRITE (SBC) commands
226       which are appropriate for disks  and  reading  from  CD/DVD/BD  drives.
227       Those  commands  are not formatted correctly for tape devices so sgm_dd
228       should not be used on tape devices.
229
230       This utility stops the copy if  any  error  is  encountered.  For  more
231       advanced  "copy  on  error"  logic see the sg_dd utility (and its 'coe'
232       flag).
233

EXAMPLES

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

SIGNALS

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

EXIT STATUS

245       The exit status of sgm_dd is 0 when it is successful. Otherwise see the
246       sg3_utils(8)  man page. Since this utility works at a higher level than
247       individual commands, and there are 'coe' and 'retries' flags,  individ‐
248       ual SCSI command failures do not necessary cause the process to exit.
249

AUTHORS

251       Written by Douglas Gilbert and Peter Allworth.
252

REPORTING BUGS

254       Report bugs to <dgilbert at interlog dot com>.
255
257       Copyright © 2000-2012 Douglas Gilbert
258       This  software is distributed under the GPL version 2. There is NO war‐
259       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
260       POSE.
261

SEE ALSO

263       The  simplest variant of this utility is called sg_dd.  A POSIX threads
264       version of this utility called sgp_dd is in the sg3_utils package.  The
265       lmbench package contains lmdd which is also interesting.  raw(8), dd(1)
266
267
268
269sg3_utils-1.35                   November 2019                       SGM_DD(8)
Impressum