getdents(S)                    6 January 1993                    getdents(S)


 Name

    getdents - read directory entries and put in a filesystem-independent
    format

 Syntax


    cc  . . .  -lc


    #include  <sys/dirent.h>

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


 Description

    The fildes argument is a file descriptor obtained from an open(S) or
    dup(S) system call.

    The getdents system call attempts to read nbyte bytes from the directory
    associated with fildes and to format them as filesystem-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 is strictly less than nbyte.

    The filesystem-independent directory entry is specified by the dirent
    structure.  For a description, see dirent(F).

    On devices capable of seeking, getdents starts at a position in the file
    given by the file pointer associated with fildes.  Upon return from get-
    dents, the file pointer is incremented to point to the next directory
    entry.

    This system call was developed to implement the readdir(S) routine (see
    directory(S)), and should not be used for other purposes.

    The getdents system call fails if one or more of the following is 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.

    [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]    fildes points to a remote machine and the link to that ma-
                 chine is no longer active.

    [ENOTDIR]    fildes is not a directory.


 Diagnostics

    Upon successful completion, a non-negative integer is returned, indicat-
    ing 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.

 See also

    directory(S), dirent(F), dup(S), open(S), readdir(S)

 Standards conformance

    getdents is not part of any currently supported standard; it is an exten-
    sion of AT&T System V provided by the Santa Cruz Operation.