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 vari-
       able  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

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

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

SEE ALSO

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

SunOS 5.10							    17 Jul 2001 						       getdents(2)