Why was a readdir function added to POSIX library interface when there is a readdir kernel function?

Question

I was surprised to discover the man pages having entries for two conflicting variants of readdir .

in READDIR(2), it specifically states you do not want to use it:

This is not the function you are interested in. Look at readdir(3) for the POSIX conforming C library interface. This page documents the bare kernel system call interface, which is superseded by getdents(2).

I understand a function may become deprecated when another function comes along and does its job better, but I am not familiar with other cases of a userspace function coming in and replacing a kernel function of the same name. Is there a known reason it was chosen to go this route rather than coming up with a new function name (as the man page mentions getdents did when superseding readdir ).

Answer 1

The programming interface, POSIX, is stable. You don't just go replacing functions in it unnecessarily because you want to implement the backend more efficiently. The Linux syscall readdir never implemented the readdir function because it has the wrong signature; it was an old, inefficient backend for implementing the readdir function. When a better backend came along, it was obsolete.

Answer 2

You have it completely backwards: it's the library function readdir(3) which predates Linux and its readdir(2) system call, and not the reverse.

Naming the syscall that way was certainly a poor decision, and probably has a story behind it, but it's pretty much irrelevant now, as nobody is using it.

On Unix, directories used to be simple files formatted in a special way, and the system call interface through which they were read was just read(2) [1]. Later systems introduced system calls like getdirentries (44BSD) and getdents (SVR3), but they weren't willing or capable to standardize on an interface, so we're still stuck with the high level and broken [2] readdir(3) library function as the only standard interface for reading a directory.

[1] On some systems like BSD you can still cat a directory, at least when using the default filesystem (FFS).

[2] it's broken because it's not signal safe, and it returns NULL for both error and EOF , which means that the only way it could be safely used is by first setting errno to 0, and checking both its return value and errno afterwards. Yuck.