POSIX Directory Browsing API for Windows
The functions and types specified in POSIX for iterating over directory
entries have been defined here as wrappers for porting to and common use on
Windows platforms. The values of errno set in the event of errors
are the most significant difference between the POSIX definition and the
wrapper API.
In addition to this documentation file, the software is provided in the
dirent.h header file and the
dirent.c C source file. To use the API
ensure that the path to the dirent.h header is either somewhere
standard or is provided to the compiler as an additional option. Ensure also
that the dirent.c file is compiled and the object file is either
referenced explicitly in the link or included in a referenced library. The
source code also compiles cleanly as C++, but it retains C linkage.
<dirent.h>
typedef ... DIR;
struct dirent
{
char *d_name;
};
DIR *opendir(const char *name);
int closedir(DIR *dir);
struct dirent *readdir(DIR *dir);
void rewinddir(DIR *dir);
DIR *opendir(const char *name);
Description
The opendir function opens the directory specified by
name, which may use either / or \ as a
directory separator but should not contain any wildcards. On success
it associates a DIR stream with the open directory. A non-null
DIR stream may be used in subsequent calls to
readdir, rewinddir and
closedir.
A successful result will position the DIR stream at the first
directory entry, ready for reading. Note that a truly empty directory
(one without even . or .. entries) will not open
successfully.
Returns
A pointer to the DIR structure for the opened directory on
success, otherwise null on failure.
Errors
ENOENT No such directory.
EINVAL Invalid argument or directory name.
ENOMEM Not enough memory to perform the operation.
int closedir(DIR *dir);
Description
The closedir function closes the directory stream associated with
dir, freeing resources as necessary and invalidating the
dir pointer.
Returns
Returns 0 on successful completion, otherwise -1.
Errors
EBADF Invalid directory stream.
struct dirent *readdir(DIR *dir);
Description
The readdir function is used to iterate through the directory
stream dir. It advances it one entry at a time, details of which
it returns as its result.
On NTFS and FAT file systems, except for drive root directories, the caller
is guaranteed that the . and .. entries will be included
in the directory stream. On FATX file systems the . and
.. entries are not included.
Returns
Returns a pointer to the directory details on success, in which
d_name is the file name of the current entry, otherwise null
on error or end of stream.
Errors
ENOENT No more entries.
EBADF Invalid directory stream.
void rewinddir(DIR *dir);
Description
The rewindir function can be used to reset the directory stream
dir to the start. Sensible results cannot be guaranteed if the
directory name used in the initial call to opendir was a
relative path name and the program has since changed its current working
directory.
Returns
No error status is returned.
Errors
EBADF Invalid directory stream.