4.3BSD-UWisc/man/cat2/getdirentries.2

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



NAME
     getdirentries - gets directory entries in a filesystem
     independent format

SYNOPSIS
     #include <sys/dir.h>

     cc = getdirentries(fd, buf, nbytes, basep)
     int cc, fd;
     char *buf;
     int nbytes;
     long *basep

DESCRIPTION
     _G_e_t_d_i_r_e_n_t_r_i_e_s attempts to put 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 for-
     mat.  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 _s_t_a_t(_2).  Sizes less than this may cause
     errors on certain filesystems.

     The data in the buffer is a series of _d_i_r_e_c_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 dis-
     tinct file in the filesystem.  Files that are linked by hard
     links (see _l_i_n_k(_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 directory 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.  Thus
     the actual size of _d__n_a_m_e may vary from 2 to MAXNAMELEN + 1.

     The structures are not necessarily tightly packed.  The
     _d__r_e_c_l_e_n entry may be used as an offset from the beginning
     of a _d_i_r_e_c_t structure to the next structure, if any.

     Upon return, 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
     is not necessarily incremented by the number of bytes
     returned by _g_e_t_d_i_r_e_n_t_r_i_e_s.  If the value returned is zero,
     the end of the directory has been reached.  The current
     position pointer may be set and retrieved by _l_s_e_e_k(_2).  _G_e_t_-
     _d_i_r_e_n_t_r_i_e_s writes the position of the block read into the
     location pointed to by _b_a_s_e_p.  It is not safe to set the
     current position pointer to any value other than a value



Printed 12/27/86         19 August 1985                         1






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



     previously returned by _l_s_e_e_k(_2) or a value previously
     returned in the location pointed to by _b_a_s_e_p or zero.

RETURN VALUE
     If successful, the number of bytes actually transferred is
     returned.  Otherwise, a -1 is returned and the global vari-
     able _e_r_r_n_o is set to indicate the error.

SEE ALSO
     open(2), lseek(2)

ERRORS
     _G_e_t_d_i_r_e_n_t_r_i_e_s will fail if one or more of the following are
     true:

     [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 allo-
                    cated address space.

     [EINTR]        A read from a slow device was interrupted
                    before any data arrived by the delivery of a
                    signal.

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




























Printed 12/27/86         19 August 1985                         2