NAME

getdents − read directory entries and put in a file system independent format

SYNOPSIS

#include <sys/dirent.h>

int getdents (fildes, buf, nbyte)
int fildes;
char ∗buf;
unsigned nbyte;

DESCRIPTION

fildes is a file descriptor obtained from an open(2) or dup(2) system call.

getdents attempts to read nbyte bytes from the directory associated with fildes and to format them as file system independent directory entries in the buffer pointed to by buf. Since the file system independent directory entries are of variable length, in most cases the actual number of bytes returned is strictly less than nbyte.

The file system independent directory entry is specified by the dirent structure.  For a description of this see dirent(4).

On devices capable of seeking, getdents starts at a position in the file given by the file pointer associated with fildes. Upon return from getdents, the file pointer is incremented to point to the next directory entry. 

This system call was developed in order to implement the readdir(3X) routine [for a description see directory(3X)], and should not be used for other purposes.

getdents fails if one or more of the following are true:

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

[EFAULT] buf points outside the allocated address space. 

[EINVAL] nbyte is not large enough for one directory entry. 

[ENOENT] The current file pointer for the directory is not located at a valid entry. 

[ENOLINK] fildes points to a remote machine and the link to that machine is no longer active. 

[ENOTDIR] fildes is not a directory. 

[EIO] An I/O error occurred while accessing the file system. 

SEE ALSO

directory(3X), dirent(4). 

DIAGNOSTICS

Upon successful completion a non-negative integer is returned indicating the number of bytes actually read.  A value of 0 indicates the end of the directory has been reached.  If the system call failed, a −1 is returned and errno is set to indicate the error. 

September 02, 1992