Crate libnss_host4 

Implementing the trait and macro in this crate will publish a gethostbyname4_r NSS hook in your Rust cdylib.

Example

use libnss_host4::{Addr, HostResolver, err::NssErr, impl_gethostbyname4_r};
use std::net::Ipv6Addr;

/// This resolver maps "localhost" to [::1%0].
struct LocalDns;
impl_gethostbyname4_r!(local, LocalDns);

impl HostResolver for LocalDns {
    fn resolve_host(hostname: &str) -> Result<impl IntoIterator<Item = Addr>, NssErr> {
        if hostname == "localhost" {
            return Ok([Addr {
                ip: Ipv6Addr::LOCALHOST.into(),
                scope_id: 0,
            }]);
        }
        Err(NssErr::NO_RESULT)
    }
}

Background

glibc defines a Name Service Switch interface for querying hostnames.

https://sourceware.org/glibc/manual/2.43/html_mono/libc.html#Host-Names

This once-simple lookup API has unfortunately degenerated into a sedimentary chaos of numbered functions differentiated by reentrance and lack thereof. An early indication of which is the conspicuous absence of gethostbyname3_r and gethostbyname4_r in the docs linked above.

However, as of writing, gethostbyname4_r is the only NSS host hook that can return IPv6 addresses with a scope_id, which makes it a big deal for the chosen few who care about such things.

Other Rust NSS usage is already well supported by the libnss crate. The motivating cause for this crate cannot accomodate its GPL license, which is why this is standalone. Presumably both crates can be used in the same cdylib to cover the full NSS host API.

If the other hooks aren’t needed, though, a cdylib with just gethostbyname4_r is sufficient for getaddrinfo-based resolution via /etc/nsswitch.conf.

Modules

err

gethostbyname4_r has three dimensions of return state defined in this module.

Macros

impl_gethostbyname4_r

This macro expands into an NSS-compatible hook for the gethostbyname4_r hostname resolution API.

Structs

Addr

An address that can be returned from gethostbyname4_r.

Traits

HostResolver

Implement this trait with the actual address business logic that gethostbyname4_r should expose. The C interop layer simply wraps the resolution defined here.