getdents(2)getdents(2)NAME
getdents, getdents64, ngetdents, ngetdents64 - read directory entries and
put in a file system independent format
C SYNOPSIS
#include <sys/dirent.h>
int getdents(int fildes, dirent_t *buf, unsigned nbyte);
int getdents64(int fildes, dirent64_t *buf, unsigned nbyte);
int ngetdents(int fildes, dirent_t *buf, unsigned nbyte, int *eof);
int ngetdents64(int fildes, dirent64_t *buf, unsigned nbyte, int *eof);
DESCRIPTION
fildes is a file descriptor obtained from a creat, open, dup, fcntl,
pipe, or ioctl 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 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).
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 routine
[for a description, see directory(3C)], and should not be used for other
purposes.
getdents64 is identical to getdents except that the dirent64_t structure
is used instead of the dirent_t structure. The dirent64_t structure can
return larger values for some fields.
ngetdents and ngetdents64 are identical to getdents and getdents64,
respectively, except that the eof argument is present. The value pointed
to by eof is set to 1 if end-of-file was encountered during the current
operation, 0 otherwise. Use of this feature eliminates the necessity to
call getdents one more time (and get 0 returned) after the last data is
returned.
getdents will fail if one or more of the following are true:
Page 1
getdents(2)getdents(2)
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. is located on a remote file
system which is not available [see intro(2)].
ETIMEDOUT fildes refers to a directory on a remote file system which
is not available [see intro(2)].
ENOTDIR fildes is not a directory.
EIO An I/O error occurred while accessing the file system.
EDIRCORRUPTED The directory is corrupted in the file system.
SEE ALSOdirectory(3C), 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.
Page 2
