cat.1p (8320B)
- '\" et
- .TH CAT "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .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.
- .\"
- .SH NAME
- cat
- \(em concatenate and print files
- .SH SYNOPSIS
- .LP
- .nf
- cat \fB[\fR-u\fB] [\fIfile\fR...\fB]\fR
- .fi
- .SH DESCRIPTION
- The
- .IR cat
- utility shall read files in sequence and shall write their contents
- to the standard output in the same sequence.
- .SH OPTIONS
- The
- .IR cat
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following option shall be supported:
- .IP "\fB\-u\fP" 10
- Write bytes from the input file to the standard output without delay as
- each is read.
- .SH OPERANDS
- The following operand shall be supported:
- .IP "\fIfile\fR" 10
- A pathname of an input file. If no
- .IR file
- operands are specified, the standard input shall be used. If a
- .IR file
- is
- .BR '\-' ,
- the
- .IR cat
- utility shall read from the standard input at that point in the
- sequence. The
- .IR cat
- utility shall not close and reopen standard input when it is referenced
- in this way, but shall accept multiple occurrences of
- .BR '\-'
- as a
- .IR file
- operand.
- .SH STDIN
- The standard input shall be used only if no
- .IR file
- operands are specified, or if a
- .IR file
- operand is
- .BR '\-' .
- See the INPUT FILES section.
- .SH "INPUT FILES"
- The input files can be any file type.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR cat :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- 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).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- The standard output shall contain the sequence of bytes read from the
- input files. Nothing else shall be written to the standard output.
- If the standard output is a regular file, and is the same file as any
- of the input file operands, the implementation may treat this as an error.
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- All input files were output successfully.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- The
- .BR \-u
- option has value in prototyping non-blocking reads from FIFOs. The
- intent is to support the following sequence:
- .sp
- .RS 4
- .nf
- mkfifo foo
- cat -u foo > /dev/tty13 &
- cat -u > foo
- .fi
- .P
- .RE
- .P
- 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
- .BR \-u
- option guarantees that unbuffered I/O is available. It is
- implementation-defined whether the
- .IR cat
- utility buffers output if the
- .BR \-u
- option is not specified. Traditionally, the
- .BR \-u
- option is implemented using the equivalent of the
- \fIsetvbuf\fR()
- function defined in the System Interfaces volume of POSIX.1\(hy2017.
- .SH EXAMPLES
- The following command:
- .sp
- .RS 4
- .nf
- cat myfile
- .fi
- .P
- .RE
- .P
- writes the contents of the file
- .BR myfile
- to standard output.
- .P
- The following command:
- .sp
- .RS 4
- .nf
- cat doc1 doc2 > doc.all
- .fi
- .P
- .RE
- .P
- concatenates the files
- .BR doc1
- and
- .BR doc2
- and writes the result to
- .BR doc.all .
- .P
- Because of the shell language mechanism used to perform output
- redirection, a command such as this:
- .sp
- .RS 4
- .nf
- cat doc doc.end > doc
- .fi
- .P
- .RE
- .P
- causes the original data in
- .BR doc
- to be lost before
- .IR cat
- even begins execution. This is true whether the
- .IR cat
- command fails with an error or silently succeeds (the specification
- allows both behaviors). In order to append the contents of
- .BR doc.end
- without losing the original contents of
- .BR doc ,
- this command should be used instead:
- .sp
- .RS 4
- .nf
- cat doc.end >> doc
- .fi
- .P
- .RE
- .P
- The command:
- .sp
- .RS 4
- .nf
- cat start - middle - end > file
- .fi
- .P
- .RE
- .P
- when standard input is a terminal, gets two arbitrary pieces of input
- from the terminal with a single invocation of
- .IR cat .
- Note, however, that if standard input is a regular file, this would be
- equivalent to the command:
- .sp
- .RS 4
- .nf
- cat start - middle /dev/null end > file
- .fi
- .P
- .RE
- .P
- because the entire contents of the file would be consumed by
- .IR cat
- the first time
- .BR '\-'
- was used as a
- .IR file
- operand and an end-of-file condition would be detected immediately when
- .BR '\-'
- was referenced the second time.
- .SH RATIONALE
- Historical versions of the
- .IR cat
- utility include the
- .BR \-e ,
- .BR \-t ,
- and
- .BR \-v ,
- options which permit the ends of lines,
- <tab>
- characters, 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 4
- .nf
- sed -n l pathname
- .fi
- .P
- .RE
- .P
- The latter also has the advantage that its output is unambiguous,
- whereas the output of historical
- .IR cat
- .BR \-etv
- is not.
- .P
- The
- .BR \-s
- option was omitted because it corresponds to different functions in BSD
- and System V-based systems. The BSD
- .BR \-s
- option to squeeze blank lines can be accomplished by the shell script
- shown in the following example:
- .sp
- .RS 4
- .nf
- sed -n \(aq
- # Write non-empty lines.
- /./ {
- p
- d
- }
- # Write a single empty line, then look for more empty lines.
- /\(ha$/ p
- # Get next line, discard the held <newline> (empty line),
- # and look for more empty lines.
- :Empty
- /\(ha$/ {
- N
- s/.//
- b Empty
- }
- # Write the non-empty line before going back to search
- # for the first in a set of empty lines.
- p
- \&\(aq
- .fi
- .P
- .RE
- .P
- The System V
- .BR \-s
- option to silence error messages can be accomplished by redirecting the
- standard error. Note that the BSD documentation for
- .IR cat
- uses the term ``blank line'' to mean the same as the POSIX ``empty
- line'': a line consisting only of a
- <newline>.
- .P
- The BSD
- .BR \-n
- option was omitted because similar functionality can be obtained from
- the
- .BR \-n
- option of the
- .IR pr
- utility.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fImore\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .P
- The System Interfaces volume of POSIX.1\(hy2017,
- .IR "\fIsetvbuf\fR\^(\|)"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .