man3/readdir_r.3

   1 '\" t
   2 .\" Copyright (C) 2008, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" and Copyright (C) 2016 Florian Weimer <fweimer@redhat.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH readdir_r 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 readdir_r \- read a directory
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <dirent.h>
  16 .PP
  17 .BI "[[deprecated]] int readdir_r(DIR *restrict " dirp ,
  18 .BI "                             struct dirent *restrict " entry ,
  19 .BI "                             struct dirent **restrict " result );
  20 .fi
  21 .PP
  22 .RS -4
  23 Feature Test Macro Requirements for glibc (see
  24 .BR feature_test_macros (7)):
  25 .RE
  26 .PP
  27 .BR readdir_r ():
  28 .nf
  29     _POSIX_C_SOURCE
  30         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  31 .fi
  32 .SH DESCRIPTION
  33 This function is deprecated; use
  34 .BR readdir (3)
  35 instead.
  36 .PP
  37 The
  38 .BR readdir_r ()
  39 function was invented as a reentrant version of
  40 .BR readdir (3).
  41 It reads the next directory entry from the directory stream
  42 .IR dirp ,
  43 and returns it in the caller-allocated buffer pointed to by
  44 .IR entry .
  45 For details of the
  46 .I dirent
  47 structure, see
  48 .BR readdir (3).
  49 .PP
  50 A pointer to the returned buffer is placed in
  51 .IR *result ;
  52 if the end of the directory stream was encountered,
  53 then NULL is instead returned in
  54 .IR *result .
  55 .PP
  56 It is recommended that applications use
  57 .BR readdir (3)
  58 instead of
  59 .BR readdir_r ().
  60 Furthermore, since glibc 2.24, glibc deprecates
  61 .BR readdir_r ().
  62 The reasons are as follows:
  63 .IP \[bu] 3
  64 On systems where
  65 .B NAME_MAX
  66 is undefined, calling
  67 .BR readdir_r ()
  68 may be unsafe because the interface does not allow the caller to specify
  69 the length of the buffer used for the returned directory entry.
  70 .IP \[bu]
  71 On some systems,
  72 .BR readdir_r ()
  73 can't read directory entries with very long names.
  74 When the glibc implementation encounters such a name,
  75 .BR readdir_r ()
  76 fails with the error
  77 .B ENAMETOOLONG
  78 .IR "after the final directory entry has been read" .
  79 On some other systems,
  80 .BR readdir_r ()
  81 may return a success status, but the returned
  82 .I d_name
  83 field may not be null terminated or may be truncated.
  84 .IP \[bu]
  85 In the current POSIX.1 specification (POSIX.1-2008),
  86 .BR readdir (3)
  87 is not required to be thread-safe.
  88 However, in modern implementations (including the glibc implementation),
  89 concurrent calls to
  90 .BR readdir (3)
  91 that specify different directory streams are thread-safe.
  92 Therefore, the use of
  93 .BR readdir_r ()
  94 is generally unnecessary in multithreaded programs.
  95 In cases where multiple threads must read from the same directory stream,
  96 using
  97 .BR readdir (3)
  98 with external synchronization is still preferable to the use of
  99 .BR readdir_r (),
 100 for the reasons given in the points above.
 101 .IP \[bu]
 102 It is expected that a future version of POSIX.1
 103 .\" FIXME .
 104 .\" http://www.austingroupbugs.net/view.php?id=696
 105 will make
 106 .BR readdir_r ()
 107 obsolete, and require that
 108 .BR readdir (3)
 109 be thread-safe when concurrently employed on different directory streams.
 110 .SH RETURN VALUE
 111 The
 112 .BR readdir_r ()
 113 function returns 0 on success.
 114 On error, it returns a positive error number (listed under ERRORS).
 115 If the end of the directory stream is reached,
 116 .BR readdir_r ()
 117 returns 0, and returns NULL in
 118 .IR *result .
 119 .SH ERRORS
 120 .TP
 121 .B EBADF
 122 Invalid directory stream descriptor \fIdirp\fP.
 123 .TP
 124 .B ENAMETOOLONG
 125 A directory entry whose name was too long to be read was encountered.
 126 .SH ATTRIBUTES
 127 For an explanation of the terms used in this section, see
 128 .BR attributes (7).
 129 .ad l
 130 .nh
 131 .TS
 132 allbox;
 133 lbx lb lb
 134 l l l.
 135 Interface       Attribute       Value
 136 T{
 137 .BR readdir_r ()
 138 T}      Thread safety   MT-Safe
 139 .TE
 140 .hy
 141 .ad
 142 .sp 1
 143 .SH STANDARDS
 144 POSIX.1-2008.
 145 .SH HISTORY
 146 POSIX.1-2001.
 147 .SH SEE ALSO
 148 .BR readdir (3)