val_gethostbyname_r(3)

1val_gethostbyname(3)          Programmer's Manual         val_gethostbyname(3)
2
3
4

NAME

6       val_gethostbyname(), val_gethostbyname2(), val_gethostbyname_r(),
7       val_gethostbyname2_r() - get DNSSEC-validated network host entry
8

SYNOPSIS

10         #include <validator.h>
11
12         extern int h_errno;
13         struct hostent *val_gethostbyname(const val_context_t *ctx,
14                                           const char *name,
15                                           val_status_t *val_status);
16
17         struct hostent *val_gethostbyname2(const val_context_t *ctx,
18                                            const char *name,
19                                            int af,
20                                            val_status_t *val_status);
21
22         int val_gethostbyname_r(const val_context_t *ctx,
23                                 const char *name,
24                                 struct hostent *ret,
25                                 char *buf,
26                                 size_t buflen,
27                                 struct hostent **result,
28                                 int *h_errnop,
29                                 val_status_t *val_status);
30
31         int val_gethostbyname2_r(const val_context_t *ctx,
32                                  const char *name,
33                                  int af,
34                                  struct hostent *ret,
35                                  char *buf,
36                                  size_t buflen,
37                                  struct hostent **result,
38                                  int *h_errnop,
39                                  val_status_t *val_status);
40
41           struct hostent *val_gethostbyaddr(val_context_t * ctx,
42                                             const char *addr,
43                                             int len,
44                                             int type,
45                                             val_status_t * val_status);
46
47           int val_gethostbyaddr_r(val_context_t * ctx,
48                                   const char *addr,
49                                   int len,
50                                   int type,
51                                   struct hostent *ret,
52                                   char *buf,
53                                   int buflen,
54                                   struct hostent **result,
55                                   int *h_errnop,
56                                   val_status_t * val_status);
57

DESCRIPTION

59       val_gethostbyname(), val_gethostbyname2(), val_gethostbyname_r(),
60       val_gethostbyname2_r(), val_gethostbyaddr() and val_gethostbyaddr_r()
61       perform DNSSEC validation of DNS queries.  They return a network host
62       entry value of type struct hostent and are DNSSEC-aware versions of the
63       gethostbyname(3), gethostbyname2(3), gethostbyname_r(),
64       gethostbyname2_r(), gethostbyaddr() and gethostbyaddr_r() functions
65       respectively.  (See gethostbyname(3) for more information on type
66       struct hostent).
67
68       val_gethostbyname(), val_gethostbyname_r(), val_gethostbyaddr(), and
69       val_gethostbyaddr_r() support only IPv4 addresses.
70       val_gethostbyname2() and val_gethostbyname2_r() support both IPv4 and
71       IPv6 addresses.
72
73       The val_gethostbyname_r(), val_gethostbyname2_r() and
74       val_gethostbyaddr_r() functions are reentrant versions and can be
75       safely used in multi-threaded applications.
76
77       The ctx parameter specifies the validation context, which can be set to
78       NULL for default values (see libval(3) and dnsval.conf for more details
79       on validation contexts and validation policy).
80
81       val_gethostbyname(), val_gethostbyname2() and val_gethostbyaddr() set
82       the global h_errno variable to return the resolver error code.  The
83       reentrant versions val_gethostbyname_r(), val_gethostbyname2_r() and
84       val_gethostbyaddr_r() use the h_errnop parameter to return this value.
85       This ensures thread safety, by avoiding the global h_errno variable.
86       h_errnop must not be NULL.  (See the man page for gethostbyname(3) for
87       possible values of h_errno.)
88
89       The name, af, ret, buf, buflen, and result parameters have the same
90       syntax and semantics as the corresponding parameters for the original
91       gethostbyname*() and gethostbyaddr*() functions.  See the manual page
92       for gethostbyname(3) for more details about these parameters.
93
94       The val_status parameter is used to return the validator error code and
95       must not be NULL.  val_istrusted() and val_isvalidated() can be used to
96       determine the trustworthiness of data and p_val_status() can be used to
97       display the status value to the user in ASCII format (See libval(3)
98       more for information).
99

RETURN VALUES

101       The val_gethostbyname(), val_gethostbyname2(), and val_gethostbyaddr()
102       functions return a pointer to a hostent structure when they can resolve
103       the given host name (with or without DNSSEC validation), and NULL if
104       data was not available.  The memory for the returned value is
105       statically allocated by these two functions.  Hence, the caller must
106       not free the memory for the returned value.
107
108       The val_gethostbyname_r(), val_gethostbyname2_r() and
109       val_gethostbyaddr_r() functions return 0 when they can resolve the
110       given host name (with or without DNSSEC validation), and a non-zero
111       error-code on failure.
112
113       The val_gethostbyaddr() and val_gethostbyaddr_r() functions return 0
114       when they can resolve the given host name (with or without DNSSEC
115       validation), and a non-zero error-code on failure.
116
117       The val_status parameter gives an indication for trustworthiness of
118       data.  If the returned hostent structure is NULL, this value gives an
119       indication of whether the non-existence of data can be trusted or not.
120

EXAMPLE

122        #include <stdio.h>
123        #include <stdlib.h>
124        #include <validator.h>
125
126           int main(int argc, char *argv[])
127           {
128                int val_status;
129                struct hostent *h = NULL;
130
131                if (argc < 2) {
132                    printf("Usage: %s <hostname>\n", argv[0]);
133                    exit(1);
134                }
135
136                h = val_gethostbyname(NULL, argv[1], &val_status);
137                printf("h_errno = %d [%s]\n", h_errno,
138                    hstrerror(h_errno));
139                if (h) {
140                    printf("Validation Status = %d [%s]\n", val_status,
141                           p_val_status(val_status));
142                }
143
144                return 0;
145           }
146

NOTES

148       These functions do not currently read the order of lookup from
149       /etc/hosts.conf.  At present, the default order is set to consult the
150       /etc/hosts file first and then query DNS.
151
152       The current versions of these functions do not support NIS lookups.
153

COPYRIGHT

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

AUTHORS

159       Abhijit Hayatnagarkar, Suresh Krishnaswamy.
160