opendir, readdir, readdir_r, telldir, seekdir, rewinddir,
closedir - Perform operations on directories
#include <sys/types.h> #include <dirent.h>
DIR *opendir(
const char *dir_name ); struct dirent *readdir(
DIR *dir_pointer ); int readdir_r(
DIR *dir_pointer,
struct dirent *entry,
struct dirent **result ); long telldir(
DIR *dir_pointer ); void seekdir(
DIR *dir_pointer,
long location ); void rewinddir(
DIR *dir_pointer ); int closedir(
DIR *dir_pointer );
The following function does not conform to current industry
standards and is supported only for backward compatibility:
int readdir_r(
DIR *dir_pointer,
struct dirent *result );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
closedir(): POSIX.1, XPG4, XPG4-UNIX
opendir(): POSIX.1, XPG4, XPG4-UNIX
readdir(): POSIX.1c, XPG4, XPG4-UNIX
readdir_r(): POSIX.1c
rewinddir(): POSIX.1, XPG4, XPG4-UNIX
seekdir(): POSIX.1, XPG4, XPG4-UNIX
telldir(): POSIX.1, XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Names the directory. If the final component of dir_name
names a symbolic link, the link will be traversed and
pathname resolution will continue. Points to the dir
structure of an open directory. Points to the storage
location that will hold the entry. Specifies the number
of an entry relative to the start of the directory. Contains
the next directory entry on return from the readdir_r()
function. Set equal to entry upon successful completion
or to NULL on error or end-of-directory.
The opendir() function opens the directory designated by
the dir_name parameter and associates a directory stream
with it. The directory stream is positioned at the first
entry. The type DIR, which is defined in the dirent.h
header file, represents a directory stream, which is an
ordered sequence of all the directory entries in a particular
directory. If a file descriptor is used, the
FD_CLOEXEC option will be set on that file descriptor.
The opendir() function also returns a pointer to identify
the directory stream in subsequent operations. The null
pointer is returned when the directory named by the
dir_name parameter cannot be accessed or when not enough
memory is available to hold the entire stream.
The type DIR, which is defined in the dirent.h header
file, represents a directory stream, which is an ordered
sequence of all the directory entries in a particular
directory. Directory entries represent files; files may be
removed from a directory or added to a directory asynchronously
to the operation of the readdir() function.
The readdir() function returns a pointer to a structure
representing the directory entry at the current position
in the directory stream specified by the dir_pointer
parameter, and positions the directory stream at the next
entry. It returns a null pointer upon reaching the end of
the directory stream. The dirent structure defined in the
dirent.h header file describes a directory entry.
The readdir() function will not return directory entries
containing empty names. If entries for . (dot) or .. (dotdot)
exist, one entry will be returned for . (dot) and one
entry will be returned for .. (dot-dot); otherwise, they
will not be returned.
The pointer returned by the readdir() function points to
data which may be overwritten by another call to readdir()
on the same directory stream. This data will not be overwritten
by another call to readdir() on a different directory
stream.
If a file is removed from or added to the directory after
the most recent call to the opendir() or rewinddir() function,
whether a subsequent call to the readdir() function
returns an entry for that file is unspecified.
The readdir() function may buffer several directory
entries per actual read operation; the readdir() function
marks for update the st_atime field of the directory each
time the directory is actually read.
When it reaches the end of the directory, or when it
detects an invalid seekdir() operation, the readdir()
function returns the null value.
The telldir() function returns the current location associated
with the specified directory stream.
The seekdir() function sets the position of the next readdir()
operation on the directory stream specified by the
dir_pointer parameter to the position specified by the
location parameter.
If the value of the location parameter was not returned by
a call to the telldir() function, or if there was an
intervening call to the rewinddir() function on this
directory stream, the effect is undefined. The new position
reverts to the one associated with the directory
stream when the telldir() operation was performed.
An attempt to seek to an invalid location causes the readdir()
function to return the null value the next time it
is called. The position should be that returned by a previous
telldir() function call.
The rewinddir() function resets the position of the specified
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 a call to
the opendir() function would have done. If the dir_pointer
parameter does not refer to a directory stream, the effect
is undefined.
The closedir() function closes a directory stream and
frees the structure associated with the dir_pointer parameter.
Upon return, the value of dir_pointer may no longer
point to an accessible object of the type DIR. If a file
descriptor is used to implement type DIR, that file
descriptor will be closed.
[POSIX] The readdir_r() function is the reentrant version
of the readdir() function. The readdir_r() function stores
the next directory entry at entry, and returns entry in
result. On end-of-directory, NULL is stored in result and
0 (zero) is returned.
An open directory must always be closed with the
closedir() function to ensure that the next attempt to
open that directory is successful.
The use of the seekdir() and telldir() functions is not
recommended in the Tru64 UNIX operating system, as the
results can be unpredictable.
[POSIX] The readdir function is not supported for multithreaded
applications. Instead, its reentrant equivalent,
readdir_r, should be used with multiple threads.
Upon successful completion, the opendir() function returns
a pointer to an object of type DIR. Otherwise, null is
returned and errno set to indicate the error.
Upon successful completion, the readdir() function returns
a pointer to an object of type struct dirent. When an
error is encountered, a null pointer is returned and errno
is set to indicate the error. When the end of the directory
is encountered, a null pointer is returned and errno
is not changed.
Upon successful completion, the telldir() function returns
the current location. Otherwise, -1 is returned.
Upon successful completion, the closedir() function
returns 0 (zero). Otherwise, -1 is returned.
[POSIX] Upon successful completion or end-of-directory,
the readd_r() function returns 0 (zero). Otherwise, an
error number is returned.
[Tru64 UNIX] Upon successful completion, the obsolete
version of the readdir_r() function returns 0 (zero). Otherwise,
-1 is returned.
If the opendir() function fails, errno may be set to one
of the following values: Search permission is denied for
any component of dir_name or read permission is denied for
dir_name. Too many links were encountered in translating
dir_name. The length of the dir_name string exceeds
PATH_MAX, or a pathname component is longer than NAME_MAX.
The dir_name parameter points to the name of a file that
does not exist, or the parameter points to an empty
string. A component of dir_name is not a directory.
To search a directory for the entry name:
len = strlen(name); dir_pointer = opendir("."); for (dp =
readdir(dir_pointer); dp != NULL; dp = readdir(dir_pointer))
if (dp->d_namlen == len && !strcmp(dp->d_name,
name)) {
closedir(dir_pointer);
return FOUND;
}
closedir(dir_pointer); return NOT_FOUND;
Functions: close(2), lseek(2), open(2), read(2), scandir(3)
Standards: standards(5)
opendir(3)
[ Back ] |
