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

NAME

6       readdir_r - read a directory
7

SYNOPSIS

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

DESCRIPTION

20       This function is deprecated; use readdir(3) instead.
21
22       The  readdir_r()  function was invented as a reentrant version of read‐
23       dir(3).  It reads the next directory entry from  the  directory  stream
24       dirp,  and  returns  it  in  the  caller-allocated buffer pointed to by
25       entry.  For details of the dirent structure, see readdir(3).
26
27       A pointer to the returned buffer is placed in *result; if  the  end  of
28       the  directory stream was encountered, then NULL is instead returned in
29       *result.
30
31       It is recommended that applications use  readdir(3)  instead  of  read‐
32       dir_r().   Furthermore,  since  version  2.24,  glibc  deprecates read‐
33       dir_r().  The reasons are as follows:
34
35       *  On systems where NAME_MAX is undefined, calling readdir_r()  may  be
36          unsafe  because  the  interface does not allow the caller to specify
37          the length of the buffer used for the returned directory entry.
38
39       *  On some systems, readdir_r() can't read directory entries with  very
40          long  names.   When the glibc implementation encounters such a name,
41          readdir_r() fails with the error ENAMETOOLONG after the final direc‐
42          tory  entry  has  been read.  On some other systems, readdir_r() may
43          return a success status, but the returned d_name field  may  not  be
44          null terminated or may be truncated.
45
46       *  In  the  current POSIX.1 specification (POSIX.1-2008), readdir(3) is
47          not required to be thread-safe.  However, in modern  implementations
48          (including the glibc implementation), concurrent calls to readdir(3)
49          that specify different directory streams  are  thread-safe.   There‐
50          fore,  the  use  of  readdir_r()  is generally unnecessary in multi‐
51          threaded programs.  In cases where multiple threads must  read  from
52          the  same  directory stream, using readdir(3) with external synchro‐
53          nization is still preferable to the use of readdir_r(), for the rea‐
54          sons given in the points above.
55
56       *  It  is  expected  that  a  future version of POSIX.1 will make read‐
57          dir_r() obsolete, and require that readdir(3)  be  thread-safe  when
58          concurrently employed on different directory streams.
59

RETURN VALUE

61       The  readdir_r() function returns 0 on success.  On error, it returns a
62       positive error number (listed under ERRORS).  If the end of the  direc‐
63       tory  stream  is  reached,  readdir_r()  returns 0, and returns NULL in
64       *result.
65

ERRORS

67       EBADF  Invalid directory stream descriptor dirp.
68
69       ENAMETOOLONG
70              A directory entry whose name was too long to be read was encoun‐
71              tered.
72

ATTRIBUTES

74       For   an   explanation   of   the  terms  used  in  this  section,  see
75       attributes(7).
76
77       ┌────────────┬───────────────┬─────────┐
78Interface   Attribute     Value   
79       ├────────────┼───────────────┼─────────┤
80readdir_r() │ Thread safety │ MT-Safe │
81       └────────────┴───────────────┴─────────┘

CONFORMING TO

83       POSIX.1-2001, POSIX.1-2008.
84

SEE ALSO

86       readdir(3)
87

COLOPHON

89       This page is part of release 5.02 of the Linux  man-pages  project.   A
90       description  of  the project, information about reporting bugs, and the
91       latest    version    of    this    page,    can     be     found     at
92       https://www.kernel.org/doc/man-pages/.
93
94
95
96                                  2016-03-01                      READDIR_R(3)
Impressum