1FOLD(1P)                   POSIX Programmer's Manual                  FOLD(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       fold — filter for folding lines
14

SYNOPSIS

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

DESCRIPTION

19       The fold utility is a filter that  shall  fold  lines  from  its  input
20       files,  breaking  the lines to have a maximum of width column positions
21       (or bytes, if the −b option is specified). Lines shall be broken by the
22       insertion  of a <newline> such that each output line (referred to later
23       in this section as a segment) is the maximum width possible  that  does
24       not  exceed the specified number of column positions (or bytes). A line
25       shall not be broken in the middle of a character. The behavior is unde‐
26       fined  if width is less than the number of columns any single character
27       in the input would occupy.
28
29       If the <carriage-return>, <backspace>, or <tab> characters are  encoun‐
30       tered  in  the input, and the −b option is not specified, they shall be
31       treated specially:
32
33       <backspace>
34                 The current count of line width shall be decremented by  one,
35                 although  the  count  never  shall  become negative. The fold
36                 utility shall not insert a <newline>  immediately  before  or
37                 after  any  <backspace>, unless the following character has a
38                 width greater than 1 and would cause the line width to exceed
39                 width.
40
41       <carriage-return>
42                 The  current  count  of  line width shall be set to zero. The
43                 fold utility shall not insert a <newline> immediately  before
44                 or after any <carriage-return>.
45
46       <tab>     Each  <tab>  encountered  shall  advance  the column position
47                 pointer to the next tab stop. Tab stops shall be at each col‐
48                 umn position n such that n modulo 8 equals 1.
49

OPTIONS

51       The  fold  utility  shall  conform  to  the  Base Definitions volume of
52       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
53
54       The following options shall be supported:
55
56       −b        Count width in bytes rather than column positions.
57
58       −s        If a segment of a line contains a <blank>  within  the  first
59                 width  column  positions (or bytes), break the line after the
60                 last such <blank> meeting the width constraints. If there  is
61                 no <blank> meeting the requirements, the −s option shall have
62                 no effect for that output segment of the input line.
63
64       −w width  Specify the maximum line  length,  in  column  positions  (or
65                 bytes  if  −b  is  specified). The results are unspecified if
66                 width is not a positive decimal  number.  The  default  value
67                 shall be 80.
68

OPERANDS

70       The following operand shall be supported:
71
72       file      A  pathname  of a text file to be folded. If no file operands
73                 are specified, the standard input shall be used.
74

STDIN

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

INPUT FILES

82       If  the  −b  option  is  specified, the input files shall be text files
83       except that the lines are not limited to {LINE_MAX} bytes in length. If
84       the −b option is not specified, the input files shall be text files.
85

ENVIRONMENT VARIABLES

87       The following environment variables shall affect the execution of fold:
88
89       LANG      Provide  a  default  value for the internationalization vari‐
90                 ables that are unset or null. (See the Base Definitions  vol‐
91                 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
92                 ables for the precedence  of  internationalization  variables
93                 used to determine the values of locale categories.)
94
95       LC_ALL    If  set  to  a non-empty string value, override the values of
96                 all the other internationalization variables.
97
98       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
99                 bytes of text data as characters (for example, single-byte as
100                 opposed to  multi-byte  characters  in  arguments  and  input
101                 files),  and  for  the  determination  of the width in column
102                 positions each character would  occupy  on  a  constant-width
103                 font output device.
104
105       LC_MESSAGES
106                 Determine the locale that should be used to affect the format
107                 and contents  of  diagnostic  messages  written  to  standard
108                 error.
109
110       NLSPATH   Determine the location of message catalogs for the processing
111                 of LC_MESSAGES.
112

ASYNCHRONOUS EVENTS

114       Default.
115

STDOUT

117       The standard output shall be a file containing a sequence of characters
118       whose  order  shall  be  preserved  from the input files, possibly with
119       inserted <newline> characters.
120

STDERR

122       The standard error shall be used only for diagnostic messages.
123

OUTPUT FILES

125       None.
126

EXTENDED DESCRIPTION

128       None.
129

EXIT STATUS

131       The following exit values shall be returned:
132
133        0    All input files were processed successfully.
134
135       >0    An error occurred.
136

CONSEQUENCES OF ERRORS

138       Default.
139
140       The following sections are informative.
141

APPLICATION USAGE

143       The cut and fold utilities can be used to  create  text  files  out  of
144       files  with arbitrary line lengths. The cut utility should be used when
145       the number of lines (or records) needs to  remain  constant.  The  fold
146       utility  should be used when the contents of long lines need to be kept
147       contiguous.
148
149       The fold utility is frequently used to send text files to printers that
150       truncate,  rather  than  fold,  lines wider than the printer is able to
151       print (usually 80 or 132 column positions).
152

EXAMPLES

154       An example invocation that submits a file of possibly long lines to the
155       printer (under the assumption that the user knows the line width of the
156       printer to be assigned by lp):
157
158           fold −w 132 bigfile | lp
159

RATIONALE

161       Although terminal input in canonical processing mode requires the erase
162       character (frequently set to <backspace>) to erase the previous charac‐
163       ter (not byte or column position), terminal output is not buffered  and
164       is  extremely  difficult,  if  not  impossible, to parse correctly; the
165       interpretation depends entirely on the physical  device  that  actually
166       displays/prints/stores  the  output.  In  all  known  internationalized
167       implementations, the utilities producing output for mixed  column-width
168       output assume that a <backspace> character backs up one column position
169       and outputs enough <backspace> characters to return to the start of the
170       character  when  <backspace>  is  used to provide local line motions to
171       support underlining and emboldening operations. Since fold without  the
172       −b option is dealing with these same constraints, <backspace> is always
173       treated as backing up one column position rather than  backing  up  one
174       character.
175
176       Historical  versions of the fold utility assumed 1 byte was one charac‐
177       ter and occupied one column position  when  written  out.  This  is  no
178       longer  always true. Since the most common usage of fold is believed to
179       be folding long lines for output to limited-length output devices, this
180       capability  was  preserved as the default case. The −b option was added
181       so that applications could fold files with arbitrary length lines  into
182       text files that could then be processed by the standard utilities. Note
183       that although the width for the −b option is in bytes, a line is  never
184       split in the middle of a character.  (It is unspecified what happens if
185       a width is specified that is too small to hold a single character found
186       in the input followed by a <newline>.)
187
188       The  tab stops are hardcoded to be every eighth column to meet histori‐
189       cal practice. No new method of specifying other tab stops was invented.
190

FUTURE DIRECTIONS

192       None.
193

SEE ALSO

195       cut
196
197       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
198       Variables, Section 12.2, Utility Syntax Guidelines
199
201       Portions  of  this text are reprinted and reproduced in electronic form
202       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
203       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
204       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
205       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
206       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
207       event of any discrepancy between this version and the original IEEE and
208       The Open Group Standard, the original IEEE and The Open Group  Standard
209       is  the  referee document. The original Standard can be obtained online
210       at http://www.unix.org/online.html .
211
212       Any typographical or formatting errors that appear  in  this  page  are
213       most likely to have been introduced during the conversion of the source
214       files to man page format. To report such errors,  see  https://www.ker
215       nel.org/doc/man-pages/reporting_bugs.html .
216
217
218
219IEEE/The Open Group                  2013                             FOLD(1P)
Impressum