DIRECTORY(3X) SysV DIRECTORY(3X)
NAME
directory: opendir, opendir_r, readdir, readdir_r, telldir, seekdir,
rewinddir, closedir - directory operations
SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
DIR *opendir (dir_name)
const char *dir_name;
int opendir_r (dir_name, dir_pointer)
const char *dir_name;
DIR *dir_pointer;
struct dirent *readdir (dir_pointer)
DIR *dir_pointer;
int readdir_r (dir_pointer, result)
DIR *dir_pointer;
struct dirent *result;
long telldir (dir_pointer)
DIR *dir_pointer;
void seekdir (dir_pointer, location)
DIR *dir_pointer;
long location;
void rewinddir (dir_pointer)
DIR *dir_pointer;
void closedir(dir_pointer)
DIR *dir_pointer;
DESCRIPTION
The opendir function opens the directory designated by the dir_name
argument and associates a directory stream with it. If the final
component of dir_name names a symbolic link, the link will be traversed
and pathname resolution will continue.
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. The type DIR is implemented in Domain/OS using a
file descriptor. Thus, applications will be able to open a total of
{OPEN_MAX} files and directories. The FD_CLOEXEC flag will be set on that
file descriptor.
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 argument, 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 dirent structure has the following members:
ino_t d_ino File serial number
char d_name[] Name of 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 argument to the
position specified by the location argument. If the value of the
location argument 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
argument 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 argument. 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.
The opendir_r and readdir_r functions are the reentrant versions of the
opendir and readdir functions, respectively. The opendir_r function
stores the new directory stream associated with dir_name at dir_pointer.
The readdir_r function stores the next directory entry at result.
EXAMPLE
Sample code which searches a directory for entry name:
DIR *dirp;
struct dirent *dp;
dirp = opendir( "." );
while ( (dp = readdir( dirp )) != NULL )
if ( strcmp( dp->d_name, name ) == 0 )
{
closedir( dirp );
return FOUND;
}
closedir( dirp );
return NOT_FOUND;
DIAGNOSTICS
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 seekdir function returns 0 (zero).
Otherwise, -1 is returned.
Upon successful completion, the rewinddir function returns 0 (zero).
Otherwise, -1 is returned.
Upon successful completion, the closedir function returns 0 (zero).
Otherwise, -1 is returned.
Upon successful completion, the opendir_r function returns 0 (zero).
Otherwise, -1 is returned.
Upon successful completion, 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.
[ENAMETOOLONG]
The length of the dir_name string exceeds PATH_MAX, or a
pathname component is longer than NAME_MAX.
[ENOENT] The dir_name argument points to the name of a file which does
not exist, or the argument points to an empty string.
[ENOTDIR] A component of dir_name is not a directory.
[EMFILE] The maximum number of file descriptors are currently open.
[EFAULT] filename points outside the allocated address space.
readdir:
[ENOENT] The current file pointer for the directory is not located at a
valid entry.
[EBADF] The file descriptor determined by the DIR stream is no longer
valid. This results if the DIR stream has been closed.
telldir, seekdir, and closedir:
[EBADF] The file descriptor determined by the DIR stream is no longer
valid. This results if the DIR stream has been closed.
SEE ALSO
close(2), lseek(2), open(2), getdents(2), read(2).
WARNINGS
rewinddir is implemented as a macro, so its function address cannot be
taken.