directory(3C) directory(3C)
NAME
directory: opendir, readdir, telldir, seekdir, rewinddir, closedir,
readdir64 - Verzeichnisoperationen
SYNTAX
#include <sys/types.h>
#include <dirent.h>
DIR *opendir(const char *filename);
struct dirent *readdir(DIR *dirp);
long int telldir(DIR *dirp);
void seekdir(DIR *dirp, long int loc);
void rewinddir(DIR *dirp);
int closedir(DIR *dirp);
struct dirent64 *readdir64(DIR *dirp);
BESCHREIBUNG
opendir() öffnet ein Verzeichnis filename und ordnet ihm eine DIR-
Struktur zu. opendir() gibt einen Zeiger auf die DIR-Struktur zurück,
der zur Identifizierung des Verzeichnisses in den nachfolgenden Opera-
tionen verwendet wird. Der Nullzeiger wird zurückgegeben, wenn auf
filename nicht zugegriffen werden kann, oder wenn filename kein Ver-
zeichnis ist, oder wenn nicht genügend Speicherplatz zur Aufnahme
einer DIR-Struktur bzw. eines Puffers für die Verzeichniseinträge mit
malloc(3C) zur Verfügung gestellt werden kann. Bei einem erfolgreichen
Aufruf einer dieser exec-Funktionen werden alle Verzeichnis-Streams,
die im aufrufenden Prozeß geöffnet sind, geschlossen.
Der in der Include-Datei <dirent.h> definierte Typ DIR steht für einen
"directory stream" (Verzeichnis-Stream), bei dem es sich um eine sor-
tierte Folge aller Verzeichniseinträge in einem bestimmten Verzeichnis
handelt. Verzeichniseinträge stehen für Dateien; Dateien können asyn-
chron zur readdir()-Operation aus einem Verzeichnis entfernt oder
einem Verzeichnis hinzugefügt werden.
Die Funktion readdir() gibt einen Zeiger auf eine Struktur zurück, die
für den Verzeichniseintrag an der aktuellen Position in dem Verzeich-
nis-Stream steht, der über das Argument dirp angegeben ist, und stellt
den Verzeichnis-Stream auf den nächsten Eintrag. Wenn das Ende des
Verzeichnis-Streams erreicht ist, wird ein Nullzeiger ausgegeben. Die
in der Include-Datei <dirent.h> definierte Struktur dirent beschreibt
einen Verzeichniseintrag.
Wenn die Einträge "." oder ".." vorhanden sind, wird ein Eintrag für
"." und ein Eintrag für ".." zurückgegeben. Andernfalls werden diese
Einträge nicht zurückgegeben.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
directory(3C) directory(3C)
Der von readdir() zurückgegebene Zeiger verweist auf Daten, die von
einem anderen Aufruf von readdir() im selben Verzeichnis-Stream über-
schrieben werden können. Diese Daten werden nicht von einem erneuten
readdir()-Aufruf in einem anderen Verzeichnis-Stream überschrieben.
Wenn eine Datei nach dem letzten Aufruf von opendir() oder rewinddir()
aus einem Verzeichnis entfernt oder einem Verzeichnis hinzugefügt
wird, ist nicht definiert, ob ein nachfolgender Aufruf von readdir()
einen Eintrag für diese Datei zurückgibt.
Die Funktion readdir() kann mehrere Verzeichniseinträge pro Leseopera-
tion zwischenspeichern; jedesmal, wenn das Verzeichnis tatsächlich
gelesen wird, markiert readdir() das Feld statime des Verzeichnisses
zur Aktualisierung.
Nach einem Aufruf von fork() kann entweder der Vater- oder der Sohn-
prozeß (jedoch nicht beide) die Verarbeitung des Verzeichnis-Streams
mit readdir(), rewinddir() oder seekdir() fortsetzen. Wenn diese Funk-
tionen sowohl vom Vater- als auch vom Sohnprozeß verwendet werden, ist
das Ergebnis undefiniert.
Wenn der Eintrag einen symbolischen Link angibt, ist der Wert der Kom-
ponente dino nicht angegeben.
Die Funktion telldir() erhält die aktuelle Position, die dem von dirp
angegebenen Verzeichnis-Stream zugeordnet ist.
Wenn es sich bei der letzten Operation im Verzeichnis-Stream um ein
seekdir() handelte, entspricht die von telldir() zurückgegebene Ver-
zeichnisposition der Position, die als loc-Argument für seekdir()
geliefert wurde.
seekdir() setzt die Position der nächsten readdir()-Operation. Die
neue Position greift auf die Position zurück, die mit dem Verzeich-
nis-Stream zur Ausführungszeit der telldir()-Operation, die loc lie-
ferte, verbunden war. Wenn der Wert von loc nicht aus einem früheren
Aufruf von telldir() erhalten wurde, oder wenn ein Aufruf von
rewinddir() zwischen telldir() und seekdir() ausgegeben wurde, sind
die Ergebnisse der nachfolgenden readdir()-Aufrufe nicht definiert.
rewinddir() setzt die Position des angegebenen Verzeichnisses auf den
Anfang des Verzeichnisses zurück. Es veranlaßt den Verzeichnis-Stream,
sich ebenfalls auf den augenblicklichen Status des mit ihm verbundenen
Verzeichnisses zu beziehen, so wie opendir() es täte.
Bei den Funktionen readdir() und rewinddir() kann nach einem Aufruf
der Funktion fork() entweder der Vater- oder der Sohnprozeß (aber
nicht beide) den Verzeichnis-Stream unter Verwendung von readdir(),
rewinddir() oder seekdir() fortführen. Wenn beide Prozesse diese Funk-
tionen verwenden, ist das Verhalten undefiniert.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
directory(3C) directory(3C)
closedir() schließt das angegebene Verzeichnis und gibt die DIR-Struk-
tur frei.
Es besteht kein funktionaler Unterschied zwischen readdir() und
readdir64(), außer bei der Interpretation von struct dirent64 [siehe
dirent(4)].
RÜCKGABEWERT
Bei erfolgreicher Ausführung gibt die Funktion opendir() einen Zeiger
auf ein Objekt vom Typ DIR zurück. Andernfalls wird ein Nullzeiger
zurückgegeben und errno zur Anzeige des Fehlers gesetzt.
Bei erfolgreicher Ausführung gibt die Funktion readdir() einen Zeiger
auf ein Objekt vom Typ struct dirent zurück. Bei einem Fehler wird ein
Nullzeiger zurückgegeben und errno zur Anzeige des Fehlers gesetzt.
Wenn das Ende des Verzeichnisses erreicht ist, wird ein Nullzeiger
zurückgegeben und errno bleibt unverändert.
FEHLER
Die folgenden Beschreibungen der Fehlercodes sind funktionsspezifisch.
Eine allgemeingültige Beschreibung finden Sie in introprm2(2) bzw. in
errno(5).
Folgende Fehler können von diesen Operationen verursacht werden:
ENOTDIR Eine Komponente von filename ist kein Verzeichnis.
EACCES Eine Komponente von filename verweigert die Suchberech-
tigung.
EACCES Die Leseberechtigung für das spezifizierte Verzeichnis
wird verweigert.
EMFILE Die Maximalanzahl von Dateideskriptoren ist bereits
geöffnet.
ENFILE Die Systemdateitabelle ist voll.
EFAULT filename weist über den zugewiesenen Adreßraum hinaus.
ELOOP Während der Auflösung von filename wurden zu viele sym-
bolische Links angetroffen.
ENAMETOOLONG Die Länge des Arguments filename ist größer als
PATHMAX, oder die Länge einer Komponente von filename
überschreitet NAMEMAX.
ENAMETOOLONG Die Auflösung des Pfadnamens eines symbolischen Links
hat ein Zwischenergebnis erzeugt, dessen Länge PATHMAX
überschreitet.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
directory(3C) directory(3C)
ENOENT filename zeigt auf den Namen einer Datei, die nicht exi-
stiert, oder auf eine leere Zeichenkette.
readdir() liefert NULL bei einem Fehler und setzt errno auf einen der
folgenden Werte:
ENOENT Der aktuelle Schreib-/Lesezeiger für das Verzeichnis
befindet sich nicht auf einem gültigen Eintrag.
EBADF Der dem Verzeichnis-Stream zugeordnete Dateideskriptor
ist nicht mehr gültig. Dieser Fehler entsteht, wenn der
Verzeichnis-Stream geschlossen wurde.
EOVERFLOW Einer der Werte in der zurückzugebenden Struktur kann
nicht korrekt dargestellt werden.
telldir(), seekdir() und closedir() liefern -1 bei einem Fehler und
setzen errno auf den folgenden Wert:
EBADF Der dem Verzeichnis zugeordnete Dateideskriptor ist
nicht mehr gültig. Dieser Fehler entsteht, wenn das Ver-
zeichnis geschlossen wurde.
BEISPIELE
Es folgt ein Beispielprogramm, das die Dateinamen aller Dateien im
aktuellen Verzeichnis ausgibt.
#include <stdio.h>
#include <dirent.h>
main()
{
DIR *dirp;
struct dirent *direntp;
dirp = opendir( "." );
while ( (direntp = readdir( dirp )) != NULL )
(void)printf( "%s\n", direntp->dname );
closedir( dirp );
return (0);
}
HINWEISE
Da rewinddir() als Makro realisiert ist, gibt es keine verwendbare
Funktionsadresse.
SIEHE AUCH
getdents(2), lstat(2), symlink(2), dirent(4), limits(4), lfs(5),
types(5).
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98