POSIX compliant directory functions

This page contains information about my dirent implementation for Microsoft Windows. However, the information you find from this page is mostly applicable to any POSIX compliant dirent implementation. You can download my implementation from here.

Contents:

• opendir - open directory stream
• readdir - read directory entry
• closedir - close directory stream
• rewinddir - rewind directory stream to beginning
• dirent example: recursive directory scanning

Other sources of information:

http://www.opengroup.org/

contains information about contents of dirent.h header, manual pages of each function defined in it and some examples of their use.

http://www.rs6000.ibm.com/

Contains information about AIX dirent data structures and functions. See the pages if you want to know some more differences between dirent implementations.

opendir - open directory stream for reading

Syntax:

DIR *opendir( const char *dirname);

Description:

The opendir() function opens named directory for reading and returns pointer to internal working area that can be used to retrieve individual directory entries. The internal working area has no fields of your interest.

Return value:

Pointer to internal working area or NULL if directory stream could not be opened. Global errno variable is set in case of error as follows:

EACESS

Permission denied.

EMFILE

Too many open files used by the process.

ENFILE

Too many open files in system.

ENOENT

Directory does not exist.

ENOMEM

Insufficient memory.

ENOTDIR

dirname does not refer to directory. This value is not reliable on MS-DOS and MS-Windows platforms. Many implementations return ENOENT even when the name does not refer to a directory.

readdir - read directory entry

Syntax:

struct dirent *readdir( DIR *dir);

Description:

Read individual directory entry and return pointer to a structure containing the name of the entry. Individual entries returned include normal files, sub-directories, "." and ".." entries, and also volume labels, hidden- and system files in MS-DOS and MS-Windows platforms. You may wish to use stat() function to determinate which one are you dealing with. (You can find information about stat() for example from http://menger.eecs.stevens-tech.edu/. The information seems to be a bit UNIX specific.)

The dirent structure that is returned by the readdir() function contains only one portable field: char d_name[]. The field contains the name of the directory entry without leading path. By the way, the length of d_name is unspecified; POSIX standard says it is at least NAME_MAX characters (without terminating null character), in MS-DOS it is exactly 13 characters (16-bit applications), in Windows 32-bit it is equal to MAX_PATH characters. The message is this: there is no portable way to find out length of d_name. Use sizeof(ptr->d_name) whenever you need to find out true length of d_name. Unfortunately, not all compilers allow the use of sizeof() in variable declarations.

Notes:

• If you create files or sub-directories while scanning the directory, you may not see them all in directory scan.
• Contents of the dirent structure are overwritten by each call to readdir() with same dir pointer.
• Some documents in the internet say that readdir() returns also deleted files the QNX operating system, at least when compiled with Watcom C/C++.

Return value:

Pointer to structure containing name of the directory entry in d_name field or NULL if there was an error. In case of an error, the global errno variable is set as follows:

EBADF

dir refers to invalid directory stream. This value is not reliable on all implementations.

closedir - close directory stream

Syntax:

int closedir(DIR *dir);

Description:

Close directory stream opened by the opendir() function. Close of directory stream invalidates the DIR structure as well as previously returned dirent structure that was read from the directory stream.

Return value:

0 on success and -1 on failure, but may return void in some other implementations. Void is returned at least in Borland C/C++.

The global errno variable is set to EBADF in case of error.

rewinddir - rewind directory stream to beginning

Syntax:

void rewinddir(DIR *dir);

Description:

Reset the directory stream to it's beginning so that next readdir() call returns the first directory entry. Note that next readdir() call may not return the same directory entry as it did in first time; the directory stream may be affected by newly created files.

Return value:

Nothing. If something went wrong while rewinding, you will notice it later when you try to retrieve next entry.