1resolver(3RESOLV)         Resolver Library Functions         resolver(3RESOLV)
2
3
4

NAME

6       resolver,    res_ninit,    fp_resstat,    res_hostalias,    res_nquery,
7       res_nsearch,  res_nquerydomain,  res_nmkquery,  res_nsend,  res_nclose,
8       res_nsendsigned,  dn_comp,  dn_expand,  hstrerror, res_init, res_query,
9       res_search, res_mkquery,  res_send,  herror,  res_getservers,  res_set‐
10       servers, res_ndestroy - resolver routines
11

SYNOPSIS

13       BIND 8.2.2 Interfaces
14
15
16       cc [ flag ... ] file ... -lresolv  -lsocket   -lnsl  [ library ... ]
17       #include <sys/types.h>
18       #include <netinet/in.h>
19       #include <arpa/nameser.h>
20       #include <resolv.h>
21       #include <netdb.h>
22
23       int res_ninit(res_state statp);
24
25
26       void res_ndestroy(res_state statp);
27
28
29       void fp_resstat(const res_state statp, FILE *fp);
30
31
32       const char *res_hostalias(const res_state statp, const char *name,
33            char * name, char *buf, size_tbuflen);
34
35
36       int res_nquery(res_state statp, const char *dname, int class, int type,
37            u_char *answer, int datalen, int anslen);
38
39
40       int res_nsearch(res_state statp, const char *dname, int class, int type,
41            u_char *answer, int anslen);
42
43
44       int res_nquerydomain(res_state statp, const char *name,
45            const char *domain, int class, int type,
46            u_char *answer, int anslen);
47
48
49       int res_nmkquery(res_state statp, int op, const char *dname, int class,
50            int type, u_char *answer, int datalen,
51            int anslen);
52
53
54       int res_nsend(res_state statp, const u_char *msg, int msglen,
55            u_char *answer, int anslen);
56
57
58       void res_nclose(res_state statp);
59
60
61       int res_snendsigned(res_state statp, const u_char *msg,
62            int msglen, ns_tsig_key *key, u_char *answer, int anslen);
63
64
65       int dn_comp(const char *exp_dn, u_char *comp_dn, int length,
66            u_char **dnptrs, **lastdnptr);
67
68
69       int dn_expand(const u_char *msg, *eomorig, *comp_dn, char *exp_dn,
70            int length);
71
72
73       const char *hstrerror(int err);
74
75
76       void res_setservers(res_state statp, const union res_sockaddr_union *set,
77            int cnt);
78
79
80       int res_getservers(res_state statp, union res_sockaddr_union *set,
81            int cnt);
82
83
84       Deprecated Interfaces
85
86
87       cc [ flag ... ] file ... -lresolv  -lsocket   -lnsl  [ library ... ]
88       #include <sys/types.h>
89       #include <netinet/in.h>
90       #include <arpa/nameser.h>
91       #include <resolv.h>
92       #include <netdb.h>
93
94       int res_init(void)
95
96
97       int res_query(const char *dname, int class,
98            int type, u_char *answer,
99            int anslen);
100
101
102       int res_search(const char *dname, int class,
103            int type, u_char *answer, int anslen);
104
105
106       int res_mkquery(int op, const char *dname, int class,
107            int type, const char *data,int datalen,
108            struct rrec *newrr, u_char *buf, int buflen);
109
110
111       int res_send(const u_char *msg, int msglen, u_char *answer,
112            int anslen);
113
114
115       void herror(const char *s);
116
117

DESCRIPTION

