- import of strongswan-2.7.0
- applied patch for charon
This commit is contained in:
Martin Willi
@@ -0,0 +1,232 @@
|
||||
# Copyright (C) 2001 Internet Software Consortium.
|
||||
#
|
||||
# Permission to use, copy, modify, and distribute this software for any
|
||||
# purpose with or without fee is hereby granted, provided that the above
|
||||
# copyright notice and this permission notice appear in all copies.
|
||||
#
|
||||
# THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
# DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
# INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
# INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
# FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
# NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
# WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
|
||||
# $Id: Makefile.in,v 1.1 2004/03/15 20:35:25 as Exp $
|
||||
|
||||
srcdir = @srcdir@
|
||||
VPATH = @srcdir@
|
||||
top_srcdir = @top_srcdir@
|
||||
|
||||
@BIND9_VERSION@
|
||||
|
||||
@BIND9_MAKE_RULES@
|
||||
|
||||
# Alphabetically
|
||||
#MANPAGES = lwres.3 lwres_addr_parse.3 lwres_buffer.3 \
|
||||
# lwres_buffer_add.3 lwres_buffer_back.3 lwres_buffer_clear.3 \
|
||||
# lwres_buffer_first.3 lwres_buffer_forward.3 \
|
||||
# lwres_buffer_getmem.3 lwres_buffer_getuint16.3 \
|
||||
# lwres_buffer_getuint32.3 lwres_buffer_getuint8.3 \
|
||||
# lwres_buffer_init.3 lwres_buffer_invalidate.3 \
|
||||
# lwres_buffer_putmem.3 lwres_buffer_putuint16.3 \
|
||||
# lwres_buffer_putuint32.3 lwres_buffer_putuint8.3 \
|
||||
# lwres_buffer_subtract.3 lwres_conf_clear.3 \
|
||||
# lwres_conf_get.3 lwres_conf_init.3 \
|
||||
# lwres_conf_parse.3 lwres_conf_print.3 \
|
||||
# lwres_config.3 lwres_context.3 \
|
||||
# lwres_context_allocmem.3 lwres_context_create.3 \
|
||||
# lwres_context_destroy.3 lwres_context_freemem.3 \
|
||||
# lwres_context_initserial.3 lwres_context_nextserial.3 \
|
||||
# lwres_context_sendrecv.3 lwres_endhostent.3 \
|
||||
# lwres_endhostent_r.3 lwres_freeaddrinfo.3 \
|
||||
# lwres_freehostent.3 lwres_gabn.3 \
|
||||
# lwres_gabnrequest_free.3 lwres_gabnrequest_parse.3 \
|
||||
# lwres_gabnrequest_render.3 lwres_gabnresponse_free.3 \
|
||||
# lwres_gabnresponse_parse.3 lwres_gabnresponse_render.3 \
|
||||
# lwres_gai_strerror.3 lwres_getaddrinfo.3 \
|
||||
# lwres_getaddrsbyname.3 lwres_gethostbyaddr.3 \
|
||||
# lwres_gethostbyaddr_r.3 lwres_gethostbyname.3 \
|
||||
# lwres_gethostbyname2.3 lwres_gethostbyname_r.3 \
|
||||
# lwres_gethostent.3 lwres_gethostent_r.3 \
|
||||
# lwres_getipnode.3 lwres_getipnodebyaddr.3 \
|
||||
# lwres_getipnodebyname.3 lwres_getnamebyaddr.3 \
|
||||
# lwres_getnameinfo.3 lwres_getrrsetbyname.3 \
|
||||
# lwres_gnba.3 lwres_gnbarequest_free.3 \
|
||||
# lwres_gnbarequest_parse.3 lwres_gnbarequest_render.3 \
|
||||
# lwres_gnbaresponse_free.3 lwres_gnbaresponse_parse.3 \
|
||||
# lwres_gnbaresponse_render.3 lwres_herror.3 \
|
||||
# lwres_hstrerror.3 lwres_inetntop.3 \
|
||||
# lwres_lwpacket_parseheader.3 lwres_lwpacket_renderheader.3 \
|
||||
# lwres_net_ntop.3 lwres_noop.3 \
|
||||
# lwres_nooprequest_free.3 lwres_nooprequest_parse.3 \
|
||||
# lwres_nooprequest_render.3 lwres_noopresponse_free.3 \
|
||||
# lwres_noopresponse_parse.3 lwres_noopresponse_render.3 \
|
||||
# lwres_packet.3 lwres_resutil.3 \
|
||||
# lwres_sethostent.3 lwres_sethostent_r.3 \
|
||||
# lwres_string_parse.3
|
||||
|
||||
|
||||
MANPAGES = lwres.3 lwres_buffer.3 lwres_config.3 lwres_context.3 \
|
||||
lwres_gabn.3 lwres_gai_strerror.3 lwres_getaddrinfo.3 \
|
||||
lwres_gethostent.3 lwres_getipnode.3 lwres_getnameinfo.3 \
|
||||
lwres_getrrsetbyname.3 lwres_gnba.3 lwres_hstrerror.3 lwres_inetntop.3 \
|
||||
lwres_noop.3 lwres_packet.3 lwres_resutil.3
|
||||
|
||||
HTMLPAGES = lwres.html lwres_buffer.html lwres_config.html lwres_context.html \
|
||||
lwres_gabn.html lwres_gai_strerror.html lwres_getaddrinfo.html \
|
||||
lwres_gethostent.html lwres_getipnode.html lwres_getnameinfo.html \
|
||||
lwres_getrrsetbyname.html lwres_gnba.html lwres_hstrerror.html lwres_inetntop.html \
|
||||
lwres_noop.html lwres_packet.html lwres_resutil.html
|
||||
|
||||
MANOBJS = ${MANPAGES} ${HTMLPAGES}
|
||||
|
||||
doc man:: ${MANOBJS}
|
||||
|
||||
docclean manclean maintainer-clean::
|
||||
rm -f ${MANOBJS}
|
||||
|
||||
installdirs:
|
||||
$(SHELL) ${top_srcdir}/mkinstalldirs ${DESTDIR}${mandir}/man3
|
||||
|
||||
man3 = ${DESTDIR}${mandir}/man3
|
||||
|
||||
install:: installdirs
|
||||
for m in ${MANPAGES}; do ${INSTALL_DATA} ${srcdir}/$$m ${DESTDIR}${mandir}/man3; done
|
||||
rm -f ${man3}/lwres_addr_parse.3
|
||||
@LN@ ${man3}/lwres_resutil.3 ${man3}/lwres_addr_parse.3
|
||||
rm -f ${man3}/lwres_buffer_add.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_add.3
|
||||
rm -f ${man3}/lwres_buffer_back.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_back.3
|
||||
rm -f ${man3}/lwres_buffer_clear.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_clear.3
|
||||
rm -f ${man3}/lwres_buffer_first.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_first.3
|
||||
rm -f ${man3}/lwres_buffer_forward.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_forward.3
|
||||
rm -f ${man3}/lwres_buffer_getmem.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_getmem.3
|
||||
rm -f ${man3}/lwres_buffer_getuint16.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_getuint16.3
|
||||
rm -f ${man3}/lwres_buffer_getuint32.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_getuint32.3
|
||||
rm -f ${man3}/lwres_buffer_getuint8.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_getuint8.3
|
||||
rm -f ${man3}/lwres_buffer_init.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_init.3
|
||||
rm -f ${man3}/lwres_buffer_invalidate.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_invalidate.3
|
||||
rm -f ${man3}/lwres_buffer_putmem.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_putmem.3
|
||||
rm -f ${man3}/lwres_buffer_putuint16.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_putuint16.3
|
||||
rm -f ${man3}/lwres_buffer_putuint32.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_putuint32.3
|
||||
rm -f ${man3}/lwres_buffer_putuint8.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_putuint8.3
|
||||
rm -f ${man3}/lwres_buffer_subtract.3
|
||||
@LN@ ${man3}/lwres_buffer.3 ${man3}/lwres_buffer_subtract.3
|
||||
rm -f ${man3}/lwres_conf_clear.3
|
||||
@LN@ ${man3}/lwres_config.3 ${man3}/lwres_conf_clear.3
|
||||
rm -f ${man3}/lwres_conf_get.3
|
||||
@LN@ ${man3}/lwres_config.3 ${man3}/lwres_conf_get.3
|
||||
rm -f ${man3}/lwres_conf_init.3
|
||||
@LN@ ${man3}/lwres_config.3 ${man3}/lwres_conf_init.3
|
||||
rm -f ${man3}/lwres_conf_parse.3
|
||||
@LN@ ${man3}/lwres_config.3 ${man3}/lwres_conf_parse.3
|
||||
rm -f ${man3}/lwres_conf_print.3
|
||||
@LN@ ${man3}/lwres_config.3 ${man3}/lwres_conf_print.3
|
||||
rm -f ${man3}/lwres_context_allocmem.3
|
||||
@LN@ ${man3}/lwres_context.3 ${man3}/lwres_context_allocmem.3
|
||||
rm -f ${man3}/lwres_context_create.3
|
||||
@LN@ ${man3}/lwres_context.3 ${man3}/lwres_context_create.3
|
||||
rm -f ${man3}/lwres_context_destroy.3
|
||||
@LN@ ${man3}/lwres_context.3 ${man3}/lwres_context_destroy.3
|
||||
rm -f ${man3}/lwres_context_freemem.3
|
||||
@LN@ ${man3}/lwres_context.3 ${man3}/lwres_context_freemem.3
|
||||
rm -f ${man3}/lwres_context_initserial.3
|
||||
@LN@ ${man3}/lwres_context.3 ${man3}/lwres_context_initserial.3
|
||||
rm -f ${man3}/lwres_context_nextserial.3
|
||||
@LN@ ${man3}/lwres_context.3 ${man3}/lwres_context_nextserial.3
|
||||
rm -f ${man3}/lwres_context_sendrecv.3
|
||||
@LN@ ${man3}/lwres_context.3 ${man3}/lwres_context_sendrecv.3
|
||||
rm -f ${man3}/lwres_endhostent.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_endhostent.3
|
||||
rm -f ${man3}/lwres_endhostent_r.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_endhostent_r.3
|
||||
rm -f ${man3}/lwres_freeaddrinfo.3
|
||||
@LN@ ${man3}/lwres_getaddrinfo.3 ${man3}/lwres_freeaddrinfo.3
|
||||
rm -f ${man3}/lwres_freehostent.3
|
||||
@LN@ ${man3}/lwres_getipnode.3 ${man3}/lwres_freehostent.3
|
||||
rm -f ${man3}/lwres_gabnrequest_free.3
|
||||
@LN@ ${man3}/lwres_gabn.3 ${man3}/lwres_gabnrequest_free.3
|
||||
rm -f ${man3}/lwres_gabnrequest_parse.3
|
||||
@LN@ ${man3}/lwres_gabn.3 ${man3}/lwres_gabnrequest_parse.3
|
||||
rm -f ${man3}/lwres_gabnrequest_render.3
|
||||
@LN@ ${man3}/lwres_gabn.3 ${man3}/lwres_gabnrequest_render.3
|
||||
rm -f ${man3}/lwres_gabnresponse_free.3
|
||||
@LN@ ${man3}/lwres_gabn.3 ${man3}/lwres_gabnresponse_free.3
|
||||
rm -f ${man3}/lwres_gabnresponse_parse.3
|
||||
@LN@ ${man3}/lwres_gabn.3 ${man3}/lwres_gabnresponse_parse.3
|
||||
rm -f ${man3}/lwres_gabnresponse_render.3
|
||||
@LN@ ${man3}/lwres_gabn.3 ${man3}/lwres_gabnresponse_render.3
|
||||
rm -f ${man3}/lwres_getaddrsbyname.3
|
||||
@LN@ ${man3}/lwres_resutil.3 ${man3}/lwres_getaddrsbyname.3
|
||||
rm -f ${man3}/lwres_gethostbyaddr.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_gethostbyaddr.3
|
||||
rm -f ${man3}/lwres_gethostbyaddr_r.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_gethostbyaddr_r.3
|
||||
rm -f ${man3}/lwres_gethostbyname.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_gethostbyname.3
|
||||
rm -f ${man3}/lwres_gethostbyname2.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_gethostbyname2.3
|
||||
rm -f ${man3}/lwres_gethostbyname_r.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_gethostbyname_r.3
|
||||
rm -f ${man3}/lwres_gethostent_r.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_gethostent_r.3
|
||||
rm -f ${man3}/lwres_getipnodebyaddr.3
|
||||
@LN@ ${man3}/lwres_getipnode.3 ${man3}/lwres_getipnodebyaddr.3
|
||||
rm -f ${man3}/lwres_getipnodebyname.3
|
||||
@LN@ ${man3}/lwres_getipnode.3 ${man3}/lwres_getipnodebyname.3
|
||||
rm -f ${man3}/lwres_getnamebyaddr.3
|
||||
@LN@ ${man3}/lwres_resutil.3 ${man3}/lwres_getnamebyaddr.3
|
||||
rm -f ${man3}/lwres_gnbarequest_free.3
|
||||
@LN@ ${man3}/lwres_gnba.3 ${man3}/lwres_gnbarequest_free.3
|
||||
rm -f ${man3}/lwres_gnbarequest_parse.3
|
||||
@LN@ ${man3}/lwres_gnba.3 ${man3}/lwres_gnbarequest_parse.3
|
||||
rm -f ${man3}/lwres_gnbarequest_render.3
|
||||
@LN@ ${man3}/lwres_gnba.3 ${man3}/lwres_gnbarequest_render.3
|
||||
rm -f ${man3}/lwres_gnbaresponse_free.3
|
||||
@LN@ ${man3}/lwres_gnba.3 ${man3}/lwres_gnbaresponse_free.3
|
||||
rm -f ${man3}/lwres_gnbaresponse_parse.3
|
||||
@LN@ ${man3}/lwres_gnba.3 ${man3}/lwres_gnbaresponse_parse.3
|
||||
rm -f ${man3}/lwres_gnbaresponse_render.3
|
||||
@LN@ ${man3}/lwres_gnba.3 ${man3}/lwres_gnbaresponse_render.3
|
||||
rm -f ${man3}/lwres_herror.3
|
||||
@LN@ ${man3}/lwres_hstrerror.3 ${man3}/lwres_herror.3
|
||||
rm -f ${man3}/lwres_lwpacket_parseheader.3
|
||||
@LN@ ${man3}/lwres_packet.3 ${man3}/lwres_lwpacket_parseheader.3
|
||||
rm -f ${man3}/lwres_lwpacket_renderheader.3
|
||||
@LN@ ${man3}/lwres_packet.3 ${man3}/lwres_lwpacket_renderheader.3
|
||||
rm -f ${man3}/lwres_net_ntop.3
|
||||
@LN@ ${man3}/lwres_inetntop.3 ${man3}/lwres_net_ntop.3
|
||||
rm -f ${man3}/lwres_nooprequest_free.3
|
||||
@LN@ ${man3}/lwres_noop.3 ${man3}/lwres_nooprequest_free.3
|
||||
rm -f ${man3}/lwres_nooprequest_parse.3
|
||||
@LN@ ${man3}/lwres_noop.3 ${man3}/lwres_nooprequest_parse.3
|
||||
rm -f ${man3}/lwres_nooprequest_render.3
|
||||
@LN@ ${man3}/lwres_noop.3 ${man3}/lwres_nooprequest_render.3
|
||||
rm -f ${man3}/lwres_noopresponse_free.3
|
||||
@LN@ ${man3}/lwres_noop.3 ${man3}/lwres_noopresponse_free.3
|
||||
rm -f ${man3}/lwres_noopresponse_parse.3
|
||||
@LN@ ${man3}/lwres_noop.3 ${man3}/lwres_noopresponse_parse.3
|
||||
rm -f ${man3}/lwres_noopresponse_render.3
|
||||
@LN@ ${man3}/lwres_noop.3 ${man3}/lwres_noopresponse_render.3
|
||||
rm -f ${man3}/lwres_sethostent.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_sethostent.3
|
||||
rm -f ${man3}/lwres_sethostent_r.3
|
||||
@LN@ ${man3}/lwres_gethostent.3 ${man3}/lwres_sethostent_r.3
|
||||
rm -f ${man3}/lwres_string_parse.3
|
||||
@LN@ ${man3}/lwres_resutil.3 ${man3}/lwres_string_parse.3
|
||||
@@ -0,0 +1,158 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres \- introduction to the lightweight resolver library
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/lwres.h>\fR
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
The BIND 9 lightweight resolver library is a simple, name service
|
||||
independent stub resolver library. It provides hostname-to-address
|
||||
and address-to-hostname lookup services to applications by
|
||||
transmitting lookup requests to a resolver daemon
|
||||
\fBlwresd\fR
|
||||
running on the local host. The resover daemon performs the
|
||||
lookup using the DNS or possibly other name service protocols,
|
||||
and returns the results to the application through the library.
|
||||
The library and resolver daemon communicate using a simple
|
||||
UDP-based protocol.
|
||||
.SH "OVERVIEW"
|
||||
.PP
|
||||
The lwresd library implements multiple name service APIs.
|
||||
The standard
|
||||
\fBgethostbyname()\fR,
|
||||
\fBgethostbyaddr()\fR,
|
||||
\fBgethostbyname_r()\fR,
|
||||
\fBgethostbyaddr_r()\fR,
|
||||
\fBgetaddrinfo()\fR,
|
||||
\fBgetipnodebyname()\fR,
|
||||
and
|
||||
\fBgetipnodebyaddr()\fR
|
||||
functions are all supported. To allow the lwres library to coexist
|
||||
with system libraries that define functions of the same name,
|
||||
the library defines these functions with names prefixed by
|
||||
lwres_.
|
||||
To define the standard names, applications must include the
|
||||
header file
|
||||
\fI<lwres/netdb.h>\fR
|
||||
which contains macro definitions mapping the standard function names
|
||||
into
|
||||
lwres_
|
||||
prefixed ones. Operating system vendors who integrate the lwres
|
||||
library into their base distributions should rename the functions
|
||||
in the library proper so that the renaming macros are not needed.
|
||||
.PP
|
||||
The library also provides a native API consisting of the functions
|
||||
\fBlwres_getaddrsbyname()\fR
|
||||
and
|
||||
\fBlwres_getnamebyaddr()\fR.
|
||||
These may be called by applications that require more detailed
|
||||
control over the lookup process than the standard functions
|
||||
provide.
|
||||
.PP
|
||||
In addition to these name service independent address lookup
|
||||
functions, the library implements a new, experimental API
|
||||
for looking up arbitrary DNS resource records, using the
|
||||
\fBlwres_getaddrsbyname()\fR
|
||||
function.
|
||||
.PP
|
||||
Finally, there is a low-level API for converting lookup
|
||||
requests and responses to and from raw lwres protocol packets.
|
||||
This API can be used by clients requiring nonblocking operation,
|
||||
and is also used when implementing the server side of the lwres
|
||||
protocol, for example in the
|
||||
\fBlwresd\fR
|
||||
resolver daemon. The use of this low-level API in clients
|
||||
and servers is outlined in the following sections.
|
||||
.SH "CLIENT-SIDE LOW-LEVEL API CALL FLOW"
|
||||
.PP
|
||||
When a client program wishes to make an lwres request using the
|
||||
native low-level API, it typically performs the following
|
||||
sequence of actions.
|
||||
.PP
|
||||
(1) Allocate or use an existing \fBlwres_packet_t\fR,
|
||||
called pkt below.
|
||||
.PP
|
||||
(2) Set \fBpkt.recvlength\fR to the maximum length we will accept.
|
||||
This is done so the receiver of our packets knows how large our receive
|
||||
buffer is. The "default" is a constant in
|
||||
\fIlwres.h\fR: LWRES_RECVLENGTH = 4096.
|
||||
.PP
|
||||
(3) Set \fBpkt.serial\fR
|
||||
to a unique serial number. This value is echoed
|
||||
back to the application by the remote server.
|
||||
.PP
|
||||
(4) Set \fBpkt.pktflags\fR. Usually this is set to 0.
|
||||
.PP
|
||||
(5) Set \fBpkt.result\fR to 0.
|
||||
.PP
|
||||
(6) Call \fBlwres_*request_render()\fR,
|
||||
or marshall in the data using the primitives
|
||||
such as \fBlwres_packet_render()\fR
|
||||
and storing the packet data.
|
||||
.PP
|
||||
(7) Transmit the resulting buffer.
|
||||
.PP
|
||||
(8) Call \fBlwres_*response_parse()\fR
|
||||
to parse any packets received.
|
||||
.PP
|
||||
(9) Verify that the opcode and serial match a request, and process the
|
||||
packet specific information contained in the body.
|
||||
.SH "SERVER-SIDE LOW-LEVEL API CALL FLOW"
|
||||
.PP
|
||||
When implementing the server side of the lightweight resolver
|
||||
protocol using the lwres library, a sequence of actions like the
|
||||
following is typically involved in processing each request packet.
|
||||
.PP
|
||||
Note that the same \fBlwres_packet_t\fR is used
|
||||
in both the \fB_parse()\fR and \fB_render()\fR calls,
|
||||
with only a few modifications made
|
||||
to the packet header's contents between uses. This method is recommended
|
||||
as it keeps the serial, opcode, and other fields correct.
|
||||
.PP
|
||||
(1) When a packet is received, call \fBlwres_*request_parse()\fR to
|
||||
unmarshall it. This returns a \fBlwres_packet_t\fR (also called pkt, below)
|
||||
as well as a data specific type, such as \fBlwres_gabnrequest_t\fR.
|
||||
.PP
|
||||
(2) Process the request in the data specific type.
|
||||
.PP
|
||||
(3) Set the \fBpkt.result\fR,
|
||||
\fBpkt.recvlength\fR as above. All other fields can
|
||||
be left untouched since they were filled in by the \fB*_parse()\fR call
|
||||
above. If using \fBlwres_*response_render()\fR,
|
||||
\fBpkt.pktflags\fR will be set up
|
||||
properly. Otherwise, the LWRES_LWPACKETFLAG_RESPONSE bit should be
|
||||
set.
|
||||
.PP
|
||||
(4) Call the data specific rendering function, such as
|
||||
\fBlwres_gabnresponse_render()\fR.
|
||||
.PP
|
||||
(5) Send the resulting packet to the client.
|
||||
.PP
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBlwres_gethostent\fR(3),
|
||||
\fBlwres_getipnode\fR(3),
|
||||
\fBlwres_getnameinfo\fR(3),
|
||||
\fBlwres_noop\fR(3),
|
||||
\fBlwres_gabn\fR(3),
|
||||
\fBlwres_gnba\fR(3),
|
||||
\fBlwres_context\fR(3),
|
||||
\fBlwres_config\fR(3),
|
||||
\fBresolver\fR(5),
|
||||
\fBlwresd\fR(8).
|
||||
@@ -0,0 +1,244 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
<refentryinfo>
|
||||
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
<refmeta>
|
||||
<refentrytitle>lwres</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>lwres</refname>
|
||||
<refpurpose>introduction to the lightweight resolver library</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
The BIND 9 lightweight resolver library is a simple, name service
|
||||
independent stub resolver library. It provides hostname-to-address
|
||||
and address-to-hostname lookup services to applications by
|
||||
transmitting lookup requests to a resolver daemon
|
||||
<command>lwresd</command>
|
||||
running on the local host. The resover daemon performs the
|
||||
lookup using the DNS or possibly other name service protocols,
|
||||
and returns the results to the application through the library.
|
||||
The library and resolver daemon communicate using a simple
|
||||
UDP-based protocol.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>OVERVIEW</title>
|
||||
<para>
|
||||
The lwresd library implements multiple name service APIs.
|
||||
The standard
|
||||
<function>gethostbyname()</function>,
|
||||
<function>gethostbyaddr()</function>,
|
||||
<function>gethostbyname_r()</function>,
|
||||
<function>gethostbyaddr_r()</function>,
|
||||
<function>getaddrinfo()</function>,
|
||||
<function>getipnodebyname()</function>,
|
||||
and
|
||||
<function>getipnodebyaddr()</function>
|
||||
functions are all supported. To allow the lwres library to coexist
|
||||
with system libraries that define functions of the same name,
|
||||
the library defines these functions with names prefixed by
|
||||
<literal>lwres_</literal>.
|
||||
To define the standard names, applications must include the
|
||||
header file
|
||||
<filename><lwres/netdb.h></filename>
|
||||
which contains macro definitions mapping the standard function names
|
||||
into
|
||||
<literal>lwres_</literal>
|
||||
prefixed ones. Operating system vendors who integrate the lwres
|
||||
library into their base distributions should rename the functions
|
||||
in the library proper so that the renaming macros are not needed.
|
||||
</para>
|
||||
<para>
|
||||
The library also provides a native API consisting of the functions
|
||||
<function>lwres_getaddrsbyname()</function>
|
||||
and
|
||||
<function>lwres_getnamebyaddr()</function>.
|
||||
These may be called by applications that require more detailed
|
||||
control over the lookup process than the standard functions
|
||||
provide.
|
||||
</para>
|
||||
<para>
|
||||
In addition to these name service independent address lookup
|
||||
functions, the library implements a new, experimental API
|
||||
for looking up arbitrary DNS resource records, using the
|
||||
<function>lwres_getaddrsbyname()</function>
|
||||
function.
|
||||
</para>
|
||||
<para>
|
||||
Finally, there is a low-level API for converting lookup
|
||||
requests and responses to and from raw lwres protocol packets.
|
||||
This API can be used by clients requiring nonblocking operation,
|
||||
and is also used when implementing the server side of the lwres
|
||||
protocol, for example in the
|
||||
<command>lwresd</command>
|
||||
resolver daemon. The use of this low-level API in clients
|
||||
and servers is outlined in the following sections.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title>
|
||||
<para>
|
||||
When a client program wishes to make an lwres request using the
|
||||
native low-level API, it typically performs the following
|
||||
sequence of actions.
|
||||
</para>
|
||||
<para>
|
||||
(1) Allocate or use an existing <type>lwres_packet_t</type>,
|
||||
called <varname>pkt</varname> below.
|
||||
</para>
|
||||
<para>
|
||||
(2) Set <structfield>pkt.recvlength</structfield> to the maximum length we will accept.
|
||||
This is done so the receiver of our packets knows how large our receive
|
||||
buffer is. The "default" is a constant in
|
||||
<filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>.
|
||||
</para>
|
||||
<para>
|
||||
(3) Set <structfield>pkt.serial</structfield>
|
||||
to a unique serial number. This value is echoed
|
||||
back to the application by the remote server.
|
||||
</para>
|
||||
<para>
|
||||
(4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to 0.
|
||||
</para>
|
||||
<para>
|
||||
(5) Set <structfield>pkt.result</structfield> to 0.
|
||||
</para>
|
||||
<para>
|
||||
(6) Call <function>lwres_*request_render()</function>,
|
||||
or marshall in the data using the primitives
|
||||
such as <function>lwres_packet_render()</function>
|
||||
and storing the packet data.
|
||||
</para>
|
||||
<para>
|
||||
(7) Transmit the resulting buffer.
|
||||
</para>
|
||||
<para>
|
||||
(8) Call <function>lwres_*response_parse()</function>
|
||||
to parse any packets received.
|
||||
</para>
|
||||
<para>
|
||||
(9) Verify that the opcode and serial match a request, and process the
|
||||
packet specific information contained in the body.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title>
|
||||
<para>
|
||||
When implementing the server side of the lightweight resolver
|
||||
protocol using the lwres library, a sequence of actions like the
|
||||
following is typically involved in processing each request packet.
|
||||
</para>
|
||||
<para>
|
||||
Note that the same <type>lwres_packet_t</type> is used
|
||||
in both the <function>_parse()</function> and <function>_render()</function> calls,
|
||||
with only a few modifications made
|
||||
to the packet header's contents between uses. This method is recommended
|
||||
as it keeps the serial, opcode, and other fields correct.
|
||||
</para>
|
||||
<para>
|
||||
(1) When a packet is received, call <function>lwres_*request_parse()</function> to
|
||||
unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below)
|
||||
as well as a data specific type, such as <type>lwres_gabnrequest_t</type>.
|
||||
</para>
|
||||
<para>
|
||||
(2) Process the request in the data specific type.
|
||||
</para>
|
||||
<para>
|
||||
(3) Set the <structfield>pkt.result</structfield>,
|
||||
<structfield>pkt.recvlength</structfield> as above. All other fields can
|
||||
be left untouched since they were filled in by the <function>*_parse()</function> call
|
||||
above. If using <function>lwres_*response_render()</function>,
|
||||
<structfield>pkt.pktflags</structfield> will be set up
|
||||
properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be
|
||||
set.
|
||||
</para>
|
||||
<para>
|
||||
(4) Call the data specific rendering function, such as
|
||||
<function>lwres_gabnresponse_render()</function>.
|
||||
</para>
|
||||
<para>
|
||||
(5) Send the resulting packet to the client.
|
||||
</para>
|
||||
<para>
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum>
|
||||
</citerefentry>.
|
||||
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,444 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres -- introduction to the lightweight resolver library</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN11"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN12"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/lwres.h></PRE
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN14"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
>The BIND 9 lightweight resolver library is a simple, name service
|
||||
independent stub resolver library. It provides hostname-to-address
|
||||
and address-to-hostname lookup services to applications by
|
||||
transmitting lookup requests to a resolver daemon
|
||||
<B
|
||||
CLASS="COMMAND"
|
||||
>lwresd</B
|
||||
>
|
||||
running on the local host. The resover daemon performs the
|
||||
lookup using the DNS or possibly other name service protocols,
|
||||
and returns the results to the application through the library.
|
||||
The library and resolver daemon communicate using a simple
|
||||
UDP-based protocol.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN18"
|
||||
></A
|
||||
><H2
|
||||
>OVERVIEW</H2
|
||||
><P
|
||||
>The lwresd library implements multiple name service APIs.
|
||||
The standard
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>gethostbyname()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>gethostbyaddr()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>gethostbyname_r()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>gethostbyaddr_r()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>getaddrinfo()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>getipnodebyname()</TT
|
||||
>,
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>getipnodebyaddr()</TT
|
||||
>
|
||||
functions are all supported. To allow the lwres library to coexist
|
||||
with system libraries that define functions of the same name,
|
||||
the library defines these functions with names prefixed by
|
||||
<TT
|
||||
CLASS="LITERAL"
|
||||
>lwres_</TT
|
||||
>.
|
||||
To define the standard names, applications must include the
|
||||
header file
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
><lwres/netdb.h></TT
|
||||
>
|
||||
which contains macro definitions mapping the standard function names
|
||||
into
|
||||
<TT
|
||||
CLASS="LITERAL"
|
||||
>lwres_</TT
|
||||
>
|
||||
prefixed ones. Operating system vendors who integrate the lwres
|
||||
library into their base distributions should rename the functions
|
||||
in the library proper so that the renaming macros are not needed.</P
|
||||
><P
|
||||
>The library also provides a native API consisting of the functions
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrsbyname()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getnamebyaddr()</TT
|
||||
>.
|
||||
These may be called by applications that require more detailed
|
||||
control over the lookup process than the standard functions
|
||||
provide.</P
|
||||
><P
|
||||
>In addition to these name service independent address lookup
|
||||
functions, the library implements a new, experimental API
|
||||
for looking up arbitrary DNS resource records, using the
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrsbyname()</TT
|
||||
>
|
||||
function.</P
|
||||
><P
|
||||
>Finally, there is a low-level API for converting lookup
|
||||
requests and responses to and from raw lwres protocol packets.
|
||||
This API can be used by clients requiring nonblocking operation,
|
||||
and is also used when implementing the server side of the lwres
|
||||
protocol, for example in the
|
||||
<B
|
||||
CLASS="COMMAND"
|
||||
>lwresd</B
|
||||
>
|
||||
resolver daemon. The use of this low-level API in clients
|
||||
and servers is outlined in the following sections.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN38"
|
||||
></A
|
||||
><H2
|
||||
>CLIENT-SIDE LOW-LEVEL API CALL FLOW</H2
|
||||
><P
|
||||
>When a client program wishes to make an lwres request using the
|
||||
native low-level API, it typically performs the following
|
||||
sequence of actions.</P
|
||||
><P
|
||||
>(1) Allocate or use an existing <SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_packet_t</SPAN
|
||||
>,
|
||||
called <TT
|
||||
CLASS="VARNAME"
|
||||
>pkt</TT
|
||||
> below.</P
|
||||
><P
|
||||
>(2) Set <TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>pkt.recvlength</I
|
||||
></TT
|
||||
> to the maximum length we will accept.
|
||||
This is done so the receiver of our packets knows how large our receive
|
||||
buffer is. The "default" is a constant in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
>lwres.h</TT
|
||||
>: <TT
|
||||
CLASS="CONSTANT"
|
||||
>LWRES_RECVLENGTH = 4096</TT
|
||||
>.</P
|
||||
><P
|
||||
>(3) Set <TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>pkt.serial</I
|
||||
></TT
|
||||
>
|
||||
to a unique serial number. This value is echoed
|
||||
back to the application by the remote server.</P
|
||||
><P
|
||||
>(4) Set <TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>pkt.pktflags</I
|
||||
></TT
|
||||
>. Usually this is set to 0.</P
|
||||
><P
|
||||
>(5) Set <TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>pkt.result</I
|
||||
></TT
|
||||
> to 0.</P
|
||||
><P
|
||||
>(6) Call <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_*request_render()</TT
|
||||
>,
|
||||
or marshall in the data using the primitives
|
||||
such as <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_packet_render()</TT
|
||||
>
|
||||
and storing the packet data.</P
|
||||
><P
|
||||
>(7) Transmit the resulting buffer.</P
|
||||
><P
|
||||
>(8) Call <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_*response_parse()</TT
|
||||
>
|
||||
to parse any packets received.</P
|
||||
><P
|
||||
>(9) Verify that the opcode and serial match a request, and process the
|
||||
packet specific information contained in the body.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN61"
|
||||
></A
|
||||
><H2
|
||||
>SERVER-SIDE LOW-LEVEL API CALL FLOW</H2
|
||||
><P
|
||||
>When implementing the server side of the lightweight resolver
|
||||
protocol using the lwres library, a sequence of actions like the
|
||||
following is typically involved in processing each request packet.</P
|
||||
><P
|
||||
>Note that the same <SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_packet_t</SPAN
|
||||
> is used
|
||||
in both the <TT
|
||||
CLASS="FUNCTION"
|
||||
>_parse()</TT
|
||||
> and <TT
|
||||
CLASS="FUNCTION"
|
||||
>_render()</TT
|
||||
> calls,
|
||||
with only a few modifications made
|
||||
to the packet header's contents between uses. This method is recommended
|
||||
as it keeps the serial, opcode, and other fields correct.</P
|
||||
><P
|
||||
>(1) When a packet is received, call <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_*request_parse()</TT
|
||||
> to
|
||||
unmarshall it. This returns a <SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_packet_t</SPAN
|
||||
> (also called <TT
|
||||
CLASS="VARNAME"
|
||||
>pkt</TT
|
||||
>, below)
|
||||
as well as a data specific type, such as <SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnrequest_t</SPAN
|
||||
>.</P
|
||||
><P
|
||||
>(2) Process the request in the data specific type.</P
|
||||
><P
|
||||
>(3) Set the <TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>pkt.result</I
|
||||
></TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>pkt.recvlength</I
|
||||
></TT
|
||||
> as above. All other fields can
|
||||
be left untouched since they were filled in by the <TT
|
||||
CLASS="FUNCTION"
|
||||
>*_parse()</TT
|
||||
> call
|
||||
above. If using <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_*response_render()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>pkt.pktflags</I
|
||||
></TT
|
||||
> will be set up
|
||||
properly. Otherwise, the <TT
|
||||
CLASS="CONSTANT"
|
||||
>LWRES_LWPACKETFLAG_RESPONSE</TT
|
||||
> bit should be
|
||||
set.</P
|
||||
><P
|
||||
>(4) Call the data specific rendering function, such as
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnresponse_render()</TT
|
||||
>.</P
|
||||
><P
|
||||
>(5) Send the resulting packet to the client.</P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN85"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_gethostent</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_getipnode</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_getnameinfo</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_noop</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_gabn</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_gnba</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_context</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_config</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>resolver</SPAN
|
||||
>(5)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwresd</SPAN
|
||||
>(8)</SPAN
|
||||
>. </P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,277 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_BUFFER" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_buffer_init, lwres_buffer_invalidate, lwres_buffer_add, lwres_buffer_subtract, lwres_buffer_clear, lwres_buffer_first, lwres_buffer_forward, lwres_buffer_back, lwres_buffer_getuint8, lwres_buffer_putuint8, lwres_buffer_getuint16, lwres_buffer_putuint16, lwres_buffer_getuint32, lwres_buffer_putuint32, lwres_buffer_putmem, lwres_buffer_getmem \- lightweight resolver buffer management
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/lwbuffer.h>
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_invalidate(lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_add(lwres_buffer_t *b, unsigned int n);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_clear(lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_first(lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_forward(lwres_buffer_t *b, unsigned int n);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_back(lwres_buffer_t *b, unsigned int n);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_uint8_t
|
||||
lwres_buffer_getuint8(lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_uint16_t
|
||||
lwres_buffer_getuint16(lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_uint32_t
|
||||
lwres_buffer_getuint32(lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, unsigned int length);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_buffer_getmem(lwres_buffer_t *b, unsigned char *base, unsigned int length);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
These functions provide bounds checked access to a region of memory
|
||||
where data is being read or written.
|
||||
They are based on, and similar to, the
|
||||
isc_buffer_
|
||||
functions in the ISC library.
|
||||
.PP
|
||||
A buffer is a region of memory, together with a set of related
|
||||
subregions.
|
||||
The \fBused region\fR and the
|
||||
\fBavailable\fR region are disjoint, and
|
||||
their union is the buffer's region.
|
||||
The used region extends from the beginning of the buffer region to the
|
||||
last used byte.
|
||||
The available region extends from one byte greater than the last used
|
||||
byte to the end of the buffer's region.
|
||||
The size of the used region can be changed using various
|
||||
buffer commands.
|
||||
Initially, the used region is empty.
|
||||
.PP
|
||||
The used region is further subdivided into two disjoint regions: the
|
||||
\fBconsumed region\fR and the \fBremaining region\fR.
|
||||
The union of these two regions is the used region.
|
||||
The consumed region extends from the beginning of the used region to
|
||||
the byte before the \fBcurrent\fR offset (if any).
|
||||
The \fBremaining\fR region the current pointer to the end of the used
|
||||
region.
|
||||
The size of the consumed region can be changed using various
|
||||
buffer commands.
|
||||
Initially, the consumed region is empty.
|
||||
.PP
|
||||
The \fBactive region\fR is an (optional) subregion of the remaining
|
||||
region.
|
||||
It extends from the current offset to an offset in the
|
||||
remaining region.
|
||||
Initially, the active region is empty.
|
||||
If the current offset advances beyond the chosen offset,
|
||||
the active region will also be empty.
|
||||
.PP
|
||||
.sp
|
||||
.nf
|
||||
|
||||
/------------entire length---------------\\\\
|
||||
/----- used region -----\\\\/-- available --\\\\
|
||||
+----------------------------------------+
|
||||
| consumed | remaining | |
|
||||
+----------------------------------------+
|
||||
a b c d e
|
||||
|
||||
a == base of buffer.
|
||||
b == current pointer. Can be anywhere between a and d.
|
||||
c == active pointer. Meaningful between b and d.
|
||||
d == used pointer.
|
||||
e == length of buffer.
|
||||
|
||||
a-e == entire length of buffer.
|
||||
a-d == used region.
|
||||
a-b == consumed region.
|
||||
b-d == remaining region.
|
||||
b-c == optional active region.
|
||||
.sp
|
||||
.fi
|
||||
.PP
|
||||
\fBlwres_buffer_init()\fR
|
||||
initializes the
|
||||
\fBlwres_buffer_t\fR
|
||||
\fI*b\fR
|
||||
and assocates it with the memory region of size
|
||||
\fIlength\fR
|
||||
bytes starting at location
|
||||
\fIbase.\fR
|
||||
.PP
|
||||
\fBlwres_buffer_invalidate()\fR
|
||||
marks the buffer
|
||||
\fI*b\fR
|
||||
as invalid. Invalidating a buffer after use is not required,
|
||||
but makes it possible to catch its possible accidental use.
|
||||
.PP
|
||||
The functions
|
||||
\fBlwres_buffer_add()\fR
|
||||
and
|
||||
\fBlwres_buffer_subtract()\fR
|
||||
respectively increase and decrease the used space in
|
||||
buffer
|
||||
\fI*b\fR
|
||||
by
|
||||
\fIn\fR
|
||||
bytes.
|
||||
\fBlwres_buffer_add()\fR
|
||||
checks for buffer overflow and
|
||||
\fBlwres_buffer_subtract()\fR
|
||||
checks for underflow.
|
||||
These functions do not allocate or deallocate memory.
|
||||
They just change the value of
|
||||
\fBused\fR.
|
||||
.PP
|
||||
A buffer is re-initialised by
|
||||
\fBlwres_buffer_clear()\fR.
|
||||
The function sets
|
||||
\fBused\fR ,
|
||||
\fBcurrent\fR
|
||||
and
|
||||
\fBactive\fR
|
||||
to zero.
|
||||
.PP
|
||||
\fBlwres_buffer_first\fR
|
||||
makes the consumed region of buffer
|
||||
\fI*p\fR
|
||||
empty by setting
|
||||
\fBcurrent\fR
|
||||
to zero (the start of the buffer).
|
||||
.PP
|
||||
\fBlwres_buffer_forward()\fR
|
||||
increases the consumed region of buffer
|
||||
\fI*b\fR
|
||||
by
|
||||
\fIn\fR
|
||||
bytes, checking for overflow.
|
||||
Similarly,
|
||||
\fBlwres_buffer_back()\fR
|
||||
decreases buffer
|
||||
\fIb\fR's
|
||||
consumed region by
|
||||
\fIn\fR
|
||||
bytes and checks for underflow.
|
||||
.PP
|
||||
\fBlwres_buffer_getuint8()\fR
|
||||
reads an unsigned 8-bit integer from
|
||||
\fI*b\fR
|
||||
and returns it.
|
||||
\fBlwres_buffer_putuint8()\fR
|
||||
writes the unsigned 8-bit integer
|
||||
\fIval\fR
|
||||
to buffer
|
||||
\fI*b\fR.
|
||||
.PP
|
||||
\fBlwres_buffer_getuint16()\fR
|
||||
and
|
||||
\fBlwres_buffer_getuint32()\fR
|
||||
are identical to
|
||||
\fBlwres_buffer_putuint8()\fR
|
||||
except that they respectively read an unsigned 16-bit or 32-bit integer
|
||||
in network byte order from
|
||||
\fIb\fR.
|
||||
Similarly,
|
||||
\fBlwres_buffer_putuint16()\fR
|
||||
and
|
||||
\fBlwres_buffer_putuint32()\fR
|
||||
writes the unsigned 16-bit or 32-bit integer
|
||||
\fIval\fR
|
||||
to buffer
|
||||
\fIb\fR,
|
||||
in network byte order.
|
||||
.PP
|
||||
Arbitrary amounts of data are read or written from a lightweight
|
||||
resolver buffer with
|
||||
\fBlwres_buffer_getmem()\fR
|
||||
and
|
||||
\fBlwres_buffer_putmem()\fR
|
||||
respectively.
|
||||
\fBlwres_buffer_putmem()\fR
|
||||
copies
|
||||
\fIlength\fR
|
||||
bytes of memory at
|
||||
\fIbase\fR
|
||||
to
|
||||
\fIb\fR.
|
||||
Conversely,
|
||||
\fBlwres_buffer_getmem()\fR
|
||||
copies
|
||||
\fIlength\fR
|
||||
bytes of memory from
|
||||
\fIb\fR
|
||||
to
|
||||
\fIbase\fR.
|
||||
@@ -0,0 +1,378 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_buffer.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_buffer</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_buffer_init</refname>
|
||||
<refname>lwres_buffer_invalidate</refname>
|
||||
<refname>lwres_buffer_add</refname>
|
||||
<refname>lwres_buffer_subtract</refname>
|
||||
<refname>lwres_buffer_clear</refname>
|
||||
<refname>lwres_buffer_first</refname>
|
||||
<refname>lwres_buffer_forward</refname>
|
||||
<refname>lwres_buffer_back</refname>
|
||||
<refname>lwres_buffer_getuint8</refname>
|
||||
<refname>lwres_buffer_putuint8</refname>
|
||||
<refname>lwres_buffer_getuint16</refname>
|
||||
<refname>lwres_buffer_putuint16</refname>
|
||||
<refname>lwres_buffer_getuint32</refname>
|
||||
<refname>lwres_buffer_putuint32</refname>
|
||||
<refname>lwres_buffer_putmem</refname>
|
||||
<refname>lwres_buffer_getmem</refname>
|
||||
<refpurpose>lightweight resolver buffer management</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <lwres/lwbuffer.h>
|
||||
</funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_init</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>void *base</paramdef>
|
||||
<paramdef>unsigned int length</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_invalidate</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_add</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned int n</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_subtract</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned int n</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_clear</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_first</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_forward</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned int n</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_back</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned int n</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_uint8_t
|
||||
<function>lwres_buffer_getuint8</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_putuint8</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_uint8_t val</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_uint16_t
|
||||
<function>lwres_buffer_getuint16</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_putuint16</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_uint16_t val</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_uint32_t
|
||||
<function>lwres_buffer_getuint32</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_putuint32</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_uint32_t val</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_putmem</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>const unsigned char *base</paramdef>
|
||||
<paramdef>unsigned int length</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_buffer_getmem</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>unsigned char *base</paramdef>
|
||||
<paramdef>unsigned int length</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
These functions provide bounds checked access to a region of memory
|
||||
where data is being read or written.
|
||||
They are based on, and similar to, the
|
||||
<literal>isc_buffer_</literal>
|
||||
functions in the ISC library.
|
||||
</para>
|
||||
<para>
|
||||
A buffer is a region of memory, together with a set of related
|
||||
subregions.
|
||||
The <emphasis>used region</emphasis> and the
|
||||
<emphasis>available</emphasis> region are disjoint, and
|
||||
their union is the buffer's region.
|
||||
The used region extends from the beginning of the buffer region to the
|
||||
last used byte.
|
||||
The available region extends from one byte greater than the last used
|
||||
byte to the end of the buffer's region.
|
||||
The size of the used region can be changed using various
|
||||
buffer commands.
|
||||
Initially, the used region is empty.
|
||||
</para>
|
||||
<para>
|
||||
The used region is further subdivided into two disjoint regions: the
|
||||
<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>.
|
||||
The union of these two regions is the used region.
|
||||
The consumed region extends from the beginning of the used region to
|
||||
the byte before the <emphasis>current</emphasis> offset (if any).
|
||||
The <emphasis>remaining</emphasis> region the current pointer to the end of the used
|
||||
region.
|
||||
The size of the consumed region can be changed using various
|
||||
buffer commands.
|
||||
Initially, the consumed region is empty.
|
||||
</para>
|
||||
<para>
|
||||
The <emphasis>active region</emphasis> is an (optional) subregion of the remaining
|
||||
region.
|
||||
It extends from the current offset to an offset in the
|
||||
remaining region.
|
||||
Initially, the active region is empty.
|
||||
If the current offset advances beyond the chosen offset,
|
||||
the active region will also be empty.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
|
||||
/------------entire length---------------\\
|
||||
/----- used region -----\\/-- available --\\
|
||||
+----------------------------------------+
|
||||
| consumed | remaining | |
|
||||
+----------------------------------------+
|
||||
a b c d e
|
||||
|
||||
a == base of buffer.
|
||||
b == current pointer. Can be anywhere between a and d.
|
||||
c == active pointer. Meaningful between b and d.
|
||||
d == used pointer.
|
||||
e == length of buffer.
|
||||
|
||||
a-e == entire length of buffer.
|
||||
a-d == used region.
|
||||
a-b == consumed region.
|
||||
b-d == remaining region.
|
||||
b-c == optional active region.
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_init()</function>
|
||||
initializes the
|
||||
<type>lwres_buffer_t</type>
|
||||
<parameter>*b</parameter>
|
||||
and assocates it with the memory region of size
|
||||
<parameter>length</parameter>
|
||||
bytes starting at location
|
||||
<parameter>base.</parameter>
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_invalidate()</function>
|
||||
marks the buffer
|
||||
<parameter>*b</parameter>
|
||||
as invalid. Invalidating a buffer after use is not required,
|
||||
but makes it possible to catch its possible accidental use.
|
||||
</para>
|
||||
<para>
|
||||
The functions
|
||||
<function>lwres_buffer_add()</function>
|
||||
and
|
||||
<function>lwres_buffer_subtract()</function>
|
||||
respectively increase and decrease the used space in
|
||||
buffer
|
||||
<parameter>*b</parameter>
|
||||
by
|
||||
<parameter>n</parameter>
|
||||
bytes.
|
||||
<function>lwres_buffer_add()</function>
|
||||
checks for buffer overflow and
|
||||
<function>lwres_buffer_subtract()</function>
|
||||
checks for underflow.
|
||||
These functions do not allocate or deallocate memory.
|
||||
They just change the value of
|
||||
<structfield>used</structfield>.
|
||||
</para>
|
||||
<para>
|
||||
A buffer is re-initialised by
|
||||
<function>lwres_buffer_clear()</function>.
|
||||
The function sets
|
||||
<structfield>used</structfield> ,
|
||||
<structfield>current</structfield>
|
||||
and
|
||||
<structfield>active</structfield>
|
||||
to zero.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_first</function>
|
||||
makes the consumed region of buffer
|
||||
<parameter>*p</parameter>
|
||||
empty by setting
|
||||
<structfield>current</structfield>
|
||||
to zero (the start of the buffer).
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_forward()</function>
|
||||
increases the consumed region of buffer
|
||||
<parameter>*b</parameter>
|
||||
by
|
||||
<parameter>n</parameter>
|
||||
bytes, checking for overflow.
|
||||
Similarly,
|
||||
<function>lwres_buffer_back()</function>
|
||||
decreases buffer
|
||||
<parameter>b</parameter>'s
|
||||
consumed region by
|
||||
<parameter>n</parameter>
|
||||
bytes and checks for underflow.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_getuint8()</function>
|
||||
reads an unsigned 8-bit integer from
|
||||
<parameter>*b</parameter>
|
||||
and returns it.
|
||||
<function>lwres_buffer_putuint8()</function>
|
||||
writes the unsigned 8-bit integer
|
||||
<parameter>val</parameter>
|
||||
to buffer
|
||||
<parameter>*b</parameter>.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_buffer_getuint16()</function>
|
||||
and
|
||||
<function>lwres_buffer_getuint32()</function>
|
||||
are identical to
|
||||
<function>lwres_buffer_putuint8()</function>
|
||||
except that they respectively read an unsigned 16-bit or 32-bit integer
|
||||
in network byte order from
|
||||
<parameter>b</parameter>.
|
||||
Similarly,
|
||||
<function>lwres_buffer_putuint16()</function>
|
||||
and
|
||||
<function>lwres_buffer_putuint32()</function>
|
||||
writes the unsigned 16-bit or 32-bit integer
|
||||
<parameter>val</parameter>
|
||||
to buffer
|
||||
<parameter>b</parameter>,
|
||||
in network byte order.
|
||||
</para>
|
||||
<para>
|
||||
Arbitrary amounts of data are read or written from a lightweight
|
||||
resolver buffer with
|
||||
<function>lwres_buffer_getmem()</function>
|
||||
and
|
||||
<function>lwres_buffer_putmem()</function>
|
||||
respectively.
|
||||
<function>lwres_buffer_putmem()</function>
|
||||
copies
|
||||
<parameter>length</parameter>
|
||||
bytes of memory at
|
||||
<parameter>base</parameter>
|
||||
to
|
||||
<parameter>b</parameter>.
|
||||
Conversely,
|
||||
<function>lwres_buffer_getmem()</function>
|
||||
copies
|
||||
<parameter>length</parameter>
|
||||
bytes of memory from
|
||||
<parameter>b</parameter>
|
||||
to
|
||||
<parameter>base</parameter>.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,608 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_buffer</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_buffer</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_buffer_init, lwres_buffer_invalidate, lwres_buffer_add, lwres_buffer_subtract, lwres_buffer_clear, lwres_buffer_first, lwres_buffer_forward, lwres_buffer_back, lwres_buffer_getuint8, lwres_buffer_putuint8, lwres_buffer_getuint16, lwres_buffer_putuint16, lwres_buffer_getuint32, lwres_buffer_putuint32, lwres_buffer_putmem, lwres_buffer_getmem -- lightweight resolver buffer management</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN26"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN27"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/lwbuffer.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_init</CODE
|
||||
>(lwres_buffer_t *b, void *base, unsigned int length);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_invalidate</CODE
|
||||
>(lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_add</CODE
|
||||
>(lwres_buffer_t *b, unsigned int n);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_subtract</CODE
|
||||
>(lwres_buffer_t *b, unsigned int n);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_clear</CODE
|
||||
>(lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_first</CODE
|
||||
>(lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_forward</CODE
|
||||
>(lwres_buffer_t *b, unsigned int n);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_back</CODE
|
||||
>(lwres_buffer_t *b, unsigned int n);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_uint8_t
|
||||
lwres_buffer_getuint8</CODE
|
||||
>(lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_putuint8</CODE
|
||||
>(lwres_buffer_t *b, lwres_uint8_t val);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_uint16_t
|
||||
lwres_buffer_getuint16</CODE
|
||||
>(lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_putuint16</CODE
|
||||
>(lwres_buffer_t *b, lwres_uint16_t val);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_uint32_t
|
||||
lwres_buffer_getuint32</CODE
|
||||
>(lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_putuint32</CODE
|
||||
>(lwres_buffer_t *b, lwres_uint32_t val);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_putmem</CODE
|
||||
>(lwres_buffer_t *b, const unsigned char *base, unsigned int length);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_buffer_getmem</CODE
|
||||
>(lwres_buffer_t *b, unsigned char *base, unsigned int length);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN106"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
>These functions provide bounds checked access to a region of memory
|
||||
where data is being read or written.
|
||||
They are based on, and similar to, the
|
||||
<TT
|
||||
CLASS="LITERAL"
|
||||
>isc_buffer_</TT
|
||||
>
|
||||
functions in the ISC library.</P
|
||||
><P
|
||||
>A buffer is a region of memory, together with a set of related
|
||||
subregions.
|
||||
The <I
|
||||
CLASS="EMPHASIS"
|
||||
>used region</I
|
||||
> and the
|
||||
<I
|
||||
CLASS="EMPHASIS"
|
||||
>available</I
|
||||
> region are disjoint, and
|
||||
their union is the buffer's region.
|
||||
The used region extends from the beginning of the buffer region to the
|
||||
last used byte.
|
||||
The available region extends from one byte greater than the last used
|
||||
byte to the end of the buffer's region.
|
||||
The size of the used region can be changed using various
|
||||
buffer commands.
|
||||
Initially, the used region is empty.</P
|
||||
><P
|
||||
>The used region is further subdivided into two disjoint regions: the
|
||||
<I
|
||||
CLASS="EMPHASIS"
|
||||
>consumed region</I
|
||||
> and the <I
|
||||
CLASS="EMPHASIS"
|
||||
>remaining region</I
|
||||
>.
|
||||
The union of these two regions is the used region.
|
||||
The consumed region extends from the beginning of the used region to
|
||||
the byte before the <I
|
||||
CLASS="EMPHASIS"
|
||||
>current</I
|
||||
> offset (if any).
|
||||
The <I
|
||||
CLASS="EMPHASIS"
|
||||
>remaining</I
|
||||
> region the current pointer to the end of the used
|
||||
region.
|
||||
The size of the consumed region can be changed using various
|
||||
buffer commands.
|
||||
Initially, the consumed region is empty.</P
|
||||
><P
|
||||
>The <I
|
||||
CLASS="EMPHASIS"
|
||||
>active region</I
|
||||
> is an (optional) subregion of the remaining
|
||||
region.
|
||||
It extends from the current offset to an offset in the
|
||||
remaining region.
|
||||
Initially, the active region is empty.
|
||||
If the current offset advances beyond the chosen offset,
|
||||
the active region will also be empty.</P
|
||||
><P
|
||||
><PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>
|
||||
/------------entire length---------------\\
|
||||
/----- used region -----\\/-- available --\\
|
||||
+----------------------------------------+
|
||||
| consumed | remaining | |
|
||||
+----------------------------------------+
|
||||
a b c d e
|
||||
|
||||
a == base of buffer.
|
||||
b == current pointer. Can be anywhere between a and d.
|
||||
c == active pointer. Meaningful between b and d.
|
||||
d == used pointer.
|
||||
e == length of buffer.
|
||||
|
||||
a-e == entire length of buffer.
|
||||
a-d == used region.
|
||||
a-b == consumed region.
|
||||
b-d == remaining region.
|
||||
b-c == optional active region.</PRE
|
||||
></P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_init()</TT
|
||||
>
|
||||
initializes the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_buffer_t</SPAN
|
||||
>
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*b</I
|
||||
></TT
|
||||
>
|
||||
and assocates it with the memory region of size
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>length</I
|
||||
></TT
|
||||
>
|
||||
bytes starting at location
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>base.</I
|
||||
></TT
|
||||
></P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_invalidate()</TT
|
||||
>
|
||||
marks the buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*b</I
|
||||
></TT
|
||||
>
|
||||
as invalid. Invalidating a buffer after use is not required,
|
||||
but makes it possible to catch its possible accidental use.</P
|
||||
><P
|
||||
>The functions
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_add()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_subtract()</TT
|
||||
>
|
||||
respectively increase and decrease the used space in
|
||||
buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*b</I
|
||||
></TT
|
||||
>
|
||||
by
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>n</I
|
||||
></TT
|
||||
>
|
||||
bytes.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_add()</TT
|
||||
>
|
||||
checks for buffer overflow and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_subtract()</TT
|
||||
>
|
||||
checks for underflow.
|
||||
These functions do not allocate or deallocate memory.
|
||||
They just change the value of
|
||||
<TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>used</I
|
||||
></TT
|
||||
>.</P
|
||||
><P
|
||||
>A buffer is re-initialised by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_clear()</TT
|
||||
>.
|
||||
The function sets
|
||||
<TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>used</I
|
||||
></TT
|
||||
> ,
|
||||
<TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>current</I
|
||||
></TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>active</I
|
||||
></TT
|
||||
>
|
||||
to zero.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_first</TT
|
||||
>
|
||||
makes the consumed region of buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*p</I
|
||||
></TT
|
||||
>
|
||||
empty by setting
|
||||
<TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>current</I
|
||||
></TT
|
||||
>
|
||||
to zero (the start of the buffer).</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_forward()</TT
|
||||
>
|
||||
increases the consumed region of buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*b</I
|
||||
></TT
|
||||
>
|
||||
by
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>n</I
|
||||
></TT
|
||||
>
|
||||
bytes, checking for overflow.
|
||||
Similarly,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_back()</TT
|
||||
>
|
||||
decreases buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>'s
|
||||
consumed region by
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>n</I
|
||||
></TT
|
||||
>
|
||||
bytes and checks for underflow.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_getuint8()</TT
|
||||
>
|
||||
reads an unsigned 8-bit integer from
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*b</I
|
||||
></TT
|
||||
>
|
||||
and returns it.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_putuint8()</TT
|
||||
>
|
||||
writes the unsigned 8-bit integer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>val</I
|
||||
></TT
|
||||
>
|
||||
to buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*b</I
|
||||
></TT
|
||||
>.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_getuint16()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_getuint32()</TT
|
||||
>
|
||||
are identical to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_putuint8()</TT
|
||||
>
|
||||
except that they respectively read an unsigned 16-bit or 32-bit integer
|
||||
in network byte order from
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>.
|
||||
Similarly,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_putuint16()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_putuint32()</TT
|
||||
>
|
||||
writes the unsigned 16-bit or 32-bit integer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>val</I
|
||||
></TT
|
||||
>
|
||||
to buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>,
|
||||
in network byte order.</P
|
||||
><P
|
||||
>Arbitrary amounts of data are read or written from a lightweight
|
||||
resolver buffer with
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_getmem()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_putmem()</TT
|
||||
>
|
||||
respectively.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_putmem()</TT
|
||||
>
|
||||
copies
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>length</I
|
||||
></TT
|
||||
>
|
||||
bytes of memory at
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>base</I
|
||||
></TT
|
||||
>
|
||||
to
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>.
|
||||
Conversely,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_buffer_getmem()</TT
|
||||
>
|
||||
copies
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>length</I
|
||||
></TT
|
||||
>
|
||||
bytes of memory from
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>
|
||||
to
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>base</I
|
||||
></TT
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,105 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_CONFIG" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_conf_init, lwres_conf_clear, lwres_conf_parse, lwres_conf_print, lwres_conf_get \- lightweight resolver configuration
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/lwres.h>
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_conf_init(lwres_context_t *ctx);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_conf_clear(lwres_context_t *ctx);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_conf_parse(lwres_context_t *ctx, const char *filename);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_conf_print(lwres_context_t *ctx, FILE *fp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_conf_t *
|
||||
lwres_conf_get(lwres_context_t *ctx);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBlwres_conf_init()\fR
|
||||
creates an empty
|
||||
\fBlwres_conf_t\fR
|
||||
structure for lightweight resolver context
|
||||
\fIctx\fR.
|
||||
.PP
|
||||
\fBlwres_conf_clear()\fR
|
||||
frees up all the internal memory used by
|
||||
that
|
||||
\fBlwres_conf_t\fR
|
||||
structure in resolver context
|
||||
\fIctx\fR.
|
||||
.PP
|
||||
\fBlwres_conf_parse()\fR
|
||||
opens the file
|
||||
\fIfilename\fR
|
||||
and parses it to initialise the resolver context
|
||||
\fIctx\fR's
|
||||
\fBlwres_conf_t\fR
|
||||
structure.
|
||||
.PP
|
||||
\fBlwres_conf_print()\fR
|
||||
prints the
|
||||
\fBlwres_conf_t\fR
|
||||
structure for resolver context
|
||||
\fIctx\fR
|
||||
to the
|
||||
\fBFILE\fR
|
||||
\fIfp\fR.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
\fBlwres_conf_parse()\fR
|
||||
returns
|
||||
LWRES_R_SUCCESS
|
||||
if it successfully read and parsed
|
||||
\fIfilename\fR.
|
||||
It returns
|
||||
LWRES_R_FAILURE
|
||||
if
|
||||
\fIfilename\fR
|
||||
could not be opened or contained incorrect
|
||||
resolver statements.
|
||||
.PP
|
||||
\fBlwres_conf_print()\fR
|
||||
returns
|
||||
LWRES_R_SUCCESS
|
||||
unless an error occurred when converting the network addresses to a
|
||||
numeric host address string.
|
||||
If this happens, the function returns
|
||||
LWRES_R_FAILURE.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBstdio\fR(3),
|
||||
\fBresolver\fR(5).
|
||||
.SH "FILES"
|
||||
.PP
|
||||
\fI/etc/resolv.conf\fR
|
||||
@@ -0,0 +1,159 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_config.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
<refentryinfo>
|
||||
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_config</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_conf_init</refname>
|
||||
<refname>lwres_conf_clear</refname>
|
||||
<refname>lwres_conf_parse</refname>
|
||||
<refname>lwres_conf_print</refname>
|
||||
<refname>lwres_conf_get</refname>
|
||||
<refpurpose>lightweight resolver configuration</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_conf_init</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_conf_clear</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_conf_parse</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>const char *filename</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_conf_print</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>FILE *fp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_conf_t *
|
||||
<function>lwres_conf_get</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
<function>lwres_conf_init()</function>
|
||||
creates an empty
|
||||
<type>lwres_conf_t</type>
|
||||
structure for lightweight resolver context
|
||||
<parameter>ctx</parameter>.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_conf_clear()</function>
|
||||
frees up all the internal memory used by
|
||||
that
|
||||
<type>lwres_conf_t</type>
|
||||
structure in resolver context
|
||||
<parameter>ctx</parameter>.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_conf_parse()</function>
|
||||
opens the file
|
||||
<parameter>filename</parameter>
|
||||
and parses it to initialise the resolver context
|
||||
<parameter>ctx</parameter>'s
|
||||
<type>lwres_conf_t</type>
|
||||
structure.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_conf_print()</function>
|
||||
prints the
|
||||
<type>lwres_conf_t</type>
|
||||
structure for resolver context
|
||||
<parameter>ctx</parameter>
|
||||
to the
|
||||
<type>FILE</type>
|
||||
<parameter>fp</parameter>.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
<function>lwres_conf_parse()</function>
|
||||
returns
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>
|
||||
if it successfully read and parsed
|
||||
<parameter>filename</parameter>.
|
||||
It returns
|
||||
<errorcode>LWRES_R_FAILURE</errorcode>
|
||||
if
|
||||
<parameter>filename</parameter>
|
||||
could not be opened or contained incorrect
|
||||
resolver statements.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_conf_print()</function>
|
||||
returns
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>
|
||||
unless an error occurred when converting the network addresses to a
|
||||
numeric host address string.
|
||||
If this happens, the function returns
|
||||
<errorcode>LWRES_R_FAILURE</errorcode>.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>stdio</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
<citerefentry>
|
||||
<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum>
|
||||
</citerefentry>.
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>FILES</title>
|
||||
<para>
|
||||
<filename>/etc/resolv.conf</filename>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,295 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_config</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_config</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_conf_init, lwres_conf_clear, lwres_conf_parse, lwres_conf_print, lwres_conf_get -- lightweight resolver configuration</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN15"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN16"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/lwres.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_conf_init</CODE
|
||||
>(lwres_context_t *ctx);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_conf_clear</CODE
|
||||
>(lwres_context_t *ctx);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_conf_parse</CODE
|
||||
>(lwres_context_t *ctx, const char *filename);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_conf_print</CODE
|
||||
>(lwres_context_t *ctx, FILE *fp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_conf_t *
|
||||
lwres_conf_get</CODE
|
||||
>(lwres_context_t *ctx);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN40"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_conf_init()</TT
|
||||
>
|
||||
creates an empty
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_conf_t</SPAN
|
||||
>
|
||||
structure for lightweight resolver context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
>.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_conf_clear()</TT
|
||||
>
|
||||
frees up all the internal memory used by
|
||||
that
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_conf_t</SPAN
|
||||
>
|
||||
structure in resolver context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
>.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_conf_parse()</TT
|
||||
>
|
||||
opens the file
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>filename</I
|
||||
></TT
|
||||
>
|
||||
and parses it to initialise the resolver context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
>'s
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_conf_t</SPAN
|
||||
>
|
||||
structure.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_conf_print()</TT
|
||||
>
|
||||
prints the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_conf_t</SPAN
|
||||
>
|
||||
structure for resolver context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
>
|
||||
to the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>FILE</SPAN
|
||||
>
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>fp</I
|
||||
></TT
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN61"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_conf_parse()</TT
|
||||
>
|
||||
returns
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>
|
||||
if it successfully read and parsed
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>filename</I
|
||||
></TT
|
||||
>.
|
||||
It returns
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_FAILURE</SPAN
|
||||
>
|
||||
if
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>filename</I
|
||||
></TT
|
||||
>
|
||||
could not be opened or contained incorrect
|
||||
resolver statements.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_conf_print()</TT
|
||||
>
|
||||
returns
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>
|
||||
unless an error occurred when converting the network addresses to a
|
||||
numeric host address string.
|
||||
If this happens, the function returns
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_FAILURE</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN73"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>stdio</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>resolver</SPAN
|
||||
>(5)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN82"
|
||||
></A
|
||||
><H2
|
||||
>FILES</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FILENAME"
|
||||
>/etc/resolv.conf</TT
|
||||
></P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,194 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_CONTEXT" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv \- lightweight resolver context management
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/lwres.h>
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_context_create(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_context_destroy(lwres_context_t **contextp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t serial);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_uint32_t
|
||||
lwres_context_nextserial(lwres_context_t *ctx);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_context_freemem(lwres_context_t *ctx, void *mem, size_t len);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_context_allocmem(lwres_context_t *ctx, size_t len);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void *
|
||||
lwres_context_sendrecv(lwres_context_t *ctx, void *sendbase, int sendlen, void *recvbase, int recvlen, int *recvd_len);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBlwres_context_create()\fR
|
||||
creates a
|
||||
\fBlwres_context_t\fR
|
||||
structure for use in lightweight resolver operations.
|
||||
It holds a socket and other data needed for communicating
|
||||
with a resolver daemon.
|
||||
The new
|
||||
\fBlwres_context_t\fR
|
||||
is returned throught
|
||||
\fIcontextp\fR,
|
||||
a pointer to a
|
||||
\fBlwres_context_t\fR
|
||||
pointer. This
|
||||
\fBlwres_context_t\fR
|
||||
pointer must initially be NULL, and is modified
|
||||
to point to the newly created
|
||||
\fBlwres_context_t\fR.
|
||||
.PP
|
||||
When the lightweight resolver needs to perform dynamic memory
|
||||
allocation, it will call
|
||||
\fImalloc_function\fR
|
||||
to allocate memory and
|
||||
\fIfree_function\fR
|
||||
to free it. If
|
||||
\fImalloc_function\fR
|
||||
and
|
||||
\fIfree_function\fR
|
||||
are NULL, memory is allocated using
|
||||
\&.Xr malloc 3
|
||||
and
|
||||
\fBfree\fR(3).
|
||||
It is not permitted to have a NULL
|
||||
\fImalloc_function\fR
|
||||
and a non-NULL
|
||||
\fIfree_function\fR
|
||||
or vice versa.
|
||||
\fIarg\fR
|
||||
is passed as the first parameter to the memory
|
||||
allocation functions.
|
||||
If
|
||||
\fImalloc_function\fR
|
||||
and
|
||||
\fIfree_function\fR
|
||||
are NULL,
|
||||
\fIarg\fR
|
||||
is unused and should be passed as NULL.
|
||||
.PP
|
||||
Once memory for the structure has been allocated,
|
||||
it is initialized using
|
||||
\fBlwres_conf_init\fR(3)
|
||||
and returned via
|
||||
\fI*contextp\fR.
|
||||
.PP
|
||||
\fBlwres_context_destroy()\fR
|
||||
destroys a
|
||||
\fBlwres_context_t\fR,
|
||||
closing its socket.
|
||||
\fIcontextp\fR
|
||||
is a pointer to a pointer to the context that is to be destroyed.
|
||||
The pointer will be set to NULL when the context has been destroyed.
|
||||
.PP
|
||||
The context holds a serial number that is used to identify resolver
|
||||
request packets and associate responses with the corresponding requests.
|
||||
This serial number is controlled using
|
||||
\fBlwres_context_initserial()\fR
|
||||
and
|
||||
\fBlwres_context_nextserial()\fR.
|
||||
\fBlwres_context_initserial()\fR
|
||||
sets the serial number for context
|
||||
\fI*ctx\fR
|
||||
to
|
||||
\fIserial\fR.
|
||||
\fBlwres_context_nextserial()\fR
|
||||
increments the serial number and returns the previous value.
|
||||
.PP
|
||||
Memory for a lightweight resolver context is allocated and freed using
|
||||
\fBlwres_context_allocmem()\fR
|
||||
and
|
||||
\fBlwres_context_freemem()\fR.
|
||||
These use whatever allocations were defined when the context was
|
||||
created with
|
||||
\fBlwres_context_create()\fR.
|
||||
\fBlwres_context_allocmem()\fR
|
||||
allocates
|
||||
\fIlen\fR
|
||||
bytes of memory and if successful returns a pointer to the allocated
|
||||
storage.
|
||||
\fBlwres_context_freemem()\fR
|
||||
frees
|
||||
\fIlen\fR
|
||||
bytes of space starting at location
|
||||
\fImem\fR.
|
||||
.PP
|
||||
\fBlwres_context_sendrecv()\fR
|
||||
performs I/O for the context
|
||||
\fIctx\fR.
|
||||
Data are read and written from the context's socket.
|
||||
It writes data from
|
||||
\fIsendbase\fR
|
||||
\(em typically a lightweight resolver query packet \(em
|
||||
and waits for a reply which is copied to the receive buffer at
|
||||
\fIrecvbase\fR.
|
||||
The number of bytes that were written to this receive buffer is
|
||||
returned in
|
||||
\fI*recvd_len\fR.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
\fBlwres_context_create()\fR
|
||||
returns
|
||||
LWRES_R_NOMEMORY
|
||||
if memory for the
|
||||
\fBstruct lwres_context\fR
|
||||
could not be allocated,
|
||||
LWRES_R_SUCCESS
|
||||
otherwise.
|
||||
.PP
|
||||
Successful calls to the memory allocator
|
||||
\fBlwres_context_allocmem()\fR
|
||||
return a pointer to the start of the allocated space.
|
||||
It returns NULL if memory could not be allocated.
|
||||
.PP
|
||||
LWRES_R_SUCCESS
|
||||
is returned when
|
||||
\fBlwres_context_sendrecv()\fR
|
||||
completes successfully.
|
||||
LWRES_R_IOERROR
|
||||
is returned if an I/O error occurs and
|
||||
LWRES_R_TIMEOUT
|
||||
is returned if
|
||||
\fBlwres_context_sendrecv()\fR
|
||||
times out waiting for a response.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBlwres_conf_init\fR(3),
|
||||
\fBmalloc\fR(3),
|
||||
\fBfree\fR(3).
|
||||
@@ -0,0 +1,283 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_context.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
<refentryinfo>
|
||||
|
||||
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_context</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>lwres_context_create</refname>
|
||||
<refname>lwres_context_destroy</refname>
|
||||
<refname>lwres_context_nextserial</refname>
|
||||
<refname>lwres_context_initserial</refname>
|
||||
<refname>lwres_context_freemem</refname>
|
||||
<refname>lwres_context_allocmem</refname>
|
||||
<refname>lwres_context_sendrecv</refname>
|
||||
<refpurpose>lightweight resolver context management</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_context_create</function></funcdef>
|
||||
<paramdef>lwres_context_t **contextp</paramdef>
|
||||
<paramdef>void *arg</paramdef>
|
||||
<paramdef>lwres_malloc_t malloc_function</paramdef>
|
||||
<paramdef>lwres_free_t free_function</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_context_destroy</function></funcdef>
|
||||
<paramdef>lwres_context_t **contextp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_context_initserial</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_uint32_t serial</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_uint32_t
|
||||
<function>lwres_context_nextserial</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_context_freemem</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>void *mem</paramdef>
|
||||
<paramdef>size_t len</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_context_allocmem</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>size_t len</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void *
|
||||
<function>lwres_context_sendrecv</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>void *sendbase</paramdef>
|
||||
<paramdef>int sendlen</paramdef>
|
||||
<paramdef>void *recvbase</paramdef>
|
||||
<paramdef>int recvlen</paramdef>
|
||||
<paramdef>int *recvd_len</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
<function>lwres_context_create()</function>
|
||||
creates a
|
||||
<type>lwres_context_t</type>
|
||||
structure for use in lightweight resolver operations.
|
||||
It holds a socket and other data needed for communicating
|
||||
with a resolver daemon.
|
||||
The new
|
||||
<type>lwres_context_t</type>
|
||||
is returned throught
|
||||
<parameter>contextp</parameter>,
|
||||
|
||||
a pointer to a
|
||||
<type>lwres_context_t</type>
|
||||
pointer. This
|
||||
<type>lwres_context_t</type>
|
||||
pointer must initially be NULL, and is modified
|
||||
to point to the newly created
|
||||
<type>lwres_context_t</type>.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
When the lightweight resolver needs to perform dynamic memory
|
||||
allocation, it will call
|
||||
<parameter>malloc_function</parameter>
|
||||
to allocate memory and
|
||||
<parameter>free_function</parameter>
|
||||
|
||||
to free it. If
|
||||
<parameter>malloc_function</parameter>
|
||||
and
|
||||
<parameter>free_function</parameter>
|
||||
|
||||
are NULL, memory is allocated using
|
||||
.Xr malloc 3
|
||||
and
|
||||
<citerefentry>
|
||||
<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>.
|
||||
|
||||
It is not permitted to have a NULL
|
||||
<parameter>malloc_function</parameter>
|
||||
and a non-NULL
|
||||
<parameter>free_function</parameter>
|
||||
or vice versa.
|
||||
<parameter>arg</parameter>
|
||||
is passed as the first parameter to the memory
|
||||
allocation functions.
|
||||
If
|
||||
<parameter>malloc_function</parameter>
|
||||
and
|
||||
<parameter>free_function</parameter>
|
||||
are NULL,
|
||||
<parameter>arg</parameter>
|
||||
|
||||
is unused and should be passed as NULL.
|
||||
</para>
|
||||
<para>
|
||||
Once memory for the structure has been allocated,
|
||||
it is initialized using
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>
|
||||
|
||||
and returned via
|
||||
<parameter>*contextp</parameter>.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_context_destroy()</function>
|
||||
destroys a
|
||||
<type>lwres_context_t</type>,
|
||||
|
||||
closing its socket.
|
||||
<parameter>contextp</parameter>
|
||||
is a pointer to a pointer to the context that is to be destroyed.
|
||||
The pointer will be set to NULL when the context has been destroyed.
|
||||
</para>
|
||||
<para>
|
||||
The context holds a serial number that is used to identify resolver
|
||||
request packets and associate responses with the corresponding requests.
|
||||
This serial number is controlled using
|
||||
<function>lwres_context_initserial()</function>
|
||||
and
|
||||
<function>lwres_context_nextserial()</function>.
|
||||
<function>lwres_context_initserial()</function>
|
||||
sets the serial number for context
|
||||
<parameter>*ctx</parameter>
|
||||
to
|
||||
<parameter>serial</parameter>.
|
||||
|
||||
<function>lwres_context_nextserial()</function>
|
||||
increments the serial number and returns the previous value.
|
||||
</para>
|
||||
<para>
|
||||
Memory for a lightweight resolver context is allocated and freed using
|
||||
<function>lwres_context_allocmem()</function>
|
||||
and
|
||||
<function>lwres_context_freemem()</function>.
|
||||
These use whatever allocations were defined when the context was
|
||||
created with
|
||||
<function>lwres_context_create()</function>.
|
||||
<function>lwres_context_allocmem()</function>
|
||||
allocates
|
||||
<parameter>len</parameter>
|
||||
bytes of memory and if successful returns a pointer to the allocated
|
||||
storage.
|
||||
<function>lwres_context_freemem()</function>
|
||||
frees
|
||||
<parameter>len</parameter>
|
||||
bytes of space starting at location
|
||||
<parameter>mem</parameter>.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_context_sendrecv()</function>
|
||||
performs I/O for the context
|
||||
<parameter>ctx</parameter>.
|
||||
|
||||
Data are read and written from the context's socket.
|
||||
It writes data from
|
||||
<parameter>sendbase</parameter>
|
||||
— typically a lightweight resolver query packet —
|
||||
and waits for a reply which is copied to the receive buffer at
|
||||
<parameter>recvbase</parameter>.
|
||||
|
||||
The number of bytes that were written to this receive buffer is
|
||||
returned in
|
||||
<parameter>*recvd_len</parameter>.
|
||||
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
<function>lwres_context_create()</function>
|
||||
returns
|
||||
<errorcode>LWRES_R_NOMEMORY</errorcode>
|
||||
if memory for the
|
||||
<type>struct lwres_context</type>
|
||||
could not be allocated,
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>
|
||||
otherwise.
|
||||
</para>
|
||||
<para>
|
||||
Successful calls to the memory allocator
|
||||
<function>lwres_context_allocmem()</function>
|
||||
return a pointer to the start of the allocated space.
|
||||
It returns NULL if memory could not be allocated.
|
||||
</para>
|
||||
<para>
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>
|
||||
is returned when
|
||||
<function>lwres_context_sendrecv()</function>
|
||||
completes successfully.
|
||||
<errorcode>LWRES_R_IOERROR</errorcode>
|
||||
is returned if an I/O error occurs and
|
||||
<errorcode>LWRES_R_TIMEOUT</errorcode>
|
||||
is returned if
|
||||
<function>lwres_context_sendrecv()</function>
|
||||
times out waiting for a response.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>free</refentrytitle><manvolnum>3
|
||||
</manvolnum>
|
||||
</citerefentry>.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,519 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_context</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_context</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv -- lightweight resolver context management</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN17"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN18"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/lwres.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_context_create</CODE
|
||||
>(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_context_destroy</CODE
|
||||
>(lwres_context_t **contextp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_context_initserial</CODE
|
||||
>(lwres_context_t *ctx, lwres_uint32_t serial);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_uint32_t
|
||||
lwres_context_nextserial</CODE
|
||||
>(lwres_context_t *ctx);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_context_freemem</CODE
|
||||
>(lwres_context_t *ctx, void *mem, size_t len);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_context_allocmem</CODE
|
||||
>(lwres_context_t *ctx, size_t len);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void *
|
||||
lwres_context_sendrecv</CODE
|
||||
>(lwres_context_t *ctx, void *sendbase, int sendlen, void *recvbase, int recvlen, int *recvd_len);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN60"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_create()</TT
|
||||
>
|
||||
creates a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_context_t</SPAN
|
||||
>
|
||||
structure for use in lightweight resolver operations.
|
||||
It holds a socket and other data needed for communicating
|
||||
with a resolver daemon.
|
||||
The new
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_context_t</SPAN
|
||||
>
|
||||
is returned throught
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>contextp</I
|
||||
></TT
|
||||
>,
|
||||
|
||||
a pointer to a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_context_t</SPAN
|
||||
>
|
||||
pointer. This
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_context_t</SPAN
|
||||
>
|
||||
pointer must initially be NULL, and is modified
|
||||
to point to the newly created
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_context_t</SPAN
|
||||
>. </P
|
||||
><P
|
||||
>When the lightweight resolver needs to perform dynamic memory
|
||||
allocation, it will call
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>malloc_function</I
|
||||
></TT
|
||||
>
|
||||
to allocate memory and
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>free_function</I
|
||||
></TT
|
||||
>
|
||||
|
||||
to free it. If
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>malloc_function</I
|
||||
></TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>free_function</I
|
||||
></TT
|
||||
>
|
||||
|
||||
are NULL, memory is allocated using
|
||||
.Xr malloc 3
|
||||
and
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>free</SPAN
|
||||
>(3)</SPAN
|
||||
>.
|
||||
|
||||
It is not permitted to have a NULL
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>malloc_function</I
|
||||
></TT
|
||||
>
|
||||
and a non-NULL
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>free_function</I
|
||||
></TT
|
||||
>
|
||||
or vice versa.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>arg</I
|
||||
></TT
|
||||
>
|
||||
is passed as the first parameter to the memory
|
||||
allocation functions.
|
||||
If
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>malloc_function</I
|
||||
></TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>free_function</I
|
||||
></TT
|
||||
>
|
||||
are NULL,
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>arg</I
|
||||
></TT
|
||||
>
|
||||
|
||||
is unused and should be passed as NULL.</P
|
||||
><P
|
||||
>Once memory for the structure has been allocated,
|
||||
it is initialized using
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_conf_init</SPAN
|
||||
>(3)</SPAN
|
||||
>
|
||||
|
||||
and returned via
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*contextp</I
|
||||
></TT
|
||||
>. </P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_destroy()</TT
|
||||
>
|
||||
destroys a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_context_t</SPAN
|
||||
>,
|
||||
|
||||
closing its socket.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>contextp</I
|
||||
></TT
|
||||
>
|
||||
is a pointer to a pointer to the context that is to be destroyed.
|
||||
The pointer will be set to NULL when the context has been destroyed.</P
|
||||
><P
|
||||
>The context holds a serial number that is used to identify resolver
|
||||
request packets and associate responses with the corresponding requests.
|
||||
This serial number is controlled using
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_initserial()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_nextserial()</TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_initserial()</TT
|
||||
>
|
||||
sets the serial number for context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*ctx</I
|
||||
></TT
|
||||
>
|
||||
to
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>serial</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_nextserial()</TT
|
||||
>
|
||||
increments the serial number and returns the previous value.</P
|
||||
><P
|
||||
>Memory for a lightweight resolver context is allocated and freed using
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_allocmem()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_freemem()</TT
|
||||
>.
|
||||
These use whatever allocations were defined when the context was
|
||||
created with
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_create()</TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_allocmem()</TT
|
||||
>
|
||||
allocates
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>len</I
|
||||
></TT
|
||||
>
|
||||
bytes of memory and if successful returns a pointer to the allocated
|
||||
storage.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_freemem()</TT
|
||||
>
|
||||
frees
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>len</I
|
||||
></TT
|
||||
>
|
||||
bytes of space starting at location
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>mem</I
|
||||
></TT
|
||||
>. </P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_sendrecv()</TT
|
||||
>
|
||||
performs I/O for the context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
Data are read and written from the context's socket.
|
||||
It writes data from
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>sendbase</I
|
||||
></TT
|
||||
>
|
||||
— typically a lightweight resolver query packet —
|
||||
and waits for a reply which is copied to the receive buffer at
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>recvbase</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
The number of bytes that were written to this receive buffer is
|
||||
returned in
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*recvd_len</I
|
||||
></TT
|
||||
>. </P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN115"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_create()</TT
|
||||
>
|
||||
returns
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_NOMEMORY</SPAN
|
||||
>
|
||||
if memory for the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct lwres_context</SPAN
|
||||
>
|
||||
could not be allocated,
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>
|
||||
otherwise.</P
|
||||
><P
|
||||
>Successful calls to the memory allocator
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_allocmem()</TT
|
||||
>
|
||||
return a pointer to the start of the allocated space.
|
||||
It returns NULL if memory could not be allocated.</P
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>
|
||||
is returned when
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_sendrecv()</TT
|
||||
>
|
||||
completes successfully.
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_IOERROR</SPAN
|
||||
>
|
||||
is returned if an I/O error occurs and
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_TIMEOUT</SPAN
|
||||
>
|
||||
is returned if
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_context_sendrecv()</TT
|
||||
>
|
||||
times out waiting for a response.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN130"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_conf_init</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>malloc</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>free</SPAN
|
||||
>(3)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,193 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_GABN" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free \- lightweight resolver getaddrbyname message handling
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/lwres.h>
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
These are low-level routines for creating and parsing
|
||||
lightweight resolver name-to-address lookup request and
|
||||
response messages.
|
||||
.PP
|
||||
There are four main functions for the getaddrbyname opcode.
|
||||
One render function converts a getaddrbyname request structure \(em
|
||||
\fBlwres_gabnrequest_t\fR \(em
|
||||
to the lighweight resolver's canonical format.
|
||||
It is complemented by a parse function that converts a packet in this
|
||||
canonical format to a getaddrbyname request structure.
|
||||
Another render function converts the getaddrbyname response structure \(em
|
||||
\fBlwres_gabnresponse_t\fR \(em
|
||||
to the canonical format.
|
||||
This is complemented by a parse function which converts a packet in
|
||||
canonical format to a getaddrbyname response structure.
|
||||
.PP
|
||||
These structures are defined in
|
||||
\fI<lwres/lwres.h>\fR.
|
||||
They are shown below.
|
||||
.sp
|
||||
.nf
|
||||
#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
|
||||
|
||||
typedef struct lwres_addr lwres_addr_t;
|
||||
typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint32_t addrtypes;
|
||||
lwres_uint16_t namelen;
|
||||
char *name;
|
||||
} lwres_gabnrequest_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint16_t naliases;
|
||||
lwres_uint16_t naddrs;
|
||||
char *realname;
|
||||
char **aliases;
|
||||
lwres_uint16_t realnamelen;
|
||||
lwres_uint16_t *aliaslen;
|
||||
lwres_addrlist_t addrs;
|
||||
void *base;
|
||||
size_t baselen;
|
||||
} lwres_gabnresponse_t;
|
||||
.sp
|
||||
.fi
|
||||
.PP
|
||||
\fBlwres_gabnrequest_render()\fR
|
||||
uses resolver context
|
||||
\fIctx\fR
|
||||
to convert getaddrbyname request structure
|
||||
\fIreq\fR
|
||||
to canonical format.
|
||||
The packet header structure
|
||||
\fIpkt\fR
|
||||
is initialised and transferred to
|
||||
buffer
|
||||
\fIb\fR.
|
||||
The contents of
|
||||
\fI*req\fR
|
||||
are then appended to the buffer in canonical format.
|
||||
\fBlwres_gabnresponse_render()\fR
|
||||
performs the same task, except it converts a getaddrbyname response structure
|
||||
\fBlwres_gabnresponse_t\fR
|
||||
to the lightweight resolver's canonical format.
|
||||
.PP
|
||||
\fBlwres_gabnrequest_parse()\fR
|
||||
uses context
|
||||
\fIctx\fR
|
||||
to convert the contents of packet
|
||||
\fIpkt\fR
|
||||
to a
|
||||
\fBlwres_gabnrequest_t\fR
|
||||
structure.
|
||||
Buffer
|
||||
\fIb\fR
|
||||
provides space to be used for storing this structure.
|
||||
When the function succeeds, the resulting
|
||||
\fBlwres_gabnrequest_t\fR
|
||||
is made available through
|
||||
\fI*structp\fR.
|
||||
\fBlwres_gabnresponse_parse()\fR
|
||||
offers the same semantics as
|
||||
\fBlwres_gabnrequest_parse()\fR
|
||||
except it yields a
|
||||
\fBlwres_gabnresponse_t\fR
|
||||
structure.
|
||||
.PP
|
||||
\fBlwres_gabnresponse_free()\fR
|
||||
and
|
||||
\fBlwres_gabnrequest_free()\fR
|
||||
release the memory in resolver context
|
||||
\fIctx\fR
|
||||
that was allocated to the
|
||||
\fBlwres_gabnresponse_t\fR
|
||||
or
|
||||
\fBlwres_gabnrequest_t\fR
|
||||
structures referenced via
|
||||
\fIstructp\fR.
|
||||
Any memory associated with ancillary buffers and strings for those
|
||||
structures is also discarded.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
The getaddrbyname opcode functions
|
||||
\fBlwres_gabnrequest_render()\fR,
|
||||
\fBlwres_gabnresponse_render()\fR
|
||||
\fBlwres_gabnrequest_parse()\fR
|
||||
and
|
||||
\fBlwres_gabnresponse_parse()\fR
|
||||
all return
|
||||
LWRES_R_SUCCESS
|
||||
on success.
|
||||
They return
|
||||
LWRES_R_NOMEMORY
|
||||
if memory allocation fails.
|
||||
LWRES_R_UNEXPECTEDEND
|
||||
is returned if the available space in the buffer
|
||||
\fIb\fR
|
||||
is too small to accommodate the packet header or the
|
||||
\fBlwres_gabnrequest_t\fR
|
||||
and
|
||||
\fBlwres_gabnresponse_t\fR
|
||||
structures.
|
||||
\fBlwres_gabnrequest_parse()\fR
|
||||
and
|
||||
\fBlwres_gabnresponse_parse()\fR
|
||||
will return
|
||||
LWRES_R_UNEXPECTEDEND
|
||||
if the buffer is not empty after decoding the received packet.
|
||||
These functions will return
|
||||
LWRES_R_FAILURE
|
||||
if
|
||||
\fBpktflags\fR
|
||||
in the packet header structure
|
||||
\fBlwres_lwpacket_t\fR
|
||||
indicate that the packet is not a response to an earlier query.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBlwres_packet\fR(3)
|
||||
@@ -0,0 +1,255 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_gabn.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
<refentryinfo>
|
||||
|
||||
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_gabn</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>lwres_gabnrequest_render</refname>
|
||||
<refname>lwres_gabnresponse_render</refname>
|
||||
<refname>lwres_gabnrequest_parse</refname>
|
||||
<refname>lwres_gabnresponse_parse</refname>
|
||||
<refname>lwres_gabnresponse_free</refname>
|
||||
<refname>lwres_gabnrequest_free</refname>
|
||||
<refpurpose>lightweight resolver getaddrbyname message handling</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_gabnrequest_render</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_gabnrequest_t *req</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_gabnresponse_render</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_gabnresponse_t *req</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_gabnrequest_parse</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_gabnrequest_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_gabnresponse_parse</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_gabnresponse_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_gabnresponse_free</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_gabnresponse_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_gabnrequest_free</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_gabnrequest_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
These are low-level routines for creating and parsing
|
||||
lightweight resolver name-to-address lookup request and
|
||||
response messages.
|
||||
</para><para>
|
||||
There are four main functions for the getaddrbyname opcode.
|
||||
One render function converts a getaddrbyname request structure —
|
||||
<type>lwres_gabnrequest_t</type> —
|
||||
to the lighweight resolver's canonical format.
|
||||
It is complemented by a parse function that converts a packet in this
|
||||
canonical format to a getaddrbyname request structure.
|
||||
Another render function converts the getaddrbyname response structure —
|
||||
<type>lwres_gabnresponse_t</type> —
|
||||
to the canonical format.
|
||||
This is complemented by a parse function which converts a packet in
|
||||
canonical format to a getaddrbyname response structure.
|
||||
</para>
|
||||
<para>
|
||||
These structures are defined in
|
||||
<filename><lwres/lwres.h></filename>.
|
||||
They are shown below.
|
||||
<programlisting>
|
||||
#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
|
||||
|
||||
typedef struct lwres_addr lwres_addr_t;
|
||||
typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint32_t addrtypes;
|
||||
lwres_uint16_t namelen;
|
||||
char *name;
|
||||
} lwres_gabnrequest_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint16_t naliases;
|
||||
lwres_uint16_t naddrs;
|
||||
char *realname;
|
||||
char **aliases;
|
||||
lwres_uint16_t realnamelen;
|
||||
lwres_uint16_t *aliaslen;
|
||||
lwres_addrlist_t addrs;
|
||||
void *base;
|
||||
size_t baselen;
|
||||
} lwres_gabnresponse_t;
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_gabnrequest_render()</function>
|
||||
uses resolver context
|
||||
<parameter>ctx</parameter>
|
||||
to convert getaddrbyname request structure
|
||||
<parameter>req</parameter>
|
||||
to canonical format.
|
||||
The packet header structure
|
||||
<parameter>pkt</parameter>
|
||||
is initialised and transferred to
|
||||
buffer
|
||||
<parameter>b</parameter>.
|
||||
|
||||
The contents of
|
||||
<parameter>*req</parameter>
|
||||
are then appended to the buffer in canonical format.
|
||||
<function>lwres_gabnresponse_render()</function>
|
||||
performs the same task, except it converts a getaddrbyname response structure
|
||||
<type>lwres_gabnresponse_t</type>
|
||||
to the lightweight resolver's canonical format.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_gabnrequest_parse()</function>
|
||||
uses context
|
||||
<parameter>ctx</parameter>
|
||||
to convert the contents of packet
|
||||
<parameter>pkt</parameter>
|
||||
to a
|
||||
<type>lwres_gabnrequest_t</type>
|
||||
structure.
|
||||
Buffer
|
||||
<parameter>b</parameter>
|
||||
provides space to be used for storing this structure.
|
||||
When the function succeeds, the resulting
|
||||
<type>lwres_gabnrequest_t</type>
|
||||
is made available through
|
||||
<parameter>*structp</parameter>.
|
||||
|
||||
<function>lwres_gabnresponse_parse()</function>
|
||||
offers the same semantics as
|
||||
<function>lwres_gabnrequest_parse()</function>
|
||||
except it yields a
|
||||
<type>lwres_gabnresponse_t</type>
|
||||
structure.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_gabnresponse_free()</function>
|
||||
and
|
||||
<function>lwres_gabnrequest_free()</function>
|
||||
release the memory in resolver context
|
||||
<parameter>ctx</parameter>
|
||||
that was allocated to the
|
||||
<type>lwres_gabnresponse_t</type>
|
||||
or
|
||||
<type>lwres_gabnrequest_t</type>
|
||||
structures referenced via
|
||||
<parameter>structp</parameter>.
|
||||
|
||||
Any memory associated with ancillary buffers and strings for those
|
||||
structures is also discarded.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
The getaddrbyname opcode functions
|
||||
<function>lwres_gabnrequest_render()</function>,
|
||||
<function>lwres_gabnresponse_render()</function>
|
||||
<function>lwres_gabnrequest_parse()</function>
|
||||
and
|
||||
<function>lwres_gabnresponse_parse()</function>
|
||||
all return
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>
|
||||
on success.
|
||||
They return
|
||||
<errorcode>LWRES_R_NOMEMORY</errorcode>
|
||||
if memory allocation fails.
|
||||
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
|
||||
is returned if the available space in the buffer
|
||||
<parameter>b</parameter>
|
||||
is too small to accommodate the packet header or the
|
||||
<type>lwres_gabnrequest_t</type>
|
||||
and
|
||||
<type>lwres_gabnresponse_t</type>
|
||||
structures.
|
||||
<function>lwres_gabnrequest_parse()</function>
|
||||
and
|
||||
<function>lwres_gabnresponse_parse()</function>
|
||||
will return
|
||||
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
|
||||
if the buffer is not empty after decoding the received packet.
|
||||
These functions will return
|
||||
<errorcode>LWRES_R_FAILURE</errorcode>
|
||||
if
|
||||
<structfield>pktflags</structfield>
|
||||
in the packet header structure
|
||||
<type>lwres_lwpacket_t</type>
|
||||
indicate that the packet is not a response to an earlier query.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_packet</refentrytitle><manvolnum>3
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,442 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_gabn</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_gabn</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free -- lightweight resolver getaddrbyname message handling</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN16"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN17"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/lwres.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_gabnrequest_render</CODE
|
||||
>(lwres_context_t *ctx, lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_gabnresponse_render</CODE
|
||||
>(lwres_context_t *ctx, lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_gabnrequest_parse</CODE
|
||||
>(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_gabnresponse_parse</CODE
|
||||
>(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_gabnresponse_free</CODE
|
||||
>(lwres_context_t *ctx, lwres_gabnresponse_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_gabnrequest_free</CODE
|
||||
>(lwres_context_t *ctx, lwres_gabnrequest_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN57"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
>These are low-level routines for creating and parsing
|
||||
lightweight resolver name-to-address lookup request and
|
||||
response messages.</P
|
||||
><P
|
||||
>There are four main functions for the getaddrbyname opcode.
|
||||
One render function converts a getaddrbyname request structure —
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnrequest_t</SPAN
|
||||
> —
|
||||
to the lighweight resolver's canonical format.
|
||||
It is complemented by a parse function that converts a packet in this
|
||||
canonical format to a getaddrbyname request structure.
|
||||
Another render function converts the getaddrbyname response structure —
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnresponse_t</SPAN
|
||||
> —
|
||||
to the canonical format.
|
||||
This is complemented by a parse function which converts a packet in
|
||||
canonical format to a getaddrbyname response structure.</P
|
||||
><P
|
||||
>These structures are defined in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
><lwres/lwres.h></TT
|
||||
>.
|
||||
They are shown below.
|
||||
<PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
|
||||
|
||||
typedef struct lwres_addr lwres_addr_t;
|
||||
typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint32_t addrtypes;
|
||||
lwres_uint16_t namelen;
|
||||
char *name;
|
||||
} lwres_gabnrequest_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint16_t naliases;
|
||||
lwres_uint16_t naddrs;
|
||||
char *realname;
|
||||
char **aliases;
|
||||
lwres_uint16_t realnamelen;
|
||||
lwres_uint16_t *aliaslen;
|
||||
lwres_addrlist_t addrs;
|
||||
void *base;
|
||||
size_t baselen;
|
||||
} lwres_gabnresponse_t;</PRE
|
||||
></P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnrequest_render()</TT
|
||||
>
|
||||
uses resolver context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
>
|
||||
to convert getaddrbyname request structure
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>req</I
|
||||
></TT
|
||||
>
|
||||
to canonical format.
|
||||
The packet header structure
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>pkt</I
|
||||
></TT
|
||||
>
|
||||
is initialised and transferred to
|
||||
buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
The contents of
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*req</I
|
||||
></TT
|
||||
>
|
||||
are then appended to the buffer in canonical format.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnresponse_render()</TT
|
||||
>
|
||||
performs the same task, except it converts a getaddrbyname response structure
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnresponse_t</SPAN
|
||||
>
|
||||
to the lightweight resolver's canonical format.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnrequest_parse()</TT
|
||||
>
|
||||
uses context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
>
|
||||
to convert the contents of packet
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>pkt</I
|
||||
></TT
|
||||
>
|
||||
to a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnrequest_t</SPAN
|
||||
>
|
||||
structure.
|
||||
Buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>
|
||||
provides space to be used for storing this structure.
|
||||
When the function succeeds, the resulting
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnrequest_t</SPAN
|
||||
>
|
||||
is made available through
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*structp</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnresponse_parse()</TT
|
||||
>
|
||||
offers the same semantics as
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnrequest_parse()</TT
|
||||
>
|
||||
except it yields a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnresponse_t</SPAN
|
||||
>
|
||||
structure.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnresponse_free()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnrequest_free()</TT
|
||||
>
|
||||
release the memory in resolver context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
>
|
||||
that was allocated to the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnresponse_t</SPAN
|
||||
>
|
||||
or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnrequest_t</SPAN
|
||||
>
|
||||
structures referenced via
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>structp</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
Any memory associated with ancillary buffers and strings for those
|
||||
structures is also discarded.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN93"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
>The getaddrbyname opcode functions
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnrequest_render()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnresponse_render()</TT
|
||||
>
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnrequest_parse()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnresponse_parse()</TT
|
||||
>
|
||||
all return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>
|
||||
on success.
|
||||
They return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_NOMEMORY</SPAN
|
||||
>
|
||||
if memory allocation fails.
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_UNEXPECTEDEND</SPAN
|
||||
>
|
||||
is returned if the available space in the buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>
|
||||
is too small to accommodate the packet header or the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnrequest_t</SPAN
|
||||
>
|
||||
and
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gabnresponse_t</SPAN
|
||||
>
|
||||
structures.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnrequest_parse()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gabnresponse_parse()</TT
|
||||
>
|
||||
will return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_UNEXPECTEDEND</SPAN
|
||||
>
|
||||
if the buffer is not empty after decoding the received packet.
|
||||
These functions will return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_FAILURE</SPAN
|
||||
>
|
||||
if
|
||||
<TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>pktflags</I
|
||||
></TT
|
||||
>
|
||||
in the packet header structure
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_lwpacket_t</SPAN
|
||||
>
|
||||
indicate that the packet is not a response to an earlier query.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN112"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_packet</SPAN
|
||||
>(3)</SPAN
|
||||
></P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,86 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_GAI_STRERROR" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
gai_strerror \- print suitable error string
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/netdb.h>
|
||||
.sp
|
||||
.na
|
||||
char *
|
||||
gai_strerror(int ecode);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBlwres_gai_strerror()\fR
|
||||
returns an error message corresponding to an error code returned by
|
||||
\fBgetaddrinfo()\fR.
|
||||
The following error codes and their meaning are defined in
|
||||
\fIinclude/lwres/netdb.h\fR.
|
||||
.TP
|
||||
\fBEAI_ADDRFAMILY\fR
|
||||
address family for hostname not supported
|
||||
.TP
|
||||
\fBEAI_AGAIN\fR
|
||||
temporary failure in name resolution
|
||||
.TP
|
||||
\fBEAI_BADFLAGS\fR
|
||||
invalid value for
|
||||
ai_flags
|
||||
.TP
|
||||
\fBEAI_FAIL\fR
|
||||
non-recoverable failure in name resolution
|
||||
.TP
|
||||
\fBEAI_FAMILY\fR
|
||||
ai_family not supported
|
||||
.TP
|
||||
\fBEAI_MEMORY\fR
|
||||
memory allocation failure
|
||||
.TP
|
||||
\fBEAI_NODATA\fR
|
||||
no address associated with hostname
|
||||
.TP
|
||||
\fBEAI_NONAME\fR
|
||||
hostname or servname not provided, or not known
|
||||
.TP
|
||||
\fBEAI_SERVICE\fR
|
||||
servname not supported for ai_socktype
|
||||
.TP
|
||||
\fBEAI_SOCKTYPE\fR
|
||||
ai_socktype not supported
|
||||
.TP
|
||||
\fBEAI_SYSTEM\fR
|
||||
system error returned in errno
|
||||
.PP
|
||||
The message \fBinvalid error code\fR is returned if
|
||||
\fIecode\fR
|
||||
is out of range.
|
||||
.PP
|
||||
ai_flags,
|
||||
ai_family
|
||||
and
|
||||
ai_socktype
|
||||
are elements of the
|
||||
\fBstruct addrinfo\fR
|
||||
used by
|
||||
\fBlwres_getaddrinfo()\fR.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBstrerror\fR(3),
|
||||
\fBlwres_getaddrinfo\fR(3),
|
||||
\fBgetaddrinfo\fR(3),
|
||||
\fBRFC2133\fR.
|
||||
@@ -0,0 +1,161 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_gai_strerror.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
<refentryinfo>
|
||||
|
||||
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_gai_strerror</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>gai_strerror</refname>
|
||||
<refpurpose>print suitable error string</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
char *
|
||||
<function>gai_strerror</function></funcdef>
|
||||
<paramdef>int ecode</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
<function>lwres_gai_strerror()</function>
|
||||
returns an error message corresponding to an error code returned by
|
||||
<function>getaddrinfo()</function>.
|
||||
The following error codes and their meaning are defined in
|
||||
<filename>include/lwres/netdb.h</filename>.
|
||||
<variablelist>
|
||||
<varlistentry><term><errorcode>EAI_ADDRFAMILY</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
address family for hostname not supported
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_AGAIN</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
temporary failure in name resolution
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_BADFLAGS</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
invalid value for
|
||||
<constant>ai_flags</constant>
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_FAIL</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
non-recoverable failure in name resolution
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_FAMILY</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<constant>ai_family</constant> not supported
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_MEMORY</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
memory allocation failure
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_NODATA</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
no address associated with hostname
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_NONAME</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
hostname or servname not provided, or not known
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_SERVICE</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
servname not supported for <constant>ai_socktype</constant>
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_SOCKTYPE</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<constant>ai_socktype</constant> not supported
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>EAI_SYSTEM</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
system error returned in errno
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
</variablelist>
|
||||
The message <errorname>invalid error code</errorname> is returned if
|
||||
<parameter>ecode</parameter>
|
||||
is out of range.
|
||||
</para>
|
||||
<para>
|
||||
<constant>ai_flags</constant>,
|
||||
<constant>ai_family</constant>
|
||||
and
|
||||
<constant>ai_socktype</constant>
|
||||
are elements of the
|
||||
<type>struct addrinfo</type>
|
||||
used by
|
||||
<function>lwres_getaddrinfo()</function>.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>RFC2133</refentrytitle>
|
||||
</citerefentry>.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,294 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_gai_strerror</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_gai_strerror</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>gai_strerror -- print suitable error string</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN11"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN12"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/netdb.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>char *
|
||||
gai_strerror</CODE
|
||||
>(int ecode);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN18"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gai_strerror()</TT
|
||||
>
|
||||
returns an error message corresponding to an error code returned by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>getaddrinfo()</TT
|
||||
>.
|
||||
The following error codes and their meaning are defined in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
>include/lwres/netdb.h</TT
|
||||
>.
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_ADDRFAMILY</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>address family for hostname not supported</P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_AGAIN</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>temporary failure in name resolution</P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_BADFLAGS</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>invalid value for
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_flags</TT
|
||||
></P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_FAIL</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>non-recoverable failure in name resolution</P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_FAMILY</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_family</TT
|
||||
> not supported</P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_MEMORY</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>memory allocation failure</P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_NODATA</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>no address associated with hostname</P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_NONAME</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>hostname or servname not provided, or not known</P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_SERVICE</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>servname not supported for <TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_socktype</TT
|
||||
></P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_SOCKTYPE</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_socktype</TT
|
||||
> not supported</P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_SYSTEM</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>system error returned in errno</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
>
|
||||
The message <SPAN
|
||||
CLASS="ERRORNAME"
|
||||
>invalid error code</SPAN
|
||||
> is returned if
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ecode</I
|
||||
></TT
|
||||
>
|
||||
is out of range.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_flags</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_family</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_socktype</TT
|
||||
>
|
||||
are elements of the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct addrinfo</SPAN
|
||||
>
|
||||
used by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrinfo()</TT
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN92"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>strerror</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_getaddrinfo</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>getaddrinfo</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>RFC2133</SPAN
|
||||
></SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,247 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_GETADDRINFO" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_getaddrinfo, lwres_freeaddrinfo \- socket address structure to host and service name
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/netdb.h>
|
||||
.sp
|
||||
.na
|
||||
int
|
||||
lwres_getaddrinfo(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_freeaddrinfo(struct addrinfo *ai);
|
||||
.ad
|
||||
\fR.PP
|
||||
If the operating system does not provide a
|
||||
\fBstruct addrinfo\fR,
|
||||
the following structure is used:
|
||||
.sp
|
||||
.nf
|
||||
struct addrinfo {
|
||||
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
|
||||
int ai_family; /* PF_xxx */
|
||||
int ai_socktype; /* SOCK_xxx */
|
||||
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
|
||||
size_t ai_addrlen; /* length of ai_addr */
|
||||
char *ai_canonname; /* canonical name for hostname */
|
||||
struct sockaddr *ai_addr; /* binary address */
|
||||
struct addrinfo *ai_next; /* next structure in linked list */
|
||||
};
|
||||
.sp
|
||||
.fi
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBlwres_getaddrinfo()\fR
|
||||
is used to get a list of IP addresses and port numbers for host
|
||||
\fIhostname\fR
|
||||
and service
|
||||
\fIservname\fR.
|
||||
The function is the lightweight resolver's implementation of
|
||||
\fBgetaddrinfo()\fR
|
||||
as defined in RFC2133.
|
||||
\fIhostname\fR
|
||||
and
|
||||
\fIservname\fR
|
||||
are pointers to null-terminated
|
||||
strings or
|
||||
\fBNULL\fR.
|
||||
\fIhostname\fR
|
||||
is either a host name or a numeric host address string: a dotted decimal
|
||||
IPv4 address or an IPv6 address.
|
||||
\fIservname\fR
|
||||
is either a decimal port number or a service name as listed in
|
||||
\fI/etc/services\fR.
|
||||
.PP
|
||||
\fIhints\fR
|
||||
is an optional pointer to a
|
||||
\fBstruct addrinfo\fR.
|
||||
This structure can be used to provide hints concerning the type of socket
|
||||
that the caller supports or wishes to use.
|
||||
The caller can supply the following structure elements in
|
||||
\fI*hints\fR:
|
||||
.TP
|
||||
\fBai_family\fR
|
||||
The protocol family that should be used.
|
||||
When
|
||||
ai_family
|
||||
is set to
|
||||
\fBPF_UNSPEC\fR,
|
||||
it means the caller will accept any protocol family supported by the
|
||||
operating system.
|
||||
.TP
|
||||
\fBai_socktype\fR
|
||||
denotes the type of socket \(em
|
||||
\fBSOCK_STREAM\fR,
|
||||
\fBSOCK_DGRAM\fR
|
||||
or
|
||||
\fBSOCK_RAW\fR
|
||||
\(em that is wanted.
|
||||
When
|
||||
ai_socktype
|
||||
is zero the caller will accept any socket type.
|
||||
.TP
|
||||
\fBai_protocol\fR
|
||||
indicates which transport protocol is wanted: IPPROTO_UDP or
|
||||
IPPROTO_TCP.
|
||||
If
|
||||
ai_protocol
|
||||
is zero the caller will accept any protocol.
|
||||
.TP
|
||||
\fBai_flags\fR
|
||||
Flag bits.
|
||||
If the
|
||||
\fBAI_CANONNAME\fR
|
||||
bit is set, a successful call to
|
||||
\fBlwres_getaddrinfo()\fR
|
||||
will return a a null-terminated string containing the canonical name
|
||||
of the specified hostname in
|
||||
ai_canonname
|
||||
of the first
|
||||
\fBaddrinfo\fR
|
||||
structure returned.
|
||||
Setting the
|
||||
\fBAI_PASSIVE\fR
|
||||
bit indicates that the returned socket address structure is intended
|
||||
for used in a call to
|
||||
\fBbind\fR(2).
|
||||
In this case, if the hostname argument is a
|
||||
\fBNULL\fR
|
||||
pointer, then the IP address portion of the socket
|
||||
address structure will be set to
|
||||
\fBINADDR_ANY\fR
|
||||
for an IPv4 address or
|
||||
\fBIN6ADDR_ANY_INIT\fR
|
||||
for an IPv6 address.
|
||||
|
||||
When
|
||||
ai_flags
|
||||
does not set the
|
||||
\fBAI_PASSIVE\fR
|
||||
bit, the returned socket address structure will be ready
|
||||
for use in a call to
|
||||
\fBconnect\fR(2)
|
||||
for a connection-oriented protocol or
|
||||
\fBconnect\fR(2),
|
||||
\fBsendto\fR(2),
|
||||
or
|
||||
\fBsendmsg\fR(2)
|
||||
if a connectionless protocol was chosen.
|
||||
The IP address portion of the socket address structure will be
|
||||
set to the loopback address if
|
||||
\fIhostname\fR
|
||||
is a
|
||||
\fBNULL\fR
|
||||
pointer and
|
||||
\fBAI_PASSIVE\fR
|
||||
is not set in
|
||||
ai_flags.
|
||||
|
||||
If
|
||||
ai_flags
|
||||
is set to
|
||||
\fBAI_NUMERICHOST\fR
|
||||
it indicates that
|
||||
\fIhostname\fR
|
||||
should be treated as a numeric string defining an IPv4 or IPv6 address
|
||||
and no name resolution should be attempted.
|
||||
.PP
|
||||
All other elements of the \fBstruct addrinfo\fR passed
|
||||
via \fIhints\fR must be zero.
|
||||
.PP
|
||||
A \fIhints\fR of \fBNULL\fR is treated as if
|
||||
the caller provided a \fBstruct addrinfo\fR initialized to zero
|
||||
with ai_familyset to
|
||||
PF_UNSPEC.
|
||||
.PP
|
||||
After a successful call to
|
||||
\fBlwres_getaddrinfo()\fR,
|
||||
\fI*res\fR
|
||||
is a pointer to a linked list of one or more
|
||||
\fBaddrinfo\fR
|
||||
structures.
|
||||
Each
|
||||
\fBstruct addrinfo\fR
|
||||
in this list cn be processed by following
|
||||
the
|
||||
ai_next
|
||||
pointer, until a
|
||||
\fBNULL\fR
|
||||
pointer is encountered.
|
||||
The three members
|
||||
ai_family,
|
||||
ai_socktype,
|
||||
and
|
||||
ai_protocol
|
||||
in each
|
||||
returned
|
||||
\fBaddrinfo\fR
|
||||
structure contain the corresponding arguments for a call to
|
||||
\fBsocket\fR(2).
|
||||
For each
|
||||
\fBaddrinfo\fR
|
||||
structure in the list, the
|
||||
ai_addr
|
||||
member points to a filled-in socket address structure of length
|
||||
ai_addrlen.
|
||||
.PP
|
||||
All of the information returned by
|
||||
\fBlwres_getaddrinfo()\fR
|
||||
is dynamically allocated: the addrinfo structures, and the socket
|
||||
address structures and canonical host name strings pointed to by the
|
||||
addrinfostructures.
|
||||
Memory allocated for the dynamically allocated structures created by
|
||||
a successful call to
|
||||
\fBlwres_getaddrinfo()\fR
|
||||
is released by
|
||||
\fBlwres_freeaddrinfo()\fR.
|
||||
\fIai\fR
|
||||
is a pointer to a
|
||||
\fBstruct addrinfo\fR
|
||||
created by a call to
|
||||
\fBlwres_getaddrinfo()\fR.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
\fBlwres_getaddrinfo()\fR
|
||||
returns zero on success or one of the error codes listed in
|
||||
\fBgai_strerror\fR(3)
|
||||
if an error occurs.
|
||||
If both
|
||||
\fIhostname\fR
|
||||
and
|
||||
\fIservname\fR
|
||||
are
|
||||
\fBNULL\fR
|
||||
\fBlwres_getaddrinfo()\fR
|
||||
returns
|
||||
EAI_NONAME.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBlwres\fR(3),
|
||||
\fBlwres_getaddrinfo\fR(3),
|
||||
\fBlwres_freeaddrinfo\fR(3),
|
||||
\fBlwres_gai_strerror\fR(3),
|
||||
\fBRFC2133\fR,
|
||||
\fBgetservbyname\fR(3),
|
||||
\fBbind\fR(2),
|
||||
\fBconnect\fR(2),
|
||||
\fBsendto\fR(2),
|
||||
\fBsendmsg\fR(2),
|
||||
\fBsocket\fR(2).
|
||||
@@ -0,0 +1,372 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_getaddrinfo.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_getaddrinfo</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_getaddrinfo</refname>
|
||||
<refname>lwres_freeaddrinfo</refname>
|
||||
<refpurpose>socket address structure to host and service name</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
int
|
||||
<function>lwres_getaddrinfo</function></funcdef>
|
||||
<paramdef>const char *hostname</paramdef>
|
||||
<paramdef>const char *servname</paramdef>
|
||||
<paramdef>const struct addrinfo *hints</paramdef>
|
||||
<paramdef>struct addrinfo **res</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_freeaddrinfo</function></funcdef>
|
||||
<paramdef>struct addrinfo *ai</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<para>
|
||||
If the operating system does not provide a
|
||||
<type>struct addrinfo</type>,
|
||||
the following structure is used:
|
||||
|
||||
<programlisting>
|
||||
struct addrinfo {
|
||||
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
|
||||
int ai_family; /* PF_xxx */
|
||||
int ai_socktype; /* SOCK_xxx */
|
||||
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
|
||||
size_t ai_addrlen; /* length of ai_addr */
|
||||
char *ai_canonname; /* canonical name for hostname */
|
||||
struct sockaddr *ai_addr; /* binary address */
|
||||
struct addrinfo *ai_next; /* next structure in linked list */
|
||||
};
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
<function>lwres_getaddrinfo()</function>
|
||||
is used to get a list of IP addresses and port numbers for host
|
||||
<parameter>hostname</parameter>
|
||||
and service
|
||||
<parameter>servname</parameter>.
|
||||
|
||||
The function is the lightweight resolver's implementation of
|
||||
<function>getaddrinfo()</function>
|
||||
as defined in RFC2133.
|
||||
<parameter>hostname</parameter>
|
||||
and
|
||||
<parameter>servname</parameter>
|
||||
are pointers to null-terminated
|
||||
strings or
|
||||
<type>NULL</type>.
|
||||
|
||||
<parameter>hostname</parameter>
|
||||
is either a host name or a numeric host address string: a dotted decimal
|
||||
IPv4 address or an IPv6 address.
|
||||
<parameter>servname</parameter>
|
||||
is either a decimal port number or a service name as listed in
|
||||
<filename>/etc/services</filename>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<parameter>hints</parameter>
|
||||
is an optional pointer to a
|
||||
<type>struct addrinfo</type>.
|
||||
This structure can be used to provide hints concerning the type of socket
|
||||
that the caller supports or wishes to use.
|
||||
The caller can supply the following structure elements in
|
||||
<parameter>*hints</parameter>:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>ai_family</constant></term>
|
||||
<listitem>
|
||||
<para>The protocol family that should be used.
|
||||
When
|
||||
<constant>ai_family</constant>
|
||||
is set to
|
||||
<type>PF_UNSPEC</type>,
|
||||
it means the caller will accept any protocol family supported by the
|
||||
operating system.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>ai_socktype</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
denotes the type of socket —
|
||||
<type>SOCK_STREAM</type>,
|
||||
<type>SOCK_DGRAM</type>
|
||||
or
|
||||
<type>SOCK_RAW</type>
|
||||
— that is wanted.
|
||||
When
|
||||
<constant>ai_socktype</constant>
|
||||
is zero the caller will accept any socket type.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><constant>ai_protocol</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
indicates which transport protocol is wanted: IPPROTO_UDP or
|
||||
IPPROTO_TCP.
|
||||
If
|
||||
<constant>ai_protocol</constant>
|
||||
is zero the caller will accept any protocol.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry><term><constant>ai_flags</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Flag bits.
|
||||
If the
|
||||
<type>AI_CANONNAME</type>
|
||||
bit is set, a successful call to
|
||||
<function>lwres_getaddrinfo()</function>
|
||||
will return a a null-terminated string containing the canonical name
|
||||
of the specified hostname in
|
||||
<constant>ai_canonname</constant>
|
||||
of the first
|
||||
<type>addrinfo</type>
|
||||
structure returned.
|
||||
Setting the
|
||||
<type>AI_PASSIVE</type>
|
||||
bit indicates that the returned socket address structure is intended
|
||||
for used in a call to
|
||||
<citerefentry>
|
||||
<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>.
|
||||
|
||||
In this case, if the hostname argument is a
|
||||
<type>NULL</type>
|
||||
pointer, then the IP address portion of the socket
|
||||
address structure will be set to
|
||||
<type>INADDR_ANY</type>
|
||||
for an IPv4 address or
|
||||
<type>IN6ADDR_ANY_INIT</type>
|
||||
for an IPv6 address.
|
||||
</para>
|
||||
<para>
|
||||
When
|
||||
<constant>ai_flags</constant>
|
||||
does not set the
|
||||
<type>AI_PASSIVE</type>
|
||||
bit, the returned socket address structure will be ready
|
||||
for use in a call to
|
||||
<citerefentry>
|
||||
<refentrytitle>connect</refentrytitle><manvolnum>2
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
for a connection-oriented protocol or
|
||||
<citerefentry>
|
||||
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
or
|
||||
<citerefentry>
|
||||
<refentrytitle>sendmsg</refentrytitle><manvolnum>2
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
if a connectionless protocol was chosen.
|
||||
The IP address portion of the socket address structure will be
|
||||
set to the loopback address if
|
||||
<parameter>hostname</parameter>
|
||||
is a
|
||||
<type>NULL</type>
|
||||
pointer and
|
||||
<type>AI_PASSIVE</type>
|
||||
is not set in
|
||||
<constant>ai_flags</constant>.
|
||||
</para>
|
||||
<para>
|
||||
If
|
||||
<constant>ai_flags</constant>
|
||||
is set to
|
||||
<type>AI_NUMERICHOST</type>
|
||||
it indicates that
|
||||
<parameter>hostname</parameter>
|
||||
should be treated as a numeric string defining an IPv4 or IPv6 address
|
||||
and no name resolution should be attempted.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All other elements of the <type>struct addrinfo</type> passed
|
||||
via <parameter>hints</parameter> must be zero.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A <parameter>hints</parameter> of <type>NULL</type> is treated as if
|
||||
the caller provided a <type>struct addrinfo</type> initialized to zero
|
||||
with <constant>ai_family</constant>set to
|
||||
<constant>PF_UNSPEC</constant>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
After a successful call to
|
||||
<function>lwres_getaddrinfo()</function>,
|
||||
<parameter>*res</parameter>
|
||||
is a pointer to a linked list of one or more
|
||||
<type>addrinfo</type>
|
||||
structures.
|
||||
Each
|
||||
<type>struct addrinfo</type>
|
||||
in this list cn be processed by following
|
||||
the
|
||||
<constant>ai_next</constant>
|
||||
pointer, until a
|
||||
<type>NULL</type>
|
||||
pointer is encountered.
|
||||
The three members
|
||||
<constant>ai_family</constant>,
|
||||
<constant>ai_socktype</constant>,
|
||||
and
|
||||
<constant>ai_protocol</constant>
|
||||
in each
|
||||
returned
|
||||
<type>addrinfo</type>
|
||||
structure contain the corresponding arguments for a call to
|
||||
<citerefentry>
|
||||
<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>.
|
||||
For each
|
||||
<type>addrinfo</type>
|
||||
structure in the list, the
|
||||
<constant>ai_addr</constant>
|
||||
member points to a filled-in socket address structure of length
|
||||
<constant>ai_addrlen</constant>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All of the information returned by
|
||||
<function>lwres_getaddrinfo()</function>
|
||||
is dynamically allocated: the addrinfo structures, and the socket
|
||||
address structures and canonical host name strings pointed to by the
|
||||
<constant>addrinfo</constant>structures.
|
||||
Memory allocated for the dynamically allocated structures created by
|
||||
a successful call to
|
||||
<function>lwres_getaddrinfo()</function>
|
||||
is released by
|
||||
<function>lwres_freeaddrinfo()</function>.
|
||||
<parameter>ai</parameter>
|
||||
is a pointer to a
|
||||
<type>struct addrinfo</type>
|
||||
created by a call to
|
||||
<function>lwres_getaddrinfo()</function>.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
<function>lwres_getaddrinfo()</function>
|
||||
returns zero on success or one of the error codes listed in
|
||||
<citerefentry>
|
||||
<refentrytitle>gai_strerror</refentrytitle><manvolnum>3
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
if an error occurs.
|
||||
If both
|
||||
<parameter>hostname</parameter>
|
||||
and
|
||||
<parameter>servname</parameter>
|
||||
are
|
||||
<type>NULL</type>
|
||||
<function>lwres_getaddrinfo()</function>
|
||||
returns
|
||||
<errorcode>EAI_NONAME</errorcode>.
|
||||
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>RFC2133</refentrytitle>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,722 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_getaddrinfo</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_getaddrinfo</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_getaddrinfo, lwres_freeaddrinfo -- socket address structure to host and service name</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN12"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN13"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/netdb.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>int
|
||||
lwres_getaddrinfo</CODE
|
||||
>(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_freeaddrinfo</CODE
|
||||
>(struct addrinfo *ai);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
><P
|
||||
>If the operating system does not provide a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct addrinfo</SPAN
|
||||
>,
|
||||
the following structure is used:
|
||||
|
||||
<PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>struct addrinfo {
|
||||
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
|
||||
int ai_family; /* PF_xxx */
|
||||
int ai_socktype; /* SOCK_xxx */
|
||||
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
|
||||
size_t ai_addrlen; /* length of ai_addr */
|
||||
char *ai_canonname; /* canonical name for hostname */
|
||||
struct sockaddr *ai_addr; /* binary address */
|
||||
struct addrinfo *ai_next; /* next structure in linked list */
|
||||
};</PRE
|
||||
></P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN29"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrinfo()</TT
|
||||
>
|
||||
is used to get a list of IP addresses and port numbers for host
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hostname</I
|
||||
></TT
|
||||
>
|
||||
and service
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>servname</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
The function is the lightweight resolver's implementation of
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>getaddrinfo()</TT
|
||||
>
|
||||
as defined in RFC2133.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hostname</I
|
||||
></TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>servname</I
|
||||
></TT
|
||||
>
|
||||
are pointers to null-terminated
|
||||
strings or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
>.
|
||||
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hostname</I
|
||||
></TT
|
||||
>
|
||||
is either a host name or a numeric host address string: a dotted decimal
|
||||
IPv4 address or an IPv6 address.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>servname</I
|
||||
></TT
|
||||
>
|
||||
is either a decimal port number or a service name as listed in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
>/etc/services</TT
|
||||
>.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hints</I
|
||||
></TT
|
||||
>
|
||||
is an optional pointer to a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct addrinfo</SPAN
|
||||
>.
|
||||
This structure can be used to provide hints concerning the type of socket
|
||||
that the caller supports or wishes to use.
|
||||
The caller can supply the following structure elements in
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*hints</I
|
||||
></TT
|
||||
>:
|
||||
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_family</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The protocol family that should be used.
|
||||
When
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_family</TT
|
||||
>
|
||||
is set to
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_UNSPEC</SPAN
|
||||
>,
|
||||
it means the caller will accept any protocol family supported by the
|
||||
operating system.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_socktype</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>denotes the type of socket —
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>SOCK_STREAM</SPAN
|
||||
>,
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>SOCK_DGRAM</SPAN
|
||||
>
|
||||
or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>SOCK_RAW</SPAN
|
||||
>
|
||||
— that is wanted.
|
||||
When
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_socktype</TT
|
||||
>
|
||||
is zero the caller will accept any socket type.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_protocol</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>indicates which transport protocol is wanted: IPPROTO_UDP or
|
||||
IPPROTO_TCP.
|
||||
If
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_protocol</TT
|
||||
>
|
||||
is zero the caller will accept any protocol.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_flags</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>Flag bits.
|
||||
If the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>AI_CANONNAME</SPAN
|
||||
>
|
||||
bit is set, a successful call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrinfo()</TT
|
||||
>
|
||||
will return a a null-terminated string containing the canonical name
|
||||
of the specified hostname in
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_canonname</TT
|
||||
>
|
||||
of the first
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>addrinfo</SPAN
|
||||
>
|
||||
structure returned.
|
||||
Setting the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>AI_PASSIVE</SPAN
|
||||
>
|
||||
bit indicates that the returned socket address structure is intended
|
||||
for used in a call to
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>bind</SPAN
|
||||
>(2)</SPAN
|
||||
>.
|
||||
|
||||
In this case, if the hostname argument is a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
>
|
||||
pointer, then the IP address portion of the socket
|
||||
address structure will be set to
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>INADDR_ANY</SPAN
|
||||
>
|
||||
for an IPv4 address or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>IN6ADDR_ANY_INIT</SPAN
|
||||
>
|
||||
for an IPv6 address.</P
|
||||
><P
|
||||
>When
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_flags</TT
|
||||
>
|
||||
does not set the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>AI_PASSIVE</SPAN
|
||||
>
|
||||
bit, the returned socket address structure will be ready
|
||||
for use in a call to
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>connect</SPAN
|
||||
>(2)</SPAN
|
||||
>
|
||||
for a connection-oriented protocol or
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>connect</SPAN
|
||||
>(2)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>sendto</SPAN
|
||||
>(2)</SPAN
|
||||
>,
|
||||
|
||||
or
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>sendmsg</SPAN
|
||||
>(2)</SPAN
|
||||
>
|
||||
if a connectionless protocol was chosen.
|
||||
The IP address portion of the socket address structure will be
|
||||
set to the loopback address if
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hostname</I
|
||||
></TT
|
||||
>
|
||||
is a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
>
|
||||
pointer and
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>AI_PASSIVE</SPAN
|
||||
>
|
||||
is not set in
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_flags</TT
|
||||
>.</P
|
||||
><P
|
||||
>If
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_flags</TT
|
||||
>
|
||||
is set to
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>AI_NUMERICHOST</SPAN
|
||||
>
|
||||
it indicates that
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hostname</I
|
||||
></TT
|
||||
>
|
||||
should be treated as a numeric string defining an IPv4 or IPv6 address
|
||||
and no name resolution should be attempted.</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
><P
|
||||
>All other elements of the <SPAN
|
||||
CLASS="TYPE"
|
||||
>struct addrinfo</SPAN
|
||||
> passed
|
||||
via <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hints</I
|
||||
></TT
|
||||
> must be zero.</P
|
||||
><P
|
||||
>A <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hints</I
|
||||
></TT
|
||||
> of <SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
> is treated as if
|
||||
the caller provided a <SPAN
|
||||
CLASS="TYPE"
|
||||
>struct addrinfo</SPAN
|
||||
> initialized to zero
|
||||
with <TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_family</TT
|
||||
>set to
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>PF_UNSPEC</TT
|
||||
>.</P
|
||||
><P
|
||||
>After a successful call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrinfo()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*res</I
|
||||
></TT
|
||||
>
|
||||
is a pointer to a linked list of one or more
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>addrinfo</SPAN
|
||||
>
|
||||
structures.
|
||||
Each
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct addrinfo</SPAN
|
||||
>
|
||||
in this list cn be processed by following
|
||||
the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_next</TT
|
||||
>
|
||||
pointer, until a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
>
|
||||
pointer is encountered.
|
||||
The three members
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_family</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_socktype</TT
|
||||
>,
|
||||
and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_protocol</TT
|
||||
>
|
||||
in each
|
||||
returned
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>addrinfo</SPAN
|
||||
>
|
||||
structure contain the corresponding arguments for a call to
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>socket</SPAN
|
||||
>(2)</SPAN
|
||||
>.
|
||||
For each
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>addrinfo</SPAN
|
||||
>
|
||||
structure in the list, the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_addr</TT
|
||||
>
|
||||
member points to a filled-in socket address structure of length
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>ai_addrlen</TT
|
||||
>.</P
|
||||
><P
|
||||
>All of the information returned by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrinfo()</TT
|
||||
>
|
||||
is dynamically allocated: the addrinfo structures, and the socket
|
||||
address structures and canonical host name strings pointed to by the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>addrinfo</TT
|
||||
>structures.
|
||||
Memory allocated for the dynamically allocated structures created by
|
||||
a successful call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrinfo()</TT
|
||||
>
|
||||
is released by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_freeaddrinfo()</TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ai</I
|
||||
></TT
|
||||
>
|
||||
is a pointer to a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct addrinfo</SPAN
|
||||
>
|
||||
created by a call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrinfo()</TT
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN142"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrinfo()</TT
|
||||
>
|
||||
returns zero on success or one of the error codes listed in
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>gai_strerror</SPAN
|
||||
>(3)</SPAN
|
||||
>
|
||||
if an error occurs.
|
||||
If both
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hostname</I
|
||||
></TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>servname</I
|
||||
></TT
|
||||
>
|
||||
are
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
>
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrinfo()</TT
|
||||
>
|
||||
returns
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAI_NONAME</SPAN
|
||||
>. </P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN154"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_getaddrinfo</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_freeaddrinfo</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_gai_strerror</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>RFC2133</SPAN
|
||||
></SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>getservbyname</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>bind</SPAN
|
||||
>(2)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>connect</SPAN
|
||||
>(2)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>sendto</SPAN
|
||||
>(2)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>sendmsg</SPAN
|
||||
>(2)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>socket</SPAN
|
||||
>(2)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,270 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_GETHOSTENT" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r \- lightweight resolver get network host entry
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/netdb.h>
|
||||
.sp
|
||||
.na
|
||||
struct hostent *
|
||||
lwres_gethostbyname(const char *name);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
struct hostent *
|
||||
lwres_gethostbyname2(const char *name, int af);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
struct hostent *
|
||||
lwres_gethostbyaddr(const char *addr, int len, int type);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
struct hostent *
|
||||
lwres_gethostent(void);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_sethostent(int stayopen);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_endhostent(void);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
struct hostent *
|
||||
lwres_gethostbyname_r(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
struct hostent *
|
||||
lwres_gethostbyaddr_r(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, int *error);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
struct hostent *
|
||||
lwres_gethostent_r(struct hostent *resbuf, char *buf, int buflen, int *error);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_sethostent_r(int stayopen);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_endhostent_r(void);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
These functions provide hostname-to-address and
|
||||
address-to-hostname lookups by means of the lightweight resolver.
|
||||
They are similar to the standard
|
||||
\fBgethostent\fR(3)
|
||||
functions provided by most operating systems.
|
||||
They use a
|
||||
\fBstruct hostent\fR
|
||||
which is usually defined in
|
||||
\fI<namedb.h>\fR.
|
||||
.sp
|
||||
.nf
|
||||
struct hostent {
|
||||
char *h_name; /* official name of host */
|
||||
char **h_aliases; /* alias list */
|
||||
int h_addrtype; /* host address type */
|
||||
int h_length; /* length of address */
|
||||
char **h_addr_list; /* list of addresses from name server */
|
||||
};
|
||||
#define h_addr h_addr_list[0] /* address, for backward compatibility */
|
||||
.sp
|
||||
.fi
|
||||
.PP
|
||||
The members of this structure are:
|
||||
.TP
|
||||
\fBh_name\fR
|
||||
The official (canonical) name of the host.
|
||||
.TP
|
||||
\fBh_aliases\fR
|
||||
A NULL-terminated array of alternate names (nicknames) for the host.
|
||||
.TP
|
||||
\fBh_addrtype\fR
|
||||
The type of address being returned \(em
|
||||
\fBPF_INET\fR
|
||||
or
|
||||
\fBPF_INET6\fR.
|
||||
.TP
|
||||
\fBh_length\fR
|
||||
The length of the address in bytes.
|
||||
.TP
|
||||
\fBh_addr_list\fR
|
||||
A \fBNULL\fR
|
||||
terminated array of network addresses for the host.
|
||||
Host addresses are returned in network byte order.
|
||||
.PP
|
||||
For backward compatibility with very old software,
|
||||
h_addr
|
||||
is the first address in
|
||||
h_addr_list.
|
||||
.PP
|
||||
\fBlwres_gethostent()\fR,
|
||||
\fBlwres_sethostent()\fR,
|
||||
\fBlwres_endhostent()\fR,
|
||||
\fBlwres_gethostent_r()\fR,
|
||||
\fBlwres_sethostent_r()\fR
|
||||
and
|
||||
\fBlwres_endhostent_r()\fR
|
||||
provide iteration over the known host entries on systems that
|
||||
provide such functionality through facilities like
|
||||
\fI/etc/hosts\fR
|
||||
or NIS. The lightweight resolver does not currently implement
|
||||
these functions; it only provides them as stub functions that always
|
||||
return failure.
|
||||
.PP
|
||||
\fBlwres_gethostbyname()\fR and
|
||||
\fBlwres_gethostbyname2()\fR look up the hostname
|
||||
\fIname\fR.
|
||||
\fBlwres_gethostbyname()\fR always looks for an IPv4
|
||||
address while \fBlwres_gethostbyname2()\fR looks for an
|
||||
address of protocol family \fIaf\fR: either
|
||||
\fBPF_INET\fR or \fBPF_INET6\fR \(em IPv4 or IPV6
|
||||
addresses respectively. Successful calls of the functions return a
|
||||
\fBstruct hostent\fRfor the name that was looked up.
|
||||
\fBNULL\fR is returned if the lookups by
|
||||
\fBlwres_gethostbyname()\fR or
|
||||
\fBlwres_gethostbyname2()\fR fail.
|
||||
.PP
|
||||
Reverse lookups of addresses are performed by
|
||||
\fBlwres_gethostbyaddr()\fR.
|
||||
\fIaddr\fR is an address of length
|
||||
\fIlen\fR bytes and protocol family
|
||||
\fItype\fR \(em \fBPF_INET\fR or
|
||||
\fBPF_INET6\fR.
|
||||
\fBlwres_gethostbyname_r()\fR is a thread-safe function
|
||||
for forward lookups. If an error occurs, an error code is returned in
|
||||
\fI*error\fR.
|
||||
\fIresbuf\fR is a pointer to a \fBstruct
|
||||
hostent\fR which is initialised by a successful call to
|
||||
\fBlwres_gethostbyname_r()\fR .
|
||||
\fIbuf\fR is a buffer of length
|
||||
\fIlen\fR bytes which is used to store the
|
||||
h_name, h_aliases, and
|
||||
h_addr_list elements of the \fBstruct
|
||||
hostent\fR returned in \fIresbuf\fR.
|
||||
Successful calls to \fBlwres_gethostbyname_r()\fR
|
||||
return \fIresbuf\fR,
|
||||
which is a pointer to the \fBstruct hostent\fR it created.
|
||||
.PP
|
||||
\fBlwres_gethostbyaddr_r()\fR is a thread-safe function
|
||||
that performs a reverse lookup of address \fIaddr\fR
|
||||
which is \fIlen\fR bytes long and is of protocol
|
||||
family \fItype\fR \(em \fBPF_INET\fR or
|
||||
\fBPF_INET6\fR. If an error occurs, the error code is returned
|
||||
in \fI*error\fR. The other function parameters are
|
||||
identical to those in \fBlwres_gethostbyname_r()\fR.
|
||||
\fIresbuf\fR is a pointer to a \fBstruct
|
||||
hostent\fR which is initialised by a successful call to
|
||||
\fBlwres_gethostbyaddr_r()\fR.
|
||||
\fIbuf\fR is a buffer of length
|
||||
\fIlen\fR bytes which is used to store the
|
||||
h_name, h_aliases, and
|
||||
h_addr_list elements of the \fBstruct
|
||||
hostent\fR returned in \fIresbuf\fR. Successful
|
||||
calls to \fBlwres_gethostbyaddr_r()\fR return
|
||||
\fIresbuf\fR, which is a pointer to the
|
||||
\fBstruct hostent()\fR it created.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
The functions
|
||||
\fBlwres_gethostbyname()\fR,
|
||||
\fBlwres_gethostbyname2()\fR,
|
||||
\fBlwres_gethostbyaddr()\fR,
|
||||
and
|
||||
\fBlwres_gethostent()\fR
|
||||
return NULL to indicate an error. In this case the global variable
|
||||
\fBlwres_h_errno\fR
|
||||
will contain one of the following error codes defined in
|
||||
\fI<lwres/netdb.h>\fR:
|
||||
.TP
|
||||
\fBHOST_NOT_FOUND\fR
|
||||
The host or address was not found.
|
||||
.TP
|
||||
\fBTRY_AGAIN\fR
|
||||
A recoverable error occurred, e.g., a timeout.
|
||||
Retrying the lookup may succeed.
|
||||
.TP
|
||||
\fBNO_RECOVERY\fR
|
||||
A non-recoverable error occurred.
|
||||
.TP
|
||||
\fBNO_DATA\fR
|
||||
The name exists, but has no address information
|
||||
associated with it (or vice versa in the case
|
||||
of a reverse lookup). The code NO_ADDRESS
|
||||
is accepted as a synonym for NO_DATA for backwards
|
||||
compatibility.
|
||||
.PP
|
||||
\fBlwres_hstrerror\fR(3)
|
||||
translates these error codes to suitable error messages.
|
||||
.PP
|
||||
\fBlwres_gethostent()\fR
|
||||
and
|
||||
\fBlwres_gethostent_r()\fR
|
||||
always return
|
||||
\fBNULL\fR.
|
||||
.PP
|
||||
Successful calls to \fBlwres_gethostbyname_r()\fR and
|
||||
\fBlwres_gethostbyaddr_r()\fR return
|
||||
\fIresbuf\fR, a pointer to the \fBstruct
|
||||
hostent\fR that was initialised by these functions. They return
|
||||
\fBNULL\fR if the lookups fail or if \fIbuf\fR
|
||||
was too small to hold the list of addresses and names referenced by
|
||||
the h_name, h_aliases, and
|
||||
h_addr_list elements of the \fBstruct
|
||||
hostent\fR. If \fIbuf\fR was too small, both
|
||||
\fBlwres_gethostbyname_r()\fR and
|
||||
\fBlwres_gethostbyaddr_r()\fR set the global variable
|
||||
\fBerrno\fR to ERANGE.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBgethostent\fR(3),
|
||||
\fBlwres_getipnode\fR(3),
|
||||
\fBlwres_hstrerror\fR(3)
|
||||
.SH "BUGS"
|
||||
.PP
|
||||
\fBlwres_gethostbyname()\fR,
|
||||
\fBlwres_gethostbyname2()\fR,
|
||||
\fBlwres_gethostbyaddr()\fR
|
||||
and
|
||||
\fBlwres_endhostent()\fR
|
||||
are not thread safe; they return pointers to static data and
|
||||
provide error codes through a global variable.
|
||||
Thread-safe versions for name and address lookup are provided by
|
||||
\fBlwres_gethostbyname_r()\fR,
|
||||
and
|
||||
\fBlwres_gethostbyaddr_r()\fR
|
||||
respectively.
|
||||
.PP
|
||||
The resolver daemon does not currently support any non-DNS
|
||||
name services such as
|
||||
\fI/etc/hosts\fR
|
||||
or
|
||||
\fBNIS\fR,
|
||||
consequently the above functions don't, either.
|
||||
@@ -0,0 +1,407 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_gethostent.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_gethostent</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_gethostbyname</refname>
|
||||
<refname>lwres_gethostbyname2</refname>
|
||||
<refname>lwres_gethostbyaddr</refname>
|
||||
<refname>lwres_gethostent</refname>
|
||||
<refname>lwres_sethostent</refname>
|
||||
<refname>lwres_endhostent</refname>
|
||||
<refname>lwres_gethostbyname_r</refname>
|
||||
<refname>lwres_gethostbyaddr_r</refname>
|
||||
<refname>lwres_gethostent_r</refname>
|
||||
<refname>lwres_sethostent_r</refname>
|
||||
<refname>lwres_endhostent_r</refname>
|
||||
<refpurpose>lightweight resolver get network host entry</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
struct hostent *
|
||||
<function>lwres_gethostbyname</function></funcdef>
|
||||
<paramdef>const char *name</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
struct hostent *
|
||||
<function>lwres_gethostbyname2</function></funcdef>
|
||||
<paramdef>const char *name</paramdef>
|
||||
<paramdef>int af</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
struct hostent *
|
||||
<function>lwres_gethostbyaddr</function></funcdef>
|
||||
<paramdef>const char *addr</paramdef>
|
||||
<paramdef>int len</paramdef>
|
||||
<paramdef>int type</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
struct hostent *
|
||||
<function>lwres_gethostent</function></funcdef>
|
||||
<paramdef>void</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_sethostent</function></funcdef>
|
||||
<paramdef>int stayopen</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_endhostent</function></funcdef>
|
||||
<paramdef>void</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
struct hostent *
|
||||
<function>lwres_gethostbyname_r</function></funcdef>
|
||||
<paramdef>const char *name</paramdef>
|
||||
<paramdef>struct hostent *resbuf</paramdef>
|
||||
<paramdef>char *buf</paramdef>
|
||||
<paramdef>int buflen</paramdef>
|
||||
<paramdef>int *error</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
struct hostent *
|
||||
<function>lwres_gethostbyaddr_r</function></funcdef>
|
||||
<paramdef>const char *addr</paramdef>
|
||||
<paramdef>int len</paramdef>
|
||||
<paramdef>int type</paramdef>
|
||||
<paramdef>struct hostent *resbuf</paramdef>
|
||||
<paramdef>char *buf</paramdef>
|
||||
<paramdef>int buflen</paramdef>
|
||||
<paramdef>int *error</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
struct hostent *
|
||||
<function>lwres_gethostent_r</function></funcdef>
|
||||
<paramdef>struct hostent *resbuf</paramdef>
|
||||
<paramdef>char *buf</paramdef>
|
||||
<paramdef>int buflen</paramdef>
|
||||
<paramdef>int *error</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_sethostent_r</function></funcdef>
|
||||
<paramdef>int stayopen</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_endhostent_r</function></funcdef>
|
||||
<paramdef>void</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
These functions provide hostname-to-address and
|
||||
address-to-hostname lookups by means of the lightweight resolver.
|
||||
They are similar to the standard
|
||||
<citerefentry>
|
||||
<refentrytitle>gethostent</refentrytitle><manvolnum>3
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
functions provided by most operating systems.
|
||||
They use a
|
||||
<type>struct hostent</type>
|
||||
which is usually defined in
|
||||
<filename><namedb.h></filename>.
|
||||
|
||||
<programlisting>
|
||||
struct hostent {
|
||||
char *h_name; /* official name of host */
|
||||
char **h_aliases; /* alias list */
|
||||
int h_addrtype; /* host address type */
|
||||
int h_length; /* length of address */
|
||||
char **h_addr_list; /* list of addresses from name server */
|
||||
};
|
||||
#define h_addr h_addr_list[0] /* address, for backward compatibility */
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
The members of this structure are:
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>h_name</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The official (canonical) name of the host.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>h_aliases</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A NULL-terminated array of alternate names (nicknames) for the host.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>h_addrtype</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The type of address being returned —
|
||||
<type>PF_INET</type>
|
||||
or
|
||||
<type>PF_INET6</type>.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>h_length</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The length of the address in bytes.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>h_addr_list</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A <type>NULL</type>
|
||||
terminated array of network addresses for the host.
|
||||
Host addresses are returned in network byte order.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
For backward compatibility with very old software,
|
||||
<constant>h_addr</constant>
|
||||
is the first address in
|
||||
<constant>h_addr_list.</constant>
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_gethostent()</function>,
|
||||
<function>lwres_sethostent()</function>,
|
||||
<function>lwres_endhostent()</function>,
|
||||
<function>lwres_gethostent_r()</function>,
|
||||
<function>lwres_sethostent_r()</function>
|
||||
and
|
||||
<function>lwres_endhostent_r()</function>
|
||||
provide iteration over the known host entries on systems that
|
||||
provide such functionality through facilities like
|
||||
<filename>/etc/hosts</filename>
|
||||
or NIS. The lightweight resolver does not currently implement
|
||||
these functions; it only provides them as stub functions that always
|
||||
return failure.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_gethostbyname()</function> and
|
||||
<function>lwres_gethostbyname2()</function> look up the hostname
|
||||
<parameter>name</parameter>.
|
||||
<function>lwres_gethostbyname()</function> always looks for an IPv4
|
||||
address while <function>lwres_gethostbyname2()</function> looks for an
|
||||
address of protocol family <parameter>af</parameter>: either
|
||||
<type>PF_INET</type> or <type>PF_INET6</type> — IPv4 or IPV6
|
||||
addresses respectively. Successful calls of the functions return a
|
||||
<type>struct hostent</type>for the name that was looked up.
|
||||
<type>NULL</type> is returned if the lookups by
|
||||
<function>lwres_gethostbyname()</function> or
|
||||
<function>lwres_gethostbyname2()</function> fail.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Reverse lookups of addresses are performed by
|
||||
<function>lwres_gethostbyaddr()</function>.
|
||||
<parameter>addr</parameter> is an address of length
|
||||
<parameter>len</parameter> bytes and protocol family
|
||||
<parameter>type</parameter> — <type>PF_INET</type> or
|
||||
<type>PF_INET6</type>.
|
||||
<function>lwres_gethostbyname_r()</function> is a thread-safe function
|
||||
for forward lookups. If an error occurs, an error code is returned in
|
||||
<parameter>*error</parameter>.
|
||||
<parameter>resbuf</parameter> is a pointer to a <type>struct
|
||||
hostent</type> which is initialised by a successful call to
|
||||
<function>lwres_gethostbyname_r()</function> .
|
||||
<parameter>buf</parameter> is a buffer of length
|
||||
<parameter>len</parameter> bytes which is used to store the
|
||||
<constant>h_name</constant>, <constant>h_aliases</constant>, and
|
||||
<constant>h_addr_list</constant> elements of the <type>struct
|
||||
hostent</type> returned in <parameter>resbuf</parameter>.
|
||||
Successful calls to <function>lwres_gethostbyname_r()</function>
|
||||
return <parameter>resbuf</parameter>,
|
||||
which is a pointer to the <type>struct hostent</type> it created.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_gethostbyaddr_r()</function> is a thread-safe function
|
||||
that performs a reverse lookup of address <parameter>addr</parameter>
|
||||
which is <parameter>len</parameter> bytes long and is of protocol
|
||||
family <parameter>type</parameter> — <type>PF_INET</type> or
|
||||
<type>PF_INET6</type>. If an error occurs, the error code is returned
|
||||
in <parameter>*error</parameter>. The other function parameters are
|
||||
identical to those in <function>lwres_gethostbyname_r()</function>.
|
||||
<parameter>resbuf</parameter> is a pointer to a <type>struct
|
||||
hostent</type> which is initialised by a successful call to
|
||||
<function>lwres_gethostbyaddr_r()</function>.
|
||||
<parameter>buf</parameter> is a buffer of length
|
||||
<parameter>len</parameter> bytes which is used to store the
|
||||
<constant>h_name</constant>, <constant>h_aliases</constant>, and
|
||||
<constant>h_addr_list</constant> elements of the <type>struct
|
||||
hostent</type> returned in <parameter>resbuf</parameter>. Successful
|
||||
calls to <function>lwres_gethostbyaddr_r()</function> return
|
||||
<parameter>resbuf</parameter>, which is a pointer to the
|
||||
<function>struct hostent()</function> it created.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
The functions
|
||||
<function>lwres_gethostbyname()</function>,
|
||||
<function>lwres_gethostbyname2()</function>,
|
||||
<function>lwres_gethostbyaddr()</function>,
|
||||
and
|
||||
<function>lwres_gethostent()</function>
|
||||
return NULL to indicate an error. In this case the global variable
|
||||
<type>lwres_h_errno</type>
|
||||
will contain one of the following error codes defined in
|
||||
<filename><lwres/netdb.h></filename>:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The host or address was not found.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>TRY_AGAIN</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A recoverable error occurred, e.g., a timeout.
|
||||
Retrying the lookup may succeed.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>NO_RECOVERY</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A non-recoverable error occurred.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>NO_DATA</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The name exists, but has no address information
|
||||
associated with it (or vice versa in the case
|
||||
of a reverse lookup). The code NO_ADDRESS
|
||||
is accepted as a synonym for NO_DATA for backwards
|
||||
compatibility.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
translates these error codes to suitable error messages.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_gethostent()</function>
|
||||
and
|
||||
<function>lwres_gethostent_r()</function>
|
||||
always return
|
||||
<type>NULL</type>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Successful calls to <function>lwres_gethostbyname_r()</function> and
|
||||
<function>lwres_gethostbyaddr_r()</function> return
|
||||
<parameter>resbuf</parameter>, a pointer to the <type>struct
|
||||
hostent</type> that was initialised by these functions. They return
|
||||
<type>NULL</type> if the lookups fail or if <parameter>buf</parameter>
|
||||
was too small to hold the list of addresses and names referenced by
|
||||
the <constant>h_name</constant>, <constant>h_aliases</constant>, and
|
||||
<constant>h_addr_list</constant> elements of the <type>struct
|
||||
hostent</type>. If <parameter>buf</parameter> was too small, both
|
||||
<function>lwres_gethostbyname_r()</function> and
|
||||
<function>lwres_gethostbyaddr_r()</function> set the global variable
|
||||
<type>errno</type> to <errorcode>ERANGE</errorcode>.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>BUGS</title>
|
||||
<para>
|
||||
<function>lwres_gethostbyname()</function>,
|
||||
<function>lwres_gethostbyname2()</function>,
|
||||
<function>lwres_gethostbyaddr()</function>
|
||||
and
|
||||
<function>lwres_endhostent()</function>
|
||||
are not thread safe; they return pointers to static data and
|
||||
provide error codes through a global variable.
|
||||
Thread-safe versions for name and address lookup are provided by
|
||||
<function>lwres_gethostbyname_r()</function>,
|
||||
and
|
||||
<function>lwres_gethostbyaddr_r()</function>
|
||||
respectively.
|
||||
</para>
|
||||
<para>
|
||||
The resolver daemon does not currently support any non-DNS
|
||||
name services such as
|
||||
<filename>/etc/hosts</filename>
|
||||
or
|
||||
<type>NIS</type>,
|
||||
consequently the above functions don't, either.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,827 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_gethostent</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_gethostent</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r -- lightweight resolver get network host entry</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN21"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN22"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/netdb.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>struct hostent *
|
||||
lwres_gethostbyname</CODE
|
||||
>(const char *name);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>struct hostent *
|
||||
lwres_gethostbyname2</CODE
|
||||
>(const char *name, int af);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>struct hostent *
|
||||
lwres_gethostbyaddr</CODE
|
||||
>(const char *addr, int len, int type);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>struct hostent *
|
||||
lwres_gethostent</CODE
|
||||
>(void);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_sethostent</CODE
|
||||
>(int stayopen);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_endhostent</CODE
|
||||
>(void);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>struct hostent *
|
||||
lwres_gethostbyname_r</CODE
|
||||
>(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>struct hostent *
|
||||
lwres_gethostbyaddr_r</CODE
|
||||
>(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>struct hostent *
|
||||
lwres_gethostent_r</CODE
|
||||
>(struct hostent *resbuf, char *buf, int buflen, int *error);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_sethostent_r</CODE
|
||||
>(int stayopen);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_endhostent_r</CODE
|
||||
>(void);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN84"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
>These functions provide hostname-to-address and
|
||||
address-to-hostname lookups by means of the lightweight resolver.
|
||||
They are similar to the standard
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>gethostent</SPAN
|
||||
>(3)</SPAN
|
||||
>
|
||||
functions provided by most operating systems.
|
||||
They use a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct hostent</SPAN
|
||||
>
|
||||
which is usually defined in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
><namedb.h></TT
|
||||
>.
|
||||
|
||||
<PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>struct hostent {
|
||||
char *h_name; /* official name of host */
|
||||
char **h_aliases; /* alias list */
|
||||
int h_addrtype; /* host address type */
|
||||
int h_length; /* length of address */
|
||||
char **h_addr_list; /* list of addresses from name server */
|
||||
};
|
||||
#define h_addr h_addr_list[0] /* address, for backward compatibility */</PRE
|
||||
></P
|
||||
><P
|
||||
>The members of this structure are:
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_name</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The official (canonical) name of the host.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_aliases</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>A NULL-terminated array of alternate names (nicknames) for the host.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addrtype</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The type of address being returned —
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET</SPAN
|
||||
>
|
||||
or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET6</SPAN
|
||||
>.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_length</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The length of the address in bytes.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addr_list</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>A <SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
>
|
||||
terminated array of network addresses for the host.
|
||||
Host addresses are returned in network byte order.</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
><P
|
||||
>For backward compatibility with very old software,
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addr</TT
|
||||
>
|
||||
is the first address in
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addr_list.</TT
|
||||
></P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostent()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_sethostent()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_endhostent()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostent_r()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_sethostent_r()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_endhostent_r()</TT
|
||||
>
|
||||
provide iteration over the known host entries on systems that
|
||||
provide such functionality through facilities like
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
>/etc/hosts</TT
|
||||
>
|
||||
or NIS. The lightweight resolver does not currently implement
|
||||
these functions; it only provides them as stub functions that always
|
||||
return failure.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname()</TT
|
||||
> and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname2()</TT
|
||||
> look up the hostname
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>name</I
|
||||
></TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname()</TT
|
||||
> always looks for an IPv4
|
||||
address while <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname2()</TT
|
||||
> looks for an
|
||||
address of protocol family <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>af</I
|
||||
></TT
|
||||
>: either
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET</SPAN
|
||||
> or <SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET6</SPAN
|
||||
> — IPv4 or IPV6
|
||||
addresses respectively. Successful calls of the functions return a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct hostent</SPAN
|
||||
>for the name that was looked up.
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
> is returned if the lookups by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname()</TT
|
||||
> or
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname2()</TT
|
||||
> fail.</P
|
||||
><P
|
||||
>Reverse lookups of addresses are performed by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyaddr()</TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>addr</I
|
||||
></TT
|
||||
> is an address of length
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>len</I
|
||||
></TT
|
||||
> bytes and protocol family
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>type</I
|
||||
></TT
|
||||
> — <SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET</SPAN
|
||||
> or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET6</SPAN
|
||||
>.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname_r()</TT
|
||||
> is a thread-safe function
|
||||
for forward lookups. If an error occurs, an error code is returned in
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*error</I
|
||||
></TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>resbuf</I
|
||||
></TT
|
||||
> is a pointer to a <SPAN
|
||||
CLASS="TYPE"
|
||||
>struct
|
||||
hostent</SPAN
|
||||
> which is initialised by a successful call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname_r()</TT
|
||||
> .
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>buf</I
|
||||
></TT
|
||||
> is a buffer of length
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>len</I
|
||||
></TT
|
||||
> bytes which is used to store the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_name</TT
|
||||
>, <TT
|
||||
CLASS="CONSTANT"
|
||||
>h_aliases</TT
|
||||
>, and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addr_list</TT
|
||||
> elements of the <SPAN
|
||||
CLASS="TYPE"
|
||||
>struct
|
||||
hostent</SPAN
|
||||
> returned in <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>resbuf</I
|
||||
></TT
|
||||
>.
|
||||
Successful calls to <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname_r()</TT
|
||||
>
|
||||
return <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>resbuf</I
|
||||
></TT
|
||||
>,
|
||||
which is a pointer to the <SPAN
|
||||
CLASS="TYPE"
|
||||
>struct hostent</SPAN
|
||||
> it created.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyaddr_r()</TT
|
||||
> is a thread-safe function
|
||||
that performs a reverse lookup of address <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>addr</I
|
||||
></TT
|
||||
>
|
||||
which is <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>len</I
|
||||
></TT
|
||||
> bytes long and is of protocol
|
||||
family <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>type</I
|
||||
></TT
|
||||
> — <SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET</SPAN
|
||||
> or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET6</SPAN
|
||||
>. If an error occurs, the error code is returned
|
||||
in <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*error</I
|
||||
></TT
|
||||
>. The other function parameters are
|
||||
identical to those in <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname_r()</TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>resbuf</I
|
||||
></TT
|
||||
> is a pointer to a <SPAN
|
||||
CLASS="TYPE"
|
||||
>struct
|
||||
hostent</SPAN
|
||||
> which is initialised by a successful call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyaddr_r()</TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>buf</I
|
||||
></TT
|
||||
> is a buffer of length
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>len</I
|
||||
></TT
|
||||
> bytes which is used to store the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_name</TT
|
||||
>, <TT
|
||||
CLASS="CONSTANT"
|
||||
>h_aliases</TT
|
||||
>, and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addr_list</TT
|
||||
> elements of the <SPAN
|
||||
CLASS="TYPE"
|
||||
>struct
|
||||
hostent</SPAN
|
||||
> returned in <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>resbuf</I
|
||||
></TT
|
||||
>. Successful
|
||||
calls to <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyaddr_r()</TT
|
||||
> return
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>resbuf</I
|
||||
></TT
|
||||
>, which is a pointer to the
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>struct hostent()</TT
|
||||
> it created.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN191"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
>The functions
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname2()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyaddr()</TT
|
||||
>,
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostent()</TT
|
||||
>
|
||||
return NULL to indicate an error. In this case the global variable
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_h_errno</SPAN
|
||||
>
|
||||
will contain one of the following error codes defined in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
><lwres/netdb.h></TT
|
||||
>:
|
||||
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>HOST_NOT_FOUND</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The host or address was not found.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>TRY_AGAIN</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>A recoverable error occurred, e.g., a timeout.
|
||||
Retrying the lookup may succeed.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NO_RECOVERY</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>A non-recoverable error occurred.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NO_DATA</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The name exists, but has no address information
|
||||
associated with it (or vice versa in the case
|
||||
of a reverse lookup). The code NO_ADDRESS
|
||||
is accepted as a synonym for NO_DATA for backwards
|
||||
compatibility.</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_hstrerror</SPAN
|
||||
>(3)</SPAN
|
||||
>
|
||||
translates these error codes to suitable error messages.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostent()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostent_r()</TT
|
||||
>
|
||||
always return
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
>.</P
|
||||
><P
|
||||
>Successful calls to <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname_r()</TT
|
||||
> and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyaddr_r()</TT
|
||||
> return
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>resbuf</I
|
||||
></TT
|
||||
>, a pointer to the <SPAN
|
||||
CLASS="TYPE"
|
||||
>struct
|
||||
hostent</SPAN
|
||||
> that was initialised by these functions. They return
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
> if the lookups fail or if <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>buf</I
|
||||
></TT
|
||||
>
|
||||
was too small to hold the list of addresses and names referenced by
|
||||
the <TT
|
||||
CLASS="CONSTANT"
|
||||
>h_name</TT
|
||||
>, <TT
|
||||
CLASS="CONSTANT"
|
||||
>h_aliases</TT
|
||||
>, and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addr_list</TT
|
||||
> elements of the <SPAN
|
||||
CLASS="TYPE"
|
||||
>struct
|
||||
hostent</SPAN
|
||||
>. If <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>buf</I
|
||||
></TT
|
||||
> was too small, both
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname_r()</TT
|
||||
> and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyaddr_r()</TT
|
||||
> set the global variable
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>errno</SPAN
|
||||
> to <SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>ERANGE</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN245"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>gethostent</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_getipnode</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_hstrerror</SPAN
|
||||
>(3)</SPAN
|
||||
></P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN257"
|
||||
></A
|
||||
><H2
|
||||
>BUGS</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname2()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyaddr()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_endhostent()</TT
|
||||
>
|
||||
are not thread safe; they return pointers to static data and
|
||||
provide error codes through a global variable.
|
||||
Thread-safe versions for name and address lookup are provided by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyname_r()</TT
|
||||
>,
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gethostbyaddr_r()</TT
|
||||
>
|
||||
respectively.</P
|
||||
><P
|
||||
>The resolver daemon does not currently support any non-DNS
|
||||
name services such as
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
>/etc/hosts</TT
|
||||
>
|
||||
or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NIS</SPAN
|
||||
>,
|
||||
consequently the above functions don't, either.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,187 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_GETIPNODE" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent \- lightweight resolver nodename / address translation API
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/netdb.h>
|
||||
.sp
|
||||
.na
|
||||
struct hostent *
|
||||
lwres_getipnodebyname(const char *name, int af, int flags, int *error_num);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
struct hostent *
|
||||
lwres_getipnodebyaddr(const void *src, size_t len, int af, int *error_num);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_freehostent(struct hostent *he);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
These functions perform thread safe, protocol independent
|
||||
nodename-to-address and address-to-nodename
|
||||
translation as defined in RFC2553.
|
||||
.PP
|
||||
They use a
|
||||
\fBstruct hostent\fR
|
||||
which is defined in
|
||||
\fInamedb.h\fR:
|
||||
.sp
|
||||
.nf
|
||||
struct hostent {
|
||||
char *h_name; /* official name of host */
|
||||
char **h_aliases; /* alias list */
|
||||
int h_addrtype; /* host address type */
|
||||
int h_length; /* length of address */
|
||||
char **h_addr_list; /* list of addresses from name server */
|
||||
};
|
||||
#define h_addr h_addr_list[0] /* address, for backward compatibility */
|
||||
.sp
|
||||
.fi
|
||||
.PP
|
||||
The members of this structure are:
|
||||
.TP
|
||||
\fBh_name\fR
|
||||
The official (canonical) name of the host.
|
||||
.TP
|
||||
\fBh_aliases\fR
|
||||
A NULL-terminated array of alternate names (nicknames) for the host.
|
||||
.TP
|
||||
\fBh_addrtype\fR
|
||||
The type of address being returned - usually
|
||||
\fBPF_INET\fR
|
||||
or
|
||||
\fBPF_INET6\fR.
|
||||
.TP
|
||||
\fBh_length\fR
|
||||
The length of the address in bytes.
|
||||
.TP
|
||||
\fBh_addr_list\fR
|
||||
A
|
||||
\fBNULL\fR
|
||||
terminated array of network addresses for the host.
|
||||
Host addresses are returned in network byte order.
|
||||
.PP
|
||||
\fBlwres_getipnodebyname()\fR
|
||||
looks up addresses of protocol family
|
||||
\fIaf\fR
|
||||
for the hostname
|
||||
\fIname\fR.
|
||||
The
|
||||
\fIflags\fR
|
||||
parameter contains ORed flag bits to
|
||||
specify the types of addresses that are searched
|
||||
for, and the types of addresses that are returned.
|
||||
The flag bits are:
|
||||
.TP
|
||||
\fBAI_V4MAPPED\fR
|
||||
This is used with an
|
||||
\fIaf\fR
|
||||
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
|
||||
IPv6 addresses.
|
||||
.TP
|
||||
\fBAI_ALL\fR
|
||||
This is used with an
|
||||
\fIaf\fR
|
||||
of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
|
||||
If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
|
||||
IPv6 addresses.
|
||||
.TP
|
||||
\fBAI_ADDRCONFIG\fR
|
||||
Only return an IPv6 or IPv4 address if here is an active network
|
||||
interface of that type. This is not currently implemented
|
||||
in the BIND 9 lightweight resolver, and the flag is ignored.
|
||||
.TP
|
||||
\fBAI_DEFAULT\fR
|
||||
This default sets the
|
||||
AI_V4MAPPED
|
||||
and
|
||||
AI_ADDRCONFIG
|
||||
flag bits.
|
||||
.PP
|
||||
\fBlwres_getipnodebyaddr()\fR
|
||||
performs a reverse lookup
|
||||
of address
|
||||
\fIsrc\fR
|
||||
which is
|
||||
\fIlen\fR
|
||||
bytes long.
|
||||
\fIaf\fR
|
||||
denotes the protocol family, typically
|
||||
\fBPF_INET\fR
|
||||
or
|
||||
\fBPF_INET6\fR.
|
||||
.PP
|
||||
\fBlwres_freehostent()\fR
|
||||
releases all the memory associated with
|
||||
the
|
||||
\fBstruct hostent\fR
|
||||
pointer
|
||||
\fIhe\fR.
|
||||
Any memory allocated for the
|
||||
h_name,
|
||||
h_addr_list
|
||||
and
|
||||
h_aliases
|
||||
is freed, as is the memory for the
|
||||
\fBhostent\fR
|
||||
structure itself.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
If an error occurs,
|
||||
\fBlwres_getipnodebyname()\fR
|
||||
and
|
||||
\fBlwres_getipnodebyaddr()\fR
|
||||
set
|
||||
\fI*error_num\fR
|
||||
to an approriate error code and the function returns a
|
||||
\fBNULL\fR
|
||||
pointer.
|
||||
The error codes and their meanings are defined in
|
||||
\fI<lwres/netdb.h>\fR:
|
||||
.TP
|
||||
\fBHOST_NOT_FOUND\fR
|
||||
No such host is known.
|
||||
.TP
|
||||
\fBNO_ADDRESS\fR
|
||||
The server recognised the request and the name but no address is
|
||||
available. Another type of request to the name server for the
|
||||
domain might return an answer.
|
||||
.TP
|
||||
\fBTRY_AGAIN\fR
|
||||
A temporary and possibly transient error occurred, such as a
|
||||
failure of a server to respond. The request may succeed if
|
||||
retried.
|
||||
.TP
|
||||
\fBNO_RECOVERY\fR
|
||||
An unexpected failure occurred, and retrying the request
|
||||
is pointless.
|
||||
.PP
|
||||
\fBlwres_hstrerror\fR(3)
|
||||
translates these error codes to suitable error messages.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBRFC2553\fR,
|
||||
\fBlwres\fR(3),
|
||||
\fBlwres_gethostent\fR(3),
|
||||
\fBlwres_getaddrinfo\fR(3),
|
||||
\fBlwres_getnameinfo\fR(3),
|
||||
\fBlwres_hstrerror\fR(3).
|
||||
@@ -0,0 +1,307 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_getipnode.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_getipnode</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_getipnodebyname</refname>
|
||||
<refname>lwres_getipnodebyaddr</refname>
|
||||
<refname>lwres_freehostent</refname>
|
||||
<refpurpose>lightweight resolver nodename / address translation API</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
struct hostent *
|
||||
<function>lwres_getipnodebyname</function></funcdef>
|
||||
<paramdef>const char *name</paramdef>
|
||||
<paramdef>int af</paramdef>
|
||||
<paramdef>int flags</paramdef>
|
||||
<paramdef>int *error_num</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
struct hostent *
|
||||
<function>lwres_getipnodebyaddr</function></funcdef>
|
||||
<paramdef>const void *src</paramdef>
|
||||
<paramdef>size_t len</paramdef>
|
||||
<paramdef>int af</paramdef>
|
||||
<paramdef>int *error_num</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_freehostent</function></funcdef>
|
||||
<paramdef>struct hostent *he</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
|
||||
<para>
|
||||
These functions perform thread safe, protocol independent
|
||||
nodename-to-address and address-to-nodename
|
||||
translation as defined in RFC2553.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
They use a
|
||||
<type>struct hostent</type>
|
||||
which is defined in
|
||||
<filename>namedb.h</filename>:
|
||||
<programlisting>
|
||||
struct hostent {
|
||||
char *h_name; /* official name of host */
|
||||
char **h_aliases; /* alias list */
|
||||
int h_addrtype; /* host address type */
|
||||
int h_length; /* length of address */
|
||||
char **h_addr_list; /* list of addresses from name server */
|
||||
};
|
||||
#define h_addr h_addr_list[0] /* address, for backward compatibility */
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The members of this structure are:
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>h_name</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The official (canonical) name of the host.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>h_aliases</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A NULL-terminated array of alternate names (nicknames) for the host.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>h_addrtype</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The type of address being returned - usually
|
||||
<type>PF_INET</type>
|
||||
or
|
||||
<type>PF_INET6</type>.
|
||||
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>h_length</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The length of the address in bytes.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>h_addr_list</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A
|
||||
<type>NULL</type>
|
||||
terminated array of network addresses for the host.
|
||||
Host addresses are returned in network byte order.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_getipnodebyname()</function>
|
||||
looks up addresses of protocol family
|
||||
<parameter>af</parameter>
|
||||
|
||||
for the hostname
|
||||
<parameter>name</parameter>.
|
||||
|
||||
The
|
||||
<parameter>flags</parameter>
|
||||
parameter contains ORed flag bits to
|
||||
specify the types of addresses that are searched
|
||||
for, and the types of addresses that are returned.
|
||||
The flag bits are:
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>AI_V4MAPPED</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This is used with an
|
||||
<parameter>af</parameter>
|
||||
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
|
||||
IPv6 addresses.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>AI_ALL</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This is used with an
|
||||
<parameter>af</parameter>
|
||||
of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
|
||||
If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
|
||||
IPv6 addresses.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>AI_ADDRCONFIG</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Only return an IPv6 or IPv4 address if here is an active network
|
||||
interface of that type. This is not currently implemented
|
||||
in the BIND 9 lightweight resolver, and the flag is ignored.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>AI_DEFAULT</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
This default sets the
|
||||
<constant>AI_V4MAPPED</constant>
|
||||
and
|
||||
<constant>AI_ADDRCONFIG</constant>
|
||||
flag bits.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_getipnodebyaddr()</function>
|
||||
performs a reverse lookup
|
||||
of address
|
||||
<parameter>src</parameter>
|
||||
which is
|
||||
<parameter>len</parameter>
|
||||
bytes long.
|
||||
<parameter>af</parameter>
|
||||
denotes the protocol family, typically
|
||||
<type>PF_INET</type>
|
||||
or
|
||||
<type>PF_INET6</type>.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_freehostent()</function>
|
||||
releases all the memory associated with
|
||||
the
|
||||
<type>struct hostent</type>
|
||||
pointer
|
||||
<parameter>he</parameter>.
|
||||
|
||||
Any memory allocated for the
|
||||
<constant>h_name</constant>,
|
||||
|
||||
<constant>h_addr_list</constant>
|
||||
and
|
||||
<constant>h_aliases</constant>
|
||||
is freed, as is the memory for the
|
||||
<type>hostent</type>
|
||||
structure itself.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
If an error occurs,
|
||||
<function>lwres_getipnodebyname()</function>
|
||||
and
|
||||
<function>lwres_getipnodebyaddr()</function>
|
||||
set
|
||||
<parameter>*error_num</parameter>
|
||||
to an approriate error code and the function returns a
|
||||
<type>NULL</type>
|
||||
pointer.
|
||||
The error codes and their meanings are defined in
|
||||
<filename><lwres/netdb.h></filename>:
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
No such host is known.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>NO_ADDRESS</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The server recognised the request and the name but no address is
|
||||
available. Another type of request to the name server for the
|
||||
domain might return an answer.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>TRY_AGAIN</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A temporary and possibly transient error occurred, such as a
|
||||
failure of a server to respond. The request may succeed if
|
||||
retried.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
<varlistentry><term><constant>NO_RECOVERY</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
An unexpected failure occurred, and retrying the request
|
||||
is pointless.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
translates these error codes to suitable error messages.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>RFC2553</refentrytitle>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,529 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_getipnode</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_getipnode</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent -- lightweight resolver nodename / address translation API</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN13"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN14"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/netdb.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>struct hostent *
|
||||
lwres_getipnodebyname</CODE
|
||||
>(const char *name, int af, int flags, int *error_num);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>struct hostent *
|
||||
lwres_getipnodebyaddr</CODE
|
||||
>(const void *src, size_t len, int af, int *error_num);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_freehostent</CODE
|
||||
>(struct hostent *he);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN34"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
>These functions perform thread safe, protocol independent
|
||||
nodename-to-address and address-to-nodename
|
||||
translation as defined in RFC2553.</P
|
||||
><P
|
||||
>They use a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct hostent</SPAN
|
||||
>
|
||||
which is defined in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
>namedb.h</TT
|
||||
>:
|
||||
<PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>struct hostent {
|
||||
char *h_name; /* official name of host */
|
||||
char **h_aliases; /* alias list */
|
||||
int h_addrtype; /* host address type */
|
||||
int h_length; /* length of address */
|
||||
char **h_addr_list; /* list of addresses from name server */
|
||||
};
|
||||
#define h_addr h_addr_list[0] /* address, for backward compatibility */</PRE
|
||||
></P
|
||||
><P
|
||||
>The members of this structure are:
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_name</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The official (canonical) name of the host.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_aliases</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>A NULL-terminated array of alternate names (nicknames) for the host.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addrtype</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The type of address being returned - usually
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET</SPAN
|
||||
>
|
||||
or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET6</SPAN
|
||||
>. </P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_length</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The length of the address in bytes.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addr_list</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>A
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
>
|
||||
terminated array of network addresses for the host.
|
||||
Host addresses are returned in network byte order.</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getipnodebyname()</TT
|
||||
>
|
||||
looks up addresses of protocol family
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>af</I
|
||||
></TT
|
||||
>
|
||||
|
||||
for the hostname
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>name</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
The
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>flags</I
|
||||
></TT
|
||||
>
|
||||
parameter contains ORed flag bits to
|
||||
specify the types of addresses that are searched
|
||||
for, and the types of addresses that are returned.
|
||||
The flag bits are:
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>AI_V4MAPPED</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>This is used with an
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>af</I
|
||||
></TT
|
||||
>
|
||||
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
|
||||
IPv6 addresses.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>AI_ALL</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>This is used with an
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>af</I
|
||||
></TT
|
||||
>
|
||||
of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned.
|
||||
If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped
|
||||
IPv6 addresses.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>AI_ADDRCONFIG</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>Only return an IPv6 or IPv4 address if here is an active network
|
||||
interface of that type. This is not currently implemented
|
||||
in the BIND 9 lightweight resolver, and the flag is ignored.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>AI_DEFAULT</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>This default sets the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>AI_V4MAPPED</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>AI_ADDRCONFIG</TT
|
||||
>
|
||||
flag bits.</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getipnodebyaddr()</TT
|
||||
>
|
||||
performs a reverse lookup
|
||||
of address
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>src</I
|
||||
></TT
|
||||
>
|
||||
which is
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>len</I
|
||||
></TT
|
||||
>
|
||||
bytes long.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>af</I
|
||||
></TT
|
||||
>
|
||||
denotes the protocol family, typically
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET</SPAN
|
||||
>
|
||||
or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>PF_INET6</SPAN
|
||||
>. </P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_freehostent()</TT
|
||||
>
|
||||
releases all the memory associated with
|
||||
the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct hostent</SPAN
|
||||
>
|
||||
pointer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>he</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
Any memory allocated for the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_name</TT
|
||||
>,
|
||||
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_addr_list</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>h_aliases</TT
|
||||
>
|
||||
is freed, as is the memory for the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>hostent</SPAN
|
||||
>
|
||||
structure itself.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN116"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
>If an error occurs,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getipnodebyname()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getipnodebyaddr()</TT
|
||||
>
|
||||
set
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*error_num</I
|
||||
></TT
|
||||
>
|
||||
to an approriate error code and the function returns a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
>
|
||||
pointer.
|
||||
The error codes and their meanings are defined in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
><lwres/netdb.h></TT
|
||||
>:
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>HOST_NOT_FOUND</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>No such host is known.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NO_ADDRESS</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The server recognised the request and the name but no address is
|
||||
available. Another type of request to the name server for the
|
||||
domain might return an answer.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>TRY_AGAIN</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>A temporary and possibly transient error occurred, such as a
|
||||
failure of a server to respond. The request may succeed if
|
||||
retried.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NO_RECOVERY</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>An unexpected failure occurred, and retrying the request
|
||||
is pointless.</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_hstrerror</SPAN
|
||||
>(3)</SPAN
|
||||
>
|
||||
translates these error codes to suitable error messages.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN149"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>RFC2553</SPAN
|
||||
></SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_gethostent</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_getaddrinfo</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_getnameinfo</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_hstrerror</SPAN
|
||||
>(3)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,84 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_GETNAMEINFO" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_getnameinfo \- lightweight resolver socket address structure to hostname and service name
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/netdb.h>
|
||||
.sp
|
||||
.na
|
||||
int
|
||||
lwres_getnameinfo(const struct sockaddr *sa, size_t salen, char *host, size_t hostlen, char *serv, size_t servlen, int flags);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
This function is equivalent to the \fBgetnameinfo\fR(3) function defined in RFC2133.
|
||||
\fBlwres_getnameinfo()\fR returns the hostname for the
|
||||
\fBstruct sockaddr\fR \fIsa\fR which is
|
||||
\fIsalen\fR bytes long. The hostname is of length
|
||||
\fIhostlen\fR and is returned via
|
||||
\fI*host.\fR The maximum length of the hostname is
|
||||
1025 bytes: NI_MAXHOST.
|
||||
.PP
|
||||
The name of the service associated with the port number in
|
||||
\fIsa\fR is returned in \fI*serv.\fR
|
||||
It is \fIservlen\fR bytes long. The maximum length
|
||||
of the service name is NI_MAXSERV - 32 bytes.
|
||||
.PP
|
||||
The \fIflags\fR argument sets the following
|
||||
bits:
|
||||
.TP
|
||||
\fBNI_NOFQDN\fR
|
||||
A fully qualified domain name is not required for local hosts.
|
||||
The local part of the fully qualified domain name is returned instead.
|
||||
.TP
|
||||
\fBNI_NUMERICHOST\fR
|
||||
Return the address in numeric form, as if calling inet_ntop(),
|
||||
instead of a host name.
|
||||
.TP
|
||||
\fBNI_NAMEREQD\fR
|
||||
A name is required. If the hostname cannot be found in the DNS and
|
||||
this flag is set, a non-zero error code is returned.
|
||||
If the hostname is not found and the flag is not set, the
|
||||
address is returned in numeric form.
|
||||
.TP
|
||||
\fBNI_NUMERICSERV\fR
|
||||
The service name is returned as a digit string representing the port number.
|
||||
.TP
|
||||
\fBNI_DGRAM\fR
|
||||
Specifies that the service being looked up is a datagram
|
||||
service, and causes getservbyport() to be called with a second
|
||||
argument of "udp" instead of its default of "tcp". This is required
|
||||
for the few ports (512-514) that have different services for UDP and
|
||||
TCP.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
\fBlwres_getnameinfo()\fR
|
||||
returns 0 on success or a non-zero error code if an error occurs.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBRFC2133\fR,
|
||||
\fBgetservbyport\fR(3),
|
||||
\fBlwres\fR(3),
|
||||
\fBlwres_getnameinfo\fR(3),
|
||||
\fBlwres_getnamebyaddr\fR(3).
|
||||
\fBlwres_net_ntop\fR(3).
|
||||
.SH "BUGS"
|
||||
.PP
|
||||
RFC2133 fails to define what the nonzero return values of
|
||||
\fBgetnameinfo\fR(3)
|
||||
are.
|
||||
@@ -0,0 +1,154 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_getnameinfo.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_getnameinfo</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_getnameinfo</refname>
|
||||
<refpurpose>lightweight resolver socket address structure to hostname and service name</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
int
|
||||
<function>lwres_getnameinfo</function></funcdef>
|
||||
<paramdef>const struct sockaddr *sa</paramdef>
|
||||
<paramdef>size_t salen</paramdef>
|
||||
<paramdef>char *host</paramdef>
|
||||
<paramdef>size_t hostlen</paramdef>
|
||||
<paramdef>char *serv</paramdef>
|
||||
<paramdef>size_t servlen</paramdef>
|
||||
<paramdef>int flags</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
|
||||
<para> This function is equivalent to the <citerefentry>
|
||||
<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry> function defined in RFC2133.
|
||||
<function>lwres_getnameinfo()</function> returns the hostname for the
|
||||
<type>struct sockaddr</type> <parameter>sa</parameter> which is
|
||||
<parameter>salen</parameter> bytes long. The hostname is of length
|
||||
<parameter>hostlen</parameter> and is returned via
|
||||
<parameter>*host.</parameter> The maximum length of the hostname is
|
||||
1025 bytes: <constant>NI_MAXHOST</constant>.</para>
|
||||
|
||||
<para> The name of the service associated with the port number in
|
||||
<parameter>sa</parameter> is returned in <parameter>*serv.</parameter>
|
||||
It is <parameter>servlen</parameter> bytes long. The maximum length
|
||||
of the service name is <constant>NI_MAXSERV</constant> - 32 bytes.
|
||||
</para>
|
||||
|
||||
<para> The <parameter>flags</parameter> argument sets the following
|
||||
bits:
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>NI_NOFQDN</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A fully qualified domain name is not required for local hosts.
|
||||
The local part of the fully qualified domain name is returned instead.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>NI_NUMERICHOST</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Return the address in numeric form, as if calling inet_ntop(),
|
||||
instead of a host name.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>NI_NAMEREQD</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
A name is required. If the hostname cannot be found in the DNS and
|
||||
this flag is set, a non-zero error code is returned.
|
||||
If the hostname is not found and the flag is not set, the
|
||||
address is returned in numeric form.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>NI_NUMERICSERV</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
The service name is returned as a digit string representing the port number.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>NI_DGRAM</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Specifies that the service being looked up is a datagram
|
||||
service, and causes getservbyport() to be called with a second
|
||||
argument of "udp" instead of its default of "tcp". This is required
|
||||
for the few ports (512-514) that have different services for UDP and
|
||||
TCP.
|
||||
</para></listitem></varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
<function>lwres_getnameinfo()</function>
|
||||
returns 0 on success or a non-zero error code if an error occurs.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>RFC2133</refentrytitle>
|
||||
</citerefentry>,
|
||||
<citerefentry>
|
||||
<refentrytitle>getservbyport</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_getnamebyaddr</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>.
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_net_ntop</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>.
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>BUGS</title>
|
||||
<para>
|
||||
RFC2133 fails to define what the nonzero return values of
|
||||
<citerefentry>
|
||||
<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>
|
||||
are.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,303 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_getnameinfo</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_getnameinfo</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_getnameinfo -- lightweight resolver socket address structure to hostname and service name</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN11"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN12"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/netdb.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>int
|
||||
lwres_getnameinfo</CODE
|
||||
>(const struct sockaddr *sa, size_t salen, char *host, size_t hostlen, char *serv, size_t servlen, int flags);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN24"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
> This function is equivalent to the <SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>getnameinfo</SPAN
|
||||
>(3)</SPAN
|
||||
> function defined in RFC2133.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getnameinfo()</TT
|
||||
> returns the hostname for the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct sockaddr</SPAN
|
||||
> <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>sa</I
|
||||
></TT
|
||||
> which is
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>salen</I
|
||||
></TT
|
||||
> bytes long. The hostname is of length
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hostlen</I
|
||||
></TT
|
||||
> and is returned via
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*host.</I
|
||||
></TT
|
||||
> The maximum length of the hostname is
|
||||
1025 bytes: <TT
|
||||
CLASS="CONSTANT"
|
||||
>NI_MAXHOST</TT
|
||||
>.</P
|
||||
><P
|
||||
> The name of the service associated with the port number in
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>sa</I
|
||||
></TT
|
||||
> is returned in <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*serv.</I
|
||||
></TT
|
||||
>
|
||||
It is <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>servlen</I
|
||||
></TT
|
||||
> bytes long. The maximum length
|
||||
of the service name is <TT
|
||||
CLASS="CONSTANT"
|
||||
>NI_MAXSERV</TT
|
||||
> - 32 bytes.</P
|
||||
><P
|
||||
> The <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>flags</I
|
||||
></TT
|
||||
> argument sets the following
|
||||
bits:
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NI_NOFQDN</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>A fully qualified domain name is not required for local hosts.
|
||||
The local part of the fully qualified domain name is returned instead.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NI_NUMERICHOST</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>Return the address in numeric form, as if calling inet_ntop(),
|
||||
instead of a host name.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NI_NAMEREQD</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>A name is required. If the hostname cannot be found in the DNS and
|
||||
this flag is set, a non-zero error code is returned.
|
||||
If the hostname is not found and the flag is not set, the
|
||||
address is returned in numeric form.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NI_NUMERICSERV</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>The service name is returned as a digit string representing the port number.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NI_DGRAM</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>Specifies that the service being looked up is a datagram
|
||||
service, and causes getservbyport() to be called with a second
|
||||
argument of "udp" instead of its default of "tcp". This is required
|
||||
for the few ports (512-514) that have different services for UDP and
|
||||
TCP.</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN70"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getnameinfo()</TT
|
||||
>
|
||||
returns 0 on success or a non-zero error code if an error occurs.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN74"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>RFC2133</SPAN
|
||||
></SPAN
|
||||
>,
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>getservbyport</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_getnameinfo</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_getnamebyaddr</SPAN
|
||||
>(3)</SPAN
|
||||
>.
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_net_ntop</SPAN
|
||||
>(3)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN94"
|
||||
></A
|
||||
><H2
|
||||
>BUGS</H2
|
||||
><P
|
||||
>RFC2133 fails to define what the nonzero return values of
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>getnameinfo</SPAN
|
||||
>(3)</SPAN
|
||||
>
|
||||
are.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,142 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_GETRRSETBYNAME" "3" "Oct 18, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_getrrsetbyname, lwres_freerrset \- retrieve DNS records
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/netdb.h>
|
||||
.sp
|
||||
.na
|
||||
int
|
||||
lwres_getrrsetbyname(const char *hostname, unsigned int rdclass, unsigned int rdtype, unsigned int flags, struct rrsetinfo **res);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_freerrset(struct rrsetinfo *rrset);
|
||||
.ad
|
||||
\fR.PP
|
||||
The following structures are used:
|
||||
.sp
|
||||
.nf
|
||||
struct rdatainfo {
|
||||
unsigned int rdi_length; /* length of data */
|
||||
unsigned char *rdi_data; /* record data */
|
||||
};
|
||||
|
||||
struct rrsetinfo {
|
||||
unsigned int rri_flags; /* RRSET_VALIDATED... */
|
||||
unsigned int rri_rdclass; /* class number */
|
||||
unsigned int rri_rdtype; /* RR type number */
|
||||
unsigned int rri_ttl; /* time to live */
|
||||
unsigned int rri_nrdatas; /* size of rdatas array */
|
||||
unsigned int rri_nsigs; /* size of sigs array */
|
||||
char *rri_name; /* canonical name */
|
||||
struct rdatainfo *rri_rdatas; /* individual records */
|
||||
struct rdatainfo *rri_sigs; /* individual signatures */
|
||||
};
|
||||
.sp
|
||||
.fi
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBlwres_getrrsetbyname()\fR
|
||||
gets a set of resource records associated with a
|
||||
\fIhostname\fR,
|
||||
\fIclass\fR,
|
||||
and
|
||||
\fItype\fR.
|
||||
\fIhostname\fR
|
||||
is
|
||||
a pointer a to null-terminated string. The
|
||||
\fIflags\fR
|
||||
field is currently unused and must be zero.
|
||||
.PP
|
||||
After a successful call to
|
||||
\fBlwres_getrrsetbyname()\fR,
|
||||
\fI*res\fR
|
||||
is a pointer to an
|
||||
\fBrrsetinfo\fR
|
||||
structure, containing a list of one or more
|
||||
\fBrdatainfo\fR
|
||||
structures containing resource records and potentially another list of
|
||||
\fBrdatainfo\fR
|
||||
structures containing SIG resource records
|
||||
associated with those records.
|
||||
The members
|
||||
rri_rdclass
|
||||
and
|
||||
rri_rdtype
|
||||
are copied from the parameters.
|
||||
rri_ttl
|
||||
and
|
||||
rri_name
|
||||
are properties of the obtained rrset.
|
||||
The resource records contained in
|
||||
rri_rdatas
|
||||
and
|
||||
rri_sigs
|
||||
are in uncompressed DNS wire format.
|
||||
Properties of the rdataset are represented in the
|
||||
rri_flags
|
||||
bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC
|
||||
validated and the signatures verified.
|
||||
.PP
|
||||
All of the information returned by
|
||||
\fBlwres_getrrsetbyname()\fR
|
||||
is dynamically allocated: the
|
||||
rrsetinfo
|
||||
and
|
||||
rdatainfo
|
||||
structures,
|
||||
and the canonical host name strings pointed to by the
|
||||
rrsetinfostructure.
|
||||
Memory allocated for the dynamically allocated structures created by
|
||||
a successful call to
|
||||
\fBlwres_getrrsetbyname()\fR
|
||||
is released by
|
||||
\fBlwres_freerrset()\fR.
|
||||
\fIrrset\fR
|
||||
is a pointer to a
|
||||
\fBstruct rrset\fR
|
||||
created by a call to
|
||||
\fBlwres_getrrsetbyname()\fR.
|
||||
.PP
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
\fBlwres_getrrsetbyname()\fR
|
||||
returns zero on success, and one of the following error
|
||||
codes if an error occurred:
|
||||
.TP
|
||||
\fBERRSET_NONAME\fR
|
||||
the name does not exist
|
||||
.TP
|
||||
\fBERRSET_NODATA\fR
|
||||
the name exists, but does not have data of the desired type
|
||||
.TP
|
||||
\fBERRSET_NOMEMORY\fR
|
||||
memory could not be allocated
|
||||
.TP
|
||||
\fBERRSET_INVAL\fR
|
||||
a parameter is invalid
|
||||
.TP
|
||||
\fBERRSET_FAIL\fR
|
||||
other failure
|
||||
.TP
|
||||
\fB\fR
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBlwres\fR(3).
|
||||
@@ -0,0 +1,208 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_getrrsetbyname.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
<refentryinfo>
|
||||
|
||||
|
||||
<date>Oct 18, 2000</date>
|
||||
</refentryinfo>
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_getrrsetbyname</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>lwres_getrrsetbyname</refname>
|
||||
<refname>lwres_freerrset</refname>
|
||||
<refpurpose>retrieve DNS records</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
int
|
||||
<function>lwres_getrrsetbyname</function></funcdef>
|
||||
<paramdef>const char *hostname</paramdef>
|
||||
<paramdef>unsigned int rdclass</paramdef>
|
||||
<paramdef>unsigned int rdtype</paramdef>
|
||||
<paramdef>unsigned int flags</paramdef>
|
||||
<paramdef>struct rrsetinfo **res</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_freerrset</function></funcdef>
|
||||
<paramdef>struct rrsetinfo *rrset</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
<para>
|
||||
The following structures are used:
|
||||
<programlisting>
|
||||
struct rdatainfo {
|
||||
unsigned int rdi_length; /* length of data */
|
||||
unsigned char *rdi_data; /* record data */
|
||||
};
|
||||
|
||||
struct rrsetinfo {
|
||||
unsigned int rri_flags; /* RRSET_VALIDATED... */
|
||||
unsigned int rri_rdclass; /* class number */
|
||||
unsigned int rri_rdtype; /* RR type number */
|
||||
unsigned int rri_ttl; /* time to live */
|
||||
unsigned int rri_nrdatas; /* size of rdatas array */
|
||||
unsigned int rri_nsigs; /* size of sigs array */
|
||||
char *rri_name; /* canonical name */
|
||||
struct rdatainfo *rri_rdatas; /* individual records */
|
||||
struct rdatainfo *rri_sigs; /* individual signatures */
|
||||
};
|
||||
</programlisting>
|
||||
</para>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
<function>lwres_getrrsetbyname()</function>
|
||||
gets a set of resource records associated with a
|
||||
<parameter>hostname</parameter>,
|
||||
|
||||
<parameter>class</parameter>,
|
||||
|
||||
and
|
||||
<parameter>type</parameter>.
|
||||
|
||||
<parameter>hostname</parameter>
|
||||
is
|
||||
a pointer a to null-terminated string. The
|
||||
<parameter>flags</parameter>
|
||||
field is currently unused and must be zero.
|
||||
</para>
|
||||
<para>
|
||||
After a successful call to
|
||||
<function>lwres_getrrsetbyname()</function>,
|
||||
|
||||
<parameter>*res</parameter>
|
||||
is a pointer to an
|
||||
<type>rrsetinfo</type>
|
||||
structure, containing a list of one or more
|
||||
<type>rdatainfo</type>
|
||||
structures containing resource records and potentially another list of
|
||||
<type>rdatainfo</type>
|
||||
structures containing SIG resource records
|
||||
associated with those records.
|
||||
The members
|
||||
<constant>rri_rdclass</constant>
|
||||
and
|
||||
<constant>rri_rdtype</constant>
|
||||
are copied from the parameters.
|
||||
<constant>rri_ttl</constant>
|
||||
and
|
||||
<constant>rri_name</constant>
|
||||
are properties of the obtained rrset.
|
||||
The resource records contained in
|
||||
<constant>rri_rdatas</constant>
|
||||
and
|
||||
<constant>rri_sigs</constant>
|
||||
are in uncompressed DNS wire format.
|
||||
Properties of the rdataset are represented in the
|
||||
<constant>rri_flags</constant>
|
||||
bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC
|
||||
validated and the signatures verified.
|
||||
</para>
|
||||
<para>
|
||||
All of the information returned by
|
||||
<function>lwres_getrrsetbyname()</function>
|
||||
is dynamically allocated: the
|
||||
<constant>rrsetinfo</constant>
|
||||
and
|
||||
<constant>rdatainfo</constant>
|
||||
structures,
|
||||
and the canonical host name strings pointed to by the
|
||||
<constant>rrsetinfo</constant>structure.
|
||||
|
||||
Memory allocated for the dynamically allocated structures created by
|
||||
a successful call to
|
||||
<function>lwres_getrrsetbyname()</function>
|
||||
is released by
|
||||
<function>lwres_freerrset()</function>.
|
||||
|
||||
<parameter>rrset</parameter>
|
||||
is a pointer to a
|
||||
<type>struct rrset</type>
|
||||
created by a call to
|
||||
<function>lwres_getrrsetbyname()</function>.
|
||||
|
||||
</para>
|
||||
<para>
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
<function>lwres_getrrsetbyname()</function>
|
||||
returns zero on success, and one of the following error
|
||||
codes if an error occurred:
|
||||
<variablelist>
|
||||
|
||||
<varlistentry><term><constant>ERRSET_NONAME</constant></term>
|
||||
<listitem><para>
|
||||
the name does not exist
|
||||
</para></listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><constant>ERRSET_NODATA</constant></term>
|
||||
<listitem><para>
|
||||
the name exists, but does not have data of the desired type
|
||||
</para></listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><constant>ERRSET_NOMEMORY</constant></term>
|
||||
<listitem><para>
|
||||
memory could not be allocated
|
||||
</para></listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><constant>ERRSET_INVAL</constant></term>
|
||||
<listitem><para>
|
||||
a parameter is invalid
|
||||
</para></listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><constant>ERRSET_FAIL</constant></term>
|
||||
<listitem><para>
|
||||
other failure
|
||||
</para></listitem></varlistentry>
|
||||
|
||||
<varlistentry><term><constant></constant></term>
|
||||
<listitem><para>
|
||||
</para></listitem></varlistentry>
|
||||
|
||||
</variablelist>
|
||||
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,371 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_getrrsetbyname</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_getrrsetbyname</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_getrrsetbyname, lwres_freerrset -- retrieve DNS records</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN12"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN13"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/netdb.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>int
|
||||
lwres_getrrsetbyname</CODE
|
||||
>(const char *hostname, unsigned int rdclass, unsigned int rdtype, unsigned int flags, struct rrsetinfo **res);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_freerrset</CODE
|
||||
>(struct rrsetinfo *rrset);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
><P
|
||||
>The following structures are used:
|
||||
<PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>struct rdatainfo {
|
||||
unsigned int rdi_length; /* length of data */
|
||||
unsigned char *rdi_data; /* record data */
|
||||
};
|
||||
|
||||
struct rrsetinfo {
|
||||
unsigned int rri_flags; /* RRSET_VALIDATED... */
|
||||
unsigned int rri_rdclass; /* class number */
|
||||
unsigned int rri_rdtype; /* RR type number */
|
||||
unsigned int rri_ttl; /* time to live */
|
||||
unsigned int rri_nrdatas; /* size of rdatas array */
|
||||
unsigned int rri_nsigs; /* size of sigs array */
|
||||
char *rri_name; /* canonical name */
|
||||
struct rdatainfo *rri_rdatas; /* individual records */
|
||||
struct rdatainfo *rri_sigs; /* individual signatures */
|
||||
};</PRE
|
||||
></P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN29"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getrrsetbyname()</TT
|
||||
>
|
||||
gets a set of resource records associated with a
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hostname</I
|
||||
></TT
|
||||
>,
|
||||
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>class</I
|
||||
></TT
|
||||
>,
|
||||
|
||||
and
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>type</I
|
||||
></TT
|
||||
>.
|
||||
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>hostname</I
|
||||
></TT
|
||||
>
|
||||
is
|
||||
a pointer a to null-terminated string. The
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>flags</I
|
||||
></TT
|
||||
>
|
||||
field is currently unused and must be zero.</P
|
||||
><P
|
||||
>After a successful call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getrrsetbyname()</TT
|
||||
>,
|
||||
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*res</I
|
||||
></TT
|
||||
>
|
||||
is a pointer to an
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>rrsetinfo</SPAN
|
||||
>
|
||||
structure, containing a list of one or more
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>rdatainfo</SPAN
|
||||
>
|
||||
structures containing resource records and potentially another list of
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>rdatainfo</SPAN
|
||||
>
|
||||
structures containing SIG resource records
|
||||
associated with those records.
|
||||
The members
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rri_rdclass</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rri_rdtype</TT
|
||||
>
|
||||
are copied from the parameters.
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rri_ttl</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rri_name</TT
|
||||
>
|
||||
are properties of the obtained rrset.
|
||||
The resource records contained in
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rri_rdatas</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rri_sigs</TT
|
||||
>
|
||||
are in uncompressed DNS wire format.
|
||||
Properties of the rdataset are represented in the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rri_flags</TT
|
||||
>
|
||||
bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC
|
||||
validated and the signatures verified. </P
|
||||
><P
|
||||
>All of the information returned by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getrrsetbyname()</TT
|
||||
>
|
||||
is dynamically allocated: the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rrsetinfo</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rdatainfo</TT
|
||||
>
|
||||
structures,
|
||||
and the canonical host name strings pointed to by the
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>rrsetinfo</TT
|
||||
>structure.
|
||||
|
||||
Memory allocated for the dynamically allocated structures created by
|
||||
a successful call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getrrsetbyname()</TT
|
||||
>
|
||||
is released by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_freerrset()</TT
|
||||
>.
|
||||
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>rrset</I
|
||||
></TT
|
||||
>
|
||||
is a pointer to a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct rrset</SPAN
|
||||
>
|
||||
created by a call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getrrsetbyname()</TT
|
||||
>. </P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN62"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getrrsetbyname()</TT
|
||||
>
|
||||
returns zero on success, and one of the following error
|
||||
codes if an error occurred:
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ERRSET_NONAME</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>the name does not exist</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ERRSET_NODATA</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>the name exists, but does not have data of the desired type</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ERRSET_NOMEMORY</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>memory could not be allocated</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ERRSET_INVAL</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>a parameter is invalid</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>ERRSET_FAIL</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>other failure</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
></TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
></P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
> </P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN97"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres</SPAN
|
||||
>(3)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,186 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_GNBA" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free \- lightweight resolver getnamebyaddress message handling
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/lwres.h>
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_gnbarequest_render(lwres_context_t *\fIctx\fB, lwres_gnbarequest_t *\fIreq\fB, lwres_lwpacket_t *\fIpkt\fB, lwres_buffer_t *\fIb\fB);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbaresponse_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
These are low-level routines for creating and parsing
|
||||
lightweight resolver address-to-name lookup request and
|
||||
response messages.
|
||||
.PP
|
||||
There are four main functions for the getnamebyaddr opcode.
|
||||
One render function converts a getnamebyaddr request structure \(em
|
||||
\fBlwres_gnbarequest_t\fR \(em
|
||||
to the lightweight resolver's canonical format.
|
||||
It is complemented by a parse function that converts a packet in this
|
||||
canonical format to a getnamebyaddr request structure.
|
||||
Another render function converts the getnamebyaddr response structure \(em
|
||||
\fBlwres_gnbaresponse_t\fR
|
||||
to the canonical format.
|
||||
This is complemented by a parse function which converts a packet in
|
||||
canonical format to a getnamebyaddr response structure.
|
||||
.PP
|
||||
These structures are defined in
|
||||
\fIlwres/lwres.h\fR.
|
||||
They are shown below.
|
||||
.sp
|
||||
.nf
|
||||
#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_addr_t addr;
|
||||
} lwres_gnbarequest_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint16_t naliases;
|
||||
char *realname;
|
||||
char **aliases;
|
||||
lwres_uint16_t realnamelen;
|
||||
lwres_uint16_t *aliaslen;
|
||||
void *base;
|
||||
size_t baselen;
|
||||
} lwres_gnbaresponse_t;
|
||||
.sp
|
||||
.fi
|
||||
.PP
|
||||
\fBlwres_gnbarequest_render()\fR
|
||||
uses resolver context
|
||||
ctx
|
||||
to convert getnamebyaddr request structure
|
||||
req
|
||||
to canonical format.
|
||||
The packet header structure
|
||||
pkt
|
||||
is initialised and transferred to
|
||||
buffer
|
||||
b.
|
||||
The contents of
|
||||
*req
|
||||
are then appended to the buffer in canonical format.
|
||||
\fBlwres_gnbaresponse_render()\fR
|
||||
performs the same task, except it converts a getnamebyaddr response structure
|
||||
\fBlwres_gnbaresponse_t\fR
|
||||
to the lightweight resolver's canonical format.
|
||||
.PP
|
||||
\fBlwres_gnbarequest_parse()\fR
|
||||
uses context
|
||||
ctx
|
||||
to convert the contents of packet
|
||||
pkt
|
||||
to a
|
||||
\fBlwres_gnbarequest_t\fR
|
||||
structure.
|
||||
Buffer
|
||||
b
|
||||
provides space to be used for storing this structure.
|
||||
When the function succeeds, the resulting
|
||||
\fBlwres_gnbarequest_t\fR
|
||||
is made available through
|
||||
*structp.
|
||||
\fBlwres_gnbaresponse_parse()\fR
|
||||
offers the same semantics as
|
||||
\fBlwres_gnbarequest_parse()\fR
|
||||
except it yields a
|
||||
\fBlwres_gnbaresponse_t\fR
|
||||
structure.
|
||||
.PP
|
||||
\fBlwres_gnbaresponse_free()\fR
|
||||
and
|
||||
\fBlwres_gnbarequest_free()\fR
|
||||
release the memory in resolver context
|
||||
ctx
|
||||
that was allocated to the
|
||||
\fBlwres_gnbaresponse_t\fR
|
||||
or
|
||||
\fBlwres_gnbarequest_t\fR
|
||||
structures referenced via
|
||||
structp.
|
||||
Any memory associated with ancillary buffers and strings for those
|
||||
structures is also discarded.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
The getnamebyaddr opcode functions
|
||||
\fBlwres_gnbarequest_render()\fR,
|
||||
\fBlwres_gnbaresponse_render()\fR
|
||||
\fBlwres_gnbarequest_parse()\fR
|
||||
and
|
||||
\fBlwres_gnbaresponse_parse()\fR
|
||||
all return
|
||||
LWRES_R_SUCCESS
|
||||
on success.
|
||||
They return
|
||||
LWRES_R_NOMEMORY
|
||||
if memory allocation fails.
|
||||
LWRES_R_UNEXPECTEDEND
|
||||
is returned if the available space in the buffer
|
||||
b
|
||||
is too small to accommodate the packet header or the
|
||||
\fBlwres_gnbarequest_t\fR
|
||||
and
|
||||
\fBlwres_gnbaresponse_t\fR
|
||||
structures.
|
||||
\fBlwres_gnbarequest_parse()\fR
|
||||
and
|
||||
\fBlwres_gnbaresponse_parse()\fR
|
||||
will return
|
||||
LWRES_R_UNEXPECTEDEND
|
||||
if the buffer is not empty after decoding the received packet.
|
||||
These functions will return
|
||||
LWRES_R_FAILURE
|
||||
if
|
||||
\fBpktflags\fR
|
||||
in the packet header structure
|
||||
\fBlwres_lwpacket_t\fR
|
||||
indicate that the packet is not a response to an earlier query.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBlwres_packet\fR(3).
|
||||
@@ -0,0 +1,259 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_gnba.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_gnba</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_gnbarequest_render</refname>
|
||||
<refname>lwres_gnbaresponse_render</refname>
|
||||
<refname>lwres_gnbarequest_parse</refname>
|
||||
<refname>lwres_gnbaresponse_parse</refname>
|
||||
<refname>lwres_gnbaresponse_free</refname>
|
||||
<refname>lwres_gnbarequest_free</refname>
|
||||
<refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <lwres/lwres.h>
|
||||
</funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_gnbarequest_render</function>
|
||||
</funcdef>
|
||||
<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef>
|
||||
<paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef>
|
||||
<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef>
|
||||
<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_gnbaresponse_render</function>
|
||||
</funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_gnbaresponse_t *req</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_gnbarequest_parse</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_gnbarequest_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_gnbaresponse_parse</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_gnbaresponse_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_gnbaresponse_free</function>
|
||||
</funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_gnbaresponse_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_gnbarequest_free</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_gnbarequest_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
These are low-level routines for creating and parsing
|
||||
lightweight resolver address-to-name lookup request and
|
||||
response messages.
|
||||
</para>
|
||||
<para>
|
||||
There are four main functions for the getnamebyaddr opcode.
|
||||
One render function converts a getnamebyaddr request structure —
|
||||
<type>lwres_gnbarequest_t</type> —
|
||||
to the lightweight resolver's canonical format.
|
||||
It is complemented by a parse function that converts a packet in this
|
||||
canonical format to a getnamebyaddr request structure.
|
||||
Another render function converts the getnamebyaddr response structure —
|
||||
<type>lwres_gnbaresponse_t</type>
|
||||
to the canonical format.
|
||||
This is complemented by a parse function which converts a packet in
|
||||
canonical format to a getnamebyaddr response structure.
|
||||
</para>
|
||||
<para>
|
||||
These structures are defined in
|
||||
<filename>lwres/lwres.h</filename>.
|
||||
They are shown below.
|
||||
<programlisting>
|
||||
#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_addr_t addr;
|
||||
} lwres_gnbarequest_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint16_t naliases;
|
||||
char *realname;
|
||||
char **aliases;
|
||||
lwres_uint16_t realnamelen;
|
||||
lwres_uint16_t *aliaslen;
|
||||
void *base;
|
||||
size_t baselen;
|
||||
} lwres_gnbaresponse_t;
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_gnbarequest_render()</function>
|
||||
uses resolver context
|
||||
<varname>ctx</varname>
|
||||
to convert getnamebyaddr request structure
|
||||
<varname>req</varname>
|
||||
to canonical format.
|
||||
The packet header structure
|
||||
<varname>pkt</varname>
|
||||
is initialised and transferred to
|
||||
buffer
|
||||
<varname>b</varname>.
|
||||
The contents of
|
||||
<varname>*req</varname>
|
||||
are then appended to the buffer in canonical format.
|
||||
<function>lwres_gnbaresponse_render()</function>
|
||||
performs the same task, except it converts a getnamebyaddr response structure
|
||||
<type>lwres_gnbaresponse_t</type>
|
||||
to the lightweight resolver's canonical format.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_gnbarequest_parse()</function>
|
||||
uses context
|
||||
<varname>ctx</varname>
|
||||
to convert the contents of packet
|
||||
<varname>pkt</varname>
|
||||
to a
|
||||
<type>lwres_gnbarequest_t</type>
|
||||
structure.
|
||||
Buffer
|
||||
<varname>b</varname>
|
||||
provides space to be used for storing this structure.
|
||||
When the function succeeds, the resulting
|
||||
<type>lwres_gnbarequest_t</type>
|
||||
is made available through
|
||||
<varname>*structp</varname>.
|
||||
<function>lwres_gnbaresponse_parse()</function>
|
||||
offers the same semantics as
|
||||
<function>lwres_gnbarequest_parse()</function>
|
||||
except it yields a
|
||||
<type>lwres_gnbaresponse_t</type>
|
||||
structure.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_gnbaresponse_free()</function>
|
||||
and
|
||||
<function>lwres_gnbarequest_free()</function>
|
||||
release the memory in resolver context
|
||||
<varname>ctx</varname>
|
||||
that was allocated to the
|
||||
<type>lwres_gnbaresponse_t</type>
|
||||
or
|
||||
<type>lwres_gnbarequest_t</type>
|
||||
structures referenced via
|
||||
<varname>structp</varname>.
|
||||
Any memory associated with ancillary buffers and strings for those
|
||||
structures is also discarded.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
The getnamebyaddr opcode functions
|
||||
<function>lwres_gnbarequest_render()</function>,
|
||||
<function>lwres_gnbaresponse_render()</function>
|
||||
<function>lwres_gnbarequest_parse()</function>
|
||||
and
|
||||
<function>lwres_gnbaresponse_parse()</function>
|
||||
all return
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>
|
||||
on success.
|
||||
They return
|
||||
<errorcode>LWRES_R_NOMEMORY</errorcode>
|
||||
if memory allocation fails.
|
||||
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
|
||||
is returned if the available space in the buffer
|
||||
<varname>b</varname>
|
||||
is too small to accommodate the packet header or the
|
||||
<type>lwres_gnbarequest_t</type>
|
||||
and
|
||||
<type>lwres_gnbaresponse_t</type>
|
||||
structures.
|
||||
<function>lwres_gnbarequest_parse()</function>
|
||||
and
|
||||
<function>lwres_gnbaresponse_parse()</function>
|
||||
will return
|
||||
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
|
||||
if the buffer is not empty after decoding the received packet.
|
||||
These functions will return
|
||||
<errorcode>LWRES_R_FAILURE</errorcode>
|
||||
if
|
||||
<structfield>pktflags</structfield>
|
||||
in the packet header structure
|
||||
<type>lwres_lwpacket_t</type>
|
||||
indicate that the packet is not a response to an earlier query.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_packet</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</citerefentry>.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,408 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_gnba</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_gnba</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free -- lightweight resolver getnamebyaddress message handling</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN16"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN17"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/lwres.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_gnbarequest_render</CODE
|
||||
>(lwres_context_t *ctx, lwres_gnbarequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_gnbaresponse_render</CODE
|
||||
>(lwres_context_t *ctx, lwres_gnbaresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_gnbarequest_parse</CODE
|
||||
>(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_gnbaresponse_parse</CODE
|
||||
>(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbaresponse_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_gnbaresponse_free</CODE
|
||||
>(lwres_context_t *ctx, lwres_gnbaresponse_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_gnbarequest_free</CODE
|
||||
>(lwres_context_t *ctx, lwres_gnbarequest_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN61"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
>These are low-level routines for creating and parsing
|
||||
lightweight resolver address-to-name lookup request and
|
||||
response messages.</P
|
||||
><P
|
||||
>There are four main functions for the getnamebyaddr opcode.
|
||||
One render function converts a getnamebyaddr request structure —
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbarequest_t</SPAN
|
||||
> —
|
||||
to the lightweight resolver's canonical format.
|
||||
It is complemented by a parse function that converts a packet in this
|
||||
canonical format to a getnamebyaddr request structure.
|
||||
Another render function converts the getnamebyaddr response structure —
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbaresponse_t</SPAN
|
||||
>
|
||||
to the canonical format.
|
||||
This is complemented by a parse function which converts a packet in
|
||||
canonical format to a getnamebyaddr response structure.</P
|
||||
><P
|
||||
>These structures are defined in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
>lwres/lwres.h</TT
|
||||
>.
|
||||
They are shown below.
|
||||
<PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_addr_t addr;
|
||||
} lwres_gnbarequest_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint16_t naliases;
|
||||
char *realname;
|
||||
char **aliases;
|
||||
lwres_uint16_t realnamelen;
|
||||
lwres_uint16_t *aliaslen;
|
||||
void *base;
|
||||
size_t baselen;
|
||||
} lwres_gnbaresponse_t;</PRE
|
||||
></P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbarequest_render()</TT
|
||||
>
|
||||
uses resolver context
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>ctx</TT
|
||||
>
|
||||
to convert getnamebyaddr request structure
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>req</TT
|
||||
>
|
||||
to canonical format.
|
||||
The packet header structure
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>pkt</TT
|
||||
>
|
||||
is initialised and transferred to
|
||||
buffer
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>b</TT
|
||||
>.
|
||||
The contents of
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>*req</TT
|
||||
>
|
||||
are then appended to the buffer in canonical format.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbaresponse_render()</TT
|
||||
>
|
||||
performs the same task, except it converts a getnamebyaddr response structure
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbaresponse_t</SPAN
|
||||
>
|
||||
to the lightweight resolver's canonical format.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbarequest_parse()</TT
|
||||
>
|
||||
uses context
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>ctx</TT
|
||||
>
|
||||
to convert the contents of packet
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>pkt</TT
|
||||
>
|
||||
to a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbarequest_t</SPAN
|
||||
>
|
||||
structure.
|
||||
Buffer
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>b</TT
|
||||
>
|
||||
provides space to be used for storing this structure.
|
||||
When the function succeeds, the resulting
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbarequest_t</SPAN
|
||||
>
|
||||
is made available through
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>*structp</TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbaresponse_parse()</TT
|
||||
>
|
||||
offers the same semantics as
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbarequest_parse()</TT
|
||||
>
|
||||
except it yields a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbaresponse_t</SPAN
|
||||
>
|
||||
structure.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbaresponse_free()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbarequest_free()</TT
|
||||
>
|
||||
release the memory in resolver context
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>ctx</TT
|
||||
>
|
||||
that was allocated to the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbaresponse_t</SPAN
|
||||
>
|
||||
or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbarequest_t</SPAN
|
||||
>
|
||||
structures referenced via
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>structp</TT
|
||||
>.
|
||||
Any memory associated with ancillary buffers and strings for those
|
||||
structures is also discarded.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN97"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
>The getnamebyaddr opcode functions
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbarequest_render()</TT
|
||||
>,
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbaresponse_render()</TT
|
||||
>
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbarequest_parse()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbaresponse_parse()</TT
|
||||
>
|
||||
all return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>
|
||||
on success.
|
||||
They return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_NOMEMORY</SPAN
|
||||
>
|
||||
if memory allocation fails.
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_UNEXPECTEDEND</SPAN
|
||||
>
|
||||
is returned if the available space in the buffer
|
||||
<TT
|
||||
CLASS="VARNAME"
|
||||
>b</TT
|
||||
>
|
||||
is too small to accommodate the packet header or the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbarequest_t</SPAN
|
||||
>
|
||||
and
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbaresponse_t</SPAN
|
||||
>
|
||||
structures.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbarequest_parse()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_gnbaresponse_parse()</TT
|
||||
>
|
||||
will return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_UNEXPECTEDEND</SPAN
|
||||
>
|
||||
if the buffer is not empty after decoding the received packet.
|
||||
These functions will return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_FAILURE</SPAN
|
||||
>
|
||||
if
|
||||
<TT
|
||||
CLASS="STRUCTFIELD"
|
||||
><I
|
||||
>pktflags</I
|
||||
></TT
|
||||
>
|
||||
in the packet header structure
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_lwpacket_t</SPAN
|
||||
>
|
||||
indicate that the packet is not a response to an earlier query.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN116"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_packet</SPAN
|
||||
>(3)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,67 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_HSTRERROR" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_herror, lwres_hstrerror \- lightweight resolver error message generation
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/netdb.h>
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_herror(const char *s);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
const char *
|
||||
lwres_hstrerror(int err);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBlwres_herror()\fR prints the string
|
||||
\fIs\fR on \fBstderr\fR followed by the string
|
||||
generated by \fBlwres_hstrerror()\fR for the error code
|
||||
stored in the global variable lwres_h_errno.
|
||||
.PP
|
||||
\fBlwres_hstrerror()\fR returns an appropriate string
|
||||
for the error code gievn by \fIerr\fR. The values of
|
||||
the error codes and messages are as follows:
|
||||
.TP
|
||||
\fBNETDB_SUCCESS\fR
|
||||
\fBResolver Error 0 (no error)\fR
|
||||
.TP
|
||||
\fBHOST_NOT_FOUND\fR
|
||||
\fBUnknown host\fR
|
||||
.TP
|
||||
\fBTRY_AGAIN\fR
|
||||
\fBHost name lookup failure\fR
|
||||
.TP
|
||||
\fBNO_RECOVERY\fR
|
||||
\fBUnknown server error\fR
|
||||
.TP
|
||||
\fBNO_DATA\fR
|
||||
\fBNo address associated with name\fR
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
The string \fBUnknown resolver error\fR is returned by
|
||||
\fBlwres_hstrerror()\fR
|
||||
when the value of
|
||||
lwres_h_errno
|
||||
is not a valid error code.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBherror\fR(3),
|
||||
\fBlwres_hstrerror\fR(3).
|
||||
@@ -0,0 +1,124 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_hstrerror.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_hstrerror</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_herror</refname>
|
||||
<refname>lwres_hstrerror</refname>
|
||||
<refpurpose>lightweight resolver error message generation</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_herror</function></funcdef>
|
||||
<paramdef>const char *s</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
const char *
|
||||
<function>lwres_hstrerror</function></funcdef>
|
||||
<paramdef>int err</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
|
||||
<para>
|
||||
<function>lwres_herror()</function> prints the string
|
||||
<parameter>s</parameter> on <type>stderr</type> followed by the string
|
||||
generated by <function>lwres_hstrerror()</function> for the error code
|
||||
stored in the global variable <constant>lwres_h_errno</constant>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_hstrerror()</function> returns an appropriate string
|
||||
for the error code gievn by <parameter>err</parameter>. The values of
|
||||
the error codes and messages are as follows:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry><term><errorcode>NETDB_SUCCESS</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<errorname>Resolver Error 0 (no error)</errorname>
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>HOST_NOT_FOUND</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<errorname>Unknown host</errorname>
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>TRY_AGAIN</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<errorname>Host name lookup failure</errorname>
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>NO_RECOVERY</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<errorname>Unknown server error</errorname>
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><errorcode>NO_DATA</errorcode></term>
|
||||
<listitem>
|
||||
<para>
|
||||
<errorname>No address associated with name</errorname>
|
||||
</para></listitem></varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
The string <errorname>Unknown resolver error</errorname> is returned by
|
||||
<function>lwres_hstrerror()</function>
|
||||
when the value of
|
||||
<constant>lwres_h_errno</constant>
|
||||
is not a valid error code.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>herror</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,242 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_hstrerror</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_hstrerror</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_herror, lwres_hstrerror -- lightweight resolver error message generation</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN12"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN13"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/netdb.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_herror</CODE
|
||||
>(const char *s);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>const char *
|
||||
lwres_hstrerror</CODE
|
||||
>(int err);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN23"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_herror()</TT
|
||||
> prints the string
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>s</I
|
||||
></TT
|
||||
> on <SPAN
|
||||
CLASS="TYPE"
|
||||
>stderr</SPAN
|
||||
> followed by the string
|
||||
generated by <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_hstrerror()</TT
|
||||
> for the error code
|
||||
stored in the global variable <TT
|
||||
CLASS="CONSTANT"
|
||||
>lwres_h_errno</TT
|
||||
>.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_hstrerror()</TT
|
||||
> returns an appropriate string
|
||||
for the error code gievn by <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>err</I
|
||||
></TT
|
||||
>. The values of
|
||||
the error codes and messages are as follows:
|
||||
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>NETDB_SUCCESS</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="ERRORNAME"
|
||||
>Resolver Error 0 (no error)</SPAN
|
||||
></P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>HOST_NOT_FOUND</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="ERRORNAME"
|
||||
>Unknown host</SPAN
|
||||
></P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>TRY_AGAIN</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="ERRORNAME"
|
||||
>Host name lookup failure</SPAN
|
||||
></P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>NO_RECOVERY</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="ERRORNAME"
|
||||
>Unknown server error</SPAN
|
||||
></P
|
||||
></DD
|
||||
><DT
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>NO_DATA</SPAN
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="ERRORNAME"
|
||||
>No address associated with name</SPAN
|
||||
></P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN65"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
>The string <SPAN
|
||||
CLASS="ERRORNAME"
|
||||
>Unknown resolver error</SPAN
|
||||
> is returned by
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_hstrerror()</TT
|
||||
>
|
||||
when the value of
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>lwres_h_errno</TT
|
||||
>
|
||||
is not a valid error code.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN71"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>herror</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_hstrerror</SPAN
|
||||
>(3)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,52 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_INETNTOP" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_net_ntop \- lightweight resolver IP address presentation
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/net.h>
|
||||
.sp
|
||||
.na
|
||||
const char *
|
||||
lwres_net_ntop(int af, const void *src, char *dst, size_t size);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBlwres_net_ntop()\fR converts an IP address of
|
||||
protocol family \fIaf\fR \(em IPv4 or IPv6 \(em
|
||||
at location \fIsrc\fR from network format to its
|
||||
conventional representation as a string. For IPv4 addresses, that
|
||||
string would be a dotted-decimal. An IPv6 address would be
|
||||
represented in colon notation as described in RFC1884.
|
||||
.PP
|
||||
The generated string is copied to \fIdst\fR provided
|
||||
\fIsize\fR indicates it is long enough to store the
|
||||
ASCII representation of the address.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
If successful, the function returns \fIdst\fR:
|
||||
a pointer to a string containing the presentation format of the
|
||||
address. \fBlwres_net_ntop()\fR returns
|
||||
\fBNULL\fR and sets the global variable
|
||||
errno to EAFNOSUPPORT if
|
||||
the protocol family given in \fIaf\fR is not
|
||||
supported.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBRFC1884\fR,
|
||||
\fBinet_ntop\fR(3),
|
||||
\fBerrno\fR(3).
|
||||
@@ -0,0 +1,99 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_inetntop.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_inetntop</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_net_ntop</refname>
|
||||
<refpurpose>lightweight resolver IP address presentation</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/net.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
const char *
|
||||
<function>lwres_net_ntop</function></funcdef>
|
||||
<paramdef>int af</paramdef>
|
||||
<paramdef>const void *src</paramdef>
|
||||
<paramdef>char *dst</paramdef>
|
||||
<paramdef>size_t size</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
|
||||
<para>
|
||||
<function>lwres_net_ntop()</function> converts an IP address of
|
||||
protocol family <parameter>af</parameter> — IPv4 or IPv6 —
|
||||
at location <parameter>src</parameter> from network format to its
|
||||
conventional representation as a string. For IPv4 addresses, that
|
||||
string would be a dotted-decimal. An IPv6 address would be
|
||||
represented in colon notation as described in RFC1884.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The generated string is copied to <parameter>dst</parameter> provided
|
||||
<parameter>size</parameter> indicates it is long enough to store the
|
||||
ASCII representation of the address.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
|
||||
<para>
|
||||
If successful, the function returns <parameter>dst</parameter>:
|
||||
a pointer to a string containing the presentation format of the
|
||||
address. <function>lwres_net_ntop()</function> returns
|
||||
<type>NULL</type> and sets the global variable
|
||||
<constant>errno</constant> to <errorcode>EAFNOSUPPORT</errorcode> if
|
||||
the protocol family given in <parameter>af</parameter> is not
|
||||
supported.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>RFC1884</refentrytitle>
|
||||
</citerefentry>,
|
||||
<citerefentry>
|
||||
<refentrytitle>inet_ntop</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
<citerefentry>
|
||||
<refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,186 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_inetntop</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_inetntop</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_net_ntop -- lightweight resolver IP address presentation</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN11"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN12"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/net.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>const char *
|
||||
lwres_net_ntop</CODE
|
||||
>(int af, const void *src, char *dst, size_t size);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN21"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_net_ntop()</TT
|
||||
> converts an IP address of
|
||||
protocol family <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>af</I
|
||||
></TT
|
||||
> — IPv4 or IPv6 —
|
||||
at location <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>src</I
|
||||
></TT
|
||||
> from network format to its
|
||||
conventional representation as a string. For IPv4 addresses, that
|
||||
string would be a dotted-decimal. An IPv6 address would be
|
||||
represented in colon notation as described in RFC1884.</P
|
||||
><P
|
||||
>The generated string is copied to <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>dst</I
|
||||
></TT
|
||||
> provided
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>size</I
|
||||
></TT
|
||||
> indicates it is long enough to store the
|
||||
ASCII representation of the address.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN30"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
>If successful, the function returns <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>dst</I
|
||||
></TT
|
||||
>:
|
||||
a pointer to a string containing the presentation format of the
|
||||
address. <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_net_ntop()</TT
|
||||
> returns
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
> and sets the global variable
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>errno</TT
|
||||
> to <SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>EAFNOSUPPORT</SPAN
|
||||
> if
|
||||
the protocol family given in <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>af</I
|
||||
></TT
|
||||
> is not
|
||||
supported.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN39"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>RFC1884</SPAN
|
||||
></SPAN
|
||||
>,
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>inet_ntop</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>errno</SPAN
|
||||
>(3)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,160 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_NOOP" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free \- lightweight resolver no-op message handling
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/lwres.h>
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_noopresponse_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
void
|
||||
lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
These are low-level routines for creating and parsing
|
||||
lightweight resolver no-op request and response messages.
|
||||
.PP
|
||||
The no-op message is analogous to a \fBping\fR packet:
|
||||
a packet is sent to the resolver daemon and is simply echoed back.
|
||||
The opcode is intended to allow a client to determine if the server is
|
||||
operational or not.
|
||||
.PP
|
||||
There are four main functions for the no-op opcode.
|
||||
One render function converts a no-op request structure \(em
|
||||
\fBlwres_nooprequest_t\fR \(em
|
||||
to the lighweight resolver's canonical format.
|
||||
It is complemented by a parse function that converts a packet in this
|
||||
canonical format to a no-op request structure.
|
||||
Another render function converts the no-op response structure \(em
|
||||
\fBlwres_noopresponse_t\fR
|
||||
to the canonical format.
|
||||
This is complemented by a parse function which converts a packet in
|
||||
canonical format to a no-op response structure.
|
||||
.PP
|
||||
These structures are defined in
|
||||
\fIlwres/lwres.h\fR.
|
||||
They are shown below.
|
||||
.sp
|
||||
.nf
|
||||
#define LWRES_OPCODE_NOOP 0x00000000U
|
||||
|
||||
typedef struct {
|
||||
lwres_uint16_t datalength;
|
||||
unsigned char *data;
|
||||
} lwres_nooprequest_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint16_t datalength;
|
||||
unsigned char *data;
|
||||
} lwres_noopresponse_t;
|
||||
.sp
|
||||
.fi
|
||||
Although the structures have different types, they are identical.
|
||||
This is because the no-op opcode simply echos whatever data was sent:
|
||||
the response is therefore identical to the request.
|
||||
.PP
|
||||
\fBlwres_nooprequest_render()\fR uses resolver
|
||||
context \fIctx\fR to convert no-op request structure
|
||||
\fIreq\fR to canonical format. The packet header
|
||||
structure \fIpkt\fR is initialised and transferred to
|
||||
buffer \fIb\fR. The contents of
|
||||
\fI*req\fR are then appended to the buffer in
|
||||
canonical format. \fBlwres_noopresponse_render()\fR
|
||||
performs the same task, except it converts a no-op response structure
|
||||
\fBlwres_noopresponse_t\fR to the lightweight resolver's
|
||||
canonical format.
|
||||
.PP
|
||||
\fBlwres_nooprequest_parse()\fR uses context
|
||||
\fIctx\fR to convert the contents of packet
|
||||
\fIpkt\fR to a \fBlwres_nooprequest_t\fR
|
||||
structure. Buffer \fIb\fR provides space to be used
|
||||
for storing this structure. When the function succeeds, the resulting
|
||||
\fBlwres_nooprequest_t\fR is made available through
|
||||
\fI*structp\fR.
|
||||
\fBlwres_noopresponse_parse()\fR offers the same
|
||||
semantics as \fBlwres_nooprequest_parse()\fR except it
|
||||
yields a \fBlwres_noopresponse_t\fR structure.
|
||||
.PP
|
||||
\fBlwres_noopresponse_free()\fR and
|
||||
\fBlwres_nooprequest_free()\fR release the memory in
|
||||
resolver context \fIctx\fR that was allocated to the
|
||||
\fBlwres_noopresponse_t\fR or \fBlwres_nooprequest_t\fR
|
||||
structures referenced via \fIstructp\fR.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
The no-op opcode functions
|
||||
\fBlwres_nooprequest_render()\fR,
|
||||
\fBlwres_noopresponse_render()\fR
|
||||
\fBlwres_nooprequest_parse()\fR
|
||||
and
|
||||
\fBlwres_noopresponse_parse()\fR
|
||||
all return
|
||||
LWRES_R_SUCCESS
|
||||
on success.
|
||||
They return
|
||||
LWRES_R_NOMEMORY
|
||||
if memory allocation fails.
|
||||
LWRES_R_UNEXPECTEDEND
|
||||
is returned if the available space in the buffer
|
||||
\fIb\fR
|
||||
is too small to accommodate the packet header or the
|
||||
\fBlwres_nooprequest_t\fR
|
||||
and
|
||||
\fBlwres_noopresponse_t\fR
|
||||
structures.
|
||||
\fBlwres_nooprequest_parse()\fR
|
||||
and
|
||||
\fBlwres_noopresponse_parse()\fR
|
||||
will return
|
||||
LWRES_R_UNEXPECTEDEND
|
||||
if the buffer is not empty after decoding the received packet.
|
||||
These functions will return
|
||||
LWRES_R_FAILURE
|
||||
if
|
||||
pktflags
|
||||
in the packet header structure
|
||||
\fBlwres_lwpacket_t\fR
|
||||
indicate that the packet is not a response to an earlier query.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBlwres_packet\fR(3)
|
||||
@@ -0,0 +1,229 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_noop.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_noop</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_nooprequest_render</refname>
|
||||
<refname>lwres_noopresponse_render</refname>
|
||||
<refname>lwres_nooprequest_parse</refname>
|
||||
<refname>lwres_noopresponse_parse</refname>
|
||||
<refname>lwres_noopresponse_free</refname>
|
||||
<refname>lwres_nooprequest_free</refname>
|
||||
<refpurpose>lightweight resolver no-op message handling</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>
|
||||
#include <lwres/lwres.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_nooprequest_render</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_nooprequest_t *req</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_noopresponse_render</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_noopresponse_t *req</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_nooprequest_parse</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_nooprequest_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_noopresponse_parse</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
<paramdef>lwres_noopresponse_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_noopresponse_free</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_noopresponse_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
void
|
||||
<function>lwres_nooprequest_free</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_nooprequest_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
These are low-level routines for creating and parsing
|
||||
lightweight resolver no-op request and response messages.
|
||||
</para>
|
||||
<para>
|
||||
The no-op message is analogous to a <command>ping</command> packet:
|
||||
a packet is sent to the resolver daemon and is simply echoed back.
|
||||
The opcode is intended to allow a client to determine if the server is
|
||||
operational or not.
|
||||
</para>
|
||||
<para>
|
||||
There are four main functions for the no-op opcode.
|
||||
One render function converts a no-op request structure —
|
||||
<type>lwres_nooprequest_t</type> —
|
||||
to the lighweight resolver's canonical format.
|
||||
It is complemented by a parse function that converts a packet in this
|
||||
canonical format to a no-op request structure.
|
||||
Another render function converts the no-op response structure —
|
||||
<type>lwres_noopresponse_t</type>
|
||||
to the canonical format.
|
||||
This is complemented by a parse function which converts a packet in
|
||||
canonical format to a no-op response structure.
|
||||
</para>
|
||||
<para>
|
||||
These structures are defined in
|
||||
<filename>lwres/lwres.h</filename>.
|
||||
|
||||
They are shown below.
|
||||
<programlisting>
|
||||
#define LWRES_OPCODE_NOOP 0x00000000U
|
||||
|
||||
typedef struct {
|
||||
lwres_uint16_t datalength;
|
||||
unsigned char *data;
|
||||
} lwres_nooprequest_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint16_t datalength;
|
||||
unsigned char *data;
|
||||
} lwres_noopresponse_t;
|
||||
</programlisting>
|
||||
Although the structures have different types, they are identical.
|
||||
This is because the no-op opcode simply echos whatever data was sent:
|
||||
the response is therefore identical to the request.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_nooprequest_render()</function> uses resolver
|
||||
context <parameter>ctx</parameter> to convert no-op request structure
|
||||
<parameter>req</parameter> to canonical format. The packet header
|
||||
structure <parameter>pkt</parameter> is initialised and transferred to
|
||||
buffer <parameter>b</parameter>. The contents of
|
||||
<parameter>*req</parameter> are then appended to the buffer in
|
||||
canonical format. <function>lwres_noopresponse_render()</function>
|
||||
performs the same task, except it converts a no-op response structure
|
||||
<type>lwres_noopresponse_t</type> to the lightweight resolver's
|
||||
canonical format.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_nooprequest_parse()</function> uses context
|
||||
<parameter>ctx</parameter> to convert the contents of packet
|
||||
<parameter>pkt</parameter> to a <type>lwres_nooprequest_t</type>
|
||||
structure. Buffer <parameter>b</parameter> provides space to be used
|
||||
for storing this structure. When the function succeeds, the resulting
|
||||
<type>lwres_nooprequest_t</type> is made available through
|
||||
<parameter>*structp</parameter>.
|
||||
<function>lwres_noopresponse_parse()</function> offers the same
|
||||
semantics as <function>lwres_nooprequest_parse()</function> except it
|
||||
yields a <type>lwres_noopresponse_t</type> structure.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_noopresponse_free()</function> and
|
||||
<function>lwres_nooprequest_free()</function> release the memory in
|
||||
resolver context <parameter>ctx</parameter> that was allocated to the
|
||||
<type>lwres_noopresponse_t</type> or <type>lwres_nooprequest_t</type>
|
||||
structures referenced via <parameter>structp</parameter>.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
The no-op opcode functions
|
||||
<function>lwres_nooprequest_render()</function>,
|
||||
|
||||
<function>lwres_noopresponse_render()</function>
|
||||
<function>lwres_nooprequest_parse()</function>
|
||||
and
|
||||
<function>lwres_noopresponse_parse()</function>
|
||||
all return
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>
|
||||
on success.
|
||||
They return
|
||||
<errorcode>LWRES_R_NOMEMORY</errorcode>
|
||||
if memory allocation fails.
|
||||
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
|
||||
is returned if the available space in the buffer
|
||||
<parameter>b</parameter>
|
||||
is too small to accommodate the packet header or the
|
||||
<type>lwres_nooprequest_t</type>
|
||||
and
|
||||
<type>lwres_noopresponse_t</type>
|
||||
structures.
|
||||
<function>lwres_nooprequest_parse()</function>
|
||||
and
|
||||
<function>lwres_noopresponse_parse()</function>
|
||||
will return
|
||||
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
|
||||
if the buffer is not empty after decoding the received packet.
|
||||
These functions will return
|
||||
<errorcode>LWRES_R_FAILURE</errorcode>
|
||||
if
|
||||
<constant>pktflags</constant>
|
||||
in the packet header structure
|
||||
<type>lwres_lwpacket_t</type>
|
||||
indicate that the packet is not a response to an earlier query.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_packet</refentrytitle><manvolnum>3
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,409 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_noop</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_noop</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free -- lightweight resolver no-op message handling</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN16"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN17"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/lwres.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_nooprequest_render</CODE
|
||||
>(lwres_context_t *ctx, lwres_nooprequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_noopresponse_render</CODE
|
||||
>(lwres_context_t *ctx, lwres_noopresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_nooprequest_parse</CODE
|
||||
>(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_noopresponse_parse</CODE
|
||||
>(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_noopresponse_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_noopresponse_free</CODE
|
||||
>(lwres_context_t *ctx, lwres_noopresponse_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>void
|
||||
lwres_nooprequest_free</CODE
|
||||
>(lwres_context_t *ctx, lwres_nooprequest_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN57"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
>These are low-level routines for creating and parsing
|
||||
lightweight resolver no-op request and response messages.</P
|
||||
><P
|
||||
>The no-op message is analogous to a <B
|
||||
CLASS="COMMAND"
|
||||
>ping</B
|
||||
> packet:
|
||||
a packet is sent to the resolver daemon and is simply echoed back.
|
||||
The opcode is intended to allow a client to determine if the server is
|
||||
operational or not.</P
|
||||
><P
|
||||
>There are four main functions for the no-op opcode.
|
||||
One render function converts a no-op request structure —
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_nooprequest_t</SPAN
|
||||
> —
|
||||
to the lighweight resolver's canonical format.
|
||||
It is complemented by a parse function that converts a packet in this
|
||||
canonical format to a no-op request structure.
|
||||
Another render function converts the no-op response structure —
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_noopresponse_t</SPAN
|
||||
>
|
||||
to the canonical format.
|
||||
This is complemented by a parse function which converts a packet in
|
||||
canonical format to a no-op response structure.</P
|
||||
><P
|
||||
>These structures are defined in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
>lwres/lwres.h</TT
|
||||
>.
|
||||
|
||||
They are shown below.
|
||||
<PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>#define LWRES_OPCODE_NOOP 0x00000000U
|
||||
|
||||
typedef struct {
|
||||
lwres_uint16_t datalength;
|
||||
unsigned char *data;
|
||||
} lwres_nooprequest_t;
|
||||
|
||||
typedef struct {
|
||||
lwres_uint16_t datalength;
|
||||
unsigned char *data;
|
||||
} lwres_noopresponse_t;</PRE
|
||||
>
|
||||
Although the structures have different types, they are identical.
|
||||
This is because the no-op opcode simply echos whatever data was sent:
|
||||
the response is therefore identical to the request.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_nooprequest_render()</TT
|
||||
> uses resolver
|
||||
context <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
> to convert no-op request structure
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>req</I
|
||||
></TT
|
||||
> to canonical format. The packet header
|
||||
structure <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>pkt</I
|
||||
></TT
|
||||
> is initialised and transferred to
|
||||
buffer <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>. The contents of
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*req</I
|
||||
></TT
|
||||
> are then appended to the buffer in
|
||||
canonical format. <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_noopresponse_render()</TT
|
||||
>
|
||||
performs the same task, except it converts a no-op response structure
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_noopresponse_t</SPAN
|
||||
> to the lightweight resolver's
|
||||
canonical format.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_nooprequest_parse()</TT
|
||||
> uses context
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
> to convert the contents of packet
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>pkt</I
|
||||
></TT
|
||||
> to a <SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_nooprequest_t</SPAN
|
||||
>
|
||||
structure. Buffer <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
> provides space to be used
|
||||
for storing this structure. When the function succeeds, the resulting
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_nooprequest_t</SPAN
|
||||
> is made available through
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*structp</I
|
||||
></TT
|
||||
>.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_noopresponse_parse()</TT
|
||||
> offers the same
|
||||
semantics as <TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_nooprequest_parse()</TT
|
||||
> except it
|
||||
yields a <SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_noopresponse_t</SPAN
|
||||
> structure.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_noopresponse_free()</TT
|
||||
> and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_nooprequest_free()</TT
|
||||
> release the memory in
|
||||
resolver context <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
> that was allocated to the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_noopresponse_t</SPAN
|
||||
> or <SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_nooprequest_t</SPAN
|
||||
>
|
||||
structures referenced via <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>structp</I
|
||||
></TT
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN95"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
>The no-op opcode functions
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_nooprequest_render()</TT
|
||||
>,
|
||||
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_noopresponse_render()</TT
|
||||
>
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_nooprequest_parse()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_noopresponse_parse()</TT
|
||||
>
|
||||
all return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>
|
||||
on success.
|
||||
They return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_NOMEMORY</SPAN
|
||||
>
|
||||
if memory allocation fails.
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_UNEXPECTEDEND</SPAN
|
||||
>
|
||||
is returned if the available space in the buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>
|
||||
is too small to accommodate the packet header or the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_nooprequest_t</SPAN
|
||||
>
|
||||
and
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_noopresponse_t</SPAN
|
||||
>
|
||||
structures.
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_nooprequest_parse()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_noopresponse_parse()</TT
|
||||
>
|
||||
will return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_UNEXPECTEDEND</SPAN
|
||||
>
|
||||
if the buffer is not empty after decoding the received packet.
|
||||
These functions will return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_FAILURE</SPAN
|
||||
>
|
||||
if
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>pktflags</TT
|
||||
>
|
||||
in the packet header structure
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_lwpacket_t</SPAN
|
||||
>
|
||||
indicate that the packet is not a response to an earlier query.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN114"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_packet</SPAN
|
||||
>(3)</SPAN
|
||||
></P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,149 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_PACKET" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_lwpacket_renderheader, lwres_lwpacket_parseheader \- lightweight resolver packet handling functions
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/lwpacket.h>
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_lwpacket_parseheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
These functions rely on a
|
||||
\fBstruct lwres_lwpacket\fR
|
||||
which is defined in
|
||||
\fIlwres/lwpacket.h\fR.
|
||||
.sp
|
||||
.nf
|
||||
typedef struct lwres_lwpacket lwres_lwpacket_t;
|
||||
|
||||
struct lwres_lwpacket {
|
||||
lwres_uint32_t length;
|
||||
lwres_uint16_t version;
|
||||
lwres_uint16_t pktflags;
|
||||
lwres_uint32_t serial;
|
||||
lwres_uint32_t opcode;
|
||||
lwres_uint32_t result;
|
||||
lwres_uint32_t recvlength;
|
||||
lwres_uint16_t authtype;
|
||||
lwres_uint16_t authlength;
|
||||
};
|
||||
.sp
|
||||
.fi
|
||||
.PP
|
||||
The elements of this structure are:
|
||||
.TP
|
||||
\fBlength\fR
|
||||
the overall packet length, including the entire packet header.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.
|
||||
.TP
|
||||
\fBversion\fR
|
||||
the header format. There is currently only one format,
|
||||
\fBLWRES_LWPACKETVERSION_0\fR.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.
|
||||
.TP
|
||||
\fBpktflags\fR
|
||||
library-defined flags for this packet: for instance whether the packet
|
||||
is a request or a reply. Flag values can be set, but not defined by
|
||||
the caller.
|
||||
This field is filled in by the application wit the exception of the
|
||||
LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
|
||||
lwres_gabn_*() and lwres_gnba_*() calls.
|
||||
.TP
|
||||
\fBserial\fR
|
||||
is set by the requestor and is returned in all replies. If two or more
|
||||
packets from the same source have the same serial number and are from
|
||||
the same source, they are assumed to be duplicates and the latter ones
|
||||
may be dropped.
|
||||
This field must be set by the application.
|
||||
.TP
|
||||
\fBopcode\fR
|
||||
indicates the operation.
|
||||
Opcodes between 0x00000000 and 0x03ffffff are
|
||||
reserved for use by the lightweight resolver library. Opcodes between
|
||||
0x04000000 and 0xffffffff are application defined.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.
|
||||
.TP
|
||||
\fBresult\fR
|
||||
is only valid for replies.
|
||||
Results between 0x04000000 and 0xffffffff are application defined.
|
||||
Results between 0x00000000 and 0x03ffffff are reserved for library use.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.
|
||||
.TP
|
||||
\fBrecvlength\fR
|
||||
is the maximum buffer size that the receiver can handle on requests
|
||||
and the size of the buffer needed to satisfy a request when the buffer
|
||||
is too large for replies.
|
||||
This field is supplied by the application.
|
||||
.TP
|
||||
\fBauthtype\fR
|
||||
defines the packet level authentication that is used.
|
||||
Authorisation types between 0x1000 and 0xffff are application defined
|
||||
and types between 0x0000 and 0x0fff are reserved for library use.
|
||||
Currently these are not used and must be zero.
|
||||
.TP
|
||||
\fBauthlen\fR
|
||||
gives the length of the authentication data.
|
||||
Since packet authentication is currently not used, this must be zero.
|
||||
.PP
|
||||
The following opcodes are currently defined:
|
||||
.TP
|
||||
\fBNOOP\fR
|
||||
Success is always returned and the packet contents are echoed.
|
||||
The lwres_noop_*() functions should be used for this type.
|
||||
.TP
|
||||
\fBGETADDRSBYNAME\fR
|
||||
returns all known addresses for a given name.
|
||||
The lwres_gabn_*() functions should be used for this type.
|
||||
.TP
|
||||
\fBGETNAMEBYADDR\fR
|
||||
return the hostname for the given address.
|
||||
The lwres_gnba_*() functions should be used for this type.
|
||||
.PP
|
||||
\fBlwres_lwpacket_renderheader()\fR transfers the
|
||||
contents of lightweight resolver packet structure
|
||||
\fBlwres_lwpacket_t\fR \fI*pkt\fR in network
|
||||
byte order to the lightweight resolver buffer,
|
||||
\fI*b\fR.
|
||||
.PP
|
||||
\fBlwres_lwpacket_parseheader()\fR performs the
|
||||
converse operation. It transfers data in network byte order from
|
||||
buffer \fI*b\fR to resolver packet
|
||||
\fI*pkt\fR. The contents of the buffer
|
||||
\fIb\fR should correspond to a
|
||||
\fBlwres_lwpacket_t\fR.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
Successful calls to
|
||||
\fBlwres_lwpacket_renderheader()\fR and
|
||||
\fBlwres_lwpacket_parseheader()\fR return
|
||||
LWRES_R_SUCCESS. If there is insufficient
|
||||
space to copy data between the buffer \fI*b\fR and
|
||||
lightweight resolver packet \fI*pkt\fR both functions
|
||||
return LWRES_R_UNEXPECTEDEND.
|
||||
@@ -0,0 +1,218 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_packet.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_packet</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_lwpacket_renderheader</refname>
|
||||
<refname>lwres_lwpacket_parseheader</refname>
|
||||
<refpurpose>lightweight resolver packet handling functions</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_lwpacket_renderheader</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_lwpacket_parseheader</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_lwpacket_t *pkt</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
<para>
|
||||
These functions rely on a
|
||||
<type>struct lwres_lwpacket</type>
|
||||
which is defined in
|
||||
<filename>lwres/lwpacket.h</filename>.
|
||||
|
||||
<programlisting>
|
||||
typedef struct lwres_lwpacket lwres_lwpacket_t;
|
||||
|
||||
struct lwres_lwpacket {
|
||||
lwres_uint32_t length;
|
||||
lwres_uint16_t version;
|
||||
lwres_uint16_t pktflags;
|
||||
lwres_uint32_t serial;
|
||||
lwres_uint32_t opcode;
|
||||
lwres_uint32_t result;
|
||||
lwres_uint32_t recvlength;
|
||||
lwres_uint16_t authtype;
|
||||
lwres_uint16_t authlength;
|
||||
};
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The elements of this structure are:
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>length</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
the overall packet length, including the entire packet header.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>version</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
the header format. There is currently only one format,
|
||||
<type>LWRES_LWPACKETVERSION_0</type>.
|
||||
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>pktflags</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
library-defined flags for this packet: for instance whether the packet
|
||||
is a request or a reply. Flag values can be set, but not defined by
|
||||
the caller.
|
||||
This field is filled in by the application wit the exception of the
|
||||
LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
|
||||
lwres_gabn_*() and lwres_gnba_*() calls.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>serial</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
is set by the requestor and is returned in all replies. If two or more
|
||||
packets from the same source have the same serial number and are from
|
||||
the same source, they are assumed to be duplicates and the latter ones
|
||||
may be dropped.
|
||||
This field must be set by the application.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>opcode</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
indicates the operation.
|
||||
Opcodes between 0x00000000 and 0x03ffffff are
|
||||
reserved for use by the lightweight resolver library. Opcodes between
|
||||
0x04000000 and 0xffffffff are application defined.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>result</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
is only valid for replies.
|
||||
Results between 0x04000000 and 0xffffffff are application defined.
|
||||
Results between 0x00000000 and 0x03ffffff are reserved for library use.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>recvlength</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
is the maximum buffer size that the receiver can handle on requests
|
||||
and the size of the buffer needed to satisfy a request when the buffer
|
||||
is too large for replies.
|
||||
This field is supplied by the application.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>authtype</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
defines the packet level authentication that is used.
|
||||
Authorisation types between 0x1000 and 0xffff are application defined
|
||||
and types between 0x0000 and 0x0fff are reserved for library use.
|
||||
Currently these are not used and must be zero.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>authlen</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
gives the length of the authentication data.
|
||||
Since packet authentication is currently not used, this must be zero.
|
||||
</para></listitem></varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
<para>
|
||||
The following opcodes are currently defined:
|
||||
<variablelist>
|
||||
<varlistentry><term><constant>NOOP</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Success is always returned and the packet contents are echoed.
|
||||
The lwres_noop_*() functions should be used for this type.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>GETADDRSBYNAME</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
returns all known addresses for a given name.
|
||||
The lwres_gabn_*() functions should be used for this type.
|
||||
</para></listitem></varlistentry>
|
||||
<varlistentry><term><constant>GETNAMEBYADDR</constant></term>
|
||||
<listitem>
|
||||
<para>
|
||||
return the hostname for the given address.
|
||||
The lwres_gnba_*() functions should be used for this type.
|
||||
</para></listitem></varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_lwpacket_renderheader()</function> transfers the
|
||||
contents of lightweight resolver packet structure
|
||||
<type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in network
|
||||
byte order to the lightweight resolver buffer,
|
||||
<parameter>*b</parameter>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_lwpacket_parseheader()</function> performs the
|
||||
converse operation. It transfers data in network byte order from
|
||||
buffer <parameter>*b</parameter> to resolver packet
|
||||
<parameter>*pkt</parameter>. The contents of the buffer
|
||||
<parameter>b</parameter> should correspond to a
|
||||
<type>lwres_lwpacket_t</type>.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para> Successful calls to
|
||||
<function>lwres_lwpacket_renderheader()</function> and
|
||||
<function>lwres_lwpacket_parseheader()</function> return
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient
|
||||
space to copy data between the buffer <parameter>*b</parameter> and
|
||||
lightweight resolver packet <parameter>*pkt</parameter> both functions
|
||||
return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,373 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_packet</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_packet</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_lwpacket_renderheader, lwres_lwpacket_parseheader -- lightweight resolver packet handling functions</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN12"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN13"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/lwpacket.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_lwpacket_renderheader</CODE
|
||||
>(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_lwpacket_parseheader</CODE
|
||||
>(lwres_buffer_t *b, lwres_lwpacket_t *pkt);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN25"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
>These functions rely on a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>struct lwres_lwpacket</SPAN
|
||||
>
|
||||
which is defined in
|
||||
<TT
|
||||
CLASS="FILENAME"
|
||||
>lwres/lwpacket.h</TT
|
||||
>.
|
||||
|
||||
<PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>typedef struct lwres_lwpacket lwres_lwpacket_t;
|
||||
|
||||
struct lwres_lwpacket {
|
||||
lwres_uint32_t length;
|
||||
lwres_uint16_t version;
|
||||
lwres_uint16_t pktflags;
|
||||
lwres_uint32_t serial;
|
||||
lwres_uint32_t opcode;
|
||||
lwres_uint32_t result;
|
||||
lwres_uint32_t recvlength;
|
||||
lwres_uint16_t authtype;
|
||||
lwres_uint16_t authlength;
|
||||
};</PRE
|
||||
></P
|
||||
><P
|
||||
>The elements of this structure are:
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>length</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>the overall packet length, including the entire packet header.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>version</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>the header format. There is currently only one format,
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>LWRES_LWPACKETVERSION_0</SPAN
|
||||
>.
|
||||
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>pktflags</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>library-defined flags for this packet: for instance whether the packet
|
||||
is a request or a reply. Flag values can be set, but not defined by
|
||||
the caller.
|
||||
This field is filled in by the application wit the exception of the
|
||||
LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the
|
||||
lwres_gabn_*() and lwres_gnba_*() calls.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>serial</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>is set by the requestor and is returned in all replies. If two or more
|
||||
packets from the same source have the same serial number and are from
|
||||
the same source, they are assumed to be duplicates and the latter ones
|
||||
may be dropped.
|
||||
This field must be set by the application.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>opcode</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>indicates the operation.
|
||||
Opcodes between 0x00000000 and 0x03ffffff are
|
||||
reserved for use by the lightweight resolver library. Opcodes between
|
||||
0x04000000 and 0xffffffff are application defined.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>result</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>is only valid for replies.
|
||||
Results between 0x04000000 and 0xffffffff are application defined.
|
||||
Results between 0x00000000 and 0x03ffffff are reserved for library use.
|
||||
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
|
||||
calls.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>recvlength</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>is the maximum buffer size that the receiver can handle on requests
|
||||
and the size of the buffer needed to satisfy a request when the buffer
|
||||
is too large for replies.
|
||||
This field is supplied by the application.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>authtype</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>defines the packet level authentication that is used.
|
||||
Authorisation types between 0x1000 and 0xffff are application defined
|
||||
and types between 0x0000 and 0x0fff are reserved for library use.
|
||||
Currently these are not used and must be zero.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>authlen</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>gives the length of the authentication data.
|
||||
Since packet authentication is currently not used, this must be zero.</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
><P
|
||||
>The following opcodes are currently defined:
|
||||
<P
|
||||
></P
|
||||
><DIV
|
||||
CLASS="VARIABLELIST"
|
||||
><DL
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>NOOP</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>Success is always returned and the packet contents are echoed.
|
||||
The lwres_noop_*() functions should be used for this type.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>GETADDRSBYNAME</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>returns all known addresses for a given name.
|
||||
The lwres_gabn_*() functions should be used for this type.</P
|
||||
></DD
|
||||
><DT
|
||||
><TT
|
||||
CLASS="CONSTANT"
|
||||
>GETNAMEBYADDR</TT
|
||||
></DT
|
||||
><DD
|
||||
><P
|
||||
>return the hostname for the given address.
|
||||
The lwres_gnba_*() functions should be used for this type.</P
|
||||
></DD
|
||||
></DL
|
||||
></DIV
|
||||
></P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_lwpacket_renderheader()</TT
|
||||
> transfers the
|
||||
contents of lightweight resolver packet structure
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_lwpacket_t</SPAN
|
||||
> <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*pkt</I
|
||||
></TT
|
||||
> in network
|
||||
byte order to the lightweight resolver buffer,
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*b</I
|
||||
></TT
|
||||
>.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_lwpacket_parseheader()</TT
|
||||
> performs the
|
||||
converse operation. It transfers data in network byte order from
|
||||
buffer <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*b</I
|
||||
></TT
|
||||
> to resolver packet
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*pkt</I
|
||||
></TT
|
||||
>. The contents of the buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
> should correspond to a
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_lwpacket_t</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN107"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
> Successful calls to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_lwpacket_renderheader()</TT
|
||||
> and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_lwpacket_parseheader()</TT
|
||||
> return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>. If there is insufficient
|
||||
space to copy data between the buffer <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*b</I
|
||||
></TT
|
||||
> and
|
||||
lightweight resolver packet <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*pkt</I
|
||||
></TT
|
||||
> both functions
|
||||
return <SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_UNEXPECTEDEND</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
@@ -0,0 +1,151 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this software for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.TH "LWRES_RESUTIL" "3" "Jun 30, 2000" "BIND9" ""
|
||||
.SH NAME
|
||||
lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr \- lightweight resolver utility functions
|
||||
.SH SYNOPSIS
|
||||
\fB#include <lwres/lwres.h>
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_getaddrsbyname(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);
|
||||
.ad
|
||||
.sp
|
||||
.na
|
||||
lwres_result_t
|
||||
lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, lwres_gnbaresponse_t **structp);
|
||||
.ad
|
||||
\fR.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBlwres_string_parse()\fR retrieves a DNS-encoded
|
||||
string starting the current pointer of lightweight resolver buffer
|
||||
\fIb\fR: i.e. b->current.
|
||||
When the function returns, the address of the first byte of the
|
||||
encoded string is returned via \fI*c\fR and the
|
||||
length of that string is given by \fI*len\fR. The
|
||||
buffer's current pointer is advanced to point at the character
|
||||
following the string length, the encoded string, and the trailing
|
||||
\fBNULL\fR character.
|
||||
.PP
|
||||
\fBlwres_addr_parse()\fR extracts an address from the
|
||||
buffer \fIb\fR. The buffer's current pointer
|
||||
b->current is presumed to point at an encoded
|
||||
address: the address preceded by a 32-bit protocol family identifier
|
||||
and a 16-bit length field. The encoded address is copied to
|
||||
addr->address and
|
||||
addr->length indicates the size in bytes of
|
||||
the address that was copied. b->current is
|
||||
advanced to point at the next byte of available data in the buffer
|
||||
following the encoded address.
|
||||
.PP
|
||||
\fBlwres_getaddrsbyname()\fR
|
||||
and
|
||||
\fBlwres_getnamebyaddr()\fR
|
||||
use the
|
||||
\fBlwres_gnbaresponse_t\fR
|
||||
structure defined below:
|
||||
.sp
|
||||
.nf
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint16_t naliases;
|
||||
lwres_uint16_t naddrs;
|
||||
char *realname;
|
||||
char **aliases;
|
||||
lwres_uint16_t realnamelen;
|
||||
lwres_uint16_t *aliaslen;
|
||||
lwres_addrlist_t addrs;
|
||||
void *base;
|
||||
size_t baselen;
|
||||
} lwres_gabnresponse_t;
|
||||
.sp
|
||||
.fi
|
||||
The contents of this structure are not manipulated directly but
|
||||
they are controlled through the
|
||||
\fBlwres_gabn\fR(3)
|
||||
functions.
|
||||
.PP
|
||||
The lightweight resolver uses
|
||||
\fBlwres_getaddrsbyname()\fR to perform foward lookups.
|
||||
Hostname \fIname\fR is looked up using the resolver
|
||||
context \fIctx\fR for memory allocation.
|
||||
\fIaddrtypes\fR is a bitmask indicating which type of
|
||||
addresses are to be looked up. Current values for this bitmask are
|
||||
\fBLWRES_ADDRTYPE_V4\fR for IPv4 addresses and
|
||||
\fBLWRES_ADDRTYPE_V6\fR for IPv6 addresses. Results of the
|
||||
lookup are returned in \fI*structp\fR.
|
||||
.PP
|
||||
\fBlwres_getnamebyaddr()\fR performs reverse lookups.
|
||||
Resolver context \fIctx\fR is used for memory
|
||||
allocation. The address type is indicated by
|
||||
\fIaddrtype\fR: \fBLWRES_ADDRTYPE_V4\fR or
|
||||
\fBLWRES_ADDRTYPE_V6\fR. The address to be looked up is given
|
||||
by \fIaddr\fR and its length is
|
||||
\fIaddrlen\fR bytes. The result of the function call
|
||||
is made available through \fI*structp\fR.
|
||||
.SH "RETURN VALUES"
|
||||
.PP
|
||||
Successful calls to
|
||||
\fBlwres_string_parse()\fR
|
||||
and
|
||||
\fBlwres_addr_parse()\fR
|
||||
return
|
||||
LWRES_R_SUCCESS.
|
||||
Both functions return
|
||||
LWRES_R_FAILURE
|
||||
if the buffer is corrupt or
|
||||
LWRES_R_UNEXPECTEDEND
|
||||
if the buffer has less space than expected for the components of the
|
||||
encoded string or address.
|
||||
.PP
|
||||
\fBlwres_getaddrsbyname()\fR
|
||||
returns
|
||||
LWRES_R_SUCCESS
|
||||
on success and it returns
|
||||
LWRES_R_NOTFOUND
|
||||
if the hostname
|
||||
\fIname\fR
|
||||
could not be found.
|
||||
.PP
|
||||
LWRES_R_SUCCESS
|
||||
is returned by a successful call to
|
||||
\fBlwres_getnamebyaddr()\fR.
|
||||
.PP
|
||||
Both
|
||||
\fBlwres_getaddrsbyname()\fR
|
||||
and
|
||||
\fBlwres_getnamebyaddr()\fR
|
||||
return
|
||||
LWRES_R_NOMEMORY
|
||||
when memory allocation requests fail and
|
||||
LWRES_R_UNEXPECTEDEND
|
||||
if the buffers used for sending queries and receiving replies are too
|
||||
small.
|
||||
.SH "SEE ALSO"
|
||||
.PP
|
||||
\fBlwres_buffer\fR(3),
|
||||
\fBlwres_gabn\fR(3).
|
||||
@@ -0,0 +1,221 @@
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
|
||||
<!--
|
||||
- Copyright (C) 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
|
||||
<!-- $Id: lwres_resutil.docbook,v 1.1 2004/03/15 20:35:25 as Exp $ -->
|
||||
|
||||
<refentry>
|
||||
|
||||
<refentryinfo>
|
||||
<date>Jun 30, 2000</date>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>lwres_resutil</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>BIND9</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>lwres_string_parse</refname>
|
||||
<refname>lwres_addr_parse</refname>
|
||||
<refname>lwres_getaddrsbyname</refname>
|
||||
<refname>lwres_getnamebyaddr</refname>
|
||||
<refpurpose>lightweight resolver utility functions</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_string_parse</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>char **c</paramdef>
|
||||
<paramdef>lwres_uint16_t *len</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_addr_parse</function></funcdef>
|
||||
<paramdef>lwres_buffer_t *b</paramdef>
|
||||
<paramdef>lwres_addr_t *addr</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_getaddrsbyname</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>const char *name</paramdef>
|
||||
<paramdef>lwres_uint32_t addrtypes</paramdef>
|
||||
<paramdef>lwres_gabnresponse_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
<funcprototype>
|
||||
<funcdef>
|
||||
lwres_result_t
|
||||
<function>lwres_getnamebyaddr</function></funcdef>
|
||||
<paramdef>lwres_context_t *ctx</paramdef>
|
||||
<paramdef>lwres_uint32_t addrtype</paramdef>
|
||||
<paramdef>lwres_uint16_t addrlen</paramdef>
|
||||
<paramdef>const unsigned char *addr</paramdef>
|
||||
<paramdef>lwres_gnbaresponse_t **structp</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>DESCRIPTION</title>
|
||||
|
||||
<para>
|
||||
<function>lwres_string_parse()</function> retrieves a DNS-encoded
|
||||
string starting the current pointer of lightweight resolver buffer
|
||||
<parameter>b</parameter>: i.e. <constant>b->current</constant>.
|
||||
When the function returns, the address of the first byte of the
|
||||
encoded string is returned via <parameter>*c</parameter> and the
|
||||
length of that string is given by <parameter>*len</parameter>. The
|
||||
buffer's current pointer is advanced to point at the character
|
||||
following the string length, the encoded string, and the trailing
|
||||
<type>NULL</type> character.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_addr_parse()</function> extracts an address from the
|
||||
buffer <parameter>b</parameter>. The buffer's current pointer
|
||||
<constant>b->current</constant> is presumed to point at an encoded
|
||||
address: the address preceded by a 32-bit protocol family identifier
|
||||
and a 16-bit length field. The encoded address is copied to
|
||||
<constant>addr->address</constant> and
|
||||
<constant>addr->length</constant> indicates the size in bytes of
|
||||
the address that was copied. <constant>b->current</constant> is
|
||||
advanced to point at the next byte of available data in the buffer
|
||||
following the encoded address.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_getaddrsbyname()</function>
|
||||
and
|
||||
<function>lwres_getnamebyaddr()</function>
|
||||
use the
|
||||
<type>lwres_gnbaresponse_t</type>
|
||||
structure defined below:
|
||||
<programlisting>
|
||||
typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint16_t naliases;
|
||||
lwres_uint16_t naddrs;
|
||||
char *realname;
|
||||
char **aliases;
|
||||
lwres_uint16_t realnamelen;
|
||||
lwres_uint16_t *aliaslen;
|
||||
lwres_addrlist_t addrs;
|
||||
void *base;
|
||||
size_t baselen;
|
||||
} lwres_gabnresponse_t;
|
||||
</programlisting>
|
||||
The contents of this structure are not manipulated directly but
|
||||
they are controlled through the
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3
|
||||
</manvolnum>
|
||||
</citerefentry>
|
||||
functions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The lightweight resolver uses
|
||||
<function>lwres_getaddrsbyname()</function> to perform foward lookups.
|
||||
Hostname <parameter>name</parameter> is looked up using the resolver
|
||||
context <parameter>ctx</parameter> for memory allocation.
|
||||
<parameter>addrtypes</parameter> is a bitmask indicating which type of
|
||||
addresses are to be looked up. Current values for this bitmask are
|
||||
<type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and
|
||||
<type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the
|
||||
lookup are returned in <parameter>*structp</parameter>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>lwres_getnamebyaddr()</function> performs reverse lookups.
|
||||
Resolver context <parameter>ctx</parameter> is used for memory
|
||||
allocation. The address type is indicated by
|
||||
<parameter>addrtype</parameter>: <type>LWRES_ADDRTYPE_V4</type> or
|
||||
<type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is given
|
||||
by <parameter>addr</parameter> and its length is
|
||||
<parameter>addrlen</parameter> bytes. The result of the function call
|
||||
is made available through <parameter>*structp</parameter>.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>RETURN VALUES</title>
|
||||
<para>
|
||||
Successful calls to
|
||||
<function>lwres_string_parse()</function>
|
||||
and
|
||||
<function>lwres_addr_parse()</function>
|
||||
return
|
||||
<errorcode>LWRES_R_SUCCESS.</errorcode>
|
||||
Both functions return
|
||||
<errorcode>LWRES_R_FAILURE</errorcode>
|
||||
if the buffer is corrupt or
|
||||
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
|
||||
if the buffer has less space than expected for the components of the
|
||||
encoded string or address.
|
||||
</para>
|
||||
<para>
|
||||
<function>lwres_getaddrsbyname()</function>
|
||||
returns
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>
|
||||
on success and it returns
|
||||
<errorcode>LWRES_R_NOTFOUND</errorcode>
|
||||
if the hostname
|
||||
<parameter>name</parameter>
|
||||
could not be found.
|
||||
</para>
|
||||
<para>
|
||||
<errorcode>LWRES_R_SUCCESS</errorcode>
|
||||
is returned by a successful call to
|
||||
<function>lwres_getnamebyaddr()</function>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Both
|
||||
<function>lwres_getaddrsbyname()</function>
|
||||
and
|
||||
<function>lwres_getnamebyaddr()</function>
|
||||
return
|
||||
<errorcode>LWRES_R_NOMEMORY</errorcode>
|
||||
when memory allocation requests fail and
|
||||
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
|
||||
if the buffers used for sending queries and receiving replies are too
|
||||
small.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
<refsect1>
|
||||
<title>SEE ALSO</title>
|
||||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>,
|
||||
|
||||
<citerefentry>
|
||||
<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum>
|
||||
</citerefentry>.
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
</refentry>
|
||||
@@ -0,0 +1,412 @@
|
||||
<!--
|
||||
- Copyright (C) 2000, 2001 Internet Software Consortium.
|
||||
-
|
||||
- Permission to use, copy, modify, and distribute this software for any
|
||||
- purpose with or without fee is hereby granted, provided that the above
|
||||
- copyright notice and this permission notice appear in all copies.
|
||||
-
|
||||
- THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
- DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
- IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
- INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
- FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
- NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
-->
|
||||
<HTML
|
||||
><HEAD
|
||||
><TITLE
|
||||
>lwres_resutil</TITLE
|
||||
><META
|
||||
NAME="GENERATOR"
|
||||
CONTENT="Modular DocBook HTML Stylesheet Version 1.61
|
||||
"></HEAD
|
||||
><BODY
|
||||
CLASS="REFENTRY"
|
||||
BGCOLOR="#FFFFFF"
|
||||
TEXT="#000000"
|
||||
LINK="#0000FF"
|
||||
VLINK="#840084"
|
||||
ALINK="#0000FF"
|
||||
><H1
|
||||
><A
|
||||
NAME="AEN1"
|
||||
>lwres_resutil</A
|
||||
></H1
|
||||
><DIV
|
||||
CLASS="REFNAMEDIV"
|
||||
><A
|
||||
NAME="AEN8"
|
||||
></A
|
||||
><H2
|
||||
>Name</H2
|
||||
>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr -- lightweight resolver utility functions</DIV
|
||||
><DIV
|
||||
CLASS="REFSYNOPSISDIV"
|
||||
><A
|
||||
NAME="AEN14"
|
||||
></A
|
||||
><H2
|
||||
>Synopsis</H2
|
||||
><DIV
|
||||
CLASS="FUNCSYNOPSIS"
|
||||
><A
|
||||
NAME="AEN15"
|
||||
></A
|
||||
><P
|
||||
></P
|
||||
><PRE
|
||||
CLASS="FUNCSYNOPSISINFO"
|
||||
>#include <lwres/lwres.h></PRE
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_string_parse</CODE
|
||||
>(lwres_buffer_t *b, char **c, lwres_uint16_t *len);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_addr_parse</CODE
|
||||
>(lwres_buffer_t *b, lwres_addr_t *addr);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_getaddrsbyname</CODE
|
||||
>(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
><CODE
|
||||
><CODE
|
||||
CLASS="FUNCDEF"
|
||||
>lwres_result_t
|
||||
lwres_getnamebyaddr</CODE
|
||||
>(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, lwres_gnbaresponse_t **structp);</CODE
|
||||
></P
|
||||
><P
|
||||
></P
|
||||
></DIV
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN43"
|
||||
></A
|
||||
><H2
|
||||
>DESCRIPTION</H2
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_string_parse()</TT
|
||||
> retrieves a DNS-encoded
|
||||
string starting the current pointer of lightweight resolver buffer
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>: i.e. <TT
|
||||
CLASS="CONSTANT"
|
||||
>b->current</TT
|
||||
>.
|
||||
When the function returns, the address of the first byte of the
|
||||
encoded string is returned via <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*c</I
|
||||
></TT
|
||||
> and the
|
||||
length of that string is given by <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*len</I
|
||||
></TT
|
||||
>. The
|
||||
buffer's current pointer is advanced to point at the character
|
||||
following the string length, the encoded string, and the trailing
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>NULL</SPAN
|
||||
> character.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_addr_parse()</TT
|
||||
> extracts an address from the
|
||||
buffer <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>b</I
|
||||
></TT
|
||||
>. The buffer's current pointer
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>b->current</TT
|
||||
> is presumed to point at an encoded
|
||||
address: the address preceded by a 32-bit protocol family identifier
|
||||
and a 16-bit length field. The encoded address is copied to
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>addr->address</TT
|
||||
> and
|
||||
<TT
|
||||
CLASS="CONSTANT"
|
||||
>addr->length</TT
|
||||
> indicates the size in bytes of
|
||||
the address that was copied. <TT
|
||||
CLASS="CONSTANT"
|
||||
>b->current</TT
|
||||
> is
|
||||
advanced to point at the next byte of available data in the buffer
|
||||
following the encoded address.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrsbyname()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getnamebyaddr()</TT
|
||||
>
|
||||
use the
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>lwres_gnbaresponse_t</SPAN
|
||||
>
|
||||
structure defined below:
|
||||
<PRE
|
||||
CLASS="PROGRAMLISTING"
|
||||
>typedef struct {
|
||||
lwres_uint32_t flags;
|
||||
lwres_uint16_t naliases;
|
||||
lwres_uint16_t naddrs;
|
||||
char *realname;
|
||||
char **aliases;
|
||||
lwres_uint16_t realnamelen;
|
||||
lwres_uint16_t *aliaslen;
|
||||
lwres_addrlist_t addrs;
|
||||
void *base;
|
||||
size_t baselen;
|
||||
} lwres_gabnresponse_t;</PRE
|
||||
>
|
||||
The contents of this structure are not manipulated directly but
|
||||
they are controlled through the
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_gabn</SPAN
|
||||
>(3)</SPAN
|
||||
>
|
||||
functions.</P
|
||||
><P
|
||||
>The lightweight resolver uses
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrsbyname()</TT
|
||||
> to perform foward lookups.
|
||||
Hostname <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>name</I
|
||||
></TT
|
||||
> is looked up using the resolver
|
||||
context <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
> for memory allocation.
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>addrtypes</I
|
||||
></TT
|
||||
> is a bitmask indicating which type of
|
||||
addresses are to be looked up. Current values for this bitmask are
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>LWRES_ADDRTYPE_V4</SPAN
|
||||
> for IPv4 addresses and
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>LWRES_ADDRTYPE_V6</SPAN
|
||||
> for IPv6 addresses. Results of the
|
||||
lookup are returned in <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*structp</I
|
||||
></TT
|
||||
>.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getnamebyaddr()</TT
|
||||
> performs reverse lookups.
|
||||
Resolver context <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>ctx</I
|
||||
></TT
|
||||
> is used for memory
|
||||
allocation. The address type is indicated by
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>addrtype</I
|
||||
></TT
|
||||
>: <SPAN
|
||||
CLASS="TYPE"
|
||||
>LWRES_ADDRTYPE_V4</SPAN
|
||||
> or
|
||||
<SPAN
|
||||
CLASS="TYPE"
|
||||
>LWRES_ADDRTYPE_V6</SPAN
|
||||
>. The address to be looked up is given
|
||||
by <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>addr</I
|
||||
></TT
|
||||
> and its length is
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>addrlen</I
|
||||
></TT
|
||||
> bytes. The result of the function call
|
||||
is made available through <TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>*structp</I
|
||||
></TT
|
||||
>.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN84"
|
||||
></A
|
||||
><H2
|
||||
>RETURN VALUES</H2
|
||||
><P
|
||||
>Successful calls to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_string_parse()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_addr_parse()</TT
|
||||
>
|
||||
return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS.</SPAN
|
||||
>
|
||||
Both functions return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_FAILURE</SPAN
|
||||
>
|
||||
if the buffer is corrupt or
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_UNEXPECTEDEND</SPAN
|
||||
>
|
||||
if the buffer has less space than expected for the components of the
|
||||
encoded string or address.</P
|
||||
><P
|
||||
><TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrsbyname()</TT
|
||||
>
|
||||
returns
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>
|
||||
on success and it returns
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_NOTFOUND</SPAN
|
||||
>
|
||||
if the hostname
|
||||
<TT
|
||||
CLASS="PARAMETER"
|
||||
><I
|
||||
>name</I
|
||||
></TT
|
||||
>
|
||||
could not be found.</P
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_SUCCESS</SPAN
|
||||
>
|
||||
is returned by a successful call to
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getnamebyaddr()</TT
|
||||
>.</P
|
||||
><P
|
||||
>Both
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getaddrsbyname()</TT
|
||||
>
|
||||
and
|
||||
<TT
|
||||
CLASS="FUNCTION"
|
||||
>lwres_getnamebyaddr()</TT
|
||||
>
|
||||
return
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_NOMEMORY</SPAN
|
||||
>
|
||||
when memory allocation requests fail and
|
||||
<SPAN
|
||||
CLASS="ERRORCODE"
|
||||
>LWRES_R_UNEXPECTEDEND</SPAN
|
||||
>
|
||||
if the buffers used for sending queries and receiving replies are too
|
||||
small.</P
|
||||
></DIV
|
||||
><DIV
|
||||
CLASS="REFSECT1"
|
||||
><A
|
||||
NAME="AEN105"
|
||||
></A
|
||||
><H2
|
||||
>SEE ALSO</H2
|
||||
><P
|
||||
><SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_buffer</SPAN
|
||||
>(3)</SPAN
|
||||
>,
|
||||
|
||||
<SPAN
|
||||
CLASS="CITEREFENTRY"
|
||||
><SPAN
|
||||
CLASS="REFENTRYTITLE"
|
||||
>lwres_gabn</SPAN
|
||||
>(3)</SPAN
|
||||
>.</P
|
||||
></DIV
|
||||
></BODY
|
||||
></HTML
|
||||
>
|
||||
Reference in New Issue
Block a user