resolv.conf(5) documents glibc implementation behaviour

[yrro]

Of the nameserver keyword, the man page states,

If there are multiple servers, the resolver library queries them in the order listed.

and,

(The algorithm used is to try a name server, and if the query times out, try the next, until out of name servers, then repeat trying all the name servers until a maximum number of retries are made.)

These are implementation details of glibc and relying on this behaviour introduces a number of subtle problems that commonly trip people up.

I think glibc's behaviour should be documented in glibc's documentation, and the text of the man page should be change to something like:

If there are multiple servers, they must all provide the same "view" of the DNS.

and

(Behaviour varies between different resolvers regarding how multiple servers are interpreted.)

Or perhaps the parenthetical remark should be removed altogether.