1 '\" te
   2 .\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   3 .\" Copyright 1989 AT&T
   4 .\" Portions Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH DD 1M "Sep 16, 1996"
  13 .SH NAME
  14 dd \- convert and copy a file
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 \fB/usr/bin/dd\fR [\fIoperand=value\fR]...
  19 .fi
  20 
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fBdd\fR utility copies the specified input file to the specified output
  25 with possible conversions. The standard input and output are used by default.
  26 The input and output block sizes may be specified to take advantage of raw
  27 physical I/O. Sizes are specified in bytes; a number may end with \fBk\fR,
  28 \fBb\fR, or \fBw\fR to specify multiplication by 1024, 512, or 2, respectively.
  29 Numbers may also be separated by \fBx\fR to indicate multiplication.
  30 .sp
  31 .LP
  32 The \fBdd\fR utility reads the input one block at a time, using the specified
  33 input block size. \fBdd\fR then processes the block of data actually returned,
  34 which could be smaller than the requested block size. \fBdd\fR applies any
  35 conversions that have been specified and writes the resulting data to the
  36 output in blocks of the specified output block size.
  37 .sp
  38 .LP
  39 \fBcbs\fR is used only if \fBascii\fR, \fBasciib\fR, \fBunblock\fR,
  40 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, \fBibmb\fR, or \fBblock\fR conversion
  41 is specified. In the first two cases, \fBcbs\fR characters are copied into the
  42 conversion buffer, any specified character mapping is done, trailing blanks are
  43 trimmed, and a \fBNEWLINE\fR is added before sending the line to output. In the
  44 last three cases, characters up to \fBNEWLINE\fR are read into the conversion
  45 buffer and blanks are added to make up an output record of size \fBcbs\fR.
  46 \fBASCII\fR files are presumed to contain \fBNEWLINE\fR characters. If
  47 \fBcbs\fR is unspecified or \fB0\fR, the \fBascii\fR, \fBasciib\fR,
  48 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, and \fBibmb\fR options convert the
  49 character set without changing the input file's block structure. The
  50 \fBunblock\fR and \fBblock\fR options become a simple file copy.
  51 .sp
  52 .LP
  53 After completion, \fBdd\fR reports the number of whole and partial input and
  54 output blocks.
  55 .SH OPERANDS
  56 .sp
  57 .LP
  58 The following operands are supported:
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fBif=\fR\fIfile\fR\fR
  63 .ad
  64 .sp .6
  65 .RS 4n
  66 Specifies the input path. Standard input is the default.
  67 .RE
  68 
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBof=\fR\fIfile\fR\fR
  73 .ad
  74 .sp .6
  75 .RS 4n
  76 Specifies the output path. Standard output is the default. If the
  77 \fBseek=\fR\fBexpr\fR conversion is not also specified, the output file will be
  78 truncated before the copy begins, unless \fBconv=notrunc\fR is specified. If
  79 \fBseek=\fR\fBexpr\fR is specified, but \fBconv=notrunc\fR is not, the effect
  80 of the copy will be to preserve the blocks in the output file over which
  81 \fBdd\fR seeks, but no other portion of the output file will be preserved. (If
  82 the size of the seek plus the size of the input file is less than the previous
  83 size of the output file, the output file is shortened by the copy.)
  84 .RE
  85 
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBibs=\fR\fIn\fR\fR
  90 .ad
  91 .sp .6
  92 .RS 4n
  93 Specifies the input block size in \fIn\fR bytes (default is \fB512\fR).
  94 .RE
  95 
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBobs=\fR\fIn\fR\fR
 100 .ad
 101 .sp .6
 102 .RS 4n
 103 Specifies the output block size in \fIn\fR bytes (default is \fB512\fR).
 104 .RE
 105 
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBbs=\fR\fIn\fR\fR
 110 .ad
 111 .sp .6
 112 .RS 4n
 113 Sets both input and output block sizes to \fIn\fR bytes, superseding \fBibs=\fR
 114 and \fBobs=\fR. If no conversion other than \fBsync\fR,\fB noerror\fR, and
 115 \fBnotrunc\fR is specified, each input block is copied to the output as a
 116 single block without aggregating short blocks.
 117 .RE
 118 
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fBcbs=\fR\fIn\fR\fR
 123 .ad
 124 .sp .6
 125 .RS 4n
 126 Specifies the conversion block size for \fBblock\fR and \fBunblock\fR in bytes
 127 by \fIn\fR (default is \fB0\fR). If \fBcbs=\fR is omitted or given a value of
 128 \fB0\fR, using \fBblock\fR or \fBunblock\fR produces unspecified results.
 129 .sp
 130 This option is used only if \fBASCII\fR or \fBEBCDIC\fR conversion is
 131 specified. For the \fBascii\fR and \fBasciib\fR operands, the input is handled
 132 as described for the \fBunblock\fR operand except that characters are converted
 133 to \fBASCII\fR before the trailing \fBSPACE\fR characters are deleted. For the
 134 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, and \fBibmb\fR operands, the input is
 135 handled as described for the \fBblock\fR operand except that the characters are
 136 converted to \fBEBCDIC\fR or IBM \fBEBCDIC\fR after the trailing \fBSPACE\fR
 137 characters are added.
 138 .RE
 139 
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fBfiles=\fR\fIn\fR\fR
 144 .ad
 145 .sp .6
 146 .RS 4n
 147 Copies and concatenates \fIn\fR input files before terminating (makes sense
 148 only where input is a magnetic tape or similar device).
 149 .RE
 150 
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fBskip=\fR\fIn\fR\fR
 155 .ad
 156 .sp .6
 157 .RS 4n
 158 Skips \fIn\fR input blocks (using the specified input block size) before
 159 starting to copy. On seekable files, the implementation reads the blocks or
 160 seeks past them. On non-seekable files, the blocks are read and the data is
 161 discarded.
 162 .RE
 163 
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBiseek=\fR\fIn\fR\fR
 168 .ad
 169 .sp .6
 170 .RS 4n
 171 Seeks \fIn\fR blocks from beginning of input file before copying (appropriate
 172 for disk files, where \fBskip\fR can be incredibly slow).
 173 .RE
 174 
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBoseek=\fR\fIn\fR\fR
 179 .ad
 180 .sp .6
 181 .RS 4n
 182 Seeks \fIn\fR blocks from beginning of output file before copying.
 183 .RE
 184 
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fBseek=\fR\fIn\fR\fR
 189 .ad
 190 .sp .6
 191 .RS 4n
 192 Skips \fIn\fR blocks (using the specified output block size) from beginning of
 193 output file before copying. On non-seekable files, existing blocks are read and
 194 space from the current end-of-file to the specified offset, if any, is filled
 195 with null bytes. On seekable files, the implementation seeks to the specified
 196 offset or reads the blocks as described for non-seekable files.
 197 .RE
 198 
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBcount=\fR\fIn\fR\fR
 203 .ad
 204 .sp .6
 205 .RS 4n
 206 Copies only \fIn\fR input blocks.
 207 .RE
 208 
 209 .sp
 210 .ne 2
 211 .na
 212 \fB\fBconv=\fR\fIvalue\fR[\fB,\fR\fIvalue\fR.\|.\|.\|]\fR
 213 .ad
 214 .sp .6
 215 .RS 4n
 216 Where \fIvalue\fRs are comma-separated symbols from the following list:
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fBascii\fR\fR
 221 .ad
 222 .RS 11n
 223 Converts \fBEBCDIC\fR to \fBASCII\fR.
 224 .RE
 225 
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBasciib\fR\fR
 230 .ad
 231 .RS 11n
 232 Converts \fBEBCDIC\fR to \fBASCII\fR using \fBBSD\fR-compatible character
 233 translations.
 234 .RE
 235 
 236 .sp
 237 .ne 2
 238 .na
 239 \fB\fBebcdic\fR\fR
 240 .ad
 241 .RS 11n
 242 Converts \fBASCII\fR to \fBEBCDIC\fR. If converting fixed-length \fBASCII\fR
 243 records without NEWLINEs, sets up a pipeline with \fBdd conv=unblock\fR
 244 beforehand.
 245 .RE
 246 
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBebcdicb\fR\fR
 251 .ad
 252 .RS 11n
 253 Converts \fBASCII\fR to \fBEBCDIC\fR using \fBBSD\fR-compatible character
 254 translations. If converting fixed-length \fBASCII\fR records without
 255 \fBNEWLINE\fRs, sets up a pipeline with \fBdd conv=unblock\fR beforehand.
 256 .RE
 257 
 258 .sp
 259 .ne 2
 260 .na
 261 \fB\fBibm\fR\fR
 262 .ad
 263 .RS 11n
 264 Slightly different map of \fBASCII\fR to \fBEBCDIC\fR. If converting
 265 fixed-length \fBASCII\fR records without \fBNEWLINE\fRs, sets up a pipeline
 266 with \fBdd conv=unblock\fR beforehand.
 267 .RE
 268 
 269 .sp
 270 .ne 2
 271 .na
 272 \fB\fBibmb\fR\fR
 273 .ad
 274 .RS 11n
 275 Slightly different map of \fBASCII\fR to \fBEBCDIC\fR using
 276 \fBBSD\fR-compatible character translations. If converting fixed-length
 277 \fBASCII\fR records without \fBNEWLINE\fRs, sets up a pipeline with \fBdd
 278 conv=unblock\fR beforehand.
 279 .RE
 280 
 281 The \fBascii\fR (or \fBasciib\fR), \fBebcdic\fR (or \fBebcdicb\fR), and
 282 \fBibm\fR (or \fBibmb\fR) values are mutually exclusive.
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fBblock\fR\fR
 287 .ad
 288 .RS 11n
 289 Treats the input as a sequence of \fBNEWLINE\fR-terminated or
 290 \fBEOF\fR-terminated variable-length records independent of the input block
 291 boundaries. Each record is converted to a record with a fixed length specified
 292 by the conversion block size. Any \fBNEWLINE\fR character is removed from the
 293 input line. \fBSPACE\fR characters are appended to lines that are shorter than
 294 their conversion block size to fill the block. Lines that are longer than the
 295 conversion block size are truncated to the largest number of characters that
 296 will fit into that size. The number of truncated lines is reported.
 297 .RE
 298 
 299 .sp
 300 .ne 2
 301 .na
 302 \fB\fBunblock\fR\fR
 303 .ad
 304 .RS 11n
 305 Converts fixed-length records to variable length. Reads a number of bytes equal
 306 to the conversion block size (or the number of bytes remaining in the input, if
 307 less than the conversion block size), delete all trailing \fBSPACE\fR
 308 characters, and append a \fBNEWLINE\fR character.
 309 .RE
 310 
 311 The  \fBblock\fR and \fBunblock\fR values are mutually exclusive.
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fBlcase\fR\fR
 316 .ad
 317 .RS 9n
 318 Maps upper-case characters specified by the \fBLC_CTYPE\fR keyword
 319 \fBtolower\fR to the corresponding lower-case character. Characters for which
 320 no mapping is specified are not modified by this conversion.
 321 .RE
 322 
 323 .sp
 324 .ne 2
 325 .na
 326 \fB\fBucase\fR\fR
 327 .ad
 328 .RS 9n
 329 Maps lower-case characters specified by the \fBLC_CTYPE\fR keyword
 330 \fBtoupper\fR to the corresponding upper-case character. Characters for which
 331 no mapping is specified are not modified by this conversion.
 332 .RE
 333 
 334 The \fBlcase\fR and \fBucase\fR symbols are mutually exclusive.
 335 .sp
 336 .ne 2
 337 .na
 338 \fB\fBswab\fR\fR
 339 .ad
 340 .RS 11n
 341 Swaps every pair of input bytes. If the current input record is an odd number
 342 of bytes, the last byte in the input record is ignored.
 343 .RE
 344 
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fBnoerror\fR\fR
 349 .ad
 350 .RS 11n
 351 Does not stop processing on an input error. When an input error occurs, a
 352 diagnostic message is written on standard error, followed by the current input
 353 and output block counts in the same format as used at completion. If the
 354 \fBsync\fR conversion is specified, the missing input is replaced with null
 355 bytes and processed normally. Otherwise, the input block will be omitted from
 356 the output.
 357 .RE
 358 
 359 .sp
 360 .ne 2
 361 .na
 362 \fB\fBnotrunc\fR\fR
 363 .ad
 364 .RS 11n
 365 Does not truncate the output file. Preserves blocks in the output file not
 366 explicitly written by this invocation of \fBdd\fR. (See also the preceding
 367 \fBof=\fR\fIfile\fR operand.)
 368 .RE
 369 
 370 .sp
 371 .ne 2
 372 .na
 373 \fB\fBsync\fR\fR
 374 .ad
 375 .RS 11n
 376 Pads every input block to the size of the \fBibs=\fR buffer, appending null
 377 bytes. (If either \fBblock\fR or \fBunblock\fR is also specified, appends
 378 \fBSPACE\fR characters, rather than null bytes.)
 379 .RE
 380 
 381 .RE
 382 
 383 .sp
 384 .LP
 385 If operands other than \fBconv=\fR are specified more than once, the last
 386 specified \fBoperand=\fR\fIvalue\fR is used.
 387 .sp
 388 .LP
 389 For the \fBbs=\fR, \fBcbs=\fR, \fBibs=\fR, and \fBobs=\fR operands, the
 390 application must supply an expression specifying a size in bytes. The
 391 expression, \fBexpr\fR, can be:
 392 .RS +4
 393 .TP
 394 1.
 395 a positive decimal number
 396 .RE
 397 .RS +4
 398 .TP
 399 2.
 400 a positive decimal number followed by \fBk\fR, specifying multiplication by
 401 1024
 402 .RE
 403 .RS +4
 404 .TP
 405 3.
 406 a positive decimal number followed by \fBb\fR, specifying multiplication by
 407 512
 408 .RE
 409 .RS +4
 410 .TP
 411 4.
 412 two or more positive decimal numbers (with or without \fBk\fR or \fBb\fR)
 413 separated by \fBx\fR, specifying the product of the indicated values.
 414 .RE
 415 .sp
 416 .LP
 417 All of the operands will be processed before any input is read.
 418 .SH USAGE
 419 .sp
 420 .LP
 421 See \fBlargefile\fR(5) for the description of the behavior of \fBdd\fR when
 422 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
 423 .SH EXAMPLES
 424 .LP
 425 \fBExample 1 \fRCopying from one tape drive to another
 426 .sp
 427 .LP
 428 The following example copies from tape drive \fB0\fR to tape drive \fB1\fR,
 429 using a common historical device naming convention.
 430 
 431 .sp
 432 .in +2
 433 .nf
 434 example% \fBdd if=/dev/rmt/0h  of=/dev/rmt/1h\fR
 435 .fi
 436 .in -2
 437 .sp
 438 
 439 .LP
 440 \fBExample 2 \fRStripping the first 10 bytes from standard input
 441 .sp
 442 .LP
 443 The following example strips the first 10 bytes from standard input:
 444 
 445 .sp
 446 .in +2
 447 .nf
 448 example% \fBdd ibs=10  skip=1\fR
 449 .fi
 450 .in -2
 451 .sp
 452 
 453 .LP
 454 \fBExample 3 \fRReading a tape into an ASCII file
 455 .sp
 456 .LP
 457 This example reads an \fBEBCDIC\fR tape blocked ten 80-byte \fBEBCDIC\fR card
 458 images per block into the \fBASCII\fR file \fBx\fR:
 459 
 460 .sp
 461 .in +2
 462 .nf
 463 example% \fBdd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase\fR
 464 .fi
 465 .in -2
 466 .sp
 467 
 468 .LP
 469 \fBExample 4 \fRUsing conv=sync to write to tape
 470 .sp
 471 .LP
 472 The following example uses \fBconv=sync\fR when writing to a tape:
 473 
 474 .sp
 475 .in +2
 476 .nf
 477 example% \fBtar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync\fR
 478 .fi
 479 .in -2
 480 .sp
 481 
 482 .SH ENVIRONMENT VARIABLES
 483 .sp
 484 .LP
 485 See \fBenviron\fR(5) for descriptions of the following environment variables
 486 that affect the execution of \fBdd\fR: \fBLANG\fR, \fBLC_ALL\fR,
 487 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 488 .SH EXIT STATUS
 489 .sp
 490 .LP
 491 The following exit values are returned:
 492 .sp
 493 .ne 2
 494 .na
 495 \fB\fB0\fR\fR
 496 .ad
 497 .RS 6n
 498 The input file was copied successfully.
 499 .RE
 500 
 501 .sp
 502 .ne 2
 503 .na
 504 \fB\fB>0\fR\fR
 505 .ad
 506 .RS 6n
 507 An error occurred.
 508 .RE
 509 
 510 .sp
 511 .LP
 512 If an input error is detected and the \fBnoerror\fR conversion has not been
 513 specified, any partial output block will be written to the output file, a
 514 diagnostic message will be written, and the copy operation will be
 515 discontinued. If some other error is detected, a diagnostic message will be
 516 written and the copy operation will be discontinued.
 517 .SH ATTRIBUTES
 518 .sp
 519 .LP
 520 See \fBattributes\fR(5) for descriptions of the following attributes:
 521 .sp
 522 
 523 .sp
 524 .TS
 525 box;
 526 c | c
 527 l | l .
 528 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 529 _
 530 Interface Stability     Standard
 531 .TE
 532 
 533 .SH SEE ALSO
 534 .sp
 535 .LP
 536 \fBcp\fR(1), \fBsed\fR(1), \fBtr\fR(1), \fBattributes\fR(5), \fBenviron\fR(5),
 537 \fBlargefile\fR(5), \fBstandards\fR(5)
 538 .SH DIAGNOSTICS
 539 .sp
 540 .ne 2
 541 .na
 542 \fB\fBf+p records in(out)\fR\fR
 543 .ad
 544 .RS 23n
 545 numbers of full and partial blocks read(written)
 546 .RE
 547 
 548 .SH NOTES
 549 .sp
 550 .LP
 551 Do not use \fBdd\fR to copy files between file systems having different block
 552 sizes.
 553 .sp
 554 .LP
 555 Using a  blocked device to copy a file will result in extra nulls being added
 556 to the file to pad the final block to the block boundary.
 557 .sp
 558 .LP
 559 When  \fBdd\fR reads from a pipe, using the  \fBibs=X\fR and  \fBobs=Y\fR
 560 operands, the output will always be blocked in chunks of size Y. When
 561 \fBbs=Z\fR is used, the output blocks will be whatever was available to be read
 562 from the pipe at the time.
 563 .sp
 564 .LP
 565 When using \fBdd\fR to copy files to a tape device, the file size must be a
 566 multiple of the device sector size (for example, 512 Kbyte).  To  copy files of
 567 arbitrary size to a tape device, use  \fBtar\fR(1) or  \fBcpio\fR(1).
 568 .sp
 569 .LP
 570 For \fBSIGINT\fR, \fBdd\fR writes status information to standard error before
 571 exiting. It takes the standard action for all other signals.