readdir_r(3)

1readdir_r(3)               Library Functions Manual               readdir_r(3)
2
3
4

NAME

6       readdir_r - read a directory
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <dirent.h>
13
14       [[deprecated]] int readdir_r(DIR *restrict dirp,
15                                    struct dirent *restrict entry,
16                                    struct dirent **restrict result);
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       readdir_r():
21           _POSIX_C_SOURCE
22               || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
23

DESCRIPTION

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

RETURN VALUE

66       The  readdir_r() function returns 0 on success.  On error, it returns a
67       positive error number (listed under ERRORS).  If the end of the  direc‐
68       tory stream is reached, readdir_r() returns 0, and returns NULL in *re‐
69       sult.
70

ERRORS

72       EBADF  Invalid directory stream descriptor dirp.
73
74       ENAMETOOLONG
75              A directory entry whose name was too long to be read was encoun‐
76              tered.
77

ATTRIBUTES

79       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
80       tributes(7).
81
82       ┌────────────────────────────────────────────┬───────────────┬─────────┐
83       │Interface                                   │ Attribute     │ Value   │
84       ├────────────────────────────────────────────┼───────────────┼─────────┤
85       │readdir_r()                                 │ Thread safety │ MT-Safe │
86       └────────────────────────────────────────────┴───────────────┴─────────┘
87

STANDARDS

89       POSIX.1-2008.
90

HISTORY

92       POSIX.1-2001.
93