--- name: "val_gethostbyname" section: "3" platform: "linux" package: "dnssec-tools" version: "2.2.3-16" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/val_gethostbyname" --- # val\_gethostbyname(3) get DNSSEC-validated network host entry ## NAME val\_gethostbyname(), val\_gethostbyname2(), val\_gethostbyname\_r(), val\_gethostbyname2\_r() - get DNSSEC-validated network host entry ## SYNOPSIS ``` #include 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); ``` ## DESCRIPTION *val\_gethostbyname()*, *val\_gethostbyname2()*, *val\_gethostbyname\_r()*, *val\_gethostbyname2\_r()*, *val\_gethostbyaddr()* and *val\_gethostbyaddr\_r()* perform DNSSEC validation of DNS queries. They return a network host entry value of type struct *hostent* and are DNSSEC-aware versions of the *[gethostbyname(3)](/gethostbyname/3.md)*, *[gethostbyname2(3)](/gethostbyname2/3.md)*, *gethostbyname\_r()*, *gethostbyname2\_r()*, *gethostbyaddr()* and *gethostbyaddr\_r()* functions respectively. (See *[gethostbyname(3)](/gethostbyname/3.md)* for more information on type struct *hostent*). *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. The *val\_gethostbyname\_r()*, *val\_gethostbyname2\_r()* and *val\_gethostbyaddr\_r()* functions are reentrant versions and can be safely used in multi-threaded applications. The *ctx* parameter specifies the validation context, which can be set to NULL for default values (see *[libval(3)](/libval/3.md)* and *dnsval.conf* for more details 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 this value. This ensures thread safety, by avoiding the global *h\_errno* variable. *h\_errnop* must not be NULL. (See the man page for *[gethostbyname(3)](/gethostbyname/3.md)* 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. See the manual page for *[gethostbyname(3)](/gethostbyname/3.md)* for more details about these parameters. The *val\_status* parameter is used to return the validator error code and must not be NULL. *val\_istrusted()* and *val\_isvalidated()* can be used to determine the trustworthiness of data and *p\_val\_status()* can be used to display the status value to the user in ASCII format (See *[libval(3)](/libval/3.md)* more for information). ## RETURN VALUES The *val\_gethostbyname()*, *val\_gethostbyname2()*, and *val\_gethostbyaddr()* functions 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. Hence, the caller must not free the memory for the returned value. The *val\_gethostbyname\_r()*, *val\_gethostbyname2\_r()* and *val\_gethostbyaddr\_r()* functions 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\_gethostbyaddr()* and *val\_gethostbyaddr\_r()* functions 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 for trustworthiness of data. If the returned *hostent* structure is NULL, this value gives an indication of whether the non-existence of data can be trusted or not. ## EXAMPLE ``` #include #include #include int main(int argc, char *argv[]) { int val_status; struct hostent *h = NULL; if (argc < 2) { printf("Usage: %s \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; } ``` ## 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. The current versions of these functions do not support NIS lookups. ## COPYRIGHT 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 *[gethostbyname(3)](/gethostbyname/3.md)*, *[gethostbyname2(3)](/gethostbyname2/3.md)*, *[gethostbyname\_r(3)](/gethostbyname_r/3.md)*, *[gethostbyname2\_r(3)](/gethostbyname2_r/3.md)* *[val\_getaddrinfo(3)](/val_getaddrinfo/3.md)*, *[val\_res\_query(3)](/val_res_query/3.md)* *[libval(3)](/libval/3.md)* http://www.dnssec-tools.org