119       These routines are used for making, sending, and interpreting query and
120       reply messages with Internet domain name servers.
121
122
123       State information is kept in statp and is used to control the  behavior
124       of  these  functions.  Set statp to all zeros prior to making the first
125       call to any of these functions.
126
127
128       The res_ndestroy() function should be called to free  memory  allocated
129       by res_ninit() after the last use of statp.
130
131
132       The  functions  res_init(),  res_query(),  res_search(), res_mkquery(),
133       res_send(), and herror() are deprecated. They are  supplied  for  back‐
134       wards  compatability.  They use global configuration and state informa‐
135       tion that is kept in the structure _res rather than  state  information
136       referenced through statp.
137
138
139       Most  of  the  values  in  statp and _res are initialized to reasonable
140       defaults on the first call to res_ninit()  or  res_init()  and  can  be
141       ignored.  Options  stored in statp->options or _res.options are defined
142       in <resolv.h>. They are stored as a simple bit mask containing the bit‐
143       wise OR of the options enabled.
144
145       RES_INIT         True  if  the  initial name server address and default
146                        domain name are initialized, that  is,  res_init()  or
147                        res_ninit() has been called.
148
149
150       RES_DEBUG        Print debugging messages.
151
152
153       RES_AAONLY       Accept  authoritative  answers only. With this option,
154                        res_send() will continue until it finds an  authorita‐
155                        tive  answer  or finds an error. Currently this option
156                        is not implemented.
157
158
159       RES_USEVC        Use TCP connections for queries instead of  UDP  data‐
160                        grams.
161
162
163       RES_STAYOPEN     Use  with  RES_USEVC  to  keep the TCP connection open
164                        between queries. This is a useful option for  programs
165                        that  regularly  do many queries. The normal mode used
166                        should be UDP.
167
168
169       RES_IGNTC        Ignore truncation errors; that is, do not  retry  with
170                        TCP.
171
172
173       RES_RECURSE      Set  the recursion-desired bit in queries. This is the
174                        default. res_send() and res_nsend() do not  do  itera‐
175                        tive  queries  and  expect  the  name server to handle
176                        recursion.
177
178
179       RES_DEFNAMES     If set,  res_search()  and  res_nsearch()  append  the
180                        default  domain  name  to single-component names, that
181                        is, names that do not contain a dot.  This  option  is
182                        enabled by default.
183
184
185       RES_DNSRCH       If  this option is set, res_search() and res_nsearch()
186                        search for host names in the  current  domain  and  in
187                        parent  domains.  See hostname(1). This option is used
188                        by  the  standard  host  lookup   routine   gethostby‐
189                        name(3NSL). This option is enabled by default.
190
191
192       RES_NOALIASES    This  option turns off the user level aliasing feature
193                        controlled by the  HOSTALIASES  environment  variable.
194                        Network daemons should set this option.
195
196
197       RES_BLAST        If the RES_BLAST option is defined, resolver() queries
198                        will be sent to all servers. If the  RES_BLAST  option
199                        is  not defined, but RES_ROTATE is , the list of name‐
200                        servers are rotated according to a round-robin scheme.
201                        RES_BLAST overrides RES_ROTATE.
202
203
204       RES_ROTATE       This  option  causes  res_nsend()  and  res_send()  to
205                        rotate the list of nameservers  in  statp->nsaddr_list
206                        or _res.nsaddr_list.
207
208
209       RES_KEEPTSIG     This option causes res_nsendsigned() to leave the mes‐
210                        sage unchanged after TSIG verification. Otherwise  the
211                        TSIG  record  would be removed and the header would be
212                        updated.
213
214
215   res_ninit(), res_init()
216       The res_ninit() and res_init() routines read the configuration file, if
217       any  is  present,  to  get the default domain name, search list and the
218       Internet address of the local name server(s). See resolv.conf(4). If no
219       server is configured, res_init() or res_ninit() will try to obtain name
220       resolution services from the host on which it is running.  The  current
221       domain  name  is defined by domainname(1M), or by the hostname if it is
222       not specified in the configuration file. Use the  environment  variable
223       LOCALDOMAIN  to override the domain name. This environment variable may
224       contain several blank-separated tokens if  you  wish  to  override  the
225       search  list on a per-process basis. This is similar to the search com‐
226       mand in the configuration file. You can set the RES_OPTIONS environment
227       variable  to override certain internal resolver options. You can other‐
228       wise set them by changing fields in the statp /_res structure. Alterna‐
229       tively,  they  are inherited from the configuration file's options com‐
230       mand. See resolv.conf(4) for information regarding the  syntax  of  the
231       RES_OPTIONS environment variable. Initialization normally occurs on the
232       first call to one of the other resolver routines.
233
234   res_nquery(), res_query()
235       The res_nquery() and res_query() functions provide  interfaces  to  the
236       server  query  mechanism.  They construct a query, send it to the local
237       server, await a response, and make preliminary checks on the reply. The
238       query  requests  information  of  the  specified type and class for the
239       specified fully-qualified domain name dname. The reply message is  left
240       in  the  answer  buffer  with  length  anslen  supplied  by the caller.
241       res_nquery() and res_query() return the length of  the  answer,  or  -1
242       upon error.
243
244
245       The  res_nquery()  and res_query() routines return a length that may be
246       bigger than anslen. In that case, retry the query with  a  larger  buf.
247       The  answer  to  the second query may be larger still], so it is recom‐
248       mended that you supply a buf larger than the  answer  returned  by  the
249       previous  query.  answer  must be large enough to receive a maximum UDP
250       response from the server or parts of the answer will be  silently  dis‐
251       carded. The default maximum UDP response size is 512 bytes.
252
253   res_nsearch(), res_search()
254       The  res_nsearch()  and  res_search() routines make a query and await a
255       response, just like like res_nquery()  and  res_query().  In  addition,
256       they  implement the default and search rules controlled by the RES_DEF‐
257       NAMES and RES_DNSRCH options. They return the length of the first  suc‐
258       cessful reply which is stored in answer. On error, they reurn -1.
259
260
261       The res_nsearch() and res_search() routines return a length that may be
262       bigger than anslen. In that case, retry the query with  a  larger  buf.
263       The  answer  to  the second query may be larger still], so it is recom‐
264       mended that you supply a buf larger than the  answer  returned  by  the
265       previous  query.  answer  must be large enough to receive a maximum UDP
266       response from the server or parts of the answer will be  silently  dis‐
267       carded. The default maximum UDP response size is 512 bytes.
268
269   res_nquerydomain()
270       The  res_nquerydomain() function calls res_query() on the concatenation
271       of name and domain, removing a trailing dot  from  name  if  domain  is
272       NULL.
273
274   res_nmkquery(), res_mkquery()
275       These  routines  are used by res_nquery() and res_query(). The res_nmk‐
276       query() and res_mkquery() functions construct a standard query  message
277       and  place  it in buf. The routine returns the size of the query, or -1
278       if the query is larger than buflen. The query type op is usually QUERY,
279       but  can  be  any  of  the query types defined in <arpa/nameser.h>. The
280       domain name for the query is given by dname. newrr is currently  unused
281       but is intended for making update messages.
282
283   res_nsend(), res_send(), res_nsendsigned()
284       The res_nsend(), res_send(), and res_nsendsigned() routines send a pre-
285       formatted query that returns an answer. The routine  calls  res_ninit()
286       or  res_init().  If RES_INIT is not set, the routine sends the query to
287       the local name server and handles timeouts and  retries.  Additionally,
288       the res_nsendsigned() uses TSIG signatures to add authentication to the
289       query and verify the response. In this case, only one name server  will
290       be  contacted.  The routines return the length of the reply message, or
291       -1 if there are errors.
292
293
294       The res_nsend() and res_send() routines return a  length  that  may  be
295       bigger  than  anslen.  In that case, retry the query with a larger buf.
296       The answer to the second query may be larger still], so  it  is  recom‐
297       mended  that  you  supply  a buf larger than the answer returned by the
298       previous query. answer must be large enough to receive  a  maximum  UDP
299       response  from  the server or parts of the answer will be silently dis‐
300       carded. The default maximum UDP response size is 512 bytes.
301
302   fp_resstat()
303       The  function  fp_resstat()  prints  out  the  active  flag   bits   in
304       statp->options preceded by the text ";; res options:" on file.
305
306   res_hostalias()
307       The  function  res_hostalias() looks up name in the file referred to by
308       the HOSTALIASES environment variable and returns  the  fully  qualified
309       host  name.  If name is not found or an error occurs, NULL is returned.
310       res_hostalias() stores the result in buf.
311
312   res_nclose()
313       The res_nclose() function closes  any  open  files  referenced  through
314       statp.
315
316   res_ndestroy()
317       The  res_ndestroy()  function calls res_nclose(), then frees any memory
318       allocated by res_ninit() referenced through statp.
319
320   dn_comp()
321       The dn_comp() function compresses the domain name exp_dn and stores  it
322       in  comp_dn.  The dn_comp() function returns the size of the compressed
323       name, or −1 if there were errors. length  is  the  size  of  the  array
324       pointed to by comp_dn.
325
326
327       The  dnptrs  parameter is a pointer to the head of the list of pointers
328       to previously compressed  names  in  the  current  message.  The  first
329       pointer  must point to the beginning of the message. The list ends with
330       NULL. The limit to the array is specified by lastdnptr.
331
332
333       A side effect of calling dn_comp() is to update the  list  of  pointers
334       for  labels  inserted into the message by dn_comp() as the name is com‐
335       pressed. If dnptrs is NULL, names are not compressed. If  lastdnptr  is
336       NULL, dn_comp() does not update the list of labels.
337
338   dn_expand()
339       The  dn_expand() function expands the compressed domain name comp_dn to
340       a full domain name. The compressed name is  contained  in  a  query  or
341       reply  message.  msg is a pointer to the beginning of that message. The
342       uncompressed name is placed in the buffer indicated by exp_dn, which is
343       of  size  length. The dn_expand() function returns the size of the com‐
344       pressed name, or −1 if there was an error.
345
346   hstrerror(), herror()
347       The variables  statp->res_h_errno  and  _res.res_h_errno  and  external
348       variable  h_errno  are  set  whenever an error occurs during a resolver
349       operation. The following definitions are given in <netdb.h>:
350
351         #define NETDB_INTERNAL -1 /* see errno */
352         #define NETDB_SUCCESS  0  /* no problem */
353         #define HOST_NOT_FOUND 1  /* Authoritative Answer Host not found */
354         #define TRY_AGAIN      2  /* Non-Authoritative not found, or SERVFAIL */
355         #define NO_RECOVERY    3  /* Non-Recoverable: FORMERR, REFUSED, NOTIMP*/
356         #define NO_DATA        4  /* Valid name, no data for requested type */
357
358
359
360
361       The herror() function writes a message to the  diagnostic  output  con‐
362       sisting  of  the string parameters, the constant string ":", and a mes‐
363       sage corresponding to the value of h_errno.
364
365
366       The hstrerror() function returns a string, which is  the  message  text
367       that corresponds to the value of the err parameter.
368
369   res_setservers(), res_getservers()
370       The functions res_getservers() and res_setservers() are used to get and
371       set the list of servers to be queried.
372

