upstream/bind9
1
0
Fork 0
mirror of https://github.com/isc-projects/bind9.git synced 2026-06-11 11:09:59 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

man page docbook conversion

Browse source
This commit is contained in:
Andreas Gustafsson 2001-03-31 00:08:23 +00:00
parent 0b062f4990
commit ddccd5811f
52 changed files with 12732 additions and 1853 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

104
lib/lwres/man/Makefile.in
View file

@ -7,48 +7,68 @@ top_srcdir = @top_srcdir@
@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_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

185
lib/lwres/man/lwres.3
View file

@ -12,140 +12,145 @@
.\" 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.3,v 1.9 2001/01/09 21:48:52 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres
.Nd introduction to the lightweight resolver library
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Sh DESCRIPTION
.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
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
.Nm lwresd
\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.
and returns the results to the application through the library.
The library and resolver daemon communicate using a simple
UDP-based protocol.
.Pp
.Sh OVERVIEW
.SH "OVERVIEW"
.PP
The lwresd library implements multiple name service APIs.
The standard
.Fn gethostbyname ,
.Fn gethostbyaddr ,
.Fn gethostbyname_r ,
.Fn gethostbyaddr_r ,
.Fn getaddrinfo ,
.Fn getipnodebyname ,
\fBgethostbyname()\fR,
\fBgethostbyaddr()\fR,
\fBgethostbyname_r()\fR,
\fBgethostbyaddr_r()\fR,
\fBgetaddrinfo()\fR,
\fBgetipnodebyname()\fR,
and
.Fn getipnodebyaddr
functions are all supported. To allow the lwres library to coexist
with system libraries that define functions of the same name,
\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
.Va lwres_ .
lwres_.
To define the standard names, applications must include the
header file
.Fd <lwres/netdb.h>
\fI<lwres/netdb.h>\fR
which contains macro definitions mapping the standard function names
into
.Va lwres_
prefixed ones. Operating system vendors who integrate the lwres
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
.PP
The library also provides a native API consisting of the functions
.Fn lwres_getaddrsbyname
\fBlwres_getaddrsbyname()\fR
and
.Fn lwres_getnamebyaddr .
\fBlwres_getnamebyaddr()\fR.
These may be called by applications that require more detailed
control over the lookup process than the standard functions
provide.
.Pp
.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
.Fn lwres_getaddrsbyname
\fBlwres_getaddrsbyname()\fR
function.
.Pp
.PP
Finally, there is a low-level API for converting lookup
requests and responses to and from raw lwres protocol packets.
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
.Nm lwresd
resolver daemon. The use of this low-level API in clients
\fBlwresd\fR
resolver daemon. The use of this low-level API in clients
and servers is outlined in the following sections.
.P
.Sh CLIENT-SIDE LOW-LEVEL API CALL FLOW
.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 lwres_packet_t, called "pkt" below.
.Pp
(2) Set pkt.recvlength to the maximum length we will accept.
.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 lwres.h: LWRES_RECVLENGTH = 4096.
.Pp
(3) Set the pkt.serial to a unique serial number. This value is echoed
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 pkt.pktflags. Usually this is set to 0.
.Pp
(5) Set pkt.result to 0.
.Pp
(6) Call lwres_*request_render, or marshall in the data using the primitives
such as lwres_packet_render() and storing the packet data.
.Pp
.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 lwres_*response_parse() to parse any packets received.
.Pp
.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
.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 lwres_packet_t is used
in both the _parse() and _render() calls, with only a few modifications made
to the packet header's contents between uses. This method is recommended
.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 lwres_*request_parse() to
unmarshall it. This returns a lwres_packet_t (also called pkt, below)
as well as a data specific type, such as lwres_gabnrequest_t.
.Pp
.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 pkt.result, pkt.recvlength as above. All other fields can
be left untouched since they were filled in by the *_parse() call
above. If using lwres_*response_render(), pkt.pktflags will be set up
properly. Otherwise, the LWRES_LWPACKETFLAG_RESPONSE bit should be
.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
.PP
(4) Call the data specific rendering function, such as
lwres_gabnresponse_render().
.Pp
\fBlwres_gabnresponse_render()\fR.
.PP
(5) Send the resulting packet to the client.
.Pp
.Sh SEE ALSO
.Xr lwres_gethostent 3 ,
.Xr lwres_getipnode 3 ,
.Xr lwres_getnameinfo 3 ,
.Xr lwres_noop 3 ,
.Xr lwres_gabn 3 ,
.Xr lwres_gnba 3 ,
.Xr lwres_context 3 ,
.Xr lwres_config 3 ,
.Xr resolver 5 ,
.Xr lwresd 8 .
.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).

14
lib/lwres/man/lwres.docbook
View file

@ -16,18 +16,18 @@
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres.docbook,v 1.1 2001/03/29 02:43:28 gson Exp $ -->
<!-- $Id: lwres.docbook,v 1.2 2001/03/31 00:08:00 gson Exp $ -->
<refentry>
<refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres</refname>
<refpurpose>introduction to the lightweight resolver library</refpurpose>

444
lib/lwres/man/lwres.html Normal file
View file

@ -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&nbsp;--&nbsp;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 &lt;lwres/lwres.h&gt;</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"
>&lt;lwres/netdb.h&gt;</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
>.&#13;</P
></DIV
></BODY
></HTML
>

330
lib/lwres/man/lwres_buffer.3
View file

@ -12,155 +12,117 @@
.\" 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.3,v 1.6 2001/01/09 21:48:54 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_BUFFER 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_buffer_init ,
.Nm lwres_buffer_invalidate ,
.Nm lwres_buffer_add ,
.Nm lwres_buffer_subtract ,
.Nm lwres_buffer_clear ,
.Nm lwres_buffer_first ,
.Nm lwres_buffer_forward ,
.Nm lwres_buffer_back ,
.Nm lwres_buffer_getuint8 ,
.Nm lwres_buffer_putuint8 ,
.Nm lwres_buffer_getuint16 ,
.Nm lwres_buffer_putuint16 ,
.Nm lwres_buffer_getuint32 ,
.Nm lwres_buffer_putuint32 ,
.Nm lwres_buffer_putmem ,
.Nm lwres_buffer_getmem
.Nd lightweight resolver buffer management
.Sh SYNOPSIS
.Fd #include <lwres/lwbuffer.h>
.Fd
.Ft void
.Fo lwres_buffer_init
.Fa "lwres_buffer_t *b"
.Fa "void *base"
.Fa "unsigned int length"
.Fc
.Ft void
.Fo lwres_buffer_invalidate
.Fa "lwres_buffer_t *b"
.Fc
.Ft void
.Fo lwres_buffer_add
.Fa "lwres_buffer_t *b"
.Fa "unsigned int n"
.Fc
.Ft void
.Fo lwres_buffer_subtract
.Fa "lwres_buffer_t *b"
.Fa "unsigned int n"
.Fc
.Ft void
.Fo lwres_buffer_clear
.Fa "lwres_buffer_t *b"
.Fc
.Ft void
.Fo lwres_buffer_first
.Fa "lwres_buffer_t *b"
.Fc
.Ft void
.Fo lwres_buffer_forward
.Fa "lwres_buffer_t *b"
.Fa "unsigned int n"
.Fc
.Ft void
.Fo lwres_buffer_back
.Fa "lwres_buffer_t *b"
.Fa "unsigned int n"
.Fc
.Ft lwres_uint8_t
.Fo lwres_buffer_getuint8
.Fa "lwres_buffer_t *b"
.Fc
.Ft void
.Fo lwres_buffer_putuint8
.Fa "lwres_buffer_t *b"
.Fa "lwres_uint8_t val"
.Fc
.Ft lwres_uint16_t
.Fo lwres_buffer_getuint16
.Fa "lwres_buffer_t *b"
.Fc
.Ft void
.Fo lwres_buffer_putuint16
.Fa "lwres_buffer_t *b"
.Fa "lwres_uint16_t val"
.Fc
.Ft lwres_uint32_t
.Fo lwres_buffer_getuint32
.Fa "lwres_buffer_t *b"
.Fc
.Ft void
.Fo lwres_buffer_putuint32
.Fa "lwres_buffer_t *b"
.Fa "lwres_uint32_t val"
.Fc
.Ft void
.Fo lwres_buffer_putmem
.Fa "lwres_buffer_t *b"
.Fa "const unsigned char *base"
.Fa "unsigned int length"
.Fc
.Ft void
.Fo lwres_buffer_getmem
.Fa "lwres_buffer_t *b"
.Fa "unsigned char *base"
.Fa "unsigned int length"
.Fc
.Sh DESCRIPTION
.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
void
lwres_buffer_init(lwres_buffer_t *b);
(void *base);
(unsigned int length);
.sp
void
lwres_buffer_invalidate(lwres_buffer_t *b);
.sp
void
lwres_buffer_add(lwres_buffer_t *b);
(unsigned int n);
.sp
void
lwres_buffer_subtract(lwres_buffer_t *b);
(unsigned int n);
.sp
void
lwres_buffer_clear(lwres_buffer_t *b);
.sp
void
lwres_buffer_first(lwres_buffer_t *b);
.sp
void
lwres_buffer_forward(lwres_buffer_t *b);
(unsigned int n);
.sp
void
lwres_buffer_back(lwres_buffer_t *b);
(unsigned int n);
.sp
lwres_uint8_t
lwres_buffer_getuint8(lwres_buffer_t *b);
.sp
void
lwres_buffer_putuint8(lwres_buffer_t *b);
(lwres_uint8_t val);
.sp
lwres_uint16_t
lwres_buffer_getuint16(lwres_buffer_t *b);
.sp
void
lwres_buffer_putuint16(lwres_buffer_t *b);
(lwres_uint16_t val);
.sp
lwres_uint32_t
lwres_buffer_getuint32(lwres_buffer_t *b);
.sp
void
lwres_buffer_putuint32(lwres_buffer_t *b);
(lwres_uint32_t val);
.sp
void
lwres_buffer_putmem(lwres_buffer_t *b);
(const unsigned char *base);
(unsigned int length);
.sp
void
lwres_buffer_getmem(lwres_buffer_t *b);
(unsigned char *base);
(unsigned int length);
\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
.Va isc_buffer_
isc_buffer_
functions in the ISC library.
.Pp
.PP
A buffer is a region of memory, together with a set of related
subregions.
The \*qused region\*q and the \*qavailable\*q region are disjoint, and
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.
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
.PP
The used region is further subdivided into two disjoint regions: the
\*qconsumed region\*q and the \*qremaining region\*q.
\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 \*qcurrent\*q offset (if any).
The \*qremaining\*q region the current pointer to the end of the used
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 \*qactive region\*q is an (optional) subregion of the remaining
.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
.Bd -literal -offset indent
.PP
.sp
.nf
/------------entire length---------------\\
/----- used region -----\\/-- available --\\
/------------entire length---------------\\\\
/----- used region -----\\\\/-- available --\\\\
+----------------------------------------+
| consumed | remaining | |
+----------------------------------------+
@ -177,118 +139,118 @@ the active region will also be empty.
a-b == consumed region.
b-d == remaining region.
b-c == optional active region.
.Ed
.Pp
.Fn lwres_buffer_init
.sp
.fi
.PP
\fBlwres_buffer_init()\fR
initializes the
.Dv lwres_buffer_t
.Fa *b
\fBlwres_buffer_t\fR
\fI*b\fR
and assocates it with the memory region of size
.Fa length
\fIlength\fR
bytes starting at location
.Fa base.
.Pp
.Fn lwres_buffer_invalidate
\fIbase.\fR
.PP
\fBlwres_buffer_invalidate()\fR
marks the buffer
.Fa *b
as invalid. Invalidating a buffer after use is not required,
\fI*b\fR
as invalid. Invalidating a buffer after use is not required,
but makes it possible to catch its possible accidental use.
.Pp
.PP
The functions
.Fn lwres_buffer_add
\fBlwres_buffer_add()\fR
and
.Fn lwres_buffer_subtract
\fBlwres_buffer_subtract()\fR
respectively increase and decrease the used space in
buffer
.Fa *b
\fI*b\fR
by
.Fa n
\fIn\fR
bytes.
.Fn lwres_buffer_add
\fBlwres_buffer_add()\fR
checks for buffer overflow and
.Fn lwres_buffer_subtract
\fBlwres_buffer_subtract()\fR
checks for underflow.
These functions do not allocate or deallocate memory.
They just change the value of
.Li used .
.Pp
\fBused\fR.
.PP
A buffer is re-initialised by
.Fn lwres_buffer_clear .
\fBlwres_buffer_clear()\fR.
The function sets
.Li used ,
.Li current
\fBused\fR ,
\fBcurrent\fR
and
.Li active
\fBactive\fR
to zero.
.Pp
.Fn lwres_buffer_first
.PP
\fBlwres_buffer_first\fR
makes the consumed region of buffer
.Fa *p
\fI*p\fR
empty by setting
.Li current
\fBcurrent\fR
to zero (the start of the buffer).
.Pp
.Fn lwres_buffer_forward
.PP
\fBlwres_buffer_forward()\fR
increases the consumed region of buffer
.Fa *b
\fI*b\fR
by
.Fa n
\fIn\fR
bytes, checking for overflow.
Similarly,
.Fn lwres_buffer_back
\fBlwres_buffer_back()\fR
decreases buffer
.Fa b 's
\fIb\fR's
consumed region by
.Fa n
\fIn\fR
bytes and checks for underflow.
.Pp
.Fn lwres_buffer_getuint8
.PP
\fBlwres_buffer_getuint8()\fR
reads an unsigned 8-bit integer from
.Fa *b
\fI*b\fR
and returns it.
.Fn lwres_buffer_putuint8
\fBlwres_buffer_putuint8()\fR
writes the unsigned 8-bit integer
.Fa val
\fIval\fR
to buffer
.Fa *b .
.Pp
.Fn lwres_buffer_getuint16
\fI*b\fR.
.PP
\fBlwres_buffer_getuint16()\fR
and
.Fn lwres_buffer_getuint32
\fBlwres_buffer_getuint32()\fR
are identical to
.Fn lwres_buffer_putuint8
\fBlwres_buffer_putuint8()\fR
except that they respectively read an unsigned 16-bit or 32-bit integer
in network byte order from
.Fa b .
\fIb\fR.
Similarly,
.Fn lwres_buffer_putuint16
\fBlwres_buffer_putuint16()\fR
and
.Fn lwres_buffer_putuint32
\fBlwres_buffer_putuint32()\fR
writes the unsigned 16-bit or 32-bit integer
.Fa val
\fIval\fR
to buffer
.Fa b ,
\fIb\fR,
in network byte order.
.Pp
.PP
Arbitrary amounts of data are read or written from a lightweight
resolver buffer with
.Fn lwres_buffer_getmem
\fBlwres_buffer_getmem()\fR
and
.Fn lwres_buffer_putmem
\fBlwres_buffer_putmem()\fR
respectively.
.Fn lwres_buffer_putmem
\fBlwres_buffer_putmem()\fR
copies
.Fa length
\fIlength\fR
bytes of memory at
.Fa base
\fIbase\fR
to
.Fa b.
\fIb\fR.
Conversely,
.Fn lwres_buffer_getmem
\fBlwres_buffer_getmem()\fR
copies
.Fa length
\fIlength\fR
bytes of memory from
.Fa b
\fIb\fR
to
.Fa base .
.Sh SEE ALSO
\fIbase\fR.

10
lib/lwres/man/lwres_buffer.docbook
View file

@ -16,17 +16,17 @@
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_buffer.docbook,v 1.1 2001/03/29 02:23:11 gson Exp $ -->
<!-- $Id: lwres_buffer.docbook,v 1.2 2001/03/31 00:08:02 gson Exp $ -->
<refentry>
<refentryinfo>
<refentryinfo>
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_buffer</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
<refentrytitle>lwres_buffer</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>

