1RESOLVER(3)                Linux Programmer's Manual               RESOLVER(3)
2
3
4

NAME

6       res_ninit,  res_nquery,  res_nsearch,  res_nquerydomain,  res_nmkquery,
7       res_nsend,   res_init,    res_query,    res_search,    res_querydomain,
8       res_mkquery, res_send, dn_comp, dn_expand - resolver routines
9

SYNOPSIS

11       #include <netinet/in.h>
12       #include <arpa/nameser.h>
13       #include <resolv.h>
14
15       struct __res_state;
16       typedef struct __res_state *res_state;
17
18       int res_ninit(res_state statep);
19
20       int res_nquery(res_state statep,
21                  const char *dname, int class, int type,
22                  unsigned char *answer, int anslen);
23
24       int res_nsearch(res_state statep,
25                  const char *dname, int class, int type,
26                  unsigned char *answer, int anslen);
27
28       int res_nquerydomain(res_state statep,
29                  const char *name, const char *domain,
30                  int class, int type, unsigned char *answer,
31                  int anslen);
32
33       int res_nmkquery(res_state statep,
34                  int op, const char *dname, int class,
35                  int type, const unsigned char *data, int datalen,
36                  const unsigned char *newrr,
37                  unsigned char *buf, int buflen);
38
39       int res_nsend(res_state statep,
40                  const unsigned char *msg, int msglen,
41                  unsigned char *answer, int anslen);
42
43       int dn_comp(const char *exp_dn, unsigned char *comp_dn,
44                  int length, unsigned char **dnptrs,
45                  unsigned char **lastdnptr);
46
47       int dn_expand(const unsigned char *msg,
48                  const unsigned char *eomorig,
49                  const unsigned char *comp_dn, char *exp_dn,
50                  int length);
51
52   Deprecated
53       extern struct __res_state _res;
54
55       int res_init(void);
56
57       int res_query(const char *dname, int class, int type,
58                  unsigned char *answer, int anslen);
59
60       int res_search(const char *dname, int class, int type,
61                  unsigned char *answer, int anslen);
62
63       int res_querydomain(const char *name, const char *domain,
64                  int class, int type, unsigned char *answer,
65                  int anslen);
66
67       int res_mkquery(int op, const char *dname, int class,
68                  int type, const unsigned char *data, int datalen,
69                  const unsigned char *newrr,
70                  unsigned char *buf, int buflen);
71
72       int res_send(const unsigned char *msg, int msglen,
73                  unsigned char *answer, int anslen);
74
75       Link with -lresolv.
76

DESCRIPTION

