EXTRACT(1)

NAME

extract - extract byte ranges from file or stream

SYNOPSIS

extract [ -nv ] ranges [ files ]
extract [ -nv ] -f frombyte -t tobyte [ files ]

DESCRIPTION

extract extracts selected ranges of bytes, from standard input or named files. Byte numbers are 1-based (but see the -s option below).

The byte ranges to be extracted may be specified in several ways. First (though this is somewhat of a special case), a single numeric argument on the command line requests that a simple initial prefix of the input, n bytes long, be extracted. For example,

	extract 10 inputfile

would extract the first 10 bytes of the file named inputfile.

More generally, byte ranges may be selected using the notation m-n. Multiple ranges may be separated by commas, or entered as separate arguments. For example, the invocation

	extract 10-20 inputfile

would extract bytes 10 through 20 of inputfile.

In the m-n notation, either m or n (but not both) may be omitted. The notation -n means from the beginning of the file up to byte n. The notation m- means from byte m to the end of the file.

Because multiple byte numbers may be entered as separate arguments, there is an ambiguity if an input filename has a name which looks like a number. To resolve the ambiguity, use an alternative pathname for the file which does not begin with a digit. The simplest way to do so is to precede the numeric filename with ``./''.

OPTIONS

-v: Invert; extract all bytes not selected.
-version: Print program's version number.
-?,-h: Print a brief help message.

ALTERNATIVE BYTE NUMBER SELECTION OPTIONS

It is also possible to specify byte numbers or ranges using explicit option flags:

-f n

(``from'') Start extracting at byte n.

-s n

(``seek'') Start extracting at lseek(2) offset n, that is, just after byte number n. (-s n is therefore equivalent to -f n+1.)

-t n

(``to'') Stop extracting at byte n.

-e n

(``end'') Stop extracting just before byte n, that is, at byte n-1.

-p n

(``plus'') Extract n bytes past the last-specified start byte. That is,

	-f m -p n

is equivalent to

	-f m -t m+n-1

(or to -f m -e m+n ).

Any number of -f, -s, -t, -e, and -p options may appear. When these options are used, lone numbers on the command line are not interpreted as byte numbers or ranges, and are therefore unambiguously usable as filenames.

The -f, -s, -t, -e, and -p options are intended for use in shell scripts, when a complicated set of byte number ranges is being built up on-the-fly, and when constructing a single string containing many dashes and commas would be even more cumbersome.

MORE DESCRIPTION

When extract is invoked with multiple input filenames, the specified bytes are selected from all files. For example,

	extract 5-10 a b c

would extract bytes 5 through 10 of file a, followed by bytes 5 through 10 of file b, followed by bytes 5 through 10 of file c. To select bytes from the concatenation of many input files, use cat(1) and a pipeline:

	cat a b c | extract 5-10

The m-n byte-selection syntax also supports ``relative'' (counted) range increments, analogous to the -p option. The notation m:n is equivalent to m-m+n-1. For example, the invocation

	extract 5:10 inputfile

would extract 10 bytes beginning with byte 5 (that is, bytes 5 through 14)

extract can extract individual bytes, although this is infrequently useful. For example,

	extract 1,5,10-20

would extract bytes 1, 5, and 10 through 20. There is another ambiguity, however, since a single number n (as discussed above) selects bytes 1-n. To select byte n and only byte n, use the degenerate range n-n.

HISTORY

extract is closely related to the line program, and in fact shares its source code.

This documentation corresponds to version 2.3 of the program.

See http://www.eskimo.com/~scs/src/#extract for possible updates.

AUTHOR

Steve Summit, scs@eskimo.com