getdents(2)                         CLIX                         getdents(2)



  NAME

    getdents - Reads directory entries and puts them in a file system-
    independent format

  LIBRARY

    Standard C Library (libc.a)

  SYNOPSIS

    #include <sys/dirent.h>
    int getdents(

      int fildes ,
      char *buf ,
      unsigned nbyte );

  PARAMETERS

    fildes   Specifies a file descriptor for a directory.

    buf      Points to a buffer to contain the returned directory entries.

    nbyte    Specifies an unsigned integer representing the number of bytes to
             read.

  DESCRIPTION

    The fildes parameter is a file descriptor obtained from an open() or dup()
    function.

    The getdents() function 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.

    The file system independent directory entry is specified by the dirent
    structure.  For a description of this, see the dirent file format.

    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.

    On devices not capable of seeking, getdents() starts at the current
    position.

    This function was developed to implement the readdir() function (for a
    description, see the directory() function), and should not be used for



  2/94 - Intergraph Corporation                                              1

  getdents(2)                         CLIX                         getdents(2)



    other purposes.

  EXAMPLES

    To process all files in a given directory:

    char getdents_buf[BUFSIZE];
    int nbytes;
    struct dirent *dirent_ptr;
    char *buf_ptr;

    ...

    for (;;) {
         nbytes = getdents(directory_fd, getdents_buf, BUFSIZE);
         if (nbytes == -1) {
              perror("getdents failed");
              return(-1);
         }
         if (nbytes == 0) {
              /* End of directory reached */
              return(0);
         }

         for (buf_ptr = getdents_buf;
              buf_ptr < &getdents_buf[nbytes];
              buf_ptr += ((struct dirent *)(buf_ptr))->d_reclen) {
              dirent_ptr = (struct dirent *)buf_ptr;

              /* Process this directory entry */
              ...

         }
    }


  RETURN VALUES

    Upon successful completion a non-negative integer indicating the number of
    bytes actually read is returned.  A value of 0 indicates the end of the
    directory has been reached.  If the function failed, a -1 is returned and
    errno is set to indicate the error.

  ERRORS

    The getdents() function fails if one or more of the following are true:

    [EBADF]     The fildes parameter does not specify a valid file descriptor
                open for reading.

    [EFAULT]    The buf parameter points outside the allocated address space.



  2                                              Intergraph Corporation - 2/94

  getdents(2)                         CLIX                         getdents(2)



    [EINVAL]    The nbyte parameter is not large enough for one directory
                entry.

    [ENOENT]    The current file pointer for the directory is not located at a
                valid entry.

    [ENOLINK]   The fildes parameter points to a remote machine and the link
                to that machine is no longer active.

    [ENOTDIR]   The fildes parameter does not specify a directory.

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

  RELATED INFORMATION

    Functions:  directory(3)

    Files:  dirent(4)




































  2/94 - Intergraph Corporation                                              3