opensolaris man page for getdents

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.11							    17 Jul 2001 						       getdents(2)