Provided by: libval-dev_2.0-1.1ubuntu1_amd64 
NAME
val_gethostbyname(), val_gethostbyname2(), val_gethostbyname_r(), val_gethostbyname2_r() -
get DNSSEC-validated network host entry
SYNOPSIS
#include <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);
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), gethostbyname2(3), gethostbyname_r(),
gethostbyname2_r(), gethostbyaddr() and gethostbyaddr_r() functions respectively. (See
gethostbyname(3) 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) 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) 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) 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) 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 <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;
}
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), gethostbyname2(3), gethostbyname_r(3), gethostbyname2_r(3)
val_getaddrinfo(3), val_res_query(3)
libval(3)
http://www.dnssec-tools.org