regcomp, regexec, regerror, regfree - Reguläre Ausdrücke interpretieren

Definition

#include <sys/types.h>
#include <regex.h>

int regcomp(regex_t *preg, const char *pattern, int cflags);
int regexec(const regex_t *preg, cont char *string, size_t nmatch, regmatch_t pmatch[],

int eflags);

size_t regerror(int errcode, const regex_t *preg,char *errbuf, size_t errbuf_size);
void regfree(regex_t *preg);

Beschreibung

Diese Funktionen interpretieren internationalisierte einfache reguläre Ausdrücke und erweiterte reguläre Ausdrücke, wie sie in „XBD Regular Expressions“ beschrieben sind.

Die Struktur regex_t enthält mindestens folgendes Element:

size_t re_nsub

Anzahl der geklammerten Teilausdrücke.

Die Struktur regmatch_t enthält mindestens folgende Elemente:

regoff_t rm_so	Offset vom Beginn der Zeichenkette bis zum Anfang der Teilzeichenkette.
regoff_t rm_eo	Offset vom Beginn der Zeichenkette bis zum ersten Zeichen nach dem Ende der Teilzeichenkette.

Die Funktion regcomp() übersetzt den regulären Ausdruck, der in der Zeichenkette enthalten ist, auf die das Argument pattern zeigt und speichert das Ergebnis in der Struktur auf die preg zeigt.

Das Argument cflags ist ein bitweises inklusives ODER von keinem oder mehreren der folgenden Flags, die im Header regex.h definiert werden:

REG_EXTENDED	Benutze erweiterte reguläre Ausdrücke.
REG_ICASE	Ignoriere Groß- Kleinschreibung beim Vergleich.
REG_NOSUB	regexex() meldet nur Erfolg oder Misserfolg.
REG_NEWLINE	Verändert die Behandlung von Neuezeilezeichen, wie im Text beschrieben.

Standardmäßig wird der Parameter pattern als einfacher regulärer Ausdruck interpretiert. Mit dem Setzen des Flags REG_EXTENDED im Parameter cflags kann die Anwendung angeben, dass es sich um einen erweiterten regulären Ausdruck handelt.

Bei Erfolg wird 0 zurückgegeben, sonst ein Wert ungleich 0. In diesem Fall ist der Inhalt von preg undefiniert.

Wenn das Flag REG_NOSUB in cflags nicht gesetzt ist, gibt regcomp() in re_nsub die Anzahl der in pattern gefundenen geklammerten Teilausdrücke zurück, die in einfachen regulären Ausdrücken durch \( \) und in erweiterten regulären Ausdrücken durch ( ) begrenzt sind.

Die Funktion regexec() vergleicht die durch string spezifizierte und mit Null abgeschlossene Zeichenkette mit dem übersetzten regulären Ausdruck preg, der durch einen vorangegangen Aufruf von regcomp() initialisiert wurde. Wenn eine Übereinstimmung gefunden wird, gibt regexec() 0 zurück. Sonst wird ein Wert verschieden von 0 zurückgegeben. Dies kann bedeuten, dass keine Übereinstimmung gefunden wurde, oder dass ein Fehler aufgetreten ist. Das Argument eflags ist ein bitweises inklusives ODER von keinem oder mehreren der folgenden Flags, die im Header regex.h definiert sind:

REG_NOTBOL	Das erste Zeichen der Zeichenkette, auf die string zeigt, ist nicht das erste Zeichen einer Zeile. Dadurch gibt es für ^ keine Übereinstimmung mit dem Zeilenanfang, wenn dieses als spezielles Zeichen verwendet wurde.
NEG_NOTEOL	Das letzte Zeichen der Zeichenkette, auf die string zeigt, ist nicht das letzte Zeichen einer Zeile. Dadurch gibt es für $ keine Übereinstimmung mit dem Zeilenende, wenn dieses als spezielles Zeichen verwendet wurde.

Wenn in den Argumenten für regcomp() für nmatch 0 übergeben, oder in cflags das Flag REG_NOSUB gesetzt wurde, ignoriert regexec() das Argument pmatch. Sonst muss pmatch auf ein Array mit mindestens nmatch Elementen zeigen und regexec() füllt die Elemente des Arrays mit den Offsets der Teilzeichenketten von string, die mit den geklammerten Teilausdrücken von pattern übereinstimmen: pmatch[i].rm_so ist der Byteoffset des Anfangs und pmatch[i].rm_eo der um eins vergrößerte Byteoffset des Endes der i-ten Teilzeichenkette. (Der Teilausdruck i beginnt mit der i-ten öffnenden Klammer, wenn man mit 1 zu zählen beginnt.) Die Offsets in pmatch[0] identifizieren die Teilzeichenkette, die mit dem gesamten regulären Ausdruck übereinstimmt. Ungenutzte Elemente von pmatch werden mit -1 gefüllt. Gibt es mehr als nmatch Teilzeichenketten in pattern, wobei pattern selbst dazu zählt, prüft regexec() zwar die gesamte Übereinstimmung, dokumentiert aber nur die ersten nmatch Teilzeichenketten.

