getdents(2)                DG/UX 4.30                 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;

     PARAMETERS
          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            d_ino;
                        off_t           d_off;
                        unsigned short  d_reclen;
                        char            d_name[1];
                };

          The "d_ino" entry is a number that is unique for each file
          in the filesystem.  The "d_off" is the offset of that
          directory entry in the actual filesystem directory.  The
          field "d_name" 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 file names makes the file system
          independent variable length.  The value "d_reclen" 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



     Licensed material--property of copyright holder(s)         Page 1

     getdents(2)                DG/UX 4.30                 getdents(2)



          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.

     EXCEPTIONS
          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
          getdirentries(2), lseek(2), open(2), dirent(4).



















     Licensed material--property of copyright holder(s)         Page 2