diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/split.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/split.1p | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/split.1p b/man-pages-posix-2017/man1p/split.1p new file mode 100644 index 0000000..c9995cf --- /dev/null +++ b/man-pages-posix-2017/man1p/split.1p @@ -0,0 +1,321 @@ +'\" et +.TH SPLIT "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 +split +\(em split a file into pieces +.SH SYNOPSIS +.LP +.nf +split \fB[\fR-l \fIline_count\fB] [\fR-a \fIsuffix_length\fB] [\fIfile \fB[\fIname\fB]]\fR +.P +split -b \fIn\fB[\fRk|m\fB] [\fR-a \fIsuffix_length\fB] [\fIfile \fB[\fIname\fB]]\fR +.fi +.SH DESCRIPTION +The +.IR split +utility shall read an input file and write zero or more output files. +The default size of each output file shall be 1\|000 lines. The size +of the output files can be modified by specification of the +.BR \-b +or +.BR \-l +options. Each output file shall be created with a unique suffix. The +suffix shall consist of exactly +.IR suffix_length +lowercase letters from the POSIX locale. The letters of the suffix +shall be used as if they were a base-26 digit system, with the first +suffix to be created consisting of all +.BR 'a' +characters, the second with a +.BR 'b' +replacing the last +.BR 'a' , +and so on, until a name of all +.BR 'z' +characters is created. By default, the names of the output files shall +be +.BR 'x' , +followed by a two-character suffix from the character set as described +above, starting with +.BR \(dqaa\(dq , +.BR \(dqab\(dq , +.BR \(dqac\(dq , +and so on, and continuing until the suffix +.BR \(dqzz\(dq , +for a maximum of 676 files. +.P +If the number of files required exceeds the maximum allowed by the +suffix length provided, such that the last allowable file would be +larger than the requested size, the +.IR split +utility shall fail after creating the last file with a valid suffix; +.IR split +shall not delete the files it created with valid suffixes. If the file +limit is not exceeded, the last file created shall contain the +remainder of the input file, and may be smaller than the requested +size. If the input is an empty file, no output file shall be created +and this shall not be considered to be an error. +.SH OPTIONS +The +.IR split +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\-a\ \fIsuffix_length\fR" 10 +.br +Use +.IR suffix_length +letters to form the suffix portion of the filenames of the split +file. If +.BR \-a +is not specified, the default suffix length shall be two. If the sum +of the +.IR name +operand and the +.IR suffix_length +option-argument would create a filename exceeding +{NAME_MAX} +bytes, an error shall result; +.IR split +shall exit with a diagnostic message and no files shall be created. +.IP "\fB\-b\ \fIn\fR" 10 +Split a file into pieces +.IR n +bytes in size. +.IP "\fB\-b\ \fIn\fBk\fR" 10 +Split a file into pieces +.IR n *1\|024 +bytes in size. +.IP "\fB\-b\ \fIn\fBm\fR" 10 +Split a file into pieces +.IR n *1\|048\|576 +bytes in size. +.IP "\fB\-l\ \fIline_count\fR" 10 +Specify the number of lines in each resulting file piece. The +.IR line_count +argument is an unsigned decimal integer. The default is 1\|000. If +the input does not end with a +<newline>, +the partial line shall be included in the last output file. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIfile\fR" 10 +The pathname of the ordinary file to be split. If no input file is +given or +.IR file +is +.BR '\-' , +the standard input shall be used. +.IP "\fIname\fR" 10 +The prefix to be used for each of the files resulting from the split +operation. If no +.IR name +argument is given, +.BR 'x' +shall be used as the prefix of the output files. The combined length +of the basename of +.IR prefix +and +.IR suffix_length +cannot exceed +{NAME_MAX} +bytes. See the OPTIONS section. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +Any file can be used as input. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR split : +.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 +Not used. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +The output files contain portions of the original input file; otherwise, +unchanged. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +In the following examples +.BR foo +is a text file that contains 5\|000 lines. +.IP " 1." 4 +Create five files, +.BR xaa , +.BR xab , +.BR xac , +.BR xad , +and +.BR xae : +.RS 4 +.sp +.RS 4 +.nf + +split foo +.fi +.P +.RE +.RE +.IP " 2." 4 +Create five files, but the suffixed portion of the created +files consists of three letters, +.BR xaaa , +.BR xaab , +.BR xaac , +.BR xaad , +and +.BR xaae : +.RS 4 +.sp +.RS 4 +.nf + +split -a 3 foo +.fi +.P +.RE +.RE +.IP " 3." 4 +Create three files with four-letter suffixes and a supplied prefix, +.BR bar_aaaa , +.BR bar_aaab , +and +.BR bar_aaac : +.RS 4 +.sp +.RS 4 +.nf + +split -a 4 -l 2000 foo bar_ +.fi +.P +.RE +.RE +.IP " 4." 4 +Create as many files as are necessary to contain at most 20*1\|024 +bytes, each with the default prefix of +.BR x +and a five-letter suffix: +.RS 4 +.sp +.RS 4 +.nf + +split -a 5 -b 20k foo +.fi +.P +.RE +.RE +.SH RATIONALE +The +.BR \-b +option was added to provide a mechanism for splitting files other than +by lines. While most uses of the +.BR \-b +option are for transmitting files over networks, some believed it would +have additional uses. +.P +The +.BR \-a +option was added to overcome the limitation of being able to create +only 676 files. +.P +Consideration was given to deleting this utility, using the rationale +that the functionality provided by this utility is available via the +.IR csplit +utility (see +.IR "\fIcsplit\fR\^"). +Upon reconsideration of the purpose of the User Portability Utilities +option, it was decided to retain both this utility and the +.IR csplit +utility because users use both utilities and have historical +expectations of their behavior. Furthermore, the splitting on byte +boundaries in +.IR split +cannot be duplicated with the historical +.IR csplit . +.P +The text ``\c +.IR split +shall not delete the files it created with valid suffixes'' would +normally be assumed, but since the related utility, +.IR csplit , +does delete files under some circumstances, the historical behavior of +.IR split +is made explicit to avoid misinterpretation. +.P +Earlier versions of this standard allowed a +.BR \- \c +.IR line_count +option. This form is no longer specified by POSIX.1\(hy2008 but may be +present in some implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcsplit\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 . |