From ac299c4f5ca236370b9df2a91b18b149b1d344a7 Mon Sep 17 00:00:00 2001 From: Andreas Gustafsson Date: Mon, 18 Jun 2001 22:56:35 +0000 Subject: [PATCH] Removed statements to the effect that certain functions perform assertion checks. Such statements are inappropriate as they document the implementation rather than the public interface. The functions are not required to perform assertion checks, but the caller is required to pass arguments that conform to the API requirements. --- lib/lwres/man/lwres_context.docbook | 6 +- lib/lwres/man/lwres_getaddrinfo.html | 5 +- lib/lwres/man/lwres_gethostent.3 | 179 ++++++------------ lib/lwres/man/lwres_gethostent.html | 261 +++++++++------------------ lib/lwres/man/lwres_getipnode.html | 1 - lib/lwres/man/lwres_getnameinfo.3 | 41 ++--- lib/lwres/man/lwres_getnameinfo.html | 60 +++--- lib/lwres/man/lwres_hstrerror.3 | 20 +- lib/lwres/man/lwres_hstrerror.html | 28 ++- lib/lwres/man/lwres_inetntop.3 | 46 ++--- lib/lwres/man/lwres_inetntop.html | 59 +++--- lib/lwres/man/lwres_noop.3 | 71 +++----- lib/lwres/man/lwres_noop.html | 89 ++++----- lib/lwres/man/lwres_packet.3 | 46 ++--- lib/lwres/man/lwres_packet.docbook | 8 +- lib/lwres/man/lwres_packet.html | 71 +++----- lib/lwres/man/lwres_resutil.3 | 128 +++++-------- lib/lwres/man/lwres_resutil.docbook | 21 +-- lib/lwres/man/lwres_resutil.html | 165 ++++++----------- 19 files changed, 435 insertions(+), 870 deletions(-) diff --git a/lib/lwres/man/lwres_context.docbook b/lib/lwres/man/lwres_context.docbook index bee9534c80..85ebd46eec 100644 --- a/lib/lwres/man/lwres_context.docbook +++ b/lib/lwres/man/lwres_context.docbook @@ -16,7 +16,7 @@ - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. --> - + @@ -207,10 +207,6 @@ allocates len bytes of memory and if successful returns a pointer to the allocated storage. -lwres_context_allocmem() -checks that -len -must be greater than 0. lwres_context_freemem() frees len diff --git a/lib/lwres/man/lwres_getaddrinfo.html b/lib/lwres/man/lwres_getaddrinfo.html index 66a6e75ea0..d04ecc1a2f 100644 --- a/lib/lwres/man/lwres_getaddrinfo.html +++ b/lib/lwres/man/lwres_getaddrinfo.html @@ -171,7 +171,7 @@ is either a decimal port number or a service name as listed in /etc/services.

.

struct addrinfo. - 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 @@ -420,7 +419,7 @@ and no name resolution should be attempted.

All other elements of the lwres_gethostbyname() -and +> and lwres_gethostbyname2() -look up the hostname +> look up the hostname name. - lwres_gethostbyname() -always looks for an IPv4 address while - always looks for an IPv4 +address while lwres_gethostbyname2() -looks for an address of protocol family - looks for an +address of protocol family af: - -either +>: either PF_INET -or - or PF_INET6 -— IPv4 or IPV6 addresses respectively. -Successful calls of the functions return a +> — IPv4 or IPV6 +addresses respectively. Successful calls of the functions return a struct hostentfor - -the name that was looked up. +>for the name that was looked up. NULL -is returned if the lookups by +> is returned if the lookups by lwres_gethostbyname() -or +> or lwres_gethostbyname2() -fail.

fail.

Reverse lookups of addresses are performed by addr -is an address of length +> is an address of length len -bytes and protocol family +> bytes and protocol family type — - — PF_INET -or +> or PF_INET6. - lwres_gethostbyname_r() -is a thread-safe function for forward lookups. -If an error occurs, an error code is returned in +> is a thread-safe function +for forward lookups. If an error occurs, an error code is returned in *error. - resbuf -is a pointer to a - is a pointer to a struct hostent -which is initialised by a successful call to +>struct +hostent which is initialised by a successful call to lwres_gethostbyname_r()buf -is a buffer of length +> is a buffer of length len -bytes which is used to store the +> bytes which is used to store the h_name, - -, h_aliases, - -and +>, and h_addr_list -elements of the - elements of the struct hostent -returned in -struct +hostent returned in resbuf. - -Successful calls to -lwres_gethostbyname_r() -return -resbuf, - -which is a pointer to the -struct hostent -it created.

