svn commit: r305154 - head/lib/libc/gen

[Jilles Tjoelker]

Author: jilles
Date: Wed Aug 31 20:38:40 2016
New Revision: 305154
URL: https://svnweb.freebsd.org/changeset/base/305154

Log:
  directory(3): Deprecate readdir_r(). Clarify dirent buffers.
  
  In existing implementations including FreeBSD, there is no reason to use
  readdir_r() in the common case where potentially multiple threads each list
  their own directory. Code using readdir() is simpler.
  
  What's more, lthough readdir_r() can safely be used on FreeBSD because
  NAME_MAX is forced to 255, it cannot be used safely on systems where
  {NAME_MAX} is not fixed. As a concrete example, FAT/NTFS filenames can be up
  to 255 UTF-16 code units long, which can be up to 765 UTF-8 bytes.
  
  Deprecating readdir_r() in POSIX has been proposed in
  http://www.austingroupbugs.net/view.php?id=696
  and glibc wants to deprecate it as well.
  
  Reviewed by:	ed, wblock
  MFC after:	1 week
  Differential Revision:	https://reviews.freebsd.org/D7678

Modified:
  head/lib/libc/gen/directory.3

Modified: head/lib/libc/gen/directory.3
==============================================================================
--- head/lib/libc/gen/directory.3	Wed Aug 31 20:33:59 2016	(r305153)
+++ head/lib/libc/gen/directory.3	Wed Aug 31 20:38:40 2016	(r305154)
@@ -28,7 +28,7 @@
 .\"     @(#)directory.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd February 19, 2016
+.Dd August 31, 2016
 .Dt DIRECTORY 3
 .Os
 .Sh NAME
@@ -68,6 +68,15 @@
 .Ft int
 .Fn dirfd "DIR *dirp"
 .Sh DESCRIPTION
+.Bf -symbolic
+The
+.Fn readdir_r
+interface is deprecated
+because it cannot be used correctly unless
+.Brq Va NAME_MAX
+is a fixed value.
+.Ef
+.Pp
 The
 .Fn opendir
 function
@@ -122,7 +131,13 @@ The
 .Fn readdir
 function
 returns a pointer to the next directory entry.
-It returns
+The directory entry remains valid until the next call to
+.Fn readdir
+or
+.Fn closedir
+on the same
+.Em directory stream .
+The function returns
 .Dv NULL
 upon reaching the end of the directory or on error.
 In the event of an error,
@@ -139,6 +154,13 @@ provides the same functionality as
 but the caller must provide a directory
 .Fa entry
 buffer to store the results in.
+The buffer must be large enough for a
+.Vt struct dirent
+with a
+.Va d_name
+array with
+.Brq Va NAME_MAX
++ 1 elements.
 If the read succeeds,
 .Fa result
 is pointed at the