ggeettddeennttss() -- System Call (libc)

Read directory entries
#iinncclluuddee <ssyyss/ddiirreenntt.hh>
iinntt ggeettddeennttss (_f_d, _b_u_f_f_e_r, _n_u_m)
iinntt _f_d;
cchhaarr *_b_u_f_f_e_r;
uunnssiiggnneedd _n_u_m;

The COHERENT  system call ggeettddeennttss() 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 ddiirreenntt.

_f_d  is the  file  descriptor for  the  directory file;  it must  be a  file
descriptor opened by  a call to ooppeenn() or dduupp().  _b_u_f_f_e_r points to the area
where ggeettddeennttss() writes its output.  _n_u_m gives the size of the area pointed
to by _b_u_f_f_e_r; ggeettddeennttss() returns no more than _n_u_m bytes of information.

ggeettddeennttss()  writes its  output into  a structure of  type ddiirreenntt,  which is
defined in the header file ddiirreenntt.hh. It has the following structure:

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

Field dd_nnaammee is a NUL-terminated string of indefinite length.  Because this
structure does not have a fixed  size, you must tell ggeettddeennttss() the maximum
number of bytes it can output.

ggeettddeennttss() automatically  increments the offset pointer  associated with _f_d
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,  ggeettddeennttss() returns  the number of  bytes it  wrote into
_b_u_f_f_e_r. 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  eerrrrnnoo  to  an
appropriate value.

_S_e_e _A_l_s_o
ddiirreenntt.hh, cclloosseeddiirr(), lliibbcc, ooppeennddiirr(), rreeaaddddiirr(), rreewwiinnddddiirr(), tteellllddiirr()

_N_o_t_e_s
This system call  is designed to support directory-access library routines.
It should not be called by user programs.

The COHERENT implementation of ggeettddeennttss was written by D. Gwynn.
