GETDENTS(S) UNIX System V GETDENTS(S)
Name
getdents - read directory entries and put in a file-system-
independent format
Syntax
#include <sys/dirent.h>
int getdents (fildes, buf, nbyte)
int fildes;
char *buf;
unsigned nbyte;
Description
The fildes argument is a file descriptor obtained from an
open(S) or dup(S) system call.
The getdents system call 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 will be strictly less than
nbyte.
The file-system-independent directory entry is specified by
the dirent structure. For a description of this see
dirent(F).
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(S) routine (for a description see directory(S)), and
should not be used for other purposes.
The getdents system call will fail if one or more of the
following is 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(S), dirent(F)
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.
(printed 6/20/89)