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(3HEAD).

     On devices capable of seeking, getdents() starts at a  posi-
     tion  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  direc-
           tory 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

     The getdents()  function  was  developed  to  implement  the
     readdir(3C)  function  and should not be used for other pur-
     poses.

     The getdents() function has  a  transitional  interface  for
     64-bit file offsets.  See lf64(5).

SEE ALSO

     readdir(3C), dirent(3HEAD), lf64(5)