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

cat.1p (8320B)


  1. '\" et
  2. .TH CAT "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. cat
  12. \(em concatenate and print files
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. cat \fB[\fR-u\fB] [\fIfile\fR...\fB]\fR
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR cat
  21. utility shall read files in sequence and shall write their contents
  22. to the standard output in the same sequence.
  23. .SH OPTIONS
  24. The
  25. .IR cat
  26. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  27. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  28. .P
  29. The following option shall be supported:
  30. .IP "\fB\-u\fP" 10
  31. Write bytes from the input file to the standard output without delay as
  32. each is read.
  33. .SH OPERANDS
  34. The following operand shall be supported:
  35. .IP "\fIfile\fR" 10
  36. A pathname of an input file. If no
  37. .IR file
  38. operands are specified, the standard input shall be used. If a
  39. .IR file
  40. is
  41. .BR '\-' ,
  42. the
  43. .IR cat
  44. utility shall read from the standard input at that point in the
  45. sequence. The
  46. .IR cat
  47. utility shall not close and reopen standard input when it is referenced
  48. in this way, but shall accept multiple occurrences of
  49. .BR '\-'
  50. as a
  51. .IR file
  52. operand.
  53. .SH STDIN
  54. The standard input shall be used only if no
  55. .IR file
  56. operands are specified, or if a
  57. .IR file
  58. operand is
  59. .BR '\-' .
  60. See the INPUT FILES section.
  61. .SH "INPUT FILES"
  62. The input files can be any file type.
  63. .SH "ENVIRONMENT VARIABLES"
  64. The following environment variables shall affect the execution of
  65. .IR cat :
  66. .IP "\fILANG\fP" 10
  67. Provide a default value for the internationalization variables that are
  68. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  69. .IR "Section 8.2" ", " "Internationalization Variables"
  70. for the precedence of internationalization variables used to determine
  71. the values of locale categories.)
  72. .IP "\fILC_ALL\fP" 10
  73. If set to a non-empty string value, override the values of all the
  74. other internationalization variables.
  75. .IP "\fILC_CTYPE\fP" 10
  76. Determine the locale for the interpretation of sequences of bytes of
  77. text data as characters (for example, single-byte as opposed to
  78. multi-byte characters in arguments).
  79. .IP "\fILC_MESSAGES\fP" 10
  80. .br
  81. Determine the locale that should be used to affect the format and
  82. contents of diagnostic messages written to standard error.
  83. .IP "\fINLSPATH\fP" 10
  84. Determine the location of message catalogs for the processing of
  85. .IR LC_MESSAGES .
  86. .SH "ASYNCHRONOUS EVENTS"
  87. Default.
  88. .SH STDOUT
  89. The standard output shall contain the sequence of bytes read from the
  90. input files. Nothing else shall be written to the standard output.
  91. If the standard output is a regular file, and is the same file as any
  92. of the input file operands, the implementation may treat this as an error.
  93. .SH STDERR
  94. The standard error shall be used only for diagnostic messages.
  95. .SH "OUTPUT FILES"
  96. None.
  97. .SH "EXTENDED DESCRIPTION"
  98. None.
  99. .SH "EXIT STATUS"
  100. The following exit values shall be returned:
  101. .IP "\00" 6
  102. All input files were output successfully.
  103. .IP >0 6
  104. An error occurred.
  105. .SH "CONSEQUENCES OF ERRORS"
  106. Default.
  107. .LP
  108. .IR "The following sections are informative."
  109. .SH "APPLICATION USAGE"
  110. The
  111. .BR \-u
  112. option has value in prototyping non-blocking reads from FIFOs. The
  113. intent is to support the following sequence:
  114. .sp
  115. .RS 4
  116. .nf
  117. mkfifo foo
  118. cat -u foo > /dev/tty13 &
  119. cat -u > foo
  120. .fi
  121. .P
  122. .RE
  123. .P
  124. It is unspecified whether standard output is or is not buffered in the
  125. default case. This is sometimes of interest when standard output is
  126. associated with a terminal, since buffering may delay the output. The
  127. presence of the
  128. .BR \-u
  129. option guarantees that unbuffered I/O is available. It is
  130. implementation-defined whether the
  131. .IR cat
  132. utility buffers output if the
  133. .BR \-u
  134. option is not specified. Traditionally, the
  135. .BR \-u
  136. option is implemented using the equivalent of the
  137. \fIsetvbuf\fR()
  138. function defined in the System Interfaces volume of POSIX.1\(hy2017.
  139. .SH EXAMPLES
  140. The following command:
  141. .sp
  142. .RS 4
  143. .nf
  144. cat myfile
  145. .fi
  146. .P
  147. .RE
  148. .P
  149. writes the contents of the file
  150. .BR myfile
  151. to standard output.
  152. .P
  153. The following command:
  154. .sp
  155. .RS 4
  156. .nf
  157. cat doc1 doc2 > doc.all
  158. .fi
  159. .P
  160. .RE
  161. .P
  162. concatenates the files
  163. .BR doc1
  164. and
  165. .BR doc2
  166. and writes the result to
  167. .BR doc.all .
  168. .P
  169. Because of the shell language mechanism used to perform output
  170. redirection, a command such as this:
  171. .sp
  172. .RS 4
  173. .nf
  174. cat doc doc.end > doc
  175. .fi
  176. .P
  177. .RE
  178. .P
  179. causes the original data in
  180. .BR doc
  181. to be lost before
  182. .IR cat
  183. even begins execution. This is true whether the
  184. .IR cat
  185. command fails with an error or silently succeeds (the specification
  186. allows both behaviors). In order to append the contents of
  187. .BR doc.end
  188. without losing the original contents of
  189. .BR doc ,
  190. this command should be used instead:
  191. .sp
  192. .RS 4
  193. .nf
  194. cat doc.end >> doc
  195. .fi
  196. .P
  197. .RE
  198. .P
  199. The command:
  200. .sp
  201. .RS 4
  202. .nf
  203. cat start - middle - end > file
  204. .fi
  205. .P
  206. .RE
  207. .P
  208. when standard input is a terminal, gets two arbitrary pieces of input
  209. from the terminal with a single invocation of
  210. .IR cat .
  211. Note, however, that if standard input is a regular file, this would be
  212. equivalent to the command:
  213. .sp
  214. .RS 4
  215. .nf
  216. cat start - middle /dev/null end > file
  217. .fi
  218. .P
  219. .RE
  220. .P
  221. because the entire contents of the file would be consumed by
  222. .IR cat
  223. the first time
  224. .BR '\-'
  225. was used as a
  226. .IR file
  227. operand and an end-of-file condition would be detected immediately when
  228. .BR '\-'
  229. was referenced the second time.
  230. .SH RATIONALE
  231. Historical versions of the
  232. .IR cat
  233. utility include the
  234. .BR \-e ,
  235. .BR \-t ,
  236. and
  237. .BR \-v ,
  238. options which permit the ends of lines,
  239. <tab>
  240. characters, and invisible characters, respectively, to be rendered visible
  241. in the output. The standard developers omitted these options because
  242. they provide too fine a degree of control over what is made visible,
  243. and similar output can be obtained using a command such as:
  244. .sp
  245. .RS 4
  246. .nf
  247. sed -n l pathname
  248. .fi
  249. .P
  250. .RE
  251. .P
  252. The latter also has the advantage that its output is unambiguous,
  253. whereas the output of historical
  254. .IR cat
  255. .BR \-etv
  256. is not.
  257. .P
  258. The
  259. .BR \-s
  260. option was omitted because it corresponds to different functions in BSD
  261. and System V-based systems. The BSD
  262. .BR \-s
  263. option to squeeze blank lines can be accomplished by the shell script
  264. shown in the following example:
  265. .sp
  266. .RS 4
  267. .nf
  268. sed -n \(aq
  269. # Write non-empty lines.
  270. /./ {
  271. p
  272. d
  273. }
  274. # Write a single empty line, then look for more empty lines.
  275. /\(ha$/ p
  276. # Get next line, discard the held <newline> (empty line),
  277. # and look for more empty lines.
  278. :Empty
  279. /\(ha$/ {
  280. N
  281. s/.//
  282. b Empty
  283. }
  284. # Write the non-empty line before going back to search
  285. # for the first in a set of empty lines.
  286. p
  287. \&\(aq
  288. .fi
  289. .P
  290. .RE
  291. .P
  292. The System V
  293. .BR \-s
  294. option to silence error messages can be accomplished by redirecting the
  295. standard error. Note that the BSD documentation for
  296. .IR cat
  297. uses the term ``blank line'' to mean the same as the POSIX ``empty
  298. line'': a line consisting only of a
  299. <newline>.
  300. .P
  301. The BSD
  302. .BR \-n
  303. option was omitted because similar functionality can be obtained from
  304. the
  305. .BR \-n
  306. option of the
  307. .IR pr
  308. utility.
  309. .SH "FUTURE DIRECTIONS"
  310. None.
  311. .SH "SEE ALSO"
  312. .IR "\fImore\fR\^"
  313. .P
  314. The Base Definitions volume of POSIX.1\(hy2017,
  315. .IR "Chapter 8" ", " "Environment Variables",
  316. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  317. .P
  318. The System Interfaces volume of POSIX.1\(hy2017,
  319. .IR "\fIsetvbuf\fR\^(\|)"
  320. .\"
  321. .SH COPYRIGHT
  322. Portions of this text are reprinted and reproduced in electronic form
  323. from IEEE Std 1003.1-2017, Standard for Information Technology
  324. -- Portable Operating System Interface (POSIX), The Open Group Base
  325. Specifications Issue 7, 2018 Edition,
  326. Copyright (C) 2018 by the Institute of
  327. Electrical and Electronics Engineers, Inc and The Open Group.
  328. In the event of any discrepancy between this version and the original IEEE and
  329. The Open Group Standard, the original IEEE and The Open Group Standard
  330. is the referee document. The original Standard can be obtained online at
  331. http://www.opengroup.org/unix/online.html .
  332. .PP
  333. Any typographical or formatting errors that appear
  334. in this page are most likely
  335. to have been introduced during the conversion of the source files to
  336. man page format. To report such errors, see
  337. https://www.kernel.org/doc/man-pages/reporting_bugs.html .