getdents(2)                    DG/UX R4.11MU05                   getdents(2)


NAME
       getdents - get directory entries in a filesystem-independent format

SYNOPSIS
       #include <sys/dirent.h>

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

   where:
       fildes    File descriptor of the directory to list

       buffer    Buffer to hold the directory entries

       nbyte     Size of the buffer in bytes

DESCRIPTION
       Getdents attempts to read nbyte bytes from the directory associated
       with fildes and then format them as filesystem-independent directory
       entries in the buffer pointed to by buffer.  Since the
       filesystem-independent directory entries are of variable length, in
       most cases the actual number of bytes returned will be strictly less
       than nbyte.

       The filesystem entry is specified by the dirent structure.  The
       dirent structure is defined as

             struct dirent {
                     long            dino;
                     offt           doff;
                     unsigned short  dreclen;
                     char            dname[1];
             };

       The dino entry is a number that is unique for each file in the
       filesystem.  The doff is the offset of that directory entry in the
       actual filesystem directory.  The field dname is the beginning of
       the character array giving the name of the directory entry.  This
       name is null terminated and may have at most MAXNAMLEN characters.
       The variable length of filenames makes the file system independent of
       variable length.  The value dreclen is the record length of this
       entry.

       On devices capable of seeking, getdents starts at a position in the
       file given by the file pointer associated with fildes.

       Upon return, the actual number of bytes transferred is returned.  The
       current position pointer associated with fildes is set to point to
       the next block of entries.

ACCESS CONTROL
       None.

RETURN VALUE
       >0     The number of bytes actually transferred.

       0      The end of the directory has been reached.

       -1     An error occurred.  errno is set to indicate the error.

DIAGNOSTICS
       Errno may be set to one of the following error codes:

       EBADF     fildes is not a valid file descriptor 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.

       ENOTDIR   fildes is not a directory.

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

SEE ALSO
       lseek(2), open(2), dirent(4).


Licensed material--property of copyright holder(s)