Beim Vergleich eines einfachen oder erweiterten regulären Ausdrucks, kann jeder enthaltene geklammerte Teilausdruck von pattern mit mehreren verschiedenen Teilzeichenketten von string, oder aber auch keiner Teilzeichenkette übereinstimmen, obwohl der gesamte Ausdruck übereinstimmt.

Die folgenden Regeln legen fest, welche der übereinstimmenden Teilzeichenketten gemeldet werden.

1. Wenn der Teilausdruck i nicht in einem anderen Teilausdruck enthalten ist und Teil mehrerer Übereinstimmungen ist, dann begrenzt pmatch[i] die letzte Übereinstimmung.

2. Wenn der Teilausdruck i nicht in einem anderen Teilausdruck enthalten ist und nicht Teil einer Übereinstimmung ist, werden die Offsets in match[i] auf -1 gesetzt.

   Ein Teilausdruck ist nicht Teil einer Übereinstimmung, wenn:

   • * oder \{ \} direkt nach dem Teilausdruck in einem einfachen regulären Ausdruck, oder *, ?, oder { } direkt nach dem Teilausdruck in einem erweiterten regulären Ausdruck steht und der Teilausdruck nicht (0 mal) übereinstimmt

     oder

   • | in einem erweiterten regulären Ausdruck verwendet wird um diesen oder einen anderen Teilausdruck auszuwählen und der andere Teilausdruck übereinstimmt.

3. Wenn der Teilausdruck i im Teilausdruck j, aber in keinem weiteren Teilausdruck innerhalb von j enthalten ist und in pmatch[j] eine Übereinstimmung gemeldet wird, dann wird eine oder keine Übereinstimmung von i in pmatch[i] auf die unter Punkt 1. und 2. beschriebene Weise gemeldet, aber bezogen auf die in pmatch[j] gemeldete Teilzeichenkette statt auf die ganze Zeichenkette.

4. Wenn der Teilausdruck i im Teilausdruck j enthalten ist und die Offsets in pmatch[j] auf -1 gesetzt sind, so sind die Zeiger in pmatch[i] ebenfalls auf -1 gesetzt.

5. Wenn der Teilausdruck i mit eine Zeichenkette der Länge 0 übereinstimmt, dann sind beide Offsets von pmatch[i] der Offset des Zeichens oder der terminierenden Null, das bzw. die unmittelbar der Zeichenkette der Länge 0 folgt.

Wenn die Lokalität, die eingestellt ist, wenn regexec() gerufen wird, nicht mit der übereinstimmt, die eingestellt war, als der reguläre Ausdruck übersetzt wurde, ist das Ergebnis undefiniert.

Wenn REG_NEWLINE in cflags nicht gesetzt ist, wird ein Zeilenumbruch immer wie ein normales Zeichen behandelt.

Wenn REG_NEWLINE gesetzt ist, wird ein Zeilenumbruch mit folgenden Ausnahmen wie ein normales Zeichen behandelt:

1. Ein Zeilenumbruch in string stimmt mit keinem Punkt (.) außerhalb eines geklammerten Ausdrucks, oder irgendeiner Form einer ausschließenden Liste überein. (siehe „XBD specification, Chapter 7, Regular Expressions“).

2. Dient ein Zirkumflex (^) in pattern zur Verankerung des regulären Ausdrucks, stimmt es mit der Zeichenkette der Länge 0 unmittelbar hinter einem Zeilenumbruch in string überein, ungeachtet ob REG_NOBOL gesetzt ist oder nicht.

3. Dient das Dollar-Zeichen ($) in pattern zur Verankerung des regulären Ausdrucks, stimmt es mit der Zeichenkette der Länge 0 unmittelbar vor einem Zeilenumbruch in string überein, ungeachtet ob REG_NOTEOL gesetzt ist oder nicht.

Die Funktion regfree() gibt den gesamten von regcomp() angeforderten und mit preg verbundenen Speicherplatz wieder frei.

Folgende Konstanten sind als Fehler-Returnwerte definiert:

REG_NOMATCH	regexec() hat keine Übereinstimmung gefunden.
REG_BADPAT	Ungültiger regulärer Ausdruck.
REG_ECOLLATE	Ungültige Äquivalenzklasse referenziert.
REG_ECTYPE	Ungültige char-Klasse referenziert.
REG_EESCAPE	Abschließender \ in pattern.
REG_ESUBREG	Ungültige oder falsche Zahl in \digit.
REG_EBRACK	Unterschiedliche Anzahl von [ und ].
REG_ENOSYS	Die Funktion wird nicht unterstützt.
REG_EEPAREN	Unterschiedliche Anzahl von \( und \) bzw. ( und ).
REG_EBRACE	Unterschiedliche Anzahl von \/ und \}.
REG_BADBR	Ungültiger Inhalt von \{ \}: keine Zahl, zu große Zahl, mehr als zwei Zahlen, die erste Zahl ist größer als die zweite.
REG_ERANGE	Ungültiger Endpunkt in Bereichsausdruck.
REG_ESPACE	Außerhalb des Speicherbereichs.
REG_BADRPT	Vor ?, * oder + steht kein regulärer Ausdruck.
Extension
REG_ENOSYS	Die Funktion wird nicht unterstützt.
REG_INVARG	Ein Argument ist ungültig.
REG_EPATTERN	Leeres/Null Pattern übergeben (End)

