./_Man_SunOS_4.1.3_html/html2/getdents.2.html

Manual page for GETDENTS(2)

getdents - gets directory entries in a filesystem independent format

SYNOPSIS

#include <sys/types.h>
#include <sys/dirent.h>

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

DESCRIPTION

getdents() attempts to put 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 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.

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().