_readdir_r(), _readdir64

Read a directory and get stat information

Synopsis:

#include <sys/types.h>
#include <dirent.h>

int _readdir_r( DIR *dirp,
                struct dirent *entry,
                struct dirent **result,
                unsigned bufsize );

int _readdir64_r( DIR *dirp,
                  struct dirent64 *dirent,
                  struct dirent64 **result,
                  unsigned bufsize );

Arguments:

dirp: A pointer to the directory stream to be read.
entry: A pointer to a dirent or dirent64 structure where the function can store the directory entry.
result: The address of a location where the function can store a pointer to the information found.
bufsize: The size of the buffer that entry points to.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The _readdir_r() function is similar to readdir_r(), but provides extra stat() information.

The _readdir_r() and _readdir64_r() functions initialize the dirent structure referenced by entry with the directory entry at the current position in the directory stream referred to by dirp, store a pointer to this structure in *result, and position the directory stream at the next entry. If you've reached the end of the directory stream, these functions set *result to NULL. The _readdir64_r() function is a large-file support version of _readdir_r().

Note: In QNX Neutrino 6.6 or later, the large-file support functions and data types appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code. For more information, see “Classification” in What's in a Function Description?

The storage pointed to by entry must be large enough for a dirent or dirent64 structure with the d_name member an array of char containing at least NAME_MAX plus one element. The struct dirent and struct dirent64 structures don't include space for the pathname; you must provide it. For example:

struct dirent *entry;
entry = malloc( offsetof(struct dirent, d_name) + NAME_MAX + 1 );

Some filesystems support names that are longer than the value of NAME_MAX. You can use pathconf() with _PC_NAME_MAX to determine the maximum number of bytes (not including the terminating null) allowed in a file name for a particular filesystem.

The buffer can also include space for the additional information; the function copies as much stat() information as will fit in the buffer. The dirent_extra_stat information follows the path, at an 8-byte aligned offset from the start of the dirent structure. The size of the buffer should then be:

len = ((offsetof(struct dirent64, d_name) + pathconf(dirname, _PC_NAME_MAX) + 1 + 7) & ~7U)
      + sizeof(struct dirent_extra_stat);

For information about the dirent_extra_stat structure, see the entry for readdir()

Returns:

EOK: Success.
EBADF: The dirp argument doesn't refer to an open directory stream.
EOVERFLOW: One of the values in the structure to be returned can't be represented correctly.

Classification:

_readdir_r() is QNX Neutrino; _readdir64_r() is Large-file support

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes