foldposix - Online in the Cloud

PROGRAM:

NAME

fold — filter for folding lines

SYNOPSIS

fold [−bs] [−w width] [file...]

DESCRIPTION

The fold utility is a filter that shall fold lines from its input files, breaking the
lines to have a maximum of width column positions (or bytes, if the −b 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 segment) 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 width is less than the
number of columns any single character in the input would occupy.

If the <carriage-return>, <backspace>, or <tab> characters are encountered in the input,
and the −b option is not specified, they shall be treated specially:

<backspace>
The current count of line width shall be decremented by one, although the count
never shall become negative. The fold utility shall not insert a <newline>
immediately before or after any <backspace>, unless the following character has
a width greater than 1 and would cause the line width to exceed width.

<carriage-return>
The current count of line width shall be set to zero. The fold utility shall not
insert a <newline> immediately before or after any <carriage-return>.

<tab> Each <tab> encountered shall advance the column position pointer to the next tab
stop. Tab stops shall be at each column position n such that n modulo 8 equals
1.

OPTIONS

The fold utility shall conform to the Base Definitions volume of POSIX.1‐2008, Section
12.2, Utility Syntax Guidelines.

The following options shall be supported:

−b Count width in bytes rather than column positions.

−s If a segment of a line contains a <blank> within the first width 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 −s
option shall have no effect for that output segment of the input line.

−w width Specify the maximum line length, in column positions (or bytes if −b is
specified). The results are unspecified if width is not a positive decimal
number. The default value shall be 80.

OPERANDS

The following operand shall be supported:

file A pathname of a text file to be folded. If no file operands are specified, the
standard input shall be used.

STDIN

The standard input shall be used if no file operands are specified, and shall be used if a
file operand is '−' and the implementation treats the '−' as meaning standard input.
Otherwise, the standard input shall not be used. See the INPUT FILES section.

INPUT FILES

If the −b 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 −b option is not specified, the
input files shall be text files.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of fold:

LANG Provide a default value for the internationalization variables that are unset or
null. (See the Base Definitions volume of POSIX.1‐2008, Section 8.2,
Internationalization Variables for the precedence of internationalization
variables used to determine the values of locale categories.)

LC_ALL If set to a non-empty string value, override the values of all the other
internationalization variables.

LC_CTYPE 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.

LC_MESSAGES
Determine the locale that should be used to affect the format and contents of
diagnostic messages written to standard error.

NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES.

ASYNCHRONOUS EVENTS

Default.

STDOUT

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> characters.

STDERR

The standard error shall be used only for diagnostic messages.

OUTPUT FILES

None.

EXTENDED DESCRIPTION

None.

EXIT STATUS

The following exit values shall be returned:

0 All input files were processed successfully.

>0 An error occurred.

CONSEQUENCES OF ERRORS

Default.

The following sections are informative.

APPLICATION USAGE

The cut and fold utilities can be used to create text files out of files with arbitrary
line lengths. The cut utility should be used when the number of lines (or records) needs
to remain constant. The fold utility should be used when the contents of long lines need
to be kept contiguous.

The fold 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).

EXAMPLES

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 lp):

fold −w 132 bigfile | lp

RATIONALE

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> character backs up one column position and outputs enough <backspace>
characters to return to the start of the character when <backspace> is used to provide
local line motions to support underlining and emboldening operations. Since fold without
the −b option is dealing with these same constraints, <backspace> is always treated as
backing up one column position rather than backing up one character.

Historical versions of the fold 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 fold is believed to be folding long lines for output to limited-length output
devices, this capability was preserved as the default case. The −b option was added so
that applications could fold files with arbitrary length lines into text files that could
then be processed by the standard utilities. Note that although the width for the −b
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>.)

The tab stops are hardcoded to be every eighth column to meet historical practice. No new
method of specifying other tab stops was invented.

FUTURE DIRECTIONS

None.

Use foldposix online using onworks.net services