diff --git a/doc/man/lwres/lwres.3 b/doc/man/lwres/lwres.3 new file mode 100644 index 0000000000..3c686c64ea --- /dev/null +++ b/doc/man/lwres/lwres.3 @@ -0,0 +1,291 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres +.Nd introduction to the lightweight resolver +.Sh SYNOPSIS +.Fd #include +.Sh DESCRIPTION +The lightweight resolver provides a simple way for clients to perform +forward and reverse lookups. +Instead of looking up the names or addresses directly, clients can send +requests to the lightweight resolver daemon +.Nm lwresd +which does hard work of performing the lookups for them. +Clients can just use the lightweight resolver library to format a +request to get a hostname for an IP address or vice versa, send it to +.Nm lwresd +and wait for a response. +.Pp +The lightweight resolver in BIND 9 consists of three components: +a client, a server and a protocol. +Clients use the functions provided by the lightweight resolver library +to encode requests and decode responses. +The server for the lightweight resolver is +.Nm lwresd . +In reality this is implemented by the name server, +.Nm named , +though when operating as the lightweight resolver server, +.Nm lwresd +is functionally and logically distinct from the actual name server. +The protocol consists of a number of opcodes, each of which has a +request and response structure associated with it. +The lightweight resolver library contains functions to convert these +structures to and from the canonical format whenver they are sent to +.Nm lwresd . +.Sh RATIONALE +.Pp +Conventional DNS lookups of hostnames and IPv4 addresses are usually +simple and straightforward. +A client can issue queries to map a hostname to an IPv4 address or +from an IPv4 address to a hostname. +Many DNS queries can be needed to lookup IPv6 addresses. +It may be necessary to resolve potentially variable-length partial +IPv6 addresses: aggregation and site-level identifiers for instance. +Keeping track of all of these queries and assembling the answers to +return the hostname or IPv6 address is very hard work and error-prone. +Further complexity can be caused by DNAME chains. +If the answers are signed using DNSSEC, additional queries may be needed +to verify the signatures. +The consequence of this is that clients can be overwhelmed with the +amount of work needed to resolve IPv6 addresses. +BIND9 provides a lightweight resolver to eliminate these problems if +applications had to resolve IPv6 addresses for themselves. +.Pp +Instead of looking up the hostnames or IPv6 addresses directly, clients +can use the lightweight resolver to get the name server to do the work. +Clients construct simple questions like \*qwhat is the hostname for +the following address?\*q or \*qwhat are the addresses of hostname +.Dv host.example.com?\*q +The lightweight resolver functions take these questions and format +them into queries which are sent to +.Nm lwresd . +Replies from the lightweight resolver server are then decoded to return +an answer to the client which made the original request. +.Sh CANONICAL FORMAT +.Pp +The lightweight resolver's canonical data format has been arranged for +efficiency. +All integer values are in network byte order. +Addresses are also in network byte order. +This means that, at least for IPv4 and IPv6 addresses, they can be +used directly in network system calls without needing to be byte +swapped. +Character strings get prefixed by a length and are always terminated +with a +.Dv NUL +character. +This simplifies structure handling and parsing for both the server +receiving a request and the client receiving a reply. +It also eliminates data copying by enabling a mapping structure to +directly point at data in the actual receive buffer. +.Sh OPCODES +.Pp +Every lightweight resolver operation uses a unique opcode. +Each opcode is assigned a number. +Opcodes in the range 0x00000000 and 0x03ffffff are reserved for use by +the lightweight resolver library. +Opcodes between 0x04000000 and 0xffffffff have been set aside for use by +applications. +.Pp +Three opcodes are currently defined: +.Bl -tag -width LWRES_OPCODE_GETADDRSBYNAME +.It Li LWRES_OPCODE_NOOP +The no-op opcode is essentially an echo operation, comparable to +.Xr ping 1 . +The server simply returns the entire data region that had been sent by +the client. +Therefore clients can use this opcode to determine if the server is +operational or not. +It can also be used by clients to check the version number and any +parameters of the lightweight resolver protocol that are supported by the +server. +.It Li LWRES_OPCODE_GETADDRSBYNAME +This opcode is used to get all the known addresses for a hostname. +In principle, this could also return information from NIS/YP or +.Pa /etc/hosts , +though this is not implemented yet. +Flags can be set in the request structure that is used for this opcode +to indicate whether IPv4 or IPv6 addresses or both should be returned. +.It Li LWRES_OPCODE_GETNAMEBYADDR +This provides the complementary operation to +.Dv LWRES_OPCODE_GETADDRSBYNAME . +It returns the hostname for the address that was supplied in the +request structure. +.El +.\" +.\" XXXJR +.\" We don't need this section, at least not yet. 23/6/00 +.\" +.\" .Sh OPCODE REPLIES +.\" .Pp +.\" Replies to lightweight resolver operations contain return codes. +.\" Results between 0x04000000 and 0xffffffff are application defined. +.\" The lightweight resolver library reserves result codes between +.\" 0x00000000 and 0x03ffffff. +.\" These occupy the same reserved range used for ISC return values that +.\" are defined in +.\" .Pa isc/resultclass.h . +.\" This means that, if appropriate, it would be trivial to map those ISC +.\" return values to lightweight resolver packet result codes. +.Sh STRUCTURE AND PACKET ENCODING/DECODING +Each opcode has two structures: one for the request and one for the +response. +Clients use the lightweight resolver functions to construct the +request structure and send it to the name server. +The name server decodes the request, carries out the operation and +fills in an opcode-specific response structure which is returned to +the client. +.Pp +For every opcode, three functions operate on these structures. +A +.Ar render +function converts the structure to canonical form and a +.Ar parse +function translates from the canonical form to the op-code specific +structure. +Memory allocated to the opcode's request or reply structures is +discarded using the +.Ar free +function. +Clients will typically use the op-code specific +.Ar xxx_request_render , +.Ar xxx_response_parse +and +.Ar xxx_response_free +functions. +The name server will use the +.Ar xxx_request_parse , +.Ar xxx_response_render +and +.Ar xxx_request_free +functions. +.Pp +For example, the no-op opcode - +.Dv LWRES_OPCODE_NOOP +- uses +.Dv lwres_nooprequest_t +and +.Dv lwres_noopresponse_t +structures for the requests and responses used in the no-op operation. +.Fn lwres_nooprequest_render +takes a +.Dv lwres_nooprequest_t +structure and converts into a packet in lightweight resolver canonical +format. +Similarly +.Fn lwres_noopresponse_render +converts a +.Dv lwres_noopresponse_t +structure into a packet in lightweight resolver canonical format. +.Fn lwres_nooprequest_parse +takes a packet in canonical format and fills in a corresponding +.Dv lwres_nooprequest_t +structure. +A +.Dv lwres_noopresponse_t +structure is set up by\p +passing a response packet in canonical format to +.Fn lwres_noopresponse_render . +.Fn lwres_nooprequest_free +and +.Fn lwres_noopresponse_free +releases the memory allocated to the +.Dv lwres_nooprequest_t +and +.Dv lwres_noopresponse_t +structures respectively. +.\" +.\" XXXJR +.\" NOT YET. +.\" This is just a placeholder to indicate where the section on the +.\" lwres security API should be documented once this is implemented. +.\" There's no point in documenting vapourware, especially if the +.\" API is likely to change between now and then. 23/6/00 +.\" .Sh SECURITY +.\" The lightweight resolver provides hooks for requesting the use of +.\" DNSSEC for authenticating requests and responses. +.\" This interface is not currently implemented and is likely to +.\" change. +.\" It is mentioned here to indicate the capabilities that can be expected +.\" in future releases of the lightweight resolver. +.\" .Pp +.\" The following flag bits have been allocated. +.\" .Bl -tag -width LWRES_FLAG_TRUSTNOTREQUIRED +.\" .It Li LWRES_FLAG_TRUSTDEFAULT +.\" Let the server decide whether to use DNSSEC or not. +.\" .It Li LWRES_FLAG_TRUSTNOTREQUIRED +.\" DNSSEC authentication of the DNS queries and replies is not required +.\" .It Li LWRES_FLAG_TRUSTREQUIRED +.\" Any DNSSEC data found when resolving the query must validate and the +.\" server must be DNSSEC-aware. +.\" .It Li LWRES_FLAG_TRUSTRESERVED +.\" Reserved for future use. +.\" .El +.Sh CLIENT SETUP +Every client that uses the lightweight resolver needs to create and +maintain its own state. +Library calls are provided to manage that data structure, a resolver +context. +If the client uses threads, it either has to provide its own locking +primitives on that context structure or else create a context for each +thread. +See +.Xr lwres_context 3 . +Once the context has been created, +.Fn lwres_conf_init +is called to read +.Pa /etc/resolv.conf +so that various options such as sort lists, search lists and so on can +be applied. +.Sh CLIENT INTERFACE +The simplest interface to the lightweight resolver is provided by +.Fn lwres_getaddrsbyname +and +.Fn lwres_getnamebyaddr . +These functions are blocking calls. +A client will wait after sending a request until either a response is +returned or else a timeout interval occurs. +If non-blocking operations are required, the client will need to +call the opcode-specific +.Ar request_render +and +.Ar response_parse +directly. +.Sh SERVER INTERFACE +Service for the lightweight resolver is provided by the lightweight +resolver daemon, +.Nm lwresd . +It listens on port number 921 of the loopback interface and expects to +receive packets in the lightweight resolver's canonical format +described above. +.Sh SEE ALSO +.Xr lwres_noop 3 , +.Xr lwres_gabn 3 , +.Xr lwres_gnba 3 , +.Xr lwres_context 3 , +.Xr lwres_config 3 , +.Xr resolver 5 , +.Xr lwres_getipnode 3 +.Xr lwresd 8 , +.Xr named 8 . diff --git a/doc/man/lwres/lwres_addr_parse.3 b/doc/man/lwres/lwres_addr_parse.3 new file mode 100644 index 0000000000..5c26a32c33 --- /dev/null +++ b/doc/man/lwres/lwres_addr_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_addr_parse.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.so lwres_resutil.3 diff --git a/doc/man/lwres/lwres_buffer.3 b/doc/man/lwres/lwres_buffer.3 new file mode 100644 index 0000000000..72b241a3e1 --- /dev/null +++ b/doc/man/lwres/lwres_buffer.3 @@ -0,0 +1,324 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_BUFFER 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_buffer_init , +.Nm lwres_buffer_invalidate , +.Nm lwres_buffer_add , +.Nm lwres_buffer_subtract , +.Nm lwres_buffer_clear , +.Nm lwres_buffer_first , +.Nm lwres_buffer_forward , +.Nm lwres_buffer_back , +.Nm lwres_buffer_getuint8 , +.Nm lwres_buffer_putuint8 , +.Nm lwres_buffer_getuint16 , +.Nm lwres_buffer_putuint16 , +.Nm lwres_buffer_getuint32 , +.Nm lwres_buffer_putuint32 , +.Nm lwres_buffer_putmem , +.Nm lwres_buffer_getmem +.Nd lightweight resolver buffer management +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft void +.Fo lwres_buffer_init +.Fa "lwres_buffer_t *b" +.Fa "void *base" +.Fa "unsigned int length" +.Fc +.Ft void +.Fo lwres_buffer_invalidate +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_add +.Fa "lwres_buffer_t *b" +.Fa "unsigned int n" +.Fc +.Ft void +.Fo lwres_buffer_subtract +.Fa "lwres_buffer_t *b" +.Fa "unsigned int n" +.Fc +.Ft void +.Fo lwres_buffer_clear +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_first +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_forward +.Fa "lwres_buffer_t *b" +.Fa "unsigned int n" +.Fc +.Ft void +.Fo lwres_buffer_back +.Fa "lwres_buffer_t *b" +.Fa "unsigned int n" +.Fc +.Ft lwres_uint8_t +.Fo lwres_buffer_getuint8 +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_putuint8 +.Fa "lwres_buffer_t *b" +.Fa "lwres_uint8_t val" +.Fc +.Ft lwres_uint16_t +.Fo lwres_buffer_getuint16 +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_putuint16 +.Fa "lwres_buffer_t *b" +.Fa "lwres_uint16_t val" +.Fc +.Ft lwres_uint32_t +.Fo lwres_buffer_getuint32 +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_putuint32 +.Fa "lwres_buffer_t *b" +.Fa "lwres_uint32_t val" +.Fc +.Ft void +.Fo lwres_buffer_putmem +.Fa "lwres_buffer_t *b" +.Fa "const unsigned char *base" +.Fa "unsigned int length" +.Fc +.Ft void +.Fo lwres_buffer_getmem +.Fa "lwres_buffer_t *b" +.Fa "unsigned char *base" +.Fa "unsigned int length" +.Fc +.Sh DESCRIPTION +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. +.Pp +A buffer is a region of memory, together with a set of related +subregions. +The \*qused region\*q and the \*qavailable\*q region are disjoint, and +their union is the buffer's region. +The used region extends from the beginning of the buffer region to the +last used byte. +The available region extends from one byte greater than the last used +byte to the end of the buffer's region. +The size of the used region can be changed using various +buffer commands. +Initially, the used region is empty. +.Pp +The used region is further subdivided into two disjoint regions: the +\*qconsumed region\*q and the \*qremaining region\*q. +The union of these two regions is the used region. +The consumed region extends from the beginning of the used region to +the byte before the \*qcurrent\*q offset (if any). +The \*qremaining\*q region the current pointer to the end of the used +region. +The size of the consumed region can be changed using various +buffer commands. +Initially, the consumed region is empty. +.Pp +The \*qactive region\*q is an (optional) subregion of the remaining +region. +It extends from the current offset to an offset in the +remaining region. +Initially, the active region is empty. +If the current offset advances beyond the chosen offset, +the active region will also be empty. +.Pp +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. +.Pp +.Fn lwres_buffer_init +makes the +.Dv "struct lwres_buffer" +referenced by +.Fa *b +to be associated with a 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. +.Pp +The functions +.Fn lwres_buffer_add +and +.Fn lwres_buffer_subtract +respectively increase and decrease the used space in +buffer +.Fa *b +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 . +.Pp +A lightweight resolver buffer is re-initialised by +.Fn lwres_buffer_clear . +The function sets +.Li b->used , +.Li b->current +and +.Li b->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. +.Pp +The consumed region of buffer +.Fa *b +is increased by +.Fa n +bytes +using +.Fn lwres_buffer_forward . +The function checks for buffer overflow. +Similarly, +.Fn lwres_buffer_back +decreases buffer +.Fa b 's +consumed region by +.Fa n +bytes and checks for buffer 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. +Similarly, +.Fn lwres_buffer_putuint16 +and +.Fn lwres_buffer_putuint32 +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. +.Pp +Arbitrary amounts of data are read or written from a lightweight +resolver buffer with +.Fn lwres_buffer_getmem +and +.Fn lwres_buffer_putmem +respectively. +.Fn lwres_buffer_putmem +copies +.Fa length +bytes of memory at +.Fa base +to +.Fa b. +Conversely, +.Fn lwres_buffer_getmem +copies +.Fa length +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. diff --git a/doc/man/lwres/lwres_buffer_add.3 b/doc/man/lwres/lwres_buffer_add.3 new file mode 100644 index 0000000000..25b7c08932 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_add.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_add.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_back.3 b/doc/man/lwres/lwres_buffer_back.3 new file mode 100644 index 0000000000..eb57f87b84 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_back.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_back.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_clear.3 b/doc/man/lwres/lwres_buffer_clear.3 new file mode 100644 index 0000000000..4d4e7c0bf5 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_clear.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_clear.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_first.3 b/doc/man/lwres/lwres_buffer_first.3 new file mode 100644 index 0000000000..4a1a8f8ad1 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_first.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_first.3,v 1.1 2000/06/27 21:52:58 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_forward.3 b/doc/man/lwres/lwres_buffer_forward.3 new file mode 100644 index 0000000000..1171c07b26 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_forward.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_forward.3,v 1.1 2000/06/27 21:52:58 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_getmem.3 b/doc/man/lwres/lwres_buffer_getmem.3 new file mode 100644 index 0000000000..f3b5d7840c --- /dev/null +++ b/doc/man/lwres/lwres_buffer_getmem.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_getmem.3,v 1.1 2000/06/27 21:52:58 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_getuint16.3 b/doc/man/lwres/lwres_buffer_getuint16.3 new file mode 100644 index 0000000000..ce7f6395f5 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_getuint16.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_getuint16.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_getuint32.3 b/doc/man/lwres/lwres_buffer_getuint32.3 new file mode 100644 index 0000000000..57645c94a0 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_getuint32.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_getuint32.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_getuint8.3 b/doc/man/lwres/lwres_buffer_getuint8.3 new file mode 100644 index 0000000000..d91088b06a --- /dev/null +++ b/doc/man/lwres/lwres_buffer_getuint8.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_getuint8.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_init.3 b/doc/man/lwres/lwres_buffer_init.3 new file mode 100644 index 0000000000..978f957248 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_init.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_init.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_invalidate.3 b/doc/man/lwres/lwres_buffer_invalidate.3 new file mode 100644 index 0000000000..8f4d5c08a4 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_invalidate.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_invalidate.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_putmem.3 b/doc/man/lwres/lwres_buffer_putmem.3 new file mode 100644 index 0000000000..106f00fe45 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_putmem.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_putmem.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_putuint16.3 b/doc/man/lwres/lwres_buffer_putuint16.3 new file mode 100644 index 0000000000..312487519e --- /dev/null +++ b/doc/man/lwres/lwres_buffer_putuint16.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_putuint16.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_putuint32.3 b/doc/man/lwres/lwres_buffer_putuint32.3 new file mode 100644 index 0000000000..54ef235e33 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_putuint32.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_putuint32.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_putuint8.3 b/doc/man/lwres/lwres_buffer_putuint8.3 new file mode 100644 index 0000000000..fa19fb80f1 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_putuint8.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_putuint8.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_buffer_subtract.3 b/doc/man/lwres/lwres_buffer_subtract.3 new file mode 100644 index 0000000000..25e62b7f25 --- /dev/null +++ b/doc/man/lwres/lwres_buffer_subtract.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_subtract.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/doc/man/lwres/lwres_conf_clear.3 b/doc/man/lwres/lwres_conf_clear.3 new file mode 100644 index 0000000000..d03f1f95b9 --- /dev/null +++ b/doc/man/lwres/lwres_conf_clear.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_clear.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/doc/man/lwres/lwres_conf_get.3 b/doc/man/lwres/lwres_conf_get.3 new file mode 100644 index 0000000000..cf2ed6aa80 --- /dev/null +++ b/doc/man/lwres/lwres_conf_get.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_get.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/doc/man/lwres/lwres_conf_init.3 b/doc/man/lwres/lwres_conf_init.3 new file mode 100644 index 0000000000..625b307bd2 --- /dev/null +++ b/doc/man/lwres/lwres_conf_init.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_init.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/doc/man/lwres/lwres_conf_parse.3 b/doc/man/lwres/lwres_conf_parse.3 new file mode 100644 index 0000000000..23bedfeb46 --- /dev/null +++ b/doc/man/lwres/lwres_conf_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_parse.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/doc/man/lwres/lwres_conf_print.3 b/doc/man/lwres/lwres_conf_print.3 new file mode 100644 index 0000000000..75e0ec411f --- /dev/null +++ b/doc/man/lwres/lwres_conf_print.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_print.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/doc/man/lwres/lwres_config.3 b/doc/man/lwres/lwres_config.3 new file mode 100644 index 0000000000..bc4679419d --- /dev/null +++ b/doc/man/lwres/lwres_config.3 @@ -0,0 +1,109 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_config.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_CONFIG 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_conf_init , +.Nm lwres_conf_clear , +.Nm lwres_conf_parse , +.Nm lwres_conf_print , +.Nm lwres_conf_get +.Nd lightweight resolver configuration +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft void +.Fo lwres_conf_init +.Fa "lwres_context_t *ctx" +.Fc +.Ft void +.Fo lwres_conf_clear +.Fa "lwres_context_t *ctx" +.Fc +.Ft lwres_result_t +.Fo lwres_conf_parse +.Fa "lwres_context_t *ctx" +.Fa "const char *filename" +.Fc +.Ft lwres_result_t +.Fo lwres_conf_print +.Fa "lwres_context_t *ctx" +.Fa "FILE *fp" +.Fc +.Ft lwres_conf_t * +.Fo lwres_conf_get +.Fa "lwres_context_t *ctx" +.Fc +.Sh DESCRIPTION +.Fn lwres_conf_init +creates an empty +.Dv lwres_conf_t +structure for lightweight resolver context +.Fa ctx . +.Pp +.Fn lwres_conf_clear +frees up all the internal memory used by +that +.Dv lwres_conf_t +structure in resolver context +.Fa ctx . +.Pp +.Fn lwres_conf_parse +opens the file +.Fa filename +and parses it to initialise the resolver context +.Fa ctx 's +.Dv lwres_conf_t +structure. +.Pp +.Fn lwres_conf_print +prints the +.Dv lwres_conf_t +structure for resolver context +.Fa ctx +to the +.Dv FILE +.Fa fp. +.Sh RETURN VALUES +.Fn lwres_conf_parse +returns +.Er LWRES_R_SUCCESS +if it successfully read and parsed +.Fa filename . +It returns +.Er LWRES_R_FAILURE +if +.Fa filename +could not be opened or contained incorrect +resolver statements. +.Pp +.Fn lwres_conf_print +returns +.Er LWRES_R_SUCCESS +unless an error occurred when converting the network addresses to a +numeric host address string. +If this happens, the function returns +.Er LWRES_R_FAILURE . +.Sh SEE ALSO +.Xr stdio 3, +.Xr resolver 5 . +.Sh FILES +.Pa /etc/resolv.conf diff --git a/doc/man/lwres/lwres_context.3 b/doc/man/lwres/lwres_context.3 new file mode 100644 index 0000000000..0c2055e42b --- /dev/null +++ b/doc/man/lwres/lwres_context.3 @@ -0,0 +1,257 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_CONTEXT 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_context_create , +.Nm lwres_context_destroy , +.Nm lwres_context_nextserial , +.Nm lwres_context_initserial , +.Nm lwres_context_freemem , +.Nm lwres_context_allocmem , +.Nm lwres_context_sendrecv +.Nd lightweight resolver memory allocation routines +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_context_create +.Fa "lwres_context_t **contextp" +.Fa "void *arg" +.Fa "lwres_malloc_t malloc_function" +.Fa "lwres_free_t free_function" +.Fc +.Ft lwres_result_t +.Fo lwres_context_destroy +.Fa "lwres_context_t **contextp" +.Fc +.Ft void +.Fo lwres_context_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 void +.Fo lwres_context_freemem +.Fa "lwres_context_t *ctx" +.Fa "void *mem" +.Fa "size_t len" +.Fc +.Ft void +.Fo lwres_context_allocmem +.Fa "lwres_context_t *ctx" +.Fa "size_t len" +.Fc +.Ft void * +.Fo lwres_context_sendrecv +.Fa "lwres_context_t *ctx" +.Fa "void *sendbase" +.Fa "int sendlen" +.Fa "void *recvbase" +.Fa "int recvlen" +.Fa "int *recvd_len" +.Fc +.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 +.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. +.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 +.Xr malloc 3 +and +.Xr free 3 +are used. +.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. +Once memory for the structure has been allocated, +.Xr lwres_conf_init 3 +is called to initialise it. +The structure is then returned via +.Fa *contextp . +.Pp +A +.Dv "struct lwres_context" +is destroyed by +.Fn lwres_context_destroy. +.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. +.Pp +The context's serial number is controlled with +.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 . +.Pp +Memory for a lightweight resolver context is allocated and freed using +.Fn lwres_context_allocmem +and +.Fn lwres_context_freemem . +These use whatever allocations were defined when the context was +created with +.Fn lwres_context_create . +.Fn lwres_context_allocmem +allocates +.Fa len +bytes of memory and if successful returns a pointer to the allocated +storage. +.Fn lwres_context_allocmem +checks that +.Fa len +must be greater than 0. +.Fn lwres_context_freemem +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 . +It writes data from +.Fa sendbase +- typically a DNS query - +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 . +.Sh RETURN VALUES +.Fn lwres_context_create +returns +.Er LWRES_R_NOMEMORY +if memory for the +.Dv "struct lwres_context" +could not be allocated, otherwise +.Er LWRES_R_SUCCESS +is returned. +.Pp +Successful calls to the memory allocator +.Fn lwres_context_allocmem +return a pointer to the start of the allocated space. +It returns NULL if memory could not be allocated. +.Pp +.Er LWRES_R_SUCCESS +is returned when +.Fn lwres_context_sendrecv +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. +.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. diff --git a/doc/man/lwres/lwres_context_allocmem.3 b/doc/man/lwres/lwres_context_allocmem.3 new file mode 100644 index 0000000000..1a94a23641 --- /dev/null +++ b/doc/man/lwres/lwres_context_allocmem.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_allocmem.3,v 1.1 2000/06/27 21:53:01 jim Exp $ +.\" +.so lwres_context.3 diff --git a/doc/man/lwres/lwres_context_create.3 b/doc/man/lwres/lwres_context_create.3 new file mode 100644 index 0000000000..f15a8d6a10 --- /dev/null +++ b/doc/man/lwres/lwres_context_create.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_create.3,v 1.1 2000/06/27 21:53:01 jim Exp $ +.\" +.so lwres_context.3 diff --git a/doc/man/lwres/lwres_context_destroy.3 b/doc/man/lwres/lwres_context_destroy.3 new file mode 100644 index 0000000000..6b9fe274d7 --- /dev/null +++ b/doc/man/lwres/lwres_context_destroy.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_destroy.3,v 1.1 2000/06/27 21:53:01 jim Exp $ +.\" +.so lwres_context.3 diff --git a/doc/man/lwres/lwres_context_freemem.3 b/doc/man/lwres/lwres_context_freemem.3 new file mode 100644 index 0000000000..ba8c4be0a0 --- /dev/null +++ b/doc/man/lwres/lwres_context_freemem.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_freemem.3,v 1.1 2000/06/27 21:53:01 jim Exp $ +.\" +.so lwres_context.3 diff --git a/doc/man/lwres/lwres_context_initserial.3 b/doc/man/lwres/lwres_context_initserial.3 new file mode 100644 index 0000000000..8c350b7233 --- /dev/null +++ b/doc/man/lwres/lwres_context_initserial.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_initserial.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_context.3 diff --git a/doc/man/lwres/lwres_context_nextserial.3 b/doc/man/lwres/lwres_context_nextserial.3 new file mode 100644 index 0000000000..231c261452 --- /dev/null +++ b/doc/man/lwres/lwres_context_nextserial.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_nextserial.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_context.3 diff --git a/doc/man/lwres/lwres_context_sendrecv.3 b/doc/man/lwres/lwres_context_sendrecv.3 new file mode 100644 index 0000000000..0d29d8abd3 --- /dev/null +++ b/doc/man/lwres/lwres_context_sendrecv.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_sendrecv.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_context.3 diff --git a/doc/man/lwres/lwres_endhostent.3 b/doc/man/lwres/lwres_endhostent.3 new file mode 100644 index 0000000000..c7f7bf2463 --- /dev/null +++ b/doc/man/lwres/lwres_endhostent.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_endhostent.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_endhostent_r.3 b/doc/man/lwres/lwres_endhostent_r.3 new file mode 100644 index 0000000000..e958b1fdbb --- /dev/null +++ b/doc/man/lwres/lwres_endhostent_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_endhostent_r.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_freeaddrinfo.3 b/doc/man/lwres/lwres_freeaddrinfo.3 new file mode 100644 index 0000000000..360ebe4e5f --- /dev/null +++ b/doc/man/lwres/lwres_freeaddrinfo.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_freeaddrinfo.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_getaddrinfo.3 diff --git a/doc/man/lwres/lwres_freehostent.3 b/doc/man/lwres/lwres_freehostent.3 new file mode 100644 index 0000000000..4544bff8ab --- /dev/null +++ b/doc/man/lwres/lwres_freehostent.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_freehostent.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_getipnode.3 diff --git a/doc/man/lwres/lwres_gabn.3 b/doc/man/lwres/lwres_gabn.3 new file mode 100644 index 0000000000..5675568953 --- /dev/null +++ b/doc/man/lwres/lwres_gabn.3 @@ -0,0 +1,208 @@ +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabn.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GABN 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_gabnrequest_render , +.Nm lwres_gabnresponse_render , +.Nm lwres_gabnrequest_parse , +.Nm lwres_gabnresponse_parse , +.Nm lwres_gabnresponse_free , +.Nm lwres_gabnrequest_free +.Nd lightweight resolver getaddrbyname functions +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_gabnrequest_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_gabnrequest_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_gabnresponse_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_gabnresponse_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_gabnrequest_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_gabnrequest_t **structp" +.Fc +.Ft lwres_result_t +.Fo lwres_gabnresponse_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_gabnresponse_t **structp" +.Fc +.Ft void +.Fo lwres_gabnresponse_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_gabnresponse_t **structp" +.Fc +.Ft void +.Fo lwres_gabnrequest_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_gabnrequest_t **structp" +.Fc +.Sh DESCRIPTION +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 +There are four main functions for the getaddrbyname opcode. +One render function converts a getaddrbyname request structure - +.Dv lwres_gabnrequest_t - +to the lighweight resolver's canonical format. +It is complemented by a parse function that converts a packet in this +canonical format to a getaddrbyname request structure. +Another render function converts the getaddrbyname response structure - +.Dv lwres_gabnresponse_t +to the canonical format. +This is complemented by a parse function which converts a packet in +canonical format to a getaddrbyname response structure. +.Pp +These structures are defined in +.Pa lwres/lwres.h . +They are shown below. +.Bd -literal -offset indent +#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U + +typedef struct lwres_addr lwres_addr_t; +typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint32_t addrtypes; + lwres_uint16_t namelen; + char *name; +} lwres_gabnrequest_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + lwres_uint16_t naddrs; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + lwres_addrlist_t addrs; + void *base; + size_t baselen; +} lwres_gabnresponse_t; +.Ed +.Pp +.Fn lwres_gabnrequest_render +uses resolver context +.Fa ctx +to convert getaddrbyname request structure +.Fa req +to canonical format. +The packet header structure +.Fa pkt +is initialised and transferred to +buffer +.Fa b . +The contents of +.Fa *req +are then appended to the buffer in canonical format. +.Fn lwres_gabnresponse_render +performs the same task, except it converts a getaddrbyname response structure +.Dv lwres_gabnresponse_t +to the lightweight resolver's canonical format. +.Pp +.Fn lwres_gabnrequest_parse +uses context +.Fa ctx +to convert the contents of packet +.Fa pkt +to a +.Dv lwres_gabnrequest_t +structure. +Buffer +.Fa b +provides space to be used for storing this structure. +When the function succeeds, the resulting +.Dv lwres_gabnrequest_t +is made available through +.Fa *structp . +.Fn lwres_gabnresponse_parse +offers the same semantics as +.Fn lwres_gabnrequest_parse +except it yields a +.Dv lwres_gabnresponse_t +structure. +.Pp +.Fn lwres_gabnresponse_free +and +.Fn lwres_gabnrequest_free +release the memory in resolver context +.Fa ctx +that was allocated to the +.Dv lwres_gabnresponse_t +or +.Dv lwres_gabnrequest_t +structures referenced via +.Fa structp . +Any memory associated with ancillary buffers and strings for those +structures is also discarded. +.Sh RETURN VALUES +The getaddrbyname opcode functions +.Fn lwres_gabnrequest_render , +.Fn lwres_gabnresponse_render +.Fn lwres_gabnrequest_parse +and +.Fn lwres_gabnresponse_parse +all return +.Er LWRES_R_SUCCESS +on success. +They return +.Er LWRES_R_NOMEMORY +if memory allocation fails. +.Er LWRES_R_UNEXPECTEDEND +is returned if the available space in the buffer +.Fa b +is too small to accommodate the packet header or the +.Dv lwres_gabnrequest_t +and +.Dv lwres_gabnresponse_t +structures. +.Fn lwres_gabnrequest_parse +and +.Fn lwres_gabnresponse_parse +will return +.Er LWRES_R_UNEXPECTEDEND +if the buffer is not empty after decoding the received packet. +These functions will return +.Er LWRES_R_FAILURE +if +.Li pktflags +in the packet header structure +.Dv lwres_lwpacket_t +indicate that the packet is not a response to an earlier query. +.Sh SEE ALSO +.Xr lwres_packet 3 diff --git a/doc/man/lwres/lwres_gabnrequest_free.3 b/doc/man/lwres/lwres_gabnrequest_free.3 new file mode 100644 index 0000000000..28f7430e51 --- /dev/null +++ b/doc/man/lwres/lwres_gabnrequest_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnrequest_free.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/doc/man/lwres/lwres_gabnrequest_parse.3 b/doc/man/lwres/lwres_gabnrequest_parse.3 new file mode 100644 index 0000000000..726724c33f --- /dev/null +++ b/doc/man/lwres/lwres_gabnrequest_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnrequest_parse.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/doc/man/lwres/lwres_gabnrequest_render.3 b/doc/man/lwres/lwres_gabnrequest_render.3 new file mode 100644 index 0000000000..b7602ddc53 --- /dev/null +++ b/doc/man/lwres/lwres_gabnrequest_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnrequest_render.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/doc/man/lwres/lwres_gabnresponse_free.3 b/doc/man/lwres/lwres_gabnresponse_free.3 new file mode 100644 index 0000000000..acd186abc4 --- /dev/null +++ b/doc/man/lwres/lwres_gabnresponse_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnresponse_free.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/doc/man/lwres/lwres_gabnresponse_parse.3 b/doc/man/lwres/lwres_gabnresponse_parse.3 new file mode 100644 index 0000000000..bf35af6796 --- /dev/null +++ b/doc/man/lwres/lwres_gabnresponse_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnresponse_parse.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/doc/man/lwres/lwres_gabnresponse_render.3 b/doc/man/lwres/lwres_gabnresponse_render.3 new file mode 100644 index 0000000000..e18436181e --- /dev/null +++ b/doc/man/lwres/lwres_gabnresponse_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnresponse_render.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/doc/man/lwres/lwres_gai_strerror.3 b/doc/man/lwres/lwres_gai_strerror.3 new file mode 100644 index 0000000000..41a14aa28d --- /dev/null +++ b/doc/man/lwres/lwres_gai_strerror.3 @@ -0,0 +1,85 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gai_strerror.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GAI_STRERROR 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm gai_strerror +.Nd print suitable error string +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft char * +.Fo gai_strerror +.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. +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 +.It Dv EAI_AGAIN +temporary failure in name resolution +.It Dv EAI_BADFLAGS +invalid value for +.Li ai_flags +.It Dv EAI_FAIL +non-recoverable failure in name resolution +.It Dv EAI_FAMILY +.Li ai_family +not supported +.It Dv EAI_MEMORY +memory allocation failure +.It Dv EAI_NODATA +no address associated with hostname +.It Dv EAI_NONAME +hostname or servname not provided, or not known +.It Dv EAI_SERVICE +servname not supported for +.Li ai_socktype +.It Dv EAI_SOCKTYPE +.Li ai_socktype +not supported +.It Dv EAI_SYSTEM +system error returned in errno +.El +.Pp +.Li ai_flags , +.Li ai_family +and +.Li ai_socktype +are elements of the +.Dv "struct addrinfo" used by +.Fn lwres_getaddrinfo . +.Sh SEE ALSO +.Xr errno 2 , +.Xr perror 3 , +.Xr lwres_getaddrinfo 3 , +.Xr getaddrinfo 3 , +.Xr RFC2133 . diff --git a/doc/man/lwres/lwres_getaddrinfo.3 b/doc/man/lwres/lwres_getaddrinfo.3 new file mode 100644 index 0000000000..9ab605bb3e --- /dev/null +++ b/doc/man/lwres/lwres_getaddrinfo.3 @@ -0,0 +1,261 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getaddrinfo.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GETADDRINFO 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_getaddrinfo , +.Nm lwres_freeaddrinfo +.Nd socket address structure to host and service name +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft int +.Fo lwres_getaddrinfo +.Fa "const char *hostname" +.Fa "const char *servname" +.Fa "const struct addrinfo *hints" +.Fa "struct addrinfo **res" +.Fc +.Ft void +.Fo lwres_freeaddrinfo +.Fa "struct addrinfo *ai" +.Fc +.Pp +If the operating system does not provide a +.Dv "struct addrinfo" , +the following structure is used +.Bd -literal -offset indent +struct addrinfo { + int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ + int ai_family; /* PF_xxx */ + int ai_socktype; /* SOCK_xxx */ + int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ + size_t ai_addrlen; /* length of ai_addr */ + char *ai_canonname; /* canonical name for hostname */ + struct sockaddr *ai_addr; /* binary address */ + struct addrinfo *ai_next; /* next structure in linked list */ +}; +.Ed +.Sh DESCRIPTION +.Pp +.Fn lwres_getaddrinfo +is used to get a list of IP addresses and port numbers for host +.Fa hostname +and +.Fa servname . +The function is the lightweight resolver's implementation of +.Fn getaddrinfo +as defined in RFC2133. +.Fa hostname +and +.Fa servname +arguments 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. +.Fa servname +is either a decimal port number or a service name as listed in +.Pa /etc/services . +.Pp +.Fa hints +is an optional pointer to a +.Dv "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 +.Fa *hints : +.Bl -tag -width ai_socktyp -offset indent -compact +.It Li ai_family +the protocol family that should be used. +When +.Li ai_family +is set to +.Dv PF_UNSPEC , +it means the caller will accept any protocol family supported by the +operating system. +.It Dv ai_socktype +denotes the type of socket - +.Dv SOCK_STREAM , +.Dv SOCK_DGRAM +or +.Dv SOCK_RAW +- that is wanted. +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. +If +.Li ai_protocol +is zero the caller will accept any protocol. +.It Li ai_flags +sets some flag bits. +If the +.Dv AI_CANONNAME +bit is set, a successful call to +.Fn lwres_getaddrinfo +will return a a null-terminated string containing the canonical name +of the specified hostname in +.Li ai_canonname +of the first +.Dv addrinfo +structure returned. +Setting the +.Dv AI_PASSIVE +bit indicates that the returned socket address structure is intended +for used in a call to +.Xr bind 2 . +In this case, if the hostname argument is a +.Dv NULL +pointer, then the IP address portion of the socket +address structure will be set to +.Dv INADDR_ANY +for an IPv4 address or +.Dv IN6ADDR_ANY_INIT +for an IPv6 address. +.Pp +When +.Li ai_flags +does not set the +.Dv AI_PASSIVE +bit, the returned socket address structure will be ready +for use in a call to +.Xr connect 2 +for a connection-oriented protocol or +.Xr connect 2 , +.Xr sendto 2 , +or +.Xr sendmsg 2 +if a connectionless protocol was chosen. +The IP address portion of the socket address structure will be +set to the loopback address if +.Fa hostname +is a +.Dv NULL +pointer and +.Dv AI_PASSIVE +is not set in +.Li ai_flags . +.Pp +If +.Li ai_flags +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. +.El +.Pp +All other elements of the +.Dv "struct addrinfo" +passed via +.Fa arg +must be zero. +.Pp +If +.Fa arg +is not supplied, a +.Dv NULL +pointer should be given for this argument. +It will be treated as if the caller provided an +.Dv "struct addrinfo" +structure initialized to zero with +.Li ai_family set to +.Li PF_UNSPEC . +.Pp +After a successful call to +.Fn lwres_getaddrinfo , +.Fa *res +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 +the +.Li ai_next +pointer, until a +.Dv NULL +pointer is encountered. +The three members +.Li ai_family , +ai_socktype, +and +.Li ai_protocol +in each +returned +.Dv addrinfo +structure contain the corresponding arguments for a call to +.Xr socket 2 . +For each +.Dv addrinfo +structure in the list, the +.Li ai_addr +member points to a filled-in socket address structure of length +.Li ai_addrlen . +.Pp +All of the information returned by +.Fn lwres_getaddrinfo +is dynamically allocated: the addrinfo structures, and the socket +address structures and canonical host name strings pointed to by the +.Li addrinfo structures. +Memory allocated for the dynamically allocated structures created by +a successful call to +.Fn lwres_getaddrinfo +is released by +.Fn lwres_freeaddrinfo . +.Fa ai +is a pointer to a +.Dv "struct addrinfo" created by a call to +.Fn lwres_getaddrinfo . +.Sh RETURN VALUES +.Fn lwres_getaddrinfo +returns zero on success or one of the error codes listed in +.Xr gai_strerror 3 +if an error occurs. +If both +.Fa hostname +and +.Fa servname +are +.Dv NULL +.Fn lwres_getaddrinfo +returns +.Er EAI_NONAME . +.Sh SEE ALSO +.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 connect 2 , +.Xr sendto 2 , +.Xr sendmsg 2 , +.Xr socket 2 . diff --git a/doc/man/lwres/lwres_getaddrsbyname.3 b/doc/man/lwres/lwres_getaddrsbyname.3 new file mode 100644 index 0000000000..966fb08baa --- /dev/null +++ b/doc/man/lwres/lwres_getaddrsbyname.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getaddrsbyname.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_resutil.3 diff --git a/doc/man/lwres/lwres_gethostbyaddr.3 b/doc/man/lwres/lwres_gethostbyaddr.3 new file mode 100644 index 0000000000..16ea1dbf73 --- /dev/null +++ b/doc/man/lwres/lwres_gethostbyaddr.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyaddr.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_gethostbyaddr_r.3 b/doc/man/lwres/lwres_gethostbyaddr_r.3 new file mode 100644 index 0000000000..310b99d5dc --- /dev/null +++ b/doc/man/lwres/lwres_gethostbyaddr_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyaddr_r.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_gethostbyname.3 b/doc/man/lwres/lwres_gethostbyname.3 new file mode 100644 index 0000000000..4df07f3084 --- /dev/null +++ b/doc/man/lwres/lwres_gethostbyname.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyname.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_gethostbyname2.3 b/doc/man/lwres/lwres_gethostbyname2.3 new file mode 100644 index 0000000000..21d9510c28 --- /dev/null +++ b/doc/man/lwres/lwres_gethostbyname2.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyname2.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_gethostbyname_r.3 b/doc/man/lwres/lwres_gethostbyname_r.3 new file mode 100644 index 0000000000..278899488d --- /dev/null +++ b/doc/man/lwres/lwres_gethostbyname_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyname_r.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_gethostent.3 b/doc/man/lwres/lwres_gethostent.3 new file mode 100644 index 0000000000..ee7837d5c5 --- /dev/null +++ b/doc/man/lwres/lwres_gethostent.3 @@ -0,0 +1,406 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostent.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GETHOSTENT 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_gethostbyname , +.Nm lwres_gethostbyname2 , +.Nm lwres_gethostbyaddr , +.Nm lwres_gethostent , +.Nm lwres_sethostent , +.Nm lwres_endhostent , +.Nm lwres_gethostbyname_r , +.Nm lwres_gethostbyaddr_r , +.Nm lwres_gethostent_r , +.Nm lwres_sethostent_r , +.Nm lwres_endhostent_r +.Nd lightweight resolver get network host entry +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft struct hostent * +.Fo lwres_gethostbyname +.Fa "const char *name" +.Fc +.Ft struct hostent * +.Fo lwres_gethostbyname2 +.Fa "const char *name" +.Fa "int af" +.Fc +.Ft struct hostent * +.Fo lwres_gethostbyaddr +.Fa "const char *addr" +.Fa "int len" +.Fa "int type" +.Fc +.Ft struct hostent * +.Fo lwres_gethostent +.Fa "void" +.Fc +.Ft void +.Fo lwres_sethostent +.Fa "int stayopen" +.Fc +.Ft void +.Fo lwres_endhostent +.Fa "void" +.Fc +.Ft struct hostent * +.Fo lwres_gethostbyname_r +.Fa "const char *name" +.Fa "struct hostent *resbuf" +.Fa "char *buf" +.Fa "int buflen" +.Fa "int *error" +.Fc +.Ft struct hostent * +.Fo lwres_gethostbyaddr_r +.Fa "const char *addr" +.Fa "int len" +.Fa "int type" +.Fa "struct hostent *resbuf" +.Fa "char *buf" +.Fa "int buflen" +.Fa "int *error" +.Fc +.Ft struct hostent * +.Fo lwres_gethostent_r +.Fa "struct hostent *resbuf" +.Fa "char *buf" +.Fa "int buflen" +.Fa "int *error" +.Fc +.Ft void +.Fo lwres_sethostent_r +.Fa "int stayopen" +.Fc +.Ft void +.Fo lwres_endhostent_r +.Fa "void" +.Fc +.Sh DESCRIPTION +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 +.Xr gethostent 3 +functions provided by as part of the standard system software. +They use a +.Dv "struct hostent" +which is usually defined in +.Pa namedb.h . +.Bd -literal +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +.Ed +.Pp +The members of this structure are: +.Bl -tag -width h_addr_list +.It Li h_name +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 - +.Dv PF_INET +or +.Dv PF_INET6 . +.It Li h_length +The length of the address in bytes. +.It Li h_addr_list +A +.Dv NULL +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_gethostent , +.Fn lwres_sethostent , +.Fn lwres_endhostent , +.Fn lwres_gethostent_r , +.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 . +.Pp +.Fn lwres_gethostbyname +and +.Fn lwres_gethostbyname2 +lookup the hostname +.Fa name . +.Fn lwres_gethostbyname +always looks for an IPv4 address while +.Fn lwres_gethostbyname2 +looks for an address of protocol family +.Fa af : +either +.Dv PF_INET +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. +.Dv NULL +is returned if the lookups by +.Fn lwres_gethostbyname +or +.Fn lwres_gethostbyname2 +fail. +.Pp +Reverse lookups of addresses are performed by +.Fn lwres_gethostbyaddr . +.Fa addr +is an address of length +.Fa len +bytes and protocol family +.Fa type - +.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 +.Fa *error . +.Fa resbuf +is a pointer to a +.Dv "struct hostent" +which is initialised by a successful call to +.Fn lwres_gethostbyname_r . +.Fa buf +is a buffer of length +.Fa len +bytes which is used to store the +.Li h_name , +.Li h_aliases , +and +.Li h_addr_list +elements of the +.Dv "struct hostent" +returned in +.Fa resbuf . +Successful calls to +.Fn lwres_gethostbyname_r +return +.Fa resbuf , +which is a pointer to the +.Fn "struct hostent" +it created. +.Pp +.Fn lwres_gethostbyaddr_r +is a thread-safe function that performs a reverse lookup of address +.Fa addr +which is +.Fa len +bytes long +and is of protocol family +.Fa type - +.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 +.Fa *error . +Like +The other function parameters are identical to those in +.Fn lwres_gethostbyname_r . +.Fa resbuf +is a pointer to a +.Dv "struct hostent" +which is initialised by a successful call to +.Fn lwres_gethostbyaddr_r . +.Fa buf +is a buffer of length +.Fa len +bytes which is used to store the +.Li h_name , +.Li h_aliases , +and +.Li h_addr_list +elements of the +.Dv "struct hostent" +returned in +.Fa resbuf . +Successful calls to +.Fn lwres_gethostbyaddr_r +return +.Fa resbuf , +which is a pointer to the +.Fn "struct hostent" +it created. +.Sh RETURN VALUES +.Pp +The functions +.Fn lwres_gethostbyname , +.Fn lwres_gethostbyname2 , +.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 +.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: +.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 +.It Li NO_ADDRESS +no address, so look for MX record +.El +.Xr lwres_hstrerror 3 +translates these error codes to suitable error messages. +.Pp +.Fn lwres_gethostent +and +.Fn lwres_gethostent_r +always return +.Dv NULL . +.Pp +Successful calls to +.Fn lwres_gethostbyname_r +and +.Fn lwres_gethostbyaddr_r +return +.Fa resbuf , +a pointer to the +.Dv "struct hostent" +that was initialised by these functions. +They return +.Dv NULL +if the lookups fail +or if +.Fa buf +was too small to hold the list of addresses and names referenced by +the +.Li h_name , +.Li h_aliases , +and +.Li h_addr_list +elements of the +.Dv "struct hostent" . +If +.Fa buf +was too small, both +.Fn lwres_gethostbyname_r +and +.Fn lwres_gethostbyaddr_r +set the global variable +.DV errno +to +.Er ERANGE . +.Sh SEE ALSO +.Xr gethostent 3 , +.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 +Thread-safe versions for name and address lookup are provided by +.Fn lwres_gethostbyname_r , +and +.Fn lwres_gethostbyaddr_r +respectively. +.Pp +Although the above functions can be considered as drop-in replacements +for their equivalents in the system software, there are limitations. +The functions that are documented here only use the BIND9 lighweight +resolver daemon +That implies that they only use the DNS for host and address lookups. +Therefore these functions do not perform lookups in +.Pa /etc/hosts +or in +.Dv NIS/YP +or +.Dv NIS+ +maps which could be supported by the operating system's +.Xr gethostent 3 +functions. diff --git a/doc/man/lwres/lwres_gethostent_r.3 b/doc/man/lwres/lwres_gethostent_r.3 new file mode 100644 index 0000000000..dded33aa6a --- /dev/null +++ b/doc/man/lwres/lwres_gethostent_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostent_r.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_getipnode.3 b/doc/man/lwres/lwres_getipnode.3 new file mode 100644 index 0000000000..9da2263476 --- /dev/null +++ b/doc/man/lwres/lwres_getipnode.3 @@ -0,0 +1,231 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getipnode.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GETIPNODE 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_getipnodebyname , +.Nm lwres_getipnodebyaddr , +.Nm lwres_freehostent +.Nd lookup functions for the lightweight resolver +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft struct hostent * +.Fo lwres_getipnodebyname +.Fa "const char *name" +.Fa "int af" +.Fa "int flags" +.Fa "int *error_num" +.Fc +.Ft struct hostent * +.Fo lwres_getipnodebyaddr +.Fa "const void *src" +.Fa "size_t len" +.Fa "int af" +.Fa "int *error_num" +.Fc +.Ft void +.Fo lwres_freehostent +.Fa "struct hostent *he" +.Fc +.Sh DESCRIPTION +These functions use a +.Dv "struct hostent" +which is usually defined in +.Pa namedb.h . +.Bd -literal +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +.Ed +.Pp +The members of this structure are: +.Bl -tag -width h_addr_list +.It Li h_name +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 - +.Dv PF_INET +or +.Dv PF_INET6 . +.It Li h_length +The length of the address in bytes. +.It Li h_addr_list +A +.Dv NULL +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 . +The +.Fa flags +parameter sets bits that indicate how IPv6 and IPv4 addresses +should presented. +The value of those flags are: +.Bl -tag -width AI_ADDRCONFIG +.It Li AI_V4MAPPED +return an IPv4 address mapped to an IPv6 address +.It Li AI_ALL +return all possible addresses +.It Li AI_ADDRCONFIG +only return an IPv6 or IPv4 address if here is an active network +interface of that type. +.It Li AI_DEFAULT +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 +of address +.Fa src +which is +.Fa len +bytes long. +.Fa af +denotes the protocol family: +.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 +the +.Dv "struct hostent" +pointer +.Fa he . +Any memory allocated for the +.Li h_name , +.Li h_addr_list +and +.Li h_aliases +is freed, as is the memory for the +.Dv hostent +structure itself. +.Sh RETURN VALUES +If an error occurs, +.Fn lwres_getipnodebyname +and +.Fn lwres_getipnodebyaddr +set +.Fa *error_num +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 . +.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 +.It Li NO_ADDRESS +no address, so look for MX record +.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 lwres_hstrerror 3 . + diff --git a/doc/man/lwres/lwres_getipnodebyaddr.3 b/doc/man/lwres/lwres_getipnodebyaddr.3 new file mode 100644 index 0000000000..c77c430d74 --- /dev/null +++ b/doc/man/lwres/lwres_getipnodebyaddr.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getipnodebyaddr.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_getipnode.3 diff --git a/doc/man/lwres/lwres_getipnodebyname.3 b/doc/man/lwres/lwres_getipnodebyname.3 new file mode 100644 index 0000000000..2583c19805 --- /dev/null +++ b/doc/man/lwres/lwres_getipnodebyname.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getipnodebyname.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_getipnode.3 diff --git a/doc/man/lwres/lwres_getnamebyaddr.3 b/doc/man/lwres/lwres_getnamebyaddr.3 new file mode 100644 index 0000000000..43f6cbb11b --- /dev/null +++ b/doc/man/lwres/lwres_getnamebyaddr.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getnamebyaddr.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_resutil.3 diff --git a/doc/man/lwres/lwres_getnameinfo.3 b/doc/man/lwres/lwres_getnameinfo.3 new file mode 100644 index 0000000000..64fa126a29 --- /dev/null +++ b/doc/man/lwres/lwres_getnameinfo.3 @@ -0,0 +1,145 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getnameinfo.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GETNAMEINFO 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_getnameinfo +.Nd lightweight resolver socket address structure to hostname and service name +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft int +.Fo lwres_getnameinfo +.Fa "const struct sockaddr *sa" +.Fa "size_t salen" +.Fa "char *host" +.Fa "size_t hostlen" +.Fa "char *serv" +.Fa "size_t servlen" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Pp +This function is equivalent to the +.Xr getnameinfo 3 +function defined in RFC2133. +.Fn lwres_getnameinfo +returns the hostname for the +.Dv "struct sockaddr" +.Fa sa +which is +.Fa salen +bytes long. +The hostname is of length +.Fa hostlen +and is returned via +.Fa *host. +The maximum length of the hostname is +1025 bytes: +.Li NI_MAXHOST . +.Pp +The name of the service associated with the port number in +.Fa sa +is returned in +.Fa *serv. +It is +.Fa servlen +bytes long. +The maximum length of the service name is +.Li NI_MAXSERV +- 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. +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. +.It Li NI_NAMEREQ +a name is required. If the hostname cannot be found in the DNS and +this flag is set, an error - +.Er ENI_NOHOSTNAME +- is returned. +.It Li NI_NUMERICSERV +service name is returned as a digit string representing the port number. +.It Li NI_DGRAM +the service uses a datagram transport protocol +.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 wres_getnameinfo +returns 0 on success or a non-zero error code if an error occurs. +The error codes are: +.Bl -tag -width ENI_NOSERVNAME +.It Li ENI_NOSOCKET +there was no socket in +.Fa sa +\fBBUT ENI_NOSOCKET IS ZERO!!!!\fP +.It Li ENI_NOSERVNAME +no service name was found +.It Li ENI_NOHOSTNAME +no hostname was found +.It Li ENI_MEMORY +memory could not be allocated +.It Li ENI_SYSTEM +a system error occurred +.It Li ENI_FAMILY +an unsupported protocol family was requested +.It Li ENI_SALEN +.Fa salen +is the wrong number of bytes for the address in +.Fa sa . +.Sh SEE ALSO +.Xr 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 . diff --git a/doc/man/lwres/lwres_gnba.3 b/doc/man/lwres/lwres_gnba.3 new file mode 100644 index 0000000000..8f4279870c --- /dev/null +++ b/doc/man/lwres/lwres_gnba.3 @@ -0,0 +1,201 @@ +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnba.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GNBA 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_gnbarequest_render , +.Nm lwres_gnbaresponse_render , +.Nm lwres_gnbarequest_parse , +.Nm lwres_gnbaresponse_parse , +.Nm lwres_gnbaresponse_free , +.Nm lwres_gnbarequest_free +.Nd lightweight resolver getnamebyaddress functions +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_gnbarequest_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_gnbarequest_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_gnbaresponse_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_gnbaresponse_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_gnbarequest_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_gnbarequest_t **structp" +.Fc +.Ft lwres_result_t +.Fo lwres_gnbaresponse_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_gnbaresponse_t **structp" +.Fc +.Ft void +.Fo lwres_gnbaresponse_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_gnbaresponse_t **structp" +.Fc +.Ft void +.Fo lwres_gnbarequest_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_gnbarequest_t **structp" +.Fc +.Sh DESCRIPTION +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. +.Pp +There are four main functions for the getnamebyaddr opcode. +One render function converts a getnamebyaddr request structure - +.Dv lwres_gnbarequest_t - +to the lighweight resolver's canonical format. +It is complemented by a parse function that converts a packet in this +canonical format to a getnamebyaddr request structure. +Another render function converts the getnamebyaddr response structure - +.Dv lwres_gnbaresponse_t +to the canonical format. +This is complemented by a parse function which converts a packet in +canonical format to a getnamebyaddr response structure. +.Pp +These structures are defined in +.Pa lwres/lwres.h . +They are shown below. +.Bd -literal -offset indent +#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U + +typedef struct { + lwres_uint32_t flags; + lwres_addr_t addr; +} lwres_gnbarequest_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + void *base; + size_t baselen; +} lwres_gnbaresponse_t; +.Ed +.Pp +.Fn lwres_gnbarequest_render +uses resolver context +.Fa ctx +to convert getnamebyaddr request structure +.Fa req +to canonical format. +The packet header structure +.Fa pkt +is initialised and transferred to +buffer +.Fa b . +The contents of +.Fa *req +are then appended to the buffer in canonical format. +.Fn lwres_gnbaresponse_render +performs the same task, except it converts a getnamebyaddr response structure +.Dv lwres_gnbaresponse_t +to the lightweight resolver's canonical format. +.Pp +.Fn lwres_gnbarequest_parse +uses context +.Fa ctx +to convert the contents of packet +.Fa pkt +to a +.Dv lwres_gnbarequest_t +structure. +Buffer +.Fa b +provides space to be used for storing this structure. +When the function succeeds, the resulting +.Dv lwres_gnbarequest_t +is made available through +.Fa *structp . +.Fn lwres_gnbaresponse_parse +offers the same semantics as +.Fn lwres_gnbarequest_parse +except it yields a +.Dv lwres_gnbaresponse_t +structure. +.Pp +.Fn lwres_gnbaresponse_free +and +.Fn lwres_gnbarequest_free +release the memory in resolver context +.Fa ctx +that was allocated to the +.Dv lwres_gnbaresponse_t +or +.Dv lwres_gnbarequest_t +structures referenced via +.Fa structp . +Any memory associated with ancillary buffers and strings for those +structures is also discarded. +.Sh RETURN VALUES +The getnamebyaddr opcode functions +.Fn lwres_gnbarequest_render , +.Fn lwres_gnbaresponse_render +.Fn lwres_gnbarequest_parse +and +.Fn lwres_gnbaresponse_parse +all return +.Er LWRES_R_SUCCESS +on success. +They return +.Er LWRES_R_NOMEMORY +if memory allocation fails. +.Er LWRES_R_UNEXPECTEDEND +is returned if the available space in the buffer +.Fa b +is too small to accommodate the packet header or the +.Dv lwres_gnbarequest_t +and +.Dv lwres_gnbaresponse_t +structures. +.Fn lwres_gnbarequest_parse +and +.Fn lwres_gnbaresponse_parse +will return +.Er LWRES_R_UNEXPECTEDEND +if the buffer is not empty after decoding the received packet. +These functions will return +.Er LWRES_R_FAILURE +if +.Li pktflags +in the packet header structure +.Dv lwres_lwpacket_t +indicate that the packet is not a response to an earlier query. +.Sh SEE ALSO +.Xr lwres_packet 3 diff --git a/doc/man/lwres/lwres_gnbarequest_free.3 b/doc/man/lwres/lwres_gnbarequest_free.3 new file mode 100644 index 0000000000..14ca78b3ee --- /dev/null +++ b/doc/man/lwres/lwres_gnbarequest_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbarequest_free.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/doc/man/lwres/lwres_gnbarequest_parse.3 b/doc/man/lwres/lwres_gnbarequest_parse.3 new file mode 100644 index 0000000000..3f0821a198 --- /dev/null +++ b/doc/man/lwres/lwres_gnbarequest_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbarequest_parse.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/doc/man/lwres/lwres_gnbarequest_render.3 b/doc/man/lwres/lwres_gnbarequest_render.3 new file mode 100644 index 0000000000..b952905a17 --- /dev/null +++ b/doc/man/lwres/lwres_gnbarequest_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbarequest_render.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/doc/man/lwres/lwres_gnbaresponse_free.3 b/doc/man/lwres/lwres_gnbaresponse_free.3 new file mode 100644 index 0000000000..5fee56d5fd --- /dev/null +++ b/doc/man/lwres/lwres_gnbaresponse_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbaresponse_free.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/doc/man/lwres/lwres_gnbaresponse_parse.3 b/doc/man/lwres/lwres_gnbaresponse_parse.3 new file mode 100644 index 0000000000..b75ac1780a --- /dev/null +++ b/doc/man/lwres/lwres_gnbaresponse_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbaresponse_parse.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/doc/man/lwres/lwres_gnbaresponse_render.3 b/doc/man/lwres/lwres_gnbaresponse_render.3 new file mode 100644 index 0000000000..b518bf849e --- /dev/null +++ b/doc/man/lwres/lwres_gnbaresponse_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbaresponse_render.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/doc/man/lwres/lwres_herror.3 b/doc/man/lwres/lwres_herror.3 new file mode 100644 index 0000000000..83d69a4ad1 --- /dev/null +++ b/doc/man/lwres/lwres_herror.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_herror.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.so lwres_hstrerror.3 diff --git a/doc/man/lwres/lwres_hstrerror.3 b/doc/man/lwres/lwres_hstrerror.3 new file mode 100644 index 0000000000..df3592d1da --- /dev/null +++ b/doc/man/lwres/lwres_hstrerror.3 @@ -0,0 +1,72 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_hstrerror.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_ERROR 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_herror , +.Nm lwres_hstrerror +.Nd lightweight resolver error message generation +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft void +.Fo lwres_herror +.Fa "const char *s" +.Fc +.Ft const char * +.Fo lwres_hstrerror +.Fa "int err" +.Fc +.Sh DESCRIPTION +.Fn lwres_herror +prints the string +.Fa s +on +.Dv stderr +followed by the string generated by +.Fn lwres_hstrerror +for the error code stored in the global variable +.Li lwres_h_errno . +.Pp +.Fn lwres_hstrerror +returns an appropriate string for the error code gievn by +.Fa err . +The values of the error codes and messages are as follows: +.Bl -tag -width HOST_NOT_FOUND +.It Li NETDB_SUCCESS +\*qResolver Error 0 (no error)\*q +.It Li HOST_NOT_FOUND +\*qUnknown host\*q +.It Li TRY_AGAIN +\*qHost name lookup failure\*q +.It Li NO_RECOVERY +\*qUnknown server error\*q +.It Li NO_DATA +\*qNo address associated with name\*q +.Sh RETURN VALUES +The string \*qUnknown resolver error\*q is returned by +.Fn lwres_hstrerror +when the value of +.Li lwres_h_errno +is not a valid error code. +.Sh SEE ALSO +.Xr herror 3 , +.Xr lwres_hstrerror 3 . diff --git a/doc/man/lwres/lwres_inetaton.3 b/doc/man/lwres/lwres_inetaton.3 new file mode 100644 index 0000000000..918b0995e9 --- /dev/null +++ b/doc/man/lwres/lwres_inetaton.3 @@ -0,0 +1,97 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_inetaton.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_INETATON 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_net_aton +.Nd lightweight resolver IPv4 address manipulation +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd +.Ft int +.Fo lwres_net_aton +.Fa "const char *cp" +.Fa "struct in_addr *addr" +.Fc +.Sh DESCRIPTION +.Fn lwres_net_aton +checks that +.Fa cp +is a valid ASCII representation of an IPv4 address and optionally converts +it to a binary address in network byte order. +If +.Fa addr +is not +.Dv NULL, +.Li addr->s_addr +is set to the binary representation of address given by +.Fa cp +if it was a valid string. +This function supersedes +.Fn inet_addr +whose return value cannot distinguish between failure and a local +broadcast address. +.Pp +.Fa cp +should be a string in conventional dot notation of the form: +.Bd -literal -offset indent +a +a.b +a.b.c +a.b.c.d +.Ed +.Pp +Each part of the address can be represented in octal, decimal or +hexadeximal using the standard C notation: a leading 0 implies octal; +a leading 0x or 0X implies hex; a decimal number is assumed otherwise. +.Pp +If a one-part address is given, its value is placed in the network +address without any byte rearrangement. +When a two-part address - +.Li a.b - +is supplied, the last part is considered a 24-bit quantity and placed +in the bottom 3 bytes of +.Li addr->s_addr . +The first part is placed in the top byte of the address. +A three-part address - +.Li a.b.c - +is treated as if the last part was a 16-bit quantity. +The first two parts - +.Li a.b - +is put in the top 2 bytes and the last part in the low-end 2 bytes of +.Li addr->s_addr . +When a four-part address is supplied in +.Fa cp , +each part is treated as a byte of data and assigned to the four bytes +of an Internet address. +In all four cases, the internet address in +.Li addr->s_addr +is stored in network byte order (big-endian) where the bytes are +ordered from left to right: i.e. 0, 1, 2, 3. +.Sh RETURN VALUES +The function returns 1 if +.Fa cp +was successfully interpreted as an IPv4 address or 0 +if it was an invalid string. +.Sh SEE ALSO +.Xr inet_aton 3 , +.Xr inet_addr 3 . diff --git a/doc/man/lwres/lwres_inetntop.3 b/doc/man/lwres/lwres_inetntop.3 new file mode 100644 index 0000000000..4e9b61aedc --- /dev/null +++ b/doc/man/lwres/lwres_inetntop.3 @@ -0,0 +1,72 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_inetntop.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_INETNTOP 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_net_ntop +.Nd lightweight resolver IP address presentation +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft const char * +.Fo lwres_net_ntop +.Fa "int af" +.Fa "const void *src" +.Fa "char *dst" +.Fa "size_t size" +.Fc +.Sh DESCRIPTION +.Fn lwres_net_ntop +converts an IP address of protocol family +.Fa af +- IPv4 or IPv6 - at location +.Fa 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. +.Pp +The generated string is copied to +.Fa dst +provided +.Fa size +indicates it is long enough to store the ASCII representation +of the address. +.Sh RETURN VALUES +.Pp +If successful, the function returns +.Fa dst : +a pointer to a string containing +the presentation format of the address. +.Fn lwres_net_ntop +returns +.Dv NULL +and sets the global variable +.Li errno +to +.Er EAFNOSUPPORT +if the protocol family given in +.Fa af +is not supported. +.Sh SEE ALSO +.Xr RFC1884 , +.Xr inet_ntop 3 , +.Xr errno 3 . diff --git a/doc/man/lwres/lwres_inetpton.3 b/doc/man/lwres/lwres_inetpton.3 new file mode 100644 index 0000000000..d7e810981c --- /dev/null +++ b/doc/man/lwres/lwres_inetpton.3 @@ -0,0 +1,64 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_inetpton.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_INETPTON 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_net_pton +.Nd lightweight resolver IP address conversion +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft int +.Fo lwres_net_pton +.Fa "int af" +.Fa "const char *src" +.Fa "void *dst" +.Fc +.Sh DESCRIPTION +.Fn lwres_net_pton +converts the presentation format of an IP address +.Fa src +to its representation in network format. +.Fa af +indicates the protocol family for the address +.Dv PF_INET +or +.Dv PF_INET6 +and +.Fa src +is either a dotted decimal string for an IPv4 address or +a string in colon notation if it represents an IPv6 address. +RFC1884 defines the text notation to represent IPv6 addresses. +.Sh RETURN VALUES +.Fn lwres_net_pton +returns 1 if address +.Fa src +was valid for protocol family +.Fa af . +The network representation of the address is returned in +.Fa *dst . +Zero is returned if the address was invalid and -1 is returned if some +other error occurred. +.Fa *dst +is not altered for either of these errors. +.Sh SEE ALSO +.Xr inet_pton 3 , +.Xr RFC1884 . diff --git a/doc/man/lwres/lwres_lwpacket_parseheader.3 b/doc/man/lwres/lwres_lwpacket_parseheader.3 new file mode 100644 index 0000000000..0301fc8196 --- /dev/null +++ b/doc/man/lwres/lwres_lwpacket_parseheader.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_lwpacket_parseheader.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_packet.3 diff --git a/doc/man/lwres/lwres_lwpacket_renderheader.3 b/doc/man/lwres/lwres_lwpacket_renderheader.3 new file mode 100644 index 0000000000..252580ad01 --- /dev/null +++ b/doc/man/lwres/lwres_lwpacket_renderheader.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_lwpacket_renderheader.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_packet.3 diff --git a/doc/man/lwres/lwres_net_aton.3 b/doc/man/lwres/lwres_net_aton.3 new file mode 100644 index 0000000000..92f2b8a052 --- /dev/null +++ b/doc/man/lwres/lwres_net_aton.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_net_aton.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_inetaton.3 diff --git a/doc/man/lwres/lwres_net_ntop.3 b/doc/man/lwres/lwres_net_ntop.3 new file mode 100644 index 0000000000..5278ce91fb --- /dev/null +++ b/doc/man/lwres/lwres_net_ntop.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_net_ntop.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_inetntop.3 diff --git a/doc/man/lwres/lwres_net_pton.3 b/doc/man/lwres/lwres_net_pton.3 new file mode 100644 index 0000000000..1424f2c59e --- /dev/null +++ b/doc/man/lwres/lwres_net_pton.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_net_pton.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_inetpton.3 diff --git a/doc/man/lwres/lwres_noop.3 b/doc/man/lwres/lwres_noop.3 new file mode 100644 index 0000000000..4353dfd2d8 --- /dev/null +++ b/doc/man/lwres/lwres_noop.3 @@ -0,0 +1,199 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_noop.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_NOOP 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_nooprequest_render , +.Nm lwres_noopresponse_render , +.Nm lwres_nooprequest_parse , +.Nm lwres_noopresponse_parse , +.Nm lwres_noopresponse_free , +.Nm lwres_nooprequest_free +.Nd lightweight resolver no-op functions +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_nooprequest_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_nooprequest_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_noopresponse_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_noopresponse_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_nooprequest_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_nooprequest_t **structp" +.Fc +.Ft lwres_result_t +.Fo lwres_noopresponse_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_noopresponse_t **structp" +.Fc +.Ft void +.Fo lwres_noopresponse_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_noopresponse_t **structp" +.Fc +.Ft void +.Fo lwres_nooprequest_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_nooprequest_t **structp" +.Fc +.Sh DESCRIPTION +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. +The opcode is intended to allow a client to determine if the server is +operational or not. +.Pp +There are four main functions for the no-op opcode. +One render function converts a no-op request structure - +.Dv lwres_nooprequest_t - +to the lighweight resolver's canonical format. +It is complemented by a parse function that converts a packet in this +canonical format to a no-op request structure. +Another render function converts the no-op response structure - +.Dv lwres_noopresponse_t +to the canonical format. +This is complemented by a parse function which converts a packet in +canonical format to a no-op response structure. +.Pp +These structures are defined in +.Pa lwres/lwres.h . +They are shown below. +.Bd -literal -offset indent +#define LWRES_OPCODE_NOOP 0x00000000U + +typedef struct { + lwres_uint16_t datalength; + unsigned char *data; +} lwres_nooprequest_t; + +typedef struct { + lwres_uint16_t datalength; + unsigned char *data; +} lwres_noopresponse_t; +.Ed +Although the structures have different types, they are identical. +This is because the no-op opcode simply echos whatever data was sent: +the response is therefore identical to the request. +.Pp +.Fn lwres_nooprequest_render +uses resolver context +.Fa ctx +to convert no-op request structure +.Fa req +to canonical format. +The packet header structure +.Fa pkt +is initialised and transferred to +buffer +.Fa b . +The contents of +.Fa *req +are then appended to the buffer in canonical format. +.Fn lwres_noopresponse_render +performs the same task, except it converts a no-op response structure +.Dv lwres_noopresponse_t +to the lightweight resolver's canonical format. +.Pp +.Fn lwres_nooprequest_parse +uses context +.Fa ctx +to convert the contents of packet +.Fa pkt +to a +.Dv lwres_nooprequest_t +structure. +Buffer +.Fa b +provides space to be used for storing this structure. +When the function succeeds, the resulting +.Dv lwres_nooprequest_t +is made available through +.Fa *structp . +.Fn lwres_noopresponse_parse +offers the same semantics as +.Fn lwres_nooprequest_parse +except it yields a +.Dv lwres_noopresponse_t +structure. +.Pp +.Fn lwres_noopresponse_free +and +.Fn lwres_nooprequest_free +release the memory in resolver context +.Fa ctx +that was allocated to the +.Dv lwres_noopresponse_t +or +.Dv lwres_nooprequest_t +structures referenced via +.Fa structp . +.Sh RETURN VALUES +The no-op opcode functions +.Fn lwres_nooprequest_render , +.Fn lwres_noopresponse_render +.Fn lwres_nooprequest_parse +and +.Fn lwres_noopresponse_parse +all return +.Er LWRES_R_SUCCESS +on success. +They return +.Er LWRES_R_NOMEMORY +if memory allocation fails. +.Er LWRES_R_UNEXPECTEDEND +is returned if the available space in the buffer +.Fa b +is too small to accommodate the packet header or the +.Dv lwres_nooprequest_t +and +.Dv lwres_noopresponse_t +structures. +.Fn lwres_nooprequest_parse +and +.Fn lwres_noopresponse_parse +will return +.Er LWRES_R_UNEXPECTEDEND +if the buffer is not empty after decoding the received packet. +These functions will return +.Er LWRES_R_FAILURE +if +.Li pktflags +in the packet header structure +.Dv lwres_lwpacket_t +indicate that the packet is not a response to an earlier query. +.Sh SEE ALSO +.Xr lwres_packet 3 diff --git a/doc/man/lwres/lwres_nooprequest_free.3 b/doc/man/lwres/lwres_nooprequest_free.3 new file mode 100644 index 0000000000..fc29a3265f --- /dev/null +++ b/doc/man/lwres/lwres_nooprequest_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_nooprequest_free.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/doc/man/lwres/lwres_nooprequest_parse.3 b/doc/man/lwres/lwres_nooprequest_parse.3 new file mode 100644 index 0000000000..5257e15f57 --- /dev/null +++ b/doc/man/lwres/lwres_nooprequest_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_nooprequest_parse.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/doc/man/lwres/lwres_nooprequest_render.3 b/doc/man/lwres/lwres_nooprequest_render.3 new file mode 100644 index 0000000000..9cd9d97cf2 --- /dev/null +++ b/doc/man/lwres/lwres_nooprequest_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_nooprequest_render.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/doc/man/lwres/lwres_noopresponse_free.3 b/doc/man/lwres/lwres_noopresponse_free.3 new file mode 100644 index 0000000000..54c2ca880e --- /dev/null +++ b/doc/man/lwres/lwres_noopresponse_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_noopresponse_free.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/doc/man/lwres/lwres_noopresponse_parse.3 b/doc/man/lwres/lwres_noopresponse_parse.3 new file mode 100644 index 0000000000..63693ef464 --- /dev/null +++ b/doc/man/lwres/lwres_noopresponse_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_noopresponse_parse.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/doc/man/lwres/lwres_noopresponse_render.3 b/doc/man/lwres/lwres_noopresponse_render.3 new file mode 100644 index 0000000000..e46c8a5db6 --- /dev/null +++ b/doc/man/lwres/lwres_noopresponse_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_noopresponse_render.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/doc/man/lwres/lwres_packet.3 b/doc/man/lwres/lwres_packet.3 new file mode 100644 index 0000000000..50e596e9ed --- /dev/null +++ b/doc/man/lwres/lwres_packet.3 @@ -0,0 +1,146 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_packet.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_PACKET 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_lwpacket_renderheader , +.Nm lwres_lwpacket_parseheader +.Nd lightweight resolver packet handling functions +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_lwpacket_renderheader +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fc +.Ft lwres_result_t +.Fo lwres_lwpacket_parseheader +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fc +.Sh DESCRIPTION +These functions rely on a +.Dv "struct lwres_lwpacket" +which is defined in +.Pa lwres/lwpacket.h . +.Bd -literal -offset indent +typedef struct lwres_lwpacket lwres_lwpacket_t; + +struct lwres_lwpacket { + lwres_uint32_t length; + lwres_uint16_t version; + lwres_uint16_t pktflags; + lwres_uint32_t serial; + lwres_uint32_t opcode; + lwres_uint32_t result; + lwres_uint32_t recvlength; + lwres_uint16_t authtype; + lwres_uint16_t authlength; +}; +.Ed +.Pp +The elements of this structure are: +.Bl -tag -width recvlength +.It Li length +the overall packet length, including the entire packet header +.It Li version +the header format. There is currently only one format, +.Dv LWRES_LWPACKETVERSION_0 . +.It Li pktflags +library-defined flags for this packet: for instance whether the packet +is a request or a reply. Flag values can be set, but not defined by +the caller. +.It Li serial +is set by the requestor and is returned in all replies. If two or more +packets from the same source have the same serial number and are from +the same source, they are assumed to be duplicates and the latter ones +may be dropped. +.It Li opcode +indicates the operation. +Opcodes between 0x00000000 and 0x03ffffff are +reserved for use by the lightweight resolver library. Opcodes between +0x04000000 and 0xffffffff are application defined. +.It Li result +is only valid for replies. +Results between 0x04000000 and 0xffffffff are application defined. +Results between 0x00000000 and 0x03ffffff are reserved for library use. +.It Li recvlength +is the maximum buffer size that the receiver can handle on requests +and the size of the buffer needed to satisfy a request when the buffer is too large for replies +.It Li authtype +defines the packet level authentication that is used. +Authorisation types between 0x1000 and 0xffff are application defined +and types between 0x0000 and 0x0fff are reserved for library use. +Currently these are not used and must be zero. +.It Li authlen +gives the length of the authentication data. +Since packet authentication is currently not used, this must be zero. +.El +The following opcodes are currently defined: +.Bl -tag -width GETADDRSBYNAME +.It Li NOOP +Success is always returned and the packet contents are echoed. +.It Li GETADDRSBYNAME +returns all known addresses for a given name +.It Li GETNAMEBYADDR +return the hostname for the given address +.El +.Pp +.Fn lwres_lwpacket_renderheader +transfers the contents of lightweight resolver packet structure +.Dv lwres_lwpacket_t +.Fa *pkt +in network byte order to the lightweight resolver buffer, +.Fa *b . +.Pp +.Fn lwres_lwpacket_parseheader +performs the converse operation. +It transfers data in network byte order from buffer +.Fa *b +to resolver packet +.Fa *pkt . +The contents of the buffer +.Fa b +should correspond to a +.Dv "struct lwres_lwpacket" . +.Pp +Both functions have assertion checks to ensure that +.Fa b +and +.Fa pkt +are not +.Dv NULL . +.Sh RETURN VALUES +Successful calls to +.Fn lwres_lwpacket_renderheader +and +.Fn lwres_lwpacket_parseheader +return +.Er LWRES_R_SUCCESS . +If there is insufficient space to copy data between the buffer +.Fa *b +and lightweight resolver packet +.Fa *pkt +both functions return +.Er LWRES_R_UNEXPECTEDEND . diff --git a/doc/man/lwres/lwres_resutil.3 b/doc/man/lwres/lwres_resutil.3 new file mode 100644 index 0000000000..eb1aaf0253 --- /dev/null +++ b/doc/man/lwres/lwres_resutil.3 @@ -0,0 +1,216 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_resutil.3,v 1.1 2000/06/27 21:53:10 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_RESUTIL 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_string_parse , +.Nm lwres_addr_parse , +.Nm lwres_getaddrsbyname , +.Nm lwres_getnamebyaddr +.Nd lightweight resolver utility functions +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_string_parse +.Fa "lwres_buffer_t *b" +.Fa "char **c" +.Fa "lwres_uint16_t *len" +.Fc +.Ft lwres_result_t +.Fo lwres_addr_parse +.Fa "lwres_buffer_t *b" +.Fa "lwres_addr_t *addr" +.Fc +.Ft lwres_result_t +.Fo lwres_getaddrsbyname +.Fa "lwres_context_t *ctx" +.Fa "const char *name" +.Fa "lwres_uint32_t addrtypes" +.Fa "lwres_gabnresponse_t **structp" +.Fc +.Ft lwres_result_t +.Fo lwres_getnamebyaddr +.Fa "lwres_context_t *ctx" +.Fa "lwres_uint32_t addrtype" +.Fa "lwres_uint16_t addrlen" +.Fa "const unsigned char *addr" +.Fa "lwres_gnbaresponse_t **structp" +.Fc +.Sh DESCRIPTION +.Fn lwres_string_parse +retrieves a DNS-encoded string starting the current pointer of +lightweight resolver buffer +.Fa b : +i.e. +.Li b->current . +When the function returns, the address of the first byte of the +encoded string is returned via +.Fa *c +and the length of that string is given by +.Fa *len . +The buffer's current pointer is advanced to point at the character +following the string length, the encoded string, and the trailing +.Dv NULL +character. +.Fn lwres_string_parse +has an assertion check that +.Fa b +is not +.Dv NULL . +.Pp +.Fn lwres_addr_parse +extracts an address from the buffer +.Fa b . +It checks that +.Fa addr +is not null. +The buffer's current pointer +.Li b->current +is presumed to point at an encoded address: the address preceded by a +32-bit protocol family identifier and a 16-bit length field. +The encoded address is copied to +.Li addr->address +and +.Li addr->length +indicates the size in bytes of the address that was copied. +.Li b->current +is advanced to point at the next byte of available data in the buffer +following the encoded address. +.Pp +.Fn lwres_getaddrsbyname +and +.Fn lwres_getnamebyaddr +use the +.Dv "lwres_gnbaresponse_t" +structure defined below: +.Bd -literal -offset indent +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + lwres_uint16_t naddrs; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + lwres_addrlist_t addrs; + void *base; + size_t baselen; +} lwres_gabnresponse_t; +.Ed +The contents of this structure are not manipulated directly but +they are controlled through the +.Xr lwres_gabn 3 +functions. +.Pp +The lightweight resolver uses +.Fn lwres_getaddrsbyname +to perform foward lookups. +Hostname +.Fa name +is looked up using the resolver context +.Fa ctx +for memory allocation. +.Fa addrtypes +is a bitmask indicating which type of addresses are to be looked up. +Current values for this bitmask are +.Dv LWRES_ADDRTYPE_V4 +for IPv4 addresses and +.Dv LWRES_ADDRTYPE_V6 +for IPv6 addresses. +Results of the lookup are returned in +.Fa *structp . +.Fn lwres_getaddrsbyname +checks that its pointer arguments are not +.Dv NULL +and that +.Fa addrtypes +is non-zero. +.Pp +.Fn lwres_getnamebyaddr +performs reverse lookups. +Resolver context +.Fa ctx +is used for memory allocation. +The address type is indicated by +.Fa addrtype : +.Dv LWRES_ADDRTYPE_V4 +or +.Dv LWRES_ADDRTYPE_V6 . +The address to be looked up is given by +.Fa addr +and its length is +.Fa addrlen +bytes. +The result of the function call is made available through +.Fa *structp . +Like +.Fn lwres_getaddrsbyname , +.Fn lwres_getnamebyaddr +uses assertion checking to ensure its pointer arguments are not +.Dv NULL +and +.Fa addrtype +is not zero. +.Fn lwres_getaddrsbyname +also checks that +.Fa addrlen +is non-zero. +.Sh RETURN VALUES +Successful calls to +.Fn lwres_string_parse +and +.Fn lwres_addr_parse +return +.Er LWRES_R_SUCCESS. +Both functions return +.Er LWRES_R_FAILURE +if the buffer is corrupt or +.Er LWRES_R_UNEXPECTEDEND +if the buffer has less space than expected for the components of the +encoded string or address. +.Pp +.Fn lwres_getaddrsbyname +returns +.Er LWRES_R_SUCCESS +on success and it returns +.Er LWRES_R_NOTFOUND +if the hostname +.Fa name +could not be found. +.Pp +.Er LWRES_R_SUCCESS +is returned by a successful call to +.Fn lwres_getnamebyaddr . +.Pp +Both +.Fn lwres_getaddrsbyname +and +.Fn lwres_getnamebyaddr +return +.Er LWRES_R_NOMEMORY +when memory allocation requests fail and +.Er LWRES_R_UNEXPECTEDEND +if the buffers used for sending queries and receiving replies are too +small. +.Sh SEE ALSO +.Xr lwres_buffer 3 , +.Xr lwres_gabn 3 . diff --git a/doc/man/lwres/lwres_sethostent.3 b/doc/man/lwres/lwres_sethostent.3 new file mode 100644 index 0000000000..b88de48284 --- /dev/null +++ b/doc/man/lwres/lwres_sethostent.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_sethostent.3,v 1.1 2000/06/27 21:53:10 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_sethostent_r.3 b/doc/man/lwres/lwres_sethostent_r.3 new file mode 100644 index 0000000000..d455328b17 --- /dev/null +++ b/doc/man/lwres/lwres_sethostent_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_sethostent_r.3,v 1.1 2000/06/27 21:53:10 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/doc/man/lwres/lwres_string_parse.3 b/doc/man/lwres/lwres_string_parse.3 new file mode 100644 index 0000000000..378a559b06 --- /dev/null +++ b/doc/man/lwres/lwres_string_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_string_parse.3,v 1.1 2000/06/27 21:53:10 jim Exp $ +.\" +.so lwres_resutil.3 diff --git a/lib/lwres/man/lwres.3 b/lib/lwres/man/lwres.3 new file mode 100644 index 0000000000..3c686c64ea --- /dev/null +++ b/lib/lwres/man/lwres.3 @@ -0,0 +1,291 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres +.Nd introduction to the lightweight resolver +.Sh SYNOPSIS +.Fd #include +.Sh DESCRIPTION +The lightweight resolver provides a simple way for clients to perform +forward and reverse lookups. +Instead of looking up the names or addresses directly, clients can send +requests to the lightweight resolver daemon +.Nm lwresd +which does hard work of performing the lookups for them. +Clients can just use the lightweight resolver library to format a +request to get a hostname for an IP address or vice versa, send it to +.Nm lwresd +and wait for a response. +.Pp +The lightweight resolver in BIND 9 consists of three components: +a client, a server and a protocol. +Clients use the functions provided by the lightweight resolver library +to encode requests and decode responses. +The server for the lightweight resolver is +.Nm lwresd . +In reality this is implemented by the name server, +.Nm named , +though when operating as the lightweight resolver server, +.Nm lwresd +is functionally and logically distinct from the actual name server. +The protocol consists of a number of opcodes, each of which has a +request and response structure associated with it. +The lightweight resolver library contains functions to convert these +structures to and from the canonical format whenver they are sent to +.Nm lwresd . +.Sh RATIONALE +.Pp +Conventional DNS lookups of hostnames and IPv4 addresses are usually +simple and straightforward. +A client can issue queries to map a hostname to an IPv4 address or +from an IPv4 address to a hostname. +Many DNS queries can be needed to lookup IPv6 addresses. +It may be necessary to resolve potentially variable-length partial +IPv6 addresses: aggregation and site-level identifiers for instance. +Keeping track of all of these queries and assembling the answers to +return the hostname or IPv6 address is very hard work and error-prone. +Further complexity can be caused by DNAME chains. +If the answers are signed using DNSSEC, additional queries may be needed +to verify the signatures. +The consequence of this is that clients can be overwhelmed with the +amount of work needed to resolve IPv6 addresses. +BIND9 provides a lightweight resolver to eliminate these problems if +applications had to resolve IPv6 addresses for themselves. +.Pp +Instead of looking up the hostnames or IPv6 addresses directly, clients +can use the lightweight resolver to get the name server to do the work. +Clients construct simple questions like \*qwhat is the hostname for +the following address?\*q or \*qwhat are the addresses of hostname +.Dv host.example.com?\*q +The lightweight resolver functions take these questions and format +them into queries which are sent to +.Nm lwresd . +Replies from the lightweight resolver server are then decoded to return +an answer to the client which made the original request. +.Sh CANONICAL FORMAT +.Pp +The lightweight resolver's canonical data format has been arranged for +efficiency. +All integer values are in network byte order. +Addresses are also in network byte order. +This means that, at least for IPv4 and IPv6 addresses, they can be +used directly in network system calls without needing to be byte +swapped. +Character strings get prefixed by a length and are always terminated +with a +.Dv NUL +character. +This simplifies structure handling and parsing for both the server +receiving a request and the client receiving a reply. +It also eliminates data copying by enabling a mapping structure to +directly point at data in the actual receive buffer. +.Sh OPCODES +.Pp +Every lightweight resolver operation uses a unique opcode. +Each opcode is assigned a number. +Opcodes in the range 0x00000000 and 0x03ffffff are reserved for use by +the lightweight resolver library. +Opcodes between 0x04000000 and 0xffffffff have been set aside for use by +applications. +.Pp +Three opcodes are currently defined: +.Bl -tag -width LWRES_OPCODE_GETADDRSBYNAME +.It Li LWRES_OPCODE_NOOP +The no-op opcode is essentially an echo operation, comparable to +.Xr ping 1 . +The server simply returns the entire data region that had been sent by +the client. +Therefore clients can use this opcode to determine if the server is +operational or not. +It can also be used by clients to check the version number and any +parameters of the lightweight resolver protocol that are supported by the +server. +.It Li LWRES_OPCODE_GETADDRSBYNAME +This opcode is used to get all the known addresses for a hostname. +In principle, this could also return information from NIS/YP or +.Pa /etc/hosts , +though this is not implemented yet. +Flags can be set in the request structure that is used for this opcode +to indicate whether IPv4 or IPv6 addresses or both should be returned. +.It Li LWRES_OPCODE_GETNAMEBYADDR +This provides the complementary operation to +.Dv LWRES_OPCODE_GETADDRSBYNAME . +It returns the hostname for the address that was supplied in the +request structure. +.El +.\" +.\" XXXJR +.\" We don't need this section, at least not yet. 23/6/00 +.\" +.\" .Sh OPCODE REPLIES +.\" .Pp +.\" Replies to lightweight resolver operations contain return codes. +.\" Results between 0x04000000 and 0xffffffff are application defined. +.\" The lightweight resolver library reserves result codes between +.\" 0x00000000 and 0x03ffffff. +.\" These occupy the same reserved range used for ISC return values that +.\" are defined in +.\" .Pa isc/resultclass.h . +.\" This means that, if appropriate, it would be trivial to map those ISC +.\" return values to lightweight resolver packet result codes. +.Sh STRUCTURE AND PACKET ENCODING/DECODING +Each opcode has two structures: one for the request and one for the +response. +Clients use the lightweight resolver functions to construct the +request structure and send it to the name server. +The name server decodes the request, carries out the operation and +fills in an opcode-specific response structure which is returned to +the client. +.Pp +For every opcode, three functions operate on these structures. +A +.Ar render +function converts the structure to canonical form and a +.Ar parse +function translates from the canonical form to the op-code specific +structure. +Memory allocated to the opcode's request or reply structures is +discarded using the +.Ar free +function. +Clients will typically use the op-code specific +.Ar xxx_request_render , +.Ar xxx_response_parse +and +.Ar xxx_response_free +functions. +The name server will use the +.Ar xxx_request_parse , +.Ar xxx_response_render +and +.Ar xxx_request_free +functions. +.Pp +For example, the no-op opcode - +.Dv LWRES_OPCODE_NOOP +- uses +.Dv lwres_nooprequest_t +and +.Dv lwres_noopresponse_t +structures for the requests and responses used in the no-op operation. +.Fn lwres_nooprequest_render +takes a +.Dv lwres_nooprequest_t +structure and converts into a packet in lightweight resolver canonical +format. +Similarly +.Fn lwres_noopresponse_render +converts a +.Dv lwres_noopresponse_t +structure into a packet in lightweight resolver canonical format. +.Fn lwres_nooprequest_parse +takes a packet in canonical format and fills in a corresponding +.Dv lwres_nooprequest_t +structure. +A +.Dv lwres_noopresponse_t +structure is set up by\p +passing a response packet in canonical format to +.Fn lwres_noopresponse_render . +.Fn lwres_nooprequest_free +and +.Fn lwres_noopresponse_free +releases the memory allocated to the +.Dv lwres_nooprequest_t +and +.Dv lwres_noopresponse_t +structures respectively. +.\" +.\" XXXJR +.\" NOT YET. +.\" This is just a placeholder to indicate where the section on the +.\" lwres security API should be documented once this is implemented. +.\" There's no point in documenting vapourware, especially if the +.\" API is likely to change between now and then. 23/6/00 +.\" .Sh SECURITY +.\" The lightweight resolver provides hooks for requesting the use of +.\" DNSSEC for authenticating requests and responses. +.\" This interface is not currently implemented and is likely to +.\" change. +.\" It is mentioned here to indicate the capabilities that can be expected +.\" in future releases of the lightweight resolver. +.\" .Pp +.\" The following flag bits have been allocated. +.\" .Bl -tag -width LWRES_FLAG_TRUSTNOTREQUIRED +.\" .It Li LWRES_FLAG_TRUSTDEFAULT +.\" Let the server decide whether to use DNSSEC or not. +.\" .It Li LWRES_FLAG_TRUSTNOTREQUIRED +.\" DNSSEC authentication of the DNS queries and replies is not required +.\" .It Li LWRES_FLAG_TRUSTREQUIRED +.\" Any DNSSEC data found when resolving the query must validate and the +.\" server must be DNSSEC-aware. +.\" .It Li LWRES_FLAG_TRUSTRESERVED +.\" Reserved for future use. +.\" .El +.Sh CLIENT SETUP +Every client that uses the lightweight resolver needs to create and +maintain its own state. +Library calls are provided to manage that data structure, a resolver +context. +If the client uses threads, it either has to provide its own locking +primitives on that context structure or else create a context for each +thread. +See +.Xr lwres_context 3 . +Once the context has been created, +.Fn lwres_conf_init +is called to read +.Pa /etc/resolv.conf +so that various options such as sort lists, search lists and so on can +be applied. +.Sh CLIENT INTERFACE +The simplest interface to the lightweight resolver is provided by +.Fn lwres_getaddrsbyname +and +.Fn lwres_getnamebyaddr . +These functions are blocking calls. +A client will wait after sending a request until either a response is +returned or else a timeout interval occurs. +If non-blocking operations are required, the client will need to +call the opcode-specific +.Ar request_render +and +.Ar response_parse +directly. +.Sh SERVER INTERFACE +Service for the lightweight resolver is provided by the lightweight +resolver daemon, +.Nm lwresd . +It listens on port number 921 of the loopback interface and expects to +receive packets in the lightweight resolver's canonical format +described above. +.Sh SEE ALSO +.Xr lwres_noop 3 , +.Xr lwres_gabn 3 , +.Xr lwres_gnba 3 , +.Xr lwres_context 3 , +.Xr lwres_config 3 , +.Xr resolver 5 , +.Xr lwres_getipnode 3 +.Xr lwresd 8 , +.Xr named 8 . diff --git a/lib/lwres/man/lwres_addr_parse.3 b/lib/lwres/man/lwres_addr_parse.3 new file mode 100644 index 0000000000..5c26a32c33 --- /dev/null +++ b/lib/lwres/man/lwres_addr_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_addr_parse.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.so lwres_resutil.3 diff --git a/lib/lwres/man/lwres_buffer.3 b/lib/lwres/man/lwres_buffer.3 new file mode 100644 index 0000000000..72b241a3e1 --- /dev/null +++ b/lib/lwres/man/lwres_buffer.3 @@ -0,0 +1,324 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_BUFFER 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_buffer_init , +.Nm lwres_buffer_invalidate , +.Nm lwres_buffer_add , +.Nm lwres_buffer_subtract , +.Nm lwres_buffer_clear , +.Nm lwres_buffer_first , +.Nm lwres_buffer_forward , +.Nm lwres_buffer_back , +.Nm lwres_buffer_getuint8 , +.Nm lwres_buffer_putuint8 , +.Nm lwres_buffer_getuint16 , +.Nm lwres_buffer_putuint16 , +.Nm lwres_buffer_getuint32 , +.Nm lwres_buffer_putuint32 , +.Nm lwres_buffer_putmem , +.Nm lwres_buffer_getmem +.Nd lightweight resolver buffer management +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft void +.Fo lwres_buffer_init +.Fa "lwres_buffer_t *b" +.Fa "void *base" +.Fa "unsigned int length" +.Fc +.Ft void +.Fo lwres_buffer_invalidate +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_add +.Fa "lwres_buffer_t *b" +.Fa "unsigned int n" +.Fc +.Ft void +.Fo lwres_buffer_subtract +.Fa "lwres_buffer_t *b" +.Fa "unsigned int n" +.Fc +.Ft void +.Fo lwres_buffer_clear +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_first +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_forward +.Fa "lwres_buffer_t *b" +.Fa "unsigned int n" +.Fc +.Ft void +.Fo lwres_buffer_back +.Fa "lwres_buffer_t *b" +.Fa "unsigned int n" +.Fc +.Ft lwres_uint8_t +.Fo lwres_buffer_getuint8 +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_putuint8 +.Fa "lwres_buffer_t *b" +.Fa "lwres_uint8_t val" +.Fc +.Ft lwres_uint16_t +.Fo lwres_buffer_getuint16 +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_putuint16 +.Fa "lwres_buffer_t *b" +.Fa "lwres_uint16_t val" +.Fc +.Ft lwres_uint32_t +.Fo lwres_buffer_getuint32 +.Fa "lwres_buffer_t *b" +.Fc +.Ft void +.Fo lwres_buffer_putuint32 +.Fa "lwres_buffer_t *b" +.Fa "lwres_uint32_t val" +.Fc +.Ft void +.Fo lwres_buffer_putmem +.Fa "lwres_buffer_t *b" +.Fa "const unsigned char *base" +.Fa "unsigned int length" +.Fc +.Ft void +.Fo lwres_buffer_getmem +.Fa "lwres_buffer_t *b" +.Fa "unsigned char *base" +.Fa "unsigned int length" +.Fc +.Sh DESCRIPTION +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. +.Pp +A buffer is a region of memory, together with a set of related +subregions. +The \*qused region\*q and the \*qavailable\*q region are disjoint, and +their union is the buffer's region. +The used region extends from the beginning of the buffer region to the +last used byte. +The available region extends from one byte greater than the last used +byte to the end of the buffer's region. +The size of the used region can be changed using various +buffer commands. +Initially, the used region is empty. +.Pp +The used region is further subdivided into two disjoint regions: the +\*qconsumed region\*q and the \*qremaining region\*q. +The union of these two regions is the used region. +The consumed region extends from the beginning of the used region to +the byte before the \*qcurrent\*q offset (if any). +The \*qremaining\*q region the current pointer to the end of the used +region. +The size of the consumed region can be changed using various +buffer commands. +Initially, the consumed region is empty. +.Pp +The \*qactive region\*q is an (optional) subregion of the remaining +region. +It extends from the current offset to an offset in the +remaining region. +Initially, the active region is empty. +If the current offset advances beyond the chosen offset, +the active region will also be empty. +.Pp +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. +.Pp +.Fn lwres_buffer_init +makes the +.Dv "struct lwres_buffer" +referenced by +.Fa *b +to be associated with a 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. +.Pp +The functions +.Fn lwres_buffer_add +and +.Fn lwres_buffer_subtract +respectively increase and decrease the used space in +buffer +.Fa *b +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 . +.Pp +A lightweight resolver buffer is re-initialised by +.Fn lwres_buffer_clear . +The function sets +.Li b->used , +.Li b->current +and +.Li b->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. +.Pp +The consumed region of buffer +.Fa *b +is increased by +.Fa n +bytes +using +.Fn lwres_buffer_forward . +The function checks for buffer overflow. +Similarly, +.Fn lwres_buffer_back +decreases buffer +.Fa b 's +consumed region by +.Fa n +bytes and checks for buffer 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. +Similarly, +.Fn lwres_buffer_putuint16 +and +.Fn lwres_buffer_putuint32 +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. +.Pp +Arbitrary amounts of data are read or written from a lightweight +resolver buffer with +.Fn lwres_buffer_getmem +and +.Fn lwres_buffer_putmem +respectively. +.Fn lwres_buffer_putmem +copies +.Fa length +bytes of memory at +.Fa base +to +.Fa b. +Conversely, +.Fn lwres_buffer_getmem +copies +.Fa length +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. diff --git a/lib/lwres/man/lwres_buffer_add.3 b/lib/lwres/man/lwres_buffer_add.3 new file mode 100644 index 0000000000..25b7c08932 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_add.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_add.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_back.3 b/lib/lwres/man/lwres_buffer_back.3 new file mode 100644 index 0000000000..eb57f87b84 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_back.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_back.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_clear.3 b/lib/lwres/man/lwres_buffer_clear.3 new file mode 100644 index 0000000000..4d4e7c0bf5 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_clear.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_clear.3,v 1.1 2000/06/27 21:52:57 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_first.3 b/lib/lwres/man/lwres_buffer_first.3 new file mode 100644 index 0000000000..4a1a8f8ad1 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_first.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_first.3,v 1.1 2000/06/27 21:52:58 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_forward.3 b/lib/lwres/man/lwres_buffer_forward.3 new file mode 100644 index 0000000000..1171c07b26 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_forward.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_forward.3,v 1.1 2000/06/27 21:52:58 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_getmem.3 b/lib/lwres/man/lwres_buffer_getmem.3 new file mode 100644 index 0000000000..f3b5d7840c --- /dev/null +++ b/lib/lwres/man/lwres_buffer_getmem.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_getmem.3,v 1.1 2000/06/27 21:52:58 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_getuint16.3 b/lib/lwres/man/lwres_buffer_getuint16.3 new file mode 100644 index 0000000000..ce7f6395f5 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_getuint16.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_getuint16.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_getuint32.3 b/lib/lwres/man/lwres_buffer_getuint32.3 new file mode 100644 index 0000000000..57645c94a0 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_getuint32.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_getuint32.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_getuint8.3 b/lib/lwres/man/lwres_buffer_getuint8.3 new file mode 100644 index 0000000000..d91088b06a --- /dev/null +++ b/lib/lwres/man/lwres_buffer_getuint8.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_getuint8.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_init.3 b/lib/lwres/man/lwres_buffer_init.3 new file mode 100644 index 0000000000..978f957248 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_init.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_init.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_invalidate.3 b/lib/lwres/man/lwres_buffer_invalidate.3 new file mode 100644 index 0000000000..8f4d5c08a4 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_invalidate.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_invalidate.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_putmem.3 b/lib/lwres/man/lwres_buffer_putmem.3 new file mode 100644 index 0000000000..106f00fe45 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_putmem.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_putmem.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_putuint16.3 b/lib/lwres/man/lwres_buffer_putuint16.3 new file mode 100644 index 0000000000..312487519e --- /dev/null +++ b/lib/lwres/man/lwres_buffer_putuint16.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_putuint16.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_putuint32.3 b/lib/lwres/man/lwres_buffer_putuint32.3 new file mode 100644 index 0000000000..54ef235e33 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_putuint32.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_putuint32.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_putuint8.3 b/lib/lwres/man/lwres_buffer_putuint8.3 new file mode 100644 index 0000000000..fa19fb80f1 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_putuint8.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_putuint8.3,v 1.1 2000/06/27 21:52:59 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_buffer_subtract.3 b/lib/lwres/man/lwres_buffer_subtract.3 new file mode 100644 index 0000000000..25e62b7f25 --- /dev/null +++ b/lib/lwres/man/lwres_buffer_subtract.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_buffer_subtract.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_buffer.3 diff --git a/lib/lwres/man/lwres_conf_clear.3 b/lib/lwres/man/lwres_conf_clear.3 new file mode 100644 index 0000000000..d03f1f95b9 --- /dev/null +++ b/lib/lwres/man/lwres_conf_clear.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_clear.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/lib/lwres/man/lwres_conf_get.3 b/lib/lwres/man/lwres_conf_get.3 new file mode 100644 index 0000000000..cf2ed6aa80 --- /dev/null +++ b/lib/lwres/man/lwres_conf_get.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_get.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/lib/lwres/man/lwres_conf_init.3 b/lib/lwres/man/lwres_conf_init.3 new file mode 100644 index 0000000000..625b307bd2 --- /dev/null +++ b/lib/lwres/man/lwres_conf_init.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_init.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/lib/lwres/man/lwres_conf_parse.3 b/lib/lwres/man/lwres_conf_parse.3 new file mode 100644 index 0000000000..23bedfeb46 --- /dev/null +++ b/lib/lwres/man/lwres_conf_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_parse.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/lib/lwres/man/lwres_conf_print.3 b/lib/lwres/man/lwres_conf_print.3 new file mode 100644 index 0000000000..75e0ec411f --- /dev/null +++ b/lib/lwres/man/lwres_conf_print.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_conf_print.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.so lwres_config.3 diff --git a/lib/lwres/man/lwres_config.3 b/lib/lwres/man/lwres_config.3 new file mode 100644 index 0000000000..bc4679419d --- /dev/null +++ b/lib/lwres/man/lwres_config.3 @@ -0,0 +1,109 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_config.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_CONFIG 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_conf_init , +.Nm lwres_conf_clear , +.Nm lwres_conf_parse , +.Nm lwres_conf_print , +.Nm lwres_conf_get +.Nd lightweight resolver configuration +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft void +.Fo lwres_conf_init +.Fa "lwres_context_t *ctx" +.Fc +.Ft void +.Fo lwres_conf_clear +.Fa "lwres_context_t *ctx" +.Fc +.Ft lwres_result_t +.Fo lwres_conf_parse +.Fa "lwres_context_t *ctx" +.Fa "const char *filename" +.Fc +.Ft lwres_result_t +.Fo lwres_conf_print +.Fa "lwres_context_t *ctx" +.Fa "FILE *fp" +.Fc +.Ft lwres_conf_t * +.Fo lwres_conf_get +.Fa "lwres_context_t *ctx" +.Fc +.Sh DESCRIPTION +.Fn lwres_conf_init +creates an empty +.Dv lwres_conf_t +structure for lightweight resolver context +.Fa ctx . +.Pp +.Fn lwres_conf_clear +frees up all the internal memory used by +that +.Dv lwres_conf_t +structure in resolver context +.Fa ctx . +.Pp +.Fn lwres_conf_parse +opens the file +.Fa filename +and parses it to initialise the resolver context +.Fa ctx 's +.Dv lwres_conf_t +structure. +.Pp +.Fn lwres_conf_print +prints the +.Dv lwres_conf_t +structure for resolver context +.Fa ctx +to the +.Dv FILE +.Fa fp. +.Sh RETURN VALUES +.Fn lwres_conf_parse +returns +.Er LWRES_R_SUCCESS +if it successfully read and parsed +.Fa filename . +It returns +.Er LWRES_R_FAILURE +if +.Fa filename +could not be opened or contained incorrect +resolver statements. +.Pp +.Fn lwres_conf_print +returns +.Er LWRES_R_SUCCESS +unless an error occurred when converting the network addresses to a +numeric host address string. +If this happens, the function returns +.Er LWRES_R_FAILURE . +.Sh SEE ALSO +.Xr stdio 3, +.Xr resolver 5 . +.Sh FILES +.Pa /etc/resolv.conf diff --git a/lib/lwres/man/lwres_context.3 b/lib/lwres/man/lwres_context.3 new file mode 100644 index 0000000000..0c2055e42b --- /dev/null +++ b/lib/lwres/man/lwres_context.3 @@ -0,0 +1,257 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context.3,v 1.1 2000/06/27 21:53:00 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_CONTEXT 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_context_create , +.Nm lwres_context_destroy , +.Nm lwres_context_nextserial , +.Nm lwres_context_initserial , +.Nm lwres_context_freemem , +.Nm lwres_context_allocmem , +.Nm lwres_context_sendrecv +.Nd lightweight resolver memory allocation routines +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_context_create +.Fa "lwres_context_t **contextp" +.Fa "void *arg" +.Fa "lwres_malloc_t malloc_function" +.Fa "lwres_free_t free_function" +.Fc +.Ft lwres_result_t +.Fo lwres_context_destroy +.Fa "lwres_context_t **contextp" +.Fc +.Ft void +.Fo lwres_context_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 void +.Fo lwres_context_freemem +.Fa "lwres_context_t *ctx" +.Fa "void *mem" +.Fa "size_t len" +.Fc +.Ft void +.Fo lwres_context_allocmem +.Fa "lwres_context_t *ctx" +.Fa "size_t len" +.Fc +.Ft void * +.Fo lwres_context_sendrecv +.Fa "lwres_context_t *ctx" +.Fa "void *sendbase" +.Fa "int sendlen" +.Fa "void *recvbase" +.Fa "int recvlen" +.Fa "int *recvd_len" +.Fc +.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 +.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. +.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 +.Xr malloc 3 +and +.Xr free 3 +are used. +.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. +Once memory for the structure has been allocated, +.Xr lwres_conf_init 3 +is called to initialise it. +The structure is then returned via +.Fa *contextp . +.Pp +A +.Dv "struct lwres_context" +is destroyed by +.Fn lwres_context_destroy. +.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. +.Pp +The context's serial number is controlled with +.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 . +.Pp +Memory for a lightweight resolver context is allocated and freed using +.Fn lwres_context_allocmem +and +.Fn lwres_context_freemem . +These use whatever allocations were defined when the context was +created with +.Fn lwres_context_create . +.Fn lwres_context_allocmem +allocates +.Fa len +bytes of memory and if successful returns a pointer to the allocated +storage. +.Fn lwres_context_allocmem +checks that +.Fa len +must be greater than 0. +.Fn lwres_context_freemem +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 . +It writes data from +.Fa sendbase +- typically a DNS query - +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 . +.Sh RETURN VALUES +.Fn lwres_context_create +returns +.Er LWRES_R_NOMEMORY +if memory for the +.Dv "struct lwres_context" +could not be allocated, otherwise +.Er LWRES_R_SUCCESS +is returned. +.Pp +Successful calls to the memory allocator +.Fn lwres_context_allocmem +return a pointer to the start of the allocated space. +It returns NULL if memory could not be allocated. +.Pp +.Er LWRES_R_SUCCESS +is returned when +.Fn lwres_context_sendrecv +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. +.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. diff --git a/lib/lwres/man/lwres_context_allocmem.3 b/lib/lwres/man/lwres_context_allocmem.3 new file mode 100644 index 0000000000..1a94a23641 --- /dev/null +++ b/lib/lwres/man/lwres_context_allocmem.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_allocmem.3,v 1.1 2000/06/27 21:53:01 jim Exp $ +.\" +.so lwres_context.3 diff --git a/lib/lwres/man/lwres_context_create.3 b/lib/lwres/man/lwres_context_create.3 new file mode 100644 index 0000000000..f15a8d6a10 --- /dev/null +++ b/lib/lwres/man/lwres_context_create.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_create.3,v 1.1 2000/06/27 21:53:01 jim Exp $ +.\" +.so lwres_context.3 diff --git a/lib/lwres/man/lwres_context_destroy.3 b/lib/lwres/man/lwres_context_destroy.3 new file mode 100644 index 0000000000..6b9fe274d7 --- /dev/null +++ b/lib/lwres/man/lwres_context_destroy.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_destroy.3,v 1.1 2000/06/27 21:53:01 jim Exp $ +.\" +.so lwres_context.3 diff --git a/lib/lwres/man/lwres_context_freemem.3 b/lib/lwres/man/lwres_context_freemem.3 new file mode 100644 index 0000000000..ba8c4be0a0 --- /dev/null +++ b/lib/lwres/man/lwres_context_freemem.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_freemem.3,v 1.1 2000/06/27 21:53:01 jim Exp $ +.\" +.so lwres_context.3 diff --git a/lib/lwres/man/lwres_context_initserial.3 b/lib/lwres/man/lwres_context_initserial.3 new file mode 100644 index 0000000000..8c350b7233 --- /dev/null +++ b/lib/lwres/man/lwres_context_initserial.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_initserial.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_context.3 diff --git a/lib/lwres/man/lwres_context_nextserial.3 b/lib/lwres/man/lwres_context_nextserial.3 new file mode 100644 index 0000000000..231c261452 --- /dev/null +++ b/lib/lwres/man/lwres_context_nextserial.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_nextserial.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_context.3 diff --git a/lib/lwres/man/lwres_context_sendrecv.3 b/lib/lwres/man/lwres_context_sendrecv.3 new file mode 100644 index 0000000000..0d29d8abd3 --- /dev/null +++ b/lib/lwres/man/lwres_context_sendrecv.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_context_sendrecv.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_context.3 diff --git a/lib/lwres/man/lwres_endhostent.3 b/lib/lwres/man/lwres_endhostent.3 new file mode 100644 index 0000000000..c7f7bf2463 --- /dev/null +++ b/lib/lwres/man/lwres_endhostent.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_endhostent.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_endhostent_r.3 b/lib/lwres/man/lwres_endhostent_r.3 new file mode 100644 index 0000000000..e958b1fdbb --- /dev/null +++ b/lib/lwres/man/lwres_endhostent_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_endhostent_r.3,v 1.1 2000/06/27 21:53:02 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_freeaddrinfo.3 b/lib/lwres/man/lwres_freeaddrinfo.3 new file mode 100644 index 0000000000..360ebe4e5f --- /dev/null +++ b/lib/lwres/man/lwres_freeaddrinfo.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_freeaddrinfo.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_getaddrinfo.3 diff --git a/lib/lwres/man/lwres_freehostent.3 b/lib/lwres/man/lwres_freehostent.3 new file mode 100644 index 0000000000..4544bff8ab --- /dev/null +++ b/lib/lwres/man/lwres_freehostent.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_freehostent.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_getipnode.3 diff --git a/lib/lwres/man/lwres_gabn.3 b/lib/lwres/man/lwres_gabn.3 new file mode 100644 index 0000000000..5675568953 --- /dev/null +++ b/lib/lwres/man/lwres_gabn.3 @@ -0,0 +1,208 @@ +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabn.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GABN 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_gabnrequest_render , +.Nm lwres_gabnresponse_render , +.Nm lwres_gabnrequest_parse , +.Nm lwres_gabnresponse_parse , +.Nm lwres_gabnresponse_free , +.Nm lwres_gabnrequest_free +.Nd lightweight resolver getaddrbyname functions +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_gabnrequest_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_gabnrequest_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_gabnresponse_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_gabnresponse_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_gabnrequest_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_gabnrequest_t **structp" +.Fc +.Ft lwres_result_t +.Fo lwres_gabnresponse_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_gabnresponse_t **structp" +.Fc +.Ft void +.Fo lwres_gabnresponse_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_gabnresponse_t **structp" +.Fc +.Ft void +.Fo lwres_gabnrequest_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_gabnrequest_t **structp" +.Fc +.Sh DESCRIPTION +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 +There are four main functions for the getaddrbyname opcode. +One render function converts a getaddrbyname request structure - +.Dv lwres_gabnrequest_t - +to the lighweight resolver's canonical format. +It is complemented by a parse function that converts a packet in this +canonical format to a getaddrbyname request structure. +Another render function converts the getaddrbyname response structure - +.Dv lwres_gabnresponse_t +to the canonical format. +This is complemented by a parse function which converts a packet in +canonical format to a getaddrbyname response structure. +.Pp +These structures are defined in +.Pa lwres/lwres.h . +They are shown below. +.Bd -literal -offset indent +#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U + +typedef struct lwres_addr lwres_addr_t; +typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint32_t addrtypes; + lwres_uint16_t namelen; + char *name; +} lwres_gabnrequest_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + lwres_uint16_t naddrs; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + lwres_addrlist_t addrs; + void *base; + size_t baselen; +} lwres_gabnresponse_t; +.Ed +.Pp +.Fn lwres_gabnrequest_render +uses resolver context +.Fa ctx +to convert getaddrbyname request structure +.Fa req +to canonical format. +The packet header structure +.Fa pkt +is initialised and transferred to +buffer +.Fa b . +The contents of +.Fa *req +are then appended to the buffer in canonical format. +.Fn lwres_gabnresponse_render +performs the same task, except it converts a getaddrbyname response structure +.Dv lwres_gabnresponse_t +to the lightweight resolver's canonical format. +.Pp +.Fn lwres_gabnrequest_parse +uses context +.Fa ctx +to convert the contents of packet +.Fa pkt +to a +.Dv lwres_gabnrequest_t +structure. +Buffer +.Fa b +provides space to be used for storing this structure. +When the function succeeds, the resulting +.Dv lwres_gabnrequest_t +is made available through +.Fa *structp . +.Fn lwres_gabnresponse_parse +offers the same semantics as +.Fn lwres_gabnrequest_parse +except it yields a +.Dv lwres_gabnresponse_t +structure. +.Pp +.Fn lwres_gabnresponse_free +and +.Fn lwres_gabnrequest_free +release the memory in resolver context +.Fa ctx +that was allocated to the +.Dv lwres_gabnresponse_t +or +.Dv lwres_gabnrequest_t +structures referenced via +.Fa structp . +Any memory associated with ancillary buffers and strings for those +structures is also discarded. +.Sh RETURN VALUES +The getaddrbyname opcode functions +.Fn lwres_gabnrequest_render , +.Fn lwres_gabnresponse_render +.Fn lwres_gabnrequest_parse +and +.Fn lwres_gabnresponse_parse +all return +.Er LWRES_R_SUCCESS +on success. +They return +.Er LWRES_R_NOMEMORY +if memory allocation fails. +.Er LWRES_R_UNEXPECTEDEND +is returned if the available space in the buffer +.Fa b +is too small to accommodate the packet header or the +.Dv lwres_gabnrequest_t +and +.Dv lwres_gabnresponse_t +structures. +.Fn lwres_gabnrequest_parse +and +.Fn lwres_gabnresponse_parse +will return +.Er LWRES_R_UNEXPECTEDEND +if the buffer is not empty after decoding the received packet. +These functions will return +.Er LWRES_R_FAILURE +if +.Li pktflags +in the packet header structure +.Dv lwres_lwpacket_t +indicate that the packet is not a response to an earlier query. +.Sh SEE ALSO +.Xr lwres_packet 3 diff --git a/lib/lwres/man/lwres_gabnrequest_free.3 b/lib/lwres/man/lwres_gabnrequest_free.3 new file mode 100644 index 0000000000..28f7430e51 --- /dev/null +++ b/lib/lwres/man/lwres_gabnrequest_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnrequest_free.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/lib/lwres/man/lwres_gabnrequest_parse.3 b/lib/lwres/man/lwres_gabnrequest_parse.3 new file mode 100644 index 0000000000..726724c33f --- /dev/null +++ b/lib/lwres/man/lwres_gabnrequest_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnrequest_parse.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/lib/lwres/man/lwres_gabnrequest_render.3 b/lib/lwres/man/lwres_gabnrequest_render.3 new file mode 100644 index 0000000000..b7602ddc53 --- /dev/null +++ b/lib/lwres/man/lwres_gabnrequest_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnrequest_render.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/lib/lwres/man/lwres_gabnresponse_free.3 b/lib/lwres/man/lwres_gabnresponse_free.3 new file mode 100644 index 0000000000..acd186abc4 --- /dev/null +++ b/lib/lwres/man/lwres_gabnresponse_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnresponse_free.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/lib/lwres/man/lwres_gabnresponse_parse.3 b/lib/lwres/man/lwres_gabnresponse_parse.3 new file mode 100644 index 0000000000..bf35af6796 --- /dev/null +++ b/lib/lwres/man/lwres_gabnresponse_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnresponse_parse.3,v 1.1 2000/06/27 21:53:03 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/lib/lwres/man/lwres_gabnresponse_render.3 b/lib/lwres/man/lwres_gabnresponse_render.3 new file mode 100644 index 0000000000..e18436181e --- /dev/null +++ b/lib/lwres/man/lwres_gabnresponse_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gabnresponse_render.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_gabn.3 diff --git a/lib/lwres/man/lwres_gai_strerror.3 b/lib/lwres/man/lwres_gai_strerror.3 new file mode 100644 index 0000000000..41a14aa28d --- /dev/null +++ b/lib/lwres/man/lwres_gai_strerror.3 @@ -0,0 +1,85 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gai_strerror.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GAI_STRERROR 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm gai_strerror +.Nd print suitable error string +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft char * +.Fo gai_strerror +.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. +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 +.It Dv EAI_AGAIN +temporary failure in name resolution +.It Dv EAI_BADFLAGS +invalid value for +.Li ai_flags +.It Dv EAI_FAIL +non-recoverable failure in name resolution +.It Dv EAI_FAMILY +.Li ai_family +not supported +.It Dv EAI_MEMORY +memory allocation failure +.It Dv EAI_NODATA +no address associated with hostname +.It Dv EAI_NONAME +hostname or servname not provided, or not known +.It Dv EAI_SERVICE +servname not supported for +.Li ai_socktype +.It Dv EAI_SOCKTYPE +.Li ai_socktype +not supported +.It Dv EAI_SYSTEM +system error returned in errno +.El +.Pp +.Li ai_flags , +.Li ai_family +and +.Li ai_socktype +are elements of the +.Dv "struct addrinfo" used by +.Fn lwres_getaddrinfo . +.Sh SEE ALSO +.Xr errno 2 , +.Xr perror 3 , +.Xr lwres_getaddrinfo 3 , +.Xr getaddrinfo 3 , +.Xr RFC2133 . diff --git a/lib/lwres/man/lwres_getaddrinfo.3 b/lib/lwres/man/lwres_getaddrinfo.3 new file mode 100644 index 0000000000..9ab605bb3e --- /dev/null +++ b/lib/lwres/man/lwres_getaddrinfo.3 @@ -0,0 +1,261 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getaddrinfo.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GETADDRINFO 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_getaddrinfo , +.Nm lwres_freeaddrinfo +.Nd socket address structure to host and service name +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft int +.Fo lwres_getaddrinfo +.Fa "const char *hostname" +.Fa "const char *servname" +.Fa "const struct addrinfo *hints" +.Fa "struct addrinfo **res" +.Fc +.Ft void +.Fo lwres_freeaddrinfo +.Fa "struct addrinfo *ai" +.Fc +.Pp +If the operating system does not provide a +.Dv "struct addrinfo" , +the following structure is used +.Bd -literal -offset indent +struct addrinfo { + int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ + int ai_family; /* PF_xxx */ + int ai_socktype; /* SOCK_xxx */ + int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ + size_t ai_addrlen; /* length of ai_addr */ + char *ai_canonname; /* canonical name for hostname */ + struct sockaddr *ai_addr; /* binary address */ + struct addrinfo *ai_next; /* next structure in linked list */ +}; +.Ed +.Sh DESCRIPTION +.Pp +.Fn lwres_getaddrinfo +is used to get a list of IP addresses and port numbers for host +.Fa hostname +and +.Fa servname . +The function is the lightweight resolver's implementation of +.Fn getaddrinfo +as defined in RFC2133. +.Fa hostname +and +.Fa servname +arguments 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. +.Fa servname +is either a decimal port number or a service name as listed in +.Pa /etc/services . +.Pp +.Fa hints +is an optional pointer to a +.Dv "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 +.Fa *hints : +.Bl -tag -width ai_socktyp -offset indent -compact +.It Li ai_family +the protocol family that should be used. +When +.Li ai_family +is set to +.Dv PF_UNSPEC , +it means the caller will accept any protocol family supported by the +operating system. +.It Dv ai_socktype +denotes the type of socket - +.Dv SOCK_STREAM , +.Dv SOCK_DGRAM +or +.Dv SOCK_RAW +- that is wanted. +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. +If +.Li ai_protocol +is zero the caller will accept any protocol. +.It Li ai_flags +sets some flag bits. +If the +.Dv AI_CANONNAME +bit is set, a successful call to +.Fn lwres_getaddrinfo +will return a a null-terminated string containing the canonical name +of the specified hostname in +.Li ai_canonname +of the first +.Dv addrinfo +structure returned. +Setting the +.Dv AI_PASSIVE +bit indicates that the returned socket address structure is intended +for used in a call to +.Xr bind 2 . +In this case, if the hostname argument is a +.Dv NULL +pointer, then the IP address portion of the socket +address structure will be set to +.Dv INADDR_ANY +for an IPv4 address or +.Dv IN6ADDR_ANY_INIT +for an IPv6 address. +.Pp +When +.Li ai_flags +does not set the +.Dv AI_PASSIVE +bit, the returned socket address structure will be ready +for use in a call to +.Xr connect 2 +for a connection-oriented protocol or +.Xr connect 2 , +.Xr sendto 2 , +or +.Xr sendmsg 2 +if a connectionless protocol was chosen. +The IP address portion of the socket address structure will be +set to the loopback address if +.Fa hostname +is a +.Dv NULL +pointer and +.Dv AI_PASSIVE +is not set in +.Li ai_flags . +.Pp +If +.Li ai_flags +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. +.El +.Pp +All other elements of the +.Dv "struct addrinfo" +passed via +.Fa arg +must be zero. +.Pp +If +.Fa arg +is not supplied, a +.Dv NULL +pointer should be given for this argument. +It will be treated as if the caller provided an +.Dv "struct addrinfo" +structure initialized to zero with +.Li ai_family set to +.Li PF_UNSPEC . +.Pp +After a successful call to +.Fn lwres_getaddrinfo , +.Fa *res +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 +the +.Li ai_next +pointer, until a +.Dv NULL +pointer is encountered. +The three members +.Li ai_family , +ai_socktype, +and +.Li ai_protocol +in each +returned +.Dv addrinfo +structure contain the corresponding arguments for a call to +.Xr socket 2 . +For each +.Dv addrinfo +structure in the list, the +.Li ai_addr +member points to a filled-in socket address structure of length +.Li ai_addrlen . +.Pp +All of the information returned by +.Fn lwres_getaddrinfo +is dynamically allocated: the addrinfo structures, and the socket +address structures and canonical host name strings pointed to by the +.Li addrinfo structures. +Memory allocated for the dynamically allocated structures created by +a successful call to +.Fn lwres_getaddrinfo +is released by +.Fn lwres_freeaddrinfo . +.Fa ai +is a pointer to a +.Dv "struct addrinfo" created by a call to +.Fn lwres_getaddrinfo . +.Sh RETURN VALUES +.Fn lwres_getaddrinfo +returns zero on success or one of the error codes listed in +.Xr gai_strerror 3 +if an error occurs. +If both +.Fa hostname +and +.Fa servname +are +.Dv NULL +.Fn lwres_getaddrinfo +returns +.Er EAI_NONAME . +.Sh SEE ALSO +.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 connect 2 , +.Xr sendto 2 , +.Xr sendmsg 2 , +.Xr socket 2 . diff --git a/lib/lwres/man/lwres_getaddrsbyname.3 b/lib/lwres/man/lwres_getaddrsbyname.3 new file mode 100644 index 0000000000..966fb08baa --- /dev/null +++ b/lib/lwres/man/lwres_getaddrsbyname.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getaddrsbyname.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_resutil.3 diff --git a/lib/lwres/man/lwres_gethostbyaddr.3 b/lib/lwres/man/lwres_gethostbyaddr.3 new file mode 100644 index 0000000000..16ea1dbf73 --- /dev/null +++ b/lib/lwres/man/lwres_gethostbyaddr.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyaddr.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_gethostbyaddr_r.3 b/lib/lwres/man/lwres_gethostbyaddr_r.3 new file mode 100644 index 0000000000..310b99d5dc --- /dev/null +++ b/lib/lwres/man/lwres_gethostbyaddr_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyaddr_r.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_gethostbyname.3 b/lib/lwres/man/lwres_gethostbyname.3 new file mode 100644 index 0000000000..4df07f3084 --- /dev/null +++ b/lib/lwres/man/lwres_gethostbyname.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyname.3,v 1.1 2000/06/27 21:53:04 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_gethostbyname2.3 b/lib/lwres/man/lwres_gethostbyname2.3 new file mode 100644 index 0000000000..21d9510c28 --- /dev/null +++ b/lib/lwres/man/lwres_gethostbyname2.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyname2.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_gethostbyname_r.3 b/lib/lwres/man/lwres_gethostbyname_r.3 new file mode 100644 index 0000000000..278899488d --- /dev/null +++ b/lib/lwres/man/lwres_gethostbyname_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostbyname_r.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_gethostent.3 b/lib/lwres/man/lwres_gethostent.3 new file mode 100644 index 0000000000..ee7837d5c5 --- /dev/null +++ b/lib/lwres/man/lwres_gethostent.3 @@ -0,0 +1,406 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostent.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GETHOSTENT 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_gethostbyname , +.Nm lwres_gethostbyname2 , +.Nm lwres_gethostbyaddr , +.Nm lwres_gethostent , +.Nm lwres_sethostent , +.Nm lwres_endhostent , +.Nm lwres_gethostbyname_r , +.Nm lwres_gethostbyaddr_r , +.Nm lwres_gethostent_r , +.Nm lwres_sethostent_r , +.Nm lwres_endhostent_r +.Nd lightweight resolver get network host entry +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft struct hostent * +.Fo lwres_gethostbyname +.Fa "const char *name" +.Fc +.Ft struct hostent * +.Fo lwres_gethostbyname2 +.Fa "const char *name" +.Fa "int af" +.Fc +.Ft struct hostent * +.Fo lwres_gethostbyaddr +.Fa "const char *addr" +.Fa "int len" +.Fa "int type" +.Fc +.Ft struct hostent * +.Fo lwres_gethostent +.Fa "void" +.Fc +.Ft void +.Fo lwres_sethostent +.Fa "int stayopen" +.Fc +.Ft void +.Fo lwres_endhostent +.Fa "void" +.Fc +.Ft struct hostent * +.Fo lwres_gethostbyname_r +.Fa "const char *name" +.Fa "struct hostent *resbuf" +.Fa "char *buf" +.Fa "int buflen" +.Fa "int *error" +.Fc +.Ft struct hostent * +.Fo lwres_gethostbyaddr_r +.Fa "const char *addr" +.Fa "int len" +.Fa "int type" +.Fa "struct hostent *resbuf" +.Fa "char *buf" +.Fa "int buflen" +.Fa "int *error" +.Fc +.Ft struct hostent * +.Fo lwres_gethostent_r +.Fa "struct hostent *resbuf" +.Fa "char *buf" +.Fa "int buflen" +.Fa "int *error" +.Fc +.Ft void +.Fo lwres_sethostent_r +.Fa "int stayopen" +.Fc +.Ft void +.Fo lwres_endhostent_r +.Fa "void" +.Fc +.Sh DESCRIPTION +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 +.Xr gethostent 3 +functions provided by as part of the standard system software. +They use a +.Dv "struct hostent" +which is usually defined in +.Pa namedb.h . +.Bd -literal +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +.Ed +.Pp +The members of this structure are: +.Bl -tag -width h_addr_list +.It Li h_name +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 - +.Dv PF_INET +or +.Dv PF_INET6 . +.It Li h_length +The length of the address in bytes. +.It Li h_addr_list +A +.Dv NULL +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_gethostent , +.Fn lwres_sethostent , +.Fn lwres_endhostent , +.Fn lwres_gethostent_r , +.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 . +.Pp +.Fn lwres_gethostbyname +and +.Fn lwres_gethostbyname2 +lookup the hostname +.Fa name . +.Fn lwres_gethostbyname +always looks for an IPv4 address while +.Fn lwres_gethostbyname2 +looks for an address of protocol family +.Fa af : +either +.Dv PF_INET +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. +.Dv NULL +is returned if the lookups by +.Fn lwres_gethostbyname +or +.Fn lwres_gethostbyname2 +fail. +.Pp +Reverse lookups of addresses are performed by +.Fn lwres_gethostbyaddr . +.Fa addr +is an address of length +.Fa len +bytes and protocol family +.Fa type - +.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 +.Fa *error . +.Fa resbuf +is a pointer to a +.Dv "struct hostent" +which is initialised by a successful call to +.Fn lwres_gethostbyname_r . +.Fa buf +is a buffer of length +.Fa len +bytes which is used to store the +.Li h_name , +.Li h_aliases , +and +.Li h_addr_list +elements of the +.Dv "struct hostent" +returned in +.Fa resbuf . +Successful calls to +.Fn lwres_gethostbyname_r +return +.Fa resbuf , +which is a pointer to the +.Fn "struct hostent" +it created. +.Pp +.Fn lwres_gethostbyaddr_r +is a thread-safe function that performs a reverse lookup of address +.Fa addr +which is +.Fa len +bytes long +and is of protocol family +.Fa type - +.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 +.Fa *error . +Like +The other function parameters are identical to those in +.Fn lwres_gethostbyname_r . +.Fa resbuf +is a pointer to a +.Dv "struct hostent" +which is initialised by a successful call to +.Fn lwres_gethostbyaddr_r . +.Fa buf +is a buffer of length +.Fa len +bytes which is used to store the +.Li h_name , +.Li h_aliases , +and +.Li h_addr_list +elements of the +.Dv "struct hostent" +returned in +.Fa resbuf . +Successful calls to +.Fn lwres_gethostbyaddr_r +return +.Fa resbuf , +which is a pointer to the +.Fn "struct hostent" +it created. +.Sh RETURN VALUES +.Pp +The functions +.Fn lwres_gethostbyname , +.Fn lwres_gethostbyname2 , +.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 +.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: +.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 +.It Li NO_ADDRESS +no address, so look for MX record +.El +.Xr lwres_hstrerror 3 +translates these error codes to suitable error messages. +.Pp +.Fn lwres_gethostent +and +.Fn lwres_gethostent_r +always return +.Dv NULL . +.Pp +Successful calls to +.Fn lwres_gethostbyname_r +and +.Fn lwres_gethostbyaddr_r +return +.Fa resbuf , +a pointer to the +.Dv "struct hostent" +that was initialised by these functions. +They return +.Dv NULL +if the lookups fail +or if +.Fa buf +was too small to hold the list of addresses and names referenced by +the +.Li h_name , +.Li h_aliases , +and +.Li h_addr_list +elements of the +.Dv "struct hostent" . +If +.Fa buf +was too small, both +.Fn lwres_gethostbyname_r +and +.Fn lwres_gethostbyaddr_r +set the global variable +.DV errno +to +.Er ERANGE . +.Sh SEE ALSO +.Xr gethostent 3 , +.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 +Thread-safe versions for name and address lookup are provided by +.Fn lwres_gethostbyname_r , +and +.Fn lwres_gethostbyaddr_r +respectively. +.Pp +Although the above functions can be considered as drop-in replacements +for their equivalents in the system software, there are limitations. +The functions that are documented here only use the BIND9 lighweight +resolver daemon +That implies that they only use the DNS for host and address lookups. +Therefore these functions do not perform lookups in +.Pa /etc/hosts +or in +.Dv NIS/YP +or +.Dv NIS+ +maps which could be supported by the operating system's +.Xr gethostent 3 +functions. diff --git a/lib/lwres/man/lwres_gethostent_r.3 b/lib/lwres/man/lwres_gethostent_r.3 new file mode 100644 index 0000000000..dded33aa6a --- /dev/null +++ b/lib/lwres/man/lwres_gethostent_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gethostent_r.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_getipnode.3 b/lib/lwres/man/lwres_getipnode.3 new file mode 100644 index 0000000000..9da2263476 --- /dev/null +++ b/lib/lwres/man/lwres_getipnode.3 @@ -0,0 +1,231 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getipnode.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GETIPNODE 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_getipnodebyname , +.Nm lwres_getipnodebyaddr , +.Nm lwres_freehostent +.Nd lookup functions for the lightweight resolver +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft struct hostent * +.Fo lwres_getipnodebyname +.Fa "const char *name" +.Fa "int af" +.Fa "int flags" +.Fa "int *error_num" +.Fc +.Ft struct hostent * +.Fo lwres_getipnodebyaddr +.Fa "const void *src" +.Fa "size_t len" +.Fa "int af" +.Fa "int *error_num" +.Fc +.Ft void +.Fo lwres_freehostent +.Fa "struct hostent *he" +.Fc +.Sh DESCRIPTION +These functions use a +.Dv "struct hostent" +which is usually defined in +.Pa namedb.h . +.Bd -literal +struct hostent { + char *h_name; /* official name of host */ + char **h_aliases; /* alias list */ + int h_addrtype; /* host address type */ + int h_length; /* length of address */ + char **h_addr_list; /* list of addresses from name server */ +}; +#define h_addr h_addr_list[0] /* address, for backward compatibility */ +.Ed +.Pp +The members of this structure are: +.Bl -tag -width h_addr_list +.It Li h_name +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 - +.Dv PF_INET +or +.Dv PF_INET6 . +.It Li h_length +The length of the address in bytes. +.It Li h_addr_list +A +.Dv NULL +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 . +The +.Fa flags +parameter sets bits that indicate how IPv6 and IPv4 addresses +should presented. +The value of those flags are: +.Bl -tag -width AI_ADDRCONFIG +.It Li AI_V4MAPPED +return an IPv4 address mapped to an IPv6 address +.It Li AI_ALL +return all possible addresses +.It Li AI_ADDRCONFIG +only return an IPv6 or IPv4 address if here is an active network +interface of that type. +.It Li AI_DEFAULT +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 +of address +.Fa src +which is +.Fa len +bytes long. +.Fa af +denotes the protocol family: +.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 +the +.Dv "struct hostent" +pointer +.Fa he . +Any memory allocated for the +.Li h_name , +.Li h_addr_list +and +.Li h_aliases +is freed, as is the memory for the +.Dv hostent +structure itself. +.Sh RETURN VALUES +If an error occurs, +.Fn lwres_getipnodebyname +and +.Fn lwres_getipnodebyaddr +set +.Fa *error_num +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 . +.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 +.It Li NO_ADDRESS +no address, so look for MX record +.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 lwres_hstrerror 3 . + diff --git a/lib/lwres/man/lwres_getipnodebyaddr.3 b/lib/lwres/man/lwres_getipnodebyaddr.3 new file mode 100644 index 0000000000..c77c430d74 --- /dev/null +++ b/lib/lwres/man/lwres_getipnodebyaddr.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getipnodebyaddr.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_getipnode.3 diff --git a/lib/lwres/man/lwres_getipnodebyname.3 b/lib/lwres/man/lwres_getipnodebyname.3 new file mode 100644 index 0000000000..2583c19805 --- /dev/null +++ b/lib/lwres/man/lwres_getipnodebyname.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getipnodebyname.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_getipnode.3 diff --git a/lib/lwres/man/lwres_getnamebyaddr.3 b/lib/lwres/man/lwres_getnamebyaddr.3 new file mode 100644 index 0000000000..43f6cbb11b --- /dev/null +++ b/lib/lwres/man/lwres_getnamebyaddr.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getnamebyaddr.3,v 1.1 2000/06/27 21:53:05 jim Exp $ +.\" +.so lwres_resutil.3 diff --git a/lib/lwres/man/lwres_getnameinfo.3 b/lib/lwres/man/lwres_getnameinfo.3 new file mode 100644 index 0000000000..64fa126a29 --- /dev/null +++ b/lib/lwres/man/lwres_getnameinfo.3 @@ -0,0 +1,145 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_getnameinfo.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GETNAMEINFO 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_getnameinfo +.Nd lightweight resolver socket address structure to hostname and service name +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft int +.Fo lwres_getnameinfo +.Fa "const struct sockaddr *sa" +.Fa "size_t salen" +.Fa "char *host" +.Fa "size_t hostlen" +.Fa "char *serv" +.Fa "size_t servlen" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Pp +This function is equivalent to the +.Xr getnameinfo 3 +function defined in RFC2133. +.Fn lwres_getnameinfo +returns the hostname for the +.Dv "struct sockaddr" +.Fa sa +which is +.Fa salen +bytes long. +The hostname is of length +.Fa hostlen +and is returned via +.Fa *host. +The maximum length of the hostname is +1025 bytes: +.Li NI_MAXHOST . +.Pp +The name of the service associated with the port number in +.Fa sa +is returned in +.Fa *serv. +It is +.Fa servlen +bytes long. +The maximum length of the service name is +.Li NI_MAXSERV +- 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. +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. +.It Li NI_NAMEREQ +a name is required. If the hostname cannot be found in the DNS and +this flag is set, an error - +.Er ENI_NOHOSTNAME +- is returned. +.It Li NI_NUMERICSERV +service name is returned as a digit string representing the port number. +.It Li NI_DGRAM +the service uses a datagram transport protocol +.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 wres_getnameinfo +returns 0 on success or a non-zero error code if an error occurs. +The error codes are: +.Bl -tag -width ENI_NOSERVNAME +.It Li ENI_NOSOCKET +there was no socket in +.Fa sa +\fBBUT ENI_NOSOCKET IS ZERO!!!!\fP +.It Li ENI_NOSERVNAME +no service name was found +.It Li ENI_NOHOSTNAME +no hostname was found +.It Li ENI_MEMORY +memory could not be allocated +.It Li ENI_SYSTEM +a system error occurred +.It Li ENI_FAMILY +an unsupported protocol family was requested +.It Li ENI_SALEN +.Fa salen +is the wrong number of bytes for the address in +.Fa sa . +.Sh SEE ALSO +.Xr 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 . diff --git a/lib/lwres/man/lwres_gnba.3 b/lib/lwres/man/lwres_gnba.3 new file mode 100644 index 0000000000..8f4279870c --- /dev/null +++ b/lib/lwres/man/lwres_gnba.3 @@ -0,0 +1,201 @@ +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnba.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_GNBA 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_gnbarequest_render , +.Nm lwres_gnbaresponse_render , +.Nm lwres_gnbarequest_parse , +.Nm lwres_gnbaresponse_parse , +.Nm lwres_gnbaresponse_free , +.Nm lwres_gnbarequest_free +.Nd lightweight resolver getnamebyaddress functions +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_gnbarequest_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_gnbarequest_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_gnbaresponse_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_gnbaresponse_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_gnbarequest_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_gnbarequest_t **structp" +.Fc +.Ft lwres_result_t +.Fo lwres_gnbaresponse_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_gnbaresponse_t **structp" +.Fc +.Ft void +.Fo lwres_gnbaresponse_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_gnbaresponse_t **structp" +.Fc +.Ft void +.Fo lwres_gnbarequest_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_gnbarequest_t **structp" +.Fc +.Sh DESCRIPTION +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. +.Pp +There are four main functions for the getnamebyaddr opcode. +One render function converts a getnamebyaddr request structure - +.Dv lwres_gnbarequest_t - +to the lighweight resolver's canonical format. +It is complemented by a parse function that converts a packet in this +canonical format to a getnamebyaddr request structure. +Another render function converts the getnamebyaddr response structure - +.Dv lwres_gnbaresponse_t +to the canonical format. +This is complemented by a parse function which converts a packet in +canonical format to a getnamebyaddr response structure. +.Pp +These structures are defined in +.Pa lwres/lwres.h . +They are shown below. +.Bd -literal -offset indent +#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U + +typedef struct { + lwres_uint32_t flags; + lwres_addr_t addr; +} lwres_gnbarequest_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + void *base; + size_t baselen; +} lwres_gnbaresponse_t; +.Ed +.Pp +.Fn lwres_gnbarequest_render +uses resolver context +.Fa ctx +to convert getnamebyaddr request structure +.Fa req +to canonical format. +The packet header structure +.Fa pkt +is initialised and transferred to +buffer +.Fa b . +The contents of +.Fa *req +are then appended to the buffer in canonical format. +.Fn lwres_gnbaresponse_render +performs the same task, except it converts a getnamebyaddr response structure +.Dv lwres_gnbaresponse_t +to the lightweight resolver's canonical format. +.Pp +.Fn lwres_gnbarequest_parse +uses context +.Fa ctx +to convert the contents of packet +.Fa pkt +to a +.Dv lwres_gnbarequest_t +structure. +Buffer +.Fa b +provides space to be used for storing this structure. +When the function succeeds, the resulting +.Dv lwres_gnbarequest_t +is made available through +.Fa *structp . +.Fn lwres_gnbaresponse_parse +offers the same semantics as +.Fn lwres_gnbarequest_parse +except it yields a +.Dv lwres_gnbaresponse_t +structure. +.Pp +.Fn lwres_gnbaresponse_free +and +.Fn lwres_gnbarequest_free +release the memory in resolver context +.Fa ctx +that was allocated to the +.Dv lwres_gnbaresponse_t +or +.Dv lwres_gnbarequest_t +structures referenced via +.Fa structp . +Any memory associated with ancillary buffers and strings for those +structures is also discarded. +.Sh RETURN VALUES +The getnamebyaddr opcode functions +.Fn lwres_gnbarequest_render , +.Fn lwres_gnbaresponse_render +.Fn lwres_gnbarequest_parse +and +.Fn lwres_gnbaresponse_parse +all return +.Er LWRES_R_SUCCESS +on success. +They return +.Er LWRES_R_NOMEMORY +if memory allocation fails. +.Er LWRES_R_UNEXPECTEDEND +is returned if the available space in the buffer +.Fa b +is too small to accommodate the packet header or the +.Dv lwres_gnbarequest_t +and +.Dv lwres_gnbaresponse_t +structures. +.Fn lwres_gnbarequest_parse +and +.Fn lwres_gnbaresponse_parse +will return +.Er LWRES_R_UNEXPECTEDEND +if the buffer is not empty after decoding the received packet. +These functions will return +.Er LWRES_R_FAILURE +if +.Li pktflags +in the packet header structure +.Dv lwres_lwpacket_t +indicate that the packet is not a response to an earlier query. +.Sh SEE ALSO +.Xr lwres_packet 3 diff --git a/lib/lwres/man/lwres_gnbarequest_free.3 b/lib/lwres/man/lwres_gnbarequest_free.3 new file mode 100644 index 0000000000..14ca78b3ee --- /dev/null +++ b/lib/lwres/man/lwres_gnbarequest_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbarequest_free.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/lib/lwres/man/lwres_gnbarequest_parse.3 b/lib/lwres/man/lwres_gnbarequest_parse.3 new file mode 100644 index 0000000000..3f0821a198 --- /dev/null +++ b/lib/lwres/man/lwres_gnbarequest_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbarequest_parse.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/lib/lwres/man/lwres_gnbarequest_render.3 b/lib/lwres/man/lwres_gnbarequest_render.3 new file mode 100644 index 0000000000..b952905a17 --- /dev/null +++ b/lib/lwres/man/lwres_gnbarequest_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbarequest_render.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/lib/lwres/man/lwres_gnbaresponse_free.3 b/lib/lwres/man/lwres_gnbaresponse_free.3 new file mode 100644 index 0000000000..5fee56d5fd --- /dev/null +++ b/lib/lwres/man/lwres_gnbaresponse_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbaresponse_free.3,v 1.1 2000/06/27 21:53:06 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/lib/lwres/man/lwres_gnbaresponse_parse.3 b/lib/lwres/man/lwres_gnbaresponse_parse.3 new file mode 100644 index 0000000000..b75ac1780a --- /dev/null +++ b/lib/lwres/man/lwres_gnbaresponse_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbaresponse_parse.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/lib/lwres/man/lwres_gnbaresponse_render.3 b/lib/lwres/man/lwres_gnbaresponse_render.3 new file mode 100644 index 0000000000..b518bf849e --- /dev/null +++ b/lib/lwres/man/lwres_gnbaresponse_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_gnbaresponse_render.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.so lwres_gnba.3 diff --git a/lib/lwres/man/lwres_herror.3 b/lib/lwres/man/lwres_herror.3 new file mode 100644 index 0000000000..83d69a4ad1 --- /dev/null +++ b/lib/lwres/man/lwres_herror.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_herror.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.so lwres_hstrerror.3 diff --git a/lib/lwres/man/lwres_hstrerror.3 b/lib/lwres/man/lwres_hstrerror.3 new file mode 100644 index 0000000000..df3592d1da --- /dev/null +++ b/lib/lwres/man/lwres_hstrerror.3 @@ -0,0 +1,72 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_hstrerror.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_ERROR 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_herror , +.Nm lwres_hstrerror +.Nd lightweight resolver error message generation +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft void +.Fo lwres_herror +.Fa "const char *s" +.Fc +.Ft const char * +.Fo lwres_hstrerror +.Fa "int err" +.Fc +.Sh DESCRIPTION +.Fn lwres_herror +prints the string +.Fa s +on +.Dv stderr +followed by the string generated by +.Fn lwres_hstrerror +for the error code stored in the global variable +.Li lwres_h_errno . +.Pp +.Fn lwres_hstrerror +returns an appropriate string for the error code gievn by +.Fa err . +The values of the error codes and messages are as follows: +.Bl -tag -width HOST_NOT_FOUND +.It Li NETDB_SUCCESS +\*qResolver Error 0 (no error)\*q +.It Li HOST_NOT_FOUND +\*qUnknown host\*q +.It Li TRY_AGAIN +\*qHost name lookup failure\*q +.It Li NO_RECOVERY +\*qUnknown server error\*q +.It Li NO_DATA +\*qNo address associated with name\*q +.Sh RETURN VALUES +The string \*qUnknown resolver error\*q is returned by +.Fn lwres_hstrerror +when the value of +.Li lwres_h_errno +is not a valid error code. +.Sh SEE ALSO +.Xr herror 3 , +.Xr lwres_hstrerror 3 . diff --git a/lib/lwres/man/lwres_inetntop.3 b/lib/lwres/man/lwres_inetntop.3 new file mode 100644 index 0000000000..4e9b61aedc --- /dev/null +++ b/lib/lwres/man/lwres_inetntop.3 @@ -0,0 +1,72 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_inetntop.3,v 1.1 2000/06/27 21:53:07 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_INETNTOP 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_net_ntop +.Nd lightweight resolver IP address presentation +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft const char * +.Fo lwres_net_ntop +.Fa "int af" +.Fa "const void *src" +.Fa "char *dst" +.Fa "size_t size" +.Fc +.Sh DESCRIPTION +.Fn lwres_net_ntop +converts an IP address of protocol family +.Fa af +- IPv4 or IPv6 - at location +.Fa 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. +.Pp +The generated string is copied to +.Fa dst +provided +.Fa size +indicates it is long enough to store the ASCII representation +of the address. +.Sh RETURN VALUES +.Pp +If successful, the function returns +.Fa dst : +a pointer to a string containing +the presentation format of the address. +.Fn lwres_net_ntop +returns +.Dv NULL +and sets the global variable +.Li errno +to +.Er EAFNOSUPPORT +if the protocol family given in +.Fa af +is not supported. +.Sh SEE ALSO +.Xr RFC1884 , +.Xr inet_ntop 3 , +.Xr errno 3 . diff --git a/lib/lwres/man/lwres_lwpacket_parseheader.3 b/lib/lwres/man/lwres_lwpacket_parseheader.3 new file mode 100644 index 0000000000..0301fc8196 --- /dev/null +++ b/lib/lwres/man/lwres_lwpacket_parseheader.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_lwpacket_parseheader.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_packet.3 diff --git a/lib/lwres/man/lwres_lwpacket_renderheader.3 b/lib/lwres/man/lwres_lwpacket_renderheader.3 new file mode 100644 index 0000000000..252580ad01 --- /dev/null +++ b/lib/lwres/man/lwres_lwpacket_renderheader.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_lwpacket_renderheader.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_packet.3 diff --git a/lib/lwres/man/lwres_net_ntop.3 b/lib/lwres/man/lwres_net_ntop.3 new file mode 100644 index 0000000000..5278ce91fb --- /dev/null +++ b/lib/lwres/man/lwres_net_ntop.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_net_ntop.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_inetntop.3 diff --git a/lib/lwres/man/lwres_noop.3 b/lib/lwres/man/lwres_noop.3 new file mode 100644 index 0000000000..4353dfd2d8 --- /dev/null +++ b/lib/lwres/man/lwres_noop.3 @@ -0,0 +1,199 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_noop.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_NOOP 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_nooprequest_render , +.Nm lwres_noopresponse_render , +.Nm lwres_nooprequest_parse , +.Nm lwres_noopresponse_parse , +.Nm lwres_noopresponse_free , +.Nm lwres_nooprequest_free +.Nd lightweight resolver no-op functions +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_nooprequest_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_nooprequest_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_noopresponse_render +.Fa "lwres_context_t *ctx" +.Fa "lwres_noopresponse_t *req" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_buffer_t *b" +.Fc +.Ft lwres_result_t +.Fo lwres_nooprequest_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_nooprequest_t **structp" +.Fc +.Ft lwres_result_t +.Fo lwres_noopresponse_parse +.Fa "lwres_context_t *ctx" +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fa "lwres_noopresponse_t **structp" +.Fc +.Ft void +.Fo lwres_noopresponse_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_noopresponse_t **structp" +.Fc +.Ft void +.Fo lwres_nooprequest_free +.Fa "lwres_context_t *ctx" +.Fa "lwres_nooprequest_t **structp" +.Fc +.Sh DESCRIPTION +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. +The opcode is intended to allow a client to determine if the server is +operational or not. +.Pp +There are four main functions for the no-op opcode. +One render function converts a no-op request structure - +.Dv lwres_nooprequest_t - +to the lighweight resolver's canonical format. +It is complemented by a parse function that converts a packet in this +canonical format to a no-op request structure. +Another render function converts the no-op response structure - +.Dv lwres_noopresponse_t +to the canonical format. +This is complemented by a parse function which converts a packet in +canonical format to a no-op response structure. +.Pp +These structures are defined in +.Pa lwres/lwres.h . +They are shown below. +.Bd -literal -offset indent +#define LWRES_OPCODE_NOOP 0x00000000U + +typedef struct { + lwres_uint16_t datalength; + unsigned char *data; +} lwres_nooprequest_t; + +typedef struct { + lwres_uint16_t datalength; + unsigned char *data; +} lwres_noopresponse_t; +.Ed +Although the structures have different types, they are identical. +This is because the no-op opcode simply echos whatever data was sent: +the response is therefore identical to the request. +.Pp +.Fn lwres_nooprequest_render +uses resolver context +.Fa ctx +to convert no-op request structure +.Fa req +to canonical format. +The packet header structure +.Fa pkt +is initialised and transferred to +buffer +.Fa b . +The contents of +.Fa *req +are then appended to the buffer in canonical format. +.Fn lwres_noopresponse_render +performs the same task, except it converts a no-op response structure +.Dv lwres_noopresponse_t +to the lightweight resolver's canonical format. +.Pp +.Fn lwres_nooprequest_parse +uses context +.Fa ctx +to convert the contents of packet +.Fa pkt +to a +.Dv lwres_nooprequest_t +structure. +Buffer +.Fa b +provides space to be used for storing this structure. +When the function succeeds, the resulting +.Dv lwres_nooprequest_t +is made available through +.Fa *structp . +.Fn lwres_noopresponse_parse +offers the same semantics as +.Fn lwres_nooprequest_parse +except it yields a +.Dv lwres_noopresponse_t +structure. +.Pp +.Fn lwres_noopresponse_free +and +.Fn lwres_nooprequest_free +release the memory in resolver context +.Fa ctx +that was allocated to the +.Dv lwres_noopresponse_t +or +.Dv lwres_nooprequest_t +structures referenced via +.Fa structp . +.Sh RETURN VALUES +The no-op opcode functions +.Fn lwres_nooprequest_render , +.Fn lwres_noopresponse_render +.Fn lwres_nooprequest_parse +and +.Fn lwres_noopresponse_parse +all return +.Er LWRES_R_SUCCESS +on success. +They return +.Er LWRES_R_NOMEMORY +if memory allocation fails. +.Er LWRES_R_UNEXPECTEDEND +is returned if the available space in the buffer +.Fa b +is too small to accommodate the packet header or the +.Dv lwres_nooprequest_t +and +.Dv lwres_noopresponse_t +structures. +.Fn lwres_nooprequest_parse +and +.Fn lwres_noopresponse_parse +will return +.Er LWRES_R_UNEXPECTEDEND +if the buffer is not empty after decoding the received packet. +These functions will return +.Er LWRES_R_FAILURE +if +.Li pktflags +in the packet header structure +.Dv lwres_lwpacket_t +indicate that the packet is not a response to an earlier query. +.Sh SEE ALSO +.Xr lwres_packet 3 diff --git a/lib/lwres/man/lwres_nooprequest_free.3 b/lib/lwres/man/lwres_nooprequest_free.3 new file mode 100644 index 0000000000..fc29a3265f --- /dev/null +++ b/lib/lwres/man/lwres_nooprequest_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_nooprequest_free.3,v 1.1 2000/06/27 21:53:08 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/lib/lwres/man/lwres_nooprequest_parse.3 b/lib/lwres/man/lwres_nooprequest_parse.3 new file mode 100644 index 0000000000..5257e15f57 --- /dev/null +++ b/lib/lwres/man/lwres_nooprequest_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_nooprequest_parse.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/lib/lwres/man/lwres_nooprequest_render.3 b/lib/lwres/man/lwres_nooprequest_render.3 new file mode 100644 index 0000000000..9cd9d97cf2 --- /dev/null +++ b/lib/lwres/man/lwres_nooprequest_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_nooprequest_render.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/lib/lwres/man/lwres_noopresponse_free.3 b/lib/lwres/man/lwres_noopresponse_free.3 new file mode 100644 index 0000000000..54c2ca880e --- /dev/null +++ b/lib/lwres/man/lwres_noopresponse_free.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_noopresponse_free.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/lib/lwres/man/lwres_noopresponse_parse.3 b/lib/lwres/man/lwres_noopresponse_parse.3 new file mode 100644 index 0000000000..63693ef464 --- /dev/null +++ b/lib/lwres/man/lwres_noopresponse_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_noopresponse_parse.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/lib/lwres/man/lwres_noopresponse_render.3 b/lib/lwres/man/lwres_noopresponse_render.3 new file mode 100644 index 0000000000..e46c8a5db6 --- /dev/null +++ b/lib/lwres/man/lwres_noopresponse_render.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_noopresponse_render.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.so lwres_noop.3 diff --git a/lib/lwres/man/lwres_packet.3 b/lib/lwres/man/lwres_packet.3 new file mode 100644 index 0000000000..50e596e9ed --- /dev/null +++ b/lib/lwres/man/lwres_packet.3 @@ -0,0 +1,146 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_packet.3,v 1.1 2000/06/27 21:53:09 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_PACKET 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_lwpacket_renderheader , +.Nm lwres_lwpacket_parseheader +.Nd lightweight resolver packet handling functions +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_lwpacket_renderheader +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fc +.Ft lwres_result_t +.Fo lwres_lwpacket_parseheader +.Fa "lwres_buffer_t *b" +.Fa "lwres_lwpacket_t *pkt" +.Fc +.Sh DESCRIPTION +These functions rely on a +.Dv "struct lwres_lwpacket" +which is defined in +.Pa lwres/lwpacket.h . +.Bd -literal -offset indent +typedef struct lwres_lwpacket lwres_lwpacket_t; + +struct lwres_lwpacket { + lwres_uint32_t length; + lwres_uint16_t version; + lwres_uint16_t pktflags; + lwres_uint32_t serial; + lwres_uint32_t opcode; + lwres_uint32_t result; + lwres_uint32_t recvlength; + lwres_uint16_t authtype; + lwres_uint16_t authlength; +}; +.Ed +.Pp +The elements of this structure are: +.Bl -tag -width recvlength +.It Li length +the overall packet length, including the entire packet header +.It Li version +the header format. There is currently only one format, +.Dv LWRES_LWPACKETVERSION_0 . +.It Li pktflags +library-defined flags for this packet: for instance whether the packet +is a request or a reply. Flag values can be set, but not defined by +the caller. +.It Li serial +is set by the requestor and is returned in all replies. If two or more +packets from the same source have the same serial number and are from +the same source, they are assumed to be duplicates and the latter ones +may be dropped. +.It Li opcode +indicates the operation. +Opcodes between 0x00000000 and 0x03ffffff are +reserved for use by the lightweight resolver library. Opcodes between +0x04000000 and 0xffffffff are application defined. +.It Li result +is only valid for replies. +Results between 0x04000000 and 0xffffffff are application defined. +Results between 0x00000000 and 0x03ffffff are reserved for library use. +.It Li recvlength +is the maximum buffer size that the receiver can handle on requests +and the size of the buffer needed to satisfy a request when the buffer is too large for replies +.It Li authtype +defines the packet level authentication that is used. +Authorisation types between 0x1000 and 0xffff are application defined +and types between 0x0000 and 0x0fff are reserved for library use. +Currently these are not used and must be zero. +.It Li authlen +gives the length of the authentication data. +Since packet authentication is currently not used, this must be zero. +.El +The following opcodes are currently defined: +.Bl -tag -width GETADDRSBYNAME +.It Li NOOP +Success is always returned and the packet contents are echoed. +.It Li GETADDRSBYNAME +returns all known addresses for a given name +.It Li GETNAMEBYADDR +return the hostname for the given address +.El +.Pp +.Fn lwres_lwpacket_renderheader +transfers the contents of lightweight resolver packet structure +.Dv lwres_lwpacket_t +.Fa *pkt +in network byte order to the lightweight resolver buffer, +.Fa *b . +.Pp +.Fn lwres_lwpacket_parseheader +performs the converse operation. +It transfers data in network byte order from buffer +.Fa *b +to resolver packet +.Fa *pkt . +The contents of the buffer +.Fa b +should correspond to a +.Dv "struct lwres_lwpacket" . +.Pp +Both functions have assertion checks to ensure that +.Fa b +and +.Fa pkt +are not +.Dv NULL . +.Sh RETURN VALUES +Successful calls to +.Fn lwres_lwpacket_renderheader +and +.Fn lwres_lwpacket_parseheader +return +.Er LWRES_R_SUCCESS . +If there is insufficient space to copy data between the buffer +.Fa *b +and lightweight resolver packet +.Fa *pkt +both functions return +.Er LWRES_R_UNEXPECTEDEND . diff --git a/lib/lwres/man/lwres_resutil.3 b/lib/lwres/man/lwres_resutil.3 new file mode 100644 index 0000000000..eb1aaf0253 --- /dev/null +++ b/lib/lwres/man/lwres_resutil.3 @@ -0,0 +1,216 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_resutil.3,v 1.1 2000/06/27 21:53:10 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt LWRES_RESUTIL 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm lwres_string_parse , +.Nm lwres_addr_parse , +.Nm lwres_getaddrsbyname , +.Nm lwres_getnamebyaddr +.Nd lightweight resolver utility functions +.Sh SYNOPSIS +.Fd #include +.Fd +.Ft lwres_result_t +.Fo lwres_string_parse +.Fa "lwres_buffer_t *b" +.Fa "char **c" +.Fa "lwres_uint16_t *len" +.Fc +.Ft lwres_result_t +.Fo lwres_addr_parse +.Fa "lwres_buffer_t *b" +.Fa "lwres_addr_t *addr" +.Fc +.Ft lwres_result_t +.Fo lwres_getaddrsbyname +.Fa "lwres_context_t *ctx" +.Fa "const char *name" +.Fa "lwres_uint32_t addrtypes" +.Fa "lwres_gabnresponse_t **structp" +.Fc +.Ft lwres_result_t +.Fo lwres_getnamebyaddr +.Fa "lwres_context_t *ctx" +.Fa "lwres_uint32_t addrtype" +.Fa "lwres_uint16_t addrlen" +.Fa "const unsigned char *addr" +.Fa "lwres_gnbaresponse_t **structp" +.Fc +.Sh DESCRIPTION +.Fn lwres_string_parse +retrieves a DNS-encoded string starting the current pointer of +lightweight resolver buffer +.Fa b : +i.e. +.Li b->current . +When the function returns, the address of the first byte of the +encoded string is returned via +.Fa *c +and the length of that string is given by +.Fa *len . +The buffer's current pointer is advanced to point at the character +following the string length, the encoded string, and the trailing +.Dv NULL +character. +.Fn lwres_string_parse +has an assertion check that +.Fa b +is not +.Dv NULL . +.Pp +.Fn lwres_addr_parse +extracts an address from the buffer +.Fa b . +It checks that +.Fa addr +is not null. +The buffer's current pointer +.Li b->current +is presumed to point at an encoded address: the address preceded by a +32-bit protocol family identifier and a 16-bit length field. +The encoded address is copied to +.Li addr->address +and +.Li addr->length +indicates the size in bytes of the address that was copied. +.Li b->current +is advanced to point at the next byte of available data in the buffer +following the encoded address. +.Pp +.Fn lwres_getaddrsbyname +and +.Fn lwres_getnamebyaddr +use the +.Dv "lwres_gnbaresponse_t" +structure defined below: +.Bd -literal -offset indent +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + lwres_uint16_t naddrs; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + lwres_addrlist_t addrs; + void *base; + size_t baselen; +} lwres_gabnresponse_t; +.Ed +The contents of this structure are not manipulated directly but +they are controlled through the +.Xr lwres_gabn 3 +functions. +.Pp +The lightweight resolver uses +.Fn lwres_getaddrsbyname +to perform foward lookups. +Hostname +.Fa name +is looked up using the resolver context +.Fa ctx +for memory allocation. +.Fa addrtypes +is a bitmask indicating which type of addresses are to be looked up. +Current values for this bitmask are +.Dv LWRES_ADDRTYPE_V4 +for IPv4 addresses and +.Dv LWRES_ADDRTYPE_V6 +for IPv6 addresses. +Results of the lookup are returned in +.Fa *structp . +.Fn lwres_getaddrsbyname +checks that its pointer arguments are not +.Dv NULL +and that +.Fa addrtypes +is non-zero. +.Pp +.Fn lwres_getnamebyaddr +performs reverse lookups. +Resolver context +.Fa ctx +is used for memory allocation. +The address type is indicated by +.Fa addrtype : +.Dv LWRES_ADDRTYPE_V4 +or +.Dv LWRES_ADDRTYPE_V6 . +The address to be looked up is given by +.Fa addr +and its length is +.Fa addrlen +bytes. +The result of the function call is made available through +.Fa *structp . +Like +.Fn lwres_getaddrsbyname , +.Fn lwres_getnamebyaddr +uses assertion checking to ensure its pointer arguments are not +.Dv NULL +and +.Fa addrtype +is not zero. +.Fn lwres_getaddrsbyname +also checks that +.Fa addrlen +is non-zero. +.Sh RETURN VALUES +Successful calls to +.Fn lwres_string_parse +and +.Fn lwres_addr_parse +return +.Er LWRES_R_SUCCESS. +Both functions return +.Er LWRES_R_FAILURE +if the buffer is corrupt or +.Er LWRES_R_UNEXPECTEDEND +if the buffer has less space than expected for the components of the +encoded string or address. +.Pp +.Fn lwres_getaddrsbyname +returns +.Er LWRES_R_SUCCESS +on success and it returns +.Er LWRES_R_NOTFOUND +if the hostname +.Fa name +could not be found. +.Pp +.Er LWRES_R_SUCCESS +is returned by a successful call to +.Fn lwres_getnamebyaddr . +.Pp +Both +.Fn lwres_getaddrsbyname +and +.Fn lwres_getnamebyaddr +return +.Er LWRES_R_NOMEMORY +when memory allocation requests fail and +.Er LWRES_R_UNEXPECTEDEND +if the buffers used for sending queries and receiving replies are too +small. +.Sh SEE ALSO +.Xr lwres_buffer 3 , +.Xr lwres_gabn 3 . diff --git a/lib/lwres/man/lwres_sethostent.3 b/lib/lwres/man/lwres_sethostent.3 new file mode 100644 index 0000000000..b88de48284 --- /dev/null +++ b/lib/lwres/man/lwres_sethostent.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_sethostent.3,v 1.1 2000/06/27 21:53:10 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_sethostent_r.3 b/lib/lwres/man/lwres_sethostent_r.3 new file mode 100644 index 0000000000..d455328b17 --- /dev/null +++ b/lib/lwres/man/lwres_sethostent_r.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_sethostent_r.3,v 1.1 2000/06/27 21:53:10 jim Exp $ +.\" +.so lwres_gethostent.3 diff --git a/lib/lwres/man/lwres_string_parse.3 b/lib/lwres/man/lwres_string_parse.3 new file mode 100644 index 0000000000..378a559b06 --- /dev/null +++ b/lib/lwres/man/lwres_string_parse.3 @@ -0,0 +1,19 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: lwres_string_parse.3,v 1.1 2000/06/27 21:53:10 jim Exp $ +.\" +.so lwres_resutil.3