xref: /freebsd/bin/cat/cat.1 (revision 4c9a0adad18263ec8725d9bfc5f560c6ad1da8bd)
1.\"-
2.\" Copyright (c) 1989, 1990, 1993
3.\"	The Regents of the University of California.  All rights reserved.
4.\"
5.\" This code is derived from software contributed to Berkeley by
6.\" the Institute of Electrical and Electronics Engineers, Inc.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)cat.1	8.3 (Berkeley) 5/2/95
33.\"
34.Dd January 29, 2013
35.Dt CAT 1
36.Os
37.Sh NAME
38.Nm cat
39.Nd concatenate and print files
40.Sh SYNOPSIS
41.Nm
42.Op Fl belnstuv
43.Op Ar
44.Sh DESCRIPTION
45The
46.Nm
47utility reads files sequentially, writing them to the standard output.
48The
49.Ar file
50operands are processed in command-line order.
51If
52.Ar file
53is a single dash
54.Pq Sq Fl
55or absent,
56.Nm
57reads from the standard input.
58If
59.Ar file
60is a
61.Ux
62domain socket,
63.Nm
64connects to it and then reads it until
65.Dv EOF .
66This complements the
67.Ux
68domain binding capability available in
69.Xr inetd 8 .
70.Pp
71The options are as follows:
72.Bl -tag -width indent
73.It Fl b
74Number the non-blank output lines, starting at 1.
75.It Fl e
76Display non-printing characters (see the
77.Fl v
78option), and display a dollar sign
79.Pq Ql \&$
80at the end of each line.
81.It Fl l
82Set an exclusive advisory lock on the standard output file descriptor.
83This lock is set using
84.Xr fcntl 2
85with the
86.Dv F_SETLKW
87command.
88If the output file is already locked,
89.Nm
90will block until the lock is acquired.
91.It Fl n
92Number the output lines, starting at 1.
93.It Fl s
94Squeeze multiple adjacent empty lines, causing the output to be
95single spaced.
96.It Fl t
97Display non-printing characters (see the
98.Fl v
99option), and display tab characters as
100.Ql ^I .
101.It Fl u
102Disable output buffering.
103.It Fl v
104Display non-printing characters so they are visible.
105Control characters print as
106.Ql ^X
107for control-X; the delete
108character (octal 0177) prints as
109.Ql ^? .
110.Pf Non- Tn ASCII
111characters (with the high bit set) are printed as
112.Ql M-
113(for meta) followed by the character for the low 7 bits.
114.El
115.Sh EXIT STATUS
116.Ex -std
117.Sh EXAMPLES
118The command:
119.Pp
120.Dl "cat file1"
121.Pp
122will print the contents of
123.Pa file1
124to the standard output.
125.Pp
126The command:
127.Pp
128.Dl "cat file1 file2 > file3"
129.Pp
130will sequentially print the contents of
131.Pa file1
132and
133.Pa file2
134to the file
135.Pa file3 ,
136truncating
137.Pa file3
138if it already exists.
139See the manual page for your shell (e.g.,
140.Xr sh 1 )
141for more information on redirection.
142.Pp
143The command:
144.Pp
145.Dl "cat file1 - file2 - file3"
146.Pp
147will print the contents of
148.Pa file1 ,
149print data it receives from the standard input until it receives an
150.Dv EOF
151.Pq Sq ^D
152character, print the contents of
153.Pa file2 ,
154read and output contents of the standard input again, then finally output
155the contents of
156.Pa file3 .
157Note that if the standard input referred to a file, the second dash
158on the command-line would have no effect, since the entire contents of the file
159would have already been read and printed by
160.Nm
161when it encountered the first
162.Sq Fl
163operand.
164.Sh SEE ALSO
165.Xr head 1 ,
166.Xr more 1 ,
167.Xr pr 1 ,
168.Xr sh 1 ,
169.Xr tail 1 ,
170.Xr vis 1 ,
171.Xr zcat 1 ,
172.Xr fcntl 2 ,
173.Xr setbuf 3
174.Rs
175.%A Rob Pike
176.%T "UNIX Style, or cat -v Considered Harmful"
177.%J "USENIX Summer Conference Proceedings"
178.%D 1983
179.Re
180.Sh STANDARDS
181The
182.Nm
183utility is compliant with the
184.St -p1003.2-92
185specification.
186.Pp
187The flags
188.Op Fl belnstv
189are extensions to the specification.
190.Sh HISTORY
191A
192.Nm
193utility appeared in
194.At v1 .
195.An Dennis Ritchie
196designed and wrote the first man page.
197It appears to have been for
198.Nm .
199.Sh BUGS
200Because of the shell language mechanism used to perform output
201redirection, the command
202.Dq Li cat file1 file2 > file1
203will cause the original data in
204.Pa file1
205to be destroyed!
206.Pp
207The
208.Nm
209utility does not recognize multibyte characters when the
210.Fl t
211or
212.Fl v
213option is in effect.
214