Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RW(1)			FreeBSD	General	Commands Manual			 RW(1)

NAME
     rw	-- blockwise input/output

SYNOPSIS
     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]

DESCRIPTION
     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 in-
     put 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 dec-
     imal 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 multi-
     plies 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 ad-
	       dition to stopping when the end of the input is reached.	 If
	       the count starts	with a leading `-', stop that many bytes be-
	       fore 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 fail-
	       ure, 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 mag-
	       nitude as described in the DIAGNOSTICS section.

     -I	offset
	       Skip past the first offset bytes	in the input before the	copy-
	       ing begins.  If the offset starts with a	leading	`-' it is in-
	       terpreted 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 copy-
	       ing begins.  If the offset starts with a	leading	`-' it is in-
	       terpreted 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 be-
	       fore 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	multi-
	       ple 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 statis-
	       tics 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 truncat-
	       able.  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.

ASYNCHRONOUS EVENTS
     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 oper-
	      ating 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 condi-
	      tion before the signal handler is	installed (as SIGUSR1 is
	      deadly by	default), block	the signal before loading this pro-
	      gram.  To	disable	the handling of	this signal, ignore the	signal
	      before loading this program.

EXIT STATUS
     rw	will exit 0 on success and non-zero otherwise.

EXAMPLES
     Copy from the standard input to the standard output:

     rw

     Copy the first 256	bytes from the input to	the output:

     rw	-c 256

     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).

     rw	-i foo -o bar

     Copy from the input file to the beginning of the output file, truncating
     the output	file to	the final output position afterwards:

     rw	-i foo -o bar -t

     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 off-
     set 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	in-
     stead, 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:

     rw	-i foo -I 100 -c -200

DIAGNOSTICS
     Statistics	about the copy are written to the standard error upon comple-
     tion 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

SEE ALSO
     cat(1), cp(1), dd(1)

HISTORY
     rw	originally appeared in Sortix 1.1.

     rw	is similar to dd(1), but has a distinct	design and improvements:

     +o	 The command line options use the conventional option format.

     +o	 The output file is not	truncated by default.  One has to use -t.

     +o	 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.

     +o	 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.

     +o	 There is no support for converting ASCII to EBCDIC, converting	ASCII
	 to a different	EBCDIC,	EBCDIC to ASCII, swapping pairs	of bytes, con-
	 verting the bytes to lower-case or upper-case,	converting line-delim-
	 ited data into	fixed-size blocks, or converting fixed-sized blocks
	 into line-delimited data.

     +o	 Offsets can be	specified relative to the end of the input/output.

     +o	 Input errors stop the copying immediately rather than writing out a
	 partial output	block.

BUGS
     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 operat-
     ing systems.

     rw	does not support copying sparse	files, a feature found on some operat-
     ing systems.

     rw	does not work around buggy operating systems that may report the pre-
     ferred IO block size st_blksize as	0 for some files.

FreeBSD	13.0			 March 6, 2018			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | ASYNCHRONOUS EVENTS | EXIT STATUS | EXAMPLES | DIAGNOSTICS | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rw&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help