NAME

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

SYNOPSIS

#include <sys/dirent.h>

int getdents(int fildes, struct dirent * buf, size_t nbyte);

DESCRIPTION

The getdents( ) function attempts to read nbyte bytes from the directory associated with the file descriptor 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 will be strictly less than nbyte. See dirent(4) to calculate the number of bytes.

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 function was developed in order to implement the readdir routine (for a description, see opendir(3C)), and should not be used for other purposes.

RETURN VALUES

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 function failed, -1 is returned and errno is set to indicate the error.

ERRORS

The getdents( ) function will fail if one or more of the following are true:

EBADF

fildes is not a valid file descriptor open for reading.

EFAULT

buf points to an illegal address.

EINVAL

nbyte is not large enough for one directory entry.

EIO

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

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.

EOVERFLOW

The value of the dirent structure member d_ino or d_off cannot be represented in an ino_t or off_t.

USAGE

The getdents( ) function has an explicit 64-bit equivalent. See interface64(5).

SEE ALSO

opendir(3C), dirent(4), interface64(5)