getdents() -- System Call (libc)

Read directory entries
#include <dirent.h>
int getdents (fd, buffer, num)
int fd;
char *buffer;
unsigned num;

The COHERENT  system call getdents() is  one of a set  of COHERENT routines
that manipulate  directories in a  device-independent manner.  It  reads an
entry from a directory file and writes it into a structure of type dirent.

fd  is the  file  descriptor for  the  directory file;  it must  be a  file
descriptor opened by  a call to open() or dup().  buffer points to the area
where getdents() writes its output.  num gives the size of the area pointed
to by buffer; getdents() returns no more than num bytes of information.

getdents()  writes its  output into  a structure of  type dirent,  which is
defined in the header file dirent.h. It has the following structure:

    struct dirent {
        long d_ino;
        long d_off;
        unsigned short d_reclen;
        char d_name[1];
    };

Field d_name is a NUL-terminated string of indefinite length.  Because this
structure does not have a fixed  size, you must tell getdents() the maximum
number of bytes it can output.

getdents() automatically  increments the offset pointer  associated with fd
to point to the next entry within the directory file.  This lets you within
a loop to read the entire contents of a directory file.

If all  goes well,  getdents() returns  the number of  bytes it  wrote into
buffer. It  returns zero if it  has reached the end  of the directory file.
If something  went wrong (for example,  you tried to use it  to read a file
other  than  a  directory  file),  it  returns -1  and  sets  errno  to  an
appropriate value.

See Also

dirent.h,
closedir(),
libc,
opendir(),
readdir(),
rewinddir(),
telldir()

Notes

This system call  is designed to support directory-access library routines.
It should not be called by user programs.

The COHERENT implementation of getdents() was written by D. Gwynn.

© 2012 by Stephen A. Ness