| DIRECTORY(3) |
AerieBSD 1.0 Refernce Manual |
DIRECTORY(3) |
NAME
opendir —
readdir,
readdir_r,
telldir,
seekdir,
rewinddir,
closedir,
dirfd
directory operations
SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
DIR*
opendir(const char *filename);
structdirent *
readdir(DIR *dirp);
int
readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);
long
telldir(const DIR *dirp);
void
seekdir(DIR *dirp, long loc);
void
rewinddir(DIR *dirp);
int
closedir(DIR *dirp);
int
dirfd(DIR *dirp);
DESCRIPTION
The
opendir();
function opens the directory named by
filename,
associates a directory stream with it, and returns a pointer to be used
to identify the directory stream in subsequent operations.
On failure,
NULL
is returned and
errno
is set to indicate the error.
The
readdir();
function returns a pointer to the next directory entry in the named
directory stream
dirp.
It returns
NULL
upon reaching the end of the directory or detecting an invalid
seekdir();
operation.
The
readdir_r();
function (much like
readdir();)
initializes the
dirent
structure referenced by
entry
to represent the next directory entry in the named directory stream
dirp,
and stores a pointer to this structure at the location referenced by
result.
The storage pointed to by
entry
must be large enough for a dirent with a
d_name
array member containing at least
NAME_MAX
plus one elements.
On successful return, the pointer returned at
"*result"
will have the same value as the argument
entry.
Upon reaching the end of the directory stream, this pointer shall have the value
NULL.
The
telldir();
function returns the current location associated with the named
directory stream
dirp.
On failure, \-1 is returned and
errno
is set to indicate the error.
The
seekdir();
function sets the position of the next
readdir();
operation on the named directory stream
dirp.
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 may be invalidated due to undetected directory compaction.
The
rewinddir();
function resets the position of the named directory stream
dirp
to the beginning of the directory.
The
closedir();
function closes the named directory stream and frees the structure
associated with the
dirp
pointer, returning 0 on success.
On failure, \-1 is returned and the global variable
errno
is set to indicate the error.
The
dirfd();
function returns the integer file descriptor associated with the named
directory stream
dirp
(see
open(2/)).
EXAMPLES
Sample code which searches a directory for entry
“name”
is:
len = strlen(name);
dirp = opendir(".");
if (dirp) {
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);
ERRORS
The
opendir();
function will fail if:
- [ENOTDIR]
-
The supplied
filename
is not a directory.
The
opendir();
function may also fail and set
errno
for any of the errors specified for the routines
fcntl(2),
fstat(2),
open(2),
and
malloc(3).
The
readdir();
and
readdir_r();
functions may also fail and set
errno
for any of the errors specified for the routine
getdirentries(2).
The
telldir();
function may also fail and set
errno
for any of the errors specified for the routine
realloc(3).
The
closedir();
function may also fail and set
errno
for any of the errors specified for the routine
close(2).
SEE ALSO
close(2),
getdirentries(2),
lseek(2),
open(2),
dir(5)
HISTORY
The
opendir();,
readdir();,
telldir();,
seekdir();,
rewinddir();,
closedir();,
and
dirfd();
functions appeared in
4.2BSD.
| AerieBSD 1.0 Reference Manual |
May 14 2010 |
DIRECTORY(3) |