78       Note:  This  page is incomplete (various resolver functions provided by
79       glibc are not described) and likely out of date.
80
81       The functions  described  below  make  queries  to  and  interpret  the
82       responses from Internet domain name servers.
83
84       The  API  consists  of a set of more modern, reentrant functions and an
85       older set of nonreentrant functions that  have  been  superseded.   The
86       traditional  resolver interfaces such as res_init() and res_query() use
87       some static (global) state stored  in  the  _res  structure,  rendering
88       these  functions  non-thread-safe.   BIND  8.2  introduced a set of new
89       interfaces res_ninit(), res_nquery(), and so on, which take a res_state
90       as their first argument, so you can use a per-thread resolver state.
91
92       The  res_ninit()  and res_init() functions read the configuration files
93       (see resolv.conf(5)) to get the default domain  name  and  name  server
94       address(es).   If  no  server is given, the local host is tried.  If no
95       domain is given, that associated with the local host is used.   It  can
96       be  overridden  with the environment variable LOCALDOMAIN.  res_ninit()
97       or res_init() is normally executed by the first  call  to  one  of  the
98       other functions.
99
100       The  res_nquery()  and  res_query() functions query the name server for
101       the fully qualified domain name name of specified type and class.   The
102       reply  is  left  in  the buffer answer of length anslen supplied by the
103       caller.
104
105       The res_nsearch() and res_search() functions make a query and waits for
106       the  response  like  res_nquery() and res_query(), but in addition they
107       implement the default and search rules controlled by  RES_DEFNAMES  and
108       RES_DNSRCH (see description of _res options below).
109
110       The  res_nquerydomain()  and  res_querydomain()  functions make a query
111       using res_nquery()/res_query() on the concatenation of name and domain.
112
113       The   following   functions   are   lower-level   routines   used    by
114       res_query()/res_query().
115
116       The  res_nmkquery()  and res_mkquery() functions construct a query mes‐
117       sage in buf of length buflen for the domain name dname.  The query type
118       op is one of the following (typically QUERY):
119
120       QUERY  Standard query.
121
122       IQUERY Inverse  query.  This option was removed in glibc 2.26, since it
123              has not been supported by DNS servers for a very long time.
124
125       NS_NOTIFY_OP
126              Notify secondary of SOA (Start of Authority) change.
127
128       newrr is currently unused.
129
130       The res_nsend() and res_send() function send a preformatted query given
131       in  msg  of  length msglen and returns the answer in answer which is of
132       length anslen.  They will call res_ninit()/res_init()  if  it  has  not
133       already been called.
134
135       The  dn_comp() function compresses the domain name exp_dn and stores it
136       in the buffer comp_dn of length length.  The compression uses an  array
137       of  pointers  dnptrs to previously compressed names in the current mes‐
138       sage.  The first pointer points to the beginning of the message and the
139       list ends with NULL.  The limit of the array is specified by lastdnptr.
140       If dnptr is NULL, domain names are not  compressed.   If  lastdnptr  is
141       NULL, the list of labels is not updated.
142
143       The  dn_expand() function expands the compressed domain name comp_dn to
144       a full domain name, which is  placed  in  the  buffer  exp_dn  of  size
145       length.   The compressed name is contained in a query or reply message,
146       and msg points to the beginning of the message.
147
148       The resolver routines use configuration and state information contained
149       in a __res_state structure (either passed as the statep argument, or in
150       the global variable _res, in the case of the older  nonreentrant  func‐
151       tions).   The only field of this structure that is normally manipulated
152       by the user is the options field.  This field can contain  the  bitwise
153       "OR" of the following options:
154
155       RES_INIT
156              True if res_ninit() or res_init() has been called.
157
158       RES_DEBUG
159              Print  debugging  messages.   This  option  is available only if
160              glibc was  built  with  debugging  enabled,  which  is  not  the
161              default.
162
163       RES_AAONLY (unimplemented; deprecated in glibc 2.25)
164              Accept  authoritative  answers only.  res_send() continues until
165              it finds an authoritative answer  or  returns  an  error.   This
166              option  was  present  but  unimplemented  in glibc until version
167              2.24; since glibc 2.25, it is deprecated, and its usage produces
168              a warning.
169
170       RES_USEVC
171              Use TCP connections for queries rather than UDP datagrams.
172
173       RES_PRIMARY (unimplemented; deprecated in glibc 2.25)
174              Query  primary domain name server only.  This option was present
175              but unimplemented in glibc until version 2.24; since glibc 2.25,
176              it is deprecated, and its usage produces a warning.
177
178       RES_IGNTC
179              Ignore truncation errors.  Don't retry with TCP.
180
181       RES_RECURSE
182              Set  the recursion desired bit in queries.  Recursion is carried
183              out by the domain name server, not by res_send().   [Enabled  by
184              default].
185
186       RES_DEFNAMES
187              If set, res_search() will append the default domain name to sin‐
188              gle component names—that is, those that do not  contain  a  dot.
189              [Enabled by default].
190
191       RES_STAYOPEN
192              Used  with  RES_USEVC  to  keep  the TCP connection open between
193              queries.
194
195       RES_DNSRCH
196              If set, res_search() will search for hostnames  in  the  current
197              domain and in parent domains.  This option is used by gethostby‐
198              name(3).  [Enabled by default].
199
200       RES_INSECURE1
201              Accept a response from a wrong server.   This  can  be  used  to
202              detect potential security hazards, but you need to compile glibc
203              with debugging enabled and use RES_DEBUG option (for debug  pur‐
204              pose only).
205
206       RES_INSECURE2
207              Accept  a  response  which  contains a wrong query.  This can be
208              used to detect potential security hazards, but you need to  com‐
209              pile  glibc with debugging enabled and use RES_DEBUG option (for
210              debug purpose only).
211
212       RES_NOALIASES
213              Disable usage of HOSTALIASES environment variable.
214
215       RES_USE_INET6
216              Try an AAAA query before an A query inside the  gethostbyname(3)
217              function,  and  map IPv4 responses in IPv6 "tunneled form" if no
218              AAAA records are found but an A record set exists.  Since  glibc
219              2.25,  this option is deprecated, and its usage produces a warn‐
220              ing; applications should use getaddrinfo(3), rather  than  geth‐
221              ostbyname(3).
222
223       RES_ROTATE
224              Causes  round-robin  selection  of name servers from among those
225              listed.  This has the effect of spreading the query  load  among
226              all listed servers, rather than having all clients try the first
227              listed server first every time.
228
229       RES_NOCHECKNAME (unimplemented; deprecated in glibc 2.25)
230              Disable the modern BIND checking of incoming hostnames and  mail
231              names  for invalid characters such as underscore (_), non-ASCII,
232              or control characters.  This option was present in  glibc  until
233              version  2.24; since glibc 2.25, it is deprecated, and its usage
234              produces a warning.
235
236       RES_KEEPTSIG (unimplemented; deprecated in glibc 2.25)
237              Do not strip TSIG records.  This option was present but unimple‐
238              mented in glibc until version 2.24; since glibc 2.25, it is dep‐
239              recated, and its usage produces a warning.
240
241       RES_BLAST  (unimplemented; deprecated in glibc 2.25)
242              Send each query simultaneously and recursively to  all  servers.
243              This option was present but unimplemented in glibc until version
244              2.24; since glibc 2.25, it is deprecated, and its usage produces
245              a warning.
246
247       RES_USEBSTRING (glibc 2.3.4 to 2.24)
248              Make  reverse  IPv6 lookups using the bit-label format described
249              in RFC 2673; if this option is not set (which is  the  default),
250              then  nibble  format  is used.  This option was removed in glibc
251              2.25, since it relied on a backward-incompatible  DNS  extension
252              that was never deployed on the Internet.
253
254       RES_NOIP6DOTINT (glibc 2.24 and earlier)
255              Use  ip6.arpa  zone  in  IPv6 reverse lookup instead of ip6.int,
256              which is deprecated since glibc 2.3.4.  This option  is  present
257              in  glibc  up to and including version 2.24, where it is enabled
258              by default.  In glibc 2.25, this option was removed.
259
260       RES_USE_EDNS0 (since glibc 2.6)
261              Enables support for the DNS extensions (EDNS0) described in  RFC
262              2671.
263
264       RES_SNGLKUP (since glibc 2.10)
265              By  default,  glibc  performs  IPv4 and IPv6 lookups in parallel
266              since version 2.9.  Some appliance  DNS  servers  cannot  handle
267              these  queries  properly  and  make the requests time out.  This
268              option disables the behavior and makes glibc  perform  the  IPv6
269              and  IPv4 requests sequentially (at the cost of some slowdown of
270              the resolving process).
271
272       RES_SNGLKUPREOP
273              When RES_SNGLKUP option is enabled, opens a new socket  for  the
274              each request.
275
276       RES_USE_DNSSEC
277              Use  DNSSEC  with  OK  bit  in  OPT record.  This option implies
278              RES_USE_EDNS0.
279
280       RES_NOTLDQUERY
281              Do not look up unqualified name as a top-level domain (TLD).
282
283       RES_DEFAULT
284              Default  option  which   implies:   RES_RECURSE,   RES_DEFNAMES,
285              RES_DNSRCH and RES_NOIP6DOTINT.
286

