glob(3C) glob(3C)
NAME
glob, globfree - Generierung von Pfadnamen entsprechend einem Muster
SYNTAX
#include <glob.h>
int glob(const char *pattern, int flags, int (*errfunc)
(const char *epath, int eerrno), globt *pglob);
void globfree(globt *pglob);
BESCHREIBUNG
Die Funktion glob() ist ein Pfadnamen-Generator, der die Regeln der
Mustervergleichssyntax mit optionaler Unterstützung von Mustern, die
für die Dateinamen-Expansion verwendet werden, implementiert.
Der Strukturtyp globt ist in der Include-Datei glob.h definiert. Er
enthält mindestens die folgenden Komponenten:
_____________________________________________________________________
| Komponententyp | Komponentenname | Beschreibung |
|________________|__________________|________________________________|
| sizet | glpathc | Anzahl der Pfade, die zu |
| | | pattern passen |
|________________|__________________|________________________________|
| char ** | glpathv | Zeiger auf eine Liste passen- |
| | | der Pfadnamen |
|________________|__________________|________________________________|
| sizet | gloffs | zu reservierende Slots am |
| | | Anfang von glpathv |
|________________|__________________|________________________________|
Das Argument pattern ist ein Zeiger auf ein Pfadnamen-Muster, das
expandiert werden soll. Die Funktion glob() vergleicht alle Pfadnamen,
auf die sie zugreifen kann, mit diesem Muster und gibt eine Liste
aller gefundenen passenden Pfadnamen aus. Für den Zugriff auf den
Pfadnamen benötigt glob() die Durchlaufberechtigung für alle Komponen-
ten des Pfades (außer der letzten Komponente) und die Leseberechtigung
für alle Dateiverzeichnisse aller Dateinamens-Komponenten der Muster,
die eines der folgenden Sonderzeichen enthalten: *, ?, [.
Die Funktion glob() legt die Anzahl der gefundenen Pfadnamen in
pglob->glpathc und einen Zeiger auf eine Liste mit Zeigern auf die
Pfadnamen in pglob->glpathv ab. Die Pfadnamen sind so sortiert, wie
es durch die aktuelle Einstellung der Kategorie LCCOLLATE definiert
ist. Der erste Zeiger nach dem letzten Pfadnamen ist ein Nullzeiger.
Wenn das Muster auf keine Pfadnamen paßt, wird die zurückgegebene
Anzahl der gefundenen Pfade auf Null gesetzt. Der Inhalt von
pglob->glpathv ist von der Implementation abhängig.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
glob(3C) glob(3C)
Es liegt in der Verantwortung des Aufrufers, die Struktur zu erstel-
len, auf die pglob zeigt. Die Funktion glob() weist weiteren Platz je
nach Bedarf zu (dies gilt auch für den Speicher, auf den glpathv
zeigt). Die Funktion globfree() gibt den Speicherplatz frei, der pglob
in einem vorherigen Aufruf von glob() zugewiesen wurde.
Mit dem Argument flags wird das Verhalten von glob() gesteuert. Der
Wert von flags ist eine bitweise, inklusive ODER-Verknüpfung keiner
oder mehrerer der folgenden Konstanten, die in der Include-Datei
<glob.h> definiert sind:
GLOBAPPEND
Generierte Pfadnamen an die Pfadnamen eines vorherigen Aufrufs
von glob() anhängen.
GLOBDOOFFS
Verwendung von pglob->gloffs. Wenn dieses Flag gesetzt ist, wird
mit pglob->gloffs angegeben, wie viele Nullzeiger am Anfang von
pglob->glpathv eingefügt werden sollen. pglob->glpathv zeigt
also auf pglob->gloffs Nullzeiger, gefolgt von pglob->glpathc
Pfadnamen-Zeiger, gefolgt von einem Nullzeiger.
GLOBERR
Rückkehr von glob(), wenn ein Dateiverzeichnis gefunden wird, das
nicht geöffnet oder gelesen werden kann. Normalerweise setzt
glob() die Suche nach Entsprechungen fort.
GLOBMARK
Ein Schrägstrich wird an jeden Pfadnamen angehängt, der einem zum
Muster passenden Dateiverzeichnis entspricht.
GLOBNOCHECK
Unterstützung der Muster für die Dateinamen-Expansion. Wenn
pattern keinem Pfadnamen entspricht, gibt glob() eine Liste
zurück, die nur pattern enthält. Die Anzahl der gefundenen Pfad-
namen beträgt 1.
GLOBNOESCAPE
Gegenschrägstrich-Entwertung deaktivieren.
GLOBNOSORT
Normalerweise sortiert glob() die gefundenen Pfadnamen entspre-
chend der aktuellen Einstellung der Kategorie LCCOLLATE. Wenn
dieses Flag verwendet wird, ist die Reihenfolge der zurückgegebe-
nen Pfadnamen unbestimmt.
Mit dem Flag GLOBAPPEND kann eine neue Menge mit Pfadnamen an die in
einem vorherigen Aufruf von glob() gefundenen Pfadnamen angehängt wer-
den. Die folgenden Regeln gelten, wenn zwei oder mehr Aufrufe von
glob() mit dem gleichen Wert für pglob und ohne zwischenzeitliche Auf-
rufe von globfree() durchgeführt werden:
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
glob(3C) glob(3C)
1. Im ersten Aufruf darf GLOBAPPEND nicht gesetzt werden. Bei allen
weiteren Aufrufen muß das Flag gesetzt sein.
2. GLOBDOOFFS muß entweder in allen Aufrufen gesetzt oder darf in
keinem Aufruf gesetzt sein.
3. Nach dem zweiten Aufruf zeigt pglob->glpathv auf eine Liste mit
dem folgenden Inhalt:
- Keine oder mehrere Nullzeiger, je nach GLOBDOOFFS und
pglob->gloffs.
- Zeiger auf die Pfadnamen, die vor dem Aufruf in der Liste
pglob->glpathv waren (Reihenfolge wie zuvor).
- Zeiger auf die neuen Pfadnamen, die vom zweiten Aufruf generiert
wurden (in der angegebenen Reihenfolge).
4. Die in pglob->glpathc zurückgegebene Anzahl ist die Gesamtzahl der
Pfadnamen für beide Aufrufe.
5. Die Anwendung kann beliebige Felder nach einem Aufruf von glob()
verändern. In diesem Fall müssen die Felder vor einem weiteren Auf-
ruf von globfree() oder glob() mit dem Flag GLOBAPPEND, für den
der gleiche Wert für pglob verwendet wird, auf die ursprünglichen
Werte zurückgesetzt werden.
Wenn bei der Suche ein Dateiverzeichnis gefunden wird, das nicht
geöffnet oder gelesen werden kann, und wenn errfunc kein Nullzeiger
ist, ruft glob() (*errfunc()) mit zwei Argumenten auf:
- Das Argument epath ist ein Zeiger auf den Pfad, bei dem das Problem
auftrat.
- Das Argument eerrno ist der entsprechende Wert, der von der Funk-
tion opendir(), readdir() bzw. stat() gesetzt wird. (Andere Werte
können für andere Fehler verwendet werden, die für diese Funktionen
nicht explizit dokumentiert sind).
Die folgenden Konstanten sind als Fehlerwerte für glob() definiert:
GLOBABORTED
Der Durchlauf wurde angehalten, weil GLOBERR gesetzt war bzw.
(*errfunc()) einen Wert ungleich Null zurückgegeben hat.
GLOBBADPAT
Ein ungültiges Muster wurde angegeben.
GLOBNOMATCH
Das Muster entspricht keinem Pfadnamen. GLOBNOCHECK war in flags
nicht gesetzt.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
glob(3C) glob(3C)
GLOBNOSPACE
Ein Versuch der Speicherzuweisung schlug fehl.
Wenn (*errfunc()) aufgerufen wird und einen Wert ungleich Null zurück-
gibt bzw. wenn das Flag GLOBERR in flags gesetzt ist, hält glob() den
Durchlauf an und gibt GLOBABORTED zurück, nachdem glpathc und
glpathv in pglob gesetzt wurden, um die bereits gelesenen Pfade fest-
zuhalten. Wenn GLOBERR nicht gesetzt ist und errfunc ein Nullzeiger
ist oder (*errfunc()) Null zurückgibt, wird der Fehler ignoriert.
Diese Funktion steht Dienstprogrammen nicht zur Verfügung, um die
Pfadnamen-Expansion für die Argumente auszuführen, da diese Operation
von der Shell ausgeführt wird und von den Dienstprogrammen explizit
nicht erwartet wird, daß sie diesen Vorgang wiederholen. Diese Funk-
tion steht jedoch für Anwendungen zur Verfügung, die Pfadnamen-
Expansionen für Zeichenketten durchführen müssen, die aus anderen
Quellen stammen (z. B. ein vom Benutzer eingegebenes oder ein von
einer Datei eingelesenes Muster).
Wenn ein Dienstprogramm feststellen muß, ob ein Pfadname einem
bestimmten Muster entspricht, kann es die Funktion fnmatch() verwen-
den.
Beachten Sie, daß glpathc und glpathv auch dann von Bedeutung sind,
wenn glob() fehlschlägt. Dadurch kann glob() bei einem Fehler Teiler-
gebnisse liefern. Wenn jedoch glpathc gleich Null ist, ist glpathv
nicht definiert, auch wenn glob() keinen Fehler zurückgibt.
Die Option GLOBNOCHECK kann verwendet werden, wenn eine Anwendung
einen Pfadnamen bei Angabe von Platzhaltern expandieren will, das
Muster aber sonst einfach als Zeichenkette behandeln will. Das Dienst-
programm sh kann dies zum Beispiel für Optionen nutzen.
Die Pfadnamen, die von einem folgenden Aufruf mit GLOBAPPEND neu
generiert werden, werden nicht zusammen mit den anderen Pfadnamen sor-
tiert. Dies entspricht der Bearbeitung der Pfadnamen-Expansion durch
die Shell, wenn in einer Kommandozeile mehrere Expansionen ausgeführt
werden.
Anwendungen, die die Expansion von Tilden und Parametern benötigen,
sollten die Funktion wordexp() verwenden.
ERGEBNIS
Bei erfolgreicher Beendigung gibt glob() Null zurück. Das Argument
pglob->glpathc gibt die Anzahl der gefundenen Pfadnamen zurück. Das
Argument pglob->glpathv enthält einen Zeiger auf eine mit Null abge-
schlossene Liste gefundener und sortierter Pfadnamen. Wenn
pglob->glpathc jedoch Null ist, ist der Inhalt von pglob->glpathv
nicht definiert.
Die Funktion globfree() gibt keinen Wert zurück.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
glob(3C) glob(3C)
Wenn glob() wegen eines Fehlers beendet wird, wird eine der Konstanten
ungleich Null, die in der Datei glob.h definiert sind, zurückgegeben.
Die Argumente pglob->glpathc und pglob->glpathv entsprechen noch der
Definition.
BEISPIELE
Eine Verwendungsmöglichkeit für das Flag GLOBDOOFFS ist die Verwen-
dung durch eine Anwendung, die eine Liste mit Argumenten für die Funk-
tionen execv(), execve() bzw. execvp() erstellt hat. Wenn eine Anwen-
dung zum Beispiel die Entsprechung von
ls -l *.c
durchführen will, aber aus bestimmten Gründen
system("ls -l *.c")
nicht möglich ist, kann die Anwendung mit den folgenden Angaben etwa
zum gleichen Ergebnis kommen:
globbuf.gloffs = 2;
glob ("*.c", GLOBDOOFFS, NULL, &globbuf);
globbuf.glpathv [0] = "ls";
globbuf.glpathv[1] = "-l";
execvp ("ls", &globbuf.glpathv[0]);
Das gleiche Beispiel
ls -l *.c *.h
kann wie folgt mit GLOBAPPEND zum gleichen Ergebnis führen:
globbuf.gloffs = 2;
glob ("*.c", GLOBDOOFFS, NULL, &globbuf);
glob ("*.c", GLOBDOOFFS|GLOBAPPEND, NULL, &globbuf);
SIEHE AUCH
execv(2), stat(2), fnmatch(3C), opendir(3C), readdir(3C), wordexp(3C),
glob(5).
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98