xref: /illumos-gate/usr/src/man/man8/dd.8 (revision d48be21240dfd051b689384ce2b23479d757f2d8)
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.\" Copyright 2021 Oxide Computer Company
49.\"
50.Dd October 24, 2021
51.Dt DD 8
52.Os
53.Sh NAME
54.Nm dd
55.Nd convert and copy a file
56.Sh SYNOPSIS
57.Nm
58.Op Ar operand Ns = Ns Ar value
59.Ar ...
60.Sh DESCRIPTION
61The
62.Nm
63utility copies the specified input file to the specified output
64with possible conversions.
65The standard input and output are used by default.
66The input and output block sizes may be specified to take advantage of raw
67physical I/O.
68Sizes are specified in bytes; a number may end with
69.Sy k ,
70.Sy b ,
71or
72.Sy w
73to specify multiplication by 1024, 512, or 2, respectively.
74Numbers may also be separated by
75.Sy x
76to indicate multiplication.
77.Pp
78The
79.Nm
80utility reads the input one block at a time, using the specified
81input block size.
82.Nm
83then processes the block of data actually returned,
84which could be smaller than the requested block size unless the input flag
85.Ar fullblock
86is used.
87.Nm
88applies any conversions that have been specified and writes the resulting data
89to the output in blocks of the specified output block size.
90.Pp
91.Cm cbs
92is used only if
93.Cm ascii ,
94.Cm asciib ,
95.Cm unblock ,
96.Cm ebcdic ,
97.Cm ebcdicb ,
98.Cm ibm ,
99.Cm ibmb ,
100or
101.Cm block
102conversion is specified.
103In the first two cases,
104.Cm cbs
105characters are copied into the conversion buffer, any specified character
106mapping is done, trailing blanks are trimmed, and a
107.Cm NEWLINE
108is added before sending the line to output.
109In the last three cases, characters up to
110.Cm NEWLINE
111are read into the conversion buffer and blanks are added to make up an output
112record of size
113.Cm cbs .
114.Cm ASCII
115files are presumed to contain
116.Cm NEWLINE
117characters.
118If
119.Cm cbs
120is unspecified or
121.Cm 0 ,
122the
123.Cm ascii ,
124.Cm asciib ,
125.Cm ebcdic ,
126.Cm ebcdicb ,
127.Cm ibm ,
128and
129.Cm ibmb
130options convert the character set without changing the input file's block
131structure.
132The
133.Cm unblock
134and
135.Cm block
136options become a simple file copy.
137.Pp
138After completion,
139.Nm
140reports the number of whole and partial input and output blocks.
141.Sh OPERANDS
142The following operands are supported:
143.Bl -tag -width "if=file"
144.It Cm if= Ns Ar file
145.Pp
146Specifies the input path.
147Standard input is the default.
148.It Cm of= Ns Ar file
149.Pp
150Specifies the output path.
151Standard output is the default.
152If the
153.Cm seek Ns = Ns Ar expr
154conversion is not also specified, the output file will be truncated before
155the copy begins, unless
156.Cm conv Ns = Ns Ar notrunc
157is specified.
158If
159.Cm seek Ns = Ns Ar expr
160is specified, but
161.Cm conv Ns = Ns Ar notrunc
162is not, the effect of the copy will be to preserve the blocks in the output
163file over which
164.Nm
165seeks, but no other portion of the output file will be preserved.
166(If the size of the seek plus the size of the input file is less than the
167previous size of the output file, the output file is shortened by the copy.)
168.It Cm ibs Ns = Ns Ar n
169.Pp
170Specifies the input block size in
171.Ar n
172bytes (default is 512).
173.It Cm obs Ns = Ns Ar n
174.Pp
175Specifies the output block size in
176.Ar n
177bytes (default is 512).
178.It Cm bs Ns = Ns Ar n
179.Pp
180Sets both input and output block sizes to
181.Ar n
182bytes, superseding
183.Cm ibs Ns =
184and
185.Cm obs Ns = .
186If no conversion other than
187.Cm sync ,
188.Cm noerror ,
189and
190.Cm notrunc
191is specified, each input block is copied to the output as a
192single block without aggregating short blocks.
193.It Cm cbs Ns = Ns Ar n
194.Pp
195Specifies the conversion block size for
196.Cm block
197and
198.Cm unblock
199in bytes by
200.Ar n
201(default is
202.Cm 0 Ns ).
203If
204.Cm cbs Ns =
205is omitted or given a value of
206.Cm 0 ,
207using
208.Cm block
209or
210.Cm unblock
211produces unspecified results.
212.Pp
213This option is used only if
214.Cm ASCII
215or
216.Cm EBCDIC
217conversion is specified.
218For the
219.Cm ascii
220and
221.Cm asciib
222operands, the input is handled as described for the
223.Cm unblock
224operand except that characters are converted to
225.Cm ASCII
226before the trailing
227.Cm SPACE
228characters are deleted.
229For the
230.Cm ebcdic ,
231.Cm ebcdicb ,
232.Cm ibm ,
233and
234.Cm ibmb
235operands, the input is handled as described for the
236.Cm block
237operand except that the characters are converted to
238.Cm EBCDIC
239or IBM
240.Cm EBCDIC
241after the trailing
242.Cm SPACE
243characters are added.
244.It Cm files Ns = Ns Ar n
245.Pp
246Copies and concatenates
247.Ar n
248input files before terminating (makes sense
249only where input is a magnetic tape or similar device).
250.It Cm skip Ns = Ns Ar n
251.Pp
252Skips
253.Ar n
254input blocks (using the specified input block size) before starting to copy.
255On seekable files, the implementation reads the blocks or seeks past them.
256On non-seekable files, the blocks are read and the data is discarded.
257.It Cm iseek Ns = Ns Ar n
258.Pp
259Seeks
260.Ar n
261blocks from beginning of input file before copying (appropriate
262for disk files, where
263.Cm skip
264can be incredibly slow).
265.It Cm oseek Ns = Ns Ar n
266.Pp
267Seeks
268.Ar n
269blocks from beginning of output file before copying.
270.It Cm seek Ns = Ns Ar n
271.Pp
272Skips
273.Ar n
274blocks (using the specified output block size) from beginning of
275output file before copying.
276On non-seekable files, existing blocks are read and space from the current
277end-of-file to the specified offset, if any, is filled with null bytes.
278On seekable files, the implementation seeks to the specified
279offset or reads the blocks as described for non-seekable files.
280.It Cm ostride Ns = Ns Ar n
281.Pp
282Writes every
283.Ar n Ns
284th block (using the specified output block size) when writing output.
285Skips
286.Ar n
287- 1 blocks after writing each record.
288.It Cm istride Ns = Ns Ar n
289.Pp
290Reads every
291.Ar n Ns
292th block (using the specified input block size) when reading input.
293Skips
294.Ar n
295- 1 blocks after reading each record.
296.It Cm stride Ns = Ns Ar n
297.Pp
298Reads every
299.Ar n Ns
300th block (using the specified input block size) when reading input.
301Skips
302.Ar n
303- 1 blocks after reading each record.
304Also writes every
305.Ar n Ns
306th block (using the specified output block size) when writing output.
307Skips
308.Ar n
309- 1 blocks after writing each record.
310.It Cm count Ns = Ns Ar n
311.Pp
312Copies only
313.Ar n
314input blocks.
315.It Cm conv Ns = Ns Ar value Ns Op , Ns  Ar value Ns ...
316.Pp
317Where
318.Ar value Ns
319s are comma-separated symbols from the following list:
320.Bl -hang
321.It Cm ascii
322Converts
323.Cm EBCDIC
324to
325.Cm ASCII .
326.sp
327.It Cm asciib
328Converts
329.Cm EBCDIC
330to
331.Cm ASCII
332using
333.Cm BSD Ns
334-compatible character translations.
335.It Cm ebcdic
336Converts
337.Cm ASCII
338to
339.Cm EBCDIC .
340If converting fixed-length
341.Cm ASCII
342records without
343.Cm NEWLINE Ns
344s, sets up a pipeline with
345.Nm
346.Cm conv Ns = Ns Ar unblock
347beforehand.
348.It Cm ebcdicb
349Converts
350.Cm ASCII
351to
352.Cm EBCDIC
353using
354.Cm BSD Ns
355-compatible character translations.
356If converting fixed-length
357.Cm ASCII
358records without
359.Cm NEWLINE Ns
360s, sets up a pipeline with
361.Nm
362.Cm conv Ns = Ns Ar unblock
363beforehand.
364.It Cm ibm
365Slightly different map of
366.Cm ASCII
367to
368.Cm EBCDIC .
369If converting fixed-length
370.Cm ASCII
371records without
372.Cm NEWLINE Ns
373s, sets up a pipeline with
374.Nm
375.Cm conv Ns = Ns Ar unblock
376beforehand.
377.It Cm ibmb
378Slightly different map of
379.Cm ASCII
380to
381.Cm EBCDIC
382using
383.Cm BSD Ns
384-compatible character translations.
385If converting fixed-length
386.Cm ASCII
387records without
388.Cm NEWLINE Ns
389s, sets up a pipeline with
390.Nm
391.Cm conv Ns = Ns Ar unblock
392beforehand.
393.El
394.Pp
395The
396.Cm ascii
397(or
398.Cm asciib Ns ),
399.Cm ebcdic
400(or
401.Cm ebcdicb Ns ),
402and
403.Cm ibm
404(or
405.Cm ibmb )
406values are mutually exclusive.
407.Bl -hang
408.It Cm block
409Treats the input as a sequence of
410.Cm NEWLINE Ns
411-terminated or
412.Cm EOF Ns
413-terminated variable-length records independent of the input block boundaries.
414Each record is converted to a record with a fixed length specified
415by the conversion block size.
416Any
417.Cm NEWLINE
418character is removed from the input line.
419.Cm SPACE
420characters are appended to lines that are shorter than their conversion block
421size to fill the block.
422Lines that are longer than the conversion block size are truncated to the
423largest number of characters that will fit into that size.
424The number of truncated lines is reported.
425.It Cm unblock
426Converts fixed-length records to variable length.
427Reads a number of bytes equal to the conversion block size (or the number of
428bytes remaining in the input, if less than the conversion block size),
429delete all trailing
430.Cm SPACE
431characters, and append a
432.Cm NEWLINE
433character.
434.El
435.Pp
436The
437.Cm block
438and
439.Cm unblock
440values are mutually exclusive.
441.Bl -hang
442.It Cm lcase
443Maps upper-case characters specified by the
444.Cm LC_CTYPE
445keyword
446.Cm tolower
447to the corresponding lower-case character.
448Characters for which no mapping is specified are not modified by this
449conversion.
450.It Cm ucase
451Maps lower-case characters specified by the
452.Cm LC_CTYPE
453keyword
454.Cm toupper
455to the corresponding upper-case character.
456Characters for which no mapping is specified are not modified by this
457conversion.
458.El
459.Pp
460The
461.Cm lcase
462and
463.Cm ucase
464symbols are mutually exclusive.
465.Bl -hang
466.It Cm swab
467Swaps every pair of input bytes.
468If the current input record is an odd number of bytes, the last byte in the
469input record is ignored.
470.It Cm noerror
471Does not stop processing on an input error.
472When an input error occurs, a diagnostic message is written on standard error,
473followed by the current input and output block counts in the same format as
474used at completion.
475If the
476.Cm sync
477conversion is specified, the missing input is replaced with null
478bytes and processed normally.
479Otherwise, the input block will be omitted from the output.
480.It Cm notrunc
481Does not truncate the output file.
482Preserves blocks in the output file not explicitly written by this invocation
483of
484.Nm .
485(See also the preceding
486.Cm of Ns = Ns Ar file
487operand.)
488.It Cm sync
489Pads every input block to the size of the
490.Cm ibs Ns =
491buffer, appending null bytes.
492(If either
493.Cm block
494or
495.Cm unblock
496is also specified, appends
497.Cm SPACE
498characters, rather than null bytes.)
499.El
500.It Cm iflag Ns = Ns Ar value Ns Op , Ns Ar value ...
501.Pp
502Where
503.Ar value Ns
504s are comma-separated symbols from the following list which
505affect the behavior of reading from the input file:
506.Bl -hang
507.It Cm fullblock
508Accumulate full blocks of input.
509.El
510.It Cm oflag Ns = Ns Ar value Ns Op , Ns Ar value ...
511.ad
512.sp .6
513Where
514.Ar value Ns
515s are comma-separated symbols from the following list which
516affect the behavior of writing the output file:
517.Bl -hang
518.It Cm dsync
519The output file is opened with the
520.Cm O_DSYNC
521flag set.
522All data writes will be synchronous.
523For more information on
524.Cm O_DSYNC
525see
526.Xr fcntl.h 3HEAD .
527.It Cm sync
528The output file is opened with the
529.Cm O_SYNC .
530All data and metadata writes will be synchronous.
531For more information on
532.Cm O_SYNC
533see
534.Xr fcntl.h 3HEAD .
535.El
536.It Cm status Ns = Ns Ar type
537Changes the way that
538.Nm
539outputs information about transfers.
540Only one
541.Ar type may be specified.
542The following are valid values for
543.Ar type :
544.Bl -hang
545.It Cm none
546The program will not output any information and statistics about the transfer.
547This includes when
548.Nm
549receives a signal such as
550.Dv SIGINFO
551and
552.Dv SIGUSR1 .
553Only errors will be emitted.
554.It Cm noxfer
555When printing statistical information such as when the program terminates or in
556response to a signal, only print information about the number of records and
557none of the statistics about the transfer
558.Pq total bytes, total time, and throughput .
559.It Cm progress
560Once a second, output the normal
561.Nm
562transfer statistics that include the total number of bytes transferred, time
563elapsed, and average throughput.
564.El
565.El
566.Pp
567If operands other than
568.Cm conv Ns =
569and
570.Cm oflag Ns =
571are specified more than once, the last specified
572.Cm operand Ns = Ns Ar value
573is used.
574.Pp
575For the
576.Cm bs Ns = ,
577.Cm cbs Ns = ,
578.Cm ibs Ns = ,
579and
580.Cm obs Ns =
581operands, the application must supply an expression specifying a size in bytes.
582The expression,
583.Cm expr ,
584can be:
585.Bl -enum -offset indent -compact
586.It
587a positive decimal number
588.Pp
589.It
590a positive decimal number followed by
591.Sy k ,
592specifying multiplication by 1024
593.Pp
594.It
595a positive decimal number followed by
596.Sy M ,
597specifying multiplication by 1024*1024
598.Pp
599.It
600a positive decimal number followed by
601.Sy G ,
602specifying multiplication by 1024*1024*1024
603.Pp
604.It
605a positive decimal number followed by
606.Sy T ,
607specifying multiplication by 1024*1024*1024*1024
608.Pp
609.It
610a positive decimal number followed by
611.Sy P ,
612specifying multiplication by 1024*1024*1024*1024*1024
613.Pp
614.It
615a positive decimal number followed by
616.Sy E ,
617specifying multiplication by 1024*1024*1024*1024*1024*1024
618.Pp
619.It
620a positive decimal number followed by
621.Sy Z ,
622specifying multiplication by 1024*1024*1024*1024*1024*1024*1024
623.Pp
624.It
625a positive decimal number followed by
626.Sy b ,
627specifying multiplication by 512
628.Pp
629.It
630two or more positive decimal numbers (with or without
631.Sy k
632or
633.Sy b )
634separated by
635.Sy x ,
636specifying the product of the indicated values.
637.El
638.Pp
639All of the operands will be processed before any input is read.
640.Sh SIGNALS
641When
642.Nm
643receives either SIGINFO or SIGUSR1,
644.Nm
645will emit the current input and output block counts, total bytes written,
646total time elapsed, and the number of bytes per second to standard error.
647This is the same information format that
648.Nm
649emits when it successfully completes.
650Users may send SIGINFO via their terminal.
651The default character is ^T, see
652.Xr stty 1
653for more information.
654.Pp
655For
656.Sy SIGINT ,
657.Nm
658writes status information to standard error before exiting.
659.Nm
660takes the standard action for all other signals.
661.Sh USAGE
662See
663.Xr largefile 7
664for the description of the behavior of
665.Nm
666when encountering files greater than or equal to 2 Gbyte (2^31 bytes).
667.Sh EXIT STATUS
668The following exit values are returned:
669.Bl -tag -width ".It Cm >0"
670.It Cm 0
671The input file was copied successfully.
672.It Cm >0
673An error occurred.
674.El
675.Pp
676If an input error is detected and the
677.Cm noerror
678conversion has not been specified, any partial output block will be written
679to the output file, a diagnostic message will be written, and the copy
680operation will be discontinued.
681If some other error is detected, a diagnostic message will be
682written and the copy operation will be discontinued.
683.Sh EXAMPLES
684.Bl -ohang
685.It Sy Example 1 No Copying from one tape drive to another
686.Pp
687The following example copies from tape drive
688.Sy 0
689to tape drive
690.Sy 1 ,
691using a common historical device naming convention.
692.Pp
693.Dl % dd if=/dev/rmt/0h of=/dev/rmt/1h
694.It Sy Example 2 No Stripping the first 10 bytes from standard input
695.Pp
696The following example strips the first 10 bytes from standard input:
697.Pp
698.Dl % dd ibs=10  skip=1
699.It Sy Example 3 No Reading a tape into an ASCII file
700.Pp
701This example reads an
702.Cm EBCDIC
703tape blocked ten 80-byte
704.Cm EBCDIC
705card images per block into the
706.Cm ASCII
707file
708.Sy x :
709.Pp
710.Dl % dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase
711.It Sy Example 4 No Using conv=sync to write to tape
712.Pp
713The following example uses
714.Cm conv Ns = Ns Ar sync
715when writing to a tape:
716.Pp
717.Dl % tar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync
718.El
719.Sh DIAGNOSTICS
720.Bl -hang
721.It Sy f+p records in(out)
722numbers of full and partial blocks read(written)
723.El
724.Sh ENVIRONMENT VARIABLES
725See
726.Xr environ 7
727for descriptions of the following environment variables
728that affect the execution of
729.Nm :
730.Ev LANG ,
731.Ev LC_ALL ,
732.Ev LC_CTYPE ,
733.Ev LC_MESSAGES ,
734and
735.Ev NLSPATH .
736.Sh INTERFACE STABILITY
737Standard
738.Sh SEE ALSO
739.Xr cp 1 ,
740.Xr sed 1 ,
741.Xr tr 1 ,
742.Xr fcntl.h 3HEAD ,
743.Xr attributes 7 ,
744.Xr environ 7 ,
745.Xr largefile 7 ,
746.Xr standards 7
747.Sh NOTES
748Do not use
749.Nm
750to copy files between file systems having different block sizes.
751.Pp
752Using a  blocked device to copy a file will result in extra nulls being added
753to the file to pad the final block to the block boundary.
754.Pp
755When
756.Nm
757reads from a pipe, using the
758.Cm ibs Ns = Ns Ar X
759and
760.Cm obs Ns = Ns Ar Y
761operands, the output will always be blocked in chunks of size Y.
762When
763.Cm bs Ns = Ns Ar Z
764is used, the output blocks will be whatever was available to be read
765from the pipe at the time.
766.Pp
767When using
768.Nm
769to copy files to a tape device, the file size must be a multiple of the
770device sector size (for example, 512 Kbyte).
771To copy files of arbitrary size to a tape device, use
772.Xr tar 1
773or
774.Xr cpio 1 .
775