GETDENTS(2)                          BSD                           GETDENTS(2)



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

SYNOPSIS
     #include <sys/dir.h>

     int getdents (fildes, buf, nbyte)
     int fildes;
     char *buf;
     unsigned nbyte;

DESCRIPTION
     fildes is a file descriptor obtained from an open(2) or dup(2) system
     call.

     getdents attempts to read nbyte bytes from the directory associated with
     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 length, in most cases the actual number
     of bytes returned will be strictly less than nbyte.

     The file system independent directory entry is specified by the direct
     structure.  For a description of this, see dir(5).

     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.

     This system call was developed in order to implement the readdir(3)
     routine (for a description see directory(3)), and should not be used for
     other purposes.

ERRORS
     getdents will fail if one or more of the following are true:

     [EBADF]     fildes is not a valid file descriptor open for reading.

     [EINVAL]    nbyte is not large enough for one directory entry.

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

     [ENOTDIR]   fildes is not a directory.

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

SEE ALSO
     directory(3), dir(5).

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

NOTES
     Under other implementations, getdents fails if the following is true:

     [ENOLINK]   fildes points to a remote machine and the link to that

                 machine is no longer active.