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