usr/src/lib/libast/common/man/re.3

   1 .fp 5 CW
   2 .de Af
   3 .ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
   4 .if !\a\\$4\a\a .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
   5 ..
   6 .de aF
   7 .ie \a\\$3\a\a .ft \\$1
   8 .el \{\
   9 .ds ;G \&
  10 .nr ;G \\n(.f
  11 .Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
  12 \\*(;G
  13 .ft \\n(;G \}
  14 ..
  15 .de L
  16 .aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
  17 ..
  18 .de LR
  19 .aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
  20 ..
  21 .de RL
  22 .aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
  23 ..
  24 .de EX          \" start example
  25 .ta 1i 2i 3i 4i 5i 6i
  26 .PP
  27 .RS
  28 .PD 0
  29 .ft 5
  30 .nf
  31 ..
  32 .de EE          \" end example
  33 .fi
  34 .ft
  35 .PD
  36 .RE
  37 .PP
  38 ..
  39 .TH RE 3
  40 .SH NAME
  41 recomp, reexec, ressub, refree, reerror \(mi regular expression library
  42 .SH SYNOPSIS
  43 .EX
  44 #include <re.h>
  45
  46 Re_program_t* recomp(char* \fIpattern\fP, int \fIflags\fP);
  47 int reexec(Re_program_t* \fIre\fP, char* \fIsource\fP);
  48 void ressub(Re_program_t* \fIre\fP, Sfio_t* \fIsp\fP, char* \fIold\fP, char* \fInew\fP, int \fIflags\fP);
  49 void reerror(char* \fImessage\fP);
  50 void refree(Re_program_t* \fIre\fP);
  51 .EE
  52 .SH DESCRIPTION
  53 .L recomp
  54 compiles a regular expression in
  55 .I pattern
  56 and returns a pointer to the compiled regular expression.
  57 The space is allocated by
  58 .IR malloc (3)
  59 and may be released by
  60 .LR refree .
  61 Regular expressions are as in
  62 .IR egrep (1)
  63 except that newlines are treated as ordinary
  64 characters and
  65 .L $
  66 matches the end of a null-terminated string.
  67 .I flags
  68 may be
  69 .L RE_EDSTYLE
  70 which specifies
  71 .IR ed (1)
  72 style special characters,
  73 .LR \e( ,
  74 .LR \e) ,
  75 .LR \e? ,
  76 .L \e+
  77 and
  78 .L \e|
  79 for the
  80 .IR egrep (1)
  81 .LR ( ,
  82 .LR ) ,
  83 .LR ? ,
  84 .L +
  85 and
  86 .LR | ,
  87 respectively.
  88 .PP
  89 .L reexec
  90 matches the null-terminated
  91 .I source
  92 string against the compiled regular expression
  93 .I re
  94 from a previous call to
  95 .LR recomp .
  96 If it matches,
  97 .L reexec
  98 returns a non-zero value.
  99 If
 100 .I flags
 101 is
 102 .L RE_MATCH
 103 then the array
 104 .I re\->match
 105 is filled with character pointers to the substrings of
 106 .I source
 107 that correspond to the
 108 parenthesized subexpressions of
 109 .IR pattern :
 110 .I re\->match[i].sp
 111 points to the beginning and
 112 .I re\->match[i].ep
 113 points just beyond
 114 the end of substring
 115 .IR i .
 116 (Subexpression
 117 .I i
 118 begins at the
 119 .IR i th
 120 matched left parenthesis, counting from 1.)
 121 Pointers in
 122 .I re\->match[0]
 123 pick out the substring that corresponds to
 124 the entire regular expression.
 125 Unused elements of
 126 .I re\->match
 127 are filled with zeros.
 128 Matches involving
 129 .LR * ,
 130 .LR + ,
 131 and
 132 .L ?
 133 are extended as far as possible.
 134 A maximum of 9 subexpressions will be matched.
 135 The structure of elements of
 136 .I re\->match
 137 is:
 138 .nf
 139 .ta 8n
 140         typedef struct
 141         {
 142                 char* sp;
 143                 char* ep;
 144         } rematch;
 145 .fi
 146 .LP
 147 .L ressub
 148 places in the
 149 .IR sfio (3)
 150 stream
 151 .I sp
 152 a substitution instance of
 153 .I old
 154 to
 155 .I new
 156 in
 157 .I source
 158 in the context of the last
 159 .L reexec
 160 performed on
 161 .IR re\->match .
 162 Each instance of
 163 .LI \e n ,
 164 where
 165 .I n
 166 is a digit, is replaced by the
 167 string delimited by
 168 .LI re\->match[ n ].sp
 169 and
 170 .LI re\->match[ n ].ep .
 171 Each instance of
 172 .L &
 173 is replaced by the string delimited by
 174 .I re\->match[0].sp
 175 and
 176 .IR re\->match[0].ep .
 177 If
 178 .L RE_ALL
 179 is set in
 180 .I flags
 181 then all occurrences of
 182 .I old
 183 are replaced by
 184 .IR new .
 185 If
 186 .L RE_LOWER
 187 .RL [ RE_UPPER ]
 188 is set in
 189 .I flags
 190 then
 191 .I old
 192 is converted to lower [upper] case.
 193 .LP
 194 .L reerror,
 195 called whenever an error is detected in
 196 .L recomp,
 197 .L reexec,
 198 or
 199 .L ressub,
 200 writes the string
 201 .I msg
 202 on the standard error file and exits.
 203 .L reerror
 204 may be replaced to perform
 205 special error processing.
 206 .SH DIAGNOSTICS
 207 .L recomp
 208 returns 0 for an invalid expression or other failure.
 209 .L reexec
 210 returns 1 if
 211 .I source
 212 is accepted, 0 otherwise.
 213 .SH "SEE ALSO"
 214 ed(1), grep(1), expr(1)