|
|
| |
RW(1) |
FreeBSD General Commands Manual |
RW(1) |
rw —
blockwise input/output
rw |
[-afhPstvx ] [-b
block-size] [-c
count] [-I
input-offset] [-i
input-file] [-O
output-offset] [-o
output-file] [-p
period] [-r
input-block-size] [-w
output-block-size] |
rw reads blocks from the standard input and copies them
to the standard output until the end of the standard input. The input and
output block sizes default to appropriate values for efficiently reading from
the input and writing to the output. Input and output will be done as aligned
as possible on the block size boundaries. The final input block can be
partial. Output blocks are written whenever enough input blocks have been
read, or partially written whenever the end of the input is reached. The
output file is not truncated after the copy is done.
Byte quantities can be specified as a non-negative count of bytes
in decimal format, hexadecimal format (with leading 0x),
or octal format (with leading 0); optionally followed by
any amount of whitespace, and then suffixed with any of the following
case-insensitive suffixes that multiplies the specified quantity by that
magnitude:
- B
- Magnitude of a byte (1 byte).
- K, KiB
- Magnitude of kibibytes (1,024 bytes).
- M, MiB
- Magnitude of mebibytes (1,048,576 bytes).
- G, GiB
- Magnitude of gibibytes (1,073,741,824 bytes).
- T, TiB
- Magnitude of tebibytes (1,099,511,627,776 bytes).
- P, PiB
- Magnitude of pebibytes (1,125,899,906,842,624 bytes).
- E, EiB
- Magnitude of exbibytes (1,152,921,504,606,846,976 bytes).
- r
- Magnitude of input blocks (the default input block size when setting block
sizes).
- w
- Magnitude of output blocks (the default output block size when setting
block sizes
- x
- Magnitude of input and output blocks (if they have the same size) (the
default block size when setting block sizes).
The options are as follows:
-a
- In combination with
-o , open the output file in
append mode. This option must be used with -o and
is incompatible with -t . The output offset is set
to the size of the output file.
-b
block-size
- Set both the input and output block sizes to the byte quantity specified
by block-size.
-c
count
- Stop after copying the byte quantity specified by
count, in addition to stopping when the end of the
input is reached. If the count starts with a leading
‘-’, stop that many bytes before the end of the input (only
works if the input size is known).
-f
- Continue as much as possible in the event of I/O errors and exit
unsuccessfully afterwards. For each input failure, skip forward to the
next input block or the next native-size input block or the end of the
file (whichever comes first), write an error to the standard error, and
replace the failed input with NUL bytes when writing it to the output. For
each output failure, skip forward to the next output block or the next
native-size output block (whichever comes first) and write an error to the
standard error. The native-size input and output blocks are those defined
by the preferred input/output size for the input and output. This option
only works for the input if it is seekable and the input size is known.
This option only works for the output if it is seekable (and
-a is not set). Beware that the default preferred
input/output sizes may be larger than the underlying storage sector sizes:
If this option is used, the -r and
-w options should be set to the appropriate
input/output sector sizes, or more than just the bad sector may be
skipped.
-h
- Write statistics in the human readable format where byte amounts and time
amounts are formatted according to their magnitude as described in the
DIAGNOSTICS section.
-I
offset
- Skip past the first offset bytes in the input before
the copying begins. If the offset starts with a
leading ‘-’ it is interpreted as that many bytes before the
end of the input (if the size is known), and if it starts with a leading
‘+’ it is interpreted as that many bytes after the end of
the input (if the size is known). If the input is not seekable, the first
offset bytes are read and discarded before the
copying begins. If the offset is not a multiple of
the input block size, the first input block is reduced in size such that
it ends at an input-block-size-aligned position in the input.
-i
input-file
- Read the input from input-file instead of the
standard input.
-O
offset
- Seek past the first offset bytes in the output
before the copying begins. If the offset starts with
a leading ‘-’ it is interpreted as that many bytes before
the end of the output (if the size is known), and if it starts with a
leading ‘+’ it is interpreted as that many bytes after the
end of the output (if the size is known). If the output is not seekable,
the number of NUL bytes specified in offset are
written to the output before the copying begins. This option cannot be set
to a non-zero value if
-a is set. If the
offset is not a multiple of the output block size,
the first output block is reduced in size such that it ends at a output
block size aligned position in the output.
-o
output-file
- Write the output to output-file instead of the
standard output, creating the file if it doesn't exist. If
output-file already exists, the existing data is not
discarded. Use
-t if you want to truncate the
output afterwards.
-P
- Pad the final output block with NUL bytes, such that the final output
offset (counting the initial offset with
-O ) is a
multiple of the output block size.
-p
period
- Write occasional statistics to the standard error during the transfer and
on completion, or when being terminated by
SIGINT .
period specifies the period in whole seconds at
which statistics are written out. Statistics are written for every read
and write if the period is zero. The format is
described in the DIAGNOSTICS
section.
-r
input-block-size
- Set the input block size to the byte quantity specified by
input-block-size.
-s
- Sync the output on successful completion.
-t
- Truncate the output to the final output position after the copy has
completed. This option requires the output to be truncatable. This option
is incompatible with
-a .
-v
- Write statistics to the standard error upon completion, or when being
terminated by
SIGINT . The format is described in
the DIAGNOSTICS section.
-w
output-block-size
- Set the output block size to the byte quantity specified by
output-block-size.
-x
- In combination with
-o , fail if the output file
already exists.
SIGINFO
- Write statistics to the standard error and continue the copy. To disable
the handling of this signal, ignore the signal before loading this
program. This signal does not exist on every operating system.
SIGINT
- If
-v or -p is set, abort
the copy, write statistics to the standard error, and then exit as if
killed by SIGINT .
SIGUSR1
- Write statistics to the standard error and continue the copy. If
SIGUSR1 is not ignored, this handler is installed
and this signal is unblocked. To use this signal without a race condition
before the signal handler is installed (as SIGUSR1
is deadly by default), block the signal before loading this program. To
disable the handling of this signal, ignore the signal before loading this
program.
rw will exit 0 on success and non-zero otherwise.
Copy from the standard input to the standard output:
Copy the first 256 bytes from the input to the output:
Copy from the input file foo to the
beginning of the output file bar (preserving any
data in the output file beyond the final output position after the copy is
finished).
Copy from the input file to the beginning of the output file,
truncating the output file to the final output position afterwards:
Copy from the input file foo to the
beginning of the output block device /dev/bar
(preserving any existing data on the output block device beyond the copied
area), while writing progress statistics every 10 seconds in the human
readable format, and sync the output block device afterwards:
rw -i foo -o /dev/bar -p 10 -h -s
Skip the first 512 bytes of the input, and then append the next
1024 bytes to the output file bar:
rw -I 512 -c 1024 -o bar -a
Copy 2 KiB from offset 768 in the input file
foo to offset 256 MiB in the output file
bar.
rw -c 2K -i foo -I 768 -o bar -O 256M
Copy from sector 32 and 4 sectors onwards from a block device
/dev/foo (with the sector size being 512 bytes) to
the output file bar:
rw -r 512 -i /dev/foo -I 32r -c 4r -o bar
With a block size of 4096 bytes, copy 64 blocks from the input
from offset 32 blocks in the input to offset 65536 blocks in the output:
rw -b 4096 -c 64x -I 32x -O 65536x
Back up the /dev/foo block device (with
the sector size being 512 bytes) to the bar output
file, continuing despite I/O errors by writing error messages to the
standard error and writing NUL bytes to the output instead, truncating the
output file to the size of the input, writing progress statistics every 10
seconds in the human readable format to the standard error:
rw -f -i /dev/foo -r 512 -o bar -t -p 10 -h
With the input block size of 512 bytes and the output block size
of 8192 bytes, copy 16384 input blocks from input block 65536 onwards to
output block 1048576:
rw -r 512 -w 8192 -c 16384r -I 65536r -O 1048576w
Copy 512 bytes from 1024 bytes before the end of the input to 2048
bytes after the current size of the output file:
rw -c 512 -I -1024 -o bar -O +2048
Skip the first 100 bytes of the input and copy until 200 bytes are
left in the input file:
Statistics about the copy are written to the standard error upon completion if
either -v or -p are set;
occasionally if -p is set; upon
SIGINT (if not ignored when the program was loaded) if
-v is set; and upon SIGUSR1
(if not ignored when the program was loaded).
The statistics are in this format:
<time-elapsed> s <done> B / <total> B <percent>% <speed> B/s <time-left> s
time-elapsed is the number of seconds since
the copying began. done is the number of bytes copied
so far. total is an estimate of how many bytes will be
copied, or ‘?’ if not known. percent is
how many percent complete the copy is, or ‘?’ if not known.
speed is the average speed of copying so far in bytes
per second, or ‘?’ if it is too early to tell.
time-left is the number of seconds left, assuming the
remaining data is copied at the current average speed, or ‘?’
is not known.
For instance, the statistics could look like this:
7 s 714682368 B / 1238364160 B 57% 102097481 B/s 5 s
The statistics are printed with human readable byte units (B, KiB,
MiB, GiB, TiB, PiB, EiB) and time units (s, m, h, d) if the
-h option is set:
7 s 714.4 MiB / 1.1 GiB 60% 102.0 MiB/s 4 s
rw originally appeared in Sortix 1.1.
rw is similar to
dd(1), but
has a distinct design and improvements:
- The command line options use the conventional option format.
- The output file is not truncated by default. One has to use
-t .
- The input and output block sizes default to the preferred I/O block sizes
instead of 512 bytes.
The -c , -I ,
and -O options accept byte quantities by default
instead of block counts, but can be specified in block counts by using
the ‘r, w’, and ‘x’ suffixes.
- Statistics are not written by default. One has to use
-v or -p . The statistics
contain more useful information and is machine readable as it contains no
localized information. A human readable statistics format is available
using -h . Statistics can occasionally be written
out using -p .
- There is no support for converting ASCII to EBCDIC, converting ASCII to a
different EBCDIC, EBCDIC to ASCII, swapping pairs of bytes, converting the
bytes to lower-case or upper-case, converting line-delimited data into
fixed-size blocks, or converting fixed-sized blocks into line-delimited
data.
- Offsets can be specified relative to the end of the input/output.
- Input errors stop the copying immediately rather than writing out a
partial output block.
rw is not yet able to determine the size of block
devices on Illumos, Minix, NetBSD, and OpenBSD.
rw does not handle tape archives
specially, as
dd(1) does
on some operating systems.
rw does not support copying sparse files,
a feature found on some operating systems.
rw does not work around buggy operating
systems that may report the preferred IO block size
st_blksize as 0 for some files.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |