diff options
Diffstat (limited to 'upstream/archlinux/man1p/fold.1p')
| -rw-r--r-- | upstream/archlinux/man1p/fold.1p | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/upstream/archlinux/man1p/fold.1p b/upstream/archlinux/man1p/fold.1p new file mode 100644 index 00000000..14d39c56 --- /dev/null +++ b/upstream/archlinux/man1p/fold.1p @@ -0,0 +1,282 @@ +'\" 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 . |