Annotation of src/usr.bin/cut/cut.1, Revision 1.26
1.26 ! schwarze 1: .\" $OpenBSD: cut.1,v 1.25 2015/12/02 00:56:46 schwarze Exp $
1.1 deraadt 2: .\" $NetBSD: cut.1,v 1.6 1995/10/02 20:19:26 jtc Exp $
3: .\"
4: .\" Copyright (c) 1989, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to Berkeley by
8: .\" the Institute of Electrical and Electronics Engineers, Inc.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
1.8 millert 18: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
34: .\" @(#)cut.1 8.1 (Berkeley) 6/6/93
35: .\"
1.26 ! schwarze 36: .Dd $Mdocdate: December 2 2015 $
1.1 deraadt 37: .Dt CUT 1
38: .Os
39: .Sh NAME
40: .Nm cut
41: .Nd select portions of each line of a file
42: .Sh SYNOPSIS
43: .Nm cut
44: .Fl b Ar list
45: .Op Fl n
46: .Op Ar
47: .Nm cut
48: .Fl c Ar list
49: .Op Ar
50: .Nm cut
51: .Fl f Ar list
1.13 sobrado 52: .Op Fl s
1.1 deraadt 53: .Op Fl d Ar delim
54: .Op Ar
55: .Sh DESCRIPTION
56: The
1.5 aaron 57: .Nm
1.1 deraadt 58: utility selects portions of each line (as specified by
1.6 aaron 59: .Ar list )
1.1 deraadt 60: from each
61: .Ar file
1.21 sobrado 62: and writes them to the standard output.
63: If no
64: .Ar file
65: arguments are specified, or a file argument is a single dash
66: .Pq Sq \- ,
67: .Nm
68: reads from the standard input.
1.1 deraadt 69: The items specified by
70: .Ar list
71: can be in terms of column position or in terms of fields delimited
1.6 aaron 72: by a special character.
1.24 jmc 73: Column and field numbering starts from 1;
74: output is in the same order as input, not in the order selected.
1.1 deraadt 75: .Pp
1.3 aaron 76: .Ar list
1.16 schwarze 77: is a comma or whitespace separated set of numbers and/or
1.1 deraadt 78: number ranges.
79: Number ranges consist of a number, a dash
1.3 aaron 80: .Pq Sq \- ,
1.1 deraadt 81: and a second number
1.6 aaron 82: which select the fields or columns from the first number to the second,
1.1 deraadt 83: inclusive.
84: Numbers or number ranges may be preceded by a dash, which selects all
85: fields or columns from 1 to the first number.
86: Numbers or number ranges may be followed by a dash, which selects all
87: fields or columns from the last number to the end of the line.
88: Numbers and number ranges may be repeated, overlapping, and in any order.
89: It is not an error to select fields or columns not present in the
90: input line.
1.23 tedu 91: .Pp
1.1 deraadt 92: The options are as follows:
1.7 aaron 93: .Bl -tag -width Ds
1.1 deraadt 94: .It Fl b Ar list
1.4 aaron 95: The
1.1 deraadt 96: .Ar list
97: specifies byte positions.
98: .It Fl c Ar list
99: The
100: .Ar list
101: specifies character positions.
1.10 jmc 102: .It Fl d Ar delim
1.1 deraadt 103: Use the first character of
1.10 jmc 104: .Ar delim
1.14 jmc 105: as the field delimiter character.
106: The default is the
107: .Aq TAB
108: character.
1.1 deraadt 109: .It Fl f Ar list
110: The
111: .Ar list
1.14 jmc 112: specifies fields, separated by the field delimiter character.
113: The selected fields are output,
114: separated by the field delimiter character.
1.1 deraadt 115: .It Fl n
116: Do not split multi-byte characters.
1.25 schwarze 117: A character is written to standard output if and only if the byte
118: position holding its last byte is selected.
1.1 deraadt 119: .It Fl s
120: Suppresses lines with no field delimiter characters.
121: Unless specified, lines with no delimiters are passed through unmodified.
122: .El
1.26 ! schwarze 123: .Sh ENVIRONMENT
! 124: .Bl -tag -width LC_CTYPE
! 125: .It Ev LC_CTYPE
! 126: The character set
! 127: .Xr locale 1 ,
! 128: defining which byte sequences form characters.
! 129: If unset or set to
! 130: .Qq C ,
! 131: .Qq POSIX ,
! 132: or an unsupported value,
! 133: .Fl c
! 134: does the same as
! 135: .Fl b ,
! 136: .Fl n
! 137: has no effect, and
! 138: .Fl d
! 139: uses the first byte of
! 140: .Ar delim .
! 141: .El
1.17 jmc 142: .Sh EXIT STATUS
1.22 jmc 143: The
144: .Nm
145: utility exits 0 if all input files are output successfully,
146: and >0 if an error occurs.
1.9 jmc 147: .Sh EXAMPLES
148: Extract login names and shells from the system
149: .Xr passwd 5
150: file as
151: .Dq name:shell
152: pairs:
153: .Pp
154: .Dl "$ cut -d : -f 1,7 /etc/passwd"
155: .Pp
156: Show the names and login times of logged in users:
157: .Pp
1.20 sobrado 158: .Dl "$ who | cut -c 1-8,18-30"
1.1 deraadt 159: .Sh SEE ALSO
1.23 tedu 160: .Xr awk 1 ,
1.1 deraadt 161: .Xr paste 1
162: .Sh STANDARDS
163: The
1.5 aaron 164: .Nm
1.11 jmc 165: utility is compliant with the
1.15 jmc 166: .St -p1003.1-2008
1.11 jmc 167: specification.