.TH getdents() "" "" "System Call (libc)"
.PC "Read directory entries"
.B "#include <dirent.h>"
\fBint getdents (\fIfd\^\fB, \fIbuffer\^\fB, \fInum\^\fB)\fR
\fBint \fIfd\^\fB;\fR
\fBchar *\fIbuffer\^\fB;\fR
\fBunsigned \fInum\^\fB;\fR
.PP
The \*(CO system call
.B getdents()
is one of a set of \*(CO routines that manipulate directories in a
device-independent manner.
It reads an entry from a directory file and writes it into a structure of type
.BR dirent .
.PP
.I fd
is the file descriptor for the directory file;
it must be a file descriptor opened by a call to
.B open()
or
.BR dup() .
.I buffer
points to the area where
.B getdents()
writes its output.
.I num
gives the size of the area pointed to by
.IR buffer ;
.B getdents()
returns no more than
.I num
bytes of information.
.PP
.B getdents()
writes its output into a structure of type
.BR dirent ,
which is defined in the header file
.BR dirent.h .
It has the following structure:
.DM
	struct dirent {
		long d_ino;
		long d_off;
		unsigned short d_reclen;
		char d_name[1];
	};
.DE
.PP
Field
.B d_name
is a NUL-terminated string of indefinite length.
Because this structure does not have a fixed size,
you must tell
.B getdents()
the maximum number of bytes it can output.
.PP
.B getdents()
automatically increments the offset pointer associated with
.I fd
to point to the next entry within the directory file.
This lets you within a loop to read the entire contents of a directory file.
.PP
If all goes well,
.B getdents()
returns the number of bytes it wrote into
.IR buffer .
It returns zero if it has reached the end of the directory file.
If something went wrong (for example, you tried to use it to read a
file other than a directory file), it returns \-1 and sets
.B errno
to an appropriate value.
.SH "See Also"
.Xr "dirent.h," dirent.h
.Xr "closedir()," closedir
.Xr "libc," libc
.Xr "opendir()," opendir
.Xr "readdir()," readdir
.Xr "rewinddir()," rewinddir
.Xr "telldir()" telldir
.SH Notes
This system call is designed to support directory-access library routines.
It should not be called by user programs.
.PP
.II "Gwynn, D."
The \*(CO implementation of
.B getdents()
was written by D. Gwynn.
