diff options
Diffstat (limited to 'man/man3/resolver.3')
| -rw-r--r-- | man/man3/resolver.3 | 511 |
1 files changed, 511 insertions, 0 deletions
diff --git a/man/man3/resolver.3 b/man/man3/resolver.3 new file mode 100644 index 000000000..c54337218 --- /dev/null +++ b/man/man3/resolver.3 @@ -0,0 +1,511 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and (C) Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 (date) "Linux man-pages (unreleased)" +.SH NAME +res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend, +res_nclose, +res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, +dn_comp, dn_expand \- +resolver routines +.SH LIBRARY +Resolver library +.RI ( libresolv ", " \-lresolv ) +.SH SYNOPSIS +.nf +.B #include <netinet/in.h> +.B #include <arpa/nameser.h> +.B #include <resolv.h> +.P +.B struct __res_state; +.B typedef struct __res_state *res_state; +.P +.BI "int res_ninit(res_state " statep ); +.P +.BI "void res_nclose(res_state " statep ); +.P +.BI "int res_nquery(res_state " statep , +.BI " const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.BI "int res_nsearch(res_state " statep , +.BI " const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.BI "int res_nquerydomain(res_state " statep , +.BI " const char *" name ", const char *" domain , +.BI " int " class ", int " type ", unsigned char " answer [. anslen ], +.BI " int " anslen ); +.P +.BI "int res_nmkquery(res_state " statep , +.BI " int " op ", const char *" dname ", int " class , +.BI " int " type ", const unsigned char " data [. datalen "], \ +int " datalen , +.BI " const unsigned char *" newrr , +.BI " unsigned char " buf [. buflen "], int " buflen ); +.P +.BI "int res_nsend(res_state " statep , +.BI " const unsigned char " msg [. msglen "], int " msglen , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.BI "int dn_comp(const char *" exp_dn ", unsigned char " comp_dn [. length ], +.BI " int " length ", unsigned char **" dnptrs , +.BI " unsigned char **" lastdnptr ); +.P +.BI "int dn_expand(const unsigned char *" msg , +.BI " const unsigned char *" eomorig , +.BI " const unsigned char *" comp_dn ", char " exp_dn [. length ], +.BI " int " length ); +.P +.B [[deprecated]] extern struct __res_state _res; +.P +.B [[deprecated]] int res_init(void); +.P +.B [[deprecated]] +.BI "int res_query(const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.B [[deprecated]] +.BI "int res_search(const char *" dname ", int " class ", int " type , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.P +.B [[deprecated]] +.BI "int res_querydomain(const char *" name ", const char *" domain , +.BI " int " class ", int " type ", unsigned char " answer [. anslen ], +.BI " int " anslen ); +.P +.B [[deprecated]] +.BI "int res_mkquery(int " op ", const char *" dname ", int " class , +.BI " int " type ", const unsigned char " data [. datalen "], \ +int " datalen , +.BI " const unsigned char *" newrr , +.BI " unsigned char " buf [. buflen "], int " buflen ); +.P +.B [[deprecated]] +.BI "int res_send(const unsigned char " msg [. msglen "], int " msglen , +.BI " unsigned char " answer [. anslen "], int " anslen ); +.fi +.SH DESCRIPTION +.B Note: +This page is incomplete (various resolver functions provided by glibc +are not described) and likely out of date. +.P +The functions described below make queries to and interpret +the responses from Internet domain name servers. +.P +The API consists of a set of more modern, reentrant functions +and an older set of nonreentrant functions that have been superseded. +The traditional resolver interfaces such as +.BR res_init () +and +.BR res_query () +use some static (global) state stored in the +.I _res +structure, rendering these functions non-thread-safe. +BIND 8.2 introduced a set of new interfaces +.BR res_ninit (), +.BR res_nquery (), +and so on, which take a +.I res_state +as their first argument, so you can use a per-thread resolver state. +.P +The +.BR res_ninit () +and +.BR res_init () +functions read the configuration files (see +.BR resolv.conf (5)) +to get the default domain name 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_ninit () +or +.BR res_init () +is normally executed by the first call to one of the +other functions. +Every call to +.BR res_ninit () +requires a corresponding call to +.BR res_nclose () +to free memory allocated by +.BR res_ninit () +and subsequent calls to +.BR res_nquery (). +.P +The +.BR res_nquery () +and +.BR res_query () +functions query 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. +.P +The +.BR res_nsearch () +and +.BR res_search () +functions make a query and waits for the response like +.BR res_nquery () +and +.BR res_query (), +but in addition they implement the default and search +rules controlled by +.B RES_DEFNAMES +and +.B RES_DNSRCH +(see description of +\fI_res\fP options below). +.P +The +.BR res_nquerydomain () +and +.BR res_querydomain () +functions make a query using +.BR res_nquery ()/ res_query () +on the concatenation of \fIname\fP and \fIdomain\fP. +.P +The following functions are lower-level routines used by +.BR res_nquery ()/ res_query (). +.P +The +.BR res_nmkquery () +and +.BR res_mkquery () +functions construct a query message in \fIbuf\fP +of length \fIbuflen\fP for the domain name \fIdname\fP. +The query type +\fIop\fP is one of the following (typically +.BR QUERY ): +.TP +.B QUERY +Standard query. +.TP +.B IQUERY +Inverse query. +This option was removed in glibc 2.26, +.\" commit e4e794841e3140875f2aa86b90e2ada3d61e1244 +since it has not been supported by DNS servers for a very long time. +.TP +.B NS_NOTIFY_OP +Notify secondary of SOA (Start of Authority) change. +.P +\fInewrr\fP is currently unused. +.P +The +.BR res_nsend () +and +.BR res_send () +function send a preformatted query given in +\fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP +which is of length \fIanslen\fP. +They will call +.BR res_ninit ()/ res_init () +if it has not already been called. +.P +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. +.P +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. +.P +The resolver routines use configuration and state information +contained in a +.I __res_state +structure (either passed as the +.I statep +argument, or in the global variable +.IR _res , +in the case of the older nonreentrant functions). +The only field of this structure that is normally manipulated by the +user is the +.I options +field. +This field can contain the bitwise "OR" +of the following options: +.TP +.B RES_INIT +True if +.BR res_ninit () +or +.BR res_init () +has been called. +.TP +.B RES_DEBUG +Print debugging messages. +This option is available only if glibc was built with debugging enabled, +.\" See resolv/README. +.\" Support for RES_DEBUG was made conditional in glibc 2.2. +which is not the default. +.TP +.BR RES_AAONLY " (unimplemented; deprecated in glibc 2.25)" +Accept authoritative answers only. +.BR res_send () +continues until +it finds an authoritative answer or returns an error. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.B RES_USEVC +Use TCP connections for queries rather than UDP datagrams. +.TP +.BR RES_PRIMARY " (unimplemented; deprecated in glibc 2.25)" +Query primary domain name server only. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.B RES_IGNTC +Ignore truncation errors. +Don't retry with TCP. +.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\[em]that is, 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]. +.TP +.B RES_INSECURE1 +Accept a response from a wrong server. +This can be used to detect potential security hazards, +but you need to compile glibc with debugging enabled and use +.B RES_DEBUG +option (for debug purpose only). +.TP +.B RES_INSECURE2 +Accept a response which contains a wrong query. +This can be used to detect potential security hazards, +but you need to compile glibc with debugging enabled and use +.B RES_DEBUG +option (for debug purpose only). +.TP +.B RES_NOALIASES +Disable usage of +.B HOSTALIASES +environment variable. +.TP +.B RES_USE_INET6 +Try an AAAA query before an A query inside the +.BR gethostbyname (3) +function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records +are found but an A record set exists. +Since glibc 2.25, this option is deprecated, +and its usage produces a warning; +applications should use +.BR getaddrinfo (3), +rather than +.BR gethostbyname (3). +.TP +.B RES_ROTATE +Causes round-robin selection of name servers from among those listed. +This has the effect of spreading the query load among all listed servers, +rather than having all clients try the first listed server first every +time. +.TP +.BR RES_NOCHECKNAME " (unimplemented; deprecated in glibc 2.25)" +Disable the modern BIND checking of incoming hostnames and mail names +for invalid characters such as underscore (_), non-ASCII, +or control characters. +This option was present until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_KEEPTSIG " (unimplemented; deprecated in glibc 2.25)" +Do not strip TSIG records. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_BLAST " (unimplemented; deprecated in glibc 2.25)" +Send each query simultaneously and recursively to all servers. +This option was present but unimplemented until glibc 2.24; +since glibc 2.25, it is deprecated, and its usage produces a warning. +.TP +.BR RES_USEBSTRING " (glibc 2.3.4 to glibc 2.24)" +Make reverse IPv6 lookups using the bit-label format described in RFC 2673; +if this option is not set (which is the default), then nibble format is used. +This option was removed in glibc 2.25, +since it relied on a backward-incompatible +DNS extension that was never deployed on the Internet. +.TP +.BR RES_NOIP6DOTINT " (glibc 2.24 and earlier)" +Use +.I ip6.arpa +zone in IPv6 reverse lookup instead of +.IR ip6.int , +which is deprecated since glibc 2.3.4. +This option is present up to and including glibc 2.24, +where it is enabled by default. +In glibc 2.25, this option was removed. +.TP +.BR RES_USE_EDNS0 " (since glibc 2.6)" +Enables support for the DNS extensions (EDNS0) described in RFC 2671. +.TP +.BR RES_SNGLKUP " (since glibc 2.10)" +By default, glibc performs IPv4 and IPv6 lookups in parallel +since glibc 2.9. +Some appliance DNS servers cannot handle these queries properly +and make the requests time out. +This option disables the behavior and makes glibc +perform the IPv6 and IPv4 requests sequentially +(at the cost of some slowdown of the resolving process). +.TP +.B RES_SNGLKUPREOP +When +.B RES_SNGLKUP +option is enabled, opens a new socket for the each request. +.TP +.B RES_USE_DNSSEC +Use DNSSEC with OK bit in OPT record. +This option implies +.BR RES_USE_EDNS0 . +.TP +.B RES_NOTLDQUERY +Do not look up unqualified name as a top-level domain (TLD). +.TP +.B RES_DEFAULT +Default option which implies: +.BR RES_RECURSE , +.BR RES_DEFNAMES , +.BR RES_DNSRCH , +and +.BR RES_NOIP6DOTINT . +.\" +.SH RETURN VALUE +The +.BR res_ninit () +and +.BR res_init () +functions return 0 on success, or \-1 if an error +occurs. +.P +The +.BR res_nquery (), +.BR res_query (), +.BR res_nsearch (), +.BR res_search (), +.BR res_nquerydomain (), +.BR res_querydomain (), +.BR res_nmkquery (), +.BR res_mkquery (), +.BR res_nsend (), +and +.BR res_send () +functions return the length +of the response, or \-1 if an error occurs. +.P +The +.BR dn_comp () +and +.BR dn_expand () +functions return the length +of the compressed name, or \-1 if an error occurs. +.P +In the case of an error return from +.BR res_nquery (), +.BR res_query (), +.BR res_nsearch (), +.BR res_search (), +.BR res_nquerydomain (), +or +.BR res_querydomain (), +the global variable +.I h_errno +(see +.BR gethostbyname (3)) +can be consulted to determine the cause of the error. +.SH FILES +.TP +.I /etc/resolv.conf +resolver configuration file +.TP +.I /etc/host.conf +resolver configuration file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR res_ninit (), +.BR res_nclose (), +.BR res_nquery (), +.BR res_nsearch (), +.BR res_nquerydomain (), +.BR res_nsend () +T} Thread safety MT-Safe locale +T{ +.na +.nh +.BR res_nmkquery (), +.BR dn_comp (), +.BR dn_expand () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +None. +.SH HISTORY +4.3BSD. +.SH SEE ALSO +.BR gethostbyname (3), +.BR resolv.conf (5), +.BR resolver (5), +.BR hostname (7), +.BR named (8) +.P +The GNU C library source file +.IR resolv/README . |