val_gethostbyname(3)

📦 version 2.2.3, in arch rolling, fedora 43, fedora 44

ok bestie, this one's from the Programmer's Manual — val_gethostbyname(3) and its whole little friend group. grab a snack, we're doing DNSSEC host lookups 🫶

✨ NAME ✨

val_gethostbyname(), val_gethostbyname2(), val_gethostbyname_r(), val_gethostbyname2_r() — get DNSSEC-validated network host entry 💅

like, it does the host lookup thing, but it also checks the DNSSEC vibes. iconic behavior honestly.

🌈 SYNOPSIS 🌈

#include <validator/validator.h>

extern int h_errno;
struct hostent *val_gethostbyname(const val_context_t *ctx,
                                  const char *name,
                                  val_status_t *val_status);

struct hostent *val_gethostbyname2(const val_context_t *ctx,
                                   const char *name,
                                   int af,
                                   val_status_t *val_status);

int val_gethostbyname_r(const val_context_t *ctx,
                        const char *name,
                        struct hostent *ret,
                        char *buf,
                        size_t buflen,
                        struct hostent **result,
                        int *h_errnop,
                        val_status_t *val_status);

int val_gethostbyname2_r(const val_context_t *ctx,
                         const char *name,
                         int af,
                         struct hostent *ret,
                         char *buf,
                         size_t buflen,
                         struct hostent **result,
                         int *h_errnop,
                         val_status_t *val_status);

  struct hostent *val_gethostbyaddr(val_context_t * ctx,
                                    const char *addr,
                                    int len,
                                    int type,
                                    val_status_t * val_status);

  int val_gethostbyaddr_r(val_context_t * ctx,
                          const char *addr,
                          int len,
                          int type,
                          struct hostent *ret,
                          char *buf,
                          int buflen,
                          struct hostent **result,
                          int *h_errnop,
                          val_status_t * val_status);

(also can I just say — val_gethostbyaddr() and val_gethostbyaddr_r() are in the synopsis but not in the NAME list. the lore is deeper than the title. iykyk 💀)

🦋 DESCRIPTION 🦋

So. val_gethostbyname(), val_gethostbyname2(), val_gethostbyname_r(), val_gethostbyname2_r(), val_gethostbyaddr() and val_gethostbyaddr_r() all do DNSSEC validation of DNS queries. They hand you back a network host entry of type struct hostent, and they're the DNSSEC-aware glow-ups of gethostbyname(3), gethostbyname2(3), gethostbyname_r(), gethostbyname2_r(), gethostbyaddr() and gethostbyaddr_r() respectively. (if you wanna know what struct hostent even is — go read gethostbyname(3), it's all in there, bestie.)

  • val_gethostbyname(), val_gethostbyname_r(), val_gethostbyaddr(), and val_gethostbyaddr_r() support only IPv4 addresses.
  • val_gethostbyname2() and val_gethostbyname2_r() support both IPv4 and IPv6 addresses. range, honestly 👑

And the reentrant versions — val_gethostbyname_r(), val_gethostbyname2_r() and val_gethostbyaddr_r() — are the ones you can safely use in multi-threaded applications. thread-safe queens, no cap 💅

The ctx parameter is the validation context. You can set it to NULL for default values (see libval(3) and dnsval.conf for the full tea on validation contexts and validation policy).

val_gethostbyname(), val_gethostbyname2() and val_gethostbyaddr() set the global h_errno variable to return the resolver error code. The reentrant versions val_gethostbyname_r(), val_gethostbyname2_r() and val_gethostbyaddr_r() use the h_errnop parameter to return that value instead. That's the whole point — it keeps things thread safe by avoiding the global h_errno variable. 🧚

Heads up: h_errnop must NOT be NULL. like, don't do that. 🙈

(see the man page for gethostbyname(3) for possible values of h_errno.)

The name, af, ret, buf, buflen, and result parameters have the same syntax and semantics as the corresponding parameters for the original gethostbyname*() and gethostbyaddr*() functions. Again, gethostbyname(3) has the details on those.

The val_status parameter is where the validator error code comes back — and it must not be NULL. Use val_istrusted() and val_isvalidated() to figure out whether the data is trustworthy, and p_val_status() to display the status value to the user in ASCII format (see libval(3) for more info).

💖 RETURN VALUES 💖

  • val_gethostbyname(), val_gethostbyname2(), and val_gethostbyaddr() return a pointer to a hostent structure when they can resolve the given host name (with or without DNSSEC validation), and NULL if data was not available. The memory for the returned value is statically allocated by these two functions, so the caller must NOT free the memory for the returned value. do not touch it, it's not yours 🫶
  • val_gethostbyname_r(), val_gethostbyname2_r() and val_gethostbyaddr_r() return 0 when they can resolve the given host name (with or without DNSSEC validation), and a non-zero error-code on failure.
  • val_gethostbyaddr() and val_gethostbyaddr_r() return 0 when they can resolve the given host name (with or without DNSSEC validation), and a non-zero error-code on failure.
  • The val_status parameter gives an indication of the trustworthiness of the data. And if the returned hostent structure is NULL, this value tells you whether the non-existence of data can be trusted or not. ✨

🌸 EXAMPLE 🌸

#include <stdio.h>
#include <stdlib.h>
#include <validator.h>

   int main(int argc, char *argv[])
   {
        int val_status;
        struct hostent *h = NULL;

        if (argc < 2) {
            printf("Usage: %s <hostname>\n", argv[0]);
            exit(1);
        }

        h = val_gethostbyname(NULL, argv[1], &val_status);
        printf("h_errno = %d [%s]\n", h_errno,
            hstrerror(h_errno));
        if (h) {
            printf("Validation Status = %d [%s]\n", val_status,
                   p_val_status(val_status));
        }

        return 0;
   }

main character energy fr fr 🌟

🎀 NOTES 🎀

  • These functions do not currently read the order of lookup from /etc/hosts.conf. At present, the default order is set to consult the /etc/hosts file first and then query DNS. that's just how it is rn 😭
  • The current versions of these functions do not support NIS lookups.

Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details.

⭐ AUTHORS ⭐

Abhijit Hayatnagarkar, Suresh Krishnaswamy.

👑 SEE ALSO 👑

ok that's the whole thing, you ate it, congrats 🎉 this page was brought to you by perl v5.14.3, dated 2013-03-12, and the letter val_. go validate something, bestie 💖✨🦋

📦 where this page comes from