 |
Index for
Section 3 |
|
 |
Alphabetical
listing for O |
|
 |
Bottom of
page |
|
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 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.
PARAMETERS
dir_name
Names the directory. If the final component of dir_name names a
symbolic link, the link will be traversed and pathname resolution will
continue.
dir_pointer
Points to the dir structure of an open directory.
entry
Points to the storage location that will hold the entry.
location
Specifies the number of an entry relative to the start of the
directory.
result
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.
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 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 .. (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 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.
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
applications. 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 following
values:
[EACCES]
Search permission is denied for any component of dir_name or read
permission is denied for dir_name.
[ELOOP]
Too many links were encountered in translating dir_name.
[ENAMETOOLONG]
The length of the dir_name string exceeds PATH_MAX, or a pathname
component is longer than NAME_MAX.
[ENOENT]
The dir_name parameter points to the name of a file that does not
exist, or the parameter points to an empty string.
[ENOTDIR]
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 = 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;
SEE ALSO
Functions: close(2), lseek(2), open(2), read(2), scandir(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for O |
|
 |
Top of
page |
|