1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  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 .