share/man/man3c/regcmp.3c

   1 '\" te
   2 .\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH REGCMP 3C "Nov 14, 2002"
   7 .SH NAME
   8 regcmp, regex \- compile and execute regular expression
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <libgen.h>
  13
  14 \fBchar *\fR\fBregcmp\fR(\fBconst char *\fR\fIstring1\fR, /* \fBchar *\fR\fIstring2\fR */ ...,
  15      \fBint\fR /*(\fBchar*\fR)0*/);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBchar *\fR\fBregex\fR(\fBconst char *\fR\fIre\fR, \fBconst char *\fR\fIsubject\fR,
  21      /* \fBchar *\fR\fIret0\fR */ ...);
  22 .fi
  23
  24 .LP
  25 .nf
  26 extern char *__loc1;
  27 .fi
  28
  29 .SH DESCRIPTION
  30 .sp
  31 .LP
  32 The \fBregcmp()\fR function compiles a regular expression (consisting of the
  33 concatenated arguments) and returns a pointer to the compiled form.  The
  34 \fBmalloc\fR(3C) function is used to create space for the compiled form. It is
  35 the user's responsibility to free unneeded space so allocated. A \fINULL\fR
  36 return from \fBregcmp()\fR indicates an incorrect argument. \fBregcmp\fR(1) has
  37 been written to generally preclude the need for this routine at execution time.
  38 .sp
  39 .LP
  40 The \fBregex()\fR function executes a compiled pattern against the subject
  41 string. Additional arguments are passed to receive values back.  The
  42 \fBregex()\fR function returns \fINULL\fR on failure or a pointer to the next
  43 unmatched character on success. A global character pointer \fB__loc1\fR points
  44 to where the match began.  The \fBregcmp()\fR and \fBregex()\fR functions were
  45 mostly borrowed from the editor \fBed\fR(1); however, the syntax and semantics
  46 have been changed slightly. The following are the valid symbols and associated
  47 meanings.
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fB[\|]\|*\|.^\fR\fR
  52 .ad
  53 .RS 18n
  54 This group of symbols retains its meaning as described on the \fBregexp\fR(5)
  55 manual page.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fB$\fR\fR
  62 .ad
  63 .RS 18n
  64 Matches the end of the string; \fB\en\fR matches a newline.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fB\(mi\fR\fR
  71 .ad
  72 .RS 18n
  73 Within brackets the minus means \fIthrough\fR. For example, \fB[a\(miz]\fR is
  74 equivalent to \fB[abcd\|.\|.\|.xyz]\fR. The \fB\(mi\fR can appear as itself
  75 only if used as the first or last character. For example, the character class
  76 expression \fB[]\(mi]\fR matches the characters \fB]\fR and \fB\(mi\fR\&.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fB+\fR\fR
  83 .ad
  84 .RS 18n
  85 A regular expression followed by \fB+\fR means \fIone or more times\fR. For
  86 example, \fB[0\(mi9]+\fR is equivalent to \fB[0\(mi9][0\(mi9]*.\fR
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fB{\fR\fIm\fR} {\fIm,\fR} {\fIm,u\fR}\fR
  93 .ad
  94 .RS 18n
  95 Integer values enclosed in \fB{\|}\fR indicate the number of times the
  96 preceding regular expression is to be applied. The value \fIm\fR is the minimum
  97 number and \fIu\fR is a number, less than 256, which is the maximum. If only
  98 \fIm\fR is present (that is, \fB{\fR\fIm\fR\fB}\fR), it indicates the exact
  99 number of times the regular expression is to be applied. The value
 100 \fB{\fR\fIm\fR\fB,}\fR is analogous to \fB{\fR\fIm,infinity\fR\fB}\fR. The plus
 101 (\fB+\fR) and star (\fB*\fR) operations are equivalent to \fB{1,}\fR and
 102 \fB{0,}\fR respectively.
 103 .RE
 104
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fB( ... )$\fR\fIn\fR\fR
 109 .ad
 110 .RS 18n
 111 The value of the enclosed regular expression is to be returned. The value will
 112 be stored in the (\fIn\fR+1)th argument following the subject argument. At
 113 most, ten enclosed regular expressions are allowed. The \fBregex()\fR function
 114 makes its assignments unconditionally.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fB( ... )\fR\fR
 121 .ad
 122 .RS 18n
 123 Parentheses are used for grouping. An operator, for example, \fB*\fR, \fB+\fR,
 124 \fB{\|}\fR, can work on a single character or a regular expression enclosed in
 125 parentheses. For example, \fB(a*(cb+)*)$0\fR. By necessity, all the above
 126 defined symbols are special. They must, therefore, be escaped with a \fB\e\fR
 127 (backslash)  to be used as themselves.
 128 .RE
 129
 130 .SH EXAMPLES
 131 .LP
 132 \fBExample 1 \fRExample matching a leading newline in the subject string.
 133 .sp
 134 .LP
 135 The following example matches a leading newline in the subject string pointed
 136 at by cursor.
 137
 138 .sp
 139 .in +2
 140 .nf
 141 char *cursor, *newcursor, *ptr;
 142         .\|.\|.
 143 newcursor = regex((ptr = regcmp("^\en", (char *)0)), cursor);
 144 free(ptr);
 145 .fi
 146 .in -2
 147
 148 .sp
 149 .LP
 150 The following example matches through the string \fBTesting3\fR and returns the
 151 address of the character after the last matched character  (the ``\fB4\fR'').
 152 The string \fBTesting3\fR is copied to the character array \fBret0\fR.
 153
 154 .sp
 155 .in +2
 156 .nf
 157 char ret0[9];
 158 char *newcursor, *name;
 159         .\|.\|.
 160 name = regcmp("([A\(miZa\(miz][A\(miza\(miz0\(mi9]{0,7})$0", (char *)0);
 161 newcursor = regex(name, "012Testing345", ret0);
 162 .fi
 163 .in -2
 164
 165 .sp
 166 .LP
 167 The following example applies a precompiled regular expression in \fBfile.i\fR
 168 (see \fBregcmp\fR(1)) against \fIstring\fR.
 169
 170 .sp
 171 .in +2
 172 .nf
 173 \fB#include "file.i"
 174 char *string, *newcursor;
 175         .\|.\|.
 176 newcursor = regex(name, string);\fR
 177 .fi
 178 .in -2
 179
 180 .SH ATTRIBUTES
 181 .sp
 182 .LP
 183 See \fBattributes\fR(5) for descriptions of the following attributes:
 184 .sp
 185
 186 .sp
 187 .TS
 188 box;
 189 c | c
 190 l | l .
 191 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 192 _
 193 MT-Level        MT-Safe
 194 .TE
 195
 196 .SH SEE ALSO
 197 .sp
 198 .LP
 199 \fBed\fR(1), \fBregcmp\fR(1), \fBmalloc\fR(3C), \fBattributes\fR(5),
 200 \fBregexp\fR(5)
 201 .SH NOTES
 202 .sp
 203 .LP
 204 The user program may run out of memory if \fBregcmp()\fR is called iteratively
 205 without freeing the vectors no longer required.