NAME    [Toc]    [Back]

     getdirentries - get directory entries in a filesystem  independent format

SYNOPSIS    [Toc]    [Back]

     #include <dirent.h>

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

DESCRIPTION    [Toc]    [Back]

     getdirentries()  reads  directory entries from the directory
referenced by
     the file descriptor fd into the buffer pointed to by buf, in
a filesystem
     independent  format.   Up  to  nbytes of data will be transferred.  nbytes
     must be greater than or equal to the block  size  associated
with the file
     (see   stat(2)).    Some   filesystems   may   not   support
getdirentries() with
     buffers smaller than this size.

     The data in the buffer is a series of dirent structures each
containing
     the following entries:

           u_int32_t       d_fileno;
           u_int16_t       d_reclen;
           u_int8_t        d_type;
           u_int8_t        d_namlen;
           char            d_name[MAXNAMLEN + 1]; /* see below */

     The d_fileno 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_fileno.  The d_reclen entry  is  the  length,  in
bytes, of the
     directory record.

     The d_type is the type of file, where the following are possible types:
     DT_UNKNOWN, DT_FIFO, DT_CHR, DT_DIR, DT_BLK, DT_REG, DT_LNK,
DT_SOCK, and
     DT_WHT.

     The d_namlen entry specifies the length of the file name excluding the
     NUL byte.  Thus the actual size of d_name may vary from 1 to
MAXNAMLEN +
     1.

     The d_name entry contains a NUL-terminated file name.

     Entries may be separated by extra space.  The d_reclen entry
may be used
     as an offset from the start of a  dirent  structure  to  the
next structure,
     if any.

     Invalid entries with d_fileno set to 0 may be returned among
regular entries.


     The actual number of bytes  transferred  is  returned.   The
current position
     pointer associated with fd is set to point to the next block
of entries.
     The pointer may not advance by the number of bytes  returned
by
     getdirentries().   A  value of zero is returned when the end
of the directory
 has been reached.

     getdirentries() writes the position of the block  read  into
the location
     pointed  to  by  basep.  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 basep, or zero.

RETURN VALUES    [Toc]    [Back]

     If successful, the number of bytes actually  transferred  is
returned.
     Otherwise,  -1  is returned and the global variable errno is
set to indicate
 the error.

ERRORS    [Toc]    [Back]

     getdirentries() will fail if:

     [EBADF]       fd is not a valid  file  descriptor  open  for
reading.

     [EFAULT]       Either  buf or basep points outside the allocated address
                   space.

     [EINVAL]      The file referenced by fd is not a  directory,
or nbytes is
                   too  small  for returning a directory entry or
block of entries,
 or the current position pointer is  invalid.

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

SEE ALSO    [Toc]    [Back]

     lseek(2), open(2), dirent(5)

HISTORY    [Toc]    [Back]

     The getdirentries() function first appeared in 4.4BSD.

OpenBSD      3.6                           June      9,      1993