1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  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