directory(3C) DG/UX 5.4R3.00 directory(3C)
NAME
directory: opendir, readdir, readdir_r, telldir, seekdir, rewinddir,
closedir - directory operations
SYNOPSIS
#include <sys/types.h>
#include <dirent.h>
DIR *opendir (const char *filename);
struct dirent *readdir (DIR *dirp);
struct dirent *readdir_r (DIR *dirp, struct dirent *result);
long telldir (DIR *dirp);
void seekdir (DIR *dirp, long loc);
void rewinddir (DIR *dirp);
int closedir (DIR *dirp);
Alternate Syntax
#include <sys/dir.h>
struct direct *readdir (DIR *dirp);
DESCRIPTION
opendir opens the directory named by filename and associates a
directory stream with it. opendir returns a pointer to be used to
identify the directory stream in subsequent operations. The
directory stream is positioned at the first entry. A null pointer is
returned if filename cannot be accessed or is not a directory, or if
it cannot malloc(3C) enough memory to hold a DIR structure or a
buffer for the directory entries.
readdir returns a pointer to the next active directory entry and
positions the directory stream at the next entry. No inactive
entries are returned. It returns NULL upon reaching the end of the
directory or upon detecting an invalid location in the directory.
readdir buffers several directory entries per actual read operation;
readdir marks for update the st_atime field of the directory each
time the directory is actually read.
readdir_r works like readdir, with the exception that the caller must
allocate storage sufficient to hold a struct dirent plus the
filename. One way to obtain the needed size is sizeof(struct
dirent)+pathconf(dir,_PC_PATH_MAX). readdir_r returns the value
value of result if successful. Otherwise, readdir_r returns NULL to
indicate the end of the directory or an error condition.
telldir returns the current location associated with the named
directory stream.
Licensed material--property of copyright holder(s) 1
directory(3C) DG/UX 5.4R3.00 directory(3C)
seekdir sets the position of the next readdir (or readdir_r)
operation on the directory stream. The new position reverts to the
position associated with the directory stream at the time the telldir
operation that provides loc was performed. Values returned by
telldir are valid only if the directory has not changed because of
compaction or expansion. This situation is not a problem with System
V, but it can be with DG/UX and some file system types.
rewinddir resets the position of the named 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 opendir would.
closedir closes the named directory stream and frees the DIR
structure.
The following errors can occur as a result of these operations.
opendir returns NULL on failure and sets errno to one of the
following values:
ENOTDIR A component of filename is not a directory.
EACCES A component of filename denies search permission.
EACCES Read permission is denied on the specified
directory.
EMFILE The maximum number of file descriptors are
currently open.
ENFILE The system file table is full.
EFAULT filename points outside the allocated address
space.
ELOOP Too many symbolic links were encountered in
translating filename.
ENAMETOOLONG The length of the filename argument exceeds
{PATH_MAX}, or the length of a filename component
exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is in
effect.
ENOENT A component of filename does not exist or is a
null pathname.
readdir and readdir_r return NULL on failure and set errno to one of
the following values:
ENOENT The current file pointer for the directory is not
located at a valid entry.
EBADF The file descriptor determined by the DIR stream
Licensed material--property of copyright holder(s) 2
directory(3C) DG/UX 5.4R3.00 directory(3C)
is no longer valid. This result occurs if the
DIR stream has been closed.
telldir, seekdir, and closedir return -1 on failure and set errno to
the following value:
EBADF The file descriptor determined by the DIR stream
is no longer valid. This results if the DIR
stream has been closed.
Considerations for Threads Programming
+----------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+----------+-----------------------------+
|closedir | Y N N |
|opendir | Y N N |
|readdir | N - - |
|readdir_r | Y Y N |
|rewinddir | Y Y N |
|telldir | Y N N |
|seekdir | Y N N |
+----------+-----------------------------+
If the same DIR stream is shared among multiple threads, entries
returned by readdir_r will be in an indeterminate order, and each
sharing thread will only see a portion of the entries. Also, the
results of other directory operations may be indeterminate since
other threads may concurrently reposition the directory pointer. For
example, calling telldir followed by seekdir and readdir_r would not
necessarily return the directory entry sought - other threads could
call readdir_r between seemingly sequential calls to seekdir and
readdir_r. One way to deal with this problem could be the use of an
application level mutex lock associated with the DIR structure.
EXAMPLE
Here is a sample program that prints the names of all the files in
the current directory:
#include <stdio.h>
#include <dirent.h>
main()
{
DIR *dirp;
struct dirent *direntp;
dirp = opendir( "." );
while ( (direntp = readdir( dirp )) != NULL )
(void)printf( "%s\n", direntp->d_name );
closedir( dirp );
return (0);
Licensed material--property of copyright holder(s) 3
directory(3C) DG/UX 5.4R3.00 directory(3C)
}
SEE ALSO
getdents(2), dirent(4), reentrant(3).
Licensed material--property of copyright holder(s) 4