FILES

374       /etc/resolv.conf    resolver configuration file
375
376

ATTRIBUTES

378       See attributes(5) for descriptions of the following attributes:
379
380
381
382
383       ┌─────────────────────────────┬─────────────────────────────┐
384       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
385       ├─────────────────────────────┼─────────────────────────────┤
386       │Availability                 │SUNWcsl (32-bit)             │
387       │                             │SUNWcslx (64-bit)            │
388       ├─────────────────────────────┼─────────────────────────────┤
389       │Interface Stability          │Committed                    │
390       ├─────────────────────────────┼─────────────────────────────┤
391       │MT-Level                     │Unsafe    for    deprecated  │
392       │                             │interfaces; MT-Safe for all  │
393       │                             │others.                      │
394       └─────────────────────────────┴─────────────────────────────┘
395

SEE ALSO

397       domainname(1M), gethostbyname(3NSL),  libresolv(3LIB),  resolv.conf(4),
398       attributes(5)
399
400
401       Lottor,  M.  RFC  1033, Domain Administrators Operations Guide. Network
402       Working Group. November 1987.
403
404
405       Mockapetris, Paul. RFC 1034, Domain Names -  Concepts  and  Facilities.
406       Network Working Group. November 1987.
407
408
409       Mockapetris, Paul. RFC 1035, Domain Names - Implementation and Specifi‐
410       cation. Network Working Group. November 1987.
411
412
413       Partridge, Craig. RFC 974, Mail Routing and the Domain System.  Network
414       Working Group. January 1986.
415
416
417       Stahl, M. RFC 1032, Domain Administrators Guide. Network Working Group.
418       November 1987.
419
420
421       Vixie, Paul, Dunlap, Kevin J., Karels, Michael J.  Name  Server  Opera‐
422       tions Guide for BIND. Internet Software Consortium, 1996.
423

NOTES

425       When  the  caller supplies a work buffer, for example the answer buffer
426       argument to res_nsend() or res_send(), the buffer should be aligned  on
427       an  eight  byte  boundary.  Otherwise,  an  error  such as a SIGBUS may
428       result.
429
430
431
432SunOS 5.11                        26 Dec 2006                resolver(3RESOLV)
Impressum