logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

split.1p (8707B)


  1. '\" et
  2. .TH SPLIT "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. split
  12. \(em split a file into pieces
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. split \fB[\fR-l \fIline_count\fB] [\fR-a \fIsuffix_length\fB] [\fIfile \fB[\fIname\fB]]\fR
  17. .P
  18. split -b \fIn\fB[\fRk|m\fB] [\fR-a \fIsuffix_length\fB] [\fIfile \fB[\fIname\fB]]\fR
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. .IR split
  23. utility shall read an input file and write zero or more output files.
  24. The default size of each output file shall be 1\|000 lines. The size
  25. of the output files can be modified by specification of the
  26. .BR \-b
  27. or
  28. .BR \-l
  29. options. Each output file shall be created with a unique suffix. The
  30. suffix shall consist of exactly
  31. .IR suffix_length
  32. lowercase letters from the POSIX locale. The letters of the suffix
  33. shall be used as if they were a base-26 digit system, with the first
  34. suffix to be created consisting of all
  35. .BR 'a'
  36. characters, the second with a
  37. .BR 'b'
  38. replacing the last
  39. .BR 'a' ,
  40. and so on, until a name of all
  41. .BR 'z'
  42. characters is created. By default, the names of the output files shall
  43. be
  44. .BR 'x' ,
  45. followed by a two-character suffix from the character set as described
  46. above, starting with
  47. .BR \(dqaa\(dq ,
  48. .BR \(dqab\(dq ,
  49. .BR \(dqac\(dq ,
  50. and so on, and continuing until the suffix
  51. .BR \(dqzz\(dq ,
  52. for a maximum of 676 files.
  53. .P
  54. If the number of files required exceeds the maximum allowed by the
  55. suffix length provided, such that the last allowable file would be
  56. larger than the requested size, the
  57. .IR split
  58. utility shall fail after creating the last file with a valid suffix;
  59. .IR split
  60. shall not delete the files it created with valid suffixes. If the file
  61. limit is not exceeded, the last file created shall contain the
  62. remainder of the input file, and may be smaller than the requested
  63. size. If the input is an empty file, no output file shall be created
  64. and this shall not be considered to be an error.
  65. .SH OPTIONS
  66. The
  67. .IR split
  68. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  69. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  70. .P
  71. The following options shall be supported:
  72. .IP "\fB\-a\ \fIsuffix_length\fR" 10
  73. .br
  74. Use
  75. .IR suffix_length
  76. letters to form the suffix portion of the filenames of the split
  77. file. If
  78. .BR \-a
  79. is not specified, the default suffix length shall be two. If the sum
  80. of the
  81. .IR name
  82. operand and the
  83. .IR suffix_length
  84. option-argument would create a filename exceeding
  85. {NAME_MAX}
  86. bytes, an error shall result;
  87. .IR split
  88. shall exit with a diagnostic message and no files shall be created.
  89. .IP "\fB\-b\ \fIn\fR" 10
  90. Split a file into pieces
  91. .IR n
  92. bytes in size.
  93. .IP "\fB\-b\ \fIn\fBk\fR" 10
  94. Split a file into pieces
  95. .IR n *1\|024
  96. bytes in size.
  97. .IP "\fB\-b\ \fIn\fBm\fR" 10
  98. Split a file into pieces
  99. .IR n *1\|048\|576
  100. bytes in size.
  101. .IP "\fB\-l\ \fIline_count\fR" 10
  102. Specify the number of lines in each resulting file piece. The
  103. .IR line_count
  104. argument is an unsigned decimal integer. The default is 1\|000. If
  105. the input does not end with a
  106. <newline>,
  107. the partial line shall be included in the last output file.
  108. .SH OPERANDS
  109. The following operands shall be supported:
  110. .IP "\fIfile\fR" 10
  111. The pathname of the ordinary file to be split. If no input file is
  112. given or
  113. .IR file
  114. is
  115. .BR '\-' ,
  116. the standard input shall be used.
  117. .IP "\fIname\fR" 10
  118. The prefix to be used for each of the files resulting from the split
  119. operation. If no
  120. .IR name
  121. argument is given,
  122. .BR 'x'
  123. shall be used as the prefix of the output files. The combined length
  124. of the basename of
  125. .IR prefix
  126. and
  127. .IR suffix_length
  128. cannot exceed
  129. {NAME_MAX}
  130. bytes. See the OPTIONS section.
  131. .SH STDIN
  132. See the INPUT FILES section.
  133. .SH "INPUT FILES"
  134. Any file can be used as input.
  135. .SH "ENVIRONMENT VARIABLES"
  136. The following environment variables shall affect the execution of
  137. .IR split :
  138. .IP "\fILANG\fP" 10
  139. Provide a default value for the internationalization variables that are
  140. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  141. .IR "Section 8.2" ", " "Internationalization Variables"
  142. for the precedence of internationalization variables used to determine
  143. the values of locale categories.)
  144. .IP "\fILC_ALL\fP" 10
  145. If set to a non-empty string value, override the values of all the
  146. other internationalization variables.
  147. .IP "\fILC_CTYPE\fP" 10
  148. Determine the locale for the interpretation of sequences of bytes of
  149. text data as characters (for example, single-byte as opposed to
  150. multi-byte characters in arguments and input files).
  151. .IP "\fILC_MESSAGES\fP" 10
  152. .br
  153. Determine the locale that should be used to affect the format and
  154. contents of diagnostic messages written to standard error.
  155. .IP "\fINLSPATH\fP" 10
  156. Determine the location of message catalogs for the processing of
  157. .IR LC_MESSAGES .
  158. .SH "ASYNCHRONOUS EVENTS"
  159. Default.
  160. .SH STDOUT
  161. Not used.
  162. .SH STDERR
  163. The standard error shall be used only for diagnostic messages.
  164. .SH "OUTPUT FILES"
  165. The output files contain portions of the original input file; otherwise,
  166. unchanged.
  167. .SH "EXTENDED DESCRIPTION"
  168. None.
  169. .SH "EXIT STATUS"
  170. The following exit values shall be returned:
  171. .IP "\00" 6
  172. Successful completion.
  173. .IP >0 6
  174. An error occurred.
  175. .SH "CONSEQUENCES OF ERRORS"
  176. Default.
  177. .LP
  178. .IR "The following sections are informative."
  179. .SH "APPLICATION USAGE"
  180. None.
  181. .SH EXAMPLES
  182. In the following examples
  183. .BR foo
  184. is a text file that contains 5\|000 lines.
  185. .IP " 1." 4
  186. Create five files,
  187. .BR xaa ,
  188. .BR xab ,
  189. .BR xac ,
  190. .BR xad ,
  191. and
  192. .BR xae :
  193. .RS 4
  194. .sp
  195. .RS 4
  196. .nf
  197. split foo
  198. .fi
  199. .P
  200. .RE
  201. .RE
  202. .IP " 2." 4
  203. Create five files, but the suffixed portion of the created
  204. files consists of three letters,
  205. .BR xaaa ,
  206. .BR xaab ,
  207. .BR xaac ,
  208. .BR xaad ,
  209. and
  210. .BR xaae :
  211. .RS 4
  212. .sp
  213. .RS 4
  214. .nf
  215. split -a 3 foo
  216. .fi
  217. .P
  218. .RE
  219. .RE
  220. .IP " 3." 4
  221. Create three files with four-letter suffixes and a supplied prefix,
  222. .BR bar_aaaa ,
  223. .BR bar_aaab ,
  224. and
  225. .BR bar_aaac :
  226. .RS 4
  227. .sp
  228. .RS 4
  229. .nf
  230. split -a 4 -l 2000 foo bar_
  231. .fi
  232. .P
  233. .RE
  234. .RE
  235. .IP " 4." 4
  236. Create as many files as are necessary to contain at most 20*1\|024
  237. bytes, each with the default prefix of
  238. .BR x
  239. and a five-letter suffix:
  240. .RS 4
  241. .sp
  242. .RS 4
  243. .nf
  244. split -a 5 -b 20k foo
  245. .fi
  246. .P
  247. .RE
  248. .RE
  249. .SH RATIONALE
  250. The
  251. .BR \-b
  252. option was added to provide a mechanism for splitting files other than
  253. by lines. While most uses of the
  254. .BR \-b
  255. option are for transmitting files over networks, some believed it would
  256. have additional uses.
  257. .P
  258. The
  259. .BR \-a
  260. option was added to overcome the limitation of being able to create
  261. only 676 files.
  262. .P
  263. Consideration was given to deleting this utility, using the rationale
  264. that the functionality provided by this utility is available via the
  265. .IR csplit
  266. utility (see
  267. .IR "\fIcsplit\fR\^").
  268. Upon reconsideration of the purpose of the User Portability Utilities
  269. option, it was decided to retain both this utility and the
  270. .IR csplit
  271. utility because users use both utilities and have historical
  272. expectations of their behavior. Furthermore, the splitting on byte
  273. boundaries in
  274. .IR split
  275. cannot be duplicated with the historical
  276. .IR csplit .
  277. .P
  278. The text ``\c
  279. .IR split
  280. shall not delete the files it created with valid suffixes'' would
  281. normally be assumed, but since the related utility,
  282. .IR csplit ,
  283. does delete files under some circumstances, the historical behavior of
  284. .IR split
  285. is made explicit to avoid misinterpretation.
  286. .P
  287. Earlier versions of this standard allowed a
  288. .BR \- \c
  289. .IR line_count
  290. option. This form is no longer specified by POSIX.1\(hy2008 but may be
  291. present in some implementations.
  292. .SH "FUTURE DIRECTIONS"
  293. None.
  294. .SH "SEE ALSO"
  295. .IR "\fIcsplit\fR\^"
  296. .P
  297. The Base Definitions volume of POSIX.1\(hy2017,
  298. .IR "Chapter 8" ", " "Environment Variables",
  299. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  300. .\"
  301. .SH COPYRIGHT
  302. Portions of this text are reprinted and reproduced in electronic form
  303. from IEEE Std 1003.1-2017, Standard for Information Technology
  304. -- Portable Operating System Interface (POSIX), The Open Group Base
  305. Specifications Issue 7, 2018 Edition,
  306. Copyright (C) 2018 by the Institute of
  307. Electrical and Electronics Engineers, Inc and The Open Group.
  308. In the event of any discrepancy between this version and the original IEEE and
  309. The Open Group Standard, the original IEEE and The Open Group Standard
  310. is the referee document. The original Standard can be obtained online at
  311. http://www.opengroup.org/unix/online.html .
  312. .PP
  313. Any typographical or formatting errors that appear
  314. in this page are most likely
  315. to have been introduced during the conversion of the source files to
  316. man page format. To report such errors, see
  317. https://www.kernel.org/doc/man-pages/reporting_bugs.html .