Content-type: text/html Man page of opendir

opendir

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

opendir, readdir, readdir_r, telldir, seekdir, rewinddir, closedir - Performs operations on directories  

LIBRARY

Standard C Library (libc.a)  

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 standards and is supported only for backward compatibility:

int readdir_r (        DIR *dir_pointer,
       struct dirent *result );
 

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

rewinddirdir(): 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 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.  

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 flag 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.  

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;  

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.

[Digital]  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: 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.  

RELATED INFORMATION

Functions: close(2), lseek(2), open(2), read(2), scandir(3)

Standards: standards(5) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
EXAMPLES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:41:07 GMT, October 02, 2010