The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group

 NAME

cut - cut out selected fields of each line of a file

 SYNOPSIS



cut -b list [-n] [file ...]

cut -c list [file ...]

cut -f list [-d delim][-s][file ...]

 DESCRIPTION

The cut utility will cut out bytes (-b option), characters (-c option) or character-delimited fields (-f option) from each line in one or more files, concatenate them and write them to standard output.

 OPTIONS

The cut utility supports the XBD specification, Utility Syntax Guidelines  .

The option-argument list (see options -b, -c and -f below) must be a comma-separated list or blank-character-separated list of positive numbers and ranges. Ranges can be in three forms. The first is two positive numbers separated by a hyphen (low-high), which represents all fields from the first number to the second number. The second is a positive number preceded by a hyphen (-high), which represents all fields from field number 1 to that number. The third is a positive number followed by a hyphen (low-), which represents that number to the last field, inclusive. The elements in list can be repeated, can overlap and can be specified in any order.

The following options are supported:

-b list
Cut based on a list of bytes. Each selected byte will be output unless the -n option is also specified. It is not an error to select bytes not present in the input line.
-c list
Cut based on a list of characters. Each selected character is output. It is not an error to select characters not present in the input line.
-d delim
Set the field delimiter to the character delim. The default is the tab character.
-f list
Cut based on a list of fields, assumed to be separated in the file by a delimiter character (see -d). Each selected field will be output. Output fields will be separated by a single occurrence of the field delimiter character. Lines with no field delimiters will be passed through intact, unless -s is specified. It is not an error to select fields not present in the input line.
-n
Do not split characters. When specified with the -b option, each element in list of the form low-high (hyphen-separated numbers) will be modified as follows:
  • If the byte selected by low is not the first byte of a character, low will be decremented to select the first byte of the character originally selected by low. If the byte selected by high is not the last byte of a character, high will be decremented to select the last byte of the character prior to the character originally selected by high, or zero if there is no prior character. If the resulting range element has high equal to zero or low greater than high, the list element will be dropped from list for that input line without causing an error.
Each element in list of the form low- will be treated as above with high set to the number of bytes in the current line, not including the terminating newline character. Each element in list of the form -high will be treated as above with low set to 1. Each element in list of the form num (a single number) will be treated as above with low set to num and high set to num.
-s
Suppress lines with no delimiter characters, when used with the -f option. Unless specified, lines with no delimiters will be passed through untouched.

 OPERANDS

The following operands are supported:
file
A pathname of an input file. If no file operands are specified, or if a file operand is "-", the standard input will be used.

 STDIN

The standard input will be used only if no file operands are specified, or if a file operand is "-". See the INPUT FILES section.

 INPUT FILES

The input files must be text files, except that line lengths are unlimited.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of cut:
LANG
Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.
LC_ALL
If set to a non-empty string value, override the values of all the other internationalisation variables.
LC_CTYPE
Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files).
LC_MESSAGES
Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
NLSPATH
Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

The cut utility output will be a concatenation of the selected bytes, characters or fields (one of the following):

"%s\n", <concatenation of bytes>

"%s\n", <concatenation of characters>

"%s\n", <concatenation of fields and field delimiters>

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:
0
All input files were output successfully.
>0
An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

Earlier versions of the cut utility worked in an environment where bytes and characters were considered equivalent (modulo backspace and tab character processing in some implementations). In the extended world of multi-byte characters, the new -b option has been added. The -n option (used with -b) allows it to be used to act on bytes rounded to character boundaries. The algorithm specified for -n guarantees that:

cut -b 1-500 -n file > file1
cut -b 501- -n file > file2

will end up with all the characters in file appearing exactly once in file1 or file2. (There is, however, a newline character in both file1 and file2 for each newline character in file.)

 EXAMPLES

Examples of the option qualifier list:
1,4,7
Select the first, fourth and seventh bytes, characters, or fields and field delimiters.
1-3,8
Equivalent to 1,2,3,8.
-5,10
Equivalent to 1,2,3,4,5,10.
3-
Equivalent to third to last, inclusive.

The low-high forms are not always equivalent when used with -b and -n and multi-byte characters. See the description of -n.

The following command:


cut -d : -f 1,6 /etc/passwd

reads the System V password file (user database) and produces lines of the form:


<user ID>:<home directory>

Most utilities in this specification work on text files. The cut utility can be used to turn files with arbitrary line lengths into a set of text files containing the same data. The paste utility can be used to create (or recreate) files with arbitrary line lengths. For example, if file contains long lines:


cut -b 1-500 -n file > file1
cut -b 501- -n file > file2

creates file1 (a text file) with lines no longer than 500 bytes (plus the newline character and file2 that contains the remainder of the data from file. (Note that file2 will not be a text file if there are lines in file that are longer than 500 + {LINE_MAX} bytes.) The original file can be recreated from file1 and file2 using the command:

paste -d "\0" file1 file2 > file

 FUTURE DIRECTIONS

None.

 SEE ALSO

grep, paste, Parameters and Variables .

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]