regcomp(3C) regcomp(3C)
NAME
regcomp, regexec, regerror, regfree - Reguläre Ausdrücke vergleichen
SYNTAX
#include <sys/types.h>
#include <regex.h>
int regcomp(regext *preg, const char *pattern, int cflags);
int regexec(const regext *preg, const char *string, sizet nmatch,
regmatcht pmatch[ ], int eflags);
sizet regerror(int errcode, const regext *preg, char *errbuf,
sizet errbufsize);
void regfree(regext *preg);
BESCHREIBUNG
Diese Funktionen bearbeiten einfache und erweiterte reguläre Ausdrücke
entsprechend der Beschreibung in expressions(5).
Falls die Funktionen nicht unterstützt werden, wird errno auf ENOSYS
gesetzt und der Rückgabewert REGENOSYS (von regcomp() und regexec())
bzw. 0 (von regerror()) zurückgeliefert.
Der Strukturtyp regext enthält mindestens die folgende Komponente:
______________________________________________________________________
| Typ | Name | Beschreibung |
|___________|_____________|___________________________________________|
| sizet | rensub | Anzahl der geklammerten Teilausdrücke |
|___________|_____________|___________________________________________|
Der Strukturtyp regmatch enthält mindestens die folgenden Komponen-
ten:
______________________________________________________________________
| Typ | Name | Beschreibung |
|____________|____________|___________________________________________|
| regofft | rmso | Byte-Offset vom Anfang von string bis |
| | | zum Anfang der Teil-Zeichenkette |
|____________|____________|___________________________________________|
| regofft | rmeo | Byte-Offset vom Anfang von string bis |
| | | zum ersten Zeichen nach dem Ende der |
| | | Teil-Zeichenkette |
|____________|____________|___________________________________________|
Die Funktion regcomp() wandelt die regulären Ausdrücke in der Zeichen-
kette, auf die das Argument pattern zeigt, um und legt die Ergebnisse
in der Struktur ab, auf die preg zeigt. Das Argument cflags steht für
die bitweise, inklusive ODER-Verknüpfung keines oder mehrerer der fol-
genden Flags (diese Flags sind in der Include-Datei <regex.h> defi-
niert):
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
regcomp(3C) regcomp(3C)
REGEXTENDED Verwendung erweiterter regulärer Ausdrücke.
REGICASE Groß-/Kleinschreibung beim Vergleich ignorieren.
REGNOSUB Nur Erfolg/Mißerfolg der Funktion regexec() mel-
den.
REGNEWLINE Bearbeitung der Neue-Zeile-Zeichen entsprechend
der Beschreibung im Text ändern.
REGLITNL Die Zeichenkette \n wird als Neue-Zeile-Zeichen
behandelt.
REGVIMODE << bzw. >> werden als Anfang bzw. Ende eines Wor-
tes interpretiert.
REGNSUBANCHOR Die Zeichen ^ und $ wirken innerhalb von Unteraus-
drücken nicht als Anker.
REGEMPTY regcomp() liefert einen Fehlerwert, wenn pattern
Null oder leer ist.
Der Standardtyp für reguläre Ausdrücke für pattern ist der einfache
reguläre Ausdruck. Die Anwendung kann den erweiterten regulären Aus-
druck mit dem Flag REGEXTENDED in cflags angeben. Bei der Formulie-
rung der regulären Ausdrücke ist folgendes zu beachten:
- Äquivalenzklassen können in Bereichsangaben verwendet werden.
- aneinandergehängte Bereichsangaben der Form [b-d-f] sind nicht mög-
lich. In diesem Fall werden - und f als normale Zeichen behandelt.
- { wird in einfachen und {{ in erweiterten regulären Ausdrücken als
normales Zeichen behandelt und initiiert in diesem Fall keine Wie-
derholung.
- eine Wiederholungsanweisung am Anfang eines regulären Ausdrucks
wird als normales Zeichen behandelt.
- ^ am Anfang bzw. $ am Ende eines Unterausdrucks wirken als Anker,
außer wenn das Flag REGNSUBANCHOR gesetzt ist.
Bei erfolgreicher Beendigung wird Null zurückgegeben. Andernfalls wird
ein Wert ungleich Null zurückgegeben. In diesem Fall ist der Inhalt
von preg nicht definiert.
Wenn das Flag REGNOSUB nicht in cflags gesetzt wurde, setzt regcomp()
rensub auf die Anzahl der geklammerten Teilausdrücke (begrenzt durch
\( \) in einfachen regulären Ausdrücken bzw. ( ) in erweiterten regu-
lären Ausdrücken) in pattern.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
regcomp(3C) regcomp(3C)
Die Funktion regexec() vergleicht die mit einem Nullbyte abgeschlos-
sene Zeichenkette, die in string angegeben ist, mit dem umgewandelt
regulären Ausdruck preg, der durch einen vorherigen Aufruf von
regcomp() initialisiert wurde. Wenn eine Entsprechung gefunden wird,
gibt regexec() Null zurück. Andernfalls wird ein Wert ungleich Null
zurückgegeben, der angibt, daß keine Entsprechung gefunden wurde oder
ein Fehler aufgetreten ist. Das Argument eflags steht für die bit-
weise, inklusive ODER-Verknüpfung keines oder mehrerer der folgenden
Flags (die Flags sind in der Include-Datei <regex.h> definiert).
REGNOTBOL Das erste Zeichen der Zeichenkette, auf die string
zeigt, ist nicht der Zeilenanfang. Daher entspricht das
Zirkumflex-Zeichen (^) als Sonderzeichen nicht dem
Anfang von string.
REGNOTEOL Das letzte Zeichen der Zeichenkette, auf die string
zeigt, ist nicht das Zeilenende. Daher entspricht das
Dollar-Zeichen ($) als Sonderzeichen nicht dem Ende von
string.
Wenn nmatch gleich Null ist oder REGNOSUB im Argument cflags von
regcomp() gesetzt wurde, ignoriert regexec() das Argument pmatch.
Andernfalls muß das Argument pmatch auf ein Feld mit mindestens nmatch
Teil-Zeichenketten zeigen. regexec() liefert für die Elemente dieses
Feldes Offsets der Teil-Zeichenketten von string, die den geklammerten
Teilausdrücken von pattern entsprechen: pmatch[i].rmso ist der Byte-
Offset des Anfangs und pmatch[i].rmeo ist um 1 größer als der Byte-
Offset des Endes der Teil-Zeichenkette i. (Der Teilausdruck i beginnt
bei der i-ten gefundenen, öffnenden Klammer, gezählt wird ab 1.) Off-
sets in pmatch[0] geben die Teil-Zeichenkette an, die dem gesamten
regulären Ausdruck entspricht. Nicht verwendete Elemente von pmatch
bis pmatch[nmatch1-1] erhalten -1. Wenn es mehr als nmatch Teilaus-
drücke in pattern gibt (pattern zählt selbst als Teilausdruck), führt
regexec() den Vergleich trotzdem aus, registriert aber nur die ersten
nmatch Teil-Zeichenketten.
Beim Vergleich mit einfachen oder erweiterten regulären Ausdrücken
kann ein beliebiger geklammerter Teilausdruck von pattern am Vergleich
mit mehreren unterschiedlichen Teil-Zeichenketten von string beteiligt
sein. Es ist auch möglich, daß er zu keiner Teil-Zeichenkette paßt,
obwohl das Muster als ganzes gepaßt hat. Die folgenden Regeln werden
verwendet, um zu bestimmen, welche Teil-Zeichenketten beim Vergleich
regulärer Ausdrücke in pmatch geliefert werden sollen:
1. Wenn der Teilausdruck i in einem regulären Ausdruck nicht in einem
anderen Teilausdruck enthalten ist und mehrmals am Vergleich betei-
ligt ist, begrenzen die Byte-Offsets in pmatch[i] den letzten Ver-
gleich.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
regcomp(3C) regcomp(3C)
2. Wenn der Teilausdruck i nicht in einem anderen Teilausdruck enthal-
ten ist und nicht an einem ansonsten erfolgreichen Vergleich betei-
ligt war, sind die Byte-Offsets in pnmatch[i] gleich -1. Ein Teil-
ausdruck ist nicht an dem Vergleich beteiligt, wenn:
- * bzw. \{ \} unmittelbar nach dem Teilausdruck in einem einfa-
chen regulären Ausdruck erscheinen
- *, ? oder { } unmittelbar nach dem Teilausdruck in einem erwei-
terten regulären Ausdruck erscheinen und der Vergleich mit dem
Teilausdruck nicht erfolgreich war (keine Entsprechung)
- | in einem erweiterten regulären Ausdruck dazu verwendet wird,
diesen oder einen anderen Teilausdruck auszuwählen, wobei der
Vergleich mit dem anderen Teilausdruck erfolgreich war.
3. Wenn der Teilausdruck i in einem anderen Teilausdruck j enthalten
ist, i in keinem anderen Teilausdruck innerhalb j enthalten ist und
in pmatch[j] eine Entsprechung des Teilausdrucks j gemeldet wird,
erfolgt eine Meldung des Erfolgs oder Mißerfolgs einer Entsprechung
des Teilausdrucks i in pmatch[i] entsprechend der Beschreibungen
unter 1. und 2. Die Meldung erfolgt jedoch im Rahmen der Teil-
Zeichenkette in pmatch[j], und nicht für die gesamte Zeichenkette.
4. Wenn der Teilausdruck i im Teilausdruck j enthalten ist und die
Byte-Offsets in pmatch[j] den Wert -1 haben, haben die Zeiger in
pmatch[i] ebenfalls den Wert -1.
5. Wenn der Teilausdruck i einer Zeichenkette der Länge Null ent-
spricht, entsprechen beide Byte-Offsets in pmatch[i] dem Byte-
Offset des Zeichens oder des abschließenden Nullbytes unmittelbar
nach der Zeichenkette der Länge Null.
Wenn beim Aufruf der Funktion regexec() die Locale (internationale
Umgebung) anders ist als bei der Übersetzung des regulären Ausdrucks,
ist das Ergebnis nicht definiert.
Wenn REGNEWLINE in cflags nicht gesetzt ist, wird ein Neue-Zeile-
Zeichen in pattern oder string als normales Zeichen behandelt. Wenn
REGNEWLINE gesetzt ist, wird das Neue-Zeile-Zeichen mit den folgenden
Ausnahmen als normales Zeichen behandelt:
1. Ein Neue-Zeile-Zeichen in string entspricht nicht einem Punkt
außerhalb eines regulären Ausdrucks in eckigen Klammern oder bei
einer beliebigen Liste von "Nicht-Entsprechungen".
2. Ein Zirkumflex-Zeichen (^) in pattern, das das erste Zeichen eines
Musters markiert, entspricht der Zeichenkette der Länge Null unmit-
telbar nach einem Neue-Zeile-Zeichen in string (ohne Berücksichti-
gung der Einstellung von REGNOTBOL).
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
regcomp(3C) regcomp(3C)
3. Ein Dollar-Zeichen ($) in pattern, das das letzte Zeichen eines
Musters markiert, entspricht der Zeichenkette der Länge Null unmit-
telbar vor einem Neue-Zeile-Zeichen in string (ohne Berücksichti-
gung der Einstellung von REGNOTEOL).
Die Funktion regfree() gibt den Speicher frei, der durch die Funktion
regcomp() für preg zugewiesen wurde.
Die folgenden Konstanten sind als Rückgabewerte für Fehler definiert:
REGNOMATCH regexec() fehlgeschlagen.
REGINVARG Ein ungültiger Parameter wurde angegeben.
REGBADPAT Ungültiger regulärer Ausdruck.
REGECOLLATE Bezug auf ungültige Zeicheneinheit aus der Buch-
stabierreihenfolge.
REGECTYPE Bezug auf ungültigen Zeichenklassentyp.
REGEESCAPE Nachfolgendes Zeichen \ im Muster.
REGESUBREG Zahl in \digit ungültig oder Fehler.
REGEBRACK [ oder ] fehlt.
REGENOSYS Die Funktion wird nicht unterstützt.
REGEPAREN \( oder \) fehlt bzw. ( oder ) fehlt.
REGEBRACE \{ oder \} fehlt.
REGBADBR Inhalt von \{ \} ungültig: keine Zahl, Zahl zu
groß, mehr als zwei Zahlen, erste Zahl größer als
zweite Zahl.
REGERANGE Ungültiger Endpunkt in Bereichsausdruck.
REGESPACE Kein Speicherplatz.
REGBADRPT Kein gültiger regulärer Ausdruck vor ?, * bzw. +.
REGEPATTERN Als Parameter wurde ein Null- bzw. Leermuster
angegeben und regcomp() wurde mit dem Flag
REGEMPTY aufgerufen.
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98
regcomp(3C) regcomp(3C)
Die Funktion regerror() liefert eine Abbildung von Fehlercodes, die
von regcomp() und regexec() zurückgegeben werden, in unspezifizierte,
druckbare Zeichenketten. Es wird eine Zeichenkette entsprechend dem
Wert des Arguments errcode generiert. Der Wert muß der letzte Wert
ungleich Null sein, der von regcomp() oder regexec() bei dem gegebenen
Wert von preg zurückgegeben wird. Wenn errcode keinen solchen Wert
hat, ist der Inhalt der generierten Zeichenkette nicht definiert.
Wenn preg ein Nullzeiger ist, aber errcode ein Wert ist, der von einem
vorherigen Aufruf von regexec() oder regcomp() zurückgegeben wurde,
generiert regerror() trotzdem eine Fehler-Zeichenkette, die dem Wert
von errcode entspricht, die jedoch bei einigen Implementierungen unter
Umständen nicht sehr detailliert ist.
Wenn das Argument errbufsize einen Wert ungleich Null hat, legt die
Funktion regerror() die generierte Zeichenkette in dem Puffer der
Größe errbufsize ab, auf den errbuf zeigt. Wenn die Zeichenkette
(einschließlich des abschließenden Nullbytes) nicht in den Puffer
paßt, schneidet regerror() die Zeichenkette ab und fügt ein abschlie-
ßendes Nullbyte an das Ergebnis an.
Wenn errbufsize gleich Null ist, ignoriert regerror() das Argument
errbuf und gibt die Größe des Puffers zurück, die benötigt wird, um
die generierte Zeichenkette aufzunehmen.
Wenn das Argument preg für regexec() oder regcomp() kein umgewandel-
ter, von regcomp() zurückgegebener, regulärer Ausdruck ist, ist das
Ergebnis nicht definiert. Nach der Übergabe an regfree() wird preg
nicht mehr als umgewandelter, regulärer Ausdruck behandelt.
Eine Anwendung könnte mit
regerror(code, preg, (char *)NULL, (sizet) 0)
feststellen, welche Größe der Puffer für die generierte Zeichenkette
haben muß, mit malloc() einen Puffer zur Aufnahme der Zeichenkette
bereitstellen und dann die Funktion regerror() noch einmal aufrufen,
um die Zeichenkette lesen. Es kann aber auch ein fester, statischer
Puffer zugewiesen werden, der für die meisten Zeichenketten ausrei-
chend groß ist. Anschließend kann mit malloc() für den Fall ein größe-
rer Puffer zugewiesen werden, wenn dieser Puffer zu klein sein sollte.
Für die Bearbeitung von Mustern mit der Mustervergleichssyntax sollten
Sie die Funktion fnmatch() verwenden.
ERGEBNIS
Bei erfolgreicher Beendigung gibt die Funktion regcomp() Null zurück.
Andernfalls wird ein Integer-Wert zurückgegeben, der einen Fehler ent-
sprechend der Beschreibung in regex.h angibt. Der Inhalt von preg ist
dann nicht definiert.
Seite 6 Reliant UNIX 5.44 Gedruckt 11/98
regcomp(3C) regcomp(3C)
Bei erfolgreicher Beendigung gibt die Funktion regexec() Null zurück.
Andernfalls gibt sie REGNOMATCH zurück, wenn keine Entsprechung
gefunden wurde. Wenn die Funktion nicht unterstützt wird, wird
REGENOSYS zurückgegeben.
Bei erfolgreicher Beendigung gibt die Funktion regerror() die zur Auf-
nahme der gesamten, generierten Zeichenkette notwendige Anzahl der
Bytes zurück. Andernfalls gibt sie Null zurück und zeigt so an, daß
die Funktion nicht implementiert ist.
Die Funktion regfree() gibt keinen Wert zurück.
BEISPIELE
#include <regex.h>
/* Match string against the extended regular expression in
* pattern, treating errors as no match.
* return 1 for match, 0 for no match. */
int match (const char *string, char *pattern)
{
int status;
regext re;
if (regcomp (&re, pattern, REGEXTENDED|REGNOSUB) !=0)
{
return (0); /* report error */
}
status = regexec (&re, string, (sizet) 0, NULL, 0);
regfree (&re);
if (status != 0)
{
return (0); /* report error */
}
return (1);
}
Das folgende Beispiel zeigt, wie das Flag REGNOTBOL für die Funktion
regexec() verwendet werden kann, um alle Teil-Zeichenketten in einer
Zeile zu finden, die einem vom Benutzer angegebenen Muster entspre-
chen. (Das Beispiel ist sehr einfach gehalten. Deshalb wird nur ein
Minimum an Fehlerprüfung durchgeführt.)
(void) regcomp (&re, pattern, 0);
/* this call to regexec() finds the first match on the line */
error = regexec (&re, &buffer[0], 1, pm, 0);
while (error == 0)
{ /* while matches found */
/* substring found between pm.rmso and pm.rmeo */
/* This call to regexec() finds the next match */
error = regexec (&re, buffer + pm.rm:eo, 1, &pm, REGNOTBOL);
}
Seite 7 Reliant UNIX 5.44 Gedruckt 11/98
regcomp(3C) regcomp(3C)
HINWEISE
Wenn Sie eine dieser Funktionen verwenden, müssen Sie bei der Überset-
zung die Bibliothek libgen dazubinden (cc -lgen).
SIEHE AUCH
regcmp(1), fnmatch(3C), glob(3C), regex(3), regcmp(3G), regexpr(3G),
expressions(5), regex(5), regexp(5).
Seite 8 Reliant UNIX 5.44 Gedruckt 11/98