share/man/man1/fold.1

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH FOLD 1 "Feb 1, 1995"
  48 .SH NAME
  49 fold \- filter for folding lines
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 \fBfold\fR [\fB-bs\fR] [\fB-w\fR \fIwidth\fR | \fB-width\fR] [\fIfile\fR]...
  54 .fi
  55
  56 .SH DESCRIPTION
  57 .sp
  58 .LP
  59 The \fBfold\fR utility is a filter that will fold lines from its input files,
  60 breaking the lines to have a maximum of \fIwidth\fR column positions (or bytes,
  61 if the \fB-b\fR option is specified). Lines will be broken by the insertion of
  62 a NEWLINE character such that each output line (referred to later in this
  63 section as a segment) is the maximum width possible that does not exceed the
  64 specified number of column positions (or bytes). A line will not be broken in
  65 the middle of a character. The behavior is undefined if \fIwidth\fR is less
  66 than the number of columns any single character in the input would occupy.
  67 .sp
  68 .LP
  69 If the CARRIAGE-RETURN, BACKSPACE, or TAB characters are encountered in the
  70 input, and the \fB-b\fR option is not specified, they will be treated
  71 specially:
  72 .sp
  73 .ne 2
  74 .na
  75 \fBBACKSPACE \fR
  76 .ad
  77 .RS 20n
  78 The current count of line width will be decremented by one, although the count
  79 never will become negative. \fBfold\fR will not insert a NEWLINE character
  80 immediately before or after any BACKSPACE character.
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fBCARRIAGE-RETURN \fR
  87 .ad
  88 .RS 20n
  89 The current count of line width will be set to \fB0\fR. \fBfold\fR will not
  90 insert a NEWLINE character immediately before or after any CARRIAGE-RETURN
  91 character.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fBTAB \fR
  98 .ad
  99 .RS 20n
 100 Each TAB character encountered will advance the column position pointer to the
 101 next tab stop. Tab stops will be at each column position \fIn\fR such that
 102 \fIn\fR modulo 8 equals 1.
 103 .RE
 104
 105 .SH OPTIONS
 106 .sp
 107 .LP
 108 The following options are supported:
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fB-b\fR \fR
 113 .ad
 114 .RS 20n
 115 Counts \fIwidth\fR in bytes rather than column positions.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fB-s\fR \fR
 122 .ad
 123 .RS 20n
 124 If a segment of a line contains a blank character within the first \fIwidth\fR
 125 column positions (or bytes), breaks the line after the last such blank
 126 character meeting the width constraints. If there is no blank character meeting
 127 the requirements, the \fB-s\fR option will have no effect for that output
 128 segment of the input line.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fB-w\fR \fIwidth\fR\fB|\fR\fB-\fR\fIwidth\fR \fR
 135 .ad
 136 .RS 20n
 137 Specifies the maximum line length, in column positions (or bytes if \fB-b\fR is
 138 specified). If \fIwidth\fR is not a positive decimal number, an error is
 139 returned. The default value is 80.
 140 .RE
 141
 142 .SH OPERANDS
 143 .sp
 144 .LP
 145 The following operand is supported:
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fB\fIfile\fR\fR \fR
 150 .ad
 151 .RS 9n
 152 A path name of a text file to be folded. If no \fIfile\fR operands are
 153 specified, the standard input will be used.
 154 .RE
 155
 156 .SH EXAMPLES
 157 .LP
 158 \fBExample 1 \fRSubmitting a file of possibly long lines to the line printer
 159 .sp
 160 .LP
 161 An example invocation that submits a file of possibly long lines to the line
 162 printer (under the assumption that the user knows the line width of the printer
 163 to be assigned by \fBlp\fR(1)):
 164
 165 .sp
 166 .in +2
 167 .nf
 168 example% \fBfold -w 132 bigfile | lp\fR
 169 .fi
 170 .in -2
 171 .sp
 172
 173 .SH ENVIRONMENT VARIABLES
 174 .sp
 175 .LP
 176 See \fBenviron\fR(5) for descriptions of the following environment variables
 177 that affect the execution of \fBfold\fR: \fBLANG\fR, \fBLC_ALL\fR,
 178 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 179 .SH EXIT STATUS
 180 .sp
 181 .LP
 182 The following exit values are returned:
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fB0\fR \fR
 187 .ad
 188 .RS 7n
 189 All input files were processed successfully.
 190 .RE
 191
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fB>0\fR \fR
 196 .ad
 197 .RS 7n
 198 An error occurred.
 199 .RE
 200
 201 .SH ATTRIBUTES
 202 .sp
 203 .LP
 204 See \fBattributes\fR(5) for descriptions of the following attributes:
 205 .sp
 206
 207 .sp
 208 .TS
 209 box;
 210 c | c
 211 l | l .
 212 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 213 _
 214 CSI     enabled
 215 _
 216 Interface Stability     Standard
 217 .TE
 218
 219 .SH SEE ALSO
 220 .sp
 221 .LP
 222 \fBcut\fR(1), \fBpr\fR(1), \fBattributes\fR(5), \fBenviron\fR(5),
 223 \fBstandards\fR(5)
 224 .SH NOTES
 225 .sp
 226 .LP
 227 \fBfold\fR and \fBcut\fR(1) can be used to create text files out of files with
 228 arbitrary line lengths. \fBfold\fR should be used when the contents of long
 229 lines need to be kept contiguous. \fBcut\fR should be used when the number of
 230 lines (or records) needs to remain constant.
 231 .sp
 232 .LP
 233 \fBfold\fR is frequently used to send text files to line printers that
 234 truncate, rather than fold, lines wider than the printer is able to print
 235 (usually 80 or 132 column positions).
 236 .sp
 237 .LP
 238 \fBfold\fR may not work correctly if underlining is present.