directory(3C) directory(3C)
NAME
directory: closedir(), opendir(), readdir(), readdir_r(), rewinddir(), seekdir(), telldir() - directory operations
SYNOPSIS
DESCRIPTION
This library package provides functions that allow programs to read directory entries without having to know the actual directory format
associated with the file system. Because these functions allow programs to be used portably on file systems with different directory for-
mats, this is the recommended way to read directory entries.
opens the directory dirname and associates a directory stream with it. returns a pointer used to identify the directory stream in subse-
quent operations. uses to allocate memory.
returns a pointer to the next directory entry.
It returns a NULL pointer upon reaching the end of the directory or detecting an invalid operation. See dirent(5) for
a description of the fields available in a directory entry.
initializes the structure referenced by to represent the current position in the directory stream referenced by and stores a pointer to
this structure at the location referenced by
returns the current location (encoded)
associated with the directory stream to which dirp refers.
sets the position of the next
operation on the directory stream to which dirp refers. The loc argument is a location within the directory stream
obtained from The position of the directory stream is restored to where it was when returned that loc value. Values
returned by are valid only while the pointer from which they are derived remains open. If the directory stream is
closed and then reopened, the value might be invalid.
resets the position of the directory stream to which
dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of
the corresponding directory, as a call to would have done.
closes the named directory stream,
then frees the structure associated with the pointer.
APPLICATION USAGE
Users of should note that now conforms with the POSIX.1c Threads standard. The old prototype of is supported for compatibility with exist-
ing DCE applications only.
RETURN VALUE
upon successful completion,
returns a pointer to an object of type referring to an open directory stream. Otherwise, it returns a NULL pointer and
sets the global variable to indicate the error.
upon successful completion,
returns a pointer to an object of type describing a directory entry. Upon reaching the end of the directory, returns a
NULL pointer and does not change the value of Otherwise, it returns a NULL pointer and sets to indicate the error.
upon successful completion returns a 0.
On successful return, the pointer returned at has the same value as the argument Upon reaching end of the directory
stream, has the value NULL. An error number is returned upon error.
upon successful completion,
returns a long value indicating the current position in the directory. Otherwise it returns and sets to indicate the
error.
does not return any value,
but if an error is encountered, is set to indicate the error.
upon successful completion, returns a value of
Otherwise, it returns a value of and sets to indicate the error.
ERRORS
fails if any of the following conditions are encountered:
Search permission is denied for a component of
dirname, or read permission is denied for dirname.
dirname points outside the allocated address space of the process. The reliable detection of this error is implementation
dependent.
Too many symbolic links were encountered in translating the path name.
Too many open file descriptors are currently open for the calling process.
A component of dirname exceeds bytes, or the entire length of dirname exceeds - 1 bytes while is in effect.
Too many open file descriptors are currently open on the system.
A component of dirname does not exist or dirname points to an empty string.
failed to provide sufficient memory to process the directory.
A component of dirname is not a directory.
or might fail if any of the following conditions are encountered:
dirp does not refer to an open directory stream.
dirp points outside the allocated address space of the process.
An I/O error occurred.
The directory stream to which
dirp refers is not located at a valid directory entry.
Directory may be corrupted.
might fail if any of the following conditions are encountered:
dirp does not refer to an open directory stream.
dirp specifies an improper file system block size.
might fail if the following condition is encountered:
dirp specifies an improper file system block size.
might fail if any of the following conditions are encountered:
dirp does not refer to an open directory stream.
dirp points outside the allocated address space of the process.
might fail if any of the following conditions are encountered:
dirp does not refer to an open directory stream.
dirp points outside the allocated address space of the process.
EXAMPLES
The following code searches the current directory for an entry name:
DIR *dirp;
struct dirent *dp;
dirp = opendir(".");
while ((dp = readdir(dirp)) != NULL) {
if (strcmp(dp->d_name, name) == 0) {
(void) closedir(dirp);
return FOUND;
}
}
(void) closedir(dirp);
return NOT_FOUND;
WARNINGS
and (see getdirentries(2)) are the only ways to access remote NFS directories. Attempting to read a remote directory via NFS by using
returns and sets to (see read(2)).
If a file is removed from or added to the directory after the most recent call to or whether a subsequent call to or returns an entry for
that file is unspecified.
For 32-bit applications, the d_ino field of the struct may overflow for filesystems that use 64-bit values. In this case the most-signifi-
cant bytes will be truncated without generating an error and d_ino values may not be unique.
AUTHOR
was developed by AT&T, HP, and the University of California, Berkeley.
SEE ALSO
close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), thread_safety(5).
STANDARDS CONFORMANCE
directory(3C)