readdir(3UCB) SunOS/BSD Compatibility Library Functions readdir(3UCB)NAME
readdir - read a directory entry
SYNOPSIS
/usr/ucb/cc[ flag ... ] file ...
#include <sys/types.h>
#include <sys/dir.h>
struct direct *readdir(dirp);
DIR *dirp;
DESCRIPTION
The readdir() function returns a pointer to a structure representing the directory entry at the current position in the directory stream to
which dirp refers, and positions the directory stream at the next entry, except on read-only file systems. It returns a NULL pointer upon
reaching the end of the directory stream, or upon detecting an invalid location in the directory. The readdir() function shall not return
directory entries containing empty names. It is unspecified whether entries are returned
for dot (.) or dot-dot (..). The pointer returned by readdir() points to data that may be overwritten by another call to readdir() on the
same directory stream. This data shall not be overwritten by another call to readdir() on a different directory stream. The readdir()
function may buffer several directory entries per actual read operation. The readdir() function marks for update the st_atime field of
the directory each time the directory is actually read.
RETURN VALUES
The readdir() function returns NULL on failure and sets errno to indicate the error.
ERRORS
The readdir() function will fail if one or more of the following are true:
EAGAIN Mandatory file/record locking was set, O_NDELAY or O_NONBLOCK was set, and there was a blocking record lock.
EAGAIN Total amount of system memory available when reading using raw I/O is temporarily insufficient.
EAGAIN No data is waiting to be read on a file associated with a tty device and O_NONBLOCK was set.
EAGAIN No message is waiting to be read on a stream and O_NDELAY or O_NONBLOCK was set.
EBADF The file descriptor determined by the DIR stream is no longer valid. This results if the DIR stream has been closed.
EBADMSG Message waiting to be read on a stream is not a data message.
EDEADLK The read() was going to go to sleep and cause a deadlock to occur.
EFAULT buf points to an illegal address.
EINTR A signal was caught during the read() or readv() function.
EINVAL Attempted to read from a stream linked to a multiplexor.
EIO A physical I/O error has occurred, or the process is in a background process group and is attempting to read from its con-
trolling terminal, and either the process is ignoring or blocking the SIGTTIN signal or the process group of the process is
orphaned.
ENOENT The current file pointer for the directory is not located at a valid entry.
ENOLCK The system record lock table was full, so the read() or readv() could not go to sleep until the blocking record lock was
removed.
ENOLINK fildes is on a remote machine and the link to that machine is no longer active.
ENXIO The device associated with fildes is a block special or character special file and the value of the file pointer is out of
range.
EOVERFLOW The value of the direct structure member d_ino cannot be represented in an ino_t.
USAGE
The readdir() function has a transitional interface for 64-bit file offsets. See lf64(5).
SEE ALSO getdents(2), readdir(3C), scandir(3UCB), lf64(5)NOTES
Use of these interfaces should be restricted to only applications written on BSD platforms. Use of these interfaces with any of the sys-
tem libraries or in multi-thread applications is unsupported.
SunOS 5.10 28 Jan 1998 readdir(3UCB)
Check Out this Related Man Page
DIRECTORY(3) BSD Library Functions Manual DIRECTORY(3)NAME
closedir, dirfd, opendir, readdir, readdir_r, rewinddir, seekdir, telldir -- directory operations
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <dirent.h>
int
closedir(DIR *dirp);
int
dirfd(DIR *dirp);
DIR *
opendir(const char *dirname);
struct dirent *
readdir(DIR *dirp);
int
readdir_r(DIR *restrict dirp, struct dirent *restrict entry, struct dirent **restrict result);
void
rewinddir(DIR *dirp);
void
seekdir(DIR *dirp, long loc);
long
telldir(DIR *dirp);
DESCRIPTION
The opendir() function opens the directory named by dirname, associates a directory stream with it, and returns a pointer to be used to iden-
tify the directory stream in subsequent operations. The pointer NULL is returned if dirname cannot be accessed or if it cannot malloc(3)
enough memory to hold the whole thing.
The readdir() function returns a pointer to the next directory entry. It returns NULL upon reaching the end of the directory or detecting an
invalid seekdir() operation.
readdir_r() provides the same functionality as readdir(), but the caller must provide a directory entry buffer to store the results in. If
the read succeeds, result is pointed at the entry; upon reaching the end of the directory, result is set to NULL. readdir_r() returns 0 on
success or an error number to indicate failure.
The telldir() function returns the current location associated with the named directory stream. Values returned by telldir() are good only
for the lifetime of the DIR pointer (e.g., dirp) from which they are derived. If the directory is closed and then reopened, prior values
returned by telldir() will no longer be valid.
The seekdir() function sets the position of the next readdir() operation on the directory stream. The new position reverts to the one asso-
ciated with the directory stream when the telldir() operation was performed.
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, 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, see open(2).
Sample code which searches a directory for entry ``name'' is:
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;
LEGACY SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
<sys/types.h> is necessary for these functions.
SEE ALSO close(2), lseek(2), open(2), read(2), compat(5), dir(5)HISTORY
The closedir(), dirfd(), opendir(), readdir(), rewinddir(), seekdir(), and telldir() functions appeared in 4.2BSD.
BSD June 4, 1993 BSD