fold.1p (8936B)
- '\" et
- .TH FOLD "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
- fold
- \(em filter for folding lines
- .SH SYNOPSIS
- .LP
- .nf
- fold \fB[\fR-bs\fB] [\fR-w \fIwidth\fB] [\fIfile\fR...\fB]\fR
- .fi
- .SH DESCRIPTION
- The
- .IR fold
- utility is a filter that shall fold lines from its input files,
- breaking the lines to have a maximum of
- .IR width
- column positions (or bytes, if the
- .BR \-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 \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
- .IR width
- is less than the number of columns any single character in the input
- would occupy.
- .P
- If the
- <carriage-return>,
- <backspace>,
- or
- <tab>
- characters are encountered in the input, and the
- .BR \-b
- option is not specified, they shall be treated specially:
- .IP <backspace> 10
- The current count of line width shall be decremented by one, although
- the count never shall become negative. The
- .IR 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
- .IR width .
- .IP <carriage-return> 10
- .br
- The current count of line width shall be set to zero. The
- .IR fold
- utility shall not insert a
- <newline>
- immediately before or after any
- <carriage-return>.
- .IP <tab> 10
- Each
- <tab>
- encountered shall advance the column position pointer to the next tab
- stop. Tab stops shall be at each column position
- .IR n
- such that
- .IR n
- modulo 8 equals 1.
- .SH OPTIONS
- The
- .IR fold
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following options shall be supported:
- .IP "\fB\-b\fR" 10
- Count
- .IR width
- in bytes rather than column positions.
- .IP "\fB\-s\fR" 10
- If a segment of a line contains a
- <blank>
- within the first
- .IR 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
- .BR \-s
- option shall have no effect for that output segment of the input line.
- .IP "\fB\-w\ \fIwidth\fR" 10
- Specify the maximum line length, in column positions (or bytes if
- .BR \-b
- is specified). The results are unspecified if
- .IR width
- is not a positive decimal number. The default value shall be 80.
- .SH OPERANDS
- The following operand shall be supported:
- .IP "\fIfile\fR" 10
- A pathname of a text file to be folded. If no
- .IR file
- operands are specified, the standard input shall be used.
- .SH STDIN
- The standard input shall be used if no
- .IR file
- operands are specified, and shall be used if a
- .IR file
- operand is
- .BR '\-'
- and the implementation treats the
- .BR '\-'
- as meaning standard input.
- Otherwise, the standard input shall not be used.
- See the INPUT FILES section.
- .SH "INPUT FILES"
- If the
- .BR \-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
- .BR \-b
- option is not specified, the input files shall be text files.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR fold :
- .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 and input files), and for the
- determination of the width in column positions each character would
- occupy on a constant-width font output device.
- .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 be a file containing a sequence of characters
- whose order shall be preserved from the input files, possibly with
- inserted
- <newline>
- characters.
- .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 processed successfully.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- The
- .IR cut
- and
- .IR fold
- utilities can be used to create text files out of files with arbitrary
- line lengths. The
- .IR cut
- utility should be used when the number of lines (or records) needs to
- remain constant. The
- .IR fold
- utility should be used when the contents of long lines need to be kept
- contiguous.
- .P
- The
- .IR 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).
- .SH 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
- .IR lp ):
- .sp
- .RS 4
- .nf
- fold -w 132 bigfile | lp
- .fi
- .P
- .RE
- .SH 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
- .IR fold
- without the
- .BR \-b
- option is dealing with these same constraints,
- <backspace>
- is always treated as backing up one column position rather than backing
- up one character.
- .P
- Historical versions of the
- .IR 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
- .IR fold
- is believed to be folding long lines for output to limited-length
- output devices, this capability was preserved as the default case. The
- .BR \-b
- option was added so that applications could
- .IR 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
- .BR \-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>.)
- .P
- 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"
- None.
- .SH "SEE ALSO"
- .IR "\fIcut\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .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 .