The Open Group Base Specifications Issue 7
IEEE Std 1003.1-2008, 2016 Edition
Copyright © 2001-2016 The IEEE and The Open Group

#### NAME

> dirent.h - format of directory entries

#### SYNOPSIS

> `#include <dirent.h>`

#### DESCRIPTION

> The internal format of directories is unspecified.

> The <dirent.h> header shall define the following type:

> DIR
>   A type representing a directory stream. The DIR type may be an incomplete type.

> It shall also define the structure dirent which shall include the following members:

>     [XSI]
>     ino_t  d_ino       File serial number.

>     char   d_name[]    Filename string of entry.

> [XSI] The <dirent.h> header shall define the ino_t type as described in <sys/types.h>.

> The array d_name is of unspecified size, but shall contain a filename of at most {NAME_MAX} bytes followed by a terminating null byte.

> The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

>     int            alphasort(const struct dirent **, const struct dirent **);
>     int            closedir(DIR *);
>     int            dirfd(DIR *);
>     DIR           *fdopendir(int);
>     DIR           *opendir(const char *);
>     struct dirent *readdir(DIR *);
>     int            readdir_r(DIR *restrict, struct dirent *restrict,
>                        struct dirent **restrict);
>     void           rewinddir(DIR *);
>     int            scandir(const char *, struct dirent ***,
>                        int (*)(const struct dirent *),
>                        int (*)(const struct dirent **,
>                        const struct dirent **));
>     [XSI]
>     void           seekdir(DIR *, long);
>     long           telldir(DIR *);

The following sections are informative.

#### APPLICATION USAGE

> None.

#### RATIONALE

> Information similar to that in the <dirent.h> header is contained in a file <sys/dir.h> in 4.2 BSD and 4.3 BSD. The equivalent in these implementations of struct dirent from this volume of POSIX.1-2008 is struct direct. The filename was changed because the name <sys/dir.h> was also used in earlier implementations to refer to definitions related to the older access method; this produced name conflicts. The name of the structure was changed because this volume of POSIX.1-2008 does not completely define what is in the structure, so it could be different on some implementations from struct direct.

> The name of an array of char of an unspecified size should not be used as an lvalue. Use of:

>     sizeof(d_name)

> is incorrect; use:

>     strlen(d_name)

> instead.

> The array of char d_name is not a fixed size. Implementations may need to declare struct dirent with an array size for d_name of 1, but the actual number of bytes provided matches (or only slightly exceeds) the length of the filename string.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> <sys/types.h>

> XSH alphasort, closedir, dirfd, fdopendir, readdir, rewinddir, seekdir, telldir

#### CHANGE HISTORY

> First released in Issue 2.

#### Issue 5

> The DESCRIPTION is updated for alignment with the POSIX Threads Extension.

#### Issue 6

> The Open Group Corrigendum U026/7 is applied, correcting the prototype for readdir_r().

> The restrict keyword is added to the prototype for readdir_r().

#### Issue 7

> The alphasort(), dirfd(), and scandir() functions are added from The Open Group Technical Standard, 2006, Extended API Set Part 1.

> The fdopendir() function is added from The Open Group Technical Standard, 2006, Extended API Set Part 2.

> Austin Group Interpretation 1003.1-2001 #110 is applied, clarifying the definition of the DIR type.

> POSIX.1-2008, Technical Corrigendum 1, XBD/TC1-2008/0039 [291], XBD/TC1-2008/0040 [291], XBD/TC1-2008/0041 [291], and XBD/TC1-2008/0042 [206] are applied.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2016 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]