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 \fBM\fR, specifying multiplication by 407 1024*1024 408 .RE 409 .RS +4 410 .TP 411 4. 412 a positive decimal number followed by \fBG\fR, specifying multiplication by 413 1024*1024*1024 414 .RE 415 .RS +4 416 .TP 417 5. 418 a positive decimal number followed by \fBT\fR, specifying multiplication by 419 1024*1024*1024*1024 420 .RE 421 .RS +4 422 .TP 423 6. 424 a positive decimal number followed by \fBP\fR, specifying multiplication by 425 1024*1024*1024*1024*1024 426 .RE 427 .RS +4 428 .TP 429 7. 430 a positive decimal number followed by \fBE\fR, specifying multiplication by 431 1024*1024*1024*1024*1024*1024 432 .RE 433 .RS +4 434 .TP 435 8. 436 a positive decimal number followed by \fBZ\fR, specifying multiplication by 437 1024*1024*1024*1024*1024*1024*1024 438 .RE 439 .RS +4 440 .TP 441 9. 442 a positive decimal number followed by \fBb\fR, specifying multiplication by 443 512 444 .RE 445 .RS +4 446 .TP 447 10. 448 two or more positive decimal numbers (with or without \fBk\fR or \fBb\fR) 449 separated by \fBx\fR, specifying the product of the indicated values. 450 .RE 451 .sp 452 .LP 453 All of the operands will be processed before any input is read. 454 .SH USAGE 455 .sp 456 .LP 457 See \fBlargefile\fR(5) for the description of the behavior of \fBdd\fR when 458 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes). 459 .SH EXAMPLES 460 .LP 461 \fBExample 1 \fRCopying from one tape drive to another 462 .sp 463 .LP 464 The following example copies from tape drive \fB0\fR to tape drive \fB1\fR, 465 using a common historical device naming convention. 466 467 .sp 468 .in +2 469 .nf 470 example% \fBdd if=/dev/rmt/0h of=/dev/rmt/1h\fR 471 .fi 472 .in -2 473 .sp 474 475 .LP 476 \fBExample 2 \fRStripping the first 10 bytes from standard input 477 .sp 478 .LP 479 The following example strips the first 10 bytes from standard input: 480 481 .sp 482 .in +2 483 .nf 484 example% \fBdd ibs=10 skip=1\fR 485 .fi 486 .in -2 487 .sp 488 489 .LP 490 \fBExample 3 \fRReading a tape into an ASCII file 491 .sp 492 .LP 493 This example reads an \fBEBCDIC\fR tape blocked ten 80-byte \fBEBCDIC\fR card 494 images per block into the \fBASCII\fR file \fBx\fR: 495 496 .sp 497 .in +2 498 .nf 499 example% \fBdd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase\fR 500 .fi 501 .in -2 502 .sp 503 504 .LP 505 \fBExample 4 \fRUsing conv=sync to write to tape 506 .sp 507 .LP 508 The following example uses \fBconv=sync\fR when writing to a tape: 509 510 .sp 511 .in +2 512 .nf 513 example% \fBtar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync\fR 514 .fi 515 .in -2 516 .sp 517 518 .SH ENVIRONMENT VARIABLES 519 .sp 520 .LP 521 See \fBenviron\fR(5) for descriptions of the following environment variables 522 that affect the execution of \fBdd\fR: \fBLANG\fR, \fBLC_ALL\fR, 523 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR. 524 .SH EXIT STATUS 525 .sp 526 .LP 527 The following exit values are returned: 528 .sp 529 .ne 2 530 .na 531 \fB\fB0\fR\fR 532 .ad 533 .RS 6n 534 The input file was copied successfully. 535 .RE 536 537 .sp 538 .ne 2 539 .na 540 \fB\fB>0\fR\fR 541 .ad 542 .RS 6n 543 An error occurred. 544 .RE 545 546 .sp 547 .LP 548 If an input error is detected and the \fBnoerror\fR conversion has not been 549 specified, any partial output block will be written to the output file, a 550 diagnostic message will be written, and the copy operation will be 551 discontinued. If some other error is detected, a diagnostic message will be 552 written and the copy operation will be discontinued. 553 .SH ATTRIBUTES 554 .sp 555 .LP 556 See \fBattributes\fR(5) for descriptions of the following attributes: 557 .sp 558 559 .sp 560 .TS 561 box; 562 c | c 563 l | l . 564 ATTRIBUTE TYPE ATTRIBUTE VALUE 565 _ 566 Interface Stability Standard 567 .TE 568 569 .SH SEE ALSO 570 .sp 571 .LP 572 \fBcp\fR(1), \fBsed\fR(1), \fBtr\fR(1), \fBattributes\fR(5), \fBenviron\fR(5), 573 \fBlargefile\fR(5), \fBstandards\fR(5) 574 .SH DIAGNOSTICS 575 .sp 576 .ne 2 577 .na 578 \fB\fBf+p records in(out)\fR\fR 579 .ad 580 .RS 23n 581 numbers of full and partial blocks read(written) 582 .RE 583 584 .SH NOTES 585 .sp 586 .LP 587 Do not use \fBdd\fR to copy files between file systems having different block 588 sizes. 589 .sp 590 .LP 591 Using a blocked device to copy a file will result in extra nulls being added 592 to the file to pad the final block to the block boundary. 593 .sp 594 .LP 595 When \fBdd\fR reads from a pipe, using the \fBibs=X\fR and \fBobs=Y\fR 596 operands, the output will always be blocked in chunks of size Y. When 597 \fBbs=Z\fR is used, the output blocks will be whatever was available to be read 598 from the pipe at the time. 599 .sp 600 .LP 601 When using \fBdd\fR to copy files to a tape device, the file size must be a 602 multiple of the device sector size (for example, 512 Kbyte). To copy files of 603 arbitrary size to a tape device, use \fBtar\fR(1) or \fBcpio\fR(1). 604 .sp 605 .LP 606 For \fBSIGINT\fR, \fBdd\fR writes status information to standard error before 607 exiting. It takes the standard action for all other signals.