bin/cat/cat.1

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