|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH FOLD "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
fold
|
|
Packit |
7cfc04 |
\(em filter for folding lines
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
fold \fB[\fR\(mibs\fB] [\fR\(miw \fIwidth\fB] [\fIfile\fR...\fB]\fR
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
utility is a filter that shall fold lines from its input files,
|
|
Packit |
7cfc04 |
breaking the lines to have a maximum of
|
|
Packit |
7cfc04 |
.IR width
|
|
Packit |
7cfc04 |
column positions (or bytes, if the
|
|
Packit |
7cfc04 |
.BR \(mib
|
|
Packit |
7cfc04 |
option is specified). Lines shall be broken by the insertion of a
|
|
Packit |
7cfc04 |
<newline>
|
|
Packit |
7cfc04 |
such that each output line (referred to later in this section
|
|
Packit |
7cfc04 |
as a \fIsegment\fP) is the maximum width possible that does not exceed
|
|
Packit |
7cfc04 |
the specified number of column positions (or bytes). A line shall not
|
|
Packit |
7cfc04 |
be broken in the middle of a character. The behavior is undefined if
|
|
Packit |
7cfc04 |
.IR width
|
|
Packit |
7cfc04 |
is less than the number of columns any single character in the input
|
|
Packit |
7cfc04 |
would occupy.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the
|
|
Packit |
7cfc04 |
<carriage-return>,
|
|
Packit |
7cfc04 |
<backspace>,
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
<tab>
|
|
Packit |
7cfc04 |
characters are encountered in the input, and the
|
|
Packit |
7cfc04 |
.BR \(mib
|
|
Packit |
7cfc04 |
option is not specified, they shall be treated specially:
|
|
Packit |
7cfc04 |
.IP <backspace> 10
|
|
Packit |
7cfc04 |
The current count of line width shall be decremented by one, although
|
|
Packit |
7cfc04 |
the count never shall become negative. The
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
utility shall not insert a
|
|
Packit |
7cfc04 |
<newline>
|
|
Packit |
7cfc04 |
immediately before or after any
|
|
Packit |
7cfc04 |
<backspace>,
|
|
Packit |
7cfc04 |
unless the following character has a width greater than 1 and would
|
|
Packit |
7cfc04 |
cause the line width to exceed
|
|
Packit |
7cfc04 |
.IR width .
|
|
Packit |
7cfc04 |
.IP <carriage-return> 10
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
The current count of line width shall be set to zero. The
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
utility shall not insert a
|
|
Packit |
7cfc04 |
<newline>
|
|
Packit |
7cfc04 |
immediately before or after any
|
|
Packit |
7cfc04 |
<carriage-return>.
|
|
Packit |
7cfc04 |
.IP <tab> 10
|
|
Packit |
7cfc04 |
Each
|
|
Packit |
7cfc04 |
<tab>
|
|
Packit |
7cfc04 |
encountered shall advance the column position pointer to the next tab
|
|
Packit |
7cfc04 |
stop. Tab stops shall be at each column position
|
|
Packit |
7cfc04 |
.IR n
|
|
Packit |
7cfc04 |
such that
|
|
Packit |
7cfc04 |
.IR n
|
|
Packit |
7cfc04 |
modulo 8 equals 1.
|
|
Packit |
7cfc04 |
.SH OPTIONS
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
utility shall conform to the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The following options shall be supported:
|
|
Packit |
7cfc04 |
.IP "\fB\(mib\fR" 10
|
|
Packit |
7cfc04 |
Count
|
|
Packit |
7cfc04 |
.IR width
|
|
Packit |
7cfc04 |
in bytes rather than column positions.
|
|
Packit |
7cfc04 |
.IP "\fB\(mis\fR" 10
|
|
Packit |
7cfc04 |
If a segment of a line contains a
|
|
Packit |
7cfc04 |
<blank>
|
|
Packit |
7cfc04 |
within the first
|
|
Packit |
7cfc04 |
.IR width
|
|
Packit |
7cfc04 |
column positions (or bytes), break the line after the last such
|
|
Packit |
7cfc04 |
<blank>
|
|
Packit |
7cfc04 |
meeting the width constraints. If there is no
|
|
Packit |
7cfc04 |
<blank>
|
|
Packit |
7cfc04 |
meeting the requirements, the
|
|
Packit |
7cfc04 |
.BR \(mis
|
|
Packit |
7cfc04 |
option shall have no effect for that output segment of the input line.
|
|
Packit |
7cfc04 |
.IP "\fB\(miw\ \fIwidth\fR" 10
|
|
Packit |
7cfc04 |
Specify the maximum line length, in column positions (or bytes if
|
|
Packit |
7cfc04 |
.BR \(mib
|
|
Packit |
7cfc04 |
is specified). The results are unspecified if
|
|
Packit |
7cfc04 |
.IR width
|
|
Packit |
7cfc04 |
is not a positive decimal number. The default value shall be 80.
|
|
Packit |
7cfc04 |
.SH OPERANDS
|
|
Packit |
7cfc04 |
The following operand shall be supported:
|
|
Packit |
7cfc04 |
.IP "\fIfile\fR" 10
|
|
Packit |
7cfc04 |
A pathname of a text file to be folded. If no
|
|
Packit |
7cfc04 |
.IR file
|
|
Packit |
7cfc04 |
operands are specified, the standard input shall be used.
|
|
Packit |
7cfc04 |
.SH STDIN
|
|
Packit |
7cfc04 |
The standard input shall be used if no
|
|
Packit |
7cfc04 |
.IR file
|
|
Packit |
7cfc04 |
operands are specified, and shall be used if a
|
|
Packit |
7cfc04 |
.IR file
|
|
Packit |
7cfc04 |
operand is
|
|
Packit |
7cfc04 |
.BR '\(mi'
|
|
Packit |
7cfc04 |
and the implementation treats the
|
|
Packit |
7cfc04 |
.BR '\(mi'
|
|
Packit |
7cfc04 |
as meaning standard input.
|
|
Packit |
7cfc04 |
Otherwise, the standard input shall not be used.
|
|
Packit |
7cfc04 |
See the INPUT FILES section.
|
|
Packit |
7cfc04 |
.SH "INPUT FILES"
|
|
Packit |
7cfc04 |
If the
|
|
Packit |
7cfc04 |
.BR \(mib
|
|
Packit |
7cfc04 |
option is specified, the input files shall be text files except that the
|
|
Packit |
7cfc04 |
lines are not limited to
|
|
Packit |
7cfc04 |
{LINE_MAX}
|
|
Packit |
7cfc04 |
bytes in length. If the
|
|
Packit |
7cfc04 |
.BR \(mib
|
|
Packit |
7cfc04 |
option is not specified, the input files shall be text files.
|
|
Packit |
7cfc04 |
.SH "ENVIRONMENT VARIABLES"
|
|
Packit |
7cfc04 |
The following environment variables shall affect the execution of
|
|
Packit |
7cfc04 |
.IR fold :
|
|
Packit |
7cfc04 |
.IP "\fILANG\fP" 10
|
|
Packit |
7cfc04 |
Provide a default value for the internationalization variables that are
|
|
Packit |
7cfc04 |
unset or null. (See the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 8.2" ", " "Internationalization Variables"
|
|
Packit |
7cfc04 |
for the precedence of internationalization variables used to determine
|
|
Packit |
7cfc04 |
the values of locale categories.)
|
|
Packit |
7cfc04 |
.IP "\fILC_ALL\fP" 10
|
|
Packit |
7cfc04 |
If set to a non-empty string value, override the values of all the
|
|
Packit |
7cfc04 |
other internationalization variables.
|
|
Packit |
7cfc04 |
.IP "\fILC_CTYPE\fP" 10
|
|
Packit |
7cfc04 |
Determine the locale for the interpretation of sequences of bytes of
|
|
Packit |
7cfc04 |
text data as characters (for example, single-byte as opposed to
|
|
Packit |
7cfc04 |
multi-byte characters in arguments and input files), and for the
|
|
Packit |
7cfc04 |
determination of the width in column positions each character would
|
|
Packit |
7cfc04 |
occupy on a constant-width font output device.
|
|
Packit |
7cfc04 |
.IP "\fILC_MESSAGES\fP" 10
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
Determine the locale that should be used to affect the format and
|
|
Packit |
7cfc04 |
contents of diagnostic messages written to standard error.
|
|
Packit |
7cfc04 |
.IP "\fINLSPATH\fP" 10
|
|
Packit |
7cfc04 |
Determine the location of message catalogs for the processing of
|
|
Packit |
7cfc04 |
.IR LC_MESSAGES .
|
|
Packit |
7cfc04 |
.SH "ASYNCHRONOUS EVENTS"
|
|
Packit |
7cfc04 |
Default.
|
|
Packit |
7cfc04 |
.SH STDOUT
|
|
Packit |
7cfc04 |
The standard output shall be a file containing a sequence of characters
|
|
Packit |
7cfc04 |
whose order shall be preserved from the input files, possibly with
|
|
Packit |
7cfc04 |
inserted
|
|
Packit |
7cfc04 |
<newline>
|
|
Packit |
7cfc04 |
characters.
|
|
Packit |
7cfc04 |
.SH STDERR
|
|
Packit |
7cfc04 |
The standard error shall be used only for diagnostic messages.
|
|
Packit |
7cfc04 |
.SH "OUTPUT FILES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "EXTENDED DESCRIPTION"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "EXIT STATUS"
|
|
Packit |
7cfc04 |
The following exit values shall be returned:
|
|
Packit |
7cfc04 |
.IP "\00" 6
|
|
Packit |
7cfc04 |
All input files were processed successfully.
|
|
Packit |
7cfc04 |
.IP >0 6
|
|
Packit |
7cfc04 |
An error occurred.
|
|
Packit |
7cfc04 |
.SH "CONSEQUENCES OF ERRORS"
|
|
Packit |
7cfc04 |
Default.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR cut
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
utilities can be used to create text files out of files with arbitrary
|
|
Packit |
7cfc04 |
line lengths. The
|
|
Packit |
7cfc04 |
.IR cut
|
|
Packit |
7cfc04 |
utility should be used when the number of lines (or records) needs to
|
|
Packit |
7cfc04 |
remain constant. The
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
utility should be used when the contents of long lines need to be kept
|
|
Packit |
7cfc04 |
contiguous.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
utility is frequently used to send text files to printers that
|
|
Packit |
7cfc04 |
truncate, rather than fold, lines wider than the printer is able to
|
|
Packit |
7cfc04 |
print (usually 80 or 132 column positions).
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
An example invocation that submits a file of possibly long lines to the
|
|
Packit |
7cfc04 |
printer (under the assumption that the user knows the line width of the
|
|
Packit |
7cfc04 |
printer to be assigned by
|
|
Packit |
7cfc04 |
.IR lp ):
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
fold \(miw 132 bigfile | lp
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
Although terminal input in canonical processing mode requires the erase
|
|
Packit |
7cfc04 |
character (frequently set to
|
|
Packit |
7cfc04 |
<backspace>)
|
|
Packit |
7cfc04 |
to erase the previous character (not byte or column position), terminal
|
|
Packit |
7cfc04 |
output is not buffered and is extremely difficult, if not impossible,
|
|
Packit |
7cfc04 |
to parse correctly; the interpretation depends entirely on the physical
|
|
Packit |
7cfc04 |
device that actually displays/prints/stores the output. In all known
|
|
Packit |
7cfc04 |
internationalized implementations, the utilities producing output for
|
|
Packit |
7cfc04 |
mixed column-width output assume that a
|
|
Packit |
7cfc04 |
<backspace>
|
|
Packit |
7cfc04 |
character backs up one column position and outputs enough
|
|
Packit |
7cfc04 |
<backspace>
|
|
Packit |
7cfc04 |
characters to return to the start of the character when
|
|
Packit |
7cfc04 |
<backspace>
|
|
Packit |
7cfc04 |
is used to provide local line motions to support underlining and
|
|
Packit |
7cfc04 |
emboldening operations. Since
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
without the
|
|
Packit |
7cfc04 |
.BR \(mib
|
|
Packit |
7cfc04 |
option is dealing with these same constraints,
|
|
Packit |
7cfc04 |
<backspace>
|
|
Packit |
7cfc04 |
is always treated as backing up one column position rather than backing
|
|
Packit |
7cfc04 |
up one character.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Historical versions of the
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
utility assumed 1 byte was one character and occupied one column
|
|
Packit |
7cfc04 |
position when written out. This is no longer always true. Since the
|
|
Packit |
7cfc04 |
most common usage of
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
is believed to be folding long lines for output to limited-length
|
|
Packit |
7cfc04 |
output devices, this capability was preserved as the default case. The
|
|
Packit |
7cfc04 |
.BR \(mib
|
|
Packit |
7cfc04 |
option was added so that applications could
|
|
Packit |
7cfc04 |
.IR fold
|
|
Packit |
7cfc04 |
files with arbitrary length lines into text files that could then be
|
|
Packit |
7cfc04 |
processed by the standard utilities. Note that although the width for
|
|
Packit |
7cfc04 |
the
|
|
Packit |
7cfc04 |
.BR \(mib
|
|
Packit |
7cfc04 |
option is in bytes, a line is never split in the middle of a character.
|
|
Packit |
7cfc04 |
(It is unspecified what happens if a width is specified that is too
|
|
Packit |
7cfc04 |
small to hold a single character found in the input followed by a
|
|
Packit |
7cfc04 |
<newline>.)
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The tab stops are hardcoded to be every eighth column to meet
|
|
Packit |
7cfc04 |
historical practice. No new method of specifying other tab stops was
|
|
Packit |
7cfc04 |
invented.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "\fIcut\fR\^"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Chapter 8" ", " "Environment Variables",
|
|
Packit |
7cfc04 |
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|