| .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
| .\" |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" |
| .\" References consulted: |
| .\" Linux libc source code |
| .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) |
| .\" 386BSD man pages |
| .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) |
| .\" Modified 2004-10-31 by aeb |
| .\" |
| .TH RESOLVER 3 2004-10-31 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, |
| dn_comp, dn_expand \- resolver routines |
| .SH SYNOPSIS |
| .nf |
| .B #include <netinet/in.h> |
| .B #include <arpa/nameser.h> |
| .B #include <resolv.h> |
| .B extern struct state _res; |
| .sp |
| .B int res_init(void); |
| .sp |
| .BI "int res_query(const char *" dname ", int " class ", int " type , |
| .RS |
| .BI "unsigned char *" answer ", int " anslen ); |
| .RE |
| .sp |
| .BI "int res_search(const char *" dname ", int " class ", int " type , |
| .RS |
| .BI "unsigned char *" answer ", int " anslen ); |
| .RE |
| .sp |
| .BI "int res_querydomain(const char *" name ", const char *" domain , |
| .RS |
| .BI "int " class ", int " type ", unsigned char *" answer , |
| .BI "int " anslen ); |
| .RE |
| .sp |
| .BI "int res_mkquery(int " op ", const char *" dname ", int " class , |
| .RS |
| .BI "int " type ", char *" data ", int " datalen ", struct rrec *" newrr , |
| .BI "char *" buf ", int " buflen ); |
| .RE |
| .sp |
| .BI "int res_send(const char *" msg ", int " msglen ", char *" answer , |
| .RS |
| .BI "int " anslen ); |
| .RE |
| .sp |
| .BI "int dn_comp(unsigned char *" exp_dn ", unsigned char *" comp_dn , |
| .RS |
| .BI "int " length ", unsigned char **" dnptrs ", unsigned char *" exp_dn , |
| .BI "unsigned char **" lastdnptr ); |
| .RE |
| .sp |
| .BI "int dn_expand(unsigned char *" msg ", unsigned char *" eomorig , |
| .RS |
| .BI "unsigned char *" comp_dn ", unsigned char *" exp_dn , |
| .BI "int " length ); |
| .RE |
| .fi |
| .sp |
| Link with \fI\-lresolv\fP. |
| .SH DESCRIPTION |
| These functions make queries to and interpret the responses from Internet |
| domain name servers. |
| .PP |
| The |
| .BR res_init () |
| function reads the configuration files (see |
| resolv.conf(5)) to get the default domain name, search order and name |
| server address(es). |
| If no server is given, the local host is tried. |
| If no domain is given, that associated with the local host is used. |
| It can be overridden with the environment variable |
| .BR LOCALDOMAIN . |
| .BR res_init () |
| is normally executed by the first call to one of the |
| other functions. |
| .PP |
| The |
| .BR res_query () |
| function queries the name server for the |
| fully qualified domain name \fIname\fP of specified \fItype\fP and |
| \fIclass\fP. |
| The reply is left in the buffer \fIanswer\fP of length |
| \fIanslen\fP supplied by the caller. |
| .PP |
| The |
| .BR res_search () |
| function makes a query and waits for the response |
| like |
| .BR res_query (), |
| but in addition implements the default and search |
| rules controlled by |
| .B RES_DEFNAMES |
| and |
| .B RES_DNSRCH |
| (see description of |
| \fI_res\fP options below). |
| .PP |
| The |
| .BR res_querydomain () |
| function makes a query using |
| .BR res_query () |
| on the concatenation of \fIname\fP and \fIdomain\fP. |
| .PP |
| The following functions are lower-level routines used by |
| .BR res_query (). |
| .PP |
| The |
| .BR res_mkquery () |
| function constructs a query message in \fIbuf\fP |
| of length \fIbuflen\fP for the domain name \fIdname\fP. |
| The query type |
| \fIop\fP is usually |
| .BR QUERY , |
| but can be any of the types defined in |
| \fI<arpa/nameser.h>\fP. |
| \fInewrr\fP is currently unused. |
| .PP |
| The |
| .BR res_send () |
| function sends a pre-formatted query given in |
| \fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP |
| which is of length \fIanslen\fP. |
| It will call |
| .BR res_init (), |
| if it |
| has not already been called. |
| .PP |
| The |
| .BR dn_comp () |
| function compresses the domain name \fIexp_dn\fP |
| and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP. |
| The compression uses an array of pointers \fIdnptrs\fP to previously |
| compressed names in the current message. |
| The first pointer points |
| to the beginning of the message and the list ends with NULL. |
| The limit of the array is specified by \fIlastdnptr\fP. |
| If \fIdnptr\fP is NULL, domain names are not compressed. |
| If \fIlastdnptr\fP is NULL, the list |
| of labels is not updated. |
| .PP |
| The |
| .BR dn_expand () |
| function expands the compressed domain name |
| \fIcomp_dn\fP to a full domain name, which is placed in the buffer |
| \fIexp_dn\fP of size \fIlength\fP. |
| The compressed name is contained |
| in a query or reply message, and \fImsg\fP points to the beginning of |
| the message. |
| .PP |
| The resolver routines use global configuration and state information |
| contained in the structure \fI_res\fP, which is defined in |
| \fI<resolv.h>\fP. |
| The only field that is normally manipulated by the |
| user is \fI_res.options\fP. |
| This field can contain the bitwise "OR" |
| of the following options: |
| .TP |
| .B RES_INIT |
| True if |
| .BR res_init () |
| has been called. |
| .TP |
| .B RES_DEBUG |
| Print debugging messages. |
| .TP |
| .B RES_AAONLY |
| Accept authoritative answers only. |
| .BR res_send () |
| continues until |
| it finds an authoritative answer or returns an error. [Not currently |
| implemented]. |
| .TP |
| .B RES_USEVC |
| Use TCP connections for queries rather than UDP datagrams. |
| .TP |
| .B RES_PRIMARY |
| Query primary domain name server only. |
| .TP |
| .B RES_IGNTC |
| Ignore truncation errors. |
| Don't retry with TCP. [Not currently |
| implemented]. |
| .TP |
| .B RES_RECURSE |
| Set the recursion desired bit in queries. |
| Recursion is carried out |
| by the domain name server, not by |
| .BR res_send (). |
| [Enabled by default]. |
| .TP |
| .B RES_DEFNAMES |
| If set, |
| .BR res_search () |
| will append the default domain name to |
| single component names, i.e., those that do not contain a dot. |
| [Enabled by default]. |
| .TP |
| .B RES_STAYOPEN |
| Used with |
| .B RES_USEVC |
| to keep the TCP connection open between queries. |
| .TP |
| .B RES_DNSRCH |
| If set, |
| .BR res_search () |
| will search for hostnames in the current |
| domain and in parent domains. |
| This option is used by |
| .BR gethostbyname (3). |
| [Enabled by default]. |
| .SH "RETURN VALUE" |
| The |
| .BR res_init () |
| function returns 0 on success, or \-1 if an error |
| occurs. |
| .PP |
| The |
| .BR res_query (), |
| .BR res_search (), |
| .BR res_querydomain (), |
| .BR res_mkquery () |
| and |
| .BR res_send () |
| functions return the length |
| of the response, or \-1 if an error occurs. |
| .PP |
| The |
| .BR dn_comp () |
| and |
| .BR dn_expand () |
| functions return the length |
| of the compressed name, or \-1 if an error occurs. |
| .SH FILES |
| .nf |
| /etc/resolv.conf resolver configuration file |
| /etc/host.conf resolver configuration file |
| .fi |
| .SH "CONFORMING TO" |
| 4.3BSD. |
| .SH "SEE ALSO" |
| .BR gethostbyname (3), |
| .BR resolv.conf (5), |
| .BR resolver (5), |
| .BR hostname (7), |
| .BR named (8) |