it created.

lwres_gethostbyaddr_r() -is a thread-safe function that performs a reverse lookup of address - is a thread-safe function +that performs a reverse lookup of address addr -which is -len -bytes long -and is of protocol family - bytes long and is of protocol +family type — - - — PF_INET -or +> or PF_INET6. - -If an error occurs, the error code is returned in -. If an error occurs, the error code is returned +in *error. - -The other function parameters are identical to those in -. The other function parameters are +identical to those in lwres_gethostbyname_r(). @@ -557,13 +507,11 @@ CLASS="PARAMETER" >resbuf -is a pointer to a - is a pointer to a struct hostent -which is initialised by a successful call to +>struct +hostent which is initialised by a successful call to lwres_gethostbyaddr_r()buf -is a buffer of length +> is a buffer of length len -bytes which is used to store the +> bytes which is used to store the h_name, - -, h_aliases, - -and +>, and h_addr_list -elements of the - elements of the struct hostent -returned in -struct +hostent returned in resbuf. - -Successful calls to -. Successful +calls to lwres_gethostbyaddr_r() -return +> return resbuf, - -which is a pointer to the +>, which is a pointer to the struct hostent() -it created.

it created.

NULL.

.

Successful calls to -Successful calls to lwres_gethostbyname_r() -and +> and lwres_gethostbyaddr_r() -return +> return resbuf, - -a pointer to the -, a pointer to the struct hostent -that was initialised by these functions. -They return +>struct +hostent that was initialised by these functions. They return NULL -if the lookups fail -or if - if the lookups fail or if buf was too small to hold the list of addresses and names referenced by -the -h_name, - -, h_aliases, - -and +>, and h_addr_list -elements of the - elements of the struct hostent. - -If -struct +hostent. If buf -was too small, both +> was too small, both lwres_gethostbyname_r() -and +> and lwres_gethostbyaddr_r() -set the global variable +> set the global variable errno -to - to ERANGE.

.

