Commit | Line | Data |
---|---|---|
984263bc MD |
1 | .\" Copyright (c) 1990, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" Keith Muller of the University of California, San Diego. | |
6 | .\" | |
7 | .\" Redistribution and use in source and binary forms, with or without | |
8 | .\" modification, are permitted provided that the following conditions | |
9 | .\" are met: | |
10 | .\" 1. Redistributions of source code must retain the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in the | |
14 | .\" documentation and/or other materials provided with the distribution. | |
1902d433 | 15 | .\" 3. Neither the name of the University nor the names of its contributors |
984263bc MD |
16 | .\" may be used to endorse or promote products derived from this software |
17 | .\" without specific prior written permission. | |
18 | .\" | |
19 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
20 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
21 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
22 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
23 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
24 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
25 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
26 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
27 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
28 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
29 | .\" SUCH DAMAGE. | |
30 | .\" | |
31 | .\" @(#)dd.1 8.2 (Berkeley) 1/13/94 | |
32 | .\" $FreeBSD: src/bin/dd/dd.1,v 1.15.2.5 2003/01/24 02:17:12 keramida Exp $ | |
1902d433 | 33 | .\" $DragonFly: src/bin/dd/dd.1,v 1.3 2008/01/28 16:08:02 matthias Exp $ |
984263bc | 34 | .\" |
1902d433 | 35 | .Dd January 28, 2008 |
984263bc MD |
36 | .Dt DD 1 |
37 | .Os | |
38 | .Sh NAME | |
39 | .Nm dd | |
40 | .Nd convert and copy a file | |
41 | .Sh SYNOPSIS | |
42 | .Nm | |
43 | .Op Ar operands ... | |
44 | .Sh DESCRIPTION | |
45 | The | |
46 | .Nm | |
47 | utility copies the standard input to the standard output. | |
48 | Input data is read and written in 512-byte blocks. | |
49 | If input reads are short, input from multiple reads are aggregated | |
50 | to form the output block. | |
51 | When finished, | |
52 | .Nm | |
53 | displays the number of complete and partial input and output blocks | |
54 | and truncated input records to the standard error output. | |
55 | .Pp | |
56 | The following operands are available: | |
57 | .Bl -tag -width ".Cm of Ns = Ns Ar file" | |
58 | .It Cm bs Ns = Ns Ar n | |
59 | Set both input and output block size to | |
60 | .Ar n | |
61 | bytes, superseding the | |
62 | .Cm ibs | |
63 | and | |
64 | .Cm obs | |
65 | operands. | |
66 | If no conversion values other than | |
67 | .Cm noerror , | |
68 | .Cm notrunc | |
69 | or | |
70 | .Cm sync | |
71 | are specified, then each input block is copied to the output as a | |
72 | single block without any aggregation of short blocks. | |
73 | .It Cm cbs Ns = Ns Ar n | |
74 | Set the conversion record size to | |
75 | .Ar n | |
76 | bytes. | |
77 | The conversion record size is required by the record oriented conversion | |
78 | values. | |
79 | .It Cm count Ns = Ns Ar n | |
80 | Copy only | |
81 | .Ar n | |
82 | input blocks. | |
83 | .It Cm files Ns = Ns Ar n | |
84 | Copy | |
85 | .Ar n | |
86 | input files before terminating. | |
87 | This operand is only applicable when the input device is a tape. | |
88 | .It Cm ibs Ns = Ns Ar n | |
89 | Set the input block size to | |
90 | .Ar n | |
91 | bytes instead of the default 512. | |
92 | .It Cm if Ns = Ns Ar file | |
93 | Read input from | |
94 | .Ar file | |
95 | instead of the standard input. | |
96 | .It Cm iseek Ns = Ns Ar n | |
97 | Seek on the input file | |
98 | .Ar n | |
99 | blocks. | |
100 | This is synonymous with | |
101 | .Cm skip Ns = Ns Ar n . | |
102 | .It Cm obs Ns = Ns Ar n | |
103 | Set the output block size to | |
104 | .Ar n | |
105 | bytes instead of the default 512. | |
106 | .It Cm of Ns = Ns Ar file | |
107 | Write output to | |
108 | .Ar file | |
109 | instead of the standard output. | |
110 | Any regular output file is truncated unless the | |
111 | .Cm notrunc | |
112 | conversion value is specified. | |
113 | If an initial portion of the output file is seeked past (see the | |
114 | .Cm oseek | |
115 | operand), | |
116 | the output file is truncated at that point. | |
117 | .It Cm oseek Ns = Ns Ar n | |
118 | Seek on the output file | |
119 | .Ar n | |
120 | blocks. | |
121 | This is synonymous with | |
122 | .Cm seek Ns = Ns Ar n . | |
123 | .It Cm seek Ns = Ns Ar n | |
124 | Seek | |
125 | .Ar n | |
126 | blocks from the beginning of the output before copying. | |
127 | On non-tape devices, an | |
128 | .Xr lseek 2 | |
129 | operation is used. | |
130 | Otherwise, existing blocks are read and the data discarded. | |
131 | If the user does not have read permission for the tape, it is positioned | |
132 | using the tape | |
133 | .Xr ioctl 2 | |
134 | function calls. | |
135 | If the seek operation is past the end of file, space from the current | |
136 | end of file to the specified offset is filled with blocks of | |
137 | .Dv NUL | |
138 | bytes. | |
139 | .It Cm skip Ns = Ns Ar n | |
140 | Skip | |
141 | .Ar n | |
142 | blocks from the beginning of the input before copying. | |
143 | On input which supports seeks, an | |
144 | .Xr lseek 2 | |
145 | operation is used. | |
146 | Otherwise, input data is read and discarded. | |
147 | For pipes, the correct number of bytes is read. | |
148 | For all other devices, the correct number of blocks is read without | |
149 | distinguishing between a partial or complete block being read. | |
150 | .It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value ... | |
151 | Where | |
152 | .Cm value | |
153 | is one of the symbols from the following list. | |
154 | .Bl -tag -width ".Cm unblock" | |
155 | .It Cm ascii , oldascii | |
156 | The same as the | |
157 | .Cm unblock | |
158 | value except that characters are translated from | |
159 | .Tn EBCDIC | |
160 | to | |
161 | .Tn ASCII | |
162 | before the | |
163 | records are converted. | |
164 | (These values imply | |
165 | .Cm unblock | |
166 | if the operand | |
167 | .Cm cbs | |
168 | is also specified.) | |
169 | There are two conversion maps for | |
170 | .Tn ASCII . | |
171 | The value | |
172 | .Cm ascii | |
173 | specifies the recommended one which is compatible with | |
174 | .At V . | |
175 | The value | |
176 | .Cm oldascii | |
177 | specifies the one used in historic | |
178 | .At | |
179 | and | |
180 | .No pre- Ns Bx 4.3 reno | |
181 | systems. | |
182 | .It Cm block | |
183 | Treats the input as a sequence of newline or end-of-file terminated variable | |
184 | length records independent of input and output block boundaries. | |
185 | Any trailing newline character is discarded. | |
186 | Each input record is converted to a fixed length output record where the | |
187 | length is specified by the | |
188 | .Cm cbs | |
189 | operand. | |
190 | Input records shorter than the conversion record size are padded with spaces. | |
191 | Input records longer than the conversion record size are truncated. | |
192 | The number of truncated input records, if any, are reported to the standard | |
193 | error output at the completion of the copy. | |
194 | .It Cm ebcdic , ibm , oldebcdic , oldibm | |
195 | The same as the | |
196 | .Cm block | |
197 | value except that characters are translated from | |
198 | .Tn ASCII | |
199 | to | |
200 | .Tn EBCDIC | |
201 | after the | |
202 | records are converted. | |
203 | (These values imply | |
204 | .Cm block | |
205 | if the operand | |
206 | .Cm cbs | |
207 | is also specified.) | |
208 | There are four conversion maps for | |
209 | .Tn EBCDIC . | |
210 | The value | |
211 | .Cm ebcdic | |
212 | specifies the recommended one which is compatible with | |
213 | .At V . | |
214 | The value | |
215 | .Cm ibm | |
216 | is a slightly different mapping, which is compatible with the | |
217 | .At V | |
218 | .Cm ibm | |
219 | value. | |
220 | The values | |
221 | .Cm oldebcdic | |
222 | and | |
223 | .Cm oldibm | |
224 | are maps used in historic | |
225 | .At | |
226 | and | |
227 | .No pre- Ns Bx 4.3 reno | |
228 | systems. | |
229 | .It Cm lcase | |
230 | Transform uppercase characters into lowercase characters. | |
231 | .It Cm noerror | |
232 | Do not stop processing on an input error. | |
233 | When an input error occurs, a diagnostic message followed by the current | |
234 | input and output block counts will be written to the standard error output | |
235 | in the same format as the standard completion message. | |
236 | If the | |
237 | .Cm sync | |
238 | conversion is also specified, any missing input data will be replaced | |
239 | with | |
240 | .Dv NUL | |
241 | bytes (or with spaces if a block oriented conversion value was | |
242 | specified) and processed as a normal input buffer. | |
243 | If the | |
244 | .Cm sync | |
245 | conversion is not specified, the input block is omitted from the output. | |
246 | On input files which are not tapes or pipes, the file offset | |
247 | will be positioned past the block in which the error occurred using | |
248 | .Xr lseek 2 . | |
249 | .It Cm notrunc | |
250 | Do not truncate the output file. | |
251 | This will preserve any blocks in the output file not explicitly written | |
252 | by | |
253 | .Nm . | |
254 | The | |
255 | .Cm notrunc | |
256 | value is not supported for tapes. | |
257 | .It Cm osync | |
258 | Pad the final output block to the full output block size. | |
259 | If the input file is not a multiple of the output block size | |
260 | after conversion, this conversion forces the final output block | |
261 | to be the same size as preceding blocks for use on devices that require | |
262 | regularly sized blocks to be written. | |
263 | This option is incompatible with use of the | |
264 | .Cm bs Ns = Ns Ar n | |
265 | block size specification. | |
266 | .It Cm sparse | |
267 | If one or more output blocks would consist solely of | |
268 | .Dv NUL | |
269 | bytes, try to seek the output file by the required space instead of | |
270 | filling them with | |
271 | .Dv NUL Ns s , | |
272 | resulting in a sparse file. | |
273 | .It Cm swab | |
274 | Swap every pair of input bytes. | |
275 | If an input buffer has an odd number of bytes, the last byte will be | |
276 | ignored during swapping. | |
277 | .It Cm sync | |
278 | Pad every input block to the input buffer size. | |
279 | Spaces are used for pad bytes if a block oriented conversion value is | |
280 | specified, otherwise | |
281 | .Dv NUL | |
282 | bytes are used. | |
283 | .It Cm ucase | |
284 | Transform lowercase characters into uppercase characters. | |
285 | .It Cm unblock | |
286 | Treats the input as a sequence of fixed length records independent of input | |
287 | and output block boundaries. | |
288 | The length of the input records is specified by the | |
289 | .Cm cbs | |
290 | operand. | |
291 | Any trailing space characters are discarded and a newline character is | |
292 | appended. | |
293 | .El | |
294 | .El | |
295 | .Pp | |
296 | Where sizes are specified, a decimal, octal, or hexadecimal number of | |
297 | bytes is expected. | |
298 | If the number ends with a | |
299 | .Dq Li b , | |
1902d433 | 300 | .Dq Li B , |
984263bc | 301 | .Dq Li k , |
1902d433 | 302 | .Dq Li K , |
984263bc | 303 | .Dq Li m , |
1902d433 | 304 | .Dq Li M , |
984263bc | 305 | .Dq Li g , |
1902d433 | 306 | .Dq Li G , |
984263bc MD |
307 | or |
308 | .Dq Li w , | |
309 | the | |
310 | number is multiplied by 512, 1024 (1K), 1048576 (1M), 1073741824 (1G) | |
311 | or the number of bytes in an integer, respectively. | |
312 | Two or more numbers may be separated by an | |
313 | .Dq Li x | |
314 | to indicate a product. | |
315 | .Pp | |
316 | When finished, | |
317 | .Nm | |
318 | displays the number of complete and partial input and output blocks, | |
319 | truncated input records and odd-length byte-swapping blocks to the | |
320 | standard error output. | |
321 | A partial input block is one where less than the input block size | |
322 | was read. | |
323 | A partial output block is one where less than the output block size | |
324 | was written. | |
325 | Partial output blocks to tape devices are considered fatal errors. | |
326 | Otherwise, the rest of the block will be written. | |
327 | Partial output blocks to character devices will produce a warning message. | |
328 | A truncated input block is one where a variable length record oriented | |
329 | conversion value was specified and the input line was too long to | |
330 | fit in the conversion record or was not newline terminated. | |
331 | .Pp | |
332 | Normally, data resulting from input or conversion or both are aggregated | |
333 | into output blocks of the specified size. | |
334 | After the end of input is reached, any remaining output is written as | |
335 | a block. | |
336 | This means that the final output block may be shorter than the output | |
337 | block size. | |
338 | .Pp | |
339 | If | |
340 | .Nm | |
341 | receives a | |
342 | .Dv SIGINFO | |
343 | (see the | |
344 | .Cm status | |
345 | argument for | |
346 | .Xr stty 1 ) | |
347 | signal, the current input and output block counts will | |
348 | be written to the standard error output | |
349 | in the same format as the standard completion message. | |
350 | If | |
351 | .Nm | |
352 | receives a | |
353 | .Dv SIGINT | |
354 | signal, the current input and output block counts will | |
355 | be written to the standard error output | |
356 | in the same format as the standard completion message and | |
357 | .Nm | |
358 | will exit. | |
19fe1c42 | 359 | .Sh EXIT STATUS |
984263bc MD |
360 | .Ex -std |
361 | .Sh SEE ALSO | |
362 | .Xr cp 1 , | |
363 | .Xr mt 1 , | |
364 | .Xr tr 1 | |
365 | .Sh STANDARDS | |
366 | The | |
367 | .Nm | |
368 | utility is expected to be a superset of the | |
369 | .St -p1003.2 | |
370 | standard. | |
371 | The | |
372 | .Cm files | |
373 | operand and the | |
374 | .Cm ascii , | |
375 | .Cm ebcdic , | |
376 | .Cm ibm , | |
377 | .Cm oldascii , | |
378 | .Cm oldebcdic | |
379 | and | |
380 | .Cm oldibm | |
381 | values are extensions to the | |
382 | .Tn POSIX | |
383 | standard. |