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.

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;
         …
     }
}

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

See also:

closedir(), dirent, errno, lstat(), opendir(), readdir_r(), rewinddir(), seekdir(), telldir(), stat()