opendir(3)opendir(3)NAME
opendir, readdir, readdir_r, telldir, seekdir, rewinddir, closedir -
Perform operations on directories
SYNOPSIS
#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 );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards 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.
PARAMETERS
Names the directory. If the final component of dir_name names a sym‐
bolic 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-direc‐
tory.
DESCRIPTION
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 direc‐
tory. 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 asyn‐
chronously 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 .. (dot-dot) 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 subse‐
quent 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() opera‐
tion 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 unde‐
fined.
The closedir() function closes a directory stream and frees the struc‐
ture 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 read‐
dir() 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.
NOTES
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 appli‐
cations. Instead, its reentrant equivalent, readdir_r, should be used
with multiple threads.
RETURN VALUES
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.
ERRORS
If the opendir() function fails, errno may be set to one of the follow‐
ing values: Search permission is denied for any component of dir_name
or read permission is denied for dir_name. Too many links were encoun‐
tered 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.
EXAMPLES
To search a directory for the entry name:
len = strlen(name); dir_pointer = opendir("."); for (dp = read‐
dir(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;
SEE ALSO
Functions: close(2), lseek(2), open(2), read(2), scandir(3)
Standards: standards(5)opendir(3)
