
GETDIRENTRIES(2)           UNIX Programmer's Manual           GETDIRENTRIES(2)

NNAAMMEE
     ggeettddiirreennttrriieess - get directory entries in a filesystem independent format

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ssyyss//ddiirreenntt..hh>>

     _i_n_t
     ggeettddiirreennttrriieess(_i_n_t _f_d, _c_h_a_r _*_b_u_f, _i_n_t _n_b_y_t_e_s, _l_o_n_g _*_b_a_s_e_p)

DDEESSCCRRIIPPTTIIOONN
     GGeettddiirreennttrriieess() reads directory entries from the directory referenced by
     the file descriptor _f_d into the buffer pointed to by _b_u_f, in a filesystem
     independent format.  Up to _n_b_y_t_e_s of data will be transferred.  _N_b_y_t_e_s
     must be greater than or equal to the block size associated with the file,
     see stat(2).  Some filesystems may not support ggeettddiirreennttrriieess() with
     buffers smaller than this size.

     The data in the buffer is a series of _d_i_r_e_n_t structures each containing
     the following entries:

           unsigned long   d_fileno;
           unsigned short  d_reclen;
           unsigned short  d_namlen;
           char            d_name[MAXNAMELEN + 1]; /* see below */

     The _d___f_i_l_e_n_o entry is a number which is unique for each distinct file in
     the filesystem.  Files that are linked by hard links (see link(2))  have
     the same _d___f_i_l_e_n_o. The _d___r_e_c_l_e_n entry is the length, in bytes, of the di-
     rectory record.  The _d___n_a_m_e entry contains a null terminated file name.
     The _d___n_a_m_l_e_n entry specifies the length of the file name excluding the
     null byte.  Thus the actual size of _d___n_a_m_e may vary from 1 to MAXNAMELEN
     + 1.

     Entries may be separated by extra space.  The _d___r_e_c_l_e_n entry may be used
     as an offset from the start of a _d_i_r_e_n_t structure to the next structure,
     if any.

     The actual number of bytes transferred is returned.  The current position
     pointer associated with _f_d is set to point to the next block of entries.
     The pointer may not advance by the number of bytes returned by
     ggeettddiirreennttrriieess().  A value of zero is returned when the end of the direc-
     tory has been reached.

     GGeettddiirreennttrriieess() writes the position of the block read into the location
     pointed to by _b_a_s_e_p. Alternatively, the current position pointer may be
     set and retrieved by lseek(2).  The current position pointer should only
     be set to a value returned by lseek(2),  a value returned in the location
     pointed to by _b_a_s_e_p, or zero.

RREETTUURRNN VVAALLUUEESS
     If successful, the number of bytes actually transferred is returned.
     Otherwise, -1 is returned and the global variable _e_r_r_n_o is set to indi-
     cate the error.

EERRRROORRSS
     GGeettddiirreennttrriieess() will fail if:

     EBADF     _f_d is not a valid file descriptor open for reading.

     EFAULT    Either _b_u_f or _b_a_s_e_p point outside the allocated address space.



     EIO       An I/O error occurred while reading from or writing to the file
               system.

SSEEEE AALLSSOO
     open(2),  lseek(2)

HHIISSTTOORRYY
     The ggeettddiirreennttrriieess function call is currently under development.

BSD Experimental                 July 23, 1991                               2
























































