mirror of https://github.com/mkerrisk/man-pages
468 lines
13 KiB
Groff
468 lines
13 KiB
Groff
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
|
.\" and (C) Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" 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.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 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 2015-05-07 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend,
|
|
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 struct __res_state;
|
|
.B typedef struct __res_state *res_state;
|
|
|
|
.B int res_ninit(void);
|
|
|
|
.BI "int res_nquery(res_state " statep ,
|
|
.BI " const char *" dname ", int " class ", int " type ,
|
|
.BI " unsigned char *" answer ", int " anslen );
|
|
|
|
.BI "int res_nsearch(res_state " statep ,
|
|
.BI " const char *" dname ", int " class ", int " type ,
|
|
.BI " unsigned char *" answer ", int " anslen );
|
|
|
|
.BI "int res_nquerydomain(res_state " statep ,
|
|
.BI " const char *" name ", const char *" domain ,
|
|
.BI " int " class ", int " type ", unsigned char *" answer ,
|
|
.BI " int " anslen );
|
|
|
|
.BI "int res_nmkquery(res_state " statep ,
|
|
.BI " int " op ", const char *" dname ", int " class ,
|
|
.BI " int " type ", const unsigned char *" data ", int " datalen ,
|
|
.BI " const unsigned char *" newrr ,
|
|
.BI " unsigned char *" buf ", int " buflen );
|
|
|
|
.BI "int res_nsend(res_state " statep ,
|
|
.BI " const unsigned char *" msg ", int " msglen ,
|
|
.BI " unsigned char *" answer ", int " anslen );
|
|
|
|
.BI "int dn_comp(const char *" exp_dn ", unsigned char *" comp_dn ,
|
|
.BI " int " length ", unsigned char **" dnptrs ,
|
|
.BI " unsigned char **" lastdnptr );
|
|
|
|
.BI "int dn_expand(const unsigned char *" msg ,
|
|
.BI " const unsigned char *" eomorig ,
|
|
.BI " const unsigned char *" comp_dn ", char *" exp_dn ,
|
|
.BI " int " length );
|
|
.fi
|
|
.\"
|
|
.SS Deprecated
|
|
.nf
|
|
.B extern struct __res_state _res;
|
|
|
|
.B int res_init(void);
|
|
|
|
.BI "int res_query(const char *" dname ", int " class ", int " type ,
|
|
.BI " unsigned char *" answer ", int " anslen );
|
|
|
|
.BI "int res_search(const char *" dname ", int " class ", int " type ,
|
|
.BI " unsigned char *" answer ", int " anslen );
|
|
|
|
.BI "int res_querydomain(const char *" name ", const char *" domain ,
|
|
.BI " int " class ", int " type ", unsigned char *" answer ,
|
|
.BI " int " anslen );
|
|
|
|
.BI "int res_mkquery(int " op ", const char *" dname ", int " class ,
|
|
.BI " int " type ", const unsigned char *" data ", int " datalen ,
|
|
.BI " const unsigned char *" newrr ,
|
|
.BI " unsigned char *" buf ", int " buflen );
|
|
|
|
.BI "int res_send(const unsigned char *" msg ", int " msglen ,
|
|
.BI " unsigned char *" answer ", int " anslen );
|
|
.fi
|
|
.sp
|
|
Link with \fI\-lresolv\fP.
|
|
.SH DESCRIPTION
|
|
.B Note:
|
|
This page is incomplete (various resolver functions provided by glibc
|
|
are not described) and likely out of date.
|
|
|
|
The functions described below make queries to and interpret
|
|
the responses from Internet domain name servers.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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).
|
|
|
|
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.
|
|
|
|
The following functions are lower-level routines used by
|
|
.BR res_query ()/ res_query ().
|
|
|
|
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 usually
|
|
.BR QUERY ,
|
|
but can be any of the types defined in
|
|
\fI<arpa/nameser.h>\fP.
|
|
\fInewrr\fP is currently unused.
|
|
|
|
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.
|
|
.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 configuration and state information
|
|
contained in a
|
|
.IR __res_state
|
|
structure (either passed as the
|
|
.IR 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
|
|
.IR 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
|
|
.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.
|
|
[Not currently implemented].
|
|
.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\(emthat 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 ()
|
|
function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records
|
|
are found but an A record set exists.
|
|
.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
|
|
.B RES_NOCHECKNAME
|
|
Disable the modern BIND checking of incoming hostnames and mail names
|
|
for invalid characters such as underscore (_), non-ASCII,
|
|
or control characters.
|
|
[Not currently implemented].
|
|
.TP
|
|
.B RES_KEEPTSIG
|
|
Do not strip TSIG records.
|
|
[Not currently implemented].
|
|
.TP
|
|
.B RES_BLAST
|
|
Send each query simultaneously and recursively to all servers.
|
|
Note this option overrides
|
|
.BR RES_ROTATE .
|
|
.TP
|
|
.BR RES_USEBSTRING " (since glibc 2.3.4)"
|
|
Make reverse IPv6 lookups using the bit-label format described in RFC 2673;
|
|
if this option is not set, then nibble format is used.
|
|
.TP
|
|
.B RES_NOIP6DOTINT
|
|
Use
|
|
.I ip6.arpa
|
|
zone in IPv6 reverse lookup instead of
|
|
.IR ip6.int ,
|
|
which is deprecated since glibc 2.3.4.
|
|
[Enabled by default].
|
|
.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
|
|
version 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.
|
|
.PP
|
|
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.
|
|
.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 ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.TS
|
|
allbox;
|
|
lbw34 lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR res_ninit (),
|
|
.BR res_nquery (),
|
|
.br
|
|
.BR res_nsearch (),
|
|
.BR res_nquerydomain (),
|
|
.BR res_nsend ()
|
|
T} Thread safety MT-Safe locale
|
|
T{
|
|
.BR res_nmkquery (),
|
|
.BR dn_comp (),
|
|
.br
|
|
.BR dn_expand ()
|
|
T} Thread safety MT-Safe
|
|
.TE
|
|
|
|
.SH CONFORMING TO
|
|
4.3BSD.
|
|
.SH SEE ALSO
|
|
.BR gethostbyname (3),
|
|
.BR resolv.conf (5),
|
|
.BR resolver (5),
|
|
.BR hostname (7),
|
|
.BR named (8)
|
|
|
|
The GNU C library source file
|
|
.IR resolv/README .
|