readdir()

Read a directory entry

Synopsis:

#include <dirent.h>

struct dirent * readdir( DIR * dirp );

Arguments:

dirp: A pointer to the directory stream to be read.

Library:

libc

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

Description:

The readdir() function reads the next directory entry from the directory specified by dirp, which is the value returned by a call to opendir().

You can call readdir() repeatedly to list all of the entries contained in the directory specified by the pathname given to opendir(). The closedir() function must be called to close the directory stream and free the memory allocated by opendir().

The <dirent.h> file defines the struct dirent and the DIR type used by the readdir() family of functions.

The result of using a directory stream after one of the exec*() or spawn*() family of functions is undefined. After a call to fork(), either the parent or the child (but not both) can continue processing the directory stream, using the readdir() and rewinddir() functions. If both the parent and child processes use these functions, the result is undefined. Either (or both) processes may use closedir().

The <dirent.h> file also defines the following macros for accessing extra data associated with the dirent structure:

_DEXTRA_FIRST( pdirent ): Get a pointer to the first block of data associated with the structure pointed to by pdirent.
_DEXTRA_NEXT( last): Get the block of data that follows the block pointed to by last.
_DEXTRA_VALID( extra, pdirent): Evaluates to 1 if extra is a pointer to a valid block of data associated with the structure pointed to by pdirent.

The blocks of data are dirent_extra or dirent_extra_stat structures:

struct dirent_extra {
    uint16_t            d_datalen;      /* data size (without header) */
    uint16_t            d_type;
    uint32_t            d_reserved;
    /* unsigned char    d_data[d_datalen] */
};

struct dirent_extra_stat {
    uint16_t            d_datalen;      /* sizeof(struct stat) */
    uint16_t            d_type;
    uint32_t            d_reserved;
    struct stat         d_stat;
};

You can use these macros to traverse the data associated with the dirent structure like this:

for( extra = _DEXTRA_FIRST(dirent); 
    _DEXTRA_VALID(extra, dirent); 
    extra = _DEXTRA_NEXT(extra)) {
      switch(extra->d_type) {
        /* No data */
         case _DTYPE_NONE  : 
            break;
         /* Data includes information as returned by stat() */
         case _DTYPE_STAT  :
            break;
         /* Data includes information as returned by lstat() */
         case _DTYPE_LSTAT : 
            break;
         …
     }
}

If the value of the d_type member is _DTYPE_STAT or _DTYPE_LSTAT, the d_stat member points to a stat structure (see the entry for stat() in this reference). You can use the dircntl() function to request that the filesystem include this extra information.

Returns:

A pointer to a struct dirent object for success, or NULL if the end of the directory stream is encountered or an error occurs (errno is set).

A returned value of NULL is ambiguous; if you need to determine if it indicates an error (as opposed to the end of the directory stream), set errno to EOK before each call to this function.
Although dirent is declared with a one-byte d_name field, the structure that readdir() returns is allocated with enough space to hold the entire name.
Subsequent calls to readdir() with the same directory stream may overwrite the memory that the returned pointer points to.

Errors:

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.

Examples:

Get a list of files contained in the directory /home/fred:

#include <stdio.h>
#include <dirent.h>
#include <stdlib.h>

int main( void )
{
    DIR* dirp;
    struct dirent* direntp;

    dirp = opendir( "/home/fred" );
    if( dirp != NULL ) {
        for(;;) {
            direntp = readdir( dirp );
            if( direntp == NULL ) break;

            printf( "%s\n", direntp->d_name );
        }

        closedir( dirp );
        
        return EXIT_SUCCESS;
    }

    return EXIT_FAILURE;
}

Classification:

POSIX 1003.1

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