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