path: root/usr/src/man/man1/csplit.1

.\"
.\" 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
.\" http://www.opengroup.org/bookstore/.
.\"
.\" 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 SunOS 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" 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.
.\"
.\" 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.
.\"
.\" 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]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
.\"
.TH CSPLIT 1 "Dec 4, 2003"
.SH NAME
csplit \- split  files based on context
.SH SYNOPSIS
.LP
.nf
\fBcsplit\fR [\fB-ks\fR] [\fB-f\fR \fIprefix\fR] [\fB-n\fR \fInumber\fR] \fIfile\fR \fIarg1\fR... \fIargn\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBcsplit\fR utility reads the file named by the \fIfile\fR operand, writes
all or part of that file into other files as directed by the \fIarg\fR
operands, and writes the sizes of the files.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-f\fR\fI prefix\fR\fR
.ad
.RS 13n
Names the created files \fIprefix\fR\fB00\fR, \fIprefix\fR\fB01\fR, ...,
\fIprefix\fR\fIn\fR. The default is \fBxx00\fR ... \fBxx\fR\fIn\fR. If the
\fIprefix\fR argument would create a file name exceeding \fB14\fR bytes, an
error results. In that case, \fBcsplit\fR exits with a diagnostic message and
no files are created.
.RE

.sp
.ne 2
.na
\fB\fB-k\fR\fR
.ad
.RS 13n
Leaves previously created files intact. By default, \fBcsplit\fR removes
created files if an error occurs.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fI number\fR\fR
.ad
.RS 13n
Uses \fInumber\fR decimal digits to form filenames for the file pieces. The
default is \fB2\fR.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 13n
Suppresses the output of file size messages.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 8n
The path name of a text file to be split. If \fIfile\fR is \fB-\fR, the
standard input will be used.
.RE

.sp
.LP
The operands \fIarg1\fR ... \fIargn\fR can be a combination of the following:
.sp
.ne 2
.na
\fB/\fIrexp\fR/[\fIoffset\fR]\fR
.ad
.RS 18n
Create a file using the content of the lines from the current line up to, but
not including, the line that results from the evaluation of the regular
expression with \fIoffset\fR, if any, applied. The regular expression
\fIrexp\fR must follow the rules for basic regular expressions. Regular
expressions can include the use of '\fB\e/\fR\&' and '\fB\e%\fR\&'. These forms
must be properly quoted with single quotes, since "\fB\e\fR" is special to the
shell. The optional \fIoffset\fR must be a positive or negative integer value
representing a number of lines. The integer value must be preceded by \fB+\fR
or \fB\(mi\fR\&. If the selection of lines from an offset expression of this
type would create a file with zero lines, or one with greater than the number
of lines left in the input file, the results are unspecified. After the section
is created, the current line will be set to the line that results from the
evaluation of the regular expression with any offset applied. The pattern match
of \fIrexp\fR always is applied from the current line to the end of the file.
.RE

.sp
.ne 2
.na
\fB%\fIrexp\fR%[\fIoffset\fR]\fR
.ad
.RS 18n
This operand is the same as /\fIrexp\fR/[\fIoffset\fR], except that no file
will be created for the selected section of the input file.
.RE

.sp
.ne 2
.na
\fB\fIline_no\fR\fR
.ad
.RS 18n
Create a file from the current line up to (but not including) the line number
\fIline_no\fR. Lines in the file will be numbered starting at one. The current
line becomes \fIline_no\fR.
.RE

.sp
.ne 2
.na
\fB{\fInum\fR}\fR
.ad
.RS 18n
Repeat operand. This operand can follow any of the operands described
previously. If it follows a \fIrexp\fR type operand, that operand will be
applied \fInum\fR more times. If it follows a \fIline_no\fR operand, the file
will be split every \fIline_no\fR lines, \fInum\fR times, from that point.
.RE

.sp
.LP
An error will be reported if an operand does not reference a line between the
current position and the end of the file.
.SH USAGE
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBcsplit\fR when
encountering files greater than or equal to 2 Gbyte (2^31 bytes).
.SH EXAMPLES
.LP
\fBExample 1 \fRSplitting and combining files
.sp
.LP
This example creates four files, \fBcobol00\fR...\fBcobol03\fR.

.sp
.in +2
.nf
example% \fBcsplit -f cobol filename \e
   '/procedure division/' /par5./ /par16./\fR
.fi
.in -2
.sp

.sp
.LP
After editing the \fBsplit\fR files, they can be recombined as follows:

.sp
.in +2
.nf
example% \fBcat cobol0[0\(mi3] > \fIfilename\fR\fR
.fi
.in -2
.sp

.sp
.LP
This example overwrites the original file.

.LP
\fBExample 2 \fRSplitting a file into equal parts
.sp
.LP
This example splits the file at every 100 lines, up to 10,000 lines. The
\fB-k\fR option causes the created files to be retained if there are less than
10,000 lines; however, an error message would still be printed.

.sp
.in +2
.nf
example% \fBcsplit -k filename 100 {99}\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRCreating a file for separate C routines
.sp
.LP
If \fBprog.c\fR follows the normal C coding convention (the last line of a
routine consists only of a \fB}\fR in the first character position), this
example creates a file for each separate C routine (up to 21) in \fBprog.c\fR.

.sp
.in +2
.nf
example% \fBcsplit -k prog.c '%main(%' '/^}/+1' {20}\fR
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBcsplit\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Standard
.TE

.SH SEE ALSO
.sp
.LP
\fBsed\fR(1), \fBsplit\fR(1), \fBattributes\fR(5), \fBenviron\fR(5),
\fBlargefile\fR(5), \fBstandards\fR(5)
.SH DIAGNOSTICS
.sp
.LP
The diagnostic messages are self-explanatory, except for the following:
.sp
.ne 2
.na
\fB\fIarg\fR \(mi out of range\fR
.ad
.RS 25n
The given argument did not reference a line between the current position and
the end of the file.
.RE