readdir(), readdir64()

read directory 

Function


SYNOPSIS

#include <sys/types.h>

#include <dirent.h>

struct dirent *readdir(DIR* dirp);

struct dirent64 *readdir64(DIR* dirp);


DESCRIPTION

The readdir() function returns a pointer to a structure that represents the directory entry at the current position in the directory stream that dirp refers to, and then positions the directory stream to the next entry. readdir() returns a NULL pointer when it reaches the end of the directory stream.

The readdir64() function is similar to the readdir() function, and is a part of the large file extensions.

An entry for dot (.) and dot-dot (..) is returned for all directories except the root of a file system (e.g. /c=/), in the normal Windows way.

The pointer that readdir() returns points to data that can be overwritten by another call to readdir() on the same directory stream. However, another call to readdir() on a different directory stream does not overwrite the data.

If a file is removed from the directory after the most recent call to opendir() or rewinddir(), a subsequent call to readdir() returns an entry for that file. If a file is added to the directory after the most recent call to opendir() or rewinddir(), a subsequent call to readdir() does not return an entry for the added file.

readdir() fills all the members of the dirent structure except d_ino which is always set to 0.

The readdir() function returns a pointer to an object of type struct dirent that includes the member d_name. The size of the d_name array is not specified; however, the number of bytes preceding the terminating null character cannot exceed NAME_MAX.

After a call to fork(), both parent and child can independently continue processing the directory stream using readdir() or rewinddir() or both. Directory streams are closed after a successful call to exec() and hence the child process cannot use the directory streams opened in the parent process.


PARAMETERS

dirp 

Points to the directory stream to be read.


RETURN VALUES

If successful, readdir() and readdir64() return a pointer to an object of type struct dirent or struct dirent64, respectively. This structure is copied into static memory specific to the directory stream being read. (Subsequent calls to readdir() or readdir64() on the same directory stream overwrites this memory area.). When the operation encounters the end of a directory, readdir() returns a NULL pointer and does not change errno to indicate the error. On failure, readdir() and readdir64() return a NULL pointer and set errno to one of the following values:

EBADF 

dirp does not refer to an open directory stream.

EOVERFLOW 

One of the values in the structure to be returned cannot be represented correctly.


CONFORMANCE

POSIX.1 (1996).

readdir64(): Large File Specification, revision 1.5.


MULTITHREAD SAFETY LEVEL

Unsafe.


PORTING ISSUES

File and Directory names are returned as multibyte sequences and are converted from Unicode (UTF-16) before returning from Win32. The conversion is either performed based on the current thread locale, set using uselocale() or the process locale as set by a call to setlocale(), and overridden by _NutConf() _NC_SET_ANSI_LOCALE and _NC_SET_UTF8_LOCALE options. Under all other conditions, the multibyte sequences are considered to be from the ANSI code page for the current windows system locale.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
closedir(), opendir(), readdir_r(), rewinddir(), scandir(), seekdir(), telldir(), xlocale()

Miscellaneous:
lf64


PTC MKS Toolkit 10.1 Documentation Build 15.