usr.bin/csplit/csplit.1

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