Annotation of src/usr.bin/cut/cut.1, Revision 1.23
1.23 ! tedu 1: .\" $OpenBSD: cut.1,v 1.22 2014/02/02 14:16:22 jmc 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.23 ! tedu 36: .Dd $Mdocdate: February 2 2014 $
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.19 jmc 73: Column and field numbering starts from 1.
1.1 deraadt 74: .Pp
1.3 aaron 75: .Ar list
1.16 schwarze 76: is a comma or whitespace separated set of numbers and/or
1.1 deraadt 77: number ranges.
78: Number ranges consist of a number, a dash
1.3 aaron 79: .Pq Sq \- ,
1.1 deraadt 80: and a second number
1.6 aaron 81: which select the fields or columns from the first number to the second,
1.1 deraadt 82: inclusive.
83: Numbers or number ranges may be preceded by a dash, which selects all
84: fields or columns from 1 to the first number.
85: Numbers or number ranges may be followed by a dash, which selects all
86: fields or columns from the last number to the end of the line.
87: Numbers and number ranges may be repeated, overlapping, and in any order.
88: It is not an error to select fields or columns not present in the
89: input line.
90: .Pp
1.23 ! tedu 91: Fields are output in the same order as input, not in the order selected.
! 92: .Pp
1.1 deraadt 93: The options are as follows:
1.7 aaron 94: .Bl -tag -width Ds
1.1 deraadt 95: .It Fl b Ar list
1.4 aaron 96: The
1.1 deraadt 97: .Ar list
98: specifies byte positions.
99: .It Fl c Ar list
100: The
101: .Ar list
102: specifies character positions.
1.10 jmc 103: .It Fl d Ar delim
1.1 deraadt 104: Use the first character of
1.10 jmc 105: .Ar delim
1.14 jmc 106: as the field delimiter character.
107: The default is the
108: .Aq TAB
109: character.
1.1 deraadt 110: .It Fl f Ar list
111: The
112: .Ar list
1.14 jmc 113: specifies fields, separated by the field delimiter character.
114: The selected fields are output,
115: separated by the field delimiter character.
1.1 deraadt 116: .It Fl n
117: Do not split multi-byte characters.
118: .It Fl s
119: Suppresses lines with no field delimiter characters.
120: Unless specified, lines with no delimiters are passed through unmodified.
121: .El
1.17 jmc 122: .Sh EXIT STATUS
1.22 jmc 123: The
124: .Nm
125: utility exits 0 if all input files are output successfully,
126: and >0 if an error occurs.
1.9 jmc 127: .Sh EXAMPLES
128: Extract login names and shells from the system
129: .Xr passwd 5
130: file as
131: .Dq name:shell
132: pairs:
133: .Pp
134: .Dl "$ cut -d : -f 1,7 /etc/passwd"
135: .Pp
136: Show the names and login times of logged in users:
137: .Pp
1.20 sobrado 138: .Dl "$ who | cut -c 1-8,18-30"
1.1 deraadt 139: .Sh SEE ALSO
1.23 ! tedu 140: .Xr awk 1 ,
1.1 deraadt 141: .Xr paste 1
142: .Sh STANDARDS
143: The
1.5 aaron 144: .Nm
1.11 jmc 145: utility is compliant with the
1.15 jmc 146: .St -p1003.1-2008
1.11 jmc 147: specification.
1.16 schwarze 148: .Sh CAVEATS
149: The current implementation does not support multi-byte characters.
150: Consequently
151: .Fl c
152: does the same as
153: .Fl b ,
154: and
155: .Fl n
156: has no effect.