2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "CAT" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" cat
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
cat \- concatenate and print files
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fBcat\fP \fB[\fP\fB-u\fP\fB][\fP\fIfile\fP \fB...\fP\fB]\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIcat\fP utility shall read files in sequence and shall write
|
|
|
|
their contents to the standard output in the same
|
|
|
|
sequence.
|
|
|
|
.SH OPTIONS
|
|
|
|
.LP
|
|
|
|
The \fIcat\fP utility shall conform to the Base Definitions volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
|
|
.LP
|
|
|
|
The following option shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fB-u\fP
|
|
|
|
Write bytes from the input file to the standard output without delay
|
|
|
|
as each is read.
|
|
|
|
.sp
|
|
|
|
.SH OPERANDS
|
|
|
|
.LP
|
|
|
|
The following operand shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fIfile\fP
|
|
|
|
A pathname of an input file. If no \fIfile\fP operands are specified,
|
|
|
|
the standard input shall be used. If a \fIfile\fP is
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB'-'\fP, the \fIcat\fP utility shall read from the standard input
|
2004-11-03 13:51:07 +00:00
|
|
|
at that point in the sequence. The \fIcat\fP utility
|
|
|
|
shall not close and reopen standard input when it is referenced in
|
|
|
|
this way, but shall accept multiple occurrences of \fB'-'\fP
|
|
|
|
as a \fIfile\fP operand.
|
|
|
|
.sp
|
|
|
|
.SH STDIN
|
|
|
|
.LP
|
|
|
|
The standard input shall be used only if no \fIfile\fP operands are
|
|
|
|
specified, or if a \fIfile\fP operand is \fB'-'\fP .
|
|
|
|
See the INPUT FILES section.
|
|
|
|
.SH INPUT FILES
|
|
|
|
.LP
|
|
|
|
The input files can be any file type.
|
|
|
|
.SH ENVIRONMENT VARIABLES
|
|
|
|
.LP
|
|
|
|
The following environment variables shall affect the execution of
|
|
|
|
\fIcat\fP:
|
|
|
|
.TP 7
|
|
|
|
\fILANG\fP
|
|
|
|
Provide a default value for the internationalization variables that
|
|
|
|
are unset or null. (See the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
|
|
for
|
|
|
|
the precedence of internationalization variables used to determine
|
|
|
|
the values of locale categories.)
|
|
|
|
.TP 7
|
|
|
|
\fILC_ALL\fP
|
|
|
|
If set to a non-empty string value, override the values of all the
|
|
|
|
other internationalization variables.
|
|
|
|
.TP 7
|
|
|
|
\fILC_CTYPE\fP
|
|
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
|
|
of text data as characters (for example, single-byte as
|
|
|
|
opposed to multi-byte characters in arguments).
|
|
|
|
.TP 7
|
|
|
|
\fILC_MESSAGES\fP
|
|
|
|
Determine the locale that should be used to affect the format and
|
|
|
|
contents of diagnostic messages written to standard
|
|
|
|
error.
|
|
|
|
.TP 7
|
|
|
|
\fINLSPATH\fP
|
|
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
|
|
\&.\fP
|
|
|
|
.sp
|
|
|
|
.SH ASYNCHRONOUS EVENTS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.SH STDOUT
|
|
|
|
.LP
|
|
|
|
The standard output shall contain the sequence of bytes read from
|
|
|
|
the input files. Nothing else shall be written to the standard
|
|
|
|
output.
|
|
|
|
.SH STDERR
|
|
|
|
.LP
|
|
|
|
The standard error shall be used only for diagnostic messages.
|
|
|
|
.SH OUTPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXTENDED DESCRIPTION
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXIT STATUS
|
|
|
|
.LP
|
|
|
|
The following exit values shall be returned:
|
|
|
|
.TP 7
|
|
|
|
\ 0
|
|
|
|
All input files were output successfully.
|
|
|
|
.TP 7
|
|
|
|
>0
|
|
|
|
An error occurred.
|
|
|
|
.sp
|
|
|
|
.SH CONSEQUENCES OF ERRORS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
The \fB-u\fP option has value in prototyping non-blocking reads from
|
|
|
|
FIFOs. The intent is to support the following
|
|
|
|
sequence:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBmkfifo foo
|
|
|
|
cat -u foo > /dev/tty13 &
|
|
|
|
cat -u > foo
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
It is unspecified whether standard output is or is not buffered in
|
|
|
|
the default case. This is sometimes of interest when standard
|
|
|
|
output is associated with a terminal, since buffering may delay the
|
|
|
|
output. The presence of the \fB-u\fP option guarantees that
|
|
|
|
unbuffered I/O is available. It is implementation-defined whether
|
|
|
|
the \fIcat\fP utility buffers output if the \fB-u\fP option is
|
|
|
|
not specified. Traditionally, the \fB-u\fP option is implemented using
|
|
|
|
the equivalent of the \fIsetvbuf\fP() function defined in the System
|
|
|
|
Interfaces volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001.
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
The following command:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBcat myfile
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
writes the contents of the file \fBmyfile\fP to standard output.
|
|
|
|
.LP
|
|
|
|
The following command:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBcat doc1 doc2 > doc.all
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
concatenates the files \fBdoc1\fP and \fBdoc2\fP and writes the result
|
|
|
|
to \fBdoc.all\fP.
|
|
|
|
.LP
|
|
|
|
Because of the shell language mechanism used to perform output redirection,
|
|
|
|
a command such as this:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBcat doc doc.end > doc
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
causes the original data in \fBdoc\fP to be lost.
|
|
|
|
.LP
|
|
|
|
The command:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBcat start - middle - end > file
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
when standard input is a terminal, gets two arbitrary pieces of input
|
|
|
|
from the terminal with a single invocation of \fIcat\fP.
|
|
|
|
Note, however, that if standard input is a regular file, this would
|
|
|
|
be equivalent to the command:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBcat start - middle /dev/null end > file
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
because the entire contents of the file would be consumed by \fIcat\fP
|
|
|
|
the first time \fB'-'\fP was used as a \fIfile\fP
|
|
|
|
operand and an end-of-file condition would be detected immediately
|
|
|
|
when \fB'-'\fP was referenced the second time.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
Historical versions of the \fIcat\fP utility include the options \fB-e\fP,
|
|
|
|
\fB-t\fP, and \fB-v\fP, which permit the ends of
|
|
|
|
lines, <tab>s, and invisible characters, respectively, to be rendered
|
|
|
|
visible in the output. The standard developers omitted
|
|
|
|
these options because they provide too fine a degree of control over
|
|
|
|
what is made visible, and similar output can be obtained using
|
|
|
|
a command such as:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBsed -n -e 's/$/$/' -e l pathname
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The \fB-s\fP option was omitted because it corresponds to different
|
|
|
|
functions in BSD and System V-based systems. The BSD
|
|
|
|
\fB-s\fP option to squeeze blank lines can be accomplished by the
|
|
|
|
shell script shown in the following example:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBsed -n '
|
|
|
|
# Write non-empty lines.
|
|
|
|
/./ {
|
|
|
|
p
|
|
|
|
d
|
|
|
|
}
|
|
|
|
# Write a single empty line, then look for more empty lines.
|
|
|
|
/^$/ p
|
|
|
|
# Get next line, discard the held <newline> (empty line),
|
|
|
|
# and look for more empty lines.
|
|
|
|
:Empty
|
|
|
|
/^$/ {
|
|
|
|
N
|
|
|
|
s/.//
|
|
|
|
b Empty
|
|
|
|
}
|
|
|
|
# Write the non-empty line before going back to search
|
|
|
|
# for the first in a set of empty lines.
|
|
|
|
p
|
|
|
|
'
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The System V \fB-s\fP option to silence error messages can be accomplished
|
|
|
|
by redirecting the standard error. Note that the BSD
|
|
|
|
documentation for \fIcat\fP uses the term "blank line" to mean the
|
|
|
|
same as the POSIX "empty line'': a line consisting only of a
|
|
|
|
<newline>.
|
|
|
|
.LP
|
|
|
|
The BSD \fB-n\fP option was omitted because similar functionality
|
|
|
|
can be obtained from the \fB-n\fP option of the \fIpr\fP utility.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 06:36:16 +00:00
|
|
|
\fImore\fP, the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
|
2004-11-03 13:51:07 +00:00
|
|
|
\fIsetvbuf\fP()
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version and the original IEEE and
|
|
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
|
|
is the referee document. The original Standard can be obtained online at
|
|
|
|
http://www.opengroup.org/unix/online.html .
|