Author: jilles
Date: Wed Sep 7 21:09:44 2016
New Revision: 305569
URL: https://svnweb.freebsd.org/changeset/base/305569
Log:
MFC r305154: 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, although 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.
Modified:
stable/10/lib/libc/gen/directory.3
Directory Properties:
stable/10/ (props changed)
Modified: stable/10/lib/libc/gen/directory.3
==============================================================================
--- stable/10/lib/libc/gen/directory.3 Wed Sep 7 21:04:39 2016
(r305568)
+++ stable/10/lib/libc/gen/directory.3 Wed Sep 7 21:09:44 2016
(r305569)
@@ -28,7 +28,7 @@
.\" @(#)directory.3 8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
-.Dd May 6, 2015
+.Dd August 31, 2016
.Dt DIRECTORY 3
.Os
.Sh NAME
@@ -69,6 +69,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
@@ -123,7 +132,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,
@@ -140,6 +155,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
_______________________________________________
svn-src-stable-10@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/svn-src-stable-10
To unsubscribe, send any mail to "svn-src-stable-10-unsubscr...@freebsd.org"
