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 "FOLD" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" fold
|
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
|
|
|
|
fold \- filter for folding lines
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fBfold\fP \fB[\fP\fB-bs\fP\fB][\fP\fB-w\fP \fIwidth\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIfold\fP utility is a filter that shall fold lines from its
|
|
|
|
input files, breaking the lines to have a maximum of
|
|
|
|
\fIwidth\fP column positions (or bytes, if the \fB-b\fP option is
|
|
|
|
specified). Lines shall be broken by the insertion of a
|
|
|
|
<newline> such that each output line (referred to later in this section
|
|
|
|
as a \fIsegment\fP) is the maximum width possible
|
|
|
|
that does not exceed the specified number of column positions (or
|
|
|
|
bytes). A line shall not be broken in the middle of a character.
|
|
|
|
The behavior is undefined if \fIwidth\fP is less than the number of
|
|
|
|
columns any single character in the input would occupy.
|
|
|
|
.LP
|
|
|
|
If the <carriage-return>s, <backspace>s, or <tab>s are encountered
|
|
|
|
in the input, and the \fB-b\fP option is
|
|
|
|
not specified, they shall be treated specially:
|
|
|
|
.TP 7
|
|
|
|
<backspace>
|
|
|
|
The current count of line width shall be decremented by one, although
|
|
|
|
the count never shall become negative. The \fIfold\fP
|
|
|
|
utility shall not insert a <newline> immediately before or after any
|
|
|
|
<backspace>.
|
|
|
|
.TP 7
|
|
|
|
<carriage-return>
|
|
|
|
.sp
|
|
|
|
The current count of line width shall be set to zero. The \fIfold\fP
|
|
|
|
utility shall not insert a <newline> immediately before
|
|
|
|
or after any <carriage-return>.
|
|
|
|
.TP 7
|
|
|
|
<tab>
|
|
|
|
Each <tab> encountered shall advance the column position pointer to
|
|
|
|
the next tab stop. Tab stops shall be at each column
|
|
|
|
position \fIn\fP such that \fIn\fP modulo 8 equals 1.
|
|
|
|
.sp
|
|
|
|
.SH OPTIONS
|
|
|
|
.LP
|
|
|
|
The \fIfold\fP utility shall conform to the Base Definitions volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
|
|
.LP
|
|
|
|
The following options shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fB-b\fP
|
|
|
|
Count \fIwidth\fP in bytes rather than column positions.
|
|
|
|
.TP 7
|
|
|
|
\fB-s\fP
|
|
|
|
If a segment of a line contains a <blank> within the first \fIwidth\fP
|
|
|
|
column positions (or bytes), break the line after
|
|
|
|
the last such <blank> meeting the width constraints. If there is no
|
|
|
|
<blank> meeting the requirements, the \fB-s\fP
|
|
|
|
option shall have no effect for that output segment of the input line.
|
|
|
|
.TP 7
|
|
|
|
\fB-w\ \fP \fIwidth\fP
|
|
|
|
Specify the maximum line length, in column positions (or bytes if
|
|
|
|
\fB-b\fP is specified). The results are unspecified if
|
|
|
|
\fIwidth\fP is not a positive decimal number. The default value shall
|
|
|
|
be 80.
|
|
|
|
.sp
|
|
|
|
.SH OPERANDS
|
|
|
|
.LP
|
|
|
|
The following operand shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fIfile\fP
|
|
|
|
A pathname of a text file to be folded. If no \fIfile\fP operands
|
|
|
|
are specified, the standard input shall be used.
|
|
|
|
.sp
|
|
|
|
.SH STDIN
|
|
|
|
.LP
|
|
|
|
The standard input shall be used only if no \fIfile\fP operands are
|
|
|
|
specified. See the INPUT FILES section.
|
|
|
|
.SH INPUT FILES
|
|
|
|
.LP
|
|
|
|
If the \fB-b\fP option is specified, the input files shall be text
|
|
|
|
files except that the lines are not limited to {LINE_MAX}
|
|
|
|
bytes in length. If the \fB-b\fP option is not specified, the input
|
|
|
|
files shall be text files.
|
|
|
|
.SH ENVIRONMENT VARIABLES
|
|
|
|
.LP
|
|
|
|
The following environment variables shall affect the execution of
|
|
|
|
\fIfold\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 and input files), and
|
|
|
|
for the determination of the width in column positions each
|
|
|
|
character would occupy on a constant-width font output device.
|
|
|
|
.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 be a file containing a sequence of characters
|
|
|
|
whose order shall be preserved from the input files,
|
|
|
|
possibly with inserted <newline>s.
|
|
|
|
.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 processed 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 \fIcut\fP and \fIfold\fP utilities can be used to create text
|
|
|
|
files out of files with
|
|
|
|
arbitrary line lengths. The \fIcut\fP utility should be used when
|
|
|
|
the number of lines (or
|
|
|
|
records) needs to remain constant. The \fIfold\fP utility should be
|
|
|
|
used when the contents of long lines need to be kept
|
|
|
|
contiguous.
|
|
|
|
.LP
|
|
|
|
The \fIfold\fP utility is frequently used to send text files to printers
|
|
|
|
that truncate, rather than fold, lines wider than the
|
|
|
|
printer is able to print (usually 80 or 132 column positions).
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
An example invocation that submits a file of possibly long lines to
|
|
|
|
the printer (under the assumption that the user knows the
|
|
|
|
line width of the printer to be assigned by \fIlp\fP):
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBfold -w 132 bigfile | lp
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
Although terminal input in canonical processing mode requires the
|
|
|
|
erase character (frequently set to <backspace>) to erase
|
|
|
|
the previous character (not byte or column position), terminal output
|
|
|
|
is not buffered and is extremely difficult, if not
|
|
|
|
impossible, to parse correctly; the interpretation depends entirely
|
|
|
|
on the physical device that actually displays/prints/stores the
|
|
|
|
output. In all known internationalized implementations, the utilities
|
|
|
|
producing output for mixed column-width output assume that a
|
|
|
|
<backspace> backs up one column position and outputs enough <backspace>s
|
|
|
|
to return to the start of the character when
|
|
|
|
<backspace> is used to provide local line motions to support underlining
|
|
|
|
and emboldening operations. Since \fIfold\fP
|
|
|
|
without the \fB-b\fP option is dealing with these same constraints,
|
|
|
|
<backspace> is always treated as backing up one column
|
|
|
|
position rather than backing up one character.
|
|
|
|
.LP
|
|
|
|
Historical versions of the \fIfold\fP utility assumed 1 byte was one
|
|
|
|
character and occupied one column position when written
|
|
|
|
out. This is no longer always true. Since the most common usage of
|
|
|
|
\fIfold\fP is believed to be folding long lines for output to
|
|
|
|
limited-length output devices, this capability was preserved as the
|
|
|
|
default case. The \fB-b\fP option was added so that
|
|
|
|
applications could \fIfold\fP files with arbitrary length lines into
|
|
|
|
text files that could then be processed by the standard
|
|
|
|
utilities. Note that although the width for the \fB-b\fP option is
|
|
|
|
in bytes, a line is never split in the middle of a character.
|
|
|
|
(It is unspecified what happens if a width is specified that is too
|
|
|
|
small to hold a single character found in the input followed by
|
|
|
|
a <newline>.)
|
|
|
|
.LP
|
|
|
|
The tab stops are hardcoded to be every eighth column to meet historical
|
|
|
|
practice. No new method of specifying other tab stops
|
|
|
|
was invented.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
|
|
|
\fIcut\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 .
|