usr.bin/csplit/csplit.1

   1 .\" Copyright (c) 2002 Tim J. Robbins.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd December 24, 2008
  28 .Dt CSPLIT 1
  29 .Os
  30 .Sh NAME
  31 .Nm csplit
  32 .Nd split files based on context
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl ks
  36 .Op Fl f Ar prefix
  37 .Op Fl n Ar number
  38 .Ar file args ...
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 utility splits
  43 .Ar file
  44 into pieces using the patterns
  45 .Ar args .
  46 If
  47 .Ar file
  48 is
  49 a dash
  50 .Pq Sq Fl ,
  51 .Nm
  52 reads from standard input.
  53 .Pp
  54 Files are created with a prefix of
  55 .Dq xx
  56 and two decimal digits.
  57 The size of each file is written to standard output
  58 as it is created.
  59 If an error occurs whilst files are being created,
  60 or a
  61 .Dv HUP ,
  62 .Dv INT ,
  63 or
  64 .Dv TERM
  65 signal is received,
  66 all files previously written are removed.
  67 .Pp
  68 The options are as follows:
  69 .Bl -tag -width indent
  70 .It Fl f Ar prefix
  71 Create file names beginning with
  72 .Ar prefix ,
  73 instead of
  74 .Dq Pa xx .
  75 .It Fl k
  76 Do not remove previously created files if an error occurs or a
  77 .Dv HUP ,
  78 .Dv INT ,
  79 or
  80 .Dv TERM
  81 signal is received.
  82 .It Fl n Ar number
  83 Create file names beginning with
  84 .Ar number
  85 of decimal digits after the prefix,
  86 instead of 2.
  87 .It Fl s
  88 Do not write the size of each output file to standard output as it is
  89 created.
  90 .El
  91 .Pp
  92 The
  93 .Ar args
  94 operands may be a combination of the following patterns:
  95 .Bl -tag -width indent
  96 .It Xo
  97 .Sm off
  98 .Cm / Ar regexp Cm / Op Oo Cm + | - Oc Ar offset
  99 .Sm on
 100 .Xc
 101 Create a file containing the input from the current line to (but not including)
 102 the next line matching the given basic regular expression.
 103 An optional
 104 .Ar offset
 105 from the line that matched may be specified.
 106 .It Xo
 107 .Sm off
 108 .Cm % Ar regexp Cm % Op Oo Cm + | - Oc Ar offset
 109 .Sm on
 110 .Xc
 111 Same as above but a file is not created for the output.
 112 .It Ar line_no
 113 Create containing the input from the current line to (but not including)
 114 the specified line number.
 115 .It Cm { Ns Ar num Ns Cm }
 116 Repeat the previous pattern the specified number of times.
 117 If it follows a line number pattern, a new file will be created for each
 118 .Ar line_no
 119 lines,
 120 .Ar num
 121 times.
 122 The first line of the file is line number 1 for historic reasons.
 123 .El
 124 .Pp
 125 After all the patterns have been processed, the remaining input data
 126 (if there is any) will be written to a new file.
 127 .Pp
 128 Requesting to split at a line before the current line number or past the
 129 end of the file will result in an error.
 130 .Sh ENVIRONMENT
 131 The
 132 .Ev LANG , LC_ALL , LC_COLLATE
 133 and
 134 .Ev LC_CTYPE
 135 environment variables affect the execution of
 136 .Nm
 137 as described in
 138 .Xr environ 7 .
 139 .Sh EXIT STATUS
 140 .Ex -std
 141 .Sh EXAMPLES
 142 Split the
 143 .Xr mdoc 7
 144 file
 145 .Pa foo.1
 146 into one file for each section (up to 20):
 147 .Pp
 148 .Dl "csplit -k foo.1 '%^\e.Sh%' '/^\e.Sh/' '{20}'"
 149 .Pp
 150 Split standard input after the first 99 lines and every 100 lines thereafter:
 151 .Pp
 152 .Dl "csplit -k - 100 '{19}'"
 153 .Sh SEE ALSO
 154 .Xr sed 1 ,
 155 .Xr split 1 ,
 156 .Xr re_format 7
 157 .Sh STANDARDS
 158 The
 159 .Nm
 160 utility conforms to
 161 .St -p1003.1-2001 .
 162 .Sh HISTORY
 163 A
 164 .Nm
 165 command appeared in PWB UNIX.
 166 .Sh BUGS
 167 Input lines are limited to
 168 .Dv LINE_MAX
 169 (2048) bytes in length.