diff options
Diffstat (limited to 'usr/src/man/man8/dd.8')
| -rw-r--r-- | usr/src/man/man8/dd.8 | 774 |
1 files changed, 774 insertions, 0 deletions
diff --git a/usr/src/man/man8/dd.8 b/usr/src/man/man8/dd.8 new file mode 100644 index 0000000000..637ab37380 --- /dev/null +++ b/usr/src/man/man8/dd.8 @@ -0,0 +1,774 @@ +.\" +.\" 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 +.\" http://www.opengroup.org/bookstore/. +.\" +.\" 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 SunOS 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. +.\" +.\" This notice shall appear on any product containing this material. +.\" +.\" 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. +.\" +.\" 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. +.\" +.\" 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] +.\" +.\" +.\" Copyright 1989 AT&T +.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved +.\" Portions Copyright (c) 1995, Sun Microsystems, Inc. All Rights Reserved +.\" Copyright (c) 2014, Joyent, Inc. All rights Reserved. +.\" Copyright (c) 2014 by Delphix. All rights reserved. +.\" Copyright 2021 Oxide Computer Company +.\" +.Dd October 24, 2021 +.Dt DD 8 +.Os +.Sh NAME +.Nm dd +.Nd convert and copy a file +.Sh SYNOPSIS +.Nm +.Op Ar operand Ns = Ns Ar value +.Ar ... +.Sh DESCRIPTION +The +.Nm +utility copies the specified input file to the specified output +with possible conversions. +The standard input and output are used by default. +The input and output block sizes may be specified to take advantage of raw +physical I/O. +Sizes are specified in bytes; a number may end with +.Sy k , +.Sy b , +or +.Sy w +to specify multiplication by 1024, 512, or 2, respectively. +Numbers may also be separated by +.Sy x +to indicate multiplication. +.Pp +The +.Nm +utility reads the input one block at a time, using the specified +input block size. +.Nm +then processes the block of data actually returned, +which could be smaller than the requested block size unless the input flag +.Ar fullblock +is used. +.Nm +applies any conversions that have been specified and writes the resulting data +to the output in blocks of the specified output block size. +.Pp +.Cm cbs +is used only if +.Cm ascii , +.Cm asciib , +.Cm unblock , +.Cm ebcdic , +.Cm ebcdicb , +.Cm ibm , +.Cm ibmb , +or +.Cm block +conversion is specified. +In the first two cases, +.Cm cbs +characters are copied into the conversion buffer, any specified character +mapping is done, trailing blanks are trimmed, and a +.Cm NEWLINE +is added before sending the line to output. +In the last three cases, characters up to +.Cm NEWLINE +are read into the conversion buffer and blanks are added to make up an output +record of size +.Cm cbs . +.Cm ASCII +files are presumed to contain +.Cm NEWLINE +characters. +If +.Cm cbs +is unspecified or +.Cm 0 , +the +.Cm ascii , +.Cm asciib , +.Cm ebcdic , +.Cm ebcdicb , +.Cm ibm , +and +.Cm ibmb +options convert the character set without changing the input file's block +structure. +The +.Cm unblock +and +.Cm block +options become a simple file copy. +.Pp +After completion, +.Nm +reports the number of whole and partial input and output blocks. +.Sh OPERANDS +The following operands are supported: +.Bl -tag -width "if=file" +.It Cm if= Ns Ar file +.Pp +Specifies the input path. +Standard input is the default. +.It Cm of= Ns Ar file +.Pp +Specifies the output path. +Standard output is the default. +If the +.Cm seek Ns = Ns Ar expr +conversion is not also specified, the output file will be truncated before +the copy begins, unless +.Cm conv Ns = Ns Ar notrunc +is specified. +If +.Cm seek Ns = Ns Ar expr +is specified, but +.Cm conv Ns = Ns Ar notrunc +is not, the effect of the copy will be to preserve the blocks in the output +file over which +.Nm +seeks, but no other portion of the output file will be preserved. +(If the size of the seek plus the size of the input file is less than the +previous size of the output file, the output file is shortened by the copy.) +.It Cm ibs Ns = Ns Ar n +.Pp +Specifies the input block size in +.Ar n +bytes (default is 512). +.It Cm obs Ns = Ns Ar n +.Pp +Specifies the output block size in +.Ar n +bytes (default is 512). +.It Cm bs Ns = Ns Ar n +.Pp +Sets both input and output block sizes to +.Ar n +bytes, superseding +.Cm ibs Ns = +and +.Cm obs Ns = . +If no conversion other than +.Cm sync , +.Cm noerror , +and +.Cm notrunc +is specified, each input block is copied to the output as a +single block without aggregating short blocks. +.It Cm cbs Ns = Ns Ar n +.Pp +Specifies the conversion block size for +.Cm block +and +.Cm unblock +in bytes by +.Ar n +(default is +.Cm 0 Ns ). +If +.Cm cbs Ns = +is omitted or given a value of +.Cm 0 , +using +.Cm block +or +.Cm unblock +produces unspecified results. +.Pp +This option is used only if +.Cm ASCII +or +.Cm EBCDIC +conversion is specified. +For the +.Cm ascii +and +.Cm asciib +operands, the input is handled as described for the +.Cm unblock +operand except that characters are converted to +.Cm ASCII +before the trailing +.Cm SPACE +characters are deleted. +For the +.Cm ebcdic , +.Cm ebcdicb , +.Cm ibm , +and +.Cm ibmb +operands, the input is handled as described for the +.Cm block +operand except that the characters are converted to +.Cm EBCDIC +or IBM +.Cm EBCDIC +after the trailing +.Cm SPACE +characters are added. +.It Cm files Ns = Ns Ar n +.Pp +Copies and concatenates +.Ar n +input files before terminating (makes sense +only where input is a magnetic tape or similar device). +.It Cm skip Ns = Ns Ar n +.Pp +Skips +.Ar n +input blocks (using the specified input block size) before starting to copy. +On seekable files, the implementation reads the blocks or seeks past them. +On non-seekable files, the blocks are read and the data is discarded. +.It Cm iseek Ns = Ns Ar n +.Pp +Seeks +.Ar n +blocks from beginning of input file before copying (appropriate +for disk files, where +.Cm skip +can be incredibly slow). +.It Cm oseek Ns = Ns Ar n +.Pp +Seeks +.Ar n +blocks from beginning of output file before copying. +.It Cm seek Ns = Ns Ar n +.Pp +Skips +.Ar n +blocks (using the specified output block size) from beginning of +output file before copying. +On non-seekable files, existing blocks are read and space from the current +end-of-file to the specified offset, if any, is filled with null bytes. +On seekable files, the implementation seeks to the specified +offset or reads the blocks as described for non-seekable files. +.It Cm ostride Ns = Ns Ar n +.Pp +Writes every +.Ar n Ns +th block (using the specified output block size) when writing output. +Skips +.Ar n +- 1 blocks after writing each record. +.It Cm istride Ns = Ns Ar n +.Pp +Reads every +.Ar n Ns +th block (using the specified input block size) when reading input. +Skips +.Ar n +- 1 blocks after reading each record. +.It Cm stride Ns = Ns Ar n +.Pp +Reads every +.Ar n Ns +th block (using the specified input block size) when reading input. +Skips +.Ar n +- 1 blocks after reading each record. +Also writes every +.Ar n Ns +th block (using the specified output block size) when writing output. +Skips +.Ar n +- 1 blocks after writing each record. +.It Cm count Ns = Ns Ar n +.Pp +Copies only +.Ar n +input blocks. +.It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value Ns ... +.Pp +Where +.Ar value Ns +s are comma-separated symbols from the following list: +.Bl -hang +.It Cm ascii +Converts +.Cm EBCDIC +to +.Cm ASCII . +.sp +.It Cm asciib +Converts +.Cm EBCDIC +to +.Cm ASCII +using +.Cm BSD Ns +-compatible character translations. +.It Cm ebcdic +Converts +.Cm ASCII +to +.Cm EBCDIC . +If converting fixed-length +.Cm ASCII +records without +.Cm NEWLINE Ns +s, sets up a pipeline with +.Nm +.Cm conv Ns = Ns Ar unblock +beforehand. +.It Cm ebcdicb +Converts +.Cm ASCII +to +.Cm EBCDIC +using +.Cm BSD Ns +-compatible character translations. +If converting fixed-length +.Cm ASCII +records without +.Cm NEWLINE Ns +s, sets up a pipeline with +.Nm +.Cm conv Ns = Ns Ar unblock +beforehand. +.It Cm ibm +Slightly different map of +.Cm ASCII +to +.Cm EBCDIC . +If converting fixed-length +.Cm ASCII +records without +.Cm NEWLINE Ns +s, sets up a pipeline with +.Nm +.Cm conv Ns = Ns Ar unblock +beforehand. +.It Cm ibmb +Slightly different map of +.Cm ASCII +to +.Cm EBCDIC +using +.Cm BSD Ns +-compatible character translations. +If converting fixed-length +.Cm ASCII +records without +.Cm NEWLINE Ns +s, sets up a pipeline with +.Nm +.Cm conv Ns = Ns Ar unblock +beforehand. +.El +.Pp +The +.Cm ascii +(or +.Cm asciib Ns ), +.Cm ebcdic +(or +.Cm ebcdicb Ns ), +and +.Cm ibm +(or +.Cm ibmb ) +values are mutually exclusive. +.Bl -hang +.It Cm block +Treats the input as a sequence of +.Cm NEWLINE Ns +-terminated or +.Cm EOF Ns +-terminated variable-length records independent of the input block boundaries. +Each record is converted to a record with a fixed length specified +by the conversion block size. +Any +.Cm NEWLINE +character is removed from the input line. +.Cm SPACE +characters are appended to lines that are shorter than their conversion block +size to fill the block. +Lines that are longer than the conversion block size are truncated to the +largest number of characters that will fit into that size. +The number of truncated lines is reported. +.It Cm unblock +Converts fixed-length records to variable length. +Reads a number of bytes equal to the conversion block size (or the number of +bytes remaining in the input, if less than the conversion block size), +delete all trailing +.Cm SPACE +characters, and append a +.Cm NEWLINE +character. +.El +.Pp +The +.Cm block +and +.Cm unblock +values are mutually exclusive. +.Bl -hang +.It Cm lcase +Maps upper-case characters specified by the +.Cm LC_CTYPE +keyword +.Cm tolower +to the corresponding lower-case character. +Characters for which no mapping is specified are not modified by this +conversion. +.It Cm ucase +Maps lower-case characters specified by the +.Cm LC_CTYPE +keyword +.Cm toupper +to the corresponding upper-case character. +Characters for which no mapping is specified are not modified by this +conversion. +.El +.Pp +The +.Cm lcase +and +.Cm ucase +symbols are mutually exclusive. +.Bl -hang +.It Cm swab +Swaps every pair of input bytes. +If the current input record is an odd number of bytes, the last byte in the +input record is ignored. +.It Cm noerror +Does not stop processing on an input error. +When an input error occurs, a diagnostic message is written on standard error, +followed by the current input and output block counts in the same format as +used at completion. +If the +.Cm sync +conversion is specified, the missing input is replaced with null +bytes and processed normally. +Otherwise, the input block will be omitted from the output. +.It Cm notrunc +Does not truncate the output file. +Preserves blocks in the output file not explicitly written by this invocation +of +.Nm . +(See also the preceding +.Cm of Ns = Ns Ar file +operand.) +.It Cm sync +Pads every input block to the size of the +.Cm ibs Ns = +buffer, appending null bytes. +(If either +.Cm block +or +.Cm unblock +is also specified, appends +.Cm SPACE +characters, rather than null bytes.) +.El +.It Cm iflag Ns = Ns Ar value Ns Op , Ns Ar value ... +.Pp +Where +.Ar value Ns +s are comma-separated symbols from the following list which +affect the behavior of reading from the input file: +.Bl -hang +.It Cm fullblock +Accumulate full blocks of input. +.El +.It Cm oflag Ns = Ns Ar value Ns Op , Ns Ar value ... +.ad +.sp .6 +Where +.Ar value Ns +s are comma-separated symbols from the following list which +affect the behavior of writing the output file: +.Bl -hang +.It Cm dsync +The output file is opened with the +.Cm O_DSYNC +flag set. +All data writes will be synchronous. +For more information on +.Cm O_DSYNC +see +.Xr fcntl.h 3HEAD . +.It Cm sync +The output file is opened with the +.Cm O_SYNC . +All data and metadata writes will be synchronous. +For more information on +.Cm O_SYNC +see +.Xr fcntl.h 3HEAD . +.El +.It Cm status Ns = Ns Ar type +Changes the way that +.Nm +outputs information about transfers. +Only one +.Ar type may be specified. +The following are valid values for +.Ar type : +.Bl -hang +.It Cm none +The program will not output any information and statistics about the transfer. +This includes when +.Nm +receives a signal such as +.Dv SIGINFO +and +.Dv SIGUSR1 . +Only errors will be emitted. +.It Cm noxfer +When printing statistical information such as when the program terminates or in +response to a signal, only print information about the number of records and +none of the statistics about the transfer +.Pq total bytes, total time, and throughput . +.It Cm progress +Once a second, output the normal +.Nm +transfer statistics that include the total number of bytes transferred, time +elapsed, and average throughput. +.El +.El +.Pp +If operands other than +.Cm conv Ns = +and +.Cm oflag Ns = +are specified more than once, the last specified +.Cm operand Ns = Ns Ar value +is used. +.Pp +For the +.Cm bs Ns = , +.Cm cbs Ns = , +.Cm ibs Ns = , +and +.Cm obs Ns = +operands, the application must supply an expression specifying a size in bytes. +The expression, +.Cm expr , +can be: +.Bl -enum -offset indent -compact +.It +a positive decimal number +.Pp +.It +a positive decimal number followed by +.Sy k , +specifying multiplication by 1024 +.Pp +.It +a positive decimal number followed by +.Sy M , +specifying multiplication by 1024*1024 +.Pp +.It +a positive decimal number followed by +.Sy G , +specifying multiplication by 1024*1024*1024 +.Pp +.It +a positive decimal number followed by +.Sy T , +specifying multiplication by 1024*1024*1024*1024 +.Pp +.It +a positive decimal number followed by +.Sy P , +specifying multiplication by 1024*1024*1024*1024*1024 +.Pp +.It +a positive decimal number followed by +.Sy E , +specifying multiplication by 1024*1024*1024*1024*1024*1024 +.Pp +.It +a positive decimal number followed by +.Sy Z , +specifying multiplication by 1024*1024*1024*1024*1024*1024*1024 +.Pp +.It +a positive decimal number followed by +.Sy b , +specifying multiplication by 512 +.Pp +.It +two or more positive decimal numbers (with or without +.Sy k +or +.Sy b ) +separated by +.Sy x , +specifying the product of the indicated values. +.El +.Pp +All of the operands will be processed before any input is read. +.Sh SIGNALS +When +.Nm +receives either SIGINFO or SIGUSR1, +.Nm +will emit the current input and output block counts, total bytes written, +total time elapsed, and the number of bytes per second to standard error. +This is the same information format that +.Nm +emits when it successfully completes. +Users may send SIGINFO via their terminal. +The default character is ^T, see +.Xr stty 1 +for more information. +.Pp +For +.Sy SIGINT , +.Nm +writes status information to standard error before exiting. +.Nm +takes the standard action for all other signals. +.Sh USAGE +See +.Xr largefile 7 +for the description of the behavior of +.Nm +when encountering files greater than or equal to 2 Gbyte (2^31 bytes). +.Sh EXIT STATUS +The following exit values are returned: +.Bl -tag -width ".It Cm >0" +.It Cm 0 +The input file was copied successfully. +.It Cm >0 +An error occurred. +.El +.Pp +If an input error is detected and the +.Cm noerror +conversion has not been specified, any partial output block will be written +to the output file, a diagnostic message will be written, and the copy +operation will be discontinued. +If some other error is detected, a diagnostic message will be +written and the copy operation will be discontinued. +.Sh EXAMPLES +.Bl -ohang +.It Sy Example 1 No Copying from one tape drive to another +.Pp +The following example copies from tape drive +.Sy 0 +to tape drive +.Sy 1 , +using a common historical device naming convention. +.Pp +.Dl % dd if=/dev/rmt/0h of=/dev/rmt/1h +.It Sy Example 2 No Stripping the first 10 bytes from standard input +.Pp +The following example strips the first 10 bytes from standard input: +.Pp +.Dl % dd ibs=10 skip=1 +.It Sy Example 3 No Reading a tape into an ASCII file +.Pp +This example reads an +.Cm EBCDIC +tape blocked ten 80-byte +.Cm EBCDIC +card images per block into the +.Cm ASCII +file +.Sy x : +.Pp +.Dl % dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase +.It Sy Example 4 No Using conv=sync to write to tape +.Pp +The following example uses +.Cm conv Ns = Ns Ar sync +when writing to a tape: +.Pp +.Dl % tar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync +.El +.Sh DIAGNOSTICS +.Bl -hang +.It Sy f+p records in(out) +numbers of full and partial blocks read(written) +.El +.Sh ENVIRONMENT VARIABLES +See +.Xr environ 7 +for descriptions of the following environment variables +that affect the execution of +.Nm : +.Ev LANG , +.Ev LC_ALL , +.Ev LC_CTYPE , +.Ev LC_MESSAGES , +and +.Ev NLSPATH . +.Sh INTERFACE STABILITY +Standard +.Sh SEE ALSO +.Xr cp 1 , +.Xr sed 1 , +.Xr tr 1 , +.Xr fcntl.h 3HEAD , +.Xr attributes 7 , +.Xr environ 7 , +.Xr largefile 7 , +.Xr standards 7 +.Sh NOTES +Do not use +.Nm +to copy files between file systems having different block sizes. +.Pp +Using a blocked device to copy a file will result in extra nulls being added +to the file to pad the final block to the block boundary. +.Pp +When +.Nm +reads from a pipe, using the +.Cm ibs Ns = Ns Ar X +and +.Cm obs Ns = Ns Ar Y +operands, the output will always be blocked in chunks of size Y. +When +.Cm bs Ns = Ns Ar Z +is used, the output blocks will be whatever was available to be read +from the pipe at the time. +.Pp +When using +.Nm +to copy files to a tape device, the file size must be a multiple of the +device sector size (for example, 512 Kbyte). +To copy files of arbitrary size to a tape device, use +.Xr tar 1 +or +.Xr cpio 1 . |