| blob | ff3cb381485157472308d5ec91505fce6cc40726 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
46 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
47 .\"
48 .TH CAT 1 "Apr 8, 2008"
49 .SH NAME
50 cat \- concatenate and display files
51 .SH SYNOPSIS
52 .SS "\fB/usr/bin/cat\fR"
53 .LP
54 .nf
55 \fB/usr/bin/cat\fR [\fB-nbsuvet\fR] [\fIfile\fR...]
56 .fi
58 .SS "\fBksh93\fR"
59 .LP
60 .nf
61 \fBcat\fR [\fB-bdenstuvABDEST\fR] [\fIfile\fR...]
62 .fi
64 .SH DESCRIPTION
65 .SS "\fB/usr/bin/cat\fR"
66 .sp
67 .LP
68 The \fBcat\fR utility reads each \fIfile\fR in sequence and writes it on the
69 standard output. Thus:
70 .sp
71 .in +2
72 .nf
73 example% \fBcat file\fR
74 .fi
75 .in -2
76 .sp
78 .sp
79 .LP
80 prints \fIfile\fR on your terminal, and:
81 .sp
82 .in +2
83 .nf
84 example% \fBcat file1 file2 >file3\fR
85 .fi
86 .in -2
87 .sp
89 .sp
90 .LP
91 concatenates \fIfile1\fR and \fIfile2\fR, and writes the results in
92 \fIfile3\fR. If no input file is given, \fBcat\fR reads from the standard input
93 file.
94 .SS "\fBksh93\fR"
95 .sp
96 .LP
97 The \fBcat\fR built-in in \fBksh93\fR is associated with the \fB/bin\fR and
98 \fB/usr/bin\fR paths. It is invoked when \fBcat\fR is executed without a
99 pathname prefix and the pathname search finds a \fB/bin/cat\fR or
100 \fB/usr/bin/cat\fR executable. \fBcat\fR copies each file in sequence to the
101 standard output. If no file is specified, or if the file is \fB-\fR, \fBcat\fR
102 copies from standard input starting at the current location.
103 .SH OPTIONS
104 .SS "\fB/usr/bin/cat\fR"
105 .sp
106 .LP
107 The following options are supported by \fB/usr/bin/cat\fR:
108 .sp
109 .ne 2
110 .na
111 \fB\fB-b\fR\fR
112 .ad
113 .RS 6n
114 Number the lines, as \fB-n\fR, but omit the line numbers from blank lines.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fB-n\fR\fR
121 .ad
122 .RS 6n
123 Precede each line output with its line number.
124 .RE
126 .sp
127 .ne 2
128 .na
129 \fB\fB-s\fR\fR
130 .ad
131 .RS 6n
132 \fBcat\fR is silent about non-existent files.
133 .RE
135 .sp
136 .ne 2
137 .na
138 \fB\fB-u\fR\fR
139 .ad
140 .RS 6n
141 The output is not buffered.
142 .sp
143 Buffered output is the default.
144 .RE
146 .sp
147 .ne 2
148 .na
149 \fB\fB-v\fR\fR
150 .ad
151 .RS 6n
152 Non-printing characters, with the exception of tabs, NEWLINEs and form feeds,
153 are printed visibly. ASCII control characters (octal \fB000\fR \(mi \fB037\fR)
154 are printed as \fB^\fR\fIn,\fR where \fIn\fR is the corresponding ASCII
155 character in the range octal 100 \(mi 137 (@, A, B, C, ..., X, Y, Z, [, \e,
156 ], ^, and _); the \fBDEL\fR character (octal \fB0177\fR) is printed \fB^?\fR.
157 Other non-printable characters are printed as \fBM-\fR\fIx,\fR where \fIx\fR is
158 the ASCII character specified by the low-order seven bits.
159 .RE
161 .sp
162 .LP
163 When used with the \fB-v\fR option, the following options can be used:
164 .sp
165 .ne 2
166 .na
167 \fB\fB-e\fR\fR
168 .ad
169 .RS 6n
170 A \fB$\fR character is printed at the end of each line, prior to the NEWLINE.
171 .RE
173 .sp
174 .ne 2
175 .na
176 \fB\fB-t\fR\fR
177 .ad
178 .RS 6n
179 Tabs are printed as \fB^I\fRs and form feeds to be printed as \fB^L\fRs.
180 .RE
182 .sp
183 .LP
184 The \fB-e\fR and \fB-t\fR options are ignored if the \fB-v\fR option is not
185 specified.
186 .SS "\fBksh93\fR"
187 .sp
188 .LP
189 \fBksh93\fR \fBcat\fR supports the following options:
190 .sp
191 .ne 2
192 .na
193 \fB\fB-b\fR \fB--number-nonblank\fR\fR
194 .ad
195 .RS 25n
196 Number lines as with \fB-n\fR but omit line numbers from blank lines.
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fB\fB-d\fR \fB--dos-input\fR\fR
203 .ad
204 .RS 25n
205 Open input files in text mode. Removes RETURNs in front of NEWLINEs on some
206 systems.
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fB-e\fR\fR
213 .ad
214 .RS 25n
215 Equivalent to \fB-vE\fR.
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fB-n\fR \fB--number\fR\fR
222 .ad
223 .RS 25n
224 Insert a line number at the beginning of each line.
225 .RE
227 .sp
228 .ne 2
229 .na
230 \fB\fB-s\fR\fR
231 .ad
232 .RS 25n
233 Equivalent to \fB-S\fR for \fBatt universe\fR and \fB-B\fR otherwise.
234 .RE
236 .sp
237 .ne 2
238 .na
239 \fB\fB-t\fR\fR
240 .ad
241 .RS 25n
242 Equivalent to \fB-vT\fR.
243 .RE
245 .sp
246 .ne 2
247 .na
248 \fB\fB-u\fR \fB--unbuffer\fR\fR
249 .ad
250 .RS 25n
251 Do not delay the output by buffering.
252 .RE
254 .sp
255 .ne 2
256 .na
257 \fB\fB-v\fR \fB--show-nonprinting\fR\fR
258 .ad
259 .RS 25n
260 Cause non-printing characters (with the exception of TABs, NEWLINEs, and form
261 feeds) to be output as printable character sequences. \fBASCII\fR control
262 characters are printed as \fB^n\fR, where \fIn\fR is the corresponding
263 \fBASCII\fR character in the range octal \fB100\fR-\fB137\fR. The DEL character
264 (octal \fB0177\fR) is copied as \fB^?\fR. Other non-printable characters are
265 copied as \fBM-\fR\fIx\fR where \fIx\fR is the \fBASCII\fR character specified
266 by the low-order seven bits. Multi-byte characters in the current locale are
267 treated as printable characters.
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fB-A\fR \fB--show-all\fR\fR
274 .ad
275 .RS 25n
276 Equivalent to \fB-vET\fR.
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fB-B\fR \fB--squeeze-blank\fR\fR
283 .ad
284 .RS 25n
285 Replace multiple adjacent NEWLINE characters with one NEWLINE.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fB-D\fR \fB--dos-output\fR\fR
292 .ad
293 .RS 25n
294 Open output files in text mode. Insert RETURNs in front of NEWLINEs on some
295 systems.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fB-E\fR \fB--show-ends\fR\fR
302 .ad
303 .RS 25n
304 Insert a \fB$\fR before each NEWLINE.
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fB-S\fR \fB--silent\fR\fR
311 .ad
312 .RS 25n
313 \fBcat\fR is silent about non-existent files.
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fB-T\fR \fB--show-blank\fR\fR
320 .ad
321 .RS 25n
322 Copies TABs as \fB^I\fR and form feeds as \fB^L\fR.
323 .RE
325 .SH OPERANDS
326 .sp
327 .LP
328 The following operand is supported:
329 .sp
330 .ne 2
331 .na
332 \fB\fIfile\fR\fR
333 .ad
334 .RS 8n
335 A path name of an input file. If no \fIfile\fR is specified, the standard input
336 is used. If \fIfile\fR is \fB\|\(mi\|\fR, \fBcat\fR reads from the standard
337 input at that point in the sequence. \fBcat\fR does not close and reopen
338 standard input when it is referenced in this way, but accepts multiple
339 occurrences of \fB\|\(mi\|\fR as \fIfile\fR.
340 .RE
342 .SH USAGE
343 .sp
344 .LP
345 See \fBlargefile\fR(5) for the description of the behavior of \fBcat\fR when
346 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
347 .SH EXAMPLES
348 .LP
349 \fBExample 1 \fRConcatenating a File
350 .sp
351 .LP
352 The following command writes the contents of the file \fBmyfile\fR to standard
353 output:
355 .sp
356 .in +2
357 .nf
358 example% \fBcat myfile\fR
359 .fi
360 .in -2
361 .sp
363 .LP
364 \fBExample 2 \fRConcatenating Two files into One
365 .sp
366 .LP
367 The following command concatenates the files \fBdoc1\fR and \fBdoc2\fR and
368 writes the result to \fBdoc.all\fR.
370 .sp
371 .in +2
372 .nf
373 example% \fBcat doc1 doc2 > doc.all\fR
374 .fi
375 .in -2
376 .sp
378 .LP
379 \fBExample 3 \fRConcatenating Two Arbitrary Pieces of Input with a Single
380 Invocation
381 .sp
382 .LP
383 When standard input is a terminal, the following command gets two arbitrary
384 pieces of input from the terminal with a single invocation of \fBcat\fR:
386 .sp
387 .in +2
388 .nf
389 example% \fBcat start - middle - end > file\fR
390 .fi
391 .in -2
392 .sp
394 .sp
395 .LP
396 when standard input is a terminal, gets two arbitrary pieces of input from the
397 terminal with a single invocation of \fBcat\fR.
399 .sp
400 .LP
401 If standard input is a regular file,
403 .sp
404 .in +2
405 .nf
406 example% \fBcat start - middle - end > file\fR
407 .fi
408 .in -2
409 .sp
411 .sp
412 .LP
413 would be equivalent to the following command:
415 .sp
416 .in +2
417 .nf
418 \fBcat start - middle /dev/null end > file\fR
419 .fi
420 .in -2
421 .sp
423 .sp
424 .LP
425 because the entire contents of the file would be consumed by \fBcat\fR the
426 first time \fB\|\(mi\|\fR was used as a \fIfile\fR operand and an end-of-file
427 condition would be detected immediately when \fB\|\(mi\|\fRwas referenced the
428 second time.
430 .SH ENVIRONMENT VARIABLES
431 .sp
432 .LP
433 See \fBenviron\fR(5) for descriptions of the following environment variables
434 that affect the execution of \fBcat\fR: \fBLANG\fR, \fBLC_ALL\fR,
435 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
436 .SH EXIT STATUS
437 .sp
438 .LP
439 The following exit values are returned:
440 .sp
441 .ne 2
442 .na
443 \fB\fB0\fR\fR
444 .ad
445 .RS 6n
446 All input files were output successfully.
447 .RE
449 .sp
450 .ne 2
451 .na
452 \fB\fB>0\fR\fR
453 .ad
454 .RS 6n
455 An error occurred.
456 .RE
458 .SH ATTRIBUTES
459 .sp
460 .LP
461 See \fBattributes\fR(5) for descriptions of the following attributes:
462 .SS "\fB/usr/bin/cat\fR"
463 .sp
465 .sp
466 .TS
467 box;
468 c | c
469 l | l .
470 ATTRIBUTE TYPE ATTRIBUTE VALUE
471 _
472 CSI Enabled
473 _
474 Interface Stability Committed
475 _
476 Standard See \fBstandards\fR(5).
477 .TE
479 .SS "\fBksh93\fR"
480 .sp
482 .sp
483 .TS
484 box;
485 c | c
486 l | l .
487 ATTRIBUTE TYPE ATTRIBUTE VALUE
488 _
489 Interface Stability See below.
490 .TE
492 .sp
493 .LP
494 The \fBksh93\fR built-in binding to \fB/bin\fR and \fB/usr/bin\fR is Volatile.
495 The built-in interfaces are Uncommitted.
496 .SH SEE ALSO
497 .sp
498 .LP
499 \fBtouch\fR(1), \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5),
500 \fBstandards\fR(5)
501 .SH NOTES
502 .sp
503 .LP
504 Redirecting the output of \fBcat\fR onto one of the files being read causes the
505 loss of the data originally in the file being read. For example,
506 .sp
507 .in +2
508 .nf
509 example% \fBcat filename1 filename2 > filename1\fR
510 .fi
511 .in -2
512 .sp
514 .sp
515 .LP
516 causes the original data in \fBfilename1\fR to be lost.