ComputerSurge/bind9
3
0
Fork 0
Code Pull Requests 1 Activity

checkpoint

Browse Source
This commit is contained in:
Andreas Gustafsson
2000-09-28 22:36:33 +00:00
parent c4016fd2bd
commit 23bfeb8bb1
20 changed files with 558 additions and 920 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/man/lwres/lwres_buffer.3
+53 -82
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:20:26 tale Exp $
.\" $Id: lwres_buffer.3,v 1.4 2000/09/28 22:36:23 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_BUFFER 3
@@ -118,24 +118,13 @@
.Fa "unsigned int length"
.Fc
.Sh DESCRIPTION
These functions use the following structure as a buffer descriptor to
manage the actual storage:
.Bd -literal -offset indent
typedef struct lwres_buffer lwres_buffer_t;
struct lwres_buffer {
unsigned int magic;
unsigned char *base;
/* The following integers are byte offsets from 'base'. */
unsigned int length;
unsigned int used;
unsigned int current;
unsigned int active;
};
.Ed
The main reason for making the buffer structure public is so that
buffer operations can be implemented using macros.
Applications should not manipulate this structure directly.
They should use the functions listed below.
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_
functions in the ISC library.
.Pp
A buffer is a region of memory, together with a set of related
subregions.
@@ -168,33 +157,42 @@ Initially, the active region is empty.
If the current offset advances beyond the chosen offset,
the active region will also be empty.
.Pp
Except for
.Fn lwres_buffer_init ,
all of the buffer managements functions contain an assertion check
that
.Fa b
is a pointer to a valid lightweight resolver buffer.
.Bd -literal -offset indent
/------------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.
.Ed
.Pp
.Fn lwres_buffer_init
makes the
.Dv "struct lwres_buffer"
referenced by
initializes the
.Dv lwres_buffer_t
.Fa *b
to be associated with a memory region of size
and assocates it with the memory region of size
.Fa length
bytes starting at location
.Fa base.
The function checks that
.Fa *b is not
.Dv NULL .
.Pp
The
.Dv lwres_buffer_t
.Fa *b
is invalidated by
.Fn lwres_buffer_invalidate .
.Fa *b
must be a valid lightweight resolver buffer.
.Fn lwres_buffer_invalidate
marks the buffer
.Fa *b
as invalid. Invalidating a buffer after use is not required,
but makes it possible to catch its possible accidental use.
.Pp
The functions
.Fn lwres_buffer_add
@@ -206,70 +204,62 @@ buffer
by
.Fa n
bytes.
.Fa *b
.Fn lwres_buffer_add
checks for buffer overflow and
.Fn lwres_buffer_subtract
checks for underflow.
These functions do not allocate or deallocate memory.
They just change the value of
.Li b->used .
.Li used .
.Pp
A lightweight resolver buffer is re-initialised by
A buffer is re-initialised by
.Fn lwres_buffer_clear .
The function sets
.Li b->used ,
.Li b->current
.Li used ,
.Li current
and
.Li b->active
.Li active
to zero.
.Pp
.Fn lwres_buffer_first
makes the consumed region of buffer
.Fa *p
empty by setting
.Li b->current
to zero: the start of the buffer.
.Li current
to zero (the start of the buffer).
.Pp
The consumed region of buffer
.Fn lwres_buffer_forward
increases the consumed region of buffer
.Fa *b
is increased by
by
.Fa n
bytes
using
.Fn lwres_buffer_forward .
The function checks for buffer overflow.
bytes, checking for overflow.
Similarly,
.Fn lwres_buffer_back
decreases buffer
.Fa b 's
consumed region by
.Fa n
bytes and checks for buffer underflow.
bytes and checks for underflow.
.Pp
.Fn lwres_buffer_getuint8
reads an unsigned 8-bit integer from
.Fa *b
and returns it.
The function checks that it does not read past the end of the buffer's
consumed region.
.Fn lwres_buffer_putuint8
writes the unsigned 8-bit integer
.Fa val
to buffer
.Fa *b .
It checks that the buffer has available space for
.Fa val .
.Pp
.Fn lwres_buffer_getuint16
and
.Fn lwres_buffer_getuint32
are identical to
.Fn lwres_buffer_putuint8
except that they respectively read an unsigned 16-bit or 32-bit integer from
.Fa b
converting it from network byte order to host byte order before
returning its value.
except that they respectively read an unsigned 16-bit or 32-bit integer
in network byte order from
.Fa b .
Similarly,
.Fn lwres_buffer_putuint16
and
@@ -278,7 +268,7 @@ writes the unsigned 16-bit or 32-bit integer
.Fa val
to buffer
.Fa b ,
converting it from host byte order to network byte order.
in network byte order.
.Pp
Arbitrary amounts of data are read or written from a lightweight
resolver buffer with
@@ -301,23 +291,4 @@ bytes of memory from
.Fa b
to
.Fa base .
For both functions,
.Fa base
should point to at least
.Fa length
bytes of valid memory.
.Fa base
.Sh RETURN VALUES
.Fn lwres_buffer_getuint8 ,
.Fn lwres_buffer_getuint16
and
.Fn lwres_buffer_getuint32
return an 8-, 16- or 32-bit unsigned integer respectively from the
current offset in buffer
.Fa b .
The 16- and 32-bit quantities are presented in host byte order even
though they are stored in network byte order inside the buffer.
.Sh SEE ALSO
.Sh BUGS
Buffers have no synchronization.
Clients must ensure exclusive access for thread-safe operations.
doc/man/lwres/lwres_context.3
+67 -111
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:20:52 tale Exp $
.\" $Id: lwres_context.3,v 1.4 2000/09/28 22:36:24 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_CONTEXT 3
@@ -27,7 +27,7 @@
.Nm lwres_context_freemem ,
.Nm lwres_context_allocmem ,
.Nm lwres_context_sendrecv
.Nd lightweight resolver memory allocation routines
.Nd lightweight resolver context management
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
@@ -43,14 +43,14 @@
.Fa "lwres_context_t **contextp"
.Fc
.Ft void
.Fo lwres_context_nextserial
.Fa "lwres_context_t *ctx"
.Fc
.Ft lwres_uint32_t
.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"
@@ -71,95 +71,81 @@
.Fa "int recvlen"
.Fa "int *recvd_len"
.Fc
.Bd -literal -offset indent
struct lwres_context {
unsigned int timeout; /* time to wait for reply */
lwres_uint32_t serial; /* serial number state */
/*
* For network I/O.
*/
int sock; /* socket to send on */
/*
* Function pointers for allocating memory.
*/
lwres_malloc_t malloc;
lwres_free_t free;
void *arg;
/*
* resolv.conf-like data
*/
lwres_conf_t confdata;
};
typedef struct lwres_context lwres_context_t;
.Ed
.Sh DESCRIPTION
.Fn lwres_context_create
is used to create a
creates a
.Dv lwres_context_t
structure for use in lightweight resolver operations and associate
general purpose memory allocation functions with that structure.
.Fa *contextp
is a pointer to a
.Dv "struct lwres_context" .
It must be non-NULL, which in turn implies that
.Fa **contextp
is also non-NULL.
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
is returned throught
.Fa contextp ,
a pointer to a
.Dv "lwres_context_t"
pointer. This
.Dv "lwres_context_t"
pointer must initially be NULL, and is modified
to point to the newly created
.Dv "lwres_context_t" .
.Pp
When the lightweight resolver needs to perform dynamic memory
allocation, it will call
.Fa malloc_function
to allocate memory and
.Fa free_function
to free it. If
.Fa malloc_function
and
.Fa free_function
are pointers to the functions the context should use for allocating
and freeing memory respectively.
Both function pointers must either be non-NULL or NULL.
It is not permitted to use a custom allocator - i.e
.Fa malloc_function
is non-NULL -
with a NULL
.Fa free_function
or vice versa.
If both function pointers are NULL, the lightweight resolver's
internal allocation routines which call
.Fa free_function
are NULL, memory is allocated using
.Xr malloc 3
and
.Xr free 3
are used.
.Xr free 3 .
It is not permitted to have a NULL
.Fa malloc_function
and a non-NULL
.Fa free_function
or vice versa.
.Fa arg
is passed as the initial parameter to the memory
allocation functions.
The argument is passed but not used in the internal allocation
and deallocation routines.
is passed as the first parameter to the memory
allocation functions.
If
.Fa malloc_function
and
.Fa free_function
are NULL,
.Fa arg
is unused and should be passed as NULL.
.P
Once memory for the structure has been allocated,
.Xr lwres_conf_init 3
is called to initialise it.
The structure is then returned via
it is initialized using
.Xr lwres_conf_init 3
and returned via
.Fa *contextp .
.Pp
A
.Dv "struct lwres_context"
is destroyed by
.Fn lwres_context_destroy.
.Fa **contextp
.Fn lwres_context_destroy
destroys a
.Dv "lwres_context_t" ,
closing its socket.
.Fa contextp
is a pointer to a pointer to the context that is to be destroyed.
It must be non-NULL, as should
.Fa *contextp .
If the context has an open socket, it is closed before the structure
is discarded.
The pointer will be set to NULL when the context has been destroyed.
.Pp
The context's serial number is controlled with
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
and
.Fn lwres_context_nextserial .
Both require that
.Fa ctx
is not NULL.
.Fn lwres_context_initserial
sets the serial number for context
.Fa *ctx
to
.Fa serial .
.Fn lwres_context_nextserial
returns the current serial number for the context and increments
.Dv ctx->serial .
increments the serial number and returns the previous value.
.Pp
Memory for a lightweight resolver context is allocated and freed using
.Fn lwres_context_allocmem
@@ -182,38 +168,16 @@ frees
.Fa len
bytes of space starting at location
.Fa mem .
It has assertion checks to ensure that
.Fa mem
is not null and
.Fa len
is not zero.
.Pp
If the lightweight resolver's memory allocation functions are used,
.Fa len
bytes in the allocated buffer will be set to '0xe5' on allocation
or '0xa9' when they are freed.
.Pp
.Fn lwres_context_sendrecv
performs I/O for the context
.Fa ctx .
Data are read and written from the context's socket
.Dv ctx->sock .
Data are read and written from the context's socket.
It writes data from
.Fa sendbase
- typically a DNS query -
- typically a lightweight resolver query packet -
and waits for a reply which is copied to the receive buffer at
.Fa recvbase .
.Fa sendbase
is a pointer to the
.Fa sendlen
bytes of data that are to be sent using
.Xr sendto 2.
Up to
.Fn recvlen
bytes of data that are returned by a call to
.Xr recvfrom 2
on the socket are copied to
.Fa recvbase .
The number of bytes that were written to this receive buffer is
returned in
.Fa *recvd_len .
@@ -223,9 +187,9 @@ returns
.Er LWRES_R_NOMEMORY
if memory for the
.Dv "struct lwres_context"
could not be allocated, otherwise
could not be allocated,
.Er LWRES_R_SUCCESS
is returned.
otherwise.
.Pp
Successful calls to the memory allocator
.Fn lwres_context_allocmem
@@ -239,18 +203,10 @@ completes successfully.
.Er LWRES_R_IOERROR
is returned if an I/O error occurs and
.Er LWRES_R_TIMEOUT
is returned if the
.Xr recvfrom 2
call times out.
is returned if
.Fn lwres_context_sendrecv
times out waiting for a response.
.Sh SEE ALSO
.Xr lwres_conf_init 3 ,
.Xr malloc 3 ,
.Xr free 3 ,
.Xr close 2 ,
.Xr memset 3 ,
.Xr sendto 2 ,
.Xr recvfrom 2 .
.Sh BUGS
The
.Dv lwres_context_t
structures and the functions which operate on them are not thread-safe.
.Xr free 3
doc/man/lwres/lwres_gabn.3
+7 -8
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:05 tale Exp $
.\" $Id: lwres_gabn.3,v 1.4 2000/09/28 22:36:25 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GABN 3
@@ -26,7 +26,7 @@
.Nm lwres_gabnresponse_parse ,
.Nm lwres_gabnresponse_free ,
.Nm lwres_gabnrequest_free
.Nd lightweight resolver getaddrbyname functions
.Nd lightweight resolver getaddrbyname message handling
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
@@ -69,11 +69,10 @@
.Fa "lwres_gabnrequest_t **structp"
.Fc
.Sh DESCRIPTION
These functions implement the lightweight resolver's getaddrbyname opcode
.Dv LWRES_OPCODE_GETADDRSBYNAME .
They provide a forward lookup mechanism, mapping a hostname to its
address or addresses.
.Pp
These are low-level routines for creating and parsing
lightweight resolver name-to-address lookup request and
response messages.
.P
There are four main functions for the getaddrbyname opcode.
One render function converts a getaddrbyname request structure -
.Dv lwres_gabnrequest_t -
@@ -87,7 +86,7 @@ This is complemented by a parse function which converts a packet in
canonical format to a getaddrbyname response structure.
.Pp
These structures are defined in
.Pa lwres/lwres.h .
.Pa <lwres/lwres.h> .
They are shown below.
.Bd -literal -offset indent
#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
doc/man/lwres/lwres_gai_strerror.3
+10 -12
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:12 tale Exp $
.\" $Id: lwres_gai_strerror.3,v 1.4 2000/09/28 22:36:26 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GAI_STRERROR 3
@@ -30,16 +30,11 @@
.Fa "int ecode"
.Fc
.Sh DESCRIPTION
.Fn gai_strerror
returns a suitable error message for the error code
.Fa ecode .
The message \*qinvalid error code\*q is returned if
.Fa ecode
is out of range.
.Fn lwres_gai_strerror
returns an error message corresponding to an error code returned by
.Fn getaddrinfo .
The following error codes and their meaning are defined in
.Aq Pa include/lwres/netdb.h .
They can be returned by
.Fn getaddrinfo .
.Bl -tag -width EAI_ADDRFAMILY -offset indent -compact
.It Dv EAI_ADDRFAMILY
address family for hostname not supported
@@ -68,17 +63,20 @@ not supported
.It Dv EAI_SYSTEM
system error returned in errno
.El
The message \*qinvalid error code\*q is returned if
.Fa ecode
is out of range.
.Pp
.Li ai_flags ,
.Li ai_family
and
.Li ai_socktype
are elements of the
.Dv "struct addrinfo" used by
.Dv "struct addrinfo"
used by
.Fn lwres_getaddrinfo .
.Sh SEE ALSO
.Xr errno 2 ,
.Xr perror 3 ,
.Xr strerror 3 ,
.Xr lwres_getaddrinfo 3 ,
.Xr getaddrinfo 3 ,
.Xr RFC2133 .
doc/man/lwres/lwres_getaddrinfo.3
+23 -25
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:13 tale Exp $
.\" $Id: lwres_getaddrinfo.3,v 1.4 2000/09/28 22:36:27 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GETADDRINFO 3
@@ -40,7 +40,8 @@
.Pp
If the operating system does not provide a
.Dv "struct addrinfo" ,
the following structure is used
the following structure is used:
.Pp
.Bd -literal -offset indent
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
@@ -58,7 +59,7 @@ struct addrinfo {
.Fn lwres_getaddrinfo
is used to get a list of IP addresses and port numbers for host
.Fa hostname
and
and service
.Fa servname .
The function is the lightweight resolver's implementation of
.Fn getaddrinfo
@@ -66,12 +67,12 @@ as defined in RFC2133.
.Fa hostname
and
.Fa servname
arguments are pointers to null-terminated
are pointers to null-terminated
strings or
.Dv NULL .
.Fa hostname
either a host name or a numeric host address string: a dotted decimal
IPv4 address or an IPv6 hex address.
is either a host name or a numeric host address string: a dotted decimal
IPv4 address or an IPv6 address.
.Fa servname
is either a decimal port number or a service name as listed in
.Pa /etc/services .
@@ -103,12 +104,13 @@ When
.Li ai_socktype
is zero the caller will accept any socket type.
.It Li ai_protocol
indicates which transport protocol is wanted: UDP or TCP.
indicates which transport protocol is wanted: IPPROTO_UDP or
IPPROTO_TCP.
If
.Li ai_protocol
is zero the caller will accept any protocol.
.It Li ai_flags
sets some flag bits.
Flag bits.
If the
.Dv AI_CANONNAME
bit is set, a successful call to
@@ -161,14 +163,9 @@ If
is set to
.Dv AI_NUMERICHOST
it indicates that
the
.Dv non-NuLL
.Fa hostname
should be treated as a numeric string defining an IPv4 or IPv6 address.
This will prevent a numeric IPv4 address from being considered as a domain
name when
.Fn lwres_getaddrinfo
is looking for IPv6 addresses or vice versa.
should be treated as a numeric string defining an IPv4 or IPv6 address
and no name resolution should be attempted.
.El
.Pp
All other elements of the
@@ -177,14 +174,13 @@ passed via
.Fa arg
must be zero.
.Pp
If
An
.Fa arg
is not supplied, a
of
.Dv NULL
pointer should be given for this argument.
It will be treated as if the caller provided an
is treated as if the caller provided a
.Dv "struct addrinfo"
structure initialized to zero with
initialized to zero with
.Li ai_family set to
.Li PF_UNSPEC .
.Pp
@@ -195,7 +191,8 @@ is a pointer to a linked list of one or more
.Dv addrinfo
structures.
Each
.Dv "struct addrinfo" in this list cn be processed by following
.Dv "struct addrinfo"
in this list cn be processed by following
the
.Li ai_next
pointer, until a
@@ -203,7 +200,7 @@ pointer, until a
pointer is encountered.
The three members
.Li ai_family ,
ai_socktype,
.Li ai_socktype ,
and
.Li ai_protocol
in each
@@ -230,7 +227,8 @@ is released by
.Fn lwres_freeaddrinfo .
.Fa ai
is a pointer to a
.Dv "struct addrinfo" created by a call to
.Dv "struct addrinfo"
created by a call to
.Fn lwres_getaddrinfo .
.Sh RETURN VALUES
.Fn lwres_getaddrinfo
@@ -247,13 +245,13 @@ are
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 bind 2 ,
.Xr connect 2 ,
.Xr sendto 2 ,
.Xr sendmsg 2 ,
doc/man/lwres/lwres_gethostent.3
+32 -76
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:21 tale Exp $
.\" $Id: lwres_gethostent.3,v 1.4 2000/09/28 22:36:28 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GETHOSTENT 3
@@ -96,16 +96,15 @@
.Fa "void"
.Fc
.Sh DESCRIPTION
These functions define the interface to the lightweight resolver
daemon \fPNOT IF IT IS GOING AWAY\fP
for looking up hostnames and addresses. They are similar to the
standard
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
functions provided by as part of the standard system software.
functions provided by most operating systems.
They use a
.Dv "struct hostent"
which is usually defined in
.Pa namedb.h .
.Pa <namedb.h> .
.Bd -literal
struct hostent {
char *h_name; /* official name of host */
@@ -149,19 +148,17 @@ is the first address in
.Fn lwres_sethostent_r
and
.Fn lwres_endhostent_r
are empty stub functions which do nothing.
They are provided as placeholders so that calls to the system's
.Xr gethostent 3
functions can simply be #defined to their
.Xr lwres_res_gethost
equivalents.
See
.Pa lwres/netdb.h .
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
these functions; it only provides them as stub functions that always
return failure.
.Pp
.Fn lwres_gethostbyname
and
.Fn lwres_gethostbyname2
lookup the hostname
look up the hostname
.Fa name .
.Fn lwres_gethostbyname
always looks for an IPv4 address while
@@ -173,9 +170,6 @@ either
or
.Dv PF_INET6
- IPv4 or IPV6 addresses respectively.
Both functions call
.Fn lwres_getipnodebyname
to look up the hostname.
Successful calls of the functions return a
.Dv "struct hostent" for
the name that was looked up.
@@ -196,19 +190,9 @@ bytes and protocol family
.Dv PF_INET
or
.Dv PF_INET6 .
It calls
.Fn lwres_getipnodebyaddr
to do the reverse lookup.
.Pp
.Fn lwres_gethostbyname_r
is a thread-safe function for forward lookups.
It also calls
.Fn lwres_getipnodebyname
to lookup the hostname
.Fa name .
If
.Fn lwres_getipnodebyname
encounters an error, the error code is returned in
If an error occurs, an error code is returned in
.Fa *error .
.Fa resbuf
is a pointer to a
@@ -232,7 +216,7 @@ Successful calls to
return
.Fa resbuf ,
which is a pointer to the
.Fn "struct hostent"
.Dv "struct hostent"
it created.
.Pp
.Fn lwres_gethostbyaddr_r
@@ -246,13 +230,8 @@ and is of protocol family
.Dv PF_INET
or
.Dv PF_INET6 .
.Fn lwres_gethostbyaddr_r
calls
.Fn lwres_getipnodebyaddr
to do the work.
If this function encounters an error, the error code is returned in
If an error occurs, the error code is returned in
.Fa *error .
Like
The other function parameters are identical to those in
.Fn lwres_gethostbyname_r .
.Fa resbuf
@@ -287,36 +266,26 @@ The functions
.Fn lwres_gethostbyaddr ,
and
.Fn lwres_gethostent
are not thread-safe because they free any memory that had been allocated
in a previous call to those functions before they perform a lookup.
They also set the global variable
return NULL to indicate an error. In this case the global variable
.Dv lwres_h_errno
when they return.
The values of this variable are defined in
.Pa lwres/netdb.h .
The values and their meaning are defined as follows:
will contain one of the following error codes defined in
.Pa <lwres/netdb.h> :
.Bl -tag -width HOST_NOT_FOUND
.It Li NETDB_INTERNAL
Internal Error - see
.Li errno
.It Li NETDB_SUCCESS
no problem
.It Li HOST_NOT_FOUND
Authoritative Answer Host not found
The host or address was not found.
.It Li TRY_AGAIN
Non-Authoritive Answer Host not found, or
.Dv SERVERFAIL
A recoverable error occurred, e.g., a timeout.
Retrying the lookup may succeed.
.It Li NO_RECOVERY
Non recoverable errors,
.Dv FORMERR ,
.Dv REFUSED ,
or
.Dv NOTIMP
A non-recoverable error occurred.
.It Li NO_DATA
Valid name, but no data record of requested type
.It Li NO_ADDRESS
no address, so look for MX record
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.
.El
.Pp
.Xr lwres_hstrerror 3
translates these error codes to suitable error messages.
.Pp
@@ -355,7 +324,7 @@ was too small, both
and
.Fn lwres_gethostbyaddr_r
set the global variable
.DV errno
.Dv errno
to
.Er ERANGE .
.Sh SEE ALSO
@@ -363,26 +332,13 @@ to
.Xr lwres_getipnode 3 ,
.Xr lwres_hstrerror 3
.Sh BUGS
Although
.Fn lwres_gethostbyname ,
.Fn lwres_gethostbyname2 ,
.Fn lwres_gethostbyaddr
and
.Fn lwres_endhostent
call thread-safe functions to perform lookups, these 3 functions
are not thread-safe because they set the global variable
.Dv lwres_h_errno
which could
overwritten if two or more threads called these functions
simultaneously.
They also release any memory that had been allocated in a previous call
to these functions.
This emulates the semantics of their equivalent functions in the
system's
.Xr gethostent 3
functions which use a static buffer that gets overwritten in subsequent
calls to those routines.
.Pp
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 ,
and
doc/man/lwres/lwres_getipnode.3
+51 -94
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:24 tale Exp $
.\" $Id: lwres_getipnode.3,v 1.4 2000/09/28 22:36:29 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GETIPNODE 3
@@ -23,9 +23,9 @@
.Nm lwres_getipnodebyname ,
.Nm lwres_getipnodebyaddr ,
.Nm lwres_freehostent
.Nd lookup functions for the lightweight resolver
.Nd lightweight resolver nodename / address translation API
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd #include <lwres/netdb.h>
.Fd
.Ft struct hostent *
.Fo lwres_getipnodebyname
@@ -46,10 +46,14 @@
.Fa "struct hostent *he"
.Fc
.Sh DESCRIPTION
These functions use a
These functions perform thread safe, protocol independent
nodename-to-address and address-to-nodename
translation as defined in RFC2553.
.Pp
They use a
.Dv "struct hostent"
which is usually defined in
.Pa namedb.h .
which is defined in
.Pa namedb.h :
.Bd -literal
struct hostent {
char *h_name; /* official name of host */
@@ -68,7 +72,7 @@ The official (canonical) name of the host.
.It Li h_aliases
A NULL-terminated array of alternate names (nicknames) for the host.
.It Li h_addrtype
The type of address being returned -
The type of address being returned - usually
.Dv PF_INET
or
.Dv PF_INET6 .
@@ -81,92 +85,53 @@ terminated array of network addresses for the host.
Host addresses are returned in network byte order.
.El
.Pp
For backward compatibility with very old software,
.Li h_addr
is the first address in
.Li h_addr_list.
.Pp
.Fn lwres_getipnodebyname
looks up the hostname
.Fa name
of protocol family
.Fa af .
looks up addresses of protocol family
.Fa af
for the hostname
.Fa name .
The
.Fa flags
parameter sets bits that indicate how IPv6 and IPv4 addresses
should presented.
The value of those flags are:
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
return an IPv4 address mapped to an IPv6 address
This is used with an
.Fa af
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
IPv6 addresses.
.It Li AI_ALL
return all possible addresses
This is used with an
.Fa af
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
only return an IPv6 or IPv4 address if here is an active network
interface of that type.
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.
.It Li AI_DEFAULT
this default sets the
This default sets the
.Li AI_V4MAPPED
and
.Li AI_ADDRCONFIG
flag bits.
.El
.Pp
The value of
.Dv AF_INET6
is sometimes added to
.Fa flags .
When
.Fa flags
is set to
.Li "AI_V4MAPPED + AF_INET6"
.Fn lwres_getipnodebyname
will look for an IPv6 address and if this is not found it will look
for an IPv4 address and map it to an IPv6 address.
When
.Fa flags
is
.Li "AI_ALL + AI_V4MAPPED + AF_INET6" ,
.Fn lwres_getipnodebyname
returns mapped IPv4 addresses and IPv6 addresses.
.Fn lwres_getipnodebyname
calls
.Fn lwres_context_create
to create a resolver context for the lookup and
then calls
.Fn lwres_getaddrsbyname
to lookup the name using that resolver context.
.Pp
.Fn lwres_getipnodebyaddr
performs a thread-safe reverse lookup
performs a reverse lookup
of address
.Fa src
which is
.Fa len
bytes long.
.Fa af
denotes the protocol family:
denotes the protocol family, typically
.Dv PF_INET
or
.Dv PF_INET6 .
.Fn lwres_getipnodebyaddr
also sets up a resolver context by calling
.Fn lwres_context_create.
It then calls
.Fn lwres_getnamebyaddr
to make the query.
.Pp
Both
.Fn lwres_getipnodebyname
and
.Fn lwres_getipnodebyaddr
will free any memory that was allocated during intermediate stages of the
lookup by calling
.Fn lwres_gnbaresponse_free .
Both functions call
.Fn lwres_getipnodebyaddr
immediately before they return so that the created resolver context
gets discarded.
.Pp
.Fn lwres_freehostent
releases all the memory associated with
@@ -193,37 +158,29 @@ to an approriate error code and the function returns a
.Dv NULL
pointer.
The error codes and their meanings are defined in
.Pa lwres/netdb.h .
.Pa <lwres/netdb.h> :
.Bl -tag -width HOST_NOT_FOUND
.It Li NETDB_INTERNAL
Internal Error - see
.Li errno
.It Li NETDB_SUCCESS
no problem
.It Li HOST_NOT_FOUND
Authoritative Answer Host not found
.It Li TRY_AGAIN
Non-Authoritive Answer Host not found, or
.Dv SERVERFAIL
.It Li NO_RECOVERY
Non recoverable errors,
.Dv FORMERR ,
.Dv REFUSED ,
or
.Dv NOTIMP
.It Li NO_DATA
Valid name, but no data record of requested type
No such host is known.
.It Li NO_ADDRESS
no address, so look for MX record
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.
.It Li TRY_AGAIN
A temporary and possibly transient error occurred, such as a
failure of a server to respond. The request may succeed if
retried.
.It Li NO_RECOVERY
An unexpected failure occurred, and retrying the request
is pointless.
.El
.Pp
.Xr lwres_hstrerror 3
translates these error codes to suitable error messages.
.Sh SEE ALSO
.Xr lwres_res_getaddrsbyname 3 ,
.Xr lwres_res_context_create 3 ,
.Xr lwres_res_context_destroy 3 ,
.Xr lwres_res_gnbaresponse_free 3 ,
.Xr lwres_res_getaddrsbyaddr 3 ,
.Xr free 3 ,
.Xr RFC2553 ,
.Xr lwres 3 ,
.Xr lwres_gethostent 3 ,
.Xr lwres_getaddrinfo 3 ,
.Xr lwres_getnameinfo 3 ,
.Xr lwres_hstrerror 3 .
doc/man/lwres/lwres_getnameinfo.3
+24 -40
View File
@@ -13,7 +13,7 @@
.\" 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.4 2000/08/01 01:21:28 tale Exp $
.\" $Id: lwres_getnameinfo.3,v 1.5 2000/09/28 22:36:30 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GETNAMEINFO 3
@@ -23,7 +23,7 @@
.Nm lwres_getnameinfo
.Nd lightweight resolver socket address structure to hostname and service name
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd #include <lwres/netdb.h>
.Fd
.Ft int
.Fo lwres_getnameinfo
@@ -64,50 +64,33 @@ It is
bytes long.
The maximum length of the service name is
.Li NI_MAXSERV
- 32 - bytes.
- 32 bytes.
.Pp
The
.Fa flags
argument sets the following bits:
.Bl -tag -width NI_NUMERICSERV
.It Li NI_NOFQDN
a fully qualified domain name is not required for local hosts.
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
the address in the
.Dv sockaddr
structure is presented as a dotted-decimal string for an IPv4
address or an IPv6 hex address if the hostname is not found in the
DNS.
Return the address in numeric form, as if calling inet_ntop(),
instead of a host name.
.It Li NI_NAMEREQD
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.
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
service name is returned as a digit string representing the port number.
The service name is returned as a digit string representing the port number.
.It Li NI_DGRAM
the service uses a datagram transport protocol
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.
.El
.Pp
When a numeric host address string is needed,
.Fn lwres_getnameinfo
calls
.Fn lwres_net_ntop
to generate an IPv6 hex address or a dotted decimal IPv4 address.
If required,
.Fn lwres_getnameinfo
will create a resolver context by calling
.Fn lwres_context_create
and then using
.Fn lwres_getnamebyaddr
to perform the reverse lookup.
Any memory allocated during that reverse lookup will be
freed by calling
.Fn lwres_gnbaresponse_free .
.Fn lwres_context_destroy
is called immediately before
.Fn lwres_getnameinfo
returns so that the created resolver context gets discarded.
.Sh RETURN VALUES
.Fn lwres_getnameinfo
returns 0 on success or a non-zero error code if an error occurs.
@@ -135,12 +118,13 @@ returns 0 on success or a non-zero error code if an error occurs.
.\" is the wrong number of bytes for the address in
.\" Fa sa .
.Sh SEE ALSO
.Xr getnameinfo 3 ,
.Xr RFC2133 ,
.Xr getservbyport 3 ,
.Xr lwres_res_net_ntop 3 ,
.Xr lwres_res_context_create 3,
.Xr lwres_res_getnamebyaddr 3,
.Xr lwres_res_gnbaresponse_free 3 ,
.Xr lwres_res_context_destroy 3 ,
.Xr lwres_res_net_ntop 3 .
.Xr lwres 3 ,
.Xr lwres_getnameinfo 3 ,
.Xr lwres_getnamebyaddr 3,
.Xr lwres_net_ntop 3 .
.Sh BUGS
RFC2133 fails to define what the nonzero return values of
.Xr getnameinfo 3
are.
doc/man/lwres/lwres_gnba.3
+5 -6
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:29 tale Exp $
.\" $Id: lwres_gnba.3,v 1.4 2000/09/28 22:36:31 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GNBA 3
@@ -26,7 +26,7 @@
.Nm lwres_gnbaresponse_parse ,
.Nm lwres_gnbaresponse_free ,
.Nm lwres_gnbarequest_free
.Nd lightweight resolver getnamebyaddress functions
.Nd lightweight resolver getnamebyaddress message handling
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
@@ -69,10 +69,9 @@
.Fa "lwres_gnbarequest_t **structp"
.Fc
.Sh DESCRIPTION
These functions implement the lightweight resolver's getnamebyaddr opcode
.Dv LWRES_OPCODE_GETNAMEBYADDR .
They provide a reverse lookup mechanism, mapping an address to its
hostname.
These are low-level routines for creating and parsing
lightweight resolver address-to-name lookup request and
response messages.
.Pp
There are four main functions for the getnamebyaddr opcode.
One render function converts a getnamebyaddr request structure -
doc/man/lwres/lwres_noop.3
+7 -6
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:48 tale Exp $
.\" $Id: lwres_noop.3,v 1.4 2000/09/28 22:36:33 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_NOOP 3
@@ -26,7 +26,7 @@
.Nm lwres_noopresponse_parse ,
.Nm lwres_noopresponse_free ,
.Nm lwres_nooprequest_free
.Nd lightweight resolver no-op functions
.Nd lightweight resolver no-op message handling
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
@@ -69,10 +69,11 @@
.Fa "lwres_nooprequest_t **structp"
.Fc
.Sh DESCRIPTION
These functions implement the lightweight resolver's no-op opcode
.Dv LWRES_OPCODE_NOOP .
This is analogous to a \*qping\*q test: a packet is sent to the
lightweight resolver daemon and is simply echoed back.
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:
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
lib/lwres/man/lwres_buffer.3
+53 -82
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:20:26 tale Exp $
.\" $Id: lwres_buffer.3,v 1.4 2000/09/28 22:36:23 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_BUFFER 3
@@ -118,24 +118,13 @@
.Fa "unsigned int length"
.Fc
.Sh DESCRIPTION
These functions use the following structure as a buffer descriptor to
manage the actual storage:
.Bd -literal -offset indent
typedef struct lwres_buffer lwres_buffer_t;
struct lwres_buffer {
unsigned int magic;
unsigned char *base;
/* The following integers are byte offsets from 'base'. */
unsigned int length;
unsigned int used;
unsigned int current;
unsigned int active;
};
.Ed
The main reason for making the buffer structure public is so that
buffer operations can be implemented using macros.
Applications should not manipulate this structure directly.
They should use the functions listed below.
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_
functions in the ISC library.
.Pp
A buffer is a region of memory, together with a set of related
subregions.
@@ -168,33 +157,42 @@ Initially, the active region is empty.
If the current offset advances beyond the chosen offset,
the active region will also be empty.
.Pp
Except for
.Fn lwres_buffer_init ,
all of the buffer managements functions contain an assertion check
that
.Fa b
is a pointer to a valid lightweight resolver buffer.
.Bd -literal -offset indent
/------------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.
.Ed
.Pp
.Fn lwres_buffer_init
makes the
.Dv "struct lwres_buffer"
referenced by
initializes the
.Dv lwres_buffer_t
.Fa *b
to be associated with a memory region of size
and assocates it with the memory region of size
.Fa length
bytes starting at location
.Fa base.
The function checks that
.Fa *b is not
.Dv NULL .
.Pp
The
.Dv lwres_buffer_t
.Fa *b
is invalidated by
.Fn lwres_buffer_invalidate .
.Fa *b
must be a valid lightweight resolver buffer.
.Fn lwres_buffer_invalidate
marks the buffer
.Fa *b
as invalid. Invalidating a buffer after use is not required,
but makes it possible to catch its possible accidental use.
.Pp
The functions
.Fn lwres_buffer_add
@@ -206,70 +204,62 @@ buffer
by
.Fa n
bytes.
.Fa *b
.Fn lwres_buffer_add
checks for buffer overflow and
.Fn lwres_buffer_subtract
checks for underflow.
These functions do not allocate or deallocate memory.
They just change the value of
.Li b->used .
.Li used .
.Pp
A lightweight resolver buffer is re-initialised by
A buffer is re-initialised by
.Fn lwres_buffer_clear .
The function sets
.Li b->used ,
.Li b->current
.Li used ,
.Li current
and
.Li b->active
.Li active
to zero.
.Pp
.Fn lwres_buffer_first
makes the consumed region of buffer
.Fa *p
empty by setting
.Li b->current
to zero: the start of the buffer.
.Li current
to zero (the start of the buffer).
.Pp
The consumed region of buffer
.Fn lwres_buffer_forward
increases the consumed region of buffer
.Fa *b
is increased by
by
.Fa n
bytes
using
.Fn lwres_buffer_forward .
The function checks for buffer overflow.
bytes, checking for overflow.
Similarly,
.Fn lwres_buffer_back
decreases buffer
.Fa b 's
consumed region by
.Fa n
bytes and checks for buffer underflow.
bytes and checks for underflow.
.Pp
.Fn lwres_buffer_getuint8
reads an unsigned 8-bit integer from
.Fa *b
and returns it.
The function checks that it does not read past the end of the buffer's
consumed region.
.Fn lwres_buffer_putuint8
writes the unsigned 8-bit integer
.Fa val
to buffer
.Fa *b .
It checks that the buffer has available space for
.Fa val .
.Pp
.Fn lwres_buffer_getuint16
and
.Fn lwres_buffer_getuint32
are identical to
.Fn lwres_buffer_putuint8
except that they respectively read an unsigned 16-bit or 32-bit integer from
.Fa b
converting it from network byte order to host byte order before
returning its value.
except that they respectively read an unsigned 16-bit or 32-bit integer
in network byte order from
.Fa b .
Similarly,
.Fn lwres_buffer_putuint16
and
@@ -278,7 +268,7 @@ writes the unsigned 16-bit or 32-bit integer
.Fa val
to buffer
.Fa b ,
converting it from host byte order to network byte order.
in network byte order.
.Pp
Arbitrary amounts of data are read or written from a lightweight
resolver buffer with
@@ -301,23 +291,4 @@ bytes of memory from
.Fa b
to
.Fa base .
For both functions,
.Fa base
should point to at least
.Fa length
bytes of valid memory.
.Fa base
.Sh RETURN VALUES
.Fn lwres_buffer_getuint8 ,
.Fn lwres_buffer_getuint16
and
.Fn lwres_buffer_getuint32
return an 8-, 16- or 32-bit unsigned integer respectively from the
current offset in buffer
.Fa b .
The 16- and 32-bit quantities are presented in host byte order even
though they are stored in network byte order inside the buffer.
.Sh SEE ALSO
.Sh BUGS
Buffers have no synchronization.
Clients must ensure exclusive access for thread-safe operations.
lib/lwres/man/lwres_context.3
+67 -111
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:20:52 tale Exp $
.\" $Id: lwres_context.3,v 1.4 2000/09/28 22:36:24 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_CONTEXT 3
@@ -27,7 +27,7 @@
.Nm lwres_context_freemem ,
.Nm lwres_context_allocmem ,
.Nm lwres_context_sendrecv
.Nd lightweight resolver memory allocation routines
.Nd lightweight resolver context management
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
@@ -43,14 +43,14 @@
.Fa "lwres_context_t **contextp"
.Fc
.Ft void
.Fo lwres_context_nextserial
.Fa "lwres_context_t *ctx"
.Fc
.Ft lwres_uint32_t
.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"
@@ -71,95 +71,81 @@
.Fa "int recvlen"
.Fa "int *recvd_len"
.Fc
.Bd -literal -offset indent
struct lwres_context {
unsigned int timeout; /* time to wait for reply */
lwres_uint32_t serial; /* serial number state */
/*
* For network I/O.
*/
int sock; /* socket to send on */
/*
* Function pointers for allocating memory.
*/
lwres_malloc_t malloc;
lwres_free_t free;
void *arg;
/*
* resolv.conf-like data
*/
lwres_conf_t confdata;
};
typedef struct lwres_context lwres_context_t;
.Ed
.Sh DESCRIPTION
.Fn lwres_context_create
is used to create a
creates a
.Dv lwres_context_t
structure for use in lightweight resolver operations and associate
general purpose memory allocation functions with that structure.
.Fa *contextp
is a pointer to a
.Dv "struct lwres_context" .
It must be non-NULL, which in turn implies that
.Fa **contextp
is also non-NULL.
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
is returned throught
.Fa contextp ,
a pointer to a
.Dv "lwres_context_t"
pointer. This
.Dv "lwres_context_t"
pointer must initially be NULL, and is modified
to point to the newly created
.Dv "lwres_context_t" .
.Pp
When the lightweight resolver needs to perform dynamic memory
allocation, it will call
.Fa malloc_function
to allocate memory and
.Fa free_function
to free it. If
.Fa malloc_function
and
.Fa free_function
are pointers to the functions the context should use for allocating
and freeing memory respectively.
Both function pointers must either be non-NULL or NULL.
It is not permitted to use a custom allocator - i.e
.Fa malloc_function
is non-NULL -
with a NULL
.Fa free_function
or vice versa.
If both function pointers are NULL, the lightweight resolver's
internal allocation routines which call
.Fa free_function
are NULL, memory is allocated using
.Xr malloc 3
and
.Xr free 3
are used.
.Xr free 3 .
It is not permitted to have a NULL
.Fa malloc_function
and a non-NULL
.Fa free_function
or vice versa.
.Fa arg
is passed as the initial parameter to the memory
allocation functions.
The argument is passed but not used in the internal allocation
and deallocation routines.
is passed as the first parameter to the memory
allocation functions.
If
.Fa malloc_function
and
.Fa free_function
are NULL,
.Fa arg
is unused and should be passed as NULL.
.P
Once memory for the structure has been allocated,
.Xr lwres_conf_init 3
is called to initialise it.
The structure is then returned via
it is initialized using
.Xr lwres_conf_init 3
and returned via
.Fa *contextp .
.Pp
A
.Dv "struct lwres_context"
is destroyed by
.Fn lwres_context_destroy.
.Fa **contextp
.Fn lwres_context_destroy
destroys a
.Dv "lwres_context_t" ,
closing its socket.
.Fa contextp
is a pointer to a pointer to the context that is to be destroyed.
It must be non-NULL, as should
.Fa *contextp .
If the context has an open socket, it is closed before the structure
is discarded.
The pointer will be set to NULL when the context has been destroyed.
.Pp
The context's serial number is controlled with
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
and
.Fn lwres_context_nextserial .
Both require that
.Fa ctx
is not NULL.
.Fn lwres_context_initserial
sets the serial number for context
.Fa *ctx
to
.Fa serial .
.Fn lwres_context_nextserial
returns the current serial number for the context and increments
.Dv ctx->serial .
increments the serial number and returns the previous value.
.Pp
Memory for a lightweight resolver context is allocated and freed using
.Fn lwres_context_allocmem
@@ -182,38 +168,16 @@ frees
.Fa len
bytes of space starting at location
.Fa mem .
It has assertion checks to ensure that
.Fa mem
is not null and
.Fa len
is not zero.
.Pp
If the lightweight resolver's memory allocation functions are used,
.Fa len
bytes in the allocated buffer will be set to '0xe5' on allocation
or '0xa9' when they are freed.
.Pp
.Fn lwres_context_sendrecv
performs I/O for the context
.Fa ctx .
Data are read and written from the context's socket
.Dv ctx->sock .
Data are read and written from the context's socket.
It writes data from
.Fa sendbase
- typically a DNS query -
- typically a lightweight resolver query packet -
and waits for a reply which is copied to the receive buffer at
.Fa recvbase .
.Fa sendbase
is a pointer to the
.Fa sendlen
bytes of data that are to be sent using
.Xr sendto 2.
Up to
.Fn recvlen
bytes of data that are returned by a call to
.Xr recvfrom 2
on the socket are copied to
.Fa recvbase .
The number of bytes that were written to this receive buffer is
returned in
.Fa *recvd_len .
@@ -223,9 +187,9 @@ returns
.Er LWRES_R_NOMEMORY
if memory for the
.Dv "struct lwres_context"
could not be allocated, otherwise
could not be allocated,
.Er LWRES_R_SUCCESS
is returned.
otherwise.
.Pp
Successful calls to the memory allocator
.Fn lwres_context_allocmem
@@ -239,18 +203,10 @@ completes successfully.
.Er LWRES_R_IOERROR
is returned if an I/O error occurs and
.Er LWRES_R_TIMEOUT
is returned if the
.Xr recvfrom 2
call times out.
is returned if
.Fn lwres_context_sendrecv
times out waiting for a response.
.Sh SEE ALSO
.Xr lwres_conf_init 3 ,
.Xr malloc 3 ,
.Xr free 3 ,
.Xr close 2 ,
.Xr memset 3 ,
.Xr sendto 2 ,
.Xr recvfrom 2 .
.Sh BUGS
The
.Dv lwres_context_t
structures and the functions which operate on them are not thread-safe.
.Xr free 3
lib/lwres/man/lwres_gabn.3
+7 -8
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:05 tale Exp $
.\" $Id: lwres_gabn.3,v 1.4 2000/09/28 22:36:25 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GABN 3
@@ -26,7 +26,7 @@
.Nm lwres_gabnresponse_parse ,
.Nm lwres_gabnresponse_free ,
.Nm lwres_gabnrequest_free
.Nd lightweight resolver getaddrbyname functions
.Nd lightweight resolver getaddrbyname message handling
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
@@ -69,11 +69,10 @@
.Fa "lwres_gabnrequest_t **structp"
.Fc
.Sh DESCRIPTION
These functions implement the lightweight resolver's getaddrbyname opcode
.Dv LWRES_OPCODE_GETADDRSBYNAME .
They provide a forward lookup mechanism, mapping a hostname to its
address or addresses.
.Pp
These are low-level routines for creating and parsing
lightweight resolver name-to-address lookup request and
response messages.
.P
There are four main functions for the getaddrbyname opcode.
One render function converts a getaddrbyname request structure -
.Dv lwres_gabnrequest_t -
@@ -87,7 +86,7 @@ This is complemented by a parse function which converts a packet in
canonical format to a getaddrbyname response structure.
.Pp
These structures are defined in
.Pa lwres/lwres.h .
.Pa <lwres/lwres.h> .
They are shown below.
.Bd -literal -offset indent
#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U
lib/lwres/man/lwres_gai_strerror.3
+10 -12
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:12 tale Exp $
.\" $Id: lwres_gai_strerror.3,v 1.4 2000/09/28 22:36:26 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GAI_STRERROR 3
@@ -30,16 +30,11 @@
.Fa "int ecode"
.Fc
.Sh DESCRIPTION
.Fn gai_strerror
returns a suitable error message for the error code
.Fa ecode .
The message \*qinvalid error code\*q is returned if
.Fa ecode
is out of range.
.Fn lwres_gai_strerror
returns an error message corresponding to an error code returned by
.Fn getaddrinfo .
The following error codes and their meaning are defined in
.Aq Pa include/lwres/netdb.h .
They can be returned by
.Fn getaddrinfo .
.Bl -tag -width EAI_ADDRFAMILY -offset indent -compact
.It Dv EAI_ADDRFAMILY
address family for hostname not supported
@@ -68,17 +63,20 @@ not supported
.It Dv EAI_SYSTEM
system error returned in errno
.El
The message \*qinvalid error code\*q is returned if
.Fa ecode
is out of range.
.Pp
.Li ai_flags ,
.Li ai_family
and
.Li ai_socktype
are elements of the
.Dv "struct addrinfo" used by
.Dv "struct addrinfo"
used by
.Fn lwres_getaddrinfo .
.Sh SEE ALSO
.Xr errno 2 ,
.Xr perror 3 ,
.Xr strerror 3 ,
.Xr lwres_getaddrinfo 3 ,
.Xr getaddrinfo 3 ,
.Xr RFC2133 .
lib/lwres/man/lwres_getaddrinfo.3
+23 -25
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:13 tale Exp $
.\" $Id: lwres_getaddrinfo.3,v 1.4 2000/09/28 22:36:27 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GETADDRINFO 3
@@ -40,7 +40,8 @@
.Pp
If the operating system does not provide a
.Dv "struct addrinfo" ,
the following structure is used
the following structure is used:
.Pp
.Bd -literal -offset indent
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
@@ -58,7 +59,7 @@ struct addrinfo {
.Fn lwres_getaddrinfo
is used to get a list of IP addresses and port numbers for host
.Fa hostname
and
and service
.Fa servname .
The function is the lightweight resolver's implementation of
.Fn getaddrinfo
@@ -66,12 +67,12 @@ as defined in RFC2133.
.Fa hostname
and
.Fa servname
arguments are pointers to null-terminated
are pointers to null-terminated
strings or
.Dv NULL .
.Fa hostname
either a host name or a numeric host address string: a dotted decimal
IPv4 address or an IPv6 hex address.
is either a host name or a numeric host address string: a dotted decimal
IPv4 address or an IPv6 address.
.Fa servname
is either a decimal port number or a service name as listed in
.Pa /etc/services .
@@ -103,12 +104,13 @@ When
.Li ai_socktype
is zero the caller will accept any socket type.
.It Li ai_protocol
indicates which transport protocol is wanted: UDP or TCP.
indicates which transport protocol is wanted: IPPROTO_UDP or
IPPROTO_TCP.
If
.Li ai_protocol
is zero the caller will accept any protocol.
.It Li ai_flags
sets some flag bits.
Flag bits.
If the
.Dv AI_CANONNAME
bit is set, a successful call to
@@ -161,14 +163,9 @@ If
is set to
.Dv AI_NUMERICHOST
it indicates that
the
.Dv non-NuLL
.Fa hostname
should be treated as a numeric string defining an IPv4 or IPv6 address.
This will prevent a numeric IPv4 address from being considered as a domain
name when
.Fn lwres_getaddrinfo
is looking for IPv6 addresses or vice versa.
should be treated as a numeric string defining an IPv4 or IPv6 address
and no name resolution should be attempted.
.El
.Pp
All other elements of the
@@ -177,14 +174,13 @@ passed via
.Fa arg
must be zero.
.Pp
If
An
.Fa arg
is not supplied, a
of
.Dv NULL
pointer should be given for this argument.
It will be treated as if the caller provided an
is treated as if the caller provided a
.Dv "struct addrinfo"
structure initialized to zero with
initialized to zero with
.Li ai_family set to
.Li PF_UNSPEC .
.Pp
@@ -195,7 +191,8 @@ is a pointer to a linked list of one or more
.Dv addrinfo
structures.
Each
.Dv "struct addrinfo" in this list cn be processed by following
.Dv "struct addrinfo"
in this list cn be processed by following
the
.Li ai_next
pointer, until a
@@ -203,7 +200,7 @@ pointer, until a
pointer is encountered.
The three members
.Li ai_family ,
ai_socktype,
.Li ai_socktype ,
and
.Li ai_protocol
in each
@@ -230,7 +227,8 @@ is released by
.Fn lwres_freeaddrinfo .
.Fa ai
is a pointer to a
.Dv "struct addrinfo" created by a call to
.Dv "struct addrinfo"
created by a call to
.Fn lwres_getaddrinfo .
.Sh RETURN VALUES
.Fn lwres_getaddrinfo
@@ -247,13 +245,13 @@ are
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 bind 2 ,
.Xr connect 2 ,
.Xr sendto 2 ,
.Xr sendmsg 2 ,
lib/lwres/man/lwres_gethostent.3
+32 -76
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:21 tale Exp $
.\" $Id: lwres_gethostent.3,v 1.4 2000/09/28 22:36:28 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GETHOSTENT 3
@@ -96,16 +96,15 @@
.Fa "void"
.Fc
.Sh DESCRIPTION
These functions define the interface to the lightweight resolver
daemon \fPNOT IF IT IS GOING AWAY\fP
for looking up hostnames and addresses. They are similar to the
standard
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
functions provided by as part of the standard system software.
functions provided by most operating systems.
They use a
.Dv "struct hostent"
which is usually defined in
.Pa namedb.h .
.Pa <namedb.h> .
.Bd -literal
struct hostent {
char *h_name; /* official name of host */
@@ -149,19 +148,17 @@ is the first address in
.Fn lwres_sethostent_r
and
.Fn lwres_endhostent_r
are empty stub functions which do nothing.
They are provided as placeholders so that calls to the system's
.Xr gethostent 3
functions can simply be #defined to their
.Xr lwres_res_gethost
equivalents.
See
.Pa lwres/netdb.h .
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
these functions; it only provides them as stub functions that always
return failure.
.Pp
.Fn lwres_gethostbyname
and
.Fn lwres_gethostbyname2
lookup the hostname
look up the hostname
.Fa name .
.Fn lwres_gethostbyname
always looks for an IPv4 address while
@@ -173,9 +170,6 @@ either
or
.Dv PF_INET6
- IPv4 or IPV6 addresses respectively.
Both functions call
.Fn lwres_getipnodebyname
to look up the hostname.
Successful calls of the functions return a
.Dv "struct hostent" for
the name that was looked up.
@@ -196,19 +190,9 @@ bytes and protocol family
.Dv PF_INET
or
.Dv PF_INET6 .
It calls
.Fn lwres_getipnodebyaddr
to do the reverse lookup.
.Pp
.Fn lwres_gethostbyname_r
is a thread-safe function for forward lookups.
It also calls
.Fn lwres_getipnodebyname
to lookup the hostname
.Fa name .
If
.Fn lwres_getipnodebyname
encounters an error, the error code is returned in
If an error occurs, an error code is returned in
.Fa *error .
.Fa resbuf
is a pointer to a
@@ -232,7 +216,7 @@ Successful calls to
return
.Fa resbuf ,
which is a pointer to the
.Fn "struct hostent"
.Dv "struct hostent"
it created.
.Pp
.Fn lwres_gethostbyaddr_r
@@ -246,13 +230,8 @@ and is of protocol family
.Dv PF_INET
or
.Dv PF_INET6 .
.Fn lwres_gethostbyaddr_r
calls
.Fn lwres_getipnodebyaddr
to do the work.
If this function encounters an error, the error code is returned in
If an error occurs, the error code is returned in
.Fa *error .
Like
The other function parameters are identical to those in
.Fn lwres_gethostbyname_r .
.Fa resbuf
@@ -287,36 +266,26 @@ The functions
.Fn lwres_gethostbyaddr ,
and
.Fn lwres_gethostent
are not thread-safe because they free any memory that had been allocated
in a previous call to those functions before they perform a lookup.
They also set the global variable
return NULL to indicate an error. In this case the global variable
.Dv lwres_h_errno
when they return.
The values of this variable are defined in
.Pa lwres/netdb.h .
The values and their meaning are defined as follows:
will contain one of the following error codes defined in
.Pa <lwres/netdb.h> :
.Bl -tag -width HOST_NOT_FOUND
.It Li NETDB_INTERNAL
Internal Error - see
.Li errno
.It Li NETDB_SUCCESS
no problem
.It Li HOST_NOT_FOUND
Authoritative Answer Host not found
The host or address was not found.
.It Li TRY_AGAIN
Non-Authoritive Answer Host not found, or
.Dv SERVERFAIL
A recoverable error occurred, e.g., a timeout.
Retrying the lookup may succeed.
.It Li NO_RECOVERY
Non recoverable errors,
.Dv FORMERR ,
.Dv REFUSED ,
or
.Dv NOTIMP
A non-recoverable error occurred.
.It Li NO_DATA
Valid name, but no data record of requested type
.It Li NO_ADDRESS
no address, so look for MX record
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.
.El
.Pp
.Xr lwres_hstrerror 3
translates these error codes to suitable error messages.
.Pp
@@ -355,7 +324,7 @@ was too small, both
and
.Fn lwres_gethostbyaddr_r
set the global variable
.DV errno
.Dv errno
to
.Er ERANGE .
.Sh SEE ALSO
@@ -363,26 +332,13 @@ to
.Xr lwres_getipnode 3 ,
.Xr lwres_hstrerror 3
.Sh BUGS
Although
.Fn lwres_gethostbyname ,
.Fn lwres_gethostbyname2 ,
.Fn lwres_gethostbyaddr
and
.Fn lwres_endhostent
call thread-safe functions to perform lookups, these 3 functions
are not thread-safe because they set the global variable
.Dv lwres_h_errno
which could
overwritten if two or more threads called these functions
simultaneously.
They also release any memory that had been allocated in a previous call
to these functions.
This emulates the semantics of their equivalent functions in the
system's
.Xr gethostent 3
functions which use a static buffer that gets overwritten in subsequent
calls to those routines.
.Pp
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 ,
and
lib/lwres/man/lwres_getipnode.3
+51 -94
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:24 tale Exp $
.\" $Id: lwres_getipnode.3,v 1.4 2000/09/28 22:36:29 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GETIPNODE 3
@@ -23,9 +23,9 @@
.Nm lwres_getipnodebyname ,
.Nm lwres_getipnodebyaddr ,
.Nm lwres_freehostent
.Nd lookup functions for the lightweight resolver
.Nd lightweight resolver nodename / address translation API
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd #include <lwres/netdb.h>
.Fd
.Ft struct hostent *
.Fo lwres_getipnodebyname
@@ -46,10 +46,14 @@
.Fa "struct hostent *he"
.Fc
.Sh DESCRIPTION
These functions use a
These functions perform thread safe, protocol independent
nodename-to-address and address-to-nodename
translation as defined in RFC2553.
.Pp
They use a
.Dv "struct hostent"
which is usually defined in
.Pa namedb.h .
which is defined in
.Pa namedb.h :
.Bd -literal
struct hostent {
char *h_name; /* official name of host */
@@ -68,7 +72,7 @@ The official (canonical) name of the host.
.It Li h_aliases
A NULL-terminated array of alternate names (nicknames) for the host.
.It Li h_addrtype
The type of address being returned -
The type of address being returned - usually
.Dv PF_INET
or
.Dv PF_INET6 .
@@ -81,92 +85,53 @@ terminated array of network addresses for the host.
Host addresses are returned in network byte order.
.El
.Pp
For backward compatibility with very old software,
.Li h_addr
is the first address in
.Li h_addr_list.
.Pp
.Fn lwres_getipnodebyname
looks up the hostname
.Fa name
of protocol family
.Fa af .
looks up addresses of protocol family
.Fa af
for the hostname
.Fa name .
The
.Fa flags
parameter sets bits that indicate how IPv6 and IPv4 addresses
should presented.
The value of those flags are:
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
return an IPv4 address mapped to an IPv6 address
This is used with an
.Fa af
of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped
IPv6 addresses.
.It Li AI_ALL
return all possible addresses
This is used with an
.Fa af
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
only return an IPv6 or IPv4 address if here is an active network
interface of that type.
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.
.It Li AI_DEFAULT
this default sets the
This default sets the
.Li AI_V4MAPPED
and
.Li AI_ADDRCONFIG
flag bits.
.El
.Pp
The value of
.Dv AF_INET6
is sometimes added to
.Fa flags .
When
.Fa flags
is set to
.Li "AI_V4MAPPED + AF_INET6"
.Fn lwres_getipnodebyname
will look for an IPv6 address and if this is not found it will look
for an IPv4 address and map it to an IPv6 address.
When
.Fa flags
is
.Li "AI_ALL + AI_V4MAPPED + AF_INET6" ,
.Fn lwres_getipnodebyname
returns mapped IPv4 addresses and IPv6 addresses.
.Fn lwres_getipnodebyname
calls
.Fn lwres_context_create
to create a resolver context for the lookup and
then calls
.Fn lwres_getaddrsbyname
to lookup the name using that resolver context.
.Pp
.Fn lwres_getipnodebyaddr
performs a thread-safe reverse lookup
performs a reverse lookup
of address
.Fa src
which is
.Fa len
bytes long.
.Fa af
denotes the protocol family:
denotes the protocol family, typically
.Dv PF_INET
or
.Dv PF_INET6 .
.Fn lwres_getipnodebyaddr
also sets up a resolver context by calling
.Fn lwres_context_create.
It then calls
.Fn lwres_getnamebyaddr
to make the query.
.Pp
Both
.Fn lwres_getipnodebyname
and
.Fn lwres_getipnodebyaddr
will free any memory that was allocated during intermediate stages of the
lookup by calling
.Fn lwres_gnbaresponse_free .
Both functions call
.Fn lwres_getipnodebyaddr
immediately before they return so that the created resolver context
gets discarded.
.Pp
.Fn lwres_freehostent
releases all the memory associated with
@@ -193,37 +158,29 @@ to an approriate error code and the function returns a
.Dv NULL
pointer.
The error codes and their meanings are defined in
.Pa lwres/netdb.h .
.Pa <lwres/netdb.h> :
.Bl -tag -width HOST_NOT_FOUND
.It Li NETDB_INTERNAL
Internal Error - see
.Li errno
.It Li NETDB_SUCCESS
no problem
.It Li HOST_NOT_FOUND
Authoritative Answer Host not found
.It Li TRY_AGAIN
Non-Authoritive Answer Host not found, or
.Dv SERVERFAIL
.It Li NO_RECOVERY
Non recoverable errors,
.Dv FORMERR ,
.Dv REFUSED ,
or
.Dv NOTIMP
.It Li NO_DATA
Valid name, but no data record of requested type
No such host is known.
.It Li NO_ADDRESS
no address, so look for MX record
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.
.It Li TRY_AGAIN
A temporary and possibly transient error occurred, such as a
failure of a server to respond. The request may succeed if
retried.
.It Li NO_RECOVERY
An unexpected failure occurred, and retrying the request
is pointless.
.El
.Pp
.Xr lwres_hstrerror 3
translates these error codes to suitable error messages.
.Sh SEE ALSO
.Xr lwres_res_getaddrsbyname 3 ,
.Xr lwres_res_context_create 3 ,
.Xr lwres_res_context_destroy 3 ,
.Xr lwres_res_gnbaresponse_free 3 ,
.Xr lwres_res_getaddrsbyaddr 3 ,
.Xr free 3 ,
.Xr RFC2553 ,
.Xr lwres 3 ,
.Xr lwres_gethostent 3 ,
.Xr lwres_getaddrinfo 3 ,
.Xr lwres_getnameinfo 3 ,
.Xr lwres_hstrerror 3 .
lib/lwres/man/lwres_getnameinfo.3
+24 -40
View File
@@ -13,7 +13,7 @@
.\" 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.4 2000/08/01 01:21:28 tale Exp $
.\" $Id: lwres_getnameinfo.3,v 1.5 2000/09/28 22:36:30 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GETNAMEINFO 3
@@ -23,7 +23,7 @@
.Nm lwres_getnameinfo
.Nd lightweight resolver socket address structure to hostname and service name
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd #include <lwres/netdb.h>
.Fd
.Ft int
.Fo lwres_getnameinfo
@@ -64,50 +64,33 @@ It is
bytes long.
The maximum length of the service name is
.Li NI_MAXSERV
- 32 - bytes.
- 32 bytes.
.Pp
The
.Fa flags
argument sets the following bits:
.Bl -tag -width NI_NUMERICSERV
.It Li NI_NOFQDN
a fully qualified domain name is not required for local hosts.
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
the address in the
.Dv sockaddr
structure is presented as a dotted-decimal string for an IPv4
address or an IPv6 hex address if the hostname is not found in the
DNS.
Return the address in numeric form, as if calling inet_ntop(),
instead of a host name.
.It Li NI_NAMEREQD
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.
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
service name is returned as a digit string representing the port number.
The service name is returned as a digit string representing the port number.
.It Li NI_DGRAM
the service uses a datagram transport protocol
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.
.El
.Pp
When a numeric host address string is needed,
.Fn lwres_getnameinfo
calls
.Fn lwres_net_ntop
to generate an IPv6 hex address or a dotted decimal IPv4 address.
If required,
.Fn lwres_getnameinfo
will create a resolver context by calling
.Fn lwres_context_create
and then using
.Fn lwres_getnamebyaddr
to perform the reverse lookup.
Any memory allocated during that reverse lookup will be
freed by calling
.Fn lwres_gnbaresponse_free .
.Fn lwres_context_destroy
is called immediately before
.Fn lwres_getnameinfo
returns so that the created resolver context gets discarded.
.Sh RETURN VALUES
.Fn lwres_getnameinfo
returns 0 on success or a non-zero error code if an error occurs.
@@ -135,12 +118,13 @@ returns 0 on success or a non-zero error code if an error occurs.
.\" is the wrong number of bytes for the address in
.\" Fa sa .
.Sh SEE ALSO
.Xr getnameinfo 3 ,
.Xr RFC2133 ,
.Xr getservbyport 3 ,
.Xr lwres_res_net_ntop 3 ,
.Xr lwres_res_context_create 3,
.Xr lwres_res_getnamebyaddr 3,
.Xr lwres_res_gnbaresponse_free 3 ,
.Xr lwres_res_context_destroy 3 ,
.Xr lwres_res_net_ntop 3 .
.Xr lwres 3 ,
.Xr lwres_getnameinfo 3 ,
.Xr lwres_getnamebyaddr 3,
.Xr lwres_net_ntop 3 .
.Sh BUGS
RFC2133 fails to define what the nonzero return values of
.Xr getnameinfo 3
are.
lib/lwres/man/lwres_gnba.3
+5 -6
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:29 tale Exp $
.\" $Id: lwres_gnba.3,v 1.4 2000/09/28 22:36:31 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_GNBA 3
@@ -26,7 +26,7 @@
.Nm lwres_gnbaresponse_parse ,
.Nm lwres_gnbaresponse_free ,
.Nm lwres_gnbarequest_free
.Nd lightweight resolver getnamebyaddress functions
.Nd lightweight resolver getnamebyaddress message handling
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
@@ -69,10 +69,9 @@
.Fa "lwres_gnbarequest_t **structp"
.Fc
.Sh DESCRIPTION
These functions implement the lightweight resolver's getnamebyaddr opcode
.Dv LWRES_OPCODE_GETNAMEBYADDR .
They provide a reverse lookup mechanism, mapping an address to its
hostname.
These are low-level routines for creating and parsing
lightweight resolver address-to-name lookup request and
response messages.
.Pp
There are four main functions for the getnamebyaddr opcode.
One render function converts a getnamebyaddr request structure -
lib/lwres/man/lwres_noop.3
+7 -6
View File
@@ -13,7 +13,7 @@
.\" 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.3 2000/08/01 01:21:48 tale Exp $
.\" $Id: lwres_noop.3,v 1.4 2000/09/28 22:36:33 gson Exp $
.\"
.Dd Jun 30, 2000
.Dt LWRES_NOOP 3
@@ -26,7 +26,7 @@
.Nm lwres_noopresponse_parse ,
.Nm lwres_noopresponse_free ,
.Nm lwres_nooprequest_free
.Nd lightweight resolver no-op functions
.Nd lightweight resolver no-op message handling
.Sh SYNOPSIS
.Fd #include <lwres/lwres.h>
.Fd
@@ -69,10 +69,11 @@
.Fa "lwres_nooprequest_t **structp"
.Fc
.Sh DESCRIPTION
These functions implement the lightweight resolver's no-op opcode
.Dv LWRES_OPCODE_NOOP .
This is analogous to a \*qping\*q test: a packet is sent to the
lightweight resolver daemon and is simply echoed back.
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:
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