DIRECTORY(3) BSD Programmer's Manual DIRECTORY(3)NAME
opendir, readdir, readdir_r, telldir, seekdir, rewinddir, closedir, dirfd
- directory operations
SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
DIR *
opendir(const char *filename);
struct dirent *
readdir(DIR *dirp);
int
readdir_r(DIR *dirp, struct dirent *buf, struct dirent **retval);
long
telldir(const DIR *dirp);
void
seekdir(DIR *dirp, long loc);
void
rewinddir(DIR *dirp);
int
closedir(DIR *dirp);
int
dirfd(DIR *dirp);
DESCRIPTION
The opendir() function opens the directory named by filename, associates
a directory stream with it and returns a pointer to be used to identify
the directory stream in subsequent operations.
The readdir() function returns a pointer to the next directory entry. A
directory entry has the form:
struct dirent {
u_int32_t d_fileno;
u_int16_t d_reclen;
u_int8_t d_type;
u_int8_t d_namlen;
char d_name[NAME_MAX + 1];
};
The nul-terminated name of the entry is contained in the d_name field.
The readdir_r() function is a reentrant version of the traditional
readdir() call. If it has not reached the end of the directory, it uses
the supplied pointer buf to hold the return value, and then sets retval
to point to this structure. The supplied buffer must have room for at
least NAME_MAX bytes of file name in its d_name field. (In BSD/OS, any
dirent structure has sufficient space automatically.)
The telldir() function returns the current location associated with the
named directory stream.
The seekdir() function sets the position of the next readdir() operation
on the directory stream. The new position reverts to the one associated
with the directory stream when the telldir() operation was performed.
Values returned by telldir() are good only for the lifetime of the DIR
pointer, dirp, from which they are derived. If the directory is closed
and then reopened, the telldir() value may be invalidated due to unde-
tected directory compaction. It is safe to use a previous telldir() val-
ue immediately after a call to opendir() and before any calls to
readdir().
The rewinddir() function resets the position of the named directory
stream to the beginning of the directory.
The closedir() function closes the named directory stream and frees the
structure associated with the dirp pointer.
The dirfd() macro returns the integer file descriptor associated with the
named directory stream; see open(2). You may only call dirfd() on a
valid directory stream; otherwise, the result is undefined.
Here is some sample code which searches the current directory for an en-
try ``name'':
len = strlen(name);
dirp = opendir(".");
while ((dp = readdir(dirp)) != NULL)
if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
(void)closedir(dirp);
return FOUND;
}
(void)closedir(dirp);
return NOT_FOUND;
RETURN VALUES
If opendir() succeeds, it returns a pointer to a valid DIR structure.
Otherwise, it returns NULL and sets the global variable errno to indicate
the error.
If readdir() succeeds, it returns a pointer to a valid dirent structure.
If readdir() reaches the end of the directory, it returns NULL and pre-
serves the value of errno. Otherwise, it returns NULL and sets errno to
indicate the error.
If readdir_r() succeeds, it returns 0. If readdir_r() reaches the end of
the directory, it sets *retval to NULL and returns 0. Otherwise,
readdir_r() returns an error number to indicate the error.
If telldir() succeeds, it returns a value that may later be provided to
seekdir() to restore the current position in the directory; otherwise, it
returns -1 and sets errno to indicate the error.
If closedir() succeeds, it returns 0; otherwise, it returns -1 and sets
errno to indicate the error.
ERRORSOpendir() will fail if:
[EACCES] Search permission is denied for a component of the path
prefix.
[EACCES] Read permission is denied for the directory.
[EMFILE] The process has already reached its limit for open file de-
scriptors (see intro(2) and getrlimit(2)).
[ENAMETOOLONG]
A pathname component was longer than NAME_MAX characters,
or the total length of the pathname exceeded PATH_MAX char-
acters.
[ENFILE] The system file table is full.
[ENOENT] The given directory does not exist.
[ENOMEM] There was insufficient free memory to allocate the DIR
structure or one of its subsidiary buffers.
[ENOTDIR] A component of the path prefix is not a directory.
Closedir(), readdir() and readdir_r() will fail if:
[EBADF] The dirp argument doesn't refer to an open directory
stream.
Telldir() will fail if:
[ENOMEM] There was insufficient free memory to allocate a record de-
scribing the current position in the directory.
SEE ALSOopen(2), close(2), read(2), lseek(2), dir(5)HISTORY
The opendir(), readdir(), telldir(), seekdir(), rewinddir(), closedir(),
and dirfd() functions appeared in 4.2BSD.
STANDARDS
The opendir(), readdir(), readdir_r()rewinddir(), and closedir() func-
tions conform to IEEE Std1003.1-1996 (``POSIX'').
BUGS
The opendir(), readdir(), telldir(), seekdir(), rewinddir(), closedir(),
and dirfd() functions may not be safely called concurrently from multiple
threads, e.g., the interfaces described by pthreads(3).
4.2 Berkeley Distribution June 4, 1993 3
