DIRECTORY(3) AerieBSD 1.0 Refernce Manual DIRECTORY(3)

NAME

opendirreaddir, readdir_r, telldir, seekdir, rewinddir, closedir, dirfd directory operations

SYNOPSIS

#include <sys/types.h>
#include <dirent.h>

DIR* opendir(const char *filename);

structdirent * readdir(DIR *dirp);

int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);

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. On failure, NULL is returned and errno is set to indicate the error.

The readdir(); function returns a pointer to the next directory entry in the named directory stream dirp. It returns NULL upon reaching the end of the directory or detecting an invalid seekdir(); operation.

The readdir_r(); function (much like readdir();) initializes the dirent structure referenced by entry to represent the next directory entry in the named directory stream dirp, and stores a pointer to this structure at the location referenced by result. The storage pointed to by entry must be large enough for a dirent with a d_name array member containing at least NAME_MAX plus one elements. On successful return, the pointer returned at "*result" will have the same value as the argument entry. Upon reaching the end of the directory stream, this pointer shall have the value NULL.

The telldir(); function returns the current location associated with the named directory stream dirp. On failure, \-1 is returned and errno is set to indicate the error.

The seekdir(); function sets the position of the next readdir(); operation on the named directory stream dirp. 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 undetected directory compaction.

The rewinddir(); function resets the position of the named directory stream dirp to the beginning of the directory.

The closedir(); function closes the named directory stream and frees the structure associated with the dirp pointer, returning 0 on success. On failure, \-1 is returned and the global variable errno is set to indicate the error.

The dirfd(); function returns the integer file descriptor associated with the named directory stream dirp (see open(2/)).

EXAMPLES

Sample code which searches a directory for entry “name” is:

len = strlen(name);
dirp = opendir(".");
if (dirp) {
	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);

ERRORS

The opendir(); function will fail if:
[ENOTDIR]
The supplied filename is not a directory.

The opendir(); function may also fail and set errno for any of the errors specified for the routines fcntl(2), fstat(2), open(2), and malloc(3).

The readdir(); and readdir_r(); functions may also fail and set errno for any of the errors specified for the routine getdirentries(2).

The telldir(); function may also fail and set errno for any of the errors specified for the routine realloc(3).

The closedir(); function may also fail and set errno for any of the errors specified for the routine close(2).

SEE ALSO

close(2), getdirentries(2), lseek(2), open(2), dir(5)

HISTORY

The opendir();, readdir();, telldir();, seekdir();, rewinddir();, closedir();, and dirfd(); functions appeared in 4.2BSD.


AerieBSD 1.0 Reference Manual May 14 2010 DIRECTORY(3)