POSIX Directory Browsing API for Win32
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
Win32 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. This stream
is for use in subsequent browsing operations on the directory.
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
dirpointer.
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. Except for drive root directories, the caller
is guaranteed that the . and .. entries will be
included in the directory stream.
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.