608
lib/lwres/man/lwres_buffer.html Normal file
View file

@ -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&nbsp;--&nbsp;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 &lt;lwres/lwbuffer.h&gt;</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
>

133
lib/lwres/man/lwres_config.3
View file

@ -12,97 +12,84 @@
.\" 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.3,v 1.6 2001/01/09 21:49:18 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_CONFIG 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_conf_init ,
.Nm lwres_conf_clear ,
.Nm lwres_conf_parse ,
.Nm lwres_conf_print ,
.Nm lwres_conf_get
.Nd lightweight resolver configuration
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
.Ft void
.Fo lwres_conf_init
.Fa "lwres_context_t *ctx"
.Fc
.Ft void
.Fo lwres_conf_clear
.Fa "lwres_context_t *ctx"
.Fc
.Ft lwres_result_t
.Fo lwres_conf_parse
.Fa "lwres_context_t *ctx"
.Fa "const char *filename"
.Fc
.Ft lwres_result_t
.Fo lwres_conf_print
.Fa "lwres_context_t *ctx"
.Fa "FILE *fp"
.Fc
.Ft lwres_conf_t *
.Fo lwres_conf_get
.Fa "lwres_context_t *ctx"
.Fc
.Sh DESCRIPTION
.Fn lwres_conf_init
.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
void
lwres_conf_init(lwres_context_t *ctx);
.sp
void
lwres_conf_clear(lwres_context_t *ctx);
.sp
lwres_result_t
lwres_conf_parse(lwres_context_t *ctx);
(const char *filename);
.sp
lwres_result_t
lwres_conf_print(lwres_context_t *ctx);
(FILE *fp);
.sp
lwres_conf_t *
lwres_conf_get(lwres_context_t *ctx);
\fR.SH "DESCRIPTION"
.PP
\fBlwres_conf_init()\fR
creates an empty
.Dv lwres_conf_t
\fBlwres_conf_t\fR
structure for lightweight resolver context
.Fa ctx .
.Pp
.Fn lwres_conf_clear
\fIctx\fR.
.PP
\fBlwres_conf_clear()\fR
frees up all the internal memory used by
that
.Dv lwres_conf_t
\fBlwres_conf_t\fR
structure in resolver context
.Fa ctx .
.Pp
.Fn lwres_conf_parse
\fIctx\fR.
.PP
\fBlwres_conf_parse()\fR
opens the file
.Fa filename
\fIfilename\fR
and parses it to initialise the resolver context
.Fa ctx 's
.Dv lwres_conf_t
\fIctx\fR's
\fBlwres_conf_t\fR
structure.
.Pp
.Fn lwres_conf_print
.PP
\fBlwres_conf_print()\fR
prints the
.Dv lwres_conf_t
\fBlwres_conf_t\fR
structure for resolver context
.Fa ctx
\fIctx\fR
to the
.Dv FILE
.Fa fp.
.Sh RETURN VALUES
.Fn lwres_conf_parse
\fBFILE\fR
\fIfp\fR.
.SH "RETURN VALUES"
.PP
\fBlwres_conf_parse()\fR
returns
.Er LWRES_R_SUCCESS
LWRES_R_SUCCESS
if it successfully read and parsed
.Fa filename .
\fIfilename\fR.
It returns
.Er LWRES_R_FAILURE
LWRES_R_FAILURE
if
.Fa filename
\fIfilename\fR
could not be opened or contained incorrect
resolver statements.
.Pp
.Fn lwres_conf_print
.PP
\fBlwres_conf_print()\fR
returns
.Er LWRES_R_SUCCESS
LWRES_R_SUCCESS
unless an error occurred when converting the network addresses to a
numeric host address string.
If this happens, the function returns
.Er LWRES_R_FAILURE .
.Sh SEE ALSO
.Xr stdio 3 ,
.Xr resolver 5 .
.Sh FILES
.Pa /etc/resolv.conf
LWRES_R_FAILURE.
.SH "SEE ALSO"
.PP
\fBstdio\fR(3),
\fBresolver\fR(5).
.SH "FILES"
.PP
\fI/etc/resolv.conf\fR

159
lib/lwres/man/lwres_config.docbook Normal file
View file

@ -0,0 +1,159 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_config.docbook,v 1.1 2001/03/31 00:08:04 gson 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 &lt;lwres/lwres.h&gt;</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>

295
lib/lwres/man/lwres_config.html Normal file
View file

@ -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&nbsp;--&nbsp;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 &lt;lwres/lwres.h&gt;</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
>

246
lib/lwres/man/lwres_context.3
View file

