readdir(3)

1READDIR(3)                 Linux Programmer's Manual                READDIR(3)
2
3
4

NAME

6       readdir, readdir_r - read a directory
7

SYNOPSIS

9       #include <dirent.h>
10
11       struct dirent *readdir(DIR *dirp);
12
13       int readdir_r(DIR *dirp, struct dirent *entry, struct dirent **result);
14
15   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
16
17       readdir_r(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE ||
18       _SVID_SOURCE || _POSIX_SOURCE
19

DESCRIPTION

21       The readdir() function returns a pointer to a dirent  structure  repre‐
22       senting  the next directory entry in the directory stream pointed to by
23       dirp.  It returns NULL on reaching the end of the directory  stream  or
24       if an error occurred.
25
26       On Linux, the dirent structure is defined as follows:
27
28           struct dirent {
29               ino_t          d_ino;       /* inode number */
30               off_t          d_off;       /* offset to the next dirent */
31               unsigned short d_reclen;    /* length of this record */
32               unsigned char  d_type;      /* type of file; not supported
33                                              by all file system types */
34               char           d_name[256]; /* filename */
35           };
36
37       The  only  fields  in the dirent structure that are mandated by POSIX.1
38       are: d_name[], of unspecified size, with at  most  NAME_MAX  characters
39       preceding  the  terminating null byte; and (as an XSI extension) d_ino.
40       The other fields are unstandardized, and not present  on  all  systems;
41       see NOTES below for some further details.
42
43       The  data  returned by readdir() may be overwritten by subsequent calls
44       to readdir() for the same directory stream.
45
46       The readdir_r() function is a reentrant version of readdir().  It reads
47       the next directory entry from the directory stream dirp, and returns it
48       in the caller-allocated buffer pointed to by  entry.   (See  NOTES  for
49       information on allocating this buffer.)  A pointer to the returned item
50       is placed in *result; if the end of the directory  stream  was  encoun‐
51       tered, then NULL is instead returned in *result.
52

RETURN VALUE

54       On  success,  readdir() returns a pointer to a dirent structure.  (This
55       structure may be statically allocated; do not attempt to  free(3)  it.)
56       If  the  end  of  the directory stream is reached, NULL is returned and
57       errno is not changed.  If an error occurs, NULL is returned  and  errno
58       is set appropriately.
59
60       The  readdir_r() function returns 0 on success.  On error, it returns a
61       positive error number.  If the end of the directory stream is  reached,
62       readdir_r() returns 0, and returns NULL in *result.
63

ERRORS

65       EBADF  Invalid directory stream descriptor dirp.
66

CONFORMING TO

68       SVr4, 4.3BSD, POSIX.1-2001.
69

NOTES

71       Only  the  fields  d_name and d_ino are specified in POSIX.1-2001.  The
72       remaining fields are available on many, but  not  all  systems.   Under
73       glibc,  programs  can  check  for  the  availability  of the fields not
74       defined in POSIX.1 by testing whether the macros _DIRENT_HAVE_D_NAMLEN,
75       _DIRENT_HAVE_D_RECLEN,  _DIRENT_HAVE_D_OFF,  or _DIRENT_HAVE_D_TYPE are
76       defined.
77
78       Other than Linux, the d_type field is available mainly only on BSD sys‐
79       tems.   This  field  makes  it possible to avoid the expense of calling
80       lstat(2) if further actions depend on the type of  the  file.   If  the
81       _BSD_SOURCE  feature test macro is defined, then glibc defines the fol‐
82       lowing macro constants for the value returned in d_type:
83
84       DT_BLK      This is a block device.
85
86       DT_CHR      This is a character device.
87
88       DT_DIR      This is a directory.
89
90       DT_FIFO     This is a named pipe (FIFO).
91
92       DT_LNK      This is a symbolic link.
93
94       DT_REG      This is a regular file.
95
96       DT_SOCK     This is a Unix domain socket.
97
98       DT_UNKNOWN  The file type is unknown.
99
100       If the file type could not  be  determined,  the  value  DT_UNKNOWN  is
101       returned in d_type.
102
103       Currently,  only  some file systems (among them: Btrfs, ext2, etx3, and
104       ext4) have full support returning the file type in d_type.  All  appli‐
105       cations must properly handle a return of DT_UNKNOWN.
106
107       Since  POSIX.1 does not specify the size of the d_name field, and other
108       non-standard fields may precede that field within the dirent structure,
109       portable  applications  that use readdir_r() should allocate the buffer
110       whose address is passed in entry as follows:
111
112           len = offsetof(struct dirent, d_name) +
113                     pathconf(dirpath, _PC_NAME_MAX) + 1
114           entryp = malloc(len);
115
116       (POSIX.1 requires that d_name is the last field in a struct dirent.)
117

COLOPHON

124       This page is part of release 3.22 of the Linux  man-pages  project.   A
125       description  of  the project, and information about reporting bugs, can
126       be found at http://www.kernel.org/doc/man-pages/.
127
128
129
130                                  2009-07-04                        READDIR(3)