Print this page
10911 dd: add input flag fullblock


  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
  45 .\" Portions Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved
  46 .\" Copyright (c) 2014, Joyent, Inc.  All rights Reserved.
  47 .\" Copyright (c) 2014 by Delphix. All rights reserved.
  48 .\"
  49 .TH DD 1M "Dec 12, 2014"
  50 .SH NAME
  51 dd \- convert and copy a file
  52 .SH SYNOPSIS
  53 .LP
  54 .nf
  55 \fB/usr/bin/dd\fR [\fIoperand=value\fR]...
  56 .fi
  57 
  58 .SH DESCRIPTION
  59 .LP
  60 The \fBdd\fR utility copies the specified input file to the specified output
  61 with possible conversions. The standard input and output are used by default.



  62 The input and output block sizes may be specified to take advantage of raw
  63 physical I/O. Sizes are specified in bytes; a number may end with \fBk\fR,
  64 \fBb\fR, or \fBw\fR to specify multiplication by 1024, 512, or 2, respectively.
  65 Numbers may also be separated by \fBx\fR to indicate multiplication.
  66 .sp
  67 .LP
  68 The \fBdd\fR utility reads the input one block at a time, using the specified
  69 input block size. \fBdd\fR then processes the block of data actually returned,
  70 which could be smaller than the requested block size. \fBdd\fR applies any
  71 conversions that have been specified and writes the resulting data to the
  72 output in blocks of the specified output block size.
  73 .sp
  74 .LP
  75 \fBcbs\fR is used only if \fBascii\fR, \fBasciib\fR, \fBunblock\fR,
  76 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, \fBibmb\fR, or \fBblock\fR conversion
  77 is specified. In the first two cases, \fBcbs\fR characters are copied into the
  78 conversion buffer, any specified character mapping is done, trailing blanks are
  79 trimmed, and a \fBNEWLINE\fR is added before sending the line to output. In the
  80 last three cases, characters up to \fBNEWLINE\fR are read into the conversion
  81 buffer and blanks are added to make up an output record of size \fBcbs\fR.
  82 \fBASCII\fR files are presumed to contain \fBNEWLINE\fR characters. If
  83 \fBcbs\fR is unspecified or \fB0\fR, the \fBascii\fR, \fBasciib\fR,
  84 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, and \fBibmb\fR options convert the
  85 character set without changing the input file's block structure. The
  86 \fBunblock\fR and \fBblock\fR options become a simple file copy.
  87 .sp
  88 .LP
  89 After completion, \fBdd\fR reports the number of whole and partial input and
  90 output blocks.
  91 .SH OPERANDS
  92 .LP













































  93 The following operands are supported:
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBif=\fR\fIfile\fR\fR
  98 .ad
  99 .sp .6
 100 .RS 4n
 101 Specifies the input path. Standard input is the default.
 102 .RE
 103 
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBof=\fR\fIfile\fR\fR
 108 .ad
 109 .sp .6
 110 .RS 4n
 111 Specifies the output path. Standard output is the default. If the
 112 \fBseek=\fR\fBexpr\fR conversion is not also specified, the output file will be
 113 truncated before the copy begins, unless \fBconv=notrunc\fR is specified. If
 114 \fBseek=\fR\fBexpr\fR is specified, but \fBconv=notrunc\fR is not, the effect
 115 of the copy will be to preserve the blocks in the output file over which
 116 \fBdd\fR seeks, but no other portion of the output file will be preserved. (If
 117 the size of the seek plus the size of the input file is less than the previous
 118 size of the output file, the output file is shortened by the copy.)
 119 .RE
 120 
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBibs=\fR\fIn\fR\fR
 125 .ad
 126 .sp .6
 127 .RS 4n
 128 Specifies the input block size in \fIn\fR bytes (default is \fB512\fR).
 129 .RE
 130 
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBobs=\fR\fIn\fR\fR
 135 .ad
 136 .sp .6
 137 .RS 4n
 138 Specifies the output block size in \fIn\fR bytes (default is \fB512\fR).
 139 .RE
 140 
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fBbs=\fR\fIn\fR\fR
 145 .ad
 146 .sp .6
 147 .RS 4n
 148 Sets both input and output block sizes to \fIn\fR bytes, superseding \fBibs=\fR
 149 and \fBobs=\fR. If no conversion other than \fBsync\fR,\fB noerror\fR, and
 150 \fBnotrunc\fR is specified, each input block is copied to the output as a
 151 single block without aggregating short blocks.
 152 .RE
 153 
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBcbs=\fR\fIn\fR\fR
 158 .ad
 159 .sp .6
 160 .RS 4n
 161 Specifies the conversion block size for \fBblock\fR and \fBunblock\fR in bytes
 162 by \fIn\fR (default is \fB0\fR). If \fBcbs=\fR is omitted or given a value of
 163 \fB0\fR, using \fBblock\fR or \fBunblock\fR produces unspecified results.
 164 .sp
 165 This option is used only if \fBASCII\fR or \fBEBCDIC\fR conversion is
 166 specified. For the \fBascii\fR and \fBasciib\fR operands, the input is handled
 167 as described for the \fBunblock\fR operand except that characters are converted
 168 to \fBASCII\fR before the trailing \fBSPACE\fR characters are deleted. For the
 169 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, and \fBibmb\fR operands, the input is
 170 handled as described for the \fBblock\fR operand except that the characters are
 171 converted to \fBEBCDIC\fR or IBM \fBEBCDIC\fR after the trailing \fBSPACE\fR






























 172 characters are added.
 173 .RE
 174 
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBfiles=\fR\fIn\fR\fR
 179 .ad
 180 .sp .6
 181 .RS 4n
 182 Copies and concatenates \fIn\fR input files before terminating (makes sense
 183 only where input is a magnetic tape or similar device).
 184 .RE
 185 
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBskip=\fR\fIn\fR\fR
 190 .ad
 191 .sp .6
 192 .RS 4n
 193 Skips \fIn\fR input blocks (using the specified input block size) before
 194 starting to copy. On seekable files, the implementation reads the blocks or
 195 seeks past them. On non-seekable files, the blocks are read and the data is
 196 discarded.
 197 .RE
 198 
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBiseek=\fR\fIn\fR\fR
 203 .ad
 204 .sp .6
 205 .RS 4n
 206 Seeks \fIn\fR blocks from beginning of input file before copying (appropriate
 207 for disk files, where \fBskip\fR can be incredibly slow).
 208 .RE
 209 
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fBoseek=\fR\fIn\fR\fR
 214 .ad
 215 .sp .6
 216 .RS 4n
 217 Seeks \fIn\fR blocks from beginning of output file before copying.
 218 .RE
 219 
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fBseek=\fR\fIn\fR\fR
 224 .ad
 225 .sp .6
 226 .RS 4n
 227 Skips \fIn\fR blocks (using the specified output block size) from beginning of
 228 output file before copying. On non-seekable files, existing blocks are read and
 229 space from the current end-of-file to the specified offset, if any, is filled
 230 with null bytes. On seekable files, the implementation seeks to the specified
 231 offset or reads the blocks as described for non-seekable files.
 232 .RE
 233 












































 234 .sp
 235 .ne 2
 236 .na
 237 \fB\fBostride=\fR\fIn\fR\fR
 238 .ad
 239 .sp .6
 240 .RS 4n
 241 Writes every \fIn\fRth block (using the specified output block size) when
 242 writing output.  Skips \fIn\fR - 1 blocks after writing each record.
 243 .RE
 244 
 245 .sp
 246 .ne 2
 247 .na
 248 \fB\fBistride=\fR\fIn\fR\fR
 249 .ad
 250 .sp .6
 251 .RS 4n
 252 Reads every \fIn\fRth block (using the specified input block size) when
 253 reading input.  Skips \fIn\fR - 1 blocks after reading each record.
 254 .RE
 255 
 256 .sp
 257 .ne 2
 258 .na
 259 \fB\fBstride=\fR\fIn\fR\fR
 260 .ad
 261 .sp .6
 262 .RS 4n
 263 Reads every \fIn\fRth block (using the specified input block size) when
 264 reading input.  Skips \fIn\fR - 1 blocks after reading each record.  Also
 265 writes every \fIn\fRth block (using the specified output block size) when
 266 writing output.  Skips \fIn\fR - 1 blocks after writing each record.
 267 .RE
 268 
 269 .sp
 270 .ne 2
 271 .na
 272 \fB\fBcount=\fR\fIn\fR\fR
 273 .ad
 274 .sp .6
 275 .RS 4n
 276 Copies only \fIn\fR input blocks.
 277 .RE
 278 
 279 .sp
 280 .ne 2
 281 .na
 282 \fB\fBconv=\fR\fIvalue\fR[\fB,\fR\fIvalue\fR.\|.\|.\|]\fR
 283 .ad
 284 .sp .6
 285 .RS 4n
 286 Where \fIvalue\fRs are comma-separated symbols from the following list:
 287 .sp
 288 .ne 2
 289 .na
 290 \fB\fBascii\fR\fR
 291 .ad
 292 .RS 11n
 293 Converts \fBEBCDIC\fR to \fBASCII\fR.
 294 .RE
 295 
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fBasciib\fR\fR
 300 .ad
 301 .RS 11n
 302 Converts \fBEBCDIC\fR to \fBASCII\fR using \fBBSD\fR-compatible character
 303 translations.
 304 .RE
 305 
 306 .sp
 307 .ne 2
 308 .na
 309 \fB\fBebcdic\fR\fR
 310 .ad
 311 .RS 11n
 312 Converts \fBASCII\fR to \fBEBCDIC\fR. If converting fixed-length \fBASCII\fR
 313 records without NEWLINEs, sets up a pipeline with \fBdd conv=unblock\fR
 314 beforehand.
 315 .RE
 316 
 317 .sp
 318 .ne 2
 319 .na
 320 \fB\fBebcdicb\fR\fR





























































































































































 321 .ad
 322 .RS 11n
 323 Converts \fBASCII\fR to \fBEBCDIC\fR using \fBBSD\fR-compatible character
 324 translations. If converting fixed-length \fBASCII\fR records without
 325 \fBNEWLINE\fRs, sets up a pipeline with \fBdd conv=unblock\fR beforehand.
 326 .RE
 327 
 328 .sp
 329 .ne 2
 330 .na
 331 \fB\fBibm\fR\fR
 332 .ad
 333 .RS 11n
 334 Slightly different map of \fBASCII\fR to \fBEBCDIC\fR. If converting
 335 fixed-length \fBASCII\fR records without \fBNEWLINE\fRs, sets up a pipeline
 336 with \fBdd conv=unblock\fR beforehand.
 337 .RE
 338 
 339 .sp
 340 .ne 2
 341 .na
 342 \fB\fBibmb\fR\fR
 343 .ad
 344 .RS 11n
 345 Slightly different map of \fBASCII\fR to \fBEBCDIC\fR using
 346 \fBBSD\fR-compatible character translations. If converting fixed-length
 347 \fBASCII\fR records without \fBNEWLINE\fRs, sets up a pipeline with \fBdd
 348 conv=unblock\fR beforehand.
 349 .RE
 350 
 351 The \fBascii\fR (or \fBasciib\fR), \fBebcdic\fR (or \fBebcdicb\fR), and
 352 \fBibm\fR (or \fBibmb\fR) values are mutually exclusive.
 353 .sp
 354 .ne 2
 355 .na
 356 \fB\fBblock\fR\fR
 357 .ad
 358 .RS 11n
 359 Treats the input as a sequence of \fBNEWLINE\fR-terminated or
 360 \fBEOF\fR-terminated variable-length records independent of the input block
 361 boundaries. Each record is converted to a record with a fixed length specified
 362 by the conversion block size. Any \fBNEWLINE\fR character is removed from the
 363 input line. \fBSPACE\fR characters are appended to lines that are shorter than
 364 their conversion block size to fill the block. Lines that are longer than the
 365 conversion block size are truncated to the largest number of characters that
 366 will fit into that size. The number of truncated lines is reported.
 367 .RE
 368 
 369 .sp
 370 .ne 2
 371 .na
 372 \fB\fBunblock\fR\fR
 373 .ad
 374 .RS 11n
 375 Converts fixed-length records to variable length. Reads a number of bytes equal
 376 to the conversion block size (or the number of bytes remaining in the input, if
 377 less than the conversion block size), delete all trailing \fBSPACE\fR
 378 characters, and append a \fBNEWLINE\fR character.
 379 .RE
 380 
 381 The  \fBblock\fR and \fBunblock\fR values are mutually exclusive.
 382 .sp
 383 .ne 2
 384 .na
 385 \fB\fBlcase\fR\fR
 386 .ad
 387 .RS 9n
 388 Maps upper-case characters specified by the \fBLC_CTYPE\fR keyword
 389 \fBtolower\fR to the corresponding lower-case character. Characters for which
 390 no mapping is specified are not modified by this conversion.
 391 .RE
 392 
 393 .sp
 394 .ne 2
 395 .na
 396 \fB\fBucase\fR\fR
 397 .ad
 398 .RS 9n
 399 Maps lower-case characters specified by the \fBLC_CTYPE\fR keyword
 400 \fBtoupper\fR to the corresponding upper-case character. Characters for which
 401 no mapping is specified are not modified by this conversion.
 402 .RE
 403 
 404 The \fBlcase\fR and \fBucase\fR symbols are mutually exclusive.
 405 .sp
 406 .ne 2
 407 .na
 408 \fB\fBswab\fR\fR
 409 .ad
 410 .RS 11n
 411 Swaps every pair of input bytes. If the current input record is an odd number
 412 of bytes, the last byte in the input record is ignored.
 413 .RE
 414 
 415 .sp
 416 .ne 2
 417 .na
 418 \fB\fBnoerror\fR\fR
 419 .ad
 420 .RS 11n
 421 Does not stop processing on an input error. When an input error occurs, a
 422 diagnostic message is written on standard error, followed by the current input
 423 and output block counts in the same format as used at completion. If the
 424 \fBsync\fR conversion is specified, the missing input is replaced with null
 425 bytes and processed normally. Otherwise, the input block will be omitted from
 426 the output.
 427 .RE
 428 
 429 .sp
 430 .ne 2
 431 .na
 432 \fB\fBnotrunc\fR\fR
 433 .ad
 434 .RS 11n
 435 Does not truncate the output file. Preserves blocks in the output file not
 436 explicitly written by this invocation of \fBdd\fR. (See also the preceding
 437 \fBof=\fR\fIfile\fR operand.)
 438 .RE
 439 
 440 .sp
 441 .ne 2
 442 .na
 443 \fB\fBsync\fR\fR
 444 .ad
 445 .RS 11n
 446 Pads every input block to the size of the \fBibs=\fR buffer, appending null
 447 bytes. (If either \fBblock\fR or \fBunblock\fR is also specified, appends
 448 \fBSPACE\fR characters, rather than null bytes.)
 449 .RE
 450 
 451 .RE
 452 
 453 .sp
 454 .ne 2
 455 .na
 456 \fB\fBoflag=\fR\fIvalue\fR[\fB,\fR\fIvalue\fR.\|.\|.\|]\fR
 457 .ad
 458 .sp .6
 459 Where \fIvalue\fRs are comma-separated symbols from the following list which


 460 affect the behavior of writing the output file:
 461 .sp
 462 .ne 2
 463 .na
 464 \fB\fBdsync\fR\fR
 465 .ad
 466 .RS 11n
 467 The output file is opened with the \fBO_DSYNC\fR flag set. All data writes will
 468 be synchronous. For more information on \fBO_DSYNC\fR see \fBfcntl.h\fR(3HEAD).
 469 .RE
 470 
 471 .sp
 472 .ne 2
 473 .na
 474 \fB\fBsync\fR\fR
 475 .ad
 476 .RS 11n
 477 The output file is opened with the \fBO_SYNC\fR flag set. All data and metadata
 478 writes will be synchronous. For more information on \fBO_SYNC\fR see
 479 \fBfcntl.h\fR(3HEAD).
 480 .RE
 481 
 482 .sp
 483 .LP
 484 If operands other than \fBconv=\fR and \fBoflag=\fR are specified more than once,
 485 the last specified \fBoperand=\fR\fIvalue\fR is used.
 486 .sp
 487 .LP
 488 For the \fBbs=\fR, \fBcbs=\fR, \fBibs=\fR, and \fBobs=\fR operands, the
 489 application must supply an expression specifying a size in bytes. The
 490 expression, \fBexpr\fR, can be:
 491 .RS +4
 492 .TP
 493 1.








 494 a positive decimal number
 495 .RE
 496 .RS +4
 497 .TP
 498 2.
 499 a positive decimal number followed by \fBk\fR, specifying multiplication by
 500 1024
 501 .RE
 502 .RS +4
 503 .TP
 504 3.
 505 a positive decimal number followed by \fBM\fR, specifying multiplication by
 506 1024*1024
 507 .RE
 508 .RS +4
 509 .TP
 510 4.
 511 a positive decimal number followed by \fBG\fR, specifying multiplication by
 512 1024*1024*1024
 513 .RE
 514 .RS +4
 515 .TP
 516 5.
 517 a positive decimal number followed by \fBT\fR, specifying multiplication by
 518 1024*1024*1024*1024
 519 .RE
 520 .RS +4
 521 .TP
 522 6.
 523 a positive decimal number followed by \fBP\fR, specifying multiplication by
 524 1024*1024*1024*1024*1024
 525 .RE
 526 .RS +4
 527 .TP
 528 7.
 529 a positive decimal number followed by \fBE\fR, specifying multiplication by
 530 1024*1024*1024*1024*1024*1024
 531 .RE
 532 .RS +4
 533 .TP
 534 8.
 535 a positive decimal number followed by \fBZ\fR, specifying multiplication by
 536 1024*1024*1024*1024*1024*1024*1024
 537 .RE
 538 .RS +4
 539 .TP
 540 9.
 541 a positive decimal number followed by \fBb\fR, specifying multiplication by
 542 512
 543 .RE
 544 .RS +4
 545 .TP
 546 10.
 547 two or more positive decimal numbers (with or without \fBk\fR or \fBb\fR)
 548 separated by \fBx\fR, specifying the product of the indicated values.
 549 .RE
 550 .sp
 551 .LP
 552 All of the operands will be processed before any input is read.
 553 .SH SIGNALS
 554 .LP
 555 When \fBdd\fR receives either SIGINFO or SIGUSR1, \fBdd\fR will emit the current
 556 input and output block counts, total bytes written, total time elapsed, and the
 557 number of bytes per second to standard error. This is the same information
 558 format that \fBdd\fR emits when it successfully completes. Users may send
 559 SIGINFO via their terminal. The default character is ^T, see \fBstty\fR(1) for
 560 more information.
 561 .sp
 562 .LP
 563 For \fBSIGINT\fR, \fBdd\fR writes status information to standard error before
 564 exiting. \fBdd\fR takes the standard action for all other signals.
 565 
 566 .SH USAGE
 567 .LP
 568 See \fBlargefile\fR(5) for the description of the behavior of \fBdd\fR when
 569 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
 570 .SH EXAMPLES
 571 .LP
 572 \fBExample 1 \fRCopying from one tape drive to another
 573 .sp
 574 .LP
 575 The following example copies from tape drive \fB0\fR to tape drive \fB1\fR,
 576 using a common historical device naming convention.
 577 
 578 .sp
 579 .in +2
 580 .nf
 581 example% \fBdd if=/dev/rmt/0h  of=/dev/rmt/1h\fR
 582 .fi
 583 .in -2
 584 .sp
 585 
 586 .LP
 587 \fBExample 2 \fRStripping the first 10 bytes from standard input
 588 .sp
 589 .LP
 590 The following example strips the first 10 bytes from standard input:
 591 
 592 .sp
 593 .in +2
 594 .nf
 595 example% \fBdd ibs=10  skip=1\fR
 596 .fi
 597 .in -2
 598 .sp
 599 
 600 .LP
 601 \fBExample 3 \fRReading a tape into an ASCII file
 602 .sp
 603 .LP
 604 This example reads an \fBEBCDIC\fR tape blocked ten 80-byte \fBEBCDIC\fR card
 605 images per block into the \fBASCII\fR file \fBx\fR:
 606 
 607 .sp
 608 .in +2
 609 .nf
 610 example% \fBdd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase\fR
 611 .fi
 612 .in -2
 613 .sp
 614 
 615 .LP
 616 \fBExample 4 \fRUsing conv=sync to write to tape
 617 .sp
 618 .LP
 619 The following example uses \fBconv=sync\fR when writing to a tape:
 620 
 621 .sp
 622 .in +2
 623 .nf
 624 example% \fBtar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync\fR
 625 .fi
 626 .in -2
 627 .sp
 628 
 629 .SH ENVIRONMENT VARIABLES
 630 .LP
 631 See \fBenviron\fR(5) for descriptions of the following environment variables
 632 that affect the execution of \fBdd\fR: \fBLANG\fR, \fBLC_ALL\fR,
 633 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 634 .SH EXIT STATUS
 635 .LP
 636 The following exit values are returned:
 637 .sp
 638 .ne 2
 639 .na
 640 \fB\fB0\fR\fR
 641 .ad
 642 .RS 6n
 643 The input file was copied successfully.
 644 .RE
 645 
 646 .sp
 647 .ne 2
 648 .na
 649 \fB\fB>0\fR\fR
 650 .ad
 651 .RS 6n
 652 An error occurred.
 653 .RE
 654 
 655 .sp
 656 .LP
 657 If an input error is detected and the \fBnoerror\fR conversion has not been
 658 specified, any partial output block will be written to the output file, a
 659 diagnostic message will be written, and the copy operation will be
 660 discontinued. If some other error is detected, a diagnostic message will be
 661 written and the copy operation will be discontinued.
 662 .SH ATTRIBUTES
 663 .LP
 664 See \fBattributes\fR(5) for descriptions of the following attributes:
 665 .sp
 666 
 667 .sp
 668 .TS
 669 box;
 670 c | c
 671 l | l .
 672 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 673 _
 674 Interface Stability     Standard
 675 .TE
 676 
 677 .SH SEE ALSO
 678 .LP
 679 \fBcp\fR(1), \fBsed\fR(1), \fBtr\fR(1), \fBfcntl.h\fR(3HEAD),
 680 \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
 681 .SH DIAGNOSTICS
 682 .ne 2
 683 .na
 684 \fB\fBf+p records in(out)\fR\fR
 685 .ad
 686 .RS 23n














 687 numbers of full and partial blocks read(written)
 688 .RE
 689 
 690 .SH NOTES
 691 .LP
 692 Do not use \fBdd\fR to copy files between file systems having different block
 693 sizes.
 694 .sp
 695 .LP





















 696 Using a  blocked device to copy a file will result in extra nulls being added
 697 to the file to pad the final block to the block boundary.
 698 .sp
 699 .LP
 700 When  \fBdd\fR reads from a pipe, using the  \fBibs=X\fR and  \fBobs=Y\fR
 701 operands, the output will always be blocked in chunks of size Y. When
 702 \fBbs=Z\fR is used, the output blocks will be whatever was available to be read






 703 from the pipe at the time.
 704 .sp
 705 .LP
 706 When using \fBdd\fR to copy files to a tape device, the file size must be a
 707 multiple of the device sector size (for example, 512 Kbyte).  To  copy files of
 708 arbitrary size to a tape device, use  \fBtar\fR(1) or  \fBcpio\fR(1).






  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
  45 .\" Portions Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved
  46 .\" Copyright (c) 2014, Joyent, Inc.  All rights Reserved.
  47 .\" Copyright (c) 2014 by Delphix. All rights reserved.
  48 .\"
  49 .Dd May 4, 2019
  50 .Dt DD 1M
  51 .Os
  52 .Sh NAME
  53 .Nm dd
  54 .Nd convert and copy a file
  55 .Sh SYNOPSIS
  56 .Nm /usr/bin/dd
  57 .Op Ar operand=value
  58 .Ar ...
  59 .Sh DESCRIPTION
  60 The
  61 .Nm dd
  62 utility copies the specified input file to the specified output
  63 with possible conversions.
  64 The standard input and output are used by default.
  65 The input and output block sizes may be specified to take advantage of raw
  66 physical I/O.
  67 Sizes are specified in bytes; a number may end with
  68 .Sy k ,
  69 .Sy b ,
  70 or
  71 .Sy w
  72 to specify multiplication by 1024, 512, or 2, respectively.
  73 Numbers may also be separated by
  74 .Sy x
  75 to indicate multiplication.
  76 .Pp
  77 The
  78 .Nm
  79 utility reads the input one block at a time, using the specified
  80 input block size.
  81 .Nm
  82 then processes the block of data actually returned,
  83 which could be smaller than the requested block size unless the input flag
  84 .Ar fullblock
  85 is used.
  86 .Nm
  87 applies any conversions that have been specified and writes the resulting data
  88 to the output in blocks of the specified output block size.
  89 .Pp
  90 .Sy cbs
  91 is used only if
  92 .Sy ascii ,
  93 .Sy asciib ,
  94 .Sy unblock ,
  95 .Sy ebcdic ,
  96 .Sy ebcdicb ,
  97 .Sy ibm ,
  98 .Sy ibmb ,
  99 or
 100 .Sy block
 101 conversion is specified.
 102 In the first two cases,
 103 .Sy cbs
 104 characters are copied into the conversion buffer, any specified character
 105 mapping is done, trailing blanks are trimmed, and a
 106 .Sy NEWLINE
 107 is added before sending the line to output.
 108 In the last three cases, characters up to
 109 .Sy NEWLINE
 110 are read into the conversion buffer and blanks are added to make up an output
 111 record of size
 112 .Sy cbs .
 113 .Sy ASCII
 114 files are presumed to contain
 115 .Sy NEWLINE
 116 characters.
 117 If
 118 .Sy cbs
 119 is unspecified or
 120 .Sy 0 ,
 121 the
 122 .Sy ascii ,
 123 .Sy asciib ,
 124 .Sy ebcdic ,
 125 .Sy ebcdicb ,
 126 .Sy ibm ,
 127 and
 128 .Sy ibmb
 129 options convert the character set without changing the input file's block
 130 structure.
 131 The
 132 .Sy unblock
 133 and
 134 .Sy block
 135 options become a simple file copy.
 136 .Pp
 137 After completion,
 138 .Nm
 139 reports the number of whole and partial input and output blocks.
 140 .Sh OPERANDS
 141 The following operands are supported:
 142 .Bl -hang
 143 .It Sy if= Ns Ar file
 144 .Pp
 145 Specifies the input path.
 146 Standard input is the default.
 147 .It Sy of= Ns Ar file
 148 .Pp
 149 Specifies the output path.
 150 Standard output is the default.
 151 If the
 152 .Sy seek=expr
 153 conversion is not also specified, the output file will be truncated before
 154 the copy begins, unless
 155 .Sy conv=notrunc
 156 is specified.
 157 If
 158 .Sy seek=expr
 159 is specified, but
 160 .Sy conv=notrunc
 161 is not, the effect of the copy will be to preserve the blocks in the output
 162 file over which
 163 .Nm
 164 seeks, but no other portion of the output file will be preserved.
 165 (If the size of the seek plus the size of the input file is less than the
 166 previous size of the output file, the output file is shortened by the copy.)
 167 .It Sy ibs= Ns Ar n
 168 .Pp
 169 Specifies the input block size in
 170 .Ar n
 171 bytes (default is
 172 .Sy 512 Ns
 173 ).
 174 .It Sy obs= Ns Ar n
 175 .Pp
 176 Specifies the output block size in
 177 .Ar n
 178 bytes (default is
 179 .Sy 512 Ns
 180 ).
 181 .It Sy bs= Ns Ar n
 182 .Pp
 183 Sets both input and output block sizes to
 184 .Ar n
 185 bytes, superseding
 186 .Sy ibs=
 187 and
 188 .Sy obs= .
 189 If no conversion other than
 190 .Sy sync ,
 191 .Sy noerror ,
 192 and
 193 .Sy notrunc
 194 is specified, each input block is copied to the output as a




 195 single block without aggregating short blocks.
 196 .It Sy cbs= Ns Ar n
 197 .Pp
 198 Specifies the conversion block size for
 199 .Sy block
 200 and
 201 .Sy unblock
 202 in bytes by
 203 .Ar n
 204 (default is
 205 .Sy 0 Ns ).
 206 If
 207 .Sy cbs=
 208 is omitted or given a value of
 209 .Sy 0 ,
 210 using
 211 .Sy block
 212 or
 213 .Sy unblock
 214 produces unspecified results.
 215 .Pp
 216 This option is used only if
 217 .Sy ASCII
 218 or
 219 .Sy EBCDIC
 220 conversion is specified.
 221 For the
 222 .Sy ascii
 223 and
 224 .Sy asciib
 225 operands, the input is handled as described for the
 226 .Sy unblock
 227 operand except that characters are converted to
 228 .Sy ASCII
 229 before the trailing
 230 .Sy SPACE
 231 characters are deleted.
 232 For the
 233 .Sy ebcdic ,
 234 .Sy ebcdicb ,
 235 .Sy ibm ,
 236 and
 237 .Sy ibmb
 238 operands, the input is handled as described for the
 239 .Sy block
 240 operand except that the characters are converted to
 241 .Sy EBCDIC
 242 or IBM
 243 .Sy EBCDIC
 244 after the trailing
 245 .Sy SPACE
 246 characters are added.
 247 .It Sy files= Ns Ar n
 248 .Pp
 249 Copies and concatenates
 250 .Ar n
 251 input files before terminating (makes sense





 252 only where input is a magnetic tape or similar device).
 253 .It Sy skip= Ns Ar n
 254 .Pp
 255 Skips
 256 .Ar n
 257 input blocks (using the specified input block size) before starting to copy.
 258 On seekable files, the implementation reads the blocks or seeks past them.
 259 On non-seekable files, the blocks are read and the data is discarded.
 260 .It Sy iseek= Ns Ar n
 261 .Pp
 262 Seeks
 263 .Ar n
 264 blocks from beginning of input file before copying (appropriate
 265 for disk files, where
 266 .Sy skip
 267 can be incredibly slow).
 268 .It Sy oseek= Ns Ar n
 269 .Pp
 270 Seeks
 271 .Ar n
 272 blocks from beginning of output file before copying.
 273 .It Sy seek= Ns Ar n
 274 .Pp
 275 Skips
 276 .Ar n
 277 blocks (using the specified output block size) from beginning of
 278 output file before copying.
 279 On non-seekable files, existing blocks are read and space from the current
 280 end-of-file to the specified offset, if any, is filled with null bytes.
 281 On seekable files, the implementation seeks to the specified


















 282 offset or reads the blocks as described for non-seekable files.
 283 .It Sy ostride= Ns Ar n
 284 .Pp
 285 Writes every
 286 .Ar n Ns
 287 th block (using the specified output block size) when writing output.
 288 Skips
 289 .Ar n
 290 - 1 blocks after writing each record.
 291 .It Sy istride= Ns Ar n
 292 .Pp
 293 Reads every
 294 .Ar n Ns
 295 th block (using the specified input block size) when reading input.
 296 Skips
 297 .Ar n
 298 - 1 blocks after reading each record.
 299 .It Sy stride= Ns Ar n
 300 .Pp
 301 Reads every
 302 .Ar n Ns
 303 th block (using the specified input block size) when reading input.
 304 Skips
 305 .Ar n
 306 - 1 blocks after reading each record.
 307 Also writes every
 308 .Ar n Ns
 309 th block (using the specified output block size) when writing output.
 310 Skips
 311 .Ar n
 312 - 1 blocks after writing each record.
 313 .It Sy count= Ns Ar n
 314 .Pp
 315 Copies only
 316 .Ar n
 317 input blocks.
 318 .It Sy conv= Ns Ar value Ns Op , Ns  Ar value Ns ...
 319 .Pp
 320 Where
 321 .Ar value Ns
 322 s are comma-separated symbols from the following list:
 323 .Bl -hang
 324 .It Sy ascii
 325 Converts
 326 .Sy EBCDIC
 327 to
 328 .Sy ASCII .
 329 .sp
 330 .It Sy asciib
 331 Converts
 332 .Sy EBCDIC
 333 to
 334 .Sy ASCII
 335 using
 336 .Sy BSD Ns
 337 -compatible character translations.
 338 .It Sy ebcdic
 339 Converts
 340 .Sy ASCII
 341 to
 342 .Sy EBCDIC .
 343 If converting fixed-length
 344 .Sy ASCII
 345 records without
 346 .Sy NEWLINE Ns
 347 s, sets up a pipeline with
 348 .Nm
 349 .Sy conv=unblock



























































 350 beforehand.
 351 .It Sy ebcdicb
 352 Converts
 353 .Sy ASCII
 354 to
 355 .Sy EBCDIC
 356 using
 357 .Sy BSD Ns
 358 -compatible character translations.
 359 If converting fixed-length
 360 .Sy ASCII
 361 records without
 362 .Sy NEWLINE Ns
 363 s, sets up a pipeline with
 364 .Nm
 365 .Sy conv=unblock
 366 beforehand.
 367 .It Sy ibm
 368 Slightly different map of
 369 .Sy ASCII
 370 to
 371 .Sy EBCDIC .
 372 If converting fixed-length
 373 .Sy ASCII
 374 records without
 375 .Sy NEWLINE Ns
 376 s, sets up a pipeline with
 377 .Nm
 378 .Sy conv=unblock
 379 beforehand.
 380 .It Sy ibmb
 381 Slightly different map of
 382 .Sy ASCII
 383 to
 384 .Sy EBCDIC
 385 using
 386 .Sy BSD Ns
 387 -compatible character translations.
 388 If converting fixed-length
 389 .Sy ASCII
 390 records without
 391 .Sy NEWLINE Ns
 392 s, sets up a pipeline with
 393 .Nm
 394 .Sy conv=unblock
 395 beforehand.
 396 .El
 397 .Pp
 398 The
 399 .Sy ascii
 400 (or
 401 .Sy asciib ),
 402 .Sy ebcdic
 403 (or
 404 .Sy ebcdicb ),
 405 and
 406 .Sy ibm
 407 (or
 408 .Sy ibmb )
 409 values are mutually exclusive.
 410 .Bl -hang
 411 .It Sy block
 412 Treats the input as a sequence of
 413 .Sy NEWLINE Ns
 414 -terminated or
 415 .Sy EOF Ns
 416 -terminated variable-length records independent of the input block boundaries.
 417 Each record is converted to a record with a fixed length specified
 418 by the conversion block size.
 419 Any
 420 .Sy NEWLINE
 421 character is removed from the input line.
 422 .Sy SPACE
 423 characters are appended to lines that are shorter than their conversion block
 424 size to fill the block.
 425 Lines that are longer than the conversion block size are truncated to the
 426 largest number of characters that will fit into that size.
 427 The number of truncated lines is reported.
 428 .It Sy unblock
 429 Converts fixed-length records to variable length.
 430 Reads a number of bytes equal to the conversion block size (or the number of
 431 bytes remaining in the input, if less than the conversion block size),
 432 delete all trailing
 433 .Sy SPACE
 434 characters, and append a
 435 .Sy NEWLINE
 436 character.
 437 .El
 438 .Pp
 439 The
 440 .Sy block
 441 and
 442 .Sy unblock
 443 values are mutually exclusive.
 444 .Bl -hang
 445 .It Sy lcase
 446 Maps upper-case characters specified by the
 447 .Sy LC_CTYPE
 448 keyword
 449 .Sy tolower
 450 to the corresponding lower-case character.
 451 Characters for which no mapping is specified are not modified by this
 452 conversion.
 453 .It Sy ucase
 454 Maps lower-case characters specified by the
 455 .Sy LC_CTYPE
 456 keyword
 457 .Sy toupper
 458 to the corresponding upper-case character.
 459 Characters for which no mapping is specified are not modified by this
 460 conversion.
 461 .El
 462 .Pp
 463 The
 464 .Sy lcase
 465 and
 466 .Sy ucase
 467 symbols are mutually exclusive.
 468 .Bl -hang
 469 .It Sy swab
 470 Swaps every pair of input bytes.
 471 If the current input record is an odd number of bytes, the last byte in the
 472 input record is ignored.
 473 .It Sy noerror
 474 Does not stop processing on an input error.
 475 When an input error occurs, a diagnostic message is written on standard error,
 476 followed by the current input and output block counts in the same format as
 477 used at completion.
 478 If the
 479 .Sy sync
 480 conversion is specified, the missing input is replaced with null
 481 bytes and processed normally.
 482 Otherwise, the input block will be omitted from the output.
 483 .It Sy notrunc
 484 Does not truncate the output file.
 485 Preserves blocks in the output file not explicitly written by this invocation
 486 of
 487 .Nm .
 488 (See also the preceding
 489 .Sy of= Ns Ar file
 490 operand.)
 491 .It Sy sync
 492 Pads every input block to the size of the
 493 .Sy ibs=
 494 buffer, appending null bytes.
 495 (If either
 496 .Sy block
 497 or
 498 .Sy unblock
 499 is also specified, appends
 500 .Sy SPACE
 501 characters, rather than null bytes.)
 502 .El
 503 .It Sy iflag= Ns Ar value Ns Op , Ns Ar value ...
 504 .Pp
 505 Where
 506 .Ar value Ns
 507 s are comma-separated symbols from the following list which
 508 affect the behavior of reading from the input file:
 509 .Bl -hang
 510 .It Sy fullblock
 511 Accumulate full blocks of input.
 512 .El
 513 .It Sy oflag= Ns Ar value Ns Op , Ns Ar value ...
 514 .ad








































































































































 515 .sp .6
 516 Where
 517 .Ar value Ns
 518 s are comma-separated symbols from the following list which
 519 affect the behavior of writing the output file:
 520 .Bl -hang
 521 .It Sy dsync
 522 The output file is opened with the
 523 .Sy O_DSYNC
 524 flag set.
 525 All data writes will be synchronous.
 526 For more information on
 527 .Sy O_DSYNC
 528 see
 529 .Xr fcntl.h 3HEAD .
 530 .It Sy sync
 531 The output file is opened with the
 532 .Sy O_SYNC .
 533 All data and metadata writes will be synchronous.
 534 For more information on
 535 .Sy O_SYNC
 536 see
 537 .Xr fcntl.h 3HEAD .
 538 .El
 539 .El
 540 .Pp
 541 If operands other than
 542 .Sy conv=
 543 and
 544 .Sy oflag=
 545 are specified more than once, the last specified
 546 .Sy operand= Ns Ar value
 547 is used.
 548 .Pp
 549 For the
 550 .Sy bs= ,
 551 .Sy cbs= ,
 552 .Sy ibs= ,
 553 and
 554 .Sy obs=
 555 operands, the application must supply an expression specifying a size in bytes.
 556 The expression,
 557 .Sy expr ,
 558 can be:
 559 .Bl -enum -offset indent -compact
 560 .It
 561 a positive decimal number
 562 .Pp
 563 .It
 564 a positive decimal number followed by
 565 .Sy k ,
 566 specifying multiplication by 1024
 567 .Pp
 568 .It
 569 a positive decimal number followed by
 570 .Sy M ,
 571 specifying multiplication by 1024*1024
 572 .Pp
 573 .It
 574 a positive decimal number followed by
 575 .Sy G ,
 576 specifying multiplication by 1024*1024*1024
 577 .Pp
 578 .It
 579 a positive decimal number followed by
 580 .Sy T ,
 581 specifying multiplication by 1024*1024*1024*1024
 582 .Pp
 583 .It
 584 a positive decimal number followed by
 585 .Sy P ,
 586 specifying multiplication by 1024*1024*1024*1024*1024
 587 .Pp
 588 .It
 589 a positive decimal number followed by
 590 .Sy E ,
 591 specifying multiplication by 1024*1024*1024*1024*1024*1024
 592 .Pp
 593 .It
 594 a positive decimal number followed by
 595 .Sy Z ,
 596 specifying multiplication by 1024*1024*1024*1024*1024*1024*1024
 597 .Pp
 598 .It
 599 a positive decimal number followed by
 600 .Sy b ,
 601 specifying multiplication by 512
 602 .Pp
 603 .It
 604 two or more positive decimal numbers (with or without
 605 .Sy k
 606 or
 607 .Sy b )
 608 separated by
 609 .Sy x ,
 610 specifying the product of the indicated values.
 611 .El
 612 .Pp






 613 All of the operands will be processed before any input is read.
 614 .Sh SIGNALS
 615 When
 616 .Nm
 617 receives either SIGINFO or SIGUSR1,
 618 .Nm
 619 will emit the current input and output block counts, total bytes written,
 620 total time elapsed, and the number of bytes per second to standard error.
 621 This is the same information format that
 622 .Nm
 623 emits when it successfully completes.
 624 Users may send SIGINFO via their terminal.
 625 The default character is ^T, see
 626 .Xr stty 1
 627 for more information.
 628 .Pp
 629 For
 630 .Sy SIGINT ,
 631 .Nm
 632 writes status information to standard error before exiting.
 633 .Nm
 634 takes the standard action for all other signals.
 635 .Sh USAGE
 636 See
 637 .Xr largefile 5
 638 for the description of the behavior of
 639 .Nm
 640 when encountering files greater than or equal to 2 Gbyte (2^31 bytes).
 641 .Sh EXIT STATUS























































 642 The following exit values are returned:
 643 .Bl -hang
 644 .It Sy 0




 645 The input file was copied successfully.
 646 .It Sy >0







 647 An error occurred.
 648 .El
 649 .Pp
 650 If an input error is detected and the
 651 .Sy noerror
 652 conversion has not been specified, any partial output block will be written
 653 to the output file, a diagnostic message will be written, and the copy
 654 operation will be discontinued.
 655 If some other error is detected, a diagnostic message will be
 656 written and the copy operation will be discontinued.
 657 .Sh EXAMPLES
 658 .Bl -ohang
 659 .It Sy Example 1 No Copying from one tape drive to another
 660 .Pp
 661 The following example copies from tape drive
 662 .Sy 0
 663 to tape drive
 664 .Sy 1 ,
 665 using a common historical device naming convention.
 666 .Pp
 667 .Dl % dd if=/dev/rmt/0h of=/dev/rmt/1h
 668 .It Sy Example 2 No Stripping the first 10 bytes from standard input
 669 .Pp
 670 The following example strips the first 10 bytes from standard input:
 671 .Pp
 672 .Dl % dd ibs=10  skip=1
 673 .It Sy Example 3 No Reading a tape into an ASCII file
 674 .Pp
 675 This example reads an
 676 .Sy EBCDIC
 677 tape blocked ten 80-byte
 678 .Sy EBCDIC
 679 card images per block into the
 680 .Sy ASCII
 681 file
 682 .Sy x :
 683 .Pp
 684 .Dl % dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase
 685 .It Sy Example 4 No Using conv=sync to write to tape
 686 .Pp
 687 The following example uses
 688 .Sy conv=sync
 689 when writing to a tape:
 690 .Pp
 691 .Dl % tar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync
 692 .El
 693 .Sh DIAGNOSTICS
 694 .Bl -hang
 695 .It Sy f+p records in(out)
 696 numbers of full and partial blocks read(written)
 697 .El
 698 .Sh ENVIRONMENT VARIABLES
 699 See
 700 .Xr environ 5
 701 for descriptions of the following environment variables
 702 that affect the execution of
 703 .Nm :
 704 .Sy LANG ,
 705 .Sy LC_ALL ,
 706 .Sy LC_CTYPE ,
 707 .Sy LC_MESSAGES ,
 708 and
 709 .Sy NLSPATH .
 710 .Sh INTERFACE STABILITY
 711 Standard
 712 .Sh SEE ALSO
 713 .Xr cp 1 ,
 714 .Xr sed 1 ,
 715 .Xr tr 1 ,
 716 .Xr fcntl.h 3HEAD ,
 717 .Xr attributes 5 ,
 718 .Xr environ 5 ,
 719 .Xr largefile 5 ,
 720 .Xr standards 5
 721 .Sh NOTES
 722 Do not use
 723 .Nm
 724 to copy files between file systems having different block sizes.
 725 .Pp
 726 Using a  blocked device to copy a file will result in extra nulls being added
 727 to the file to pad the final block to the block boundary.
 728 .Pp
 729 When
 730 .Nm
 731 reads from a pipe, using the
 732 .Sy ibs=X
 733 and
 734 .Sy obs=Y
 735 operands, the output will always be blocked in chunks of size Y.
 736 When
 737 .Sy bs=Z
 738 is used, the output blocks will be whatever was available to be read
 739 from the pipe at the time.
 740 .Pp
 741 When using
 742 .Nm
 743 to copy files to a tape device, the file size must be a multiple of the
 744 device sector size (for example, 512 Kbyte).
 745 To copy files of arbitrary size to a tape device, use
 746 .Xr tar 1
 747 or
 748 .Xr cpio 1 .