26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved
46 .\"
47 .TH CUT 1 "Apr 29, 1999"
48 .SH NAME
49 cut \- cut out selected fields of each line of a file
50 .SH SYNOPSIS
51 .LP
52 .nf
53 \fBcut\fR \fB-b\fR \fIlist\fR [\fB-n\fR] [\fIfile\fR]...
54 .fi
55
56 .LP
57 .nf
58 \fBcut\fR \fB-c\fR \fIlist\fR [\fIfile\fR]...
59 .fi
60
61 .LP
62 .nf
63 \fBcut\fR \fB-f\fR \fIlist\fR [\fB-d\fR \fIdelim\fR] [\fB-s\fR] [\fIfile\fR]...
64 .fi
65
66 .SH DESCRIPTION
67 .sp
68 .LP
69 Use the \fBcut\fR utility to cut out columns from a table or fields from each
70 line of a file; in data base parlance, it implements the projection of a
71 relation. The fields as specified by \fIlist\fR can be fixed length, that is,
72 character positions as on a punched card (\fB-c\fR option) or the length can
73 vary from line to line and be marked with a field delimiter character like TAB
74 (\fB-f\fR option). \fBcut\fR can be used as a filter.
75 .sp
76 .LP
77 Either the \fB-b\fR, \fB-c\fR, or \fB-f\fR option must be specified.
78 .sp
79 .LP
80 Use \fBgrep\fR(1) to make horizontal ``cuts'' (by context) through a file, or
81 \fBpaste\fR(1) to put files together column-wise (that is, horizontally). To
82 reorder columns in a table, use \fBcut\fR and \fBpaste\fR.
83 .SH OPTIONS
84 .sp
85 .LP
86 The following options are supported:
87 .sp
88 .ne 2
89 .na
90 \fB\fIlist\fR \fR
91 .ad
92 .RS 13n
93 A comma-separated or blank-character-separated list of integer field numbers
94 (in increasing order), with optional \fB\(mi\fR to indicate ranges (for
95 instance, \fB1,4,7\fR; \fB1\(mi3,8\fR; \fB\(mi5,10\fR (short for
96 \fB1\(mi5,10\fR); or \fB3\(mi\fR (short for third through last field)).
97 .RE
98
99 .sp
100 .ne 2
101 .na
102 \fB\fB\fR\fB-b\fR \fIlist\fR \fR
103 .ad
104 .RS 13n
105 The \fIlist\fR following \fB-b\fR specifies byte positions (for instance,
106 \fB-b1\fR\fB-72\fR would pass the first 72 bytes of each line). When \fB-b\fR
107 and \fB-n\fR are used together, \fIlist\fR is adjusted so that no multi-byte
108 character is split.
109 .RE
110
111 .sp
112 .ne 2
113 .na
114 \fB\fB\fR\fB-c\fR \fIlist\fR \fR
115 .ad
116 .RS 13n
117 The \fIlist\fR following \fB-c\fR specifies character positions (for instance,
118 \fB-c1\fR\fB-72\fR would pass the first 72 characters of each line).
119 .RE
120
121 .sp
122 .ne 2
123 .na
124 \fB\fB\fR\fB-d\fR \fIdelim\fR \fR
125 .ad
126 .RS 13n
127 The character following \fB-d\fR is the field delimiter (\fB-f\fR option only).
128 Default is \fItab\fR. Space or other characters with special meaning to the
129 shell must be quoted. \fIdelim\fR can be a multi-byte character.
130 .RE
131
132 .sp
133 .ne 2
134 .na
135 \fB\fB\fR\fB-f\fR \fIlist\fR \fR
136 .ad
137 .RS 13n
138 The \fIlist\fR following \fB-f\fR is a list of fields assumed to be separated
139 in the file by a delimiter character (see \fB-d\fR ); for instance,
140 \fB-f1\fR\fB,7\fR copies the first and seventh field only. Lines with no field
141 delimiters will be passed through intact (useful for table subheadings), unless
142 \fB-s\fR is specified.
143 .RE
144
145 .sp
146 .ne 2
147 .na
148 \fB\fB-n\fR \fR
149 .ad
150 .RS 13n
151 Do not split characters. When \fB-b\fR \fIlist\fR and \fB-n\fR are used
152 together, \fIlist\fR is adjusted so that no multi-byte character is split.
153 .RE
154
155 .sp
156 .ne 2
157 .na
158 \fB\fB-s\fR \fR
159 .ad
160 .RS 13n
161 Suppresses lines with no delimiter characters in case of \fB-f\fR option.
162 Unless specified, lines with no delimiters will be passed through untouched.
163 .RE
164
165 .SH OPERANDS
166 .sp
167 .LP
168 The following operands are supported:
169 .sp
170 .ne 2
171 .na
172 \fB\fIfile\fR \fR
173 .ad
174 .RS 9n
175 A path name of an input file. If no \fIfile\fR operands are specified, or if a
176 \fIfile\fR operand is \fB\(mi\fR, the standard input will be used.
177 .RE
178
179 .SH USAGE
180 .sp
181 .LP
182 See \fBlargefile\fR(5) for the description of the behavior of \fBcut\fR when
183 encountering files greater than or equal to 2 Gbyte (2^31 bytes).
184 .SH EXAMPLES
185 .LP
186 \fBExample 1 \fRMapping user IDs
187 .sp
188 .LP
189 A mapping of user \fBIDs\fR to names follows:
190
191 .sp
192 .in +2
193 .nf
194 example% \fBcut -d: -f1,5 /etc/passwd\fR
195 .fi
196 .in -2
197 .sp
198
199 .LP
200 \fBExample 2 \fRSetting current login name
201 .sp
202 .LP
203 To set \fBname\fR to current login name:
204
205 .sp
206 .in +2
207 .nf
208 example$ \fBname=\(gawho am i | cut -f1 -d' '\(ga\fR
209 .fi
210 .in -2
211 .sp
212
213 .SH ENVIRONMENT VARIABLES
214 .sp
215 .LP
216 See \fBenviron\fR(5) for descriptions of the following environment variables
217 that affect the execution of \fBcut\fR: \fBLANG\fR, \fBLC_ALL\fR,
218 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
219 .SH EXIT STATUS
220 .sp
221 .LP
222 The following exit values are returned:
223 .sp
224 .ne 2
225 .na
226 \fB\fB0\fR \fR
227 .ad
228 .RS 7n
229 All input files were output successfully.
230 .RE
231
232 .sp
233 .ne 2
234 .na
235 \fB\fB>0\fR \fR
236 .ad
237 .RS 7n
238 An error occurred.
239 .RE
240
241 .SH ATTRIBUTES
242 .sp
243 .LP
244 See \fBattributes\fR(5) for descriptions of the following attributes:
245 .sp
246
247 .sp
248 .TS
249 box;
250 c | c
251 l | l .
252 ATTRIBUTE TYPE ATTRIBUTE VALUE
253 _
254 CSI Enabled
255 _
256 Interface Stability Standard
257 .TE
258
259 .SH SEE ALSO
260 .sp
261 .LP
262 \fBgrep\fR(1), \fBpaste\fR(1), \fBattributes\fR(5), \fBenviron\fR(5),
263 \fBlargefile\fR(5), \fBstandards\fR(5)
264 .SH DIAGNOSTICS
265 .sp
266 .ne 2
267 .na
268 \fB\fBcut: \fR\fB-n\fR\fB may only be used with \fR\fB-b\fR \fR
269 .ad
270 .sp .6
271 .RS 4n
272
273 .RE
274
275 .sp
276 .ne 2
277 .na
278 \fB\fBcut: \fR\fB-d\fR\fB may only be used with \fR\fB-f\fR \fR
279 .ad
280 .sp .6
281 .RS 4n
282
283 .RE
284
285 .sp
286 .ne 2
287 .na
288 \fB\fBcut: \fR\fB-s\fR\fB may only be used with \fR\fB-f\fR \fR
289 .ad
290 .sp .6
291 .RS 4n
292
293 .RE
294
295 .sp
296 .ne 2
297 .na
298 \fB\fBcut: cannot open \fR\fI<file>\fR \fR
299 .ad
300 .sp .6
301 .RS 4n
302 Either \fIfile\fR cannot be read or does not exist. If multiple files are
303 present, processing continues.
304 .RE
305
306 .sp
307 .ne 2
308 .na
309 \fB\fBcut: no delimiter specified\fR \fR
310 .ad
311 .sp .6
312 .RS 4n
313 Missing \fIdelim\fR on \fB-d\fR option.
314 .RE
315
316 .sp
317 .ne 2
318 .na
319 \fB\fBcut: invalid delimiter\fR \fR
320 .ad
321 .sp .6
322 .RS 4n
323
324 .RE
325
326 .sp
327 .ne 2
328 .na
329 \fB\fBcut: no \fIlist\fR\fR\fB specified\fR \fR
330 .ad
331 .sp .6
332 .RS 4n
333 Missing \fIlist\fR on \fB-b\fR, \fB-c\fR, or \fB-f\fR option.
334 .RE
335
336 .sp
337 .ne 2
338 .na
339 \fB\fBcut: invalid range specifier\fR \fR
340 .ad
341 .sp .6
342 .RS 4n
343
344 .RE
345
346 .sp
347 .ne 2
348 .na
349 \fB\fBcut: too many ranges specified\fR \fR
350 .ad
351 .sp .6
352 .RS 4n
353
354 .RE
355
356 .sp
357 .ne 2
358 .na
359 \fB\fBcut: range must be increasing\fR \fR
360 .ad
361 .sp .6
362 .RS 4n
363
364 .RE
365
366 .sp
367 .ne 2
368 .na
369 \fB\fBcut: invalid character in range\fR \fR
370 .ad
371 .sp .6
372 .RS 4n
373
374 .RE
375
376 .sp
377 .ne 2
378 .na
379 \fB\fBcut: internal error processing input\fR \fR
380 .ad
381 .sp .6
382 .RS 4n
383
384 .RE
385
386 .sp
387 .ne 2
388 .na
389 \fB\fBcut: invalid multibyte character\fR \fR
390 .ad
391 .sp .6
392 .RS 4n
393
394 .RE
395
396 .sp
397 .ne 2
398 .na
399 \fB\fBcut: unable to allocate enough memory\fR \fR
400 .ad
401 .sp .6
402 .RS 4n
403
404 .RE
405
|
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved
46 .\" Copyright 2021 OmniOS Community Edition (OmniOSce) Association.
47 .\"
48 .Dd Feb 9, 2021
49 .Dt CUT 1
50 .Os
51 .Sh NAME
52 .Nm cut
53 .Nd cut out selected columns or fields of each line of a file
54 .Sh SYNOPSIS
55 .Nm
56 .Fl b Ar list
57 .Op Fl nN
58 .Op Fl r Ar reclen
59 .Oo Ar file Oc Ns ...
60 .Pp
61 .Nm
62 .Fl c Ar list
63 .Op Fl N
64 .Op Fl r Ar reclen
65 .Oo Ar file Oc Ns ...
66 .Pp
67 .Nm
68 .Fl f Ar list
69 .Op Fl s
70 .Op Fl d Ar delim
71 .Op Fl D Ar ldelim
72 .Oo Ar file Oc Ns ...
73 .Sh DESCRIPTION
74 Use the
75 .Nm
76 utility to cut out columns from a table or fields from each line of a file.
77 In database parlance, it implements the projection of a relation.
78 The fields as specified by
79 .Ar list
80 can be fixed length, that is, character positions as on a punched card
81 .Pq Fl c No option
82 or the length can vary from line to line and be marked with a field delimiter
83 character such as TAB
84 .Po Fl f No option Pc .
85 .Nm
86 can be used as a filter.
87 .Pp
88 Either the
89 .Fl b ,
90 .Fl c ,
91 or
92 .Fl f
93 option must be specified.
94 .Pp
95 Use
96 .Xr grep 1
97 to make horizontal cuts (by context) through a file, or
98 .Xr paste 1
99 to put files together column-wise (that is, horizontally).
100 To reorder columns in a table, use
101 .Nm cut
102 and
103 .Xr paste 1 .
104 .Sh OPTIONS
105 The following options are supported:
106 .Bl -tag -width Ar
107 .It Fl b Ar list Ns \&, Fl \-bytes Ns = Ns Ar list
108 The
109 .Ar list
110 following
111 .Fl b
112 specifies byte positions (for instance,
113 .Fl b Ar 1-72
114 would pass the first 72 bytes of each line).
115 When
116 .Fl b
117 and
118 .Fl n
119 are used together, list is adjusted so that no multi-byte character is split.
120 .It Fl c Ar list Ns \&, Fl \-characters Ns = Ns Ar list
121 The
122 .Ar list
123 following
124 .Fl c
125 specifies character positions (for instance,
126 .Fl c Ar 1-72
127 would pass the first 72 characters of each line).
128 .It Fl d Ar delim Ns \&, Fl \-delimiter Ns = Ns Ar delim
129 The character following
130 .Fl d
131 is the field delimiter
132 .Po Fl f No option only Pc ;
133 the default is the TAB character.
134 Space or other characters with special meaning to the shell must be quoted.
135 delim can be a multi-byte character.
136 .It Fl f Ar list Ns \&, Fl \-fields Ns = Ns Ar list
137 The
138 .Ar list
139 following
140 .Fl f
141 is a list of fields assumed to be separated in the file by a delimiter
142 character
143 .Po see Fl d Pc ;
144 for instance,
145 .Fl f Ar 1,7
146 copies the first and seventh field only.
147 Lines with no field delimiters will be passed through intact (useful for table
148 subheadings), unless
149 .Fl s
150 is specified.
151 .It Fl n Ns \&, Fl \-split Ns \&, Fl \-nosplit
152 Controls whether multi-byte characters are split with the
153 .Fl b
154 option.
155 The default is to split characters and this can be disabled with the
156 .Fl n
157 or
158 .Fl \-nosplit
159 flag.
160 Unless specified, lines with no delimiters will be passed through untouched.
161 .It Fl r Ar reclen Ns \&, Fl R Ar reclen Ns \&, Fl \-reclen Ns = Ns Ar reclen
162 If
163 .Ar reclen
164 is > 0, the input will be read as fixed length records of length
165 .Ar reclen
166 when used with the
167 .Fl b
168 or
169 .Fl c
170 options.
171 .It Fl s Ns \&, Fl \-suppress Ns \&, Fl \-only-delimited
172 Suppress lines which do not contain any delimiter characters
173 .Po Fl f No option only Pc .
174 .It Fl D Ar ldelim Ns \&, Fl \-line-delimiter Ns = Ns Ar ldelim Ns \&, Fl \-output-delimiter Ns = Ns Ar ldelim
175 The line delimiter for the
176 .Fl f
177 option is set to
178 .Ar ldelim .
179 The default is the newline character.
180 .It Fl N Ns \&, Fl \-newline Ns \&, Fl \-nonewline
181 Controls whether to output a new-line at the end of each record when used with
182 the
183 .Fl b
184 or
185 .Fl c
186 options.
187 This is on by default;
188 .Fl N
189 turns it off and is the same as specifying
190 .Fl \-nonewline .
191 .El
192 .Pp
193 In the above options,
194 .Ar list
195 is a comma-separated or blank-character-separated list of integer field, byte
196 or character numbers (in increasing order), with optional
197 .Ar \(mi
198 to indicate ranges (for instance,
199 .Em 1,4,7 ;
200 .Em 1\(mi3,8 ;
201 .Em \(mi5,10
202 .Po short for Ar 1\(mi5,10 Pc ;
203 or
204 .Ar 3\(mi
205 .Po short for third through last field Pc .
206 )
207 .Sh OPERANDS
208 The following operands are supported:
209 .Bl -tag -width Ar
210 .It Ar file
211 A path name of an input file.
212 If no file operands are specified, or if a file operand is \(mi, the standard
213 input will be used.
214 .El
215 .Sh EXIT STATUS
216 .Bl -tag -width Ds
217 .It Sy 0
218 All input files were output successfully.
219 .It Sy >0
220 An error occurred.
221 .El
222 .Sh EXAMPLES
223 .Bl -tag -width 6
224 .It Sy Example 1 No Mapping user IDs
225 .Pp
226 A mapping of user IDs to names follows:
227 .Bd -literal
228 $ cut -d: -f1,5 /etc/passwd
229 .Ed
230 .It Sy Example 2 No Setting current login name
231 .Pp
232 To set
233 .Ar name
234 to current login name:
235 .Bd -literal
236 $ name=\(gawho am i | cut -f1 -d' '\(ga
237 .Ed
238 .El
239 .Sh ENVIRONMENT VARIABLES
240 See
241 .Xr environ 5
242 for descriptions of the following environment variables
243 that affect the execution of
244 .Nm :
245 .Ev LANG ,
246 .Ev LC_ALL ,
247 .Ev LC_CTYPE ,
248 .Ev LC_MESSAGES ,
249 .Ev LC_NUMERIC ,
250 and
251 .Ev NLSPATH .
252 .Sh INTERFACE STABILITY
253 The command line interface of
254 .Nm
255 is
256 .Sy Committed .
257 The output of
258 .Nm
259 is
260 .Sy Committed .
261 .Sh SEE ALSO
262 .Xr grep 1 ,
263 .Xr paste 1 ,
264 .Xr attributes 5 ,
265 .Xr environ 5 ,
266 .Xr largefile 5 ,
267 .Xr standards 5
|