unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

GETDENTS(2)                   System Calls Manual                  GETDENTS(2)



NAME
       getdents - gets directory entries in a filesystem independent format

SYNOPSIS
       #include <&lt;sys/types.h>&gt;
       #include <&lt;sys/dirent.h>&gt;

       int getdents(fd, buf, nbytes)
       int fd;
       char *buf;
       int nbytes;

DESCRIPTION
       getdents()  attempts to put directory entries from the directory refer-
       enced by the file descriptor fd into the buffer pointed to by buf, in a
       filesystem  independent  format.   Up  to  nbytes bytes of data will be
       transferred.

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

              off_t          d_off;
              u_long         d_fileno;
              u_short        d_reclen;
              u_short        d_namlen;
              char           d_name[MAXNAMLEN + 1]; /* see below */

       The  d_off  entry  contains  a value which is interpretable only by the
       filesystem that generated it.  It may  be  supplied  as  an  offset  to
       lseek(2V))  to find the entry following the current one in a directory.
       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(2V))
       have the same d_fileno.  The d_reclen entry is the length, in bytes, of
       the directory record.  The d_name entry contains a null terminated file
       name.  The d_namlen entry specifies the length of the file name.   Thus
       the actual size of d_name may vary from 1 to MAXNAMLEN+1.

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

       Upon  return,  the actual number of bytes transferred is returned.  The
       current position pointer associated with fd is  set  to  point  to  the
       directory  entry  following  the last one returned.  The pointer is not
       necessarily incremented by the number of bytes returned by  getdents().
       If  the  value  returned  is  zero,  the  end of the directory has been
       reached.  The current position pointer may  be  set  and  retrieved  by
       lseek(2V).   It  is not safe to set the current position pointer to any
       value other than a value previously returned by lseek(2V), or the value
       of a d_off entry in a dirent structure returned by getdents(), or zero.

RETURN VALUES
       getdents() returns the number of bytes actually transferred on success.
       On failure, it returns -1 and sets errno to indicate the error.

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

       EFAULT         buf points outside the allocated address space.

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

       EINVAL         nbytes is not large enough for one directory entry.

       ENOTDIR        The file referenced by fd is not a directory.

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

SEE ALSO
       link(2V), lseek(2V), open(2V), directory(3V)

NOTES
       It is strongly recommended, for portability reasons, that programs that
       deal with directory entries use the directory(3V) interface rather than
       directly calling getdents().



                                21 January 1990                    GETDENTS(2)