get directory entries in a filesystem independent
() reads directory entries from the
directory referenced by the file descriptor
into the buffer pointed to by
, in a filesystem independent format. Up
of data will be transferred.
must be greater than or equal to the
block size associated with the file (see
). Some filesystems may not
() with buffers smaller
than this size.
The data in the buffer is a series of dirent
structures each containing at least the following entries:
char d_name[MAXNAMLEN + 1]; /* see below */
entry is a number which is unique
for each distinct file in the filesystem. Files that are linked by hard links
) have the same
entry is the file offset of the next
entry. The d_reclen
entry is the length, in
bytes, of the directory record.
is the type of file, where the
following are possible types:
entry specifies the length of the
file name excluding the NUL byte. Thus the actual size of
may vary from 1 to
entry contains a NUL-terminated file
Entries may be separated by extra space. The
entry may be used as an offset from
the start of a dirent
structure to the next
structure, if any.
Invalid entries with d_fileno
set to 0 may be
returned among regular entries.
The actual number of bytes transferred is returned. The current position pointer
associated with fd
is set to point to the
next block of entries. The pointer may not advance by the number of bytes
The current position pointer may be set and retrieved by
. The current position
pointer should only be set to a value returned by
, the value of
from an entry, or zero.
If successful, the number of bytes actually transferred is returned. A value of
zero is returned when the end of the directory has been reached. Otherwise, -1
is returned and the global variable errno
set to indicate the error.
() will fail if:
- fd is not a valid file descriptor open
- Part of buf points outside the process's
allocated address space.
- The file referenced by fd is not a
directory, or nbytes is too small for
returning a directory entry or block of entries, or the current position
pointer is invalid.
- An I/O error occurred while reading from or writing to the file
() call is not a portable
interface and should not be used directly by applications. Use
() function first appeared
. In OpenBSD 5.5
entry was added to
() was replaced with