diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/cut.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/cut.1p | 498 |
1 files changed, 498 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/cut.1p b/man-pages-posix-2017/man1p/cut.1p new file mode 100644 index 0000000..e545969 --- /dev/null +++ b/man-pages-posix-2017/man1p/cut.1p @@ -0,0 +1,498 @@ +'\" et +.TH CUT "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH 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. +.\" +.SH NAME +cut +\(em cut out selected fields of each line of a file +.SH SYNOPSIS +.LP +.nf +cut -b \fIlist \fB[\fR-n\fB] [\fIfile\fR...\fB]\fR +.P +cut -c \fIlist \fB[\fIfile\fR...\fB]\fR +.P +cut -f \fIlist \fB[\fR-d \fIdelim\fB] [\fR-s\fB] [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR cut +utility shall cut out bytes (\c +.BR \-b +option), characters (\c +.BR \-c +option), or character-delimited fields (\c +.BR \-f +option) from each line in one or more files, concatenate them, and +write them to standard output. +.SH OPTIONS +The +.IR cut +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The application shall ensure that the option-argument +.IR list +(see options +.BR \-b , +.BR \-c , +and +.BR \-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-minus> +(\c +.IR low \-\c +.IR high ), +which represents all fields from the first number to the second +number. The second is a positive number preceded by a +<hyphen-minus> +(\-\c +.IR high ), +which represents all fields from field number 1 to that number. The +third is a positive number followed by a +<hyphen-minus> +(\c +.IR low \-), +which represents that number to the last field, inclusive. The elements +in +.IR 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. +.P +The following options shall be supported: +.IP "\fB\-b\ \fIlist\fR" 10 +Cut based on a +.IR list +of bytes. Each selected byte shall be output unless the +.BR \-n +option is also specified. It shall not be an error to select bytes not +present in the input line. +.IP "\fB\-c\ \fIlist\fR" 10 +Cut based on a +.IR list +of characters. Each selected character shall be output. It shall not +be an error to select characters not present in the input line. +.IP "\fB\-d\ \fIdelim\fR" 10 +Set the field delimiter to the character +.IR delim . +The default is the +<tab>. +.IP "\fB\-f\ \fIlist\fR" 10 +Cut based on a +.IR list +of fields, assumed to be separated in the file by a delimiter character +(see +.BR \-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 +.BR \-s +is specified. It shall not be an error to select fields not present in +the input line. +.IP "\fB\-n\fP" 10 +Do not split characters. When specified with the +.BR \-b +option, each element in +.IR list +of the form +.IR low \-\c +.IR high +(\c +<hyphen-minus>-separated +numbers) shall be modified as follows: +.RS 10 +.IP " *" 4 +If the byte selected by +.IR low +is not the first byte of a character, +.IR low +shall be decremented to select the first byte of the character +originally selected by +.IR low . +If the byte selected by +.IR high +is not the last byte of a character, +.IR high +shall be decremented to select the last byte of the character prior to +the character originally selected by +.IR high , +or zero if there is no prior character. If the resulting range element +has +.IR high +equal to zero or +.IR low +greater than +.IR high , +the list element shall be dropped from +.IR list +for that input line without causing an error. +.P +Each element in +.IR list +of the form +.IR low \- +shall be treated as above with +.IR high +set to the number of bytes in the current line, not including the +terminating +<newline>. +Each element in +.IR list +of the form \-\c +.IR high +shall be treated as above with +.IR low +set to 1. Each element in +.IR list +of the form +.IR num +(a single number) shall be treated as above with +.IR low +set to +.IR num +and +.IR high +set to +.IR num . +.RE +.IP "\fB\-s\fP" 10 +Suppress lines with no delimiter characters, when used with the +.BR \-f +option. Unless specified, lines with no delimiters shall be passed +through untouched. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an input file. If no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\-' , +the standard input shall be used. +.SH STDIN +The standard input shall be used only if no +.IR file +operands are specified, or if a +.IR file +operand is +.BR '\-' . +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files, except that line lengths shall be +unlimited. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR cut : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +The +.IR cut +utility output shall be a concatenation of the selected bytes, +characters, or fields (one of the following): +.sp +.RS 4 +.nf + +"%s\en", <\fIconcatenation of bytes\fR> +.P +"%s\en", <\fIconcatenation of characters\fR> +.P +"%s\en", <\fIconcatenation of fields and field delimiters\fR> +.fi +.P +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +All input files were output successfully. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.IR cut +and +.IR fold +utilities can be used to create text files out of files with +arbitrary line lengths. The +.IR cut +utility should be used when the number of lines (or records) needs +to remain constant. The +.IR fold +utility should be used when the contents of long lines need to be +kept contiguous. +.P +Earlier versions of the +.IR 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 +.BR \-b +option has been added. The +.BR \-n +option (used with +.BR \-b ) +allows it to be used to act on bytes rounded to character boundaries. +The algorithm specified for +.BR \-n +guarantees that: +.sp +.RS 4 +.nf + +cut -b 1-500 -n file > file1 +cut -b 501- -n file > file2 +.fi +.P +.RE +.P +ends up with all the characters in +.BR file +appearing exactly once in +.BR file1 +or +.BR file2 . +(There is, however, a +<newline> +in both +.BR file1 +and +.BR file2 +for each +<newline> +in +.BR file .) +.SH EXAMPLES +Examples of the option qualifier list: +.IP 1,4,7 8 +Select the first, fourth, and seventh bytes, characters, or fields and +field delimiters. +.IP "1\-3,8" 8 +Equivalent to 1,2,3,8. +.IP "\-5,10" 8 +Equivalent to 1,2,3,4,5,10. +.IP "3\-" 8 +Equivalent to third to last, inclusive. +.P +The +.IR low \-\c +.IR high +forms are not always equivalent when used with +.BR \-b +and +.BR \-n +and multi-byte characters; see the description of +.BR \-n . +.P +The following command: +.sp +.RS 4 +.nf + +cut -d : -f 1,6 /etc/passwd +.fi +.P +.RE +.P +reads the System V password file (user database) and produces lines of +the form: +.sp +.RS 4 +.nf + +<\fIuser ID\fR>:<\fIhome directory\fR> +.fi +.P +.RE +.P +Most utilities in this volume of POSIX.1\(hy2017 work on text files. The +.IR cut +utility can be used to turn files with arbitrary line lengths into a +set of text files containing the same data. The +.IR paste +utility can be used to create (or recreate) files with arbitrary line +lengths. For example, if +.BR file +contains long lines: +.sp +.RS 4 +.nf + +cut -b 1-500 -n file > file1 +cut -b 501- -n file > file2 +.fi +.P +.RE +.P +creates +.BR file1 +(a text file) with lines no longer than 500 bytes (plus the +<newline>) +and +.BR file2 +that contains the remainder of the data from +.BR file . +(Note that +.BR file2 +is not a text file if there are lines in +.BR file +that are longer than 500 + +{LINE_MAX} +bytes.) The original file can be recreated from +.BR file1 +and +.BR file2 +using the command: +.sp +.RS 4 +.nf + +paste -d "\e0" file1 file2 > file +.fi +.P +.RE +.SH RATIONALE +Some historical implementations do not count +<backspace> +characters in determining character counts with the +.BR \-c +option. This may be useful for using +.IR cut +for processing +.IR nroff +output. It was deliberately decided not to have the +.BR \-c +option treat either +<backspace> +or +<tab> +characters in any special fashion. The +.IR fold +utility does treat these characters specially. +.P +Unlike other utilities, some historical implementations of +.IR cut +exit after not finding an input file, rather than continuing to process +the remaining +.IR file +operands. This behavior is prohibited by this volume of POSIX.1\(hy2017, where only the exit +status is affected by this problem. +.P +The behavior of +.IR 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 +.IR "Section 1.4" ", " "Utility Description Defaults". +.P +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. +.P +The +.IR 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: +.sp +.RS 4 +.nf + +echo abcdefghi | cut -c6,2,4-7,1 +.fi +.P +.RE +.P +yields +.BR \(dqabdefg\(dq . +.P +A proposal to enhance +.IR cut +with the following option: +.IP "\fB\-o\fP" 6 +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 +.IR list +option-argument, even if this requires multiple outputs of the same +bytes, characters, or fields. +.P +was rejected because this type of enhancement is outside the scope of +the IEEE\ P1003.2b draft standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Parameters and Variables", +.IR "\fIfold\fR\^", +.IR "\fIgrep\fR\^", +.IR "\fIpaste\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.\" +.SH COPYRIGHT +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 . +.PP +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 . |