usr/src/man/man1/csplit.1

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   4 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH CSPLIT 1 "Dec 4, 2003"
  13 .SH NAME
  14 csplit \- split  files based on context
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 \fBcsplit\fR [\fB-ks\fR] [\fB-f\fR \fIprefix\fR] [\fB-n\fR \fInumber\fR] \fIfile\fR \fIarg1\fR... \fIargn\fR
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fBcsplit\fR utility reads the file named by the \fIfile\fR operand, writes
  25 all or part of that file into other files as directed by the \fIarg\fR
  26 operands, and writes the sizes of the files.
  27 .SH OPTIONS
  28 .sp
  29 .LP
  30 The following options are supported:
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fB-f\fR\fI prefix\fR\fR
  35 .ad
  36 .RS 13n
  37 Names the created files \fIprefix\fR\fB00\fR, \fIprefix\fR\fB01\fR, ...,
  38 \fIprefix\fR\fIn\fR. The default is \fBxx00\fR ... \fBxx\fR\fIn\fR. If the
  39 \fIprefix\fR argument would create a file name exceeding \fB14\fR bytes, an
  40 error results. In that case, \fBcsplit\fR exits with a diagnostic message and
  41 no files are created.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fB-k\fR\fR
  48 .ad
  49 .RS 13n
  50 Leaves previously created files intact. By default, \fBcsplit\fR removes
  51 created files if an error occurs.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fB-n\fR\fI number\fR\fR
  58 .ad
  59 .RS 13n
  60 Uses \fInumber\fR decimal digits to form filenames for the file pieces. The
  61 default is \fB2\fR.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fB-s\fR\fR
  68 .ad
  69 .RS 13n
  70 Suppresses the output of file size messages.
  71 .RE
  72
  73 .SH OPERANDS
  74 .sp
  75 .LP
  76 The following operands are supported:
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fIfile\fR\fR
  81 .ad
  82 .RS 8n
  83 The path name of a text file to be split. If \fIfile\fR is \fB-\fR, the
  84 standard input will be used.
  85 .RE
  86
  87 .sp
  88 .LP
  89 The operands \fIarg1\fR ... \fIargn\fR can be a combination of the following:
  90 .sp
  91 .ne 2
  92 .na
  93 \fB/\fIrexp\fR/[\fIoffset\fR]\fR
  94 .ad
  95 .RS 18n
  96 Create a file using the content of the lines from the current line up to, but
  97 not including, the line that results from the evaluation of the regular
  98 expression with \fIoffset\fR, if any, applied. The regular expression
  99 \fIrexp\fR must follow the rules for basic regular expressions. Regular
 100 expressions can include the use of '\fB\e/\fR\&' and '\fB\e%\fR\&'. These forms
 101 must be properly quoted with single quotes, since "\fB\e\fR" is special to the
 102 shell. The optional \fIoffset\fR must be a positive or negative integer value
 103 representing a number of lines. The integer value must be preceded by \fB+\fR
 104 or \fB\(mi\fR\&. If the selection of lines from an offset expression of this
 105 type would create a file with zero lines, or one with greater than the number
 106 of lines left in the input file, the results are unspecified. After the section
 107 is created, the current line will be set to the line that results from the
 108 evaluation of the regular expression with any offset applied. The pattern match
 109 of \fIrexp\fR always is applied from the current line to the end of the file.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB%\fIrexp\fR%[\fIoffset\fR]\fR
 116 .ad
 117 .RS 18n
 118 This operand is the same as /\fIrexp\fR/[\fIoffset\fR], except that no file
 119 will be created for the selected section of the input file.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fIline_no\fR\fR
 126 .ad
 127 .RS 18n
 128 Create a file from the current line up to (but not including) the line number
 129 \fIline_no\fR. Lines in the file will be numbered starting at one. The current
 130 line becomes \fIline_no\fR.
 131 .RE
 132
 133 .sp
 134 .ne 2
 135 .na
 136 \fB{\fInum\fR}\fR
 137 .ad
 138 .RS 18n
 139 Repeat operand. This operand can follow any of the operands described
 140 previously. If it follows a \fIrexp\fR type operand, that operand will be
 141 applied \fInum\fR more times. If it follows a \fIline_no\fR operand, the file
 142 will be split every \fIline_no\fR lines, \fInum\fR times, from that point.
 143 .RE
 144
 145 .sp
 146 .LP
 147 An error will be reported if an operand does not reference a line between the
 148 current position and the end of the file.
 149 .SH USAGE
 150 .sp
 151 .LP
 152 See \fBlargefile\fR(5) for the description of the behavior of \fBcsplit\fR when
 153 encountering files greater than or equal to 2 Gbyte (2^31 bytes).
 154 .SH EXAMPLES
 155 .LP
 156 \fBExample 1 \fRSplitting and combining files
 157 .sp
 158 .LP
 159 This example creates four files, \fBcobol00\fR...\fBcobol03\fR.
 160
 161 .sp
 162 .in +2
 163 .nf
 164 example% \fBcsplit -f cobol filename \e
 165    '/procedure division/' /par5./ /par16./\fR
 166 .fi
 167 .in -2
 168 .sp
 169
 170 .sp
 171 .LP
 172 After editing the \fBsplit\fR files, they can be recombined as follows:
 173
 174 .sp
 175 .in +2
 176 .nf
 177 example% \fBcat cobol0[0\(mi3] > \fIfilename\fR\fR
 178 .fi
 179 .in -2
 180 .sp
 181
 182 .sp
 183 .LP
 184 This example overwrites the original file.
 185
 186 .LP
 187 \fBExample 2 \fRSplitting a file into equal parts
 188 .sp
 189 .LP
 190 This example splits the file at every 100 lines, up to 10,000 lines. The
 191 \fB-k\fR option causes the created files to be retained if there are less than
 192 10,000 lines; however, an error message would still be printed.
 193
 194 .sp
 195 .in +2
 196 .nf
 197 example% \fBcsplit -k filename 100 {99}\fR
 198 .fi
 199 .in -2
 200 .sp
 201
 202 .LP
 203 \fBExample 3 \fRCreating a file for separate C routines
 204 .sp
 205 .LP
 206 If \fBprog.c\fR follows the normal C coding convention (the last line of a
 207 routine consists only of a \fB}\fR in the first character position), this
 208 example creates a file for each separate C routine (up to 21) in \fBprog.c\fR.
 209
 210 .sp
 211 .in +2
 212 .nf
 213 example% \fBcsplit -k prog.c '%main(%' '/^}/+1' {20}\fR
 214 .fi
 215 .in -2
 216 .sp
 217
 218 .SH ENVIRONMENT VARIABLES
 219 .sp
 220 .LP
 221 See \fBenviron\fR(5) for descriptions of the following environment variables
 222 that affect the execution of \fBcsplit\fR: \fBLANG\fR, \fBLC_ALL\fR,
 223 \fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 224 .SH EXIT STATUS
 225 .sp
 226 .LP
 227 The following exit values are returned:
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fB0\fR\fR
 232 .ad
 233 .RS 6n
 234 Successful completion.
 235 .RE
 236
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fB>0\fR\fR
 241 .ad
 242 .RS 6n
 243 An error occurred.
 244 .RE
 245
 246 .SH ATTRIBUTES
 247 .sp
 248 .LP
 249 See \fBattributes\fR(5) for descriptions of the following attributes:
 250 .sp
 251
 252 .sp
 253 .TS
 254 box;
 255 c | c
 256 l | l .
 257 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 258 _
 259 CSI     Enabled
 260 _
 261 Interface Stability     Standard
 262 .TE
 263
 264 .SH SEE ALSO
 265 .sp
 266 .LP
 267 \fBsed\fR(1), \fBsplit\fR(1), \fBattributes\fR(5), \fBenviron\fR(5),
 268 \fBlargefile\fR(5), \fBstandards\fR(5)
 269 .SH DIAGNOSTICS
 270 .sp
 271 .LP
 272 The diagnostic messages are self-explanatory, except for the following:
 273 .sp
 274 .ne 2
 275 .na
 276 \fB\fIarg\fR \(mi out of range\fR
 277 .ad
 278 .RS 25n
 279 The given argument did not reference a line between the current position and
 280 the end of the file.
 281 .RE
 282