7.1 The Module

4 min read

The shim's obligations are PSPU §6.10. This chapter describes the module resolvd's source tree builds.

7.1.1 The object #

  • libnss_peios_net.so.2 is installed by dev.peios.resolvd-nss at /usr/lib/x86_64-linux-peios/libnss_peios_net.so.2.
  • It is built from the nss crate, with the native channel codec compiled in. Its only shared-object dependencies are libc.so.6 and the dynamic loader, ld-linux-x86-64.so.2. The GCC unwinder required by Rust is linked statically, with its symbols private to the module; name lookups do not load libgcc_s.so.1. The identity shim, libnss_peios.so.2, uses the same static-unwinder arrangement. Neither shim links libpeios.

7.1.1.1 The entry points #

The module exports six entry points:

Entry pointAsks
_nss_peios_net_gethostbyname4_rlookup, family any
_nss_peios_net_gethostbyname3_rlookup, family from af
_nss_peios_net_gethostbyname2_ras gethostbyname3_r, with no TTL or canonical name out
_nss_peios_net_gethostbyname_ras gethostbyname3_r, with af AF_INET
_nss_peios_net_gethostbyaddr2_rreverse
_nss_peios_net_gethostbyaddr_ras gethostbyaddr2_r, with no TTL out

7.1.2 One connection per call #

  • Every call that needs resolvd opens a new connection to /run/resolvd/resolv.sock, sends one request, reads one reply, and closes the connection.
  • Nothing is kept between calls: no connection, no cache, no configuration. The module reads no file.

7.1.2.1 The ten-second socket timeouts #

Each connection is given ten-second read and write timeouts, which apply to each read and write on the socket. Ten seconds is longer than the six seconds a question's three timed-out attempts take in resolvd, TCP retries included (§4.6), so a slow upstream normally reaches the caller as unavailable from resolvd rather than as a timeout here. A question can still reach the timeout when many search candidates each answer NXDOMAIN slowly, since those answers do not spend the attempt budget; that is reported as the table below shows.

7.1.3 Results #

ResultNSS statuserrnoh_errno
Addresses, or names, foundSUCCESS——
found, but no address of the asked familyNOTFOUNDENOENTHOST_NOT_FOUND
notfoundNOTFOUNDENOENTHOST_NOT_FOUND
unavailableTRYAGAINEAGAINTRY_AGAIN
No reply within ten secondsTRYAGAINEAGAINTRY_AGAIN
resolvd cannot be connected toUNAVAILENOENTNO_RECOVERY
An error reply, including access deniedUNAVAILENOENTNO_RECOVERY
A reply of the wrong kind, a reply that does not decode, or any other I/O errorUNAVAILENOENTNO_RECOVERY
The caller's buffer is too smallTRYAGAINERANGENETDB_INTERNAL (-1), required for retry; see version note below
gethostbyname3_r or 2_r with an af other than AF_INET or AF_INET6UNAVAILEAFNOSUPPORTNO_DATA
gethostbyaddr2_r or _r with an af and length other than AF_INET/4 or AF_INET6/16UNAVAILEAFNOSUPPORTNO_RECOVERY
A null name, a name that is not UTF-8, or a null addressNOTFOUNDENOENTHOST_NOT_FOUND

The missing-family row above describes source b4f7085: a found name with no address of the family asked is reported exactly as a name that does not exist. This does not meet PSPU §6.10's requirement that found without an address of that family return NO_DATA.

The proposed source correction preserves NOTFOUND and ENOENT, but sets h_errno to NO_DATA when a found reply has no usable address of the requested family. A found reverse reply with no PTR record has the same result. Explicit notfound still returns HOST_NOT_FOUND; unavailable and transport failures keep their distinct results in the table. This describes proposed source behavior, not a released package or an installed module. Check the installed module's source revision before relying on this distinction.

7.1.3.1 AF_UNSPEC #

AF_UNSPEC is accepted only by gethostbyname4_r, which always asks for both families.

7.1.4 The caller's buffer #

Every string, pointer array and address the module returns is placed in the buffer glibc passes in; the module allocates nothing that outlives the call. When the buffer cannot hold the result, the call returns as in the table, and nothing written to the buffer is valid.

Edit this page