=pod

=head1 NAME

I<val_getaddrinfo()> - get DNSSEC-validated network
address and service translation

=head1 SYNOPSIS

  #include <validator/validator.h>

  int val_getaddrinfo(const struct val_context *ctx,
                      const char *nodename,
                      const char *servname,
                      const struct addrinfo *hints,
                      struct addrinfo **res,
                      val_status_t * val_status);

  int val_getnameinfo(val_context_t * ctx,
                      const struct sockaddr *sa,
                      socklen_t salen,
                      char *host,
                      size_t hostlen,
                      char *serv,
                      size_t servlen,
                      int flags,
                      val_status_t * val_status);

=head1 DESCRIPTION

I<val_getaddrinfo()> and I<val_getnameinfo> perform DNSSEC validation of DNS
queries.  They are intended to be DNSSEC-aware replacements for
I<getaddrinfo(3)> and I<getnameinfo(3)>.

I<val_getaddrinfo()>  returns a network address value of type I<struct
addrinfo> in the I<res> parameter.  I<val_getnameinfo> is used to convert a
I<sockaddr> structure to a pair of host name and service strings.

I<val_status> gives the combined validation status value for all
answers returned by the each of the functions.  I<val_istrusted()> and
I<val_isvalidated()> can be used to determine the trustworthiness of data and
I<p_val_status()> can be used to display the status value to the user in ASCII
format (See I<libval(3)> more for information).

The I<ctx> parameter specifies the validation context, which can be set to NULL
for default values (see I<libval(3)> and I<dnsval.conf> for more details on validation
contexts and validation policy).

The I<nodename>, I<servname>, and I<hints> parameters have similar
syntax and semantics as the corresponding parameters for the original
I<getaddrinfo()> function.  The I<res> parameter is similar to the
I<res> parameter for I<getaddrinfo()>.  Please see the manual
page for I<getaddrinfo(3)> for more details about these parameters.


=head1 RETURN VALUES

The I<val_getaddrinfo()> function returns 0 on success and a non-zero error
code on failure.  I<*res> will point to a dynamically allocated linked list
of I<addrinfo> structures on success and will be NULL if no answer was
available.

The I<val_status> parameter gives an indication for trustworthiness of data. If
I<*res> is NULL, this value gives an indication of whether the non-existence of
data can be trusted or not.

=head1 EXAMPLE

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

 int main(int argc, char *argv[])
 {
          struct addrinfo *ainfo = NULL;
          int retval;

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

          retval = val_getaddrinfo(NULL, argv[1], NULL, NULL, &ainfo);

          if ((retval == 0) && (ainfo != NULL)) {

                  printf("Validation Status = %d [%s]\n",
                         ainfo->ai_val_status,
                         p_val_status(ainfo->ai_val_status));

                  val_freeaddrinfo(ainfo);
          }

          return 0;
 }

=head1 COPYRIGHT

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

=head1 AUTHORS

Abhijit Hayatnagarkar, Michael Baer

=head1 SEE ALSO

I<getaddrinfo(3)>

I<val_gethostbyname(3)>, I<val_res_query(3)>

I<libval(3)>

http://www.dnssec-tools.org

=cut
