directory(3): Deprecate readdir_r(). Clarify dirent buffers.

[jilles]

Summary

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.

Test Plan

textproc/igor reported no new warnings

[wblock]

lib/libc/gen/directory.3

73 ↗

(On Diff #19767)

This seems like it would be better as

The
.Fn readdir_r
interface is deprecated

75 ↗

(On Diff #19767)

Invert the logic:

because it cannot be used correctly unless
.Brq Va NAME_MAX
is fixed.

(Might want to use "fixed value" or "constant value" there for clarity.)

134 ↗

(On Diff #19767)

Maybe
s/remains/is/ for clarity?

163 ↗

(On Diff #19767)

A little ambiguous: len(dname(n)) + 1 or len(dname(n+1)) ?

[ed]

I accept with this change from a technical point of view. The changes proposed by Warren also look good.

Thanks for working on this!

[jilles]

lib/libc/gen/directory.3

134 ↗

(On Diff #19767)

Hmm, both forms already occur in man pages, and I think "remains" is somewhat clearer that readdir() calls on other directory streams will not affect the directory entry.

163 ↗

(On Diff #19767)

What to write instead? "a d_name array with NAME_MAX + 1 elements"?

Note that all this is not relevant on FreeBSD because d_namlen makes it impossible to have a name of more than 255 bytes.

[wblock]

lib/libc/gen/directory.3

134 ↗

(On Diff #19767)

I'm okay with that. Be careful about using existing stuff as precedent, though. That's why we still have so many driver pages with "Alternatively, to load the driver as a module at boot time, place the following line in loader.conf(5):". That it exists in man pages is why people keep reusing the horrible thing.

163 ↗

(On Diff #19767)

Phabricator won't let me quote, but yes, that sounds like a much better way to say it.

If it's really not relevant on FreeBSD, an argument could be made that it should not be said at all. But there is always the concern of people either coming from or porting to other platforms.