update from main archive 961001

1 files changed, 30 insertions, 0 deletions

diff --git a/manual/filesys.texi b/manual/filesys.texi
index e269663e70..31325268f9 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -327,6 +327,36 @@ conditions are defined for this function:
 @item EBADF
 The @var{dirstream} argument is not valid.
 @end table
+
+@code{readdir} is not thread safe.  Multiple threads using
+@code{readdir} on the same @var{dirstream} may overwrite the return
+value.  Use @code{readdir_r} when this is critical.
+@end deftypefun
+
+@comment dirent.h
+@comment GNU
+@deftypefun int readdir_r (DIR *@var{dirstream}, struct *@var{entry}, struct **@var{result})
+This function is the reentrant version of @code{reentrant}.  Like
+@code{readdir} it returns the next entry from the directory.  But to
+prevent conflicts for simultanously running threads the result is not
+stored in some internal memory.  Instead the argument @var{entry} has to
+point to a place where the result is stored.
+
+The return value is @code{0} in case the next entry was read
+successfully.  In this case a pointer to the result is returned in
+*@var{result}.  It is not required that *@var{result} is the same as
+@var{entry}.  If somethings goes wrong while exeucting @code{readdir_r}
+the function return @code{-1}.  The @code{errno} variable is set like
+described for @code{readdir}.
+
+@strong{Portability Note:} On some systems, @code{readdir_r} may not
+return a terminated string as the file name even if no @code{d_reclen}
+element is available in @code{struct dirent} and the file name as the
+maximal allowed size.  Modern systems all have the @code{d_reclen} field
+and on old systems multi threading is not critical.  In any case, there
+is no such problem with the @code{readdir} function so that even on
+systems without @code{d_reclen} field one could use multiple threads by
+using external locking.
 @end deftypefun
 
 @comment dirent.h