@ -12,201 +12,183 @@
.\" 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.3,v 1.6 2001/01/09 21:49:19 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_CONTEXT 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_context_create ,
.Nm lwres_context_destroy ,
.Nm lwres_context_nextserial ,
.Nm lwres_context_initserial ,
.Nm lwres_context_freemem ,
.Nm lwres_context_allocmem ,
.Nm lwres_context_sendrecv
.Nd lightweight resolver context management
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
.Ft lwres_result_t
.Fo lwres_context_create
.Fa "lwres_context_t **contextp"
.Fa "void *arg"
.Fa "lwres_malloc_t malloc_function"
.Fa "lwres_free_t free_function"
.Fc
.Ft lwres_result_t
.Fo lwres_context_destroy
.Fa "lwres_context_t **contextp"
.Fc
.Ft void
.Fo lwres_context_initserial
.Fa "lwres_context_t *ctx"
.Fa "lwres_uint32_t serial"
.Fc
.Ft lwres_uint32_t
.Fo lwres_context_nextserial
.Fa "lwres_context_t *ctx"
.Fc
.Ft void
.Fo lwres_context_freemem
.Fa "lwres_context_t *ctx"
.Fa "void *mem"
.Fa "size_t len"
.Fc
.Ft void
.Fo lwres_context_allocmem
.Fa "lwres_context_t *ctx"
.Fa "size_t len"
.Fc
.Ft void *
.Fo lwres_context_sendrecv
.Fa "lwres_context_t *ctx"
.Fa "void *sendbase"
.Fa "int sendlen"
.Fa "void *recvbase"
.Fa "int recvlen"
.Fa "int *recvd_len"
.Fc
.Sh DESCRIPTION
.Fn lwres_context_create
.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
lwres_result_t
lwres_context_create(lwres_context_t **contextp);
(void *arg);
(lwres_malloc_t malloc_function);
(lwres_free_t free_function);
.sp
lwres_result_t
lwres_context_destroy(lwres_context_t **contextp);
.sp
void
lwres_context_initserial(lwres_context_t *ctx);
(lwres_uint32_t serial);
.sp
lwres_uint32_t
lwres_context_nextserial(lwres_context_t *ctx);
.sp
void
lwres_context_freemem(lwres_context_t *ctx);
(void *mem);
(size_t len);
.sp
void
lwres_context_allocmem(lwres_context_t *ctx);
(size_t len);
.sp
void *
lwres_context_sendrecv(lwres_context_t *ctx);
(void *sendbase);
(int sendlen);
(void *recvbase);
(int recvlen);
(int *recvd_len);
\fR.SH "DESCRIPTION"
.PP
\fBlwres_context_create()\fR
creates a
.Dv lwres_context_t
\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
.Dv lwres_context_t
\fBlwres_context_t\fR
is returned throught
.Fa contextp ,
\fIcontextp\fR,
a pointer to a
.Dv "lwres_context_t"
pointer. This
.Dv "lwres_context_t"
\fBlwres_context_t\fR
pointer. This
\fBlwres_context_t\fR
pointer must initially be NULL, and is modified
to point to the newly created
.Dv "lwres_context_t" .
.Pp
\fBlwres_context_t\fR.
.PP
When the lightweight resolver needs to perform dynamic memory
allocation, it will call
.Fa malloc_function
\fImalloc_function\fR
to allocate memory and
.Fa free_function
to free it. If
.Fa malloc_function
\fIfree_function\fR
to free it. If
\fImalloc_function\fR
and
.Fa free_function
\fIfree_function\fR
are NULL, memory is allocated using
.Xr malloc 3
\&.Xr malloc 3
and
.Xr free 3 .
\fBfree\fR(3).
It is not permitted to have a NULL
.Fa malloc_function
\fImalloc_function\fR
and a non-NULL
.Fa free_function
\fIfree_function\fR
or vice versa.
.Fa arg
\fIarg\fR
is passed as the first parameter to the memory
allocation functions.
allocation functions.
If
.Fa malloc_function
\fImalloc_function\fR
and
.Fa free_function
\fIfree_function\fR
are NULL,
.Fa arg
\fIarg\fR
is unused and should be passed as NULL.
.P
.PP
Once memory for the structure has been allocated,
it is initialized using
.Xr lwres_conf_init 3
\fBlwres_conf_init\fR(3)
and returned via
.Fa *contextp .
.Pp
.Fn lwres_context_destroy
\fI*contextp\fR.
.PP
\fBlwres_context_destroy()\fR
destroys a
.Dv "lwres_context_t" ,
\fBlwres_context_t\fR,
closing its socket.
.Fa contextp
\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
.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
.Fn lwres_context_initserial
\fBlwres_context_initserial()\fR
and
.Fn lwres_context_nextserial .
.Fn lwres_context_initserial
\fBlwres_context_nextserial()\fR.
\fBlwres_context_initserial()\fR
sets the serial number for context
.Fa *ctx
\fI*ctx\fR
to
.Fa serial .
.Fn lwres_context_nextserial
\fIserial\fR.
\fBlwres_context_nextserial()\fR
increments the serial number and returns the previous value.
.Pp
.PP
Memory for a lightweight resolver context is allocated and freed using
.Fn lwres_context_allocmem
\fBlwres_context_allocmem()\fR
and
.Fn lwres_context_freemem .
\fBlwres_context_freemem()\fR.
These use whatever allocations were defined when the context was
created with
.Fn lwres_context_create .
.Fn lwres_context_allocmem
\fBlwres_context_create()\fR.
\fBlwres_context_allocmem()\fR
allocates
.Fa len
\fIlen\fR
bytes of memory and if successful returns a pointer to the allocated
storage.
.Fn lwres_context_allocmem
\fBlwres_context_allocmem()\fR
checks that
.Fa len
\fIlen\fR
must be greater than 0.
.Fn lwres_context_freemem
\fBlwres_context_freemem()\fR
frees
.Fa len
\fIlen\fR
bytes of space starting at location
.Fa mem .
.Pp
.Fn lwres_context_sendrecv
\fImem\fR.
.PP
\fBlwres_context_sendrecv()\fR
performs I/O for the context
.Fa ctx .
\fIctx\fR.
Data are read and written from the context's socket.
It writes data from
.Fa sendbase
- typically a lightweight resolver query packet -
\fIsendbase\fR
\(em typically a lightweight resolver query packet \(em
and waits for a reply which is copied to the receive buffer at
.Fa recvbase .
\fIrecvbase\fR.
The number of bytes that were written to this receive buffer is
returned in
.Fa *recvd_len .
.Sh RETURN VALUES
.Fn lwres_context_create
\fI*recvd_len\fR.
.SH "RETURN VALUES"
.PP
\fBlwres_context_create()\fR
returns
.Er LWRES_R_NOMEMORY
LWRES_R_NOMEMORY
if memory for the
.Dv "struct lwres_context"
\fBstruct lwres_context\fR
could not be allocated,
.Er LWRES_R_SUCCESS
LWRES_R_SUCCESS
otherwise.
.Pp
.PP
Successful calls to the memory allocator
.Fn lwres_context_allocmem
\fBlwres_context_allocmem()\fR
return a pointer to the start of the allocated space.
It returns NULL if memory could not be allocated.
.Pp
.Er LWRES_R_SUCCESS
.PP
LWRES_R_SUCCESS
is returned when
.Fn lwres_context_sendrecv
\fBlwres_context_sendrecv()\fR
completes successfully.
.Er LWRES_R_IOERROR
LWRES_R_IOERROR
is returned if an I/O error occurs and
.Er LWRES_R_TIMEOUT
LWRES_R_TIMEOUT
is returned if
.Fn lwres_context_sendrecv
\fBlwres_context_sendrecv()\fR
times out waiting for a response.
.Sh SEE ALSO
.Xr lwres_conf_init 3 ,
.Xr malloc 3 ,
.Xr free 3
.SH "SEE ALSO"
.PP
\fBlwres_conf_init\fR(3),
\fBmalloc\fR(3),
\fBfree\fR(3).

287
lib/lwres/man/lwres_context.docbook Normal file
View file

@ -0,0 +1,287 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_context.docbook,v 1.1 2001/03/31 00:08:06 gson 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 &lt;lwres/lwres.h&gt;</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_allocmem()</function>
checks that
<parameter>len</parameter>
must be greater than 0.
<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>
&mdash; typically a lightweight resolver query packet &mdash;
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>

531
lib/lwres/man/lwres_context.html Normal file
View file

@ -0,0 +1,531 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/lwres.h&gt;</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
>.&#13;</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
>.&#13;</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_allocmem()</TT
>
checks that
<TT
CLASS="PARAMETER"
><I
>len</I
></TT
>
must be greater than 0.
<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
>.&#13;</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
>
&mdash; typically a lightweight resolver query packet &mdash;
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
>.&#13;</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN117"
></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="AEN132"
></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
>

210
lib/lwres/man/lwres_gabn.3
View file

@ -12,83 +12,66 @@
.\" 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.3,v 1.6 2001/01/09 21:49:33 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_GABN 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_gabnrequest_render ,
.Nm lwres_gabnresponse_render ,
.Nm lwres_gabnrequest_parse ,
.Nm lwres_gabnresponse_parse ,
.Nm lwres_gabnresponse_free ,
.Nm lwres_gabnrequest_free
.Nd lightweight resolver getaddrbyname message handling
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
.Ft lwres_result_t
.Fo lwres_gabnrequest_render
.Fa "lwres_context_t *ctx"
.Fa "lwres_gabnrequest_t *req"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_buffer_t *b"
.Fc
.Ft lwres_result_t
.Fo lwres_gabnresponse_render
.Fa "lwres_context_t *ctx"
.Fa "lwres_gabnresponse_t *req"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_buffer_t *b"
.Fc
.Ft lwres_result_t
.Fo lwres_gabnrequest_parse
.Fa "lwres_context_t *ctx"
.Fa "lwres_buffer_t *b"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_gabnrequest_t **structp"
.Fc
.Ft lwres_result_t
.Fo lwres_gabnresponse_parse
.Fa "lwres_context_t *ctx"
.Fa "lwres_buffer_t *b"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_gabnresponse_t **structp"
.Fc
.Ft void
.Fo lwres_gabnresponse_free
.Fa "lwres_context_t *ctx"
.Fa "lwres_gabnresponse_t **structp"
.Fc
.Ft void
.Fo lwres_gabnrequest_free
.Fa "lwres_context_t *ctx"
.Fa "lwres_gabnrequest_t **structp"
.Fc
.Sh DESCRIPTION
.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
lwres_result_t
lwres_gabnrequest_render(lwres_context_t *ctx);
(lwres_gabnrequest_t *req);
(lwres_lwpacket_t *pkt);
(lwres_buffer_t *b);
.sp
lwres_result_t
lwres_gabnresponse_render(lwres_context_t *ctx);
(lwres_gabnresponse_t *req);
(lwres_lwpacket_t *pkt);
(lwres_buffer_t *b);
.sp
lwres_result_t
lwres_gabnrequest_parse(lwres_context_t *ctx);
(lwres_buffer_t *b);
(lwres_lwpacket_t *pkt);
(lwres_gabnrequest_t **structp);
.sp
lwres_result_t
lwres_gabnresponse_parse(lwres_context_t *ctx);
(lwres_buffer_t *b);
(lwres_lwpacket_t *pkt);
(lwres_gabnresponse_t **structp);
.sp
void
lwres_gabnresponse_free(lwres_context_t *ctx);
(lwres_gabnresponse_t **structp);
.sp
void
lwres_gabnrequest_free(lwres_context_t *ctx);
(lwres_gabnrequest_t **structp);
\fR.SH "DESCRIPTION"
.PP
These are low-level routines for creating and parsing
lightweight resolver name-to-address lookup request and
response messages.
.P
.PP
There are four main functions for the getaddrbyname opcode.
One render function converts a getaddrbyname request structure -
.Dv lwres_gabnrequest_t -
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 -
.Dv lwres_gabnresponse_t
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
.PP
These structures are defined in
.Pa <lwres/lwres.h> .
\fI<lwres/lwres.h>\fR.
They are shown below.
.Bd -literal -offset indent
.sp
.nf
#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
typedef struct lwres_addr lwres_addr_t;
@ -113,95 +96,98 @@ typedef struct {
void *base;
size_t baselen;
} lwres_gabnresponse_t;
.Ed
.Pp
.Fn lwres_gabnrequest_render
.sp
.fi
.PP
\fBlwres_gabnrequest_render()\fR
uses resolver context
.Fa ctx
\fIctx\fR
to convert getaddrbyname request structure
.Fa req
\fIreq\fR
to canonical format.
The packet header structure
.Fa pkt
\fIpkt\fR
is initialised and transferred to
buffer
.Fa b .
\fIb\fR.
The contents of
.Fa *req
\fI*req\fR
are then appended to the buffer in canonical format.
.Fn lwres_gabnresponse_render
\fBlwres_gabnresponse_render()\fR
performs the same task, except it converts a getaddrbyname response structure
.Dv lwres_gabnresponse_t
\fBlwres_gabnresponse_t\fR
to the lightweight resolver's canonical format.
.Pp
.Fn lwres_gabnrequest_parse
.PP
\fBlwres_gabnrequest_parse()\fR
uses context
.Fa ctx
\fIctx\fR
to convert the contents of packet
.Fa pkt
\fIpkt\fR
to a
.Dv lwres_gabnrequest_t
\fBlwres_gabnrequest_t\fR
structure.
Buffer
.Fa b
\fIb\fR
provides space to be used for storing this structure.
When the function succeeds, the resulting
.Dv lwres_gabnrequest_t
\fBlwres_gabnrequest_t\fR
is made available through
.Fa *structp .
.Fn lwres_gabnresponse_parse
\fI*structp\fR.
\fBlwres_gabnresponse_parse()\fR
offers the same semantics as
.Fn lwres_gabnrequest_parse
\fBlwres_gabnrequest_parse()\fR
except it yields a
.Dv lwres_gabnresponse_t
\fBlwres_gabnresponse_t\fR
structure.
.Pp
.Fn lwres_gabnresponse_free
.PP
\fBlwres_gabnresponse_free()\fR
and
.Fn lwres_gabnrequest_free
\fBlwres_gabnrequest_free()\fR
release the memory in resolver context
.Fa ctx
\fIctx\fR
that was allocated to the
.Dv lwres_gabnresponse_t
\fBlwres_gabnresponse_t\fR
or
.Dv lwres_gabnrequest_t
\fBlwres_gabnrequest_t\fR
structures referenced via
.Fa structp .
\fIstructp\fR.
Any memory associated with ancillary buffers and strings for those
structures is also discarded.
.Sh RETURN VALUES
.SH "RETURN VALUES"
.PP
The getaddrbyname opcode functions
.Fn lwres_gabnrequest_render ,
.Fn lwres_gabnresponse_render
.Fn lwres_gabnrequest_parse
\fBlwres_gabnrequest_render()\fR,
\fBlwres_gabnresponse_render()\fR
\fBlwres_gabnrequest_parse()\fR
and
.Fn lwres_gabnresponse_parse
\fBlwres_gabnresponse_parse()\fR
all return
.Er LWRES_R_SUCCESS
LWRES_R_SUCCESS
on success.
They return
.Er LWRES_R_NOMEMORY
LWRES_R_NOMEMORY
if memory allocation fails.
.Er LWRES_R_UNEXPECTEDEND
LWRES_R_UNEXPECTEDEND
is returned if the available space in the buffer
.Fa b
\fIb\fR
is too small to accommodate the packet header or the
.Dv lwres_gabnrequest_t
\fBlwres_gabnrequest_t\fR
and
.Dv lwres_gabnresponse_t
\fBlwres_gabnresponse_t\fR
structures.
.Fn lwres_gabnrequest_parse
\fBlwres_gabnrequest_parse()\fR
and
.Fn lwres_gabnresponse_parse
\fBlwres_gabnresponse_parse()\fR
will return
.Er LWRES_R_UNEXPECTEDEND
LWRES_R_UNEXPECTEDEND
if the buffer is not empty after decoding the received packet.
These functions will return
.Er LWRES_R_FAILURE
LWRES_R_FAILURE
if
.Li pktflags
\fBpktflags\fR
in the packet header structure
.Dv lwres_lwpacket_t
\fBlwres_lwpacket_t\fR
indicate that the packet is not a response to an earlier query.
.Sh SEE ALSO
.Xr lwres_packet 3
.SH "SEE ALSO"
.PP
\fBlwres_packet\fR(3)

255
lib/lwres/man/lwres_gabn.docbook Normal file
View file

@ -0,0 +1,255 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_gabn.docbook,v 1.1 2001/03/31 00:08:07 gson 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 &lt;lwres/lwres.h&gt;</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 &mdash;
<type>lwres_gabnrequest_t</type> &mdash;
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 &mdash;
<type>lwres_gabnresponse_t</type> &mdash;
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>&lt;lwres/lwres.h&gt;</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>

442
lib/lwres/man/lwres_gabn.html Normal file
View file

@ -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&nbsp;--&nbsp;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 &lt;lwres/lwres.h&gt;</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 &mdash;
<SPAN
CLASS="TYPE"
>lwres_gabnrequest_t</SPAN
> &mdash;
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 &mdash;
<SPAN
CLASS="TYPE"
>lwres_gabnresponse_t</SPAN
> &mdash;
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"
>&lt;lwres/lwres.h&gt;</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
>

105
lib/lwres/man/lwres_gai_strerror.3
View file

@ -12,71 +12,74 @@
.\" 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.3,v 1.6 2001/01/09 21:49:40 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_GAI_STRERROR 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm gai_strerror
.Nd print suitable error string
.Sh SYNOPSIS
.Fd #include <lwres/netdb.h>
.Fd
.Ft char *
.Fo gai_strerror
.Fa "int ecode"
.Fc
.Sh DESCRIPTION
.Fn lwres_gai_strerror
.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
char *
gai_strerror(int ecode);
\fR.SH "DESCRIPTION"
.PP
\fBlwres_gai_strerror()\fR
returns an error message corresponding to an error code returned by
.Fn getaddrinfo .
\fBgetaddrinfo()\fR.
The following error codes and their meaning are defined in
.Aq Pa include/lwres/netdb.h .
.Bl -tag -width EAI_ADDRFAMILY -offset indent -compact
.It Dv EAI_ADDRFAMILY
\fIinclude/lwres/netdb.h\fR.
.TP
\fBEAI_ADDRFAMILY\fR
address family for hostname not supported
.It Dv EAI_AGAIN
.TP
\fBEAI_AGAIN\fR
temporary failure in name resolution
.It Dv EAI_BADFLAGS
.TP
\fBEAI_BADFLAGS\fR
invalid value for
.Li ai_flags
.It Dv EAI_FAIL
ai_flags
.TP
\fBEAI_FAIL\fR
non-recoverable failure in name resolution
.It Dv EAI_FAMILY
.Li ai_family
.TP
\fBEAI_FAMILY\fR
ai_family
not supported
.It Dv EAI_MEMORY
.TP
\fBEAI_MEMORY\fR
memory allocation failure
.It Dv EAI_NODATA
.TP
\fBEAI_NODATA\fR
no address associated with hostname
.It Dv EAI_NONAME
.TP
\fBEAI_NONAME\fR
hostname or servname not provided, or not known
.It Dv EAI_SERVICE
.TP
\fBEAI_SERVICE\fR
servname not supported for
.Li ai_socktype
.It Dv EAI_SOCKTYPE
.Li ai_socktype
ai_socktype
.TP
\fBEAI_SOCKTYPE\fR
ai_socktype
not supported
.It Dv EAI_SYSTEM
.TP
\fBEAI_SYSTEM\fR
system error returned in errno
.El
The message \*qinvalid error code\*q is returned if
.Fa ecode
.PP
The message \fBinvalid error code\fR is returned if
\fIecode\fR
is out of range.
.Pp
.Li ai_flags ,
.Li ai_family
.PP
ai_flags,
ai_family
and
.Li ai_socktype
ai_socktype
are elements of the
.Dv "struct addrinfo"
\fBstruct addrinfo\fR
used by
.Fn lwres_getaddrinfo .
.Sh SEE ALSO
.Xr strerror 3 ,
.Xr lwres_getaddrinfo 3 ,
.Xr getaddrinfo 3 ,
.Xr RFC2133 .
\fBlwres_getaddrinfo()\fR.
.SH "SEE ALSO"
.PP
\fBstrerror\fR(3),
\fBlwres_getaddrinfo\fR(3),
\fBgetaddrinfo\fR(3),
\fBRFC2133\fR.

154
lib/lwres/man/lwres_gai_strerror.docbook Normal file
View file

@ -0,0 +1,154 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_gai_strerror.docbook,v 1.1 2001/03/31 00:08:08 gson 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 &lt;lwres/netdb.h&gt;</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
</listitem>
<varlistentry><term><errorcode>EAI_AGAIN</errorcode></term>
<listitem>
<para>
temporary failure in name resolution
</listitem>
<varlistentry><term><errorcode>EAI_BADFLAGS</errorcode></term>
<listitem>
<para>
invalid value for
<constant>ai_flags</constant>
</listitem>
<varlistentry><term><errorcode>EAI_FAIL</errorcode></term>
<listitem>
<para>
non-recoverable failure in name resolution
</listitem>
<varlistentry><term><errorcode>EAI_FAMILY</errorcode></term>
<listitem>
<para>
<constant>ai_family</constant>
not supported
</listitem>
<varlistentry><term><errorcode>EAI_MEMORY</errorcode></term>
<listitem>
<para>
memory allocation failure
</listitem>
<varlistentry><term><errorcode>EAI_NODATA</errorcode></term>
<listitem>
<para>
no address associated with hostname
</listitem>
<varlistentry><term><errorcode>EAI_NONAME</errorcode></term>
<listitem>
<para>
hostname or servname not provided, or not known
</listitem>
<varlistentry><term><errorcode>EAI_SERVICE</errorcode></term>
<listitem>
<para>
servname not supported for
<constant>ai_socktype</constant>
</listitem>
<varlistentry><term><errorcode>EAI_SOCKTYPE</errorcode></term>
<listitem>
<para>
<constant>ai_socktype</constant>
not supported
</listitem>
<varlistentry><term><errorcode>EAI_SYSTEM</errorcode></term>
<listitem>
<para>
system error returned in errno
</para>
</listitem>
</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>

297
lib/lwres/man/lwres_gai_strerror.html Normal file
View file

@ -0,0 +1,297 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/netdb.h&gt;</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
>

270
lib/lwres/man/lwres_getaddrinfo.3
View file

@ -12,37 +12,26 @@
.\" 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.3,v 1.8 2001/01/09 21:49:41 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_GETADDRINFO 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_getaddrinfo ,
.Nm lwres_freeaddrinfo
.Nd socket address structure to host and service name
.Sh SYNOPSIS
.Fd #include <lwres/netdb.h>
.Fd
.Ft int
.Fo lwres_getaddrinfo
.Fa "const char *hostname"
.Fa "const char *servname"
.Fa "const struct addrinfo *hints"
.Fa "struct addrinfo **res"
.Fc
.Ft void
.Fo lwres_freeaddrinfo
.Fa "struct addrinfo *ai"
.Fc
.Pp
.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
int
lwres_getaddrinfo(const char *hostname);
(const char *servname);
(const struct addrinfo *hints);
(struct addrinfo **res);
.sp
void
lwres_freeaddrinfo(struct addrinfo *ai);
\fR.PP
If the operating system does not provide a
.Dv "struct addrinfo" ,
\fBstruct addrinfo\fR,
the following structure is used:
.Pp
.Bd -literal -offset indent
.sp
.nf
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
int ai_family; /* PF_xxx */
@ -53,206 +42,211 @@ struct addrinfo {
struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */
};
.Ed
.Sh DESCRIPTION
.Pp
.Fn lwres_getaddrinfo
.sp
.fi
.SH "DESCRIPTION"
.PP
\fBlwres_getaddrinfo()\fR
is used to get a list of IP addresses and port numbers for host
.Fa hostname
\fIhostname\fR
and service
.Fa servname .
\fIservname\fR.
The function is the lightweight resolver's implementation of
.Fn getaddrinfo
\fBgetaddrinfo()\fR
as defined in RFC2133.
.Fa hostname
\fIhostname\fR
and
.Fa servname
\fIservname\fR
are pointers to null-terminated
strings or
.Dv NULL .
.Fa hostname
\fBNULL\fR.
\fIhostname\fR
is either a host name or a numeric host address string: a dotted decimal
IPv4 address or an IPv6 address.
.Fa servname
\fIservname\fR
is either a decimal port number or a service name as listed in
.Pa /etc/services .
.Pp
.Fa hints
\fI/etc/services\fR.
.PP
\fIhints\fR
is an optional pointer to a
.Dv "struct addrinfo" .
\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
.Fa *hints :
.Bl -tag -width ai_socktyp -offset indent -compact
.It Li ai_family
the protocol family that should be used.
\fI*hints\fR:
.TP
\fBai_family\fR
The protocol family that should be used.
When
.Li ai_family
ai_family
is set to
.Dv PF_UNSPEC ,
\fBPF_UNSPEC\fR,
it means the caller will accept any protocol family supported by the
operating system.
.It Dv ai_socktype
denotes the type of socket -
.Dv SOCK_STREAM ,
.Dv SOCK_DGRAM
.TP
\fBai_socktype\fR
denotes the type of socket \(em
\fBSOCK_STREAM\fR,
\fBSOCK_DGRAM\fR
or
.Dv SOCK_RAW
- that is wanted.
\fBSOCK_RAW\fR
\(em that is wanted.
When
.Li ai_socktype
ai_socktype
is zero the caller will accept any socket type.
.It Li ai_protocol
.TP
\fBai_protocol\fR
indicates which transport protocol is wanted: IPPROTO_UDP or
IPPROTO_TCP.
If
.Li ai_protocol
ai_protocol
is zero the caller will accept any protocol.
.It Li ai_flags
.TP
\fBai_flags\fR
Flag bits.
If the
.Dv AI_CANONNAME
\fBAI_CANONNAME\fR
bit is set, a successful call to
.Fn lwres_getaddrinfo
\fBlwres_getaddrinfo()\fR
will return a a null-terminated string containing the canonical name
of the specified hostname in
.Li ai_canonname
ai_canonname
of the first
.Dv addrinfo
\fBaddrinfo\fR
structure returned.
Setting the
.Dv AI_PASSIVE
\fBAI_PASSIVE\fR
bit indicates that the returned socket address structure is intended
for used in a call to
.Xr bind 2 .
\fBbind\fR(2).
In this case, if the hostname argument is a
.Dv NULL
\fBNULL\fR
pointer, then the IP address portion of the socket
address structure will be set to
.Dv INADDR_ANY
\fBINADDR_ANY\fR
for an IPv4 address or
.Dv IN6ADDR_ANY_INIT
\fBIN6ADDR_ANY_INIT\fR
for an IPv6 address.
.Pp
When
.Li ai_flags
ai_flags
does not set the
.Dv AI_PASSIVE
\fBAI_PASSIVE\fR
bit, the returned socket address structure will be ready
for use in a call to
.Xr connect 2
\fBconnect\fR(2)
for a connection-oriented protocol or
.Xr connect 2 ,
.Xr sendto 2 ,
\fBconnect\fR(2),
\fBsendto\fR(2),
or
.Xr sendmsg 2
\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
.Fa hostname
\fIhostname\fR
is a
.Dv NULL
\fBNULL\fR
pointer and
.Dv AI_PASSIVE
\fBAI_PASSIVE\fR
is not set in
.Li ai_flags .
.Pp
ai_flags.
If
.Li ai_flags
ai_flags
is set to
.Dv AI_NUMERICHOST
\fBAI_NUMERICHOST\fR
it indicates that
.Fa hostname
\fIhostname\fR
should be treated as a numeric string defining an IPv4 or IPv6 address
and no name resolution should be attempted.
.El
.Pp
.PP
All other elements of the
.Dv "struct addrinfo"
\fBstruct addrinfo\fR
passed via
.Fa hints
\fIhints\fR
must be zero.
.Pp
.PP
A
.Fa hints
\fIhints\fR
of
.Dv NULL
\fBNULL\fR
is treated as if the caller provided a
.Dv "struct addrinfo"
\fBstruct addrinfo\fR
initialized to zero with
.Li ai_family set to
.Li PF_UNSPEC .
.Pp
ai_familyset to
PF_UNSPEC.
.PP
After a successful call to
.Fn lwres_getaddrinfo ,
.Fa *res
\fBlwres_getaddrinfo()\fR,
\fI*res\fR
is a pointer to a linked list of one or more
.Dv addrinfo
\fBaddrinfo\fR
structures.
Each
.Dv "struct addrinfo"
\fBstruct addrinfo\fR
in this list cn be processed by following
the
.Li ai_next
ai_next
pointer, until a
.Dv NULL
\fBNULL\fR
pointer is encountered.
The three members
.Li ai_family ,
.Li ai_socktype ,
ai_family,
ai_socktype,
and
.Li ai_protocol
ai_protocol
in each
returned
.Dv addrinfo
\fBaddrinfo\fR
structure contain the corresponding arguments for a call to
.Xr socket 2 .
\fBsocket\fR(2).
For each
.Dv addrinfo
\fBaddrinfo\fR
structure in the list, the
.Li ai_addr
ai_addr
member points to a filled-in socket address structure of length
.Li ai_addrlen .
.Pp
ai_addrlen.
.PP
All of the information returned by
.Fn lwres_getaddrinfo
\fBlwres_getaddrinfo()\fR
is dynamically allocated: the addrinfo structures, and the socket
address structures and canonical host name strings pointed to by the
.Li addrinfo structures.
addrinfostructures.
Memory allocated for the dynamically allocated structures created by
a successful call to
.Fn lwres_getaddrinfo
\fBlwres_getaddrinfo()\fR
is released by
.Fn lwres_freeaddrinfo .
.Fa ai
\fBlwres_freeaddrinfo()\fR.
\fIai\fR
is a pointer to a
.Dv "struct addrinfo"
\fBstruct addrinfo\fR
created by a call to
.Fn lwres_getaddrinfo .
.Sh RETURN VALUES
.Fn lwres_getaddrinfo
\fBlwres_getaddrinfo()\fR.
.SH "RETURN VALUES"
.PP
\fBlwres_getaddrinfo()\fR
returns zero on success or one of the error codes listed in
.Xr gai_strerror 3
\fBgai_strerror\fR(3)
if an error occurs.
If both
.Fa hostname
\fIhostname\fR
and
.Fa servname
\fIservname\fR
are
.Dv NULL
.Fn lwres_getaddrinfo
\fBNULL\fR
\fBlwres_getaddrinfo()\fR
returns
.Er EAI_NONAME .
.Sh SEE ALSO
.Xr lwres 3 ,
.Xr lwres_getaddrinfo 3 ,
.Xr lwres_freeaddrinfo 3 ,
.Xr lwres_gai_strerror 3 ,
.Xr RFC2133 ,
.Xr getservbyname 3 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr sendto 2 ,
.Xr sendmsg 2 ,
.Xr socket 2 .
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).

382
lib/lwres/man/lwres_getaddrinfo.docbook Normal file
View file

@ -0,0 +1,382 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_getaddrinfo.docbook,v 1.1 2001/03/31 00:08:09 gson 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 &lt;lwres/netdb.h&gt;</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.
<varlistentry><term><constant>ai_socktype</constant></term>
<listitem>
<para>
denotes the type of socket &mdash;
<type>SOCK_STREAM</type>,
<type>SOCK_DGRAM</type>
or
<type>SOCK_RAW</type>
&mdash; that is wanted.
When
<constant>ai_socktype</constant>
is zero the caller will accept any socket type.
</para>
</listitem>
<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><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>
</variablelist>
<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>

739
lib/lwres/man/lwres_getaddrinfo.html Normal file
View file

@ -0,0 +1,739 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/netdb.h&gt;</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
>.&#13;</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 &mdash;
<SPAN
CLASS="TYPE"
>SOCK_STREAM</SPAN
>,
<SPAN
CLASS="TYPE"
>SOCK_DGRAM</SPAN
>
or
<SPAN
CLASS="TYPE"
>SOCK_RAW</SPAN
>
&mdash; 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
>.&#13;</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
>&#13;</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
>.&#13;</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
>.&#13;</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
>.&#13;</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
>

428
lib/lwres/man/lwres_gethostent.3
View file

@ -12,100 +12,73 @@
.\" 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.3,v 1.7 2001/01/09 21:49:49 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_GETHOSTENT 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_gethostbyname ,
.Nm lwres_gethostbyname2 ,
.Nm lwres_gethostbyaddr ,
.Nm lwres_gethostent ,
.Nm lwres_sethostent ,
.Nm lwres_endhostent ,
.Nm lwres_gethostbyname_r ,
.Nm lwres_gethostbyaddr_r ,
.Nm lwres_gethostent_r ,
.Nm lwres_sethostent_r ,
.Nm lwres_endhostent_r
.Nd lightweight resolver get network host entry
.Sh SYNOPSIS
.Fd #include <lwres/netdb.h>
.Fd
.Ft struct hostent *
.Fo lwres_gethostbyname
.Fa "const char *name"
.Fc
.Ft struct hostent *
.Fo lwres_gethostbyname2
.Fa "const char *name"
.Fa "int af"
.Fc
.Ft struct hostent *
.Fo lwres_gethostbyaddr
.Fa "const char *addr"
.Fa "int len"
.Fa "int type"
.Fc
.Ft struct hostent *
.Fo lwres_gethostent
.Fa "void"
.Fc
.Ft void
.Fo lwres_sethostent
.Fa "int stayopen"
.Fc
.Ft void
.Fo lwres_endhostent
.Fa "void"
.Fc
.Ft struct hostent *
.Fo lwres_gethostbyname_r
.Fa "const char *name"
.Fa "struct hostent *resbuf"
.Fa "char *buf"
.Fa "int buflen"
.Fa "int *error"
.Fc
.Ft struct hostent *
.Fo lwres_gethostbyaddr_r
.Fa "const char *addr"
.Fa "int len"
.Fa "int type"
.Fa "struct hostent *resbuf"
.Fa "char *buf"
.Fa "int buflen"
.Fa "int *error"
.Fc
.Ft struct hostent *
.Fo lwres_gethostent_r
.Fa "struct hostent *resbuf"
.Fa "char *buf"
.Fa "int buflen"
.Fa "int *error"
.Fc
.Ft void
.Fo lwres_sethostent_r
.Fa "int stayopen"
.Fc
.Ft void
.Fo lwres_endhostent_r
.Fa "void"
.Fc
.Sh DESCRIPTION
.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
struct hostent *
lwres_gethostbyname(const char *name);
.sp
struct hostent *
lwres_gethostbyname2(const char *name);
(int af);
.sp
struct hostent *
lwres_gethostbyaddr(const char *addr);
(int len);
(int type);
.sp
struct hostent *
lwres_gethostent(void);
.sp
void
lwres_sethostent(int stayopen);
.sp
void
lwres_endhostent(void);
.sp
struct hostent *
lwres_gethostbyname_r(const char *name);
(struct hostent *resbuf);
(char *buf);
(int buflen);
(int *error);
.sp
struct hostent *
lwres_gethostbyaddr_r(const char *addr);
(int len);
(int type);
(struct hostent *resbuf);
(char *buf);
(int buflen);
(int *error);
.sp
struct hostent *
lwres_gethostent_r(struct hostent *resbuf);
(char *buf);
(int buflen);
(int *error);
.sp
void
lwres_sethostent_r(int stayopen);
.sp
void
lwres_endhostent_r(void);
\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
.Xr gethostent 3
\fBgethostent\fR(3)
functions provided by most operating systems.
They use a
.Dv "struct hostent"
\fBstruct hostent\fR
which is usually defined in
.Pa <namedb.h> .
.Bd -literal
\fI<namedb.h>\fR.
.sp
.nf
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
@ -114,240 +87,247 @@ struct hostent {
char **h_addr_list; /* list of addresses from name server */
};
#define h_addr h_addr_list[0] /* address, for backward compatibility */
.Ed
.Pp
.sp
.fi
.PP
The members of this structure are:
.Bl -tag -width h_addr_list
.It Li h_name
.TP
\fBh_name\fR
The official (canonical) name of the host.
.It Li h_aliases
.TP
\fBh_aliases\fR
A NULL-terminated array of alternate names (nicknames) for the host.
.It Li h_addrtype
The type of address being returned -
.Dv PF_INET
.TP
\fBh_addrtype\fR
The type of address being returned \(em
\fBPF_INET\fR
or
.Dv PF_INET6 .
.It Li h_length
\fBPF_INET6\fR.
.TP
\fBh_length\fR
The length of the address in bytes.
.It Li h_addr_list
A
.Dv NULL
.TP
\fBh_addr_list\fR
A \fBNULL\fR
terminated array of network addresses for the host.
Host addresses are returned in network byte order.
.El
.Pp
.PP
For backward compatibility with very old software,
.Li h_addr
h_addr
is the first address in
.Li h_addr_list.
.Pp
.Fn lwres_gethostent ,
.Fn lwres_sethostent ,
.Fn lwres_endhostent ,
.Fn lwres_gethostent_r ,
.Fn lwres_sethostent_r
h_addr_list.
.PP
\fBlwres_gethostent()\fR,
\fBlwres_sethostent()\fR,
\fBlwres_endhostent()\fR,
\fBlwres_gethostent_r()\fR,
\fBlwres_sethostent_r()\fR
and
.Fn lwres_endhostent_r
\fBlwres_endhostent_r()\fR
provide iteration over the known host entries on systems that
provide such functionality through facilities like
.Pa /etc/hosts
or NIS. The lightweight resolver does not currently implement
\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
.Fn lwres_gethostbyname
.PP
\fBlwres_gethostbyname()\fR
and
.Fn lwres_gethostbyname2
\fBlwres_gethostbyname2()\fR
look up the hostname
.Fa name .
.Fn lwres_gethostbyname
\fIname\fR.
\fBlwres_gethostbyname()\fR
always looks for an IPv4 address while
.Fn lwres_gethostbyname2
\fBlwres_gethostbyname2()\fR
looks for an address of protocol family
.Fa af :
\fIaf\fR:
either
.Dv PF_INET
\fBPF_INET\fR
or
.Dv PF_INET6
- IPv4 or IPV6 addresses respectively.
\fBPF_INET6\fR
\(em IPv4 or IPV6 addresses respectively.
Successful calls of the functions return a
.Dv "struct hostent" for
\fBstruct hostent\fRfor
the name that was looked up.
.Dv NULL
\fBNULL\fR
is returned if the lookups by
.Fn lwres_gethostbyname
\fBlwres_gethostbyname()\fR
or
.Fn lwres_gethostbyname2
\fBlwres_gethostbyname2()\fR
fail.
.Pp
.PP
Reverse lookups of addresses are performed by
.Fn lwres_gethostbyaddr .
.Fa addr
\fBlwres_gethostbyaddr()\fR.
\fIaddr\fR
is an address of length
.Fa len
\fIlen\fR
bytes and protocol family
.Fa type -
.Dv PF_INET
\fItype\fR \(em
\fBPF_INET\fR
or
.Dv PF_INET6 .
.Fn lwres_gethostbyname_r
\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
.Fa *error .
.Fa resbuf
\fI*error\fR.
\fIresbuf\fR
is a pointer to a
.Dv "struct hostent"
\fBstruct hostent\fR
which is initialised by a successful call to
.Fn lwres_gethostbyname_r .
.Fa buf
\fBlwres_gethostbyname_r()\fR .
\fIbuf\fR
is a buffer of length
.Fa len
\fIlen\fR
bytes which is used to store the
.Li h_name ,
.Li h_aliases ,
h_name,
h_aliases,
and
.Li h_addr_list
h_addr_list
elements of the
.Dv "struct hostent"
\fBstruct hostent\fR
returned in
.Fa resbuf .
\fIresbuf\fR.
Successful calls to
.Fn lwres_gethostbyname_r
\fBlwres_gethostbyname_r()\fR
return
.Fa resbuf ,
\fIresbuf\fR,
which is a pointer to the
.Dv "struct hostent"
\fBstruct hostent\fR
it created.
.Pp
.Fn lwres_gethostbyaddr_r
.PP
\fBlwres_gethostbyaddr_r()\fR
is a thread-safe function that performs a reverse lookup of address
.Fa addr
\fIaddr\fR
which is
.Fa len
\fIlen\fR
bytes long
and is of protocol family
.Fa type -
.Dv PF_INET
\fItype\fR \(em
\fBPF_INET\fR
or
.Dv PF_INET6 .
\fBPF_INET6\fR.
If an error occurs, the error code is returned in
.Fa *error .
\fI*error\fR.
The other function parameters are identical to those in
.Fn lwres_gethostbyname_r .
.Fa resbuf
\fBlwres_gethostbyname_r()\fR.
\fIresbuf\fR
is a pointer to a
.Dv "struct hostent"
\fBstruct hostent\fR
which is initialised by a successful call to
.Fn lwres_gethostbyaddr_r .
.Fa buf
\fBlwres_gethostbyaddr_r()\fR.
\fIbuf\fR
is a buffer of length
.Fa len
\fIlen\fR
bytes which is used to store the
.Li h_name ,
.Li h_aliases ,
h_name,
h_aliases,
and
.Li h_addr_list
h_addr_list
elements of the
.Dv "struct hostent"
\fBstruct hostent\fR
returned in
.Fa resbuf .
\fIresbuf\fR.
Successful calls to
.Fn lwres_gethostbyaddr_r
\fBlwres_gethostbyaddr_r()\fR
return
.Fa resbuf ,
\fIresbuf\fR,
which is a pointer to the
.Fn "struct hostent"
\fB"struct hostent"()\fR
it created.
.Sh RETURN VALUES
.Pp
.SH "RETURN VALUES"
.PP
The functions
.Fn lwres_gethostbyname ,
.Fn lwres_gethostbyname2 ,
.Fn lwres_gethostbyaddr ,
\fBlwres_gethostbyname()\fR,
\fBlwres_gethostbyname2()\fR,
\fBlwres_gethostbyaddr()\fR,
and
.Fn lwres_gethostent
return NULL to indicate an error. In this case the global variable
.Dv lwres_h_errno
\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
.Pa <lwres/netdb.h> :
.Bl -tag -width HOST_NOT_FOUND
.It Li HOST_NOT_FOUND
\fI<lwres/netdb.h>\fR:
.TP
\fBHOST_NOT_FOUND\fR
The host or address was not found.
.It Li TRY_AGAIN
.TP
\fBTRY_AGAIN\fR
A recoverable error occurred, e.g., a timeout.
Retrying the lookup may succeed.
.It Li NO_RECOVERY
.TP
\fBNO_RECOVERY\fR
A non-recoverable error occurred.
.It Li NO_DATA
.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
of a reverse lookup). The code NO_ADDRESS
is accepted as a synonym for NO_DATA for backwards
compatibility.
.El
.Pp
.Xr lwres_hstrerror 3
.PP
\fBlwres_hstrerror\fR(3)
translates these error codes to suitable error messages.
.Pp
.Fn lwres_gethostent
.PP
\fBlwres_gethostent()\fR
and
.Fn lwres_gethostent_r
\fBlwres_gethostent_r()\fR
always return
.Dv NULL .
.Pp
\fBNULL\fR.
.PP
Successful calls to
.Fn lwres_gethostbyname_r
\fBlwres_gethostbyname_r()\fR
and
.Fn lwres_gethostbyaddr_r
\fBlwres_gethostbyaddr_r()\fR
return
.Fa resbuf ,
\fIresbuf\fR,
a pointer to the
.Dv "struct hostent"
\fBstruct hostent\fR
that was initialised by these functions.
They return
.Dv NULL
\fBNULL\fR
if the lookups fail
or if
.Fa buf
\fIbuf\fR
was too small to hold the list of addresses and names referenced by
the
.Li h_name ,
.Li h_aliases ,
h_name,
h_aliases,
and
.Li h_addr_list
h_addr_list
elements of the
.Dv "struct hostent" .
\fBstruct hostent\fR.
If
.Fa buf
\fIbuf\fR
was too small, both
.Fn lwres_gethostbyname_r
\fBlwres_gethostbyname_r()\fR
and
.Fn lwres_gethostbyaddr_r
\fBlwres_gethostbyaddr_r()\fR
set the global variable
.Dv errno
\fBerrno\fR
to
.Er ERANGE .
.Sh SEE ALSO
.Xr gethostent 3 ,
.Xr lwres_getipnode 3 ,
.Xr lwres_hstrerror 3
.Sh BUGS
.Fn lwres_gethostbyname ,
.Fn lwres_gethostbyname2 ,
.Fn lwres_gethostbyaddr
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
.Fn lwres_endhostent
\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
.Fn lwres_gethostbyname_r ,
\fBlwres_gethostbyname_r()\fR,
and
.Fn lwres_gethostbyaddr_r
\fBlwres_gethostbyaddr_r()\fR
respectively.
.Pp
.PP
The resolver daemon does not currently support any non-DNS
name services such as
.Pa /etc/hosts
\fI/etc/hosts\fR
or
.Dv NIS ,
\fBNIS\fR,
consequently the above functions don't, either.

490
lib/lwres/man/lwres_gethostent.docbook Normal file
View file

@ -0,0 +1,490 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_gethostent.docbook,v 1.1 2001/03/31 00:08:10 gson 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 &lt;lwres/netdb.h&gt;</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>&lt;namedb.h&gt;</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><term><constant>h_aliases</constant></term>
<listitem>
<para>
A NULL-terminated array of alternate names (nicknames) for the host.
</para>
</listitem>
<varlistentry><term><constant>h_addrtype</constant></term>
<listitem>
<para>
The type of address being returned &mdash;
<type>PF_INET</type>
or
<type>PF_INET6</type>.
</para>
</listitem>
<varlistentry><term><constant>h_length</constant></term>
<listitem>
<para>
The length of the address in bytes.
</para>
</listitem>
<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>
</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>
&mdash; 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> &mdash;
<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> &mdash;
<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>&lt;lwres/netdb.h&gt;</filename>:
<variablelist>
<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
<listitem>
<para>
The host or address was not found.
</para>
</listitem>
<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><term><constant>NO_RECOVERY</constant></term>
<listitem>
<para>
A non-recoverable error occurred.
</para>
</listitem>
<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>
</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>

918
lib/lwres/man/lwres_gethostent.html Normal file
View file

@ -0,0 +1,918 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/netdb.h&gt;</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"
>&lt;namedb.h&gt;</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 &mdash;
<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
>
&mdash; 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
> &mdash;
<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
> &mdash;
<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"
>&lt;lwres/netdb.h&gt;</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
>.&#13;</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
>.&#13;</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
>

207
lib/lwres/man/lwres_getipnode.3
View file

@ -12,49 +12,38 @@
.\" 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.3,v 1.6 2001/01/09 21:49:51 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_GETIPNODE 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_getipnodebyname ,
.Nm lwres_getipnodebyaddr ,
.Nm lwres_freehostent
.Nd lightweight resolver nodename / address translation API
.Sh SYNOPSIS
.Fd #include <lwres/netdb.h>
.Fd
.Ft struct hostent *
.Fo lwres_getipnodebyname
.Fa "const char *name"
.Fa "int af"
.Fa "int flags"
.Fa "int *error_num"
.Fc
.Ft struct hostent *
.Fo lwres_getipnodebyaddr
.Fa "const void *src"
.Fa "size_t len"
.Fa "int af"
.Fa "int *error_num"
.Fc
.Ft void
.Fo lwres_freehostent
.Fa "struct hostent *he"
.Fc
.Sh DESCRIPTION
.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
struct hostent *
lwres_getipnodebyname(const char *name);
(int af);
(int flags);
(int *error_num);
.sp
struct hostent *
lwres_getipnodebyaddr(const void *src);
(size_t len);
(int af);
(int *error_num);
.sp
void
lwres_freehostent(struct hostent *he);
\fR.SH "DESCRIPTION"
.PP
These functions perform thread safe, protocol independent
nodename-to-address and address-to-nodename
translation as defined in RFC2553.
.Pp
.PP
They use a
.Dv "struct hostent"
\fBstruct hostent\fR
which is defined in
.Pa namedb.h :
.Bd -literal
\fInamedb.h\fR:
.sp
.nf
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
@ -63,124 +52,134 @@ struct hostent {
char **h_addr_list; /* list of addresses from name server */
};
#define h_addr h_addr_list[0] /* address, for backward compatibility */
.Ed
.Pp
.sp
.fi
.PP
The members of this structure are:
.Bl -tag -width h_addr_list
.It Li h_name
.TP
\fBh_name\fR
The official (canonical) name of the host.
.It Li h_aliases
.TP
\fBh_aliases\fR
A NULL-terminated array of alternate names (nicknames) for the host.
.It Li h_addrtype
.TP
\fBh_addrtype\fR
The type of address being returned - usually
.Dv PF_INET
\fBPF_INET\fR
or
.Dv PF_INET6 .
.It Li h_length
\fBPF_INET6\fR.
.TP
\fBh_length\fR
The length of the address in bytes.
.It Li h_addr_list
.TP
\fBh_addr_list\fR
A
.Dv NULL
\fBNULL\fR
terminated array of network addresses for the host.
Host addresses are returned in network byte order.
.El
.Pp
.Fn lwres_getipnodebyname
.PP
\fBlwres_getipnodebyname()\fR
looks up addresses of protocol family
.Fa af
\fIaf\fR
for the hostname
.Fa name .
\fIname\fR.
The
.Fa flags
\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:
.Bl -tag -width AI_ADDRCONFIG
.It Li AI_V4MAPPED
.TP
\fBAI_V4MAPPED\fR
This is used with an
.Fa af
\fIaf\fR
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
IPv6 addresses.
.It Li AI_ALL
.TP
\fBAI_ALL\fR
This is used with an
.Fa af
\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.
.It Li AI_ADDRCONFIG
.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
interface of that type. This is not currently implemented
in the BIND 9 lightweight resolver, and the flag is ignored.
.It Li AI_DEFAULT
.TP
\fBAI_DEFAULT\fR
This default sets the
.Li AI_V4MAPPED
AI_V4MAPPED
and
.Li AI_ADDRCONFIG
AI_ADDRCONFIG
flag bits.
.El
.Pp
.Fn lwres_getipnodebyaddr
.PP
\fBlwres_getipnodebyaddr()\fR
performs a reverse lookup
of address
.Fa src
\fIsrc\fR
which is
.Fa len
\fIlen\fR
bytes long.
.Fa af
\fIaf\fR
denotes the protocol family, typically
.Dv PF_INET
\fBPF_INET\fR
or
.Dv PF_INET6 .
.Pp
.Fn lwres_freehostent
\fBPF_INET6\fR.
.PP
\fBlwres_freehostent()\fR
releases all the memory associated with
the
.Dv "struct hostent"
\fBstruct hostent\fR
pointer
.Fa he .
\fIhe\fR.
Any memory allocated for the
.Li h_name ,
.Li h_addr_list
h_name,
h_addr_list
and
.Li h_aliases
h_aliases
is freed, as is the memory for the
.Dv hostent
\fBhostent\fR
structure itself.
.Sh RETURN VALUES
.SH "RETURN VALUES"
.PP
If an error occurs,
.Fn lwres_getipnodebyname
\fBlwres_getipnodebyname()\fR
and
.Fn lwres_getipnodebyaddr
\fBlwres_getipnodebyaddr()\fR
set
.Fa *error_num
\fI*error_num\fR
to an approriate error code and the function returns a
.Dv NULL
\fBNULL\fR
pointer.
The error codes and their meanings are defined in
.Pa <lwres/netdb.h> :
.Bl -tag -width HOST_NOT_FOUND
.It Li HOST_NOT_FOUND
\fI<lwres/netdb.h>\fR:
.TP
\fBHOST_NOT_FOUND\fR
No such host is known.
.It Li NO_ADDRESS
.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
available. Another type of request to the name server for the
domain might return an answer.
.It Li TRY_AGAIN
.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
failure of a server to respond. The request may succeed if
retried.
.It Li NO_RECOVERY
.TP
\fBNO_RECOVERY\fR
An unexpected failure occurred, and retrying the request
is pointless.
.El
.Pp
.Xr lwres_hstrerror 3
.PP
\fBlwres_hstrerror\fR(3)
translates these error codes to suitable error messages.
.Sh SEE ALSO
.Xr RFC2553 ,
.Xr lwres 3 ,
.Xr lwres_gethostent 3 ,
.Xr lwres_getaddrinfo 3 ,
.Xr lwres_getnameinfo 3 ,
.Xr lwres_hstrerror 3 .
.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).

303
lib/lwres/man/lwres_getipnode.docbook Normal file
View file

@ -0,0 +1,303 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_getipnode.docbook,v 1.1 2001/03/31 00:08:12 gson 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 &lt;lwres/netdb.h&gt;</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><term><constant>h_aliases</constant></term>
<listitem>
<para>
A NULL-terminated array of alternate names (nicknames) for the host.
</para>
</listitem>
<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><term><constant>h_length</constant></term>
<listitem>
<para>
The length of the address in bytes.
</para>
</listitem>
<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>
</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><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><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><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>
</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>&lt;lwres/netdb.h&gt;</filename>:
<variablelist>
<varlistentry><term><constant>HOST_NOT_FOUND</constant></term>
<listitem>
<para>
No such host is known.
</para>
</listitem>
<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><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><term><constant>NO_RECOVERY</constant></term>
<listitem>
<para>
An unexpected failure occurred, and retrying the request
is pointless.
</para>
</listitem>
</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>

530
lib/lwres/man/lwres_getipnode.html Normal file
View file

@ -0,0 +1,530 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/netdb.h&gt;</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
>.&#13;</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
>.&#13;</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"
>&lt;lwres/netdb.h&gt;</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
>

143
lib/lwres/man/lwres_getnameinfo.3
View file

@ -12,119 +12,92 @@
.\" 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.3,v 1.8 2001/01/09 21:49:56 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_GETNAMEINFO 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_getnameinfo
.Nd lightweight resolver socket address structure to hostname and service name
.Sh SYNOPSIS
.Fd #include <lwres/netdb.h>
.Fd
.Ft int
.Fo lwres_getnameinfo
.Fa "const struct sockaddr *sa"
.Fa "size_t salen"
.Fa "char *host"
.Fa "size_t hostlen"
.Fa "char *serv"
.Fa "size_t servlen"
.Fa "int flags"
.Fc
.Sh DESCRIPTION
.Pp
.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
int
lwres_getnameinfo(const struct sockaddr *sa);
(size_t salen);
(char *host);
(size_t hostlen);
(char *serv);
(size_t servlen);
(int flags);
\fR.SH "DESCRIPTION"
.PP
This function is equivalent to the
.Xr getnameinfo 3
\fBgetnameinfo\fR(3)
function defined in RFC2133.
.Fn lwres_getnameinfo
\fBlwres_getnameinfo()\fR
returns the hostname for the
.Dv "struct sockaddr"
.Fa sa
\fBstruct sockaddr\fR
\fIsa\fR
which is
.Fa salen
\fIsalen\fR
bytes long.
The hostname is of length
.Fa hostlen
\fIhostlen\fR
and is returned via
.Fa *host.
\fI*host.\fR
The maximum length of the hostname is
1025 bytes:
.Li NI_MAXHOST .
.Pp
NI_MAXHOST.
.PP
The name of the service associated with the port number in
.Fa sa
\fIsa\fR
is returned in
.Fa *serv.
\fI*serv.\fR
It is
.Fa servlen
\fIservlen\fR
bytes long.
The maximum length of the service name is
.Li NI_MAXSERV
- 32 bytes.
.Pp
NI_MAXSERV - 32 bytes.
.PP
The
.Fa flags
\fIflags\fR
argument sets the following bits:
.Bl -tag -width NI_NUMERICSERV
.It Li NI_NOFQDN
.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.
.It Li NI_NUMERICHOST
.TP
\fBNI_NUMERICHOST\fR
Return the address in numeric form, as if calling inet_ntop(),
instead of a host name.
.It Li NI_NAMEREQD
.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.
.It Li NI_NUMERICSERV
.TP
\fBNI_NUMERICSERV\fR
The service name is returned as a digit string representing the port number.
.It Li NI_DGRAM
.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
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.
.El
.Pp
.Sh RETURN VALUES
.Fn lwres_getnameinfo
.PP
.SH "RETURN VALUES"
.PP
\fBlwres_getnameinfo()\fR
returns 0 on success or a non-zero error code if an error occurs.
.\"
.\" The error codes below were invented by the ISC/Nominum. They
.\" should be defined in RFC2133 before getting documented here.
.\" XXXJR 28/6/00
.\" The error codes are:
.\" Bl -tag -width ENI_NOSERVNAME
.\" It Li ENI_NOSOCKET
.\" there was no socket in
.\" Fa sa
.\" It Li ENI_NOSERVNAME
.\" no service name was found
.\" It Li ENI_NOHOSTNAME
.\" no hostname was found
.\" It Li ENI_MEMORY
.\" memory could not be allocated
.\" It Li ENI_SYSTEM
.\" a system error occurred
.\" It Li ENI_FAMILY
.\" an unsupported protocol family was requested
.\" It Li ENI_SALEN
.\" Fa salen
.\" is the wrong number of bytes for the address in
.\" Fa sa .
.Sh SEE ALSO
.Xr RFC2133 ,
.Xr getservbyport 3 ,
.Xr lwres 3 ,
.Xr lwres_getnameinfo 3 ,
.Xr lwres_getnamebyaddr 3 .
.Xr lwres_net_ntop 3 .
.Sh BUGS
.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
.Xr getnameinfo 3
\fBgetnameinfo\fR(3)
are.

171
lib/lwres/man/lwres_getnameinfo.docbook Normal file
View file

@ -0,0 +1,171 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_getnameinfo.docbook,v 1.1 2001/03/31 00:08:13 gson 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 &lt;lwres/netdb.h&gt;</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.
</listitem>
<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.
</listitem>
<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.
</listitem>
<varlistentry><term><constant>NI_NUMERICSERV</constant></term>
<listitem>
<para>
The service name is returned as a digit string representing the port number.
</listitem>
<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>
</variablelist>
</para>
<para>
</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>

321
lib/lwres/man/lwres_getnameinfo.html Normal file
View file

@ -0,0 +1,321 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/netdb.h&gt;</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
>.&#13;</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
><P
></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN71"
></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="AEN75"
></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="AEN95"
></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
>

158
lib/lwres/man/lwres_getrrsetbyname.3
View file

@ -12,121 +12,113 @@
.\" 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.3,v 1.4 2001/01/09 21:49:57 bwelling Exp $
.Dd Oct 18, 2000
.Dt LWRES_GETRRSETBYNAME 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_getrrsetbyname ,
.Nm lwres_freerrset
.Nd retrieve DNS records
.Sh SYNOPSIS
.Fd #include <lwres/netdb.h>
.Fd
.Ft int
.Fo lwres_getrrsetbyname
.Fa "const char *hostname"
.Fa "unsigned int rdclass"
.Fa "unsigned int rdtype"
.Fa "unsigned int flags"
.Fa "struct rrsetinfo **res"
.Fc
.Ft void
.Fo lwres_freerrset
.Fa "struct rrsetinfo *rrset"
.Fc
.Pp
.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
int
lwres_getrrsetbyname(const char *hostname);
(unsigned int rdclass);
(unsigned int rdtype);
(unsigned int flags);
(struct rrsetinfo **res);
.sp
void
lwres_freerrset(struct rrsetinfo *rrset);
\fR.PP
The following structures are used:
.Pp
.Bd -literal -offset indent
struct rdatainfo {
unsigned int rdi_length; /* length of data */
unsigned char *rdi_data; /* record data */
.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 */
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 */
};
.Ed
.Sh DESCRIPTION
.Pp
.Fn lwres_getrrsetbyname
.sp
.fi
.SH "DESCRIPTION"
.PP
\fBlwres_getrrsetbyname()\fR
gets a set of resource records associated with a
.Fa hostname ,
.Fa class ,
\fIhostname\fR,
\fIclass\fR,
and
.Fa type .
.Fa hostname
\fItype\fR.
\fIhostname\fR
is
a pointer a to null-terminated string. The
.Fa flags
a pointer a to null-terminated string. The
\fIflags\fR
field is currently unused and must be zero.
.Pp
.PP
After a successful call to
.Fn lwres_getrrsetbyname ,
.Fa *res
\fBlwres_getrrsetbyname()\fR,
\fI*res\fR
is a pointer to an
.Dv rrsetinfo
\fBrrsetinfo\fR
structure, containing a list of one or more
.Dv rdatainfo
\fBrdatainfo\fR
structures containing resource records and potentially another list of
.Dv rdatainfo
\fBrdatainfo\fR
structures containing SIG resource records
associated with those records.
The members
.Li rri_rdclass
rri_rdclass
and
.Li rri_rdtype
rri_rdtype
are copied from the parameters.
.Li rri_ttl
rri_ttl
and
.Li rri_name
rri_name
are properties of the obtained rrset.
The resource records contained in
.Li rri_rdatas
rri_rdatas
and
.Li rri_sigs
rri_sigs
are in uncompressed DNS wire format.
Properties of the rdataset are represented in the
.Li rri_flags
bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC
validated and the signatures verified.
.Pp
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
.Fn lwres_getrrsetbyname
\fBlwres_getrrsetbyname()\fR
is dynamically allocated: the
.Li rrsetinfo
rrsetinfo
and
.Li rdatainfo
rdatainfo
structures,
and the canonical host name strings pointed to by the
.Li rrsetinfo structure.
rrsetinfostructure.
Memory allocated for the dynamically allocated structures created by
a successful call to
.Fn lwres_getrrsetbyname
\fBlwres_getrrsetbyname()\fR
is released by
.Fn lwres_freerrset .
.Fa rrset
\fBlwres_freerrset()\fR.
\fIrrset\fR
is a pointer to a
.Dv "struct rrset"
\fBstruct rrset\fR
created by a call to
.Fn lwres_getrrsetbyname .
.Pp
.Sh RETURN VALUES
.Fn lwres_getrrsetbyname
returns zero on success or an error code if an error occurs. The defined
\fBlwres_getrrsetbyname()\fR.
.PP
.SH "RETURN VALUES"
.PP
\fBlwres_getrrsetbyname()\fR
returns zero on success or an error code if an error occurs. The defined
error codes are ERRSET_NOMEMORY (memory could not be allocated),
ERRSET_INVAL (a parameter is invalid) and ERRSET_FAIL (other failure).
.Sh SEE ALSO
.Xr lwres 3 .
.SH "SEE ALSO"
.PP
\fBlwres\fR(3).

176
lib/lwres/man/lwres_getrrsetbyname.docbook Normal file
View file

@ -0,0 +1,176 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_getrrsetbyname.docbook,v 1.1 2001/03/31 00:08:15 gson 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 &lt;lwres/netdb.h&gt;</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 or an error code if an error occurs. The defined
error codes are ERRSET_NOMEMORY (memory could not be allocated),
ERRSET_INVAL (a parameter is invalid) and ERRSET_FAIL (other failure).
</para>
</refsect1>
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>

310
lib/lwres/man/lwres_getrrsetbyname.html Normal file
View file

@ -0,0 +1,310 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/netdb.h&gt;</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
>.&#13;</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 or an error code if an error occurs. The defined
error codes are ERRSET_NOMEMORY (memory could not be allocated),
ERRSET_INVAL (a parameter is invalid) and ERRSET_FAIL (other failure).</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN66"
></A
><H2
>SEE ALSO</H2
><P
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres</SPAN
>(3)</SPAN
>.</P
></DIV
></BODY
></HTML
>

212
lib/lwres/man/lwres_gnba.3
View file

@ -12,83 +12,66 @@
.\" 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.3,v 1.6 2001/01/09 21:49:58 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_GNBA 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_gnbarequest_render ,
.Nm lwres_gnbaresponse_render ,
.Nm lwres_gnbarequest_parse ,
.Nm lwres_gnbaresponse_parse ,
.Nm lwres_gnbaresponse_free ,
.Nm lwres_gnbarequest_free
.Nd lightweight resolver getnamebyaddress message handling
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
.Ft lwres_result_t
.Fo lwres_gnbarequest_render
.Fa "lwres_context_t *ctx"
.Fa "lwres_gnbarequest_t *req"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_buffer_t *b"
.Fc
.Ft lwres_result_t
.Fo lwres_gnbaresponse_render
.Fa "lwres_context_t *ctx"
.Fa "lwres_gnbaresponse_t *req"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_buffer_t *b"
.Fc
.Ft lwres_result_t
.Fo lwres_gnbarequest_parse
.Fa "lwres_context_t *ctx"
.Fa "lwres_buffer_t *b"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_gnbarequest_t **structp"
.Fc
.Ft lwres_result_t
.Fo lwres_gnbaresponse_parse
.Fa "lwres_context_t *ctx"
.Fa "lwres_buffer_t *b"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_gnbaresponse_t **structp"
.Fc
.Ft void
.Fo lwres_gnbaresponse_free
.Fa "lwres_context_t *ctx"
.Fa "lwres_gnbaresponse_t **structp"
.Fc
.Ft void
.Fo lwres_gnbarequest_free
.Fa "lwres_context_t *ctx"
.Fa "lwres_gnbarequest_t **structp"
.Fc
.Sh DESCRIPTION
.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
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);
.sp
lwres_result_t
lwres_gnbaresponse_render(lwres_context_t *ctx);
(lwres_gnbaresponse_t *req);
(lwres_lwpacket_t *pkt);
(lwres_buffer_t *b);
.sp
lwres_result_t
lwres_gnbarequest_parse(lwres_context_t *ctx);
(lwres_buffer_t *b);
(lwres_lwpacket_t *pkt);
(lwres_gnbarequest_t **structp);
.sp
lwres_result_t
lwres_gnbaresponse_parse(lwres_context_t *ctx);
(lwres_buffer_t *b);
(lwres_lwpacket_t *pkt);
(lwres_gnbaresponse_t **structp);
.sp
void
lwres_gnbaresponse_free(lwres_context_t *ctx);
(lwres_gnbaresponse_t **structp);
.sp
void
lwres_gnbarequest_free(lwres_context_t *ctx);
(lwres_gnbarequest_t **structp);
\fR.SH "DESCRIPTION"
.PP
These are low-level routines for creating and parsing
lightweight resolver address-to-name lookup request and
response messages.
.Pp
.PP
There are four main functions for the getnamebyaddr opcode.
One render function converts a getnamebyaddr request structure -
.Dv lwres_gnbarequest_t -
to the lighweight resolver's canonical format.
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 -
.Dv lwres_gnbaresponse_t
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
.PP
These structures are defined in
.Pa lwres/lwres.h .
\fIlwres/lwres.h\fR.
They are shown below.
.Bd -literal -offset indent
.sp
.nf
#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U
typedef struct {
@ -106,95 +89,98 @@ typedef struct {
void *base;
size_t baselen;
} lwres_gnbaresponse_t;
.Ed
.Pp
.Fn lwres_gnbarequest_render
.sp
.fi
.PP
\fBlwres_gnbarequest_render()\fR
uses resolver context
.Fa ctx
ctx
to convert getnamebyaddr request structure
.Fa req
req
to canonical format.
The packet header structure
.Fa pkt
pkt
is initialised and transferred to
buffer
.Fa b .
b.
The contents of
.Fa *req
*req
are then appended to the buffer in canonical format.
.Fn lwres_gnbaresponse_render
\fBlwres_gnbaresponse_render()\fR
performs the same task, except it converts a getnamebyaddr response structure
.Dv lwres_gnbaresponse_t
\fBlwres_gnbaresponse_t\fR
to the lightweight resolver's canonical format.
.Pp
.Fn lwres_gnbarequest_parse
.PP
\fBlwres_gnbarequest_parse()\fR
uses context
.Fa ctx
ctx
to convert the contents of packet
.Fa pkt
pkt
to a
.Dv lwres_gnbarequest_t
\fBlwres_gnbarequest_t\fR
structure.
Buffer
.Fa b
b
provides space to be used for storing this structure.
When the function succeeds, the resulting
.Dv lwres_gnbarequest_t
\fBlwres_gnbarequest_t\fR
is made available through
.Fa *structp .
.Fn lwres_gnbaresponse_parse
*structp.
\fBlwres_gnbaresponse_parse()\fR
offers the same semantics as
.Fn lwres_gnbarequest_parse
\fBlwres_gnbarequest_parse()\fR
except it yields a
.Dv lwres_gnbaresponse_t
\fBlwres_gnbaresponse_t\fR
structure.
.Pp
.Fn lwres_gnbaresponse_free
.PP
\fBlwres_gnbaresponse_free()\fR
and
.Fn lwres_gnbarequest_free
\fBlwres_gnbarequest_free()\fR
release the memory in resolver context
.Fa ctx
ctx
that was allocated to the
.Dv lwres_gnbaresponse_t
\fBlwres_gnbaresponse_t\fR
or
.Dv lwres_gnbarequest_t
\fBlwres_gnbarequest_t\fR
structures referenced via
.Fa structp .
structp.
Any memory associated with ancillary buffers and strings for those
structures is also discarded.
.Sh RETURN VALUES
.SH "RETURN VALUES"
.PP
The getnamebyaddr opcode functions
.Fn lwres_gnbarequest_render ,
.Fn lwres_gnbaresponse_render
.Fn lwres_gnbarequest_parse
\fBlwres_gnbarequest_render()\fR,
\fBlwres_gnbaresponse_render()\fR
\fBlwres_gnbarequest_parse()\fR
and
.Fn lwres_gnbaresponse_parse
\fBlwres_gnbaresponse_parse()\fR
all return
.Er LWRES_R_SUCCESS
LWRES_R_SUCCESS
on success.
They return
.Er LWRES_R_NOMEMORY
LWRES_R_NOMEMORY
if memory allocation fails.
.Er LWRES_R_UNEXPECTEDEND
LWRES_R_UNEXPECTEDEND
is returned if the available space in the buffer
.Fa b
b
is too small to accommodate the packet header or the
.Dv lwres_gnbarequest_t
\fBlwres_gnbarequest_t\fR
and
.Dv lwres_gnbaresponse_t
\fBlwres_gnbaresponse_t\fR
structures.
.Fn lwres_gnbarequest_parse
\fBlwres_gnbarequest_parse()\fR
and
.Fn lwres_gnbaresponse_parse
\fBlwres_gnbaresponse_parse()\fR
will return
.Er LWRES_R_UNEXPECTEDEND
LWRES_R_UNEXPECTEDEND
if the buffer is not empty after decoding the received packet.
These functions will return
.Er LWRES_R_FAILURE
LWRES_R_FAILURE
if
.Li pktflags
\fBpktflags\fR
in the packet header structure
.Dv lwres_lwpacket_t
\fBlwres_lwpacket_t\fR
indicate that the packet is not a response to an earlier query.
.Sh SEE ALSO
.Xr lwres_packet 3
.SH "SEE ALSO"
.PP
\fBlwres_packet\fR(3).

37
lib/lwres/man/lwres_gnba.docbook
View file

@ -16,7 +16,7 @@
- WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-->
<!-- $Id: lwres_gnba.docbook,v 1.1 2001/03/29 02:23:11 gson Exp $ -->
<!-- $Id: lwres_gnba.docbook,v 1.2 2001/03/31 00:08:16 gson Exp $ -->
<refentry>
@ -24,11 +24,11 @@
<date>Jun 30, 2000</date>
</refentryinfo>
<refmeta>
<refentrytitle>lwres_gnba</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refmeta>
<refentrytitle>lwres_gnba</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>BIND9</refmiscinfo>
</refmeta>
<refnamediv>
<refname>lwres_gnbarequest_render</refname>
@ -115,12 +115,12 @@ 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> -
One render function converts a getnamebyaddr request structure &mdash;
<type>lwres_gnbarequest_t</type> &mdash;
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 -
Another render function converts the getnamebyaddr response structure &mdash;
<type>lwres_gnbaresponse_t</type>
to the canonical format.
This is complemented by a parse function which converts a packet in
@ -219,12 +219,12 @@ The getnamebyaddr opcode functions
and
<function>lwres_gnbaresponse_parse()</function>
all return
<errorname>LWRES_R_SUCCESS</errorname>
<errorcode>LWRES_R_SUCCESS</errorcode>
on success.
They return
<errorname>LWRES_R_NOMEMORY</errorname>
<errorcode>LWRES_R_NOMEMORY</errorcode>
if memory allocation fails.
<errorname>LWRES_R_UNEXPECTEDEND</errorname>
<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
@ -236,10 +236,10 @@ structures.
and
<function>lwres_gnbaresponse_parse()</function>
will return
<errorname>LWRES_R_UNEXPECTEDEND</errorname>
<errorcode>LWRES_R_UNEXPECTEDEND</errorcode>
if the buffer is not empty after decoding the received packet.
These functions will return
<errorname>LWRES_R_FAILURE</errorname>
<errorcode>LWRES_R_FAILURE</errorcode>
if
<structfield>pktflags</structfield>
in the packet header structure
@ -250,9 +250,10 @@ indicate that the packet is not a response to an earlier query.
<refsect1>
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>lwres_packet</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>.
<citerefentry>
<refentrytitle>lwres_packet</refentrytitle>
<manvolnum>3</manvolnum>
</citerefentry>.
</para>
</refsect1>
</refentry>

408
lib/lwres/man/lwres_gnba.html Normal file
View file

@ -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&nbsp;--&nbsp;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 &lt;lwres/lwres.h&gt;</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 &mdash;
<SPAN
CLASS="TYPE"
>lwres_gnbarequest_t</SPAN
> &mdash;
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 &mdash;
<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
>

95
lib/lwres/man/lwres_hstrerror.3
View file

@ -12,61 +12,56 @@
.\" 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.3,v 1.6 2001/01/09 21:50:07 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_ERROR 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_herror ,
.Nm lwres_hstrerror
.Nd lightweight resolver error message generation
.Sh SYNOPSIS
.Fd #include <lwres/netdb.h>
.Fd
.Ft void
.Fo lwres_herror
.Fa "const char *s"
.Fc
.Ft const char *
.Fo lwres_hstrerror
.Fa "int err"
.Fc
.Sh DESCRIPTION
.Fn lwres_herror
.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
void
lwres_herror(const char *s);
.sp
const char *
lwres_hstrerror(int err);
\fR.SH "DESCRIPTION"
.PP
\fBlwres_herror()\fR
prints the string
.Fa s
\fIs\fR
on
.Dv stderr
\fBstderr\fR
followed by the string generated by
.Fn lwres_hstrerror
\fBlwres_hstrerror()\fR
for the error code stored in the global variable
.Li lwres_h_errno .
.Pp
.Fn lwres_hstrerror
lwres_h_errno.
.PP
\fBlwres_hstrerror()\fR
returns an appropriate string for the error code gievn by
.Fa err .
\fIerr\fR.
The values of the error codes and messages are as follows:
.Bl -tag -width HOST_NOT_FOUND
.It Li NETDB_SUCCESS
\*qResolver Error 0 (no error)\*q
.It Li HOST_NOT_FOUND
\*qUnknown host\*q
.It Li TRY_AGAIN
\*qHost name lookup failure\*q
.It Li NO_RECOVERY
\*qUnknown server error\*q
.It Li NO_DATA
\*qNo address associated with name\*q
.El
.Sh RETURN VALUES
The string \*qUnknown resolver error\*q is returned by
.Fn lwres_hstrerror
.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
.Li lwres_h_errno
lwres_h_errno
is not a valid error code.
.Sh SEE ALSO
.Xr herror 3 ,
.Xr lwres_hstrerror 3 .
.SH "SEE ALSO"
.PP
\fBherror\fR(3),
\fBlwres_hstrerror\fR(3).

128
lib/lwres/man/lwres_hstrerror.docbook Normal file
View file

@ -0,0 +1,128 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_hstrerror.docbook,v 1.1 2001/03/31 00:08:18 gson 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 &lt;lwres/netdb.h&gt;</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>
</listitem>
<varlistentry><term><errorcode>HOST_NOT_FOUND</errorcode></term>
<listitem>
<para>
<errorname>Unknown host</errorname>
</listitem>
<varlistentry><term><errorcode>TRY_AGAIN</errorcode></term>
<listitem>
<para>
<errorname>Host name lookup failure</errorname>
</listitem>
<varlistentry><term><errorcode>NO_RECOVERY</errorcode></term>
<listitem>
<para>
<errorname>Unknown server error</errorname>
</listitem>
<varlistentry><term><errorcode>NO_DATA</errorcode></term>
<listitem>
<para>
<errorname>No address associated with name</errorname>
</para>
</listitem>
</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>

248
lib/lwres/man/lwres_hstrerror.html Normal file
View file

@ -0,0 +1,248 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/netdb.h&gt;</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
>.&#13;</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
>

74
lib/lwres/man/lwres_inetntop.3
View file

@ -12,60 +12,54 @@
.\" 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.3,v 1.5 2001/01/09 21:50:08 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_INETNTOP 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_net_ntop
.Nd lightweight resolver IP address presentation
.Sh SYNOPSIS
.Fd #include <lwres/net.h>
.Fd
.Ft const char *
.Fo lwres_net_ntop
.Fa "int af"
.Fa "const void *src"
.Fa "char *dst"
.Fa "size_t size"
.Fc
.Sh DESCRIPTION
.Fn lwres_net_ntop
.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
const char *
lwres_net_ntop(int af);
(const void *src);
(char *dst);
(size_t size);
\fR.SH "DESCRIPTION"
.PP
\fBlwres_net_ntop()\fR
converts an IP address of protocol family
.Fa af
- IPv4 or IPv6 - at location
.Fa src
\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
.PP
The generated string is copied to
.Fa dst
\fIdst\fR
provided
.Fa size
\fIsize\fR
indicates it is long enough to store the ASCII representation
of the address.
.Sh RETURN VALUES
.Pp
.SH "RETURN VALUES"
.PP
If successful, the function returns
.Fa dst :
\fIdst\fR:
a pointer to a string containing
the presentation format of the address.
.Fn lwres_net_ntop
\fBlwres_net_ntop()\fR
returns
.Dv NULL
\fBNULL\fR
and sets the global variable
.Li errno
errno
to
.Er EAFNOSUPPORT
EAFNOSUPPORT
if the protocol family given in
.Fa af
\fIaf\fR
is not supported.
.Sh SEE ALSO
.Xr RFC1884 ,
.Xr inet_ntop 3 ,
.Xr errno 3 .
.SH "SEE ALSO"
.PP
\fBRFC1884\fR,
\fBinet_ntop\fR(3),
\fBerrno\fR(3).

107
lib/lwres/man/lwres_inetntop.docbook Normal file
View file

@ -0,0 +1,107 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_inetntop.docbook,v 1.1 2001/03/31 00:08:19 gson 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 &lt;lwres/net.h&gt;</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>
&mdash; IPv4 or IPv6 &mdash;
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>

201
lib/lwres/man/lwres_inetntop.html Normal file
View file

@ -0,0 +1,201 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/net.h&gt;</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
>
&mdash; IPv4 or IPv6 &mdash;
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
>

214
lib/lwres/man/lwres_noop.3
View file

@ -12,87 +12,70 @@
.\" 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.3,v 1.6 2001/01/09 21:50:12 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_NOOP 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_nooprequest_render ,
.Nm lwres_noopresponse_render ,
.Nm lwres_nooprequest_parse ,
.Nm lwres_noopresponse_parse ,
.Nm lwres_noopresponse_free ,
.Nm lwres_nooprequest_free
.Nd lightweight resolver no-op message handling
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
.Ft lwres_result_t
.Fo lwres_nooprequest_render
.Fa "lwres_context_t *ctx"
.Fa "lwres_nooprequest_t *req"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_buffer_t *b"
.Fc
.Ft lwres_result_t
.Fo lwres_noopresponse_render
.Fa "lwres_context_t *ctx"
.Fa "lwres_noopresponse_t *req"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_buffer_t *b"
.Fc
.Ft lwres_result_t
.Fo lwres_nooprequest_parse
.Fa "lwres_context_t *ctx"
.Fa "lwres_buffer_t *b"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_nooprequest_t **structp"
.Fc
.Ft lwres_result_t
.Fo lwres_noopresponse_parse
.Fa "lwres_context_t *ctx"
.Fa "lwres_buffer_t *b"
.Fa "lwres_lwpacket_t *pkt"
.Fa "lwres_noopresponse_t **structp"
.Fc
.Ft void
.Fo lwres_noopresponse_free
.Fa "lwres_context_t *ctx"
.Fa "lwres_noopresponse_t **structp"
.Fc
.Ft void
.Fo lwres_nooprequest_free
.Fa "lwres_context_t *ctx"
.Fa "lwres_nooprequest_t **structp"
.Fc
.Sh DESCRIPTION
.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
lwres_result_t
lwres_nooprequest_render(lwres_context_t *ctx);
(lwres_nooprequest_t *req);
(lwres_lwpacket_t *pkt);
(lwres_buffer_t *b);
.sp
lwres_result_t
lwres_noopresponse_render(lwres_context_t *ctx);
(lwres_noopresponse_t *req);
(lwres_lwpacket_t *pkt);
(lwres_buffer_t *b);
.sp
lwres_result_t
lwres_nooprequest_parse(lwres_context_t *ctx);
(lwres_buffer_t *b);
(lwres_lwpacket_t *pkt);
(lwres_nooprequest_t **structp);
.sp
lwres_result_t
lwres_noopresponse_parse(lwres_context_t *ctx);
(lwres_buffer_t *b);
(lwres_lwpacket_t *pkt);
(lwres_noopresponse_t **structp);
.sp
void
lwres_noopresponse_free(lwres_context_t *ctx);
(lwres_noopresponse_t **structp);
.sp
void
lwres_nooprequest_free(lwres_context_t *ctx);
(lwres_nooprequest_t **structp);
\fR.SH "DESCRIPTION"
.PP
These are low-level routines for creating and parsing
lightweight resolver no-op request and response messages.
.P
The no-op message is analogous to a \*qping\*q packet:
.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
.PP
There are four main functions for the no-op opcode.
One render function converts a no-op request structure -
.Dv lwres_nooprequest_t -
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 -
.Dv lwres_noopresponse_t
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
.PP
These structures are defined in
.Pa lwres/lwres.h .
\fIlwres/lwres.h\fR.
They are shown below.
.Bd -literal -offset indent
.sp
.nf
#define LWRES_OPCODE_NOOP 0x00000000U
typedef struct {
@ -104,96 +87,99 @@ typedef struct {
lwres_uint16_t datalength;
unsigned char *data;
} lwres_noopresponse_t;
.Ed
.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
.Fn lwres_nooprequest_render
.PP
\fBlwres_nooprequest_render()\fR
uses resolver context
.Fa ctx
\fIctx\fR
to convert no-op request structure
.Fa req
\fIreq\fR
to canonical format.
The packet header structure
.Fa pkt
\fIpkt\fR
is initialised and transferred to
buffer
.Fa b .
\fIb\fR.
The contents of
.Fa *req
\fI*req\fR
are then appended to the buffer in canonical format.
.Fn lwres_noopresponse_render
\fBlwres_noopresponse_render()\fR
performs the same task, except it converts a no-op response structure
.Dv lwres_noopresponse_t
\fBlwres_noopresponse_t\fR
to the lightweight resolver's canonical format.
.Pp
.Fn lwres_nooprequest_parse
.PP
\fBlwres_nooprequest_parse()\fR
uses context
.Fa ctx
\fIctx\fR
to convert the contents of packet
.Fa pkt
\fIpkt\fR
to a
.Dv lwres_nooprequest_t
\fBlwres_nooprequest_t\fR
structure.
Buffer
.Fa b
\fIb\fR
provides space to be used for storing this structure.
When the function succeeds, the resulting
.Dv lwres_nooprequest_t
\fBlwres_nooprequest_t\fR
is made available through
.Fa *structp .
.Fn lwres_noopresponse_parse
\fI*structp\fR.
\fBlwres_noopresponse_parse()\fR
offers the same semantics as
.Fn lwres_nooprequest_parse
\fBlwres_nooprequest_parse()\fR
except it yields a
.Dv lwres_noopresponse_t
\fBlwres_noopresponse_t\fR
structure.
.Pp
.Fn lwres_noopresponse_free
.PP
\fBlwres_noopresponse_free()\fR
and
.Fn lwres_nooprequest_free
\fBlwres_nooprequest_free()\fR
release the memory in resolver context
.Fa ctx
\fIctx\fR
that was allocated to the
.Dv lwres_noopresponse_t
\fBlwres_noopresponse_t\fR
or
.Dv lwres_nooprequest_t
\fBlwres_nooprequest_t\fR
structures referenced via
.Fa structp .
.Sh RETURN VALUES
\fIstructp\fR.
.SH "RETURN VALUES"
.PP
The no-op opcode functions
.Fn lwres_nooprequest_render ,
.Fn lwres_noopresponse_render
.Fn lwres_nooprequest_parse
\fBlwres_nooprequest_render()\fR,
\fBlwres_noopresponse_render()\fR
\fBlwres_nooprequest_parse()\fR
and
.Fn lwres_noopresponse_parse
\fBlwres_noopresponse_parse()\fR
all return
.Er LWRES_R_SUCCESS
LWRES_R_SUCCESS
on success.
They return
.Er LWRES_R_NOMEMORY
LWRES_R_NOMEMORY
if memory allocation fails.
.Er LWRES_R_UNEXPECTEDEND
LWRES_R_UNEXPECTEDEND
is returned if the available space in the buffer
.Fa b
\fIb\fR
is too small to accommodate the packet header or the
.Dv lwres_nooprequest_t
\fBlwres_nooprequest_t\fR
and
.Dv lwres_noopresponse_t
\fBlwres_noopresponse_t\fR
structures.
.Fn lwres_nooprequest_parse
\fBlwres_nooprequest_parse()\fR
and
.Fn lwres_noopresponse_parse
\fBlwres_noopresponse_parse()\fR
will return
.Er LWRES_R_UNEXPECTEDEND
LWRES_R_UNEXPECTEDEND
if the buffer is not empty after decoding the received packet.
These functions will return
.Er LWRES_R_FAILURE
LWRES_R_FAILURE
if
.Li pktflags
pktflags
in the packet header structure
.Dv lwres_lwpacket_t
\fBlwres_lwpacket_t\fR
indicate that the packet is not a response to an earlier query.
.Sh SEE ALSO
.Xr lwres_packet 3
.SH "SEE ALSO"
.PP
\fBlwres_packet\fR(3)

252
lib/lwres/man/lwres_noop.docbook Normal file
View file

@ -0,0 +1,252 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_noop.docbook,v 1.1 2001/03/31 00:08:20 gson 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 &lt;lwres/lwres.h&gt;</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 &mdash;
<type>lwres_nooprequest_t</type> &mdash;
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 &mdash;
<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>

436
lib/lwres/man/lwres_noop.html Normal file
View file

@ -0,0 +1,436 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/lwres.h&gt;</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 &mdash;
<SPAN
CLASS="TYPE"
>lwres_nooprequest_t</SPAN
> &mdash;
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 &mdash;
<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
>.&#13;</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
>

145
lib/lwres/man/lwres_packet.3
View file

@ -12,38 +12,27 @@
.\" 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.3,v 1.6 2001/01/09 21:50:20 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_PACKET 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_lwpacket_renderheader ,
.Nm lwres_lwpacket_parseheader
.Nd lightweight resolver packet handling functions
.Sh SYNOPSIS
.Fd #include <lwres/lwbuffer.h>
.Fd #include <lwres/lwpacket.h>
.Fd #include <lwres/result.h>
.Fd
.Ft lwres_result_t
.Fo lwres_lwpacket_renderheader
.Fa "lwres_buffer_t *b"
.Fa "lwres_lwpacket_t *pkt"
.Fc
.Ft lwres_result_t
.Fo lwres_lwpacket_parseheader
.Fa "lwres_buffer_t *b"
.Fa "lwres_lwpacket_t *pkt"
.Fc
.Sh DESCRIPTION
.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/lwbuffer.h>#include <lwres/lwpacket.h>#include <lwres/result.h>
.sp
lwres_result_t
lwres_lwpacket_renderheader(lwres_buffer_t *b);
(lwres_lwpacket_t *pkt);
.sp
lwres_result_t
lwres_lwpacket_parseheader(lwres_buffer_t *b);
(lwres_lwpacket_t *pkt);
\fR.SH "DESCRIPTION"
.PP
These functions rely on a
.Dv "struct lwres_lwpacket"
\fBstruct lwres_lwpacket\fR
which is defined in
.Pa lwres/lwpacket.h .
.Bd -literal -offset indent
\fIlwres/lwpacket.h\fR.
.sp
.nf
typedef struct lwres_lwpacket lwres_lwpacket_t;
struct lwres_lwpacket {
@ -57,108 +46,118 @@ struct lwres_lwpacket {
lwres_uint16_t authtype;
lwres_uint16_t authlength;
};
.Ed
.Pp
.Pp
.sp
.fi
.PP
.PP
The elements of this structure are:
.Bl -tag -width recvlength
.It Li length
.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.
.It Li version
.TP
\fBversion\fR
the header format. There is currently only one format,
.Dv LWRES_LWPACKETVERSION_0 .
\fBLWRES_LWPACKETVERSION_0\fR.
This field is filled in by the lwres_gabn_*() and lwres_gnba_*()
calls.
.It Li pktflags
.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.
.It Li serial
.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.
.It Li opcode
.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.
.It Li result
.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.
.It Li recvlength
.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.
.It Li authtype
.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.
.It Li authlen
.TP
\fBauthlen\fR
gives the length of the authentication data.
Since packet authentication is currently not used, this must be zero.
.El
.Pp
.PP
The following opcodes are currently defined:
.Bl -tag -width GETADDRSBYNAME
.It Li NOOP
.TP
\fBNOOP\fR
Success is always returned and the packet contents are echoed.
The lwres_noop_*() functions should be used for this type.
.It Li GETADDRSBYNAME
.TP
\fBGETADDRSBYNAME\fR
returns all known addresses for a given name.
The lwres_gabn_*() functions should be used for this type.
.It Li GETNAMEBYADDR
.TP
\fBGETNAMEBYADDR\fR
return the hostname for the given address.
The lwres_gnba_*() functions should be used for this type.
.El
.Pp
.Fn lwres_lwpacket_renderheader
.PP
\fBlwres_lwpacket_renderheader()\fR
transfers the contents of lightweight resolver packet structure
.Dv lwres_lwpacket_t
.Fa *pkt
\fBlwres_lwpacket_t\fR
\fI*pkt\fR
in network byte order to the lightweight resolver buffer,
.Fa *b .
.Pp
.Fn lwres_lwpacket_parseheader
\fI*b\fR.
.PP
\fBlwres_lwpacket_parseheader()\fR
performs the converse operation.
It transfers data in network byte order from buffer
.Fa *b
\fI*b\fR
to resolver packet
.Fa *pkt .
\fI*pkt\fR.
The contents of the buffer
.Fa b
\fIb\fR
should correspond to a
.Dv "lwres_lwpacket_t" .
.Pp
\fBlwres_lwpacket_t\fR.
.PP
Both functions have assertion checks to ensure that
.Fa b
\fIb\fR
and
.Fa pkt
\fIpkt\fR
are not
.Dv NULL .
.Sh RETURN VALUES
\fBNULL\fR.
.SH "RETURN VALUES"
.PP
Successful calls to
.Fn lwres_lwpacket_renderheader
\fBlwres_lwpacket_renderheader()\fR
and
.Fn lwres_lwpacket_parseheader
\fBlwres_lwpacket_parseheader()\fR
return
.Er LWRES_R_SUCCESS .
LWRES_R_SUCCESS.
If there is insufficient space to copy data between the buffer
.Fa *b
\fI*b\fR
and lightweight resolver packet
.Fa *pkt
\fI*pkt\fR
both functions return
.Er LWRES_R_UNEXPECTEDEND .
LWRES_R_UNEXPECTEDEND.

240
lib/lwres/man/lwres_packet.docbook Normal file
View file

@ -0,0 +1,240 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_packet.docbook,v 1.1 2001/03/31 00:08:22 gson 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 &lt;lwres/lwbuffer.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;lwres/lwpacket.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;lwres/result.h&gt;</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>
</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.
</listitem>
<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.
</listitem>
<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.
</listitem>
<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.
</listitem>
<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.
</listitem>
<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.
</listitem>
<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.
</listitem>
<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.
</listitem>
<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>
</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.
</listitem>
<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.
</listitem>
<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>
</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>
<para>
Both functions have assertion checks to ensure that
<parameter>b</parameter>
and
<parameter>pkt</parameter>
are not
<type>NULL</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>

413
lib/lwres/man/lwres_packet.html Normal file
View file

@ -0,0 +1,413 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/lwbuffer.h&gt;</PRE
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include &lt;lwres/lwpacket.h&gt;</PRE
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include &lt;lwres/result.h&gt;</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="AEN27"
></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
></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
>.&#13;</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
>.&#13;</P
><P
>Both functions have assertion checks to ensure that
<TT
CLASS="PARAMETER"
><I
>b</I
></TT
>
and
<TT
CLASS="PARAMETER"
><I
>pkt</I
></TT
>
are not
<SPAN
CLASS="TYPE"
>NULL</SPAN
>.&#13;</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN114"
></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
>.&#13;</P
></DIV
></BODY
></HTML
>

220
lib/lwres/man/lwres_resutil.3
View file

@ -12,96 +12,83 @@
.\" 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.3,v 1.5 2001/01/09 21:50:21 bwelling Exp $
.Dd Jun 30, 2000
.Dt LWRES_RESUTIL 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm lwres_string_parse ,
.Nm lwres_addr_parse ,
.Nm lwres_getaddrsbyname ,
.Nm lwres_getnamebyaddr
.Nd lightweight resolver utility functions
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
.Ft lwres_result_t
.Fo lwres_string_parse
.Fa "lwres_buffer_t *b"
.Fa "char **c"
.Fa "lwres_uint16_t *len"
.Fc
.Ft lwres_result_t
.Fo lwres_addr_parse
.Fa "lwres_buffer_t *b"
.Fa "lwres_addr_t *addr"
.Fc
.Ft lwres_result_t
.Fo lwres_getaddrsbyname
.Fa "lwres_context_t *ctx"
.Fa "const char *name"
.Fa "lwres_uint32_t addrtypes"
.Fa "lwres_gabnresponse_t **structp"
.Fc
.Ft lwres_result_t
.Fo lwres_getnamebyaddr
.Fa "lwres_context_t *ctx"
.Fa "lwres_uint32_t addrtype"
.Fa "lwres_uint16_t addrlen"
.Fa "const unsigned char *addr"
.Fa "lwres_gnbaresponse_t **structp"
.Fc
.Sh DESCRIPTION
.Fn lwres_string_parse
.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
lwres_result_t
lwres_string_parse(lwres_buffer_t *b);
(char **c);
(lwres_uint16_t *len);
.sp
lwres_result_t
lwres_addr_parse(lwres_buffer_t *b);
(lwres_addr_t *addr);
.sp
lwres_result_t
lwres_getaddrsbyname(lwres_context_t *ctx);
(const char *name);
(lwres_uint32_t addrtypes);
(lwres_gabnresponse_t **structp);
.sp
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);
\fR.SH "DESCRIPTION"
.PP
\fBlwres_string_parse()\fR
retrieves a DNS-encoded string starting the current pointer of
lightweight resolver buffer
.Fa b :
\fIb\fR:
i.e.
.Li b->current .
b->current.
When the function returns, the address of the first byte of the
encoded string is returned via
.Fa *c
\fI*c\fR
and the length of that string is given by
.Fa *len .
\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
.Dv NULL
\fBNULL\fR
character.
.Fn lwres_string_parse
\fBlwres_string_parse()\fR
has an assertion check that
.Fa b
\fIb\fR
is not
.Dv NULL .
.Pp
.Fn lwres_addr_parse
\fBNULL\fR.
.PP
\fBlwres_addr_parse()\fR
extracts an address from the buffer
.Fa b .
\fIb\fR.
It checks that
.Fa addr
\fIaddr\fR
is not null.
The buffer's current pointer
.Li b->current
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
.Li addr->address
addr->address
and
.Li addr->length
addr->length
indicates the size in bytes of the address that was copied.
.Li b->current
b->current
is advanced to point at the next byte of available data in the buffer
following the encoded address.
.Pp
.Fn lwres_getaddrsbyname
.PP
\fBlwres_getaddrsbyname()\fR
and
.Fn lwres_getnamebyaddr
\fBlwres_getnamebyaddr()\fR
use the
.Dv "lwres_gnbaresponse_t"
\fBlwres_gnbaresponse_t\fR
structure defined below:
.Bd -literal -offset indent
.sp
.nf
typedef struct {
lwres_uint32_t flags;
lwres_uint16_t naliases;
@ -114,102 +101,105 @@ typedef struct {
void *base;
size_t baselen;
} lwres_gabnresponse_t;
.Ed
.sp
.fi
The contents of this structure are not manipulated directly but
they are controlled through the
.Xr lwres_gabn 3
\fBlwres_gabn\fR(3)
functions.
.Pp
.PP
The lightweight resolver uses
.Fn lwres_getaddrsbyname
\fBlwres_getaddrsbyname()\fR
to perform foward lookups.
Hostname
.Fa name
\fIname\fR
is looked up using the resolver context
.Fa ctx
\fIctx\fR
for memory allocation.
.Fa addrtypes
\fIaddrtypes\fR
is a bitmask indicating which type of addresses are to be looked up.
Current values for this bitmask are
.Dv LWRES_ADDRTYPE_V4
\fBLWRES_ADDRTYPE_V4\fR
for IPv4 addresses and
.Dv LWRES_ADDRTYPE_V6
\fBLWRES_ADDRTYPE_V6\fR
for IPv6 addresses.
Results of the lookup are returned in
.Fa *structp .
.Fn lwres_getaddrsbyname
\fI*structp\fR.
\fBlwres_getaddrsbyname()\fR
checks that its pointer arguments are not
.Dv NULL
\fBNULL\fR
and that
.Fa addrtypes
\fIaddrtypes\fR
is non-zero.
.Pp
.Fn lwres_getnamebyaddr
.PP
\fBlwres_getnamebyaddr()\fR
performs reverse lookups.
Resolver context
.Fa ctx
\fIctx\fR
is used for memory allocation.
The address type is indicated by
.Fa addrtype :
.Dv LWRES_ADDRTYPE_V4
\fIaddrtype\fR:
\fBLWRES_ADDRTYPE_V4\fR
or
.Dv LWRES_ADDRTYPE_V6 .
\fBLWRES_ADDRTYPE_V6\fR.
The address to be looked up is given by
.Fa addr
\fIaddr\fR
and its length is
.Fa addrlen
\fIaddrlen\fR
bytes.
The result of the function call is made available through
.Fa *structp .
\fI*structp\fR.
Like
.Fn lwres_getaddrsbyname ,
.Fn lwres_getnamebyaddr
\fBlwres_getaddrsbyname()\fR,
\fBlwres_getnamebyaddr()\fR
uses assertion checking to ensure its pointer arguments are not
.Dv NULL
\fBNULL\fR
and
.Fa addrtype
\fIaddrtype\fR
is not zero.
.Fn lwres_getaddrsbyname
\fBlwres_getaddrsbyname()\fR
also checks that
.Fa addrlen
\fIaddrlen\fR
is non-zero.
.Sh RETURN VALUES
.SH "RETURN VALUES"
.PP
Successful calls to
.Fn lwres_string_parse
\fBlwres_string_parse()\fR
and
.Fn lwres_addr_parse
\fBlwres_addr_parse()\fR
return
.Er LWRES_R_SUCCESS.
LWRES_R_SUCCESS.
Both functions return
.Er LWRES_R_FAILURE
LWRES_R_FAILURE
if the buffer is corrupt or
.Er LWRES_R_UNEXPECTEDEND
LWRES_R_UNEXPECTEDEND
if the buffer has less space than expected for the components of the
encoded string or address.
.Pp
.Fn lwres_getaddrsbyname
.PP
\fBlwres_getaddrsbyname()\fR
returns
.Er LWRES_R_SUCCESS
LWRES_R_SUCCESS
on success and it returns
.Er LWRES_R_NOTFOUND
LWRES_R_NOTFOUND
if the hostname
.Fa name
\fIname\fR
could not be found.
.Pp
.Er LWRES_R_SUCCESS
.PP
LWRES_R_SUCCESS
is returned by a successful call to
.Fn lwres_getnamebyaddr .
.Pp
\fBlwres_getnamebyaddr()\fR.
.PP
Both
.Fn lwres_getaddrsbyname
\fBlwres_getaddrsbyname()\fR
and
.Fn lwres_getnamebyaddr
\fBlwres_getnamebyaddr()\fR
return
.Er LWRES_R_NOMEMORY
LWRES_R_NOMEMORY
when memory allocation requests fail and
.Er LWRES_R_UNEXPECTEDEND
LWRES_R_UNEXPECTEDEND
if the buffers used for sending queries and receiving replies are too
small.
.Sh SEE ALSO
.Xr lwres_buffer 3 ,
.Xr lwres_gabn 3 .
.SH "SEE ALSO"
.PP
\fBlwres_buffer\fR(3),
\fBlwres_gabn\fR(3).

276
lib/lwres/man/lwres_resutil.docbook Normal file
View file

@ -0,0 +1,276 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<!--
- 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.
-->
<!-- $Id: lwres_resutil.docbook,v 1.1 2001/03/31 00:08:23 gson 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 &lt;lwres/lwres.h&gt;</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-&gt;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.
<function>lwres_string_parse()</function>
has an assertion check that
<parameter>b</parameter>
is not
<type>NULL</type>.
</para>
<para>
<function>lwres_addr_parse()</function>
extracts an address from the buffer
<parameter>b</parameter>.
It checks that
<parameter>addr</parameter>
is not null.
The buffer's current pointer
<constant>b-&gt;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-&gt;address</constant>
and
<constant>addr-&gt;length</constant>
indicates the size in bytes of the address that was copied.
<constant>b-&gt;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>.
<function>lwres_getaddrsbyname()</function>
checks that its pointer arguments are not
<type>NULL</type>
and that
<parameter>addrtypes</parameter>
is non-zero.
</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>.
Like
<function>lwres_getaddrsbyname()</function>,
<function>lwres_getnamebyaddr()</function>
uses assertion checking to ensure its pointer arguments are not
<type>NULL</type>
and
<parameter>addrtype</parameter>
is not zero.
<function>lwres_getaddrsbyname()</function>
also checks that
<parameter>addrlen</parameter>
is non-zero.
</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>

524
lib/lwres/man/lwres_resutil.html Normal file
View file

@ -0,0 +1,524 @@
<!--
- 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&nbsp;--&nbsp;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 &lt;lwres/lwres.h&gt;</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-&gt;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.
<TT
CLASS="FUNCTION"
>lwres_string_parse()</TT
>
has an assertion check that
<TT
CLASS="PARAMETER"
><I
>b</I
></TT
>
is not
<SPAN
CLASS="TYPE"
>NULL</SPAN
>.&#13;</P
><P
><TT
CLASS="FUNCTION"
>lwres_addr_parse()</TT
>
extracts an address from the buffer
<TT
CLASS="PARAMETER"
><I
>b</I
></TT
>.
It checks that
<TT
CLASS="PARAMETER"
><I
>addr</I
></TT
>
is not null.
The buffer's current pointer
<TT
CLASS="CONSTANT"
>b-&gt;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-&gt;address</TT
>
and
<TT
CLASS="CONSTANT"
>addr-&gt;length</TT
>
indicates the size in bytes of the address that was copied.
<TT
CLASS="CONSTANT"
>b-&gt;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
>.
<TT
CLASS="FUNCTION"
>lwres_getaddrsbyname()</TT
>
checks that its pointer arguments are not
<SPAN
CLASS="TYPE"
>NULL</SPAN
>
and that
<TT
CLASS="PARAMETER"
><I
>addrtypes</I
></TT
>
is non-zero.</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
>.
Like
<TT
CLASS="FUNCTION"
>lwres_getaddrsbyname()</TT
>,
<TT
CLASS="FUNCTION"
>lwres_getnamebyaddr()</TT
>
uses assertion checking to ensure its pointer arguments are not
<SPAN
CLASS="TYPE"
>NULL</SPAN
>
and
<TT
CLASS="PARAMETER"
><I
>addrtype</I
></TT
>
is not zero.
<TT
CLASS="FUNCTION"
>lwres_getaddrsbyname()</TT
>
also checks that
<TT
CLASS="PARAMETER"
><I
>addrlen</I
></TT
>
is non-zero.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN97"
></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
>.&#13;</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="AEN118"
></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
>