ftw(3C) ftw(3C)
NAME
ftw, nftw, ftw64, nftw64 - Dateibaum durchlaufen
SYNTAX
#include <ftw.h>
int ftw(const char *path,
int (*fn) (const char *, const struct stat *ptr, int flag),
int ndirs);
int nftw(const char *path,
int (*fn) (const char *, const struct stat *, int, struct FTW *),
int depth, int flags);
int ftw64(const char *path,
int (*fn) (const char *, const struct stat64 *, int), int ndirs);
int nftw64(const char *path,
int (*fn) (const char *, const struct stat64 *, int, struct FTW *),
int depth, int flags);
BESCHREIBUNG
ftw() durchsucht die Verzeichnishierarchie, die mit path beginnt,
rekursiv. Für jedes Objekt in der Hierarchie ruft ftw() die benutzer-
definierte Funktion fn auf und übergibt ihr einen Zeiger auf eine Zei-
chenkette mit Endenull, die den Namen des Objekts, einen Zeiger auf
eine stat-Struktur [siehe stat(2)] mit Informationen über das Objekt
sowie eine ganze Zahl enthält. Mögliche Werte der ganzen Zahl, die in
der Include-Datei ftw.h definiert sind:
FTWF Das Objekt ist eine Datei.
FTWD Das Objekt ist ein Verzeichnis.
FTWDNR Das Objekt ist ein Verzeichnis, das nicht gelesen werden
kann. Verzeichnisse und Dateien unterhalb des Verzeich-
nisses (Nachfolger) werden nicht verarbeitet.
FTWSL Ein symbolischer Link (siehe hierzu auch FTWNS unten).
FTWNS Ein Objekt, aber kein symbolischer Link, für das stat()
nicht erfolgreich ausgeführt werden konnte. Wenn das
Objekt ein symbolischer Link und stat() fehlgeschlagen
ist, ist nicht definiert, ob ftw() den Wert FTWSL oder
FTWNS an die benutzerdefinierte Funktion übergibt.
Ist die Ganzzahl FTWDNR, werden Nachfolger dieses Verzeichnisses
nicht verarbeitet. Ist die Ganzzahl FTWNS, enthält die Struktur stat
undefinierte Werte. Eine Datei in einem Verzeichnis, das zwar gelesen,
nicht jedoch ausgeführt (durchsucht) werden darf, wäre zum Beispiel
ein Objekt, bei dem FTWNS an die Funktion, auf die fn zeigt, überge-
ben würde.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
ftw(3C) ftw(3C)
Die Funktion ftw() durchläuft zunächst ein Verzeichnis, bevor die
zugehörigen Unterverzeichnisse durchsucht werden.
Die Funktion ftw() verwendet höchstens einen Dateideskriptor für jede
Ebene des Dateibaums.
Das Argument ndirs sollte im Bereich von 1 bis OPENMAX liegen.
Das rekursive Durchlaufen des Baums wird solange fortgesetzt, bis das
Ende des Baums erreicht ist, ein Aufrufen von fn einen Wert ungleich 0
zurückgibt, oder ein Fehler außer EACCES innerhalb von ftw() gefunden
wird.
Das Argument ndirs gibt die maximale Anzahl der Verzeichnis-Streams
und/oder Dateideskriptoren an, die für ftw() beim Durchlaufen des
Baums verfügbar ist. Bei der Rückkehr werden alle von ftw() verwende-
ten Verzeichnis-Streams und Dateideskriptoren geschlossen, ausgenommen
derjenigen, die von der anwendungsspezifischen fn-Funktion geöffnet
wurden.
Die Funktion nftw() ist ähnlich wie ftw(), nur daß sie ein weiteres
Argument, flags, erwartet, bei dem es sich um eine bitweise OR-Ver-
knüpfung mit keinem oder mehreren der folgenden Flags handelt:
FTWCHDIR Ist dieses Flag gesetzt, wechselt nftw() das aktuelle
Arbeitsverzeichnis und ruft die einzelnen Verzeichnisse
auf, aus denen Dateien gemeldet werden. Andernfalls
wechselt nftw() nicht das aktuelle Arbeitsverzeichnis.
FTWDEPTH Ist dieses Flag gesetzt, meldet nftw() alle Dateien in
einem Verzeichnis bevor das Verzeichnis selbst genannt
wird. Andernfalls meldet nftw() zuerst ein Verzeichnis
und dann erst die Dateien in diesem Verzeichnis.
FTWMOUNT Ist dieses Flag gesetzt, meldet nftw() nur Dateien in
dem Dateisystem, auf das path verweist. Andernfalls mel-
det nftw() alle Dateien, die während des Durchlaufens
gefunden werden.
FTWNONFS Ist dieses Flag gesetzt, läuft nftw() nicht in Verzeich-
nisse, die mit NFS eingehängt worden sind. Wird nftw()
mit diesem Flag in einem NFS-Verzeichnis gestartet,
beendet es sich ohne Aktion.
FTWPHYS Ist dieses Flag gesetzt, führt nftw() ein physisches
Durchlaufen aus, ohne symbolischen Links zu folgen.
Andernfalls folgt nftw() symbolischen Links anstatt sie
zu melden. Dieselbe Datei wird in diesem Fall nicht
zweimal gemeldet.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
ftw(3C) ftw(3C)
Die Funktion nftw() ruft fn mit vier Argumenten zu jeder Datei und
jedem Verzeichnis auf. Das erste Argument ist der Pfadname des
Objekts, das zweite ist ein Zeiger auf den stat-Puffer, das dritte ist
eine Ganzzahl, die zusätzliche Informationen liefert, und das vierte
ist ein struct FTW, das die folgenden Komponenten enthält:
int base;
int level;
base ist der Offset innerhalb des Pfadnamens für den Namen des
Objekts. level gibt an, welche Hierarchieebenen bereits durchlaufen
wurden und welche noch durchlaufen werden müssen. Dabei hat die unter-
ste Ebene den Wert 0.
Die Werte des dritten Arguments haben folgende Bedeutung:
FTWF Das Objekt ist eine Datei.
FTWD Das Objekt ist ein Verzeichnis.
FTWDP Das Objekt ist ein Verzeichnis, Unterverzeichnisse wur-
den bereits durchlaufen. (Diese Bedingung tritt nur dann
auf, wenn das FTWDEPTH-Flag in flags enthalten ist.)
FTWSL Das Objekt ist ein symbolischer Link (Diese Bedingung
tritt nur dann auf, wenn das FTWPHYS-Flag in flags ent-
halten ist.)
FTWSLN Das Objekt ist ein symbolischer Link, der auf eine nicht
vorhandene Datei zeigt. (Diese Bedingung tritt nur dann
auf, wenn das FTWPHYS-Flag nicht in flags enthalten
ist.)
FTWDNR Das Objekt ist ein Verzeichnis, das nicht gelesen werden
kann. fn wird für keinen seiner Nachfolger aufgerufen.
FTWNS stat() kann das Objekt aufgrund unzureichender Zugriffs-
rechte nicht bearbeiten. Der an fn übergebene stat-Puf-
fer ist undefiniert. Wenn stat() aus anderen Gründen
scheitert, wird das als ein Fehler betrachtet, und
nftw() gibt -1 zurück.
Das Argument depth setzt die maximale Anzahl der Dateideskriptoren,
die von nftw() beim Durchlaufen eines Dateibaums verwendet werden. Für
jede Verzeichnisebene wird höchstens ein Dateideskriptor verwendet.
Es besteht kein funktionaler Unterschied zwischen ftw()/nftw() und
ftw64()/nftw64(), außer bei der Interpretation von stat/stat64 [siehe
stat(5)].
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
ftw(3C) ftw(3C)
RÜCKGABEWERT
Wenn das Ende des Baums erreicht ist gibt ftw() den Wert 0 zurück.
Wenn die Funktion, auf die fn zeigt, einen Wert ungleich Null zurück-
gibt, stoppt ftw() die Verarbeitung des Baums und gibt den Wert
zurück, der von der Funktion ausgegeben wurde, auf die fn zeigt. Wenn
ftw() einen Fehler findet, wird -1 zurückgegeben und errno gesetzt, um
den Fehler anzuzeigen.
Wenn ftw() einen anderen Fehler als EACCES (siehe FTWDNR und FTWNS
oben) findet, wird -1 zurückgegeben und errno gesetzt, um den Fehler
anzuzeigen. Die externe Variable errno kann jeden Fehlerwert enthal-
ten, der beim Öffnen eines Verzeichnisses oder bei der Ausführung
einer der stat-Funktionen für ein Verzeichnis oder eine Datei möglich
ist.
Dasselbe gilt für die Funktion nftw().
FEHLER
Die folgenden Beschreibungen der Fehlercodes sind funktionsspezifisch.
Eine allgemeingültige Beschreibung finden Sie in introprm2(2) bzw. in
errno(5).
Die Funktionen ftw() und nftw() schlagen bei einer der folgenden
Bedingungen fehl:
ENAMETOOLONG Die Länge von path überschreitet PATHMAX, oder eine
Komponente des Pfadnamens ist länger als NAMEMAX.
ENOENT Eine Komponente von path gibt keine vorhandene Datei an,
oder path ist eine leere Zeichenkette.
ENOTDIR Eine Komponente von path ist kein Verzeichnis.
Die Funktion ftw() schlägt bei folgender Bedingung fehl:
EACCES Für eine Komponente von path wird die Suchberechtigung
verweigert oder für path wird die Leseberechtigung ver-
weigert.
Die Funktion nftw() schlägt bei folgender Bedingung fehl:
EACCES Für eine Komponente von path wird die Suchberechtigung
verweigert, für path wird die Leseberechtigung verwei-
gert oder fn gibt -1 zurück und setzt errno nicht
zurück.
Die Funktionen ftw() und nftw() können bei folgenden Bedingungen fehl-
schlagen:
ELOOP Während der Auflösung von path wurden zu viele symboli-
sche Links angetroffen.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
ftw(3C) ftw(3C)
ENAMETOOLONG Die Auflösung des Pfadnamens eines symbolischen Links
hat ein Zwischenergebnis erzeugt, dessen Länge PATHMAX
überschreitet.
Die Funktion ftw() kann bei folgender Bedingung fehlschlagen:
EINVAL Der Wert des Arguments ndirs ist ungültig.
Die Funktion nftw() kann bei folgender Bedingung fehlschlagen:
EMFILE OPENMAX Dateideskriptoren sind derzeit im aufrufenden
Prozeß geöffnet.
ENFILE Zu viele Dateien sind zur Zeit im System geöffnet.
Wenn die Funktion, auf die fn zeigt, Systemfehler findet, wird errno
unter Umständen entsprechend gesetzt.
HINWEISE
Da ftw() rekursiv ist, besteht die Möglichkeit, daß es mit einem Spei-
cherfehler abbricht, wenn es auf Dateibäume mit zu vielen Hierarchie-
ebenen angewendet wird. ftw() verwendet malloc(3C) zur Zuweisung von
dynamischem Speicher während der Ausführung. Wenn ftw() abgebrochen
wird, wie z. B. durch Ausführen von longjmp() durch fn oder durch eine
Unterbrechungsroutine, hat ftw() keine Möglichkeit, diesen Speicher
freizugeben, so daß der Speicher ständig belegt bleibt. Unterbrechun-
gen können bearbeitet werden, indem veranlaßt wird, daß fn beim näch-
sten Aufrufen einen Wert ungleich Null zurückgibt.
SIEHE AUCH
stat(2), malloc(3C), ftw(5), lfs(5), stat(5).
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98