DIRECTORY(3C)
NAME
opendir, readdir, telldir, seekdir, rewinddir, closedir − directory operations
SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
DIR ∗opendir(dirname)
char ∗dirname;
struct dirent ∗readdir(dirp)
DIR ∗dirp;
long telldir(dirp)
DIR ∗dirp;
void seekdir(dirp, loc)
DIR ∗dirp;
long loc;
void rewinddir(dirp)
DIR ∗dirp;
int closedir(dirp)
DIR ∗dirp;
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 formats, this is the recommended way to read directory entries.
Opendir opens the directory dirname and associates a directory stream with it. Opendir returns a pointer used to identify the directory stream in subsequent operations. The opendir routine allocates memory using malloc(3C) or malloc(3X), depending on which is linked with the program.
Readdir returns a pointer to the next directory entry. It returns a NULL pointer upon reaching the end of the directory or detecting an invalid seekdir operation. See dirent(5) for a description of the fields available in a directory entry.
Telldir returns the current location (encoded) associated with the directory stream to which dirp refers.
Seekdir sets the position of the next readdir operation on the directory stream to which dirp refers. The loc argument is a location within the directory stream obtained from telldir. The position of the directory stream is restored to where it was when telldir returned that loc value. Values returned by telldir are valid only while the DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the telldir value might be invalid.
Rewinddir 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 opendir() would have done.
Closedir closes the named directory stream and then frees the structure associated with the DIR pointer.
RETURN VALUE
Upon successful completion, opendir returns a pointer to an object of type DIR referring to an open directory stream. Otherwise, it returns a NULL pointer and sets the global variable errno to indicate the error.
Upon successful completion, readdir returns a pointer to an object of type struct dirent describing a directory entry. Upon reaching the end of the directory, readdir returns a NULL pointer and does not change the value of errno. Otherwise, it returns a NULL pointer and sets errno to indicate the error.
Upon successful completion, telldir returns a long value indicating the current position in the directory. Otherwise it returns −1 and sets errno to indicate the error.
Upon successful completion, closedir returns a value of 0. Otherwise, it returns a value of −1 and sets errno to indicate the error.
ERRORS
Opendir might fail if any of the following is true:
[EACCES] Search permission is denied for a component of dirname, or read permission is denied for dirname.
[EFAULT] Dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent.
[ELOOP] Too many symbolic links were encountered in translating the path name.
[EMFILE] Too many open file descriptors are currently open for the calling process.
[ENAMETOOLONG] A component of dirname exceeds PATH_MAX bytes, or the entire length of dirname exceeds PATH_MAX−1 bytes while _POSIX_NO_TRUNC is in effect.
[ENFILE] Too many open file descriptors are currently open on the system.
[ENOENT] A component of the dirname does not exist.
[ENOMEM] The malloc routine failed to provide sufficient memory to process the directory.
[ENOTDIR] A component of dirname is not a directory.
[ENOENT] The dirname argument points to an empty string.
Readdir might fail if any of the following is true:
[EBADF] The dirp argument does not refer to an open directory stream.
[ENOENT] The directory stream to which dirp refers is not located at a valid directory entry.
[EFAULT] dirp points outside the allocated address space of the process.
Telldir might fail if the following is true:
[EBADF] The dirp argument does not refer to an open directory stream.
Closedir might fail if the following is true:
[EBADF] The dirp argument does not refer to an open directory stream.
[EFAULT] dirp points outside the allocated address space of the process.
Rewinddir might fail if the following is true:
[EFAULT] 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
Readdir or getdirentries(2) are the only ways to access remote NFS directories. Attempting to read a remote directory using read(2) with NFS returns −1 and sets errno to EISDIR.
APPLICATION USAGE
The header file required for these functions and the type of the return value from the readdir function has been changed for compatibility with System V Release 3 and the X/Open Portability Guide. See ndir(5) for a description of the header file <ndir.h>, which is provided to allow existing HP−UX applications to compile unmodified.
New applications should use the <dirent.h> header file for portability to System V and X/Open systems.
AUTHOR
Directory 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), ndir(5).
STANDARDS CONFORMANCE
closedir: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1
opendir: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1
readdir: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1
rewinddir: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1
seekdir: XPG2, XPG3
telldir: XPG2, XPG3
Hewlett-Packard Company — HP-UX Release 7.0: Sept 1989