Tribblix: manual page: getdents.2

GETDENTS(2) System Calls GETDENTS(2)

NAME

getdents - read directory entries and put in a file system
independent format

SYNOPSIS

#include <dirent.h>

int getdents(int fildes, struct dirent *buf, size_t nbyte);

DESCRIPTION

The getdents() function attempts to read nbyte bytes from the
directory associated with the file descriptor fildes and to format
them as file system independent directory entries in the buffer
pointed to by buf. Since the file system independent directory
entries are of variable lengths, in most cases the actual number of
bytes returned will be less than nbyte. The file system independent
directory entry is specified by the dirent structure. See
dirent.h(3HEAD).

On devices capable of seeking, getdents() starts at a position in the
file given by the file pointer associated with fildes. Upon return
from getdents(), the file pointer is incremented to point to the next
directory entry.

RETURN VALUES

Upon successful completion, a non-negative integer is returned
indicating the number of bytes actually read. A return value of 0
indicates the end of the directory has been reached. Otherwise, -1 is
returned and errno is set to indicate the error.

ERRORS

The getdents() function will fail if:

EBADF
The fildes argument is not a valid file descriptor open
for reading.

EFAULT
The buf argument points to an illegal address.

EINVAL
The nbyte argument is not large enough for one directory
entry.

EIO
An I/O error occurred while accessing the file system.

ENOENT
The current file pointer for the directory is not
located at a valid entry.

ENOLINK
The fildes argument points to a remote machine and the
link to that machine is no longer active.

ENOTDIR
The fildes argument is not a directory.

EOVERFLOW
The value of the dirent structure member d_ino or d_off
cannot be represented in an ino_t or off_t.

USAGE