Provided by: manpages-posix_2013a-2_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of this interface
       may differ (consult the corresponding Linux manual page for details of Linux behavior), or the  interface
       may not be implemented on Linux.

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  shall 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 shall conform to the Base Definitions  volume  of  POSIX.1‐2008,  Section  12.2,  Utility
       Syntax Guidelines.

       The  application  shall  ensure  that  the  option-argument  list (see options −b, −c, and −f below) is a
       <comma>-separated list or <blank>-separated list of positive numbers and ranges. Ranges can be  in  three
       forms.  The first is two positive numbers separated by a <hyphen> (lowhigh), 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, but the bytes, characters, or
       fields selected shall be written in the order of the input data. If an element appears in  the  selection
       list more than once, it shall be written exactly once.

       The following options shall be supported:

       −b list   Cut  based  on a list of bytes. Each selected byte shall be output unless the −n option is also
                 specified. It shall not be an error to select bytes not present in the input line.

       −c list   Cut based on a list of characters. Each selected character shall be output. It shall not be  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>.

       −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 shall be output. Output fields shall be separated  by  a  single
                 occurrence  of  the  field  delimiter character. Lines with no field delimiters shall be passed
                 through intact, unless −s is specified. It shall not be 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
                 lowhigh (<hyphen>-separated numbers) shall be modified as follows:

                  *  If the byte selected by low is not the first byte of a character, low shall 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 shall 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 shall be dropped from list for that input line without causing
                     an error.

                 Each element in list of the form low− shall be treated as above with high set to the number  of
                 bytes  in  the  current line, not including the terminating <newline>.  Each element in list of
                 the form −high shall be treated as above with low set to 1. Each element in list  of  the  form
                 num (a single number) shall 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 shall be passed through untouched.

OPERANDS

       The following operand shall be supported:

       file      A pathname of an input file. If no file operands are specified, or if a file  operand  is  '−',
                 the standard input shall be used.

STDIN

       The  standard  input  shall  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 shall be text files, except that line lengths shall be unlimited.

ENVIRONMENT VARIABLES

       The following environment variables shall affect the execution of cut:

       LANG      Provide a default value for the internationalization variables that are unset or null. (See the
                 Base  Definitions  volume  of POSIX.1‐2008, Section 8.2, Internationalization Variables for the
                 precedence  of  internationalization  variables  used  to  determine  the  values   of   locale
                 categories.)

       LC_ALL    If  set  to a non-empty string value, override the values of all the other internationalization
                 variables.

       LC_CTYPE  Determine the locale for the interpretation of sequences of bytes of text  data  as  characters
                 (for example, single-byte 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 catalogs for the processing of LC_MESSAGES.

ASYNCHRONOUS EVENTS

       Default.

STDOUT

       The cut utility output shall 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

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       None.

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       The following exit values shall be returned:

        0    All input files were output successfully.

       >0    An error occurred.

CONSEQUENCES OF ERRORS

       Default.

       The following sections are informative.

APPLICATION USAGE

       The cut and fold utilities can be used to create text files out of files with arbitrary line lengths. The
       cut utility should be used when the number of lines (or records)  needs  to  remain  constant.  The  fold
       utility should be used when the contents of long lines need to be kept contiguous.

       Earlier  versions  of the cut utility worked in an environment where bytes and characters were considered
       equivalent (modulo <backspace> and <tab> 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

       ends up with all the characters in file appearing exactly once in file1 or file2.  (There is, however,  a
       <newline> in both file1 and file2 for each <newline> 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  lowhigh 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 volume of POSIX.1‐2008 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>) and file2 that
       contains the remainder of the data from file.  (Note that file2 is not 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

RATIONALE

       Some historical implementations do not count <backspace> characters in determining character counts  with
       the  −c option. This may be useful for using cut for processing nroff output. It was deliberately decided
       not to have the −c option treat either <backspace> or <tab> characters in any special fashion.  The  fold
       utility does treat these characters specially.

       Unlike  other  utilities,  some  historical  implementations of cut exit after not finding an input file,
       rather than continuing to process the remaining file operands. This behavior is prohibited by this volume
       of POSIX.1‐2008, where only the exit status is affected by this problem.

       The  behavior  of  cut  when  provided with either mutually-exclusive options or options that do not work
       logically together has been deliberately left unspecified in favor of  global  wording  in  Section  1.4,
       Utility Description Defaults.

       The  OPTIONS  section  was  changed  in  response  to  IEEE  PASC  Interpretation 1003.2 #149. The change
       represents historical practice on all known systems. The original standard was ambiguous on the nature of
       the output.

       The  list option-arguments are historically used to select the portions of the line to be written, but do
       not affect the order of the data. For example:

           echo abcdefghi | cut −c6,2,4−7,1

       yields "abdefg".

       A proposal to enhance cut with the following option:

       −o    Preserve the selected field order. When this option is specified, each byte,  character,  or  field
             (or  ranges  of  such) shall be written in the order specified by the list option-argument, even if
             this requires multiple outputs of the same bytes, characters, or fields.

       was rejected because this type of enhancement is outside the scope of the IEEE P1003.2b draft standard.

FUTURE DIRECTIONS

       None.

SEE ALSO

       Section 2.5, Parameters and Variables, fold, grep, paste

       The Base Definitions volume of POSIX.1‐2008, Chapter 8,  Environment  Variables,  Section  12.2,  Utility
       Syntax Guidelines

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications  Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc
       and The Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In  the  event
       of  any  discrepancy between this version and the original IEEE and The Open Group Standard, the original
       IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at
       http://www.unix.org/online.html .

       Any  typographical  or formatting errors that appear in this page are most likely to have been introduced
       during  the  conversion  of  the  source  files  to  man  page  format.  To  report  such   errors,   see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .