'\"macro stdmacro
.if n .pH g2.getdents @(#)getdents	40.11 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getdents 2 "" "" "\&"
.if \nX=1 .ds x} getdents 2 "" ""
.if \nX=2 .ds x} getdents 2 "" "" "\&"
.if \nX=3 .ds x} getdents 2 "" "" "\&"
.TH \*(x}
.SH NAME
\f4getdents\f1 \- read directory entries and put in a file 
system independent format
.SH SYNOPSIS
\f4#include <sys/dirent.h>\f1
.br
.PP
\f4int getdents (int fildes, struct dirent \(**buf, size_t nbyte); \f1
.SH DESCRIPTION
.I fildes\^
is a
file descriptor
obtained from an
\f4open\fP(2)
or
\f4dup\fP(2)
system call.
.PP
\f4getdents\fP
attempts to read
.I nbyte\^
bytes from the directory associated with
.I fildes\^
and to format them as file
system independent directory entries
in the buffer pointed to by
.IR 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
.I nbyte\^.
See \f4dirent\fP(4) to calculate the number of bytes.
.PP
The file system independent directory
entry is specified by the
\f4dirent\fP
structure.
For a description of this see
\f4dirent\fP(4).
.PP
.PP
On devices capable of seeking,
\f4getdents\fP
starts at a position in the file given by the file pointer
associated with
.IR fildes .
Upon return from
.IR getdents,
the file pointer is incremented
to point to the next directory entry.
.PP
This system call was developed in order to
implement the 
\f4readdir\fP
routine
[for a description, see
\f4directory\fP(3C)],
and should not be used for other purposes.
.PP
\f4getdents\fP
will fail if one or more of the following are true:
.TP 15
\f4EBADF\fP
.I fildes\^
is not a valid file descriptor open for reading.
.TP
\f4EFAULT\fP
.I buf\^
points outside the allocated address space.
.TP
\f4EINVAL\fP
.I nbyte\^
is not large enough for one directory entry.
.TP
\f4ENOENT\fP
The current file pointer for the directory
is not located at a valid entry.
.TP
\f4ENOLINK\fP
.I fildes\^
points to a remote machine and the link to that
machine is no longer active.
.TP
\f4ENOTDIR\fP
.I fildes\^
is not a directory.
.TP
\f4EIO\fP
An I/O error occurred while accessing the file system.
.SH "SEE ALSO"
\f4directory\fP(3C).
.br
\f4dirent\fP(4) in the \f2System Administrator's Reference Manual\f1.
.SH "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
\f4errno\fP
is set to indicate the error.
.Ee