namedb.h: - 
struct  hostent {
diff --git a/lib/lwres/man/lwres_getnameinfo.3 b/lib/lwres/man/lwres_getnameinfo.3
index f0446c9950..61f3ba426c 100644
--- a/lib/lwres/man/lwres_getnameinfo.3
+++ b/lib/lwres/man/lwres_getnameinfo.3
@@ -26,37 +26,21 @@ lwres_getnameinfo(const struct sockaddr *sa, size_t salen, char *host, size_t ho
 .ad
 \fR.SH "DESCRIPTION"
 .PP
-This function is equivalent to the
-\fBgetnameinfo\fR(3)
-function defined in RFC2133.
-\fBlwres_getnameinfo()\fR
-returns the hostname for the
-\fBstruct sockaddr\fR
-\fIsa\fR
-which is
-\fIsalen\fR
-bytes long.
-The hostname is of length
-\fIhostlen\fR
-and is returned via
-\fI*host.\fR
-The maximum length of the hostname is
-1025 bytes:
-NI_MAXHOST.
+This function is equivalent to the \fBgetnameinfo\fR(3) function defined in RFC2133.
+\fBlwres_getnameinfo()\fR returns the hostname for the
+\fBstruct sockaddr\fR \fIsa\fR which is
+\fIsalen\fR bytes long. The hostname is of length
+\fIhostlen\fR and is returned via
+\fI*host.\fR The maximum length of the hostname is
+1025 bytes: NI_MAXHOST.
 .PP
 The name of the service associated with the port number in
-\fIsa\fR
-is returned in
-\fI*serv.\fR
-It is
-\fIservlen\fR
-bytes long.
-The maximum length of the service name is
-NI_MAXSERV - 32 bytes.
+\fIsa\fR is returned in \fI*serv.\fR
+It is \fIservlen\fR bytes long. The maximum length
+of the service name is NI_MAXSERV - 32 bytes.
 .PP
-The
-\fIflags\fR
-argument sets the following bits:
+The \fIflags\fR argument sets the following
+bits:
 .TP
 \fBNI_NOFQDN\fR
 A fully qualified domain name is not required for local hosts.
@@ -81,7 +65,6 @@ 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.
-.PP
 .SH "RETURN VALUES"
 .PP
 \fBlwres_getnameinfo()\fR
diff --git a/lib/lwres/man/lwres_getnameinfo.html b/lib/lwres/man/lwres_getnameinfo.html
index 05e40b668b..b98a928483 100644
--- a/lib/lwres/man/lwres_getnameinfo.html
+++ b/lib/lwres/man/lwres_getnameinfo.html
@@ -79,95 +79,79 @@ NAME="AEN24"
 >
DESCRIPTION
This function is equivalent to the
- This function is equivalent to the getnameinfo(3)
-function defined in RFC2133.
+> function defined in RFC2133.
 lwres_getnameinfo()
-returns the hostname for the
+> returns the hostname for the
 struct sockaddr
- sa
-which is
+> which is
 salen
-bytes long.
-The hostname is of length
+> bytes long.  The hostname is of length
 hostlen
-and is returned via
+> and is returned via
 *host.
-The maximum length of the hostname is
-1025 bytes:
- The maximum length of the hostname is
+1025 bytes: NI_MAXHOST.
.
The name of the service associated with the port number in
+> The name of the service associated with the port number in
 sa
-is returned in
- is returned in *serv.
-It is
-servlen
-bytes long.
-The maximum length of the service name is
- bytes long.  The maximum length
+of the service name is NI_MAXSERV - 32 bytes.
The
- The flags
-argument sets the following bits:
+> argument sets the following
+bits:

RETURN VALUES

SEE ALSO

BUGS

lwres_herror() -prints the string +> prints the string s -on - on stderr -followed by the string generated by - followed by the string +generated by lwres_hstrerror() -for the error code stored in the global variable - for the error code +stored in the global variable lwres_h_errno.

.

lwres_hstrerror() -returns an appropriate string for the error code gievn by - returns an appropriate string +for the error code gievn by err. +>. The values of +the error codes and messages are as follows: -The values of the error codes and messages are as follows:

lwres_net_ntop() -converts an IP address of protocol family - converts an IP address of +protocol family af -— IPv4 or IPv6 — -at location - — IPv4 or IPv6 — +at location src -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.

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.

The generated string is copied to -The generated string is copied to dst -provided +> provided size -indicates it is long enough to store the ASCII representation -of the address.

indicates it is long enough to store the +ASCII representation of the address.

RETURN VALUES

If successful, the function returns -If successful, the function returns dst: - -a pointer to a string containing -the presentation format of the address. -lwres_net_ntop() -returns +> returns NULL -and sets the global variable +> and sets the global variable errno -to - to EAFNOSUPPORT -if the protocol family given in - if +the protocol family given in af -is not supported.

is not +supported.

lwres_nooprequest_render() -uses resolver context - uses resolver +context ctx -to convert no-op request structure +> to convert no-op request structure req -to canonical format. -The packet header structure - to canonical format. The packet header +structure pkt -is initialised and transferred to -buffer - is initialised and transferred to +buffer b. - -The contents of +>. The contents of *req -are then appended to the buffer in canonical format. - are then appended to the buffer in +canonical format. lwres_noopresponse_render() @@ -224,103 +215,85 @@ performs the same task, except it converts a no-op response structure lwres_noopresponse_t -to the lightweight resolver's canonical format.

to the lightweight resolver's +canonical format.

lwres_nooprequest_parse() -uses context +> uses context ctx -to convert the contents of packet +> to convert the contents of packet pkt -to a - to a lwres_nooprequest_t -structure. -Buffer -b -provides space to be used for storing this structure. -When the function succeeds, the resulting +> provides space to be used +for storing this structure. When the function succeeds, the resulting lwres_nooprequest_t -is made available through +> is made available through *structp. - lwres_noopresponse_parse() -offers the same semantics as - offers the same +semantics as lwres_nooprequest_parse() -except it yields a - except it +yields a lwres_noopresponse_t -structure.

structure.

lwres_noopresponse_free() -and +> and lwres_nooprequest_free() -release the memory in resolver context - release the memory in +resolver context ctx -that was allocated to the +> that was allocated to the lwres_noopresponse_t -or - or lwres_nooprequest_t -structures referenced via -structp.

.

- + @@ -201,12 +201,6 @@ buffer *b to resolver packet lwres_lwpacket_t. - -Both functions have assertion checks to ensure that -b and pkt are not -NULL. - - diff --git a/lib/lwres/man/lwres_packet.html b/lib/lwres/man/lwres_packet.html index 50a82126c1..2d2ab53b49 100644 --- a/lib/lwres/man/lwres_packet.html +++ b/lib/lwres/man/lwres_packet.html @@ -115,8 +115,6 @@ struct lwres_lwpacket { };

The elements of this structure are:

lwres_lwpacket_renderheader() -transfers the contents of lightweight resolver packet structure +> transfers the +contents of lightweight resolver packet structure lwres_lwpacket_t - *pkt -in network byte order to the lightweight resolver buffer, +> in network +byte order to the lightweight resolver buffer, *b.

.

lwres_lwpacket_parseheader() -performs the converse operation. -It transfers data in network byte order from buffer - performs the +converse operation. It transfers data in network byte order from +buffer *b -to resolver packet +> to resolver packet *pkt. - -The contents of the buffer +>. The contents of the buffer b -should correspond to a +> should correspond to a lwres_lwpacket_t.

.

Both functions have assertion checks to ensure that b -and - and pkt -are not +> are not NULL.

.

RETURN VALUES

Successful calls to +> Successful calls to lwres_lwpacket_renderheader() -and +> and lwres_lwpacket_parseheader() -return +> return LWRES_R_SUCCESS. - -If there is insufficient space to copy data between the buffer -. If there is insufficient +space to copy data between the buffer *b -and lightweight resolver packet - and +lightweight resolver packet *pkt -both functions return - both functions +return LWRES_R_UNEXPECTEDEND.

.

current. +\fBlwres_string_parse()\fR retrieves a DNS-encoded +string starting the current pointer of lightweight resolver buffer +\fIb\fR: i.e. b->current. When the function returns, the address of the first byte of the -encoded string is returned via -\fI*c\fR -and the length of that string is given by -\fI*len\fR. -The buffer's current pointer is advanced to point at the character +encoded string is returned via \fI*c\fR and the +length of that string is given by \fI*len\fR. The +buffer's current pointer is advanced to point at the character following the string length, the encoded string, and the trailing -\fBNULL\fR -character. -\fBlwres_string_parse()\fR -has an assertion check that -\fIb\fR -is not -\fBNULL\fR. +\fBNULL\fR character. +\fBlwres_string_parse()\fR has an assertion check that +\fIb\fR is not \fBNULL\fR. .PP -\fBlwres_addr_parse()\fR -extracts an address from the buffer -\fIb\fR. -It checks that -\fIaddr\fR -is not null. -The buffer's current pointer -b->current -is presumed to point at an encoded address: the address preceded by a -32-bit protocol family identifier and a 16-bit length field. -The encoded address is copied to -addr->address -and -addr->length -indicates the size in bytes of the address that was copied. -b->current -is advanced to point at the next byte of available data in the buffer +\fBlwres_addr_parse()\fR extracts an address from the +buffer \fIb\fR. It checks that +\fIaddr\fR is not null. The buffer's current pointer +b->current is presumed to point at an encoded +address: the address preceded by a 32-bit protocol family identifier +and a 16-bit length field. The encoded address is copied to +addr->address and +addr->length indicates the size in bytes of +the address that was copied. b->current is +advanced to point at the next byte of available data in the buffer following the encoded address. .PP \fBlwres_getaddrsbyname()\fR @@ -109,58 +93,32 @@ they are controlled through the functions. .PP The lightweight resolver uses -\fBlwres_getaddrsbyname()\fR -to perform foward lookups. -Hostname -\fIname\fR -is looked up using the resolver context -\fIctx\fR -for memory allocation. -\fIaddrtypes\fR -is a bitmask indicating which type of addresses are to be looked up. -Current values for this bitmask are -\fBLWRES_ADDRTYPE_V4\fR -for IPv4 addresses and -\fBLWRES_ADDRTYPE_V6\fR -for IPv6 addresses. -Results of the lookup are returned in -\fI*structp\fR. -\fBlwres_getaddrsbyname()\fR -checks that its pointer arguments are not -\fBNULL\fR -and that -\fIaddrtypes\fR -is non-zero. +\fBlwres_getaddrsbyname()\fR to perform foward lookups. +Hostname \fIname\fR is looked up using the resolver +context \fIctx\fR for memory allocation. +\fIaddrtypes\fR is a bitmask indicating which type of +addresses are to be looked up. Current values for this bitmask are +\fBLWRES_ADDRTYPE_V4\fR for IPv4 addresses and +\fBLWRES_ADDRTYPE_V6\fR for IPv6 addresses. Results of the +lookup are returned in \fI*structp\fR. +\fBlwres_getaddrsbyname()\fR checks that its pointer +arguments are not \fBNULL\fR and that +\fIaddrtypes\fR is non-zero. .PP -\fBlwres_getnamebyaddr()\fR -performs reverse lookups. -Resolver context -\fIctx\fR -is used for memory allocation. -The address type is indicated by -\fIaddrtype\fR: -\fBLWRES_ADDRTYPE_V4\fR -or -\fBLWRES_ADDRTYPE_V6\fR. -The address to be looked up is given by -\fIaddr\fR -and its length is -\fIaddrlen\fR -bytes. -The result of the function call is made available through -\fI*structp\fR. -Like +\fBlwres_getnamebyaddr()\fR performs reverse lookups. +Resolver context \fIctx\fR is used for memory +allocation. The address type is indicated by +\fIaddrtype\fR: \fBLWRES_ADDRTYPE_V4\fR or +\fBLWRES_ADDRTYPE_V6\fR. The address to be looked up is given +by \fIaddr\fR and its length is +\fIaddrlen\fR bytes. The result of the function call +is made available through \fI*structp\fR. Like \fBlwres_getaddrsbyname()\fR, -\fBlwres_getnamebyaddr()\fR -uses assertion checking to ensure its pointer arguments are not -\fBNULL\fR -and -\fIaddrtype\fR -is not zero. -\fBlwres_getaddrsbyname()\fR -also checks that -\fIaddrlen\fR -is non-zero. +\fBlwres_getnamebyaddr()\fR uses assertion checking to +ensure its pointer arguments are not \fBNULL\fR and +\fIaddrtype\fR is not zero. +\fBlwres_getaddrsbyname()\fR also checks that +\fIaddrlen\fR is non-zero. .SH "RETURN VALUES" .PP Successful calls to diff --git a/lib/lwres/man/lwres_resutil.docbook b/lib/lwres/man/lwres_resutil.docbook index f892e37e98..a21e78baa6 100644 --- a/lib/lwres/man/lwres_resutil.docbook +++ b/lib/lwres/man/lwres_resutil.docbook @@ -16,7 +16,7 @@ - WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. --> - + @@ -90,14 +90,11 @@ length of that string is given by *len. The buffer's current pointer is advanced to point at the character following the string length, the encoded string, and the trailing NULL character. -lwres_string_parse() has an assertion check that -b is not NULL. lwres_addr_parse() extracts an address from the -buffer b. It checks that -addr is not null. The buffer's current pointer +buffer b. The buffer's current pointer b->current is presumed to point at an encoded address: the address preceded by a 32-bit protocol family identifier and a 16-bit length field. The encoded address is copied to @@ -148,9 +145,9 @@ addresses are to be looked up. Current values for this bitmask are LWRES_ADDRTYPE_V4 for IPv4 addresses and LWRES_ADDRTYPE_V6 for IPv6 addresses. Results of the lookup are returned in *structp. -lwres_getaddrsbyname() checks that its pointer -arguments are not NULL and that -addrtypes is non-zero. + + + lwres_getnamebyaddr() performs reverse lookups. Resolver context ctx is used for memory allocation. The address type is indicated by @@ -158,13 +155,7 @@ allocation. The address type is indicated by LWRES_ADDRTYPE_V6. The address to be looked up is given by addr and its length is addrlen bytes. The result of the function call -is made available through *structp. Like -lwres_getaddrsbyname(), -lwres_getnamebyaddr() uses assertion checking to -ensure its pointer arguments are not NULL and -addrtype is not zero. -lwres_getaddrsbyname() also checks that -addrlen is non-zero. +is made available through *structp. diff --git a/lib/lwres/man/lwres_resutil.html b/lib/lwres/man/lwres_resutil.html index ad3b0cd357..31466df7fd 100644 --- a/lib/lwres/man/lwres_resutil.html +++ b/lib/lwres/man/lwres_resutil.html @@ -106,105 +106,85 @@ NAME="AEN43" >lwres_string_parse() -retrieves a DNS-encoded string starting the current pointer of -lightweight resolver buffer +> retrieves a DNS-encoded +string starting the current pointer of lightweight resolver buffer b: - -i.e. -: i.e. b->current. - When the function returns, the address of the first byte of the -encoded string is returned via -*c -and the length of that string is given by - and the +length of that string is given by *len. - -The buffer's current pointer is advanced to point at the character +>. The +buffer's current pointer is advanced to point at the character following the string length, the encoded string, and the trailing NULL -character. +> character. lwres_string_parse() -has an assertion check that +> has an assertion check that b -is not - is not NULL.

.

lwres_addr_parse() -extracts an address from the buffer - extracts an address from the +buffer b. - -It checks that +>. It checks that addr -is not null. -The buffer's current pointer +> is not null. The buffer's current pointer b->current -is presumed to point at an encoded address: the address preceded by a -32-bit protocol family identifier and a 16-bit length field. -The encoded address is copied to +> is presumed to point at an encoded +address: the address preceded by a 32-bit protocol family identifier +and a 16-bit length field. The encoded address is copied to addr->address -and +> and addr->length -indicates the size in bytes of the address that was copied. - indicates the size in bytes of +the address that was copied. b->current -is advanced to point at the next byte of available data in the buffer +> is +advanced to point at the next byte of available data in the buffer following the encoded address.

lwres_getaddrsbyname() -to perform foward lookups. -Hostname - to perform foward lookups. +Hostname name -is looked up using the resolver context - is looked up using the resolver +context ctx -for memory allocation. +> for memory allocation. addrtypes -is a bitmask indicating which type of addresses are to be looked up. -Current values for this bitmask are +> is a bitmask indicating which type of +addresses are to be looked up. Current values for this bitmask are LWRES_ADDRTYPE_V4 -for IPv4 addresses and +> for IPv4 addresses and LWRES_ADDRTYPE_V6 -for IPv6 addresses. -Results of the lookup are returned in - for IPv6 addresses. Results of the +lookup are returned in *structp. - lwres_getaddrsbyname() -checks that its pointer arguments are not - checks that its pointer +arguments are not NULL -and that +> and that addrtypes -is non-zero.

is non-zero.

lwres_getnamebyaddr() -performs reverse lookups. -Resolver context - performs reverse lookups. +Resolver context ctx -is used for memory allocation. -The address type is indicated by +> is used for memory +allocation. The address type is indicated by addrtype: - -: LWRES_ADDRTYPE_V4 -or +> or LWRES_ADDRTYPE_V6. - -The address to be looked up is given by -. The address to be looked up is given +by addr -and its length is +> and its length is addrlen -bytes. -The result of the function call is made available through - bytes. The result of the function call +is made available through *structp. - -Like +>. Like lwres_getaddrsbyname(), - lwres_getnamebyaddr() -uses assertion checking to ensure its pointer arguments are not - uses assertion checking to +ensure its pointer arguments are not NULL -and +> and addrtype -is not zero. +> is not zero. lwres_getaddrsbyname() -also checks that +> also checks that addrlen -is non-zero.

is non-zero.

lwres_getnamebyaddr().

.

Both