Definition | #include <ftw.h> int ftw(const char *path, int (*fn) (const char *, const struct stat *ptr, int flag), int ndirs);
int ftw64(const char *path, int (*fn) (const char *, const struct stat64 *ptr, int flag), int ndirs); CRTE111A30 int ftwx(const char *path, int (*fn) (const char *, const struct statx *ptr, int flag), int ndirs);
int ftw64x(const char *path, int (*fn) (const char *, const struct stat64x *ptr, int flag), int ndirs); (Ende) |
Beschreibung | ftw() wandert rekursiv durch die Dateiverzeichnishierarchie hinab, die bei path beginnt. Für jedes Objekt der Hierarchie ruft ftw() die Funktion auf, auf die fn zeigt, und übergibt ihr einen Zeiger auf eine mit dem Nullbyte abgeschlossene Zeichenkette, die den Namen des Objekts enthält, einen Zeiger auf eine Struktur vom Typ struct stat (siehe auch sys/stat.h), die Informationen über das Objekt enthält (erlangt durch Aufruf der Funktion stat()), und eine ganze Zahl. Mögliche Werte für die ganze Zahl sind die in der Include-Datei ftw.h definierten Werte:
FTW_F
| für eine Datei | FTW_D
| für ein Dateiverzeichnis | FTW_DNR
| für ein Dateiverzeichnis, das nicht gelesen werden kann | FTW_NS
| für ein Objekt, für das stat() nicht erfolgreich ausgeführt werden konnte | Wenn die ganze Zahl gleich FTW_DNR ist, dann werden Unterbäume dieses Dateiverzeichnisses nicht bearbeitet. Wenn die ganze Zahl gleich FTW_NS ist, dann enthält die Struktur stat undefinierte Werte. Ein Beispiel für ein Objekt, für das FTW_NS an die Funktion, auf die fn zeigt, übergeben werden würde, ist eine Datei in einem Dateiverzeichnis mit Lese- aber ohne Sucherlaubnis. ftw() durchläuft zuerst ein Dateiverzeichnis, bevor einer seiner Nachfolger bearbeitet wird.
Die Baumdurchquerung dauert solange, bis der Baum vollständig durchsucht ist, ein Aufruf von fn einen Wert ungleich 0 zurückgibt oder in ftw() ein Fehler entdeckt wird. ndirs gibt die maximale Anzahl von Dateiverzeichnisströmen und/oder Dateideskriptoren an, die für die Verwendung durch ftw() bei der Bearbeitung des Dateibaums zur Verfügung stehen. Wenn ftw() zurückkehrt, dann schließt sie alle Dateiverzeichnisströme und Dateideskriptoren, die sie verwendet hat, ohne dabei diejenigen zu berücksichtigen, die durch die Funktion fn des Benutzers geöffnet wurden. Es besteht kein funktionaler Unterschied zwischen ftw() und ftw64(), außer dass ftw64() intern stat64() anstelle von stat() aufruft und einen Zeirer auf eine stat64-Struktur an fn übergibt. Die Funktionen mit dem Suffix x verhalten sich, wie die gleichnamigen Funktionen ohne Suffix, außer dass sie die entsprechende stat()-Funktion und stat-Struktur ebenfalls mit Suffix x referenzieren und daher auch über den 19.1.2038 03:14:07 Uhr UTC hinaus korrekt funktionieren. |
Returnwert | 0 | bei Erfolg. Der Dateibaum ist abgearbeitet. ftw() liefert das Ergebnis der Funktion zurück, auf die fn zeigt. |
| -1 | bei Fehler. errno wird gesetzt, um den Fehler anzuzeigen. Wenn die Funktion, auf die fn zeigt, einen Wert ungleich 0 zurückliefert, dann beendet ftw() die Abarbeitung des Dateibaums und liefert das Ergebnis der Funktion zurück, auf die fn zeigt. Entdeckt ftw() einen Fehler, wird -1 zurückgegeben (s. oben). Wenn die Funktion, auf die fn zeigt, einen Systemfehler erkennt, kann errno auf diesen gesetzt werden. |
Fehler | ftw(), ftw64(), ftwx() und ftw64x() schlagen fehl, wenn gilt:
|
| EACCES
| Das Durchsuchrecht für eine Komponente von path oder das Leserecht für path wird verweigert. |
| Erweiterung |
| EBADF
| Es wurde versucht, auf eine BS2000-Datei zuzugreifen. (Ende) |
| ENAMETOOLONG
|
|
| Die Länge von path überschreitet {PATH_MAX} oder eine Komponente des Pfadnamens ist länger als {NAME_MAX}. |
| ENOENT
| path zeigt auf den Namen einer Datei, die nicht existiert, oder auf die leere Zeichenkette. |
| ENOTDIR
| Eine Komponente von path ist kein Dateiverzeichnis. |
| Außerdem kann errno gesetzt sein, wenn stat() oder die Funktion, auf die fn() zeigt, errno setzt. |
Hinweise | Da ftw() rekursiv ist, kann diese Funktion mit einem Speicherfehler abbrechen, wenn sie auf sehr tiefe Dateibäume angewendet wird. ftw() verwendet malloc(), um während ihres Ablaufs dynamisch Speicherplatz zu reservieren. Wenn ftw() zum Abbruch gezwungen wird, wie zum Beispiel durch longjmp() oder siglongjmp(), ausgeführt von der Funktion, auf die fn zeigt, oder aus einer Signalbehandlungsroutine heraus, dann hat ftw() keine Möglichkeit, diesen Speicher freizugeben, so dass dieser ständig reserviert bleibt. Ein sicherer Weg, Unterbrechungen zu behandeln, ist der, sich das Auftreten der Unterbrechung zu merken und die Funktion, auf die fn zeigt, zu veranlassen, bei ihrem nächsten Aufruf einen Wert ungleich 0 zurückzuliefern.
ftw() wird nur für POSIX-Dateien ausgeführt.
|
Siehe auch | longjmp(), malloc(), nftw(), siglongjmp(), stat(), ftw.h.
|
