GETDENTS(2) System Calls Manual GETDENTS(2)
getdents - gets directory entries in a filesystem independent format
int getdents(fd, buf, nbytes)
getdents() attempts to put directory entries from the directory refer-
enced by the file descriptor fd into the buffer pointed to by buf, in a
filesystem independent format. Up to nbytes bytes of data will be
The data in the buffer is a series of dirent structures each containing
the following entries:
char d_name[MAXNAMLEN + 1]; /* see below */
The d_off entry contains a value which is interpretable only by the
filesystem that generated it. It may be supplied as an offset to
lseek(2V)) to find the entry following the current one in a directory.
The d_fileno entry is a number which is unique for each distinct file
in the filesystem. Files that are linked by hard links (see link(2V))
have the same d_fileno. The d_reclen entry is the length, in bytes, of
the directory record. The d_name entry contains a null terminated file
name. The d_namlen entry specifies the length of the file name. Thus
the actual size of d_name may vary from 1 to MAXNAMLEN+1.
The structures are not necessarily tightly packed. The d_reclen entry
may be used as an offset from the beginning of a dirent structure to
the next structure, if any.
Upon return, the actual number of bytes transferred is returned. The
current position pointer associated with fd is set to point to the
directory entry following the last one returned. The pointer is not
necessarily incremented by the number of bytes returned by getdents().
If the value returned is zero, the end of the directory has been
reached. The current position pointer may be set and retrieved by
lseek(2V). It is not safe to set the current position pointer to any
value other than a value previously returned by lseek(2V), or the value
of a d_off entry in a dirent structure returned by getdents(), or zero.
getdents() returns the number of bytes actually transferred on success.
On failure, it returns -1 and sets errno to indicate the error.
EBADF fd is not a valid file descriptor open for reading.
EFAULT buf points outside the allocated address space.
EINTR A read from a slow device was interrupted before any
data arrived by the delivery of a signal.
EINVAL nbytes is not large enough for one directory entry.
ENOTDIR The file referenced by fd is not a directory.
EIO An I/O error occurred while reading from or writing to
the file system.
link(2V), lseek(2V), open(2V), directory(3V)
It is strongly recommended, for portability reasons, that programs that
deal with directory entries use the directory(3V) interface rather than
directly calling getdents().
21 January 1990 GETDENTS(2)