RETURN VALUE

288       The  res_ninit() and res_init() functions return 0 on success, or -1 if
289       an error occurs.
290
291       The res_nquery(), res_query(), res_nsearch(), res_search(), res_nquery‐
292       domain(),     res_querydomain(),     res_nmkquery(),     res_mkquery(),
293       res_nsend(),  and  res_send()  functions  return  the  length  of   the
294       response, or -1 if an error occurs.
295
296       The  dn_comp()  and dn_expand() functions return the length of the com‐
297       pressed name, or -1 if an error occurs.
298

FILES

300       /etc/resolv.conf
301              resolver configuration file
302
303       /etc/host.conf
304              resolver configuration file
305

ATTRIBUTES

307       For  an  explanation  of  the  terms  used   in   this   section,   see
308       attributes(7).
309
310       ┌───────────────────────────────────┬───────────────┬────────────────┐
311Interface                          Attribute     Value          
312       ├───────────────────────────────────┼───────────────┼────────────────┤
313res_ninit(), res_nquery(),         │ Thread safety │ MT-Safe locale │
314res_nsearch(), res_nquerydomain(), │               │                │
315res_nsend()                        │               │                │
316       ├───────────────────────────────────┼───────────────┼────────────────┤
317res_nmkquery(), dn_comp(),         │ Thread safety │ MT-Safe        │
318dn_expand()                        │               │                │
319       └───────────────────────────────────┴───────────────┴────────────────┘
320

CONFORMING TO

322       4.3BSD.
323

SEE ALSO

325       gethostbyname(3), resolv.conf(5), resolver(5), hostname(7), named(8)
326
327       The GNU C library source file resolv/README.
328

COLOPHON

330       This page is part of release 4.15 of the Linux  man-pages  project.   A
331       description  of  the project, information about reporting bugs, and the
332       latest    version    of    this    page,    can     be     found     at
333       https://www.kernel.org/doc/man-pages/.
334
335
336
337GNU                               2017-09-15                       RESOLVER(3)
Impressum