Die Funktion regerror() bietet eine Abbildung der Fehlerrückgabewerte von regcomp() und regexec() auf einen abdruckbaren Text. Die generierte Zeichenfolge korrespondiert mit dem Wert des zuletzt zurückgegebenen Fehlerwertes eines Aufrufs von regcomp() oder regexec() mit dem Wert von preg. Ist errcode kein solcher Wert, ist der Inhalt der generierten Zeichenkette undefiniert.

Ist preg der NULL-Zeiger, aber errcode ein von einem vorangegangen Aufruf von regexec() oder regcomp() stammender Fehlercode, generiert regerror() ebenfalls einen zu diesem Fehlercode korrespondierenden Text. Dieser ist aber möglichweise nicht so detailliert.

Ist der Wert der Arguments errbuf_size verschieden von 0, speichert die Funktion regerror() die generierte Zeichenkette in den Puffer der Länge errbuf_size auf den das Argument errbuf zeigt. Passt die Zeichenkette inklusive der abschließenden NULL nicht in den Puffer, kürzt regerror() die Zeichenkette und schließt sie mit einer NULL ab.

Hat errbuf_size den Wert 0, ignoriert regerror() das Argument errbuf und gibt die Länge des Puffers mit, der benötigt würde um die generierte Zeichenkette aufzunehmen.

Enthält das an regexec() oder regfree() übergebene Argument preg nicht einen von regcomp() übersetzten regulären Ausdruck, ist das Ergebnis undefiniert. Nachdem preg an regfree() übergeben wurde, wird es nicht mehr als übersetzter regulärer Ausdruck behandelt.

Returnwert

für regcomp():

0

bei Erfolg.

Integer-Wert, der einen Fehler anzeigt, wie in regex.h beschrieben und der Inhalt von preg ist undefiniert.

für regexec():

0

bei Erfolg.

REG_NOMATCH

wenn keine Übereinstimmung gefunden wurde.         

REG_ENOSYS

wenn die Funktion nicht unterstützt wird.

für regerror(): 

Anzahl der Bytes, die benötigt werden um die generierte Zeichenkette aufzunehmen

bei Erfolg.

0

wenn die Funktion nicht unterstützt wird.

für regfree(): 

Die Funktion gibt keinen Wert zurück.

Fehler

regcomp() und regexec() schlagen fehl, wenn gilt:

Erweiterung

EINVAL

ungültiges Flag angegeben (End)

Fehler

Es sind keine Fehler definiert.

Hinweis

Mit

regerror(code,preg,(char *)NULL,(size_t)0)

kann eine Anwendung herauszufinden, wie groß ein Puffer sein muss, um die generierte Zeichenkette aufzunehmen. Anschließend kann sie mit malloc() einen entsprechend großen Speicherbereich anfordern und schließlich regerror() erneut aufrufen, um die Zeichenkette zu erhalten.

Alternativ kann auch ein statischer Puffer verwendet werden, der ausreichend groß ist, um die meisten Texte aufzunehmen, und nur dann mit malloc() einen größeren Puffer anfordern, wenn sich herausstellt, dass der statische Puffer zu klein ist.

Beispiel 1

#include <regex.h>
/*
* Prueft string gegen den erweiterten regulären Ausdruck in pattern
* und behandelt Fehler, falls keine Uebereinstimmung gefunden wird.
*
* gibt 1 zurueck bei Uebereinstimmung und 0 sonst.
*/
int
match(const char *string, char *pattern)
{
int status;
regex_t re;
if (regcomp(&re, pattern, REG_EXTENDED | REG_NOSUB) != 0) {
  return(0); /* report error */
  }
status = regexec(&re, string, (size_t) 0, NULL, 0);
regfree(&re);
if (status != 0) {
  return(0); /* report error */
  }
return(1);
}

Beispiel 2

Das folgende Beispiel zeigt, wie das Flag REG_NOTBOL mit regexec() genutzt werden kann um all Teilzeichenketten in einer Zeile zu finden, die mit einem vom Anwender übergeben pattern übereinstimmen.

Um das Beispiel zu vereinfachen, wird weitgehend auf Fehlerbehandlung verzichtet.

(void) regcom (&re, pattern, 0);
/* Dieser Aufruf von regexec() findet die erste Uebereinstimmung in der
* Zeile.
*/
error = regexec (&re, &buffer[0], 1, pm, 0);
while (error == 0) { /* Solange eine Uebereinstimmung gefunden wird */
/* Eine Teilzeichenkette wurde gefunden zwischen pm.rm_so und
* pm.rem_eo.
* Dieser Aufruf von regexec() findet die naechste
* Uebereinstimmung.
*/
error = regexec (&re, buffer + pm.rm_eo, 1, &pm, REG_NOTBOL);
}

Siehe auch

fnmatch(), glob(), regex.h, sys/types.h