CUT(1)                     POSIX Programmer's Manual                    CUT(1)



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

NNAAMMEE
       cut -- cut out selected fields of each line of a file

SSYYNNOOPPSSIISS
       cut -b _l_i_s_t [[-n]] [[_f_i_l_e...]]

       cut -c _l_i_s_t [[_f_i_l_e...]]

       cut -f _l_i_s_t [[-d _d_e_l_i_m]] [[-s]] [[_f_i_l_e...]]

DDEESSCCRRIIPPTTIIOONN
       The _c_u_t utility shall cut out bytes (--bb option), characters (--cc
       option), or character-delimited fields (--ff option) from each line in
       one or more files, concatenate them, and write them to standard output.

OOPPTTIIOONNSS
       The _c_u_t utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The application shall ensure that the option-argument _l_i_s_t (see options
       --bb, --cc, and --ff 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-minus> (_l_o_w-_h_i_g_h),
       which represents all fields from the first number to the second number.
       The second is a positive number preceded by a <hyphen-minus> (-_h_i_g_h),
       which represents all fields from field number 1 to that number. The
       third is a positive number followed by a <hyphen-minus> (_l_o_w-), which
       represents that number to the last field, inclusive. The elements in
       _l_i_s_t 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:

       --bb _l_i_s_t   Cut based on a _l_i_s_t of bytes. Each selected byte shall be
                 output unless the --nn option is also specified. It shall not
                 be an error to select bytes not present in the input line.

       --cc _l_i_s_t   Cut based on a _l_i_s_t of characters. Each selected character
                 shall be output. It shall not be an error to select
                 characters not present in the input line.

       --dd _d_e_l_i_m  Set the field delimiter to the character _d_e_l_i_m.  The default
                 is the <tab>.

       --ff _l_i_s_t   Cut based on a _l_i_s_t of fields, assumed to be separated in the
                 file by a delimiter character (see --dd).  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 --ss is
                 specified. It shall not be an error to select fields not
                 present in the input line.

       --nn        Do not split characters. When specified with the --bb option,
                 each element in _l_i_s_t of the form _l_o_w-_h_i_g_h (<hyphen-
                 minus>-separated numbers) shall be modified as follows:

                  *  If the byte selected by _l_o_w is not the first byte of a
                     character, _l_o_w shall be decremented to select the first
                     byte of the character originally selected by _l_o_w.  If the
                     byte selected by _h_i_g_h is not the last byte of a
                     character, _h_i_g_h shall be decremented to select the last
                     byte of the character prior to the character originally
                     selected by _h_i_g_h, or zero if there is no prior character.
                     If the resulting range element has _h_i_g_h equal to zero or
                     _l_o_w greater than _h_i_g_h, the list element shall be dropped
                     from _l_i_s_t for that input line without causing an error.

                 Each element in _l_i_s_t of the form _l_o_w- shall be treated as
                 above with _h_i_g_h set to the number of bytes in the current
                 line, not including the terminating <newline>.  Each element
                 in _l_i_s_t of the form -_h_i_g_h shall be treated as above with _l_o_w
                 set to 1. Each element in _l_i_s_t of the form _n_u_m (a single
                 number) shall be treated as above with _l_o_w set to _n_u_m and
                 _h_i_g_h set to _n_u_m.

       --ss        Suppress lines with no delimiter characters, when used with
                 the --ff option. Unless specified, lines with no delimiters
                 shall be passed through untouched.

OOPPEERRAANNDDSS
       The following operand shall be supported:

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

SSTTDDIINN
       The standard input shall be used only if no _f_i_l_e operands are
       specified, or if a _f_i_l_e operand is ''--''.  See the INPUT FILES section.

IINNPPUUTT FFIILLEESS
       The input files shall be text files, except that line lengths shall be
       unlimited.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _c_u_t:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

       _L_C___C_T_Y_P_E  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).

       _L_C___M_E_S_S_A_G_E_S
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       The _c_u_t utility output shall be a concatenation of the selected bytes,
       characters, or fields (one of the following):


           "%s\n", <_c_o_n_c_a_t_e_n_a_t_i_o_n _o_f _b_y_t_e_s>

           "%s\n", <_c_o_n_c_a_t_e_n_a_t_i_o_n _o_f _c_h_a_r_a_c_t_e_r_s>

           "%s\n", <_c_o_n_c_a_t_e_n_a_t_i_o_n _o_f _f_i_e_l_d_s _a_n_d _f_i_e_l_d _d_e_l_i_m_i_t_e_r_s>

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    All input files were output successfully.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

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

       Earlier versions of the _c_u_t 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 --bb option has been added. The --nn option
       (used with --bb) allows it to be used to act on bytes rounded to
       character boundaries.  The algorithm specified for --nn guarantees that:


           cut -b 1-500 -n file > file1
           cut -b 501- -n file > file2

       ends up with all the characters in ffiillee appearing exactly once in ffiillee11
       or ffiillee22.  (There is, however, a <newline> in both ffiillee11 and ffiillee22 for
       each <newline> in ffiillee.)

EEXXAAMMPPLLEESS
       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 _l_o_w-_h_i_g_h forms are not always equivalent when used with --bb and --nn
       and multi-byte characters; see the description of --nn.

       The following command:


           cut -d : -f 1,6 /etc/passwd

       reads the System V password file (user database) and produces lines of
       the form:


           <_u_s_e_r _I_D>:<_h_o_m_e _d_i_r_e_c_t_o_r_y>

       Most utilities in this volume of POSIX.1-2017 work on text files. The
       _c_u_t utility can be used to turn files with arbitrary line lengths into
       a set of text files containing the same data. The _p_a_s_t_e utility can be
       used to create (or recreate) files with arbitrary line lengths. For
       example, if ffiillee contains long lines:


           cut -b 1-500 -n file > file1
           cut -b 501- -n file > file2

       creates ffiillee11 (a text file) with lines no longer than 500 bytes (plus
       the <newline>) and ffiillee22 that contains the remainder of the data from
       ffiillee.  (Note that ffiillee22 is not a text file if there are lines in ffiillee
       that are longer than 500 + {LINE_MAX} bytes.) The original file can be
       recreated from ffiillee11 and ffiillee22 using the command:


           paste -d "\0" file1 file2 > file

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

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

       The behavior of _c_u_t 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 _S_e_c_t_i_o_n
       _1_._4, _U_t_i_l_i_t_y _D_e_s_c_r_i_p_t_i_o_n _D_e_f_a_u_l_t_s.

       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 _l_i_s_t 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 ""aabbddeeffgg"".

       A proposal to enhance _c_u_t with the following option:

       --oo    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 _l_i_s_t 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.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._5, _P_a_r_a_m_e_t_e_r_s _a_n_d _V_a_r_i_a_b_l_e_s, _f_o_l_d, _g_r_e_p, _p_a_s_t_e

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  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.opengroup.org/unix/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 .



IEEE/The Open Group                  2017                               CUT(1)
