getdents(2)                                                        getdents(2)


NAME
     getdents, getdents64, ngetdents, ngetdents64 - read directory entries and
     put in a file system independent format

C SYNOPSIS
     #include <sys/dirent.h>

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

     int getdents64(int fildes, dirent64_t *buf, unsigned nbyte);

     int ngetdents(int fildes, dirent_t *buf, unsigned nbyte, int *eof);

     int ngetdents64(int fildes, dirent64_t *buf, unsigned nbyte, int *eof);

DESCRIPTION
     fildes is a file descriptor obtained from a creat, open, dup, fcntl,
     pipe, or ioctl 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. See dirent(4) to
     calculate the number of bytes.

     The file system independent directory entry is specified by the dirent
     structure.  For a description of this see dirent(4).

     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 routine
     [for a description, see directory(3C)], and should not be used for other
     purposes.

     getdents64 is identical to getdents except that the dirent64_t structure
     is used instead of the dirent_t structure.  The dirent64_t structure can
     return larger values for some fields.

     ngetdents and ngetdents64 are identical to getdents and getdents64,
     respectively, except that the eof argument is present.  The value pointed
     to by eof is set to 1 if end-of-file was encountered during the current
     operation, 0 otherwise.  Use of this feature eliminates the necessity to
     call getdents one more time (and get 0 returned) after the last data is
     returned.

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


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

     EFAULT         buf points outside the allocated address space.

     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.

     ENOLINK        fildes points to a remote machine and the link to that
                    machine is no longer active.  is located on a remote file
                    system which is not available [see intro(2)].

     ETIMEDOUT      fildes refers to a directory on a remote file system which
                    is not available [see intro(2)].

     ENOTDIR        fildes is not a directory.

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

     EDIRCORRUPTED  The directory is corrupted in the file system.

SEE ALSO
     directory(3C), dirent(4)

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.


                                                                        Page 2