DIRECTORY(3) | Library Functions Manual | DIRECTORY(3) |
fdopendir
, opendir
,
readdir
, readdir_r
,
telldir
, seekdir
,
rewinddir
, closedir
,
dirfd
—
#include <dirent.h>
DIR *
opendir
(const
char *filename);
DIR *
fdopendir
(int
fd);
struct dirent *
readdir
(DIR
*dirp);
int
readdir_r
(DIR
* restrict dirp, struct
dirent * restrict entry,
struct dirent ** restrict
result);
long
telldir
(DIR
*dirp);
void
seekdir
(DIR
*dirp, long
loc);
void
rewinddir
(DIR
*dirp);
int
closedir
(DIR
*dirp);
int
dirfd
(DIR
*dirp);
opendir
(filename)opendir
() function opens the directory named
by filename and associates a directory stream with
it. The directory stream is positioned at the first entry. Upon successful
completion, a pointer to DIR type is returned.
Otherwise, opendir
() returns
NULL
.fdopendir
(fd)fdopendir
() function associates a directory
stream with the directory file descriptor fd. The
file offset associated with fd at the time of the
call determines which entries are returned.
Upon failure, fdopendir
() returns
NULL
. Otherwise the file descriptor is under the
control of the system, and if any attempt is made to close the file
descriptor, or to modify the state of the associated description, other
than by means of closedir
(),
readdir
(), readdir_r
(),
rewinddir
(), the behavior is undefined. The file
descriptor can be closed by calling
closedir
().
readdir
(dirp)readdir
() function returns a pointer to the
directory entry at the current position in the directory stream specified
by dirp, and positions the directory stream at the
next entry. It returns NULL
upon reaching the end
of the directory or detecting an invalid seekdir
()
operation. The returned structure is described in
dirent(3).
The returned pointer to the dirent structure
points to data which may be overwritten by another call to
readdir
() on the same directory stream. This
data is not however overwritten by another call to
readdir
() on a different directory stream.
readdir_r
(dirp,
entry, result)readdir_r
() function provides the same
functionality as readdir
(), but the caller must
provide a directory entry buffer to store the
results in. If the read succeeds, result is pointed
at the entry; upon reaching the end of the directory
result is set to NULL
. The
readdir_r
() function returns 0 on success or an
error number to indicate failure.
Like readdir
(), the
readdir_r
() function may buffer several
directory entries per actual read operation. Both functions mark for
update the st_atime field (see
stat(2)) of the directory
each time the directory is actually read.
telldir
(dirp)telldir
() function returns the current
location associated with the directory stream specified by
dirp.
If the most recent operation on the particular directory
stream was a seekdir
(), the directory position
returned from telldir
() is the same as
loc supplied as an argument to the
seekdir
() call.
seekdir
(dirp,
loc)seekdir
() function sets the position of the
next readdir
() operation on the directory stream
specified by dirp. The value of
loc should come from a previous call to
telldir
() using the same directory stream.
The new position reverts to the one associated with the
directory stream when the telldir
() operation
was performed. Values returned by telldir
() are
good only for the lifetime of the DIR pointer,
dirp, from which they are derived. If the
directory is closed and then reopened, the
telldir
() value cannot be re-used.
rewinddir
(dirp)rewinddir
() function resets the position of
the named directory stream to the beginning of the directory. It also
causes the directory stream to refer to the current state of the
corresponding directory, as if a call to opendir
()
would have been made.
If dirp does not refer to a valid directory stream, the behavior is undefined.
closedir
(dirp)closedir
() function closes the directory
stream and frees the structure associated with the
dirp pointer, returning 0 on success and -1 on
failure.dirfd
(dirp)dirfd
() function returns the integer file
descriptor associated with the directory stream specified by
dirp. Upon failure, dirfd
()
returns -1. The returned file descriptor should not be closed by
close(2), it will be released
when dirp is closed with
closedir
().
The rationale of dirfd
() is to provide
a mechanism by which a file descriptor can be obtained for the use of
the fchdir(2)
function.
len = strlen(name); dirp = opendir("."); if (dirp != NULL) { while ((dp = readdir(dirp)) != NULL) if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { (void)closedir(dirp); return (FOUND); } (void)closedir(dirp); } return (NOT_FOUND);
The following additional remarks can be noted from the IEEE Std 1003.1-2008 (“POSIX.1”) standard.
OPEN_MAX
files and directories.
Otherwise the limit is left as unspecified.closedir
() function behaves as if the
FD_CLOEXEC
had been set for the file descriptor.
In another words, it is mandatory that closedir
()
deallocates the file descriptor.dirfd
() may fail with
ENOTSUP
.opendir
() or
rewinddir
(), it is unspecified whether a
subsequent call to readdir
() returns an entry for
that file.seekdir
(), note that if
the value of loc was not obtained from an earlier
call to telldir
(), or if a call to
rewinddir
() occurred between the calls to
telldir
() and seekdir
(),
any subsequent call to readdir
() is unspecified,
possibly resulting in undefined behavior.readdir
(),
rewinddir
(), or seekdir
().
However, if both the parent and child processes use these functions, the
result is undefined.opendir
(), readdir
(),
rewinddir
() and closedir
()
functions conform to IEEE Std 1003.1-1990
(“POSIX.1”). The other functions conform to
IEEE Std 1003.1-2008 (“POSIX.1”).
opendir
(), readdir
(),
telldir
(), seekdir
(),
rewinddir
(), closedir
(), and
dirfd
() functions appeared in
4.2BSD. The fdopendir
()
function appeared in NetBSD 6.0.
January 22, 2016 | NetBSD 9.2 |