diff options
Diffstat (limited to 'contrib/bind9/lib/lwres')
98 files changed, 7822 insertions, 6615 deletions
diff --git a/contrib/bind9/lib/lwres/Makefile.in b/contrib/bind9/lib/lwres/Makefile.in index 024b988492a7..a06bd8a2c9e5 100644 --- a/contrib/bind9/lib/lwres/Makefile.in +++ b/contrib/bind9/lib/lwres/Makefile.in @@ -13,7 +13,7 @@ # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -# $Id: Makefile.in,v 1.25.12.8 2005/06/09 23:54:32 marka Exp $ +# $Id: Makefile.in,v 1.28.18.4 2005/06/09 23:55:10 marka Exp $ srcdir = @srcdir@ VPATH = @srcdir@ diff --git a/contrib/bind9/lib/lwres/api b/contrib/bind9/lib/lwres/api index 63704dd62ad3..d94beab3e3f9 100644 --- a/contrib/bind9/lib/lwres/api +++ b/contrib/bind9/lib/lwres/api @@ -1,3 +1,3 @@ -LIBINTERFACE = 10 -LIBREVISION = 5 -LIBAGE = 1 +LIBINTERFACE = 30 +LIBREVISION = 4 +LIBAGE = 0 diff --git a/contrib/bind9/lib/lwres/assert_p.h b/contrib/bind9/lib/lwres/assert_p.h index 78b4b7927a54..c47ececabc48 100644 --- a/contrib/bind9/lib/lwres/assert_p.h +++ b/contrib/bind9/lib/lwres/assert_p.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: assert_p.h,v 1.9.206.1 2004/03/06 08:15:30 marka Exp $ */ +/* $Id: assert_p.h,v 1.10.18.2 2005/04/29 00:17:16 marka Exp $ */ #ifndef LWRES_ASSERT_P_H #define LWRES_ASSERT_P_H 1 +/*! \file */ + #include <assert.h> /* Required for assert() prototype. */ #define REQUIRE(x) assert(x) diff --git a/contrib/bind9/lib/lwres/context.c b/contrib/bind9/lib/lwres/context.c index b606b9d21a1f..0da426ba5910 100644 --- a/contrib/bind9/lib/lwres/context.c +++ b/contrib/bind9/lib/lwres/context.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001, 2003 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,8 +15,76 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: context.c,v 1.41.2.1.2.4 2004/09/17 05:50:31 marka Exp $ */ - +/* $Id: context.c,v 1.45.18.3 2005/04/29 00:17:16 marka Exp $ */ + +/*! \file context.c + lwres_context_create() creates a #lwres_context_t structure for use in + lightweight resolver operations. It holds a socket and other data + needed for communicating with a resolver daemon. The new + lwres_context_t is returned through contextp, a pointer to a + lwres_context_t pointer. This lwres_context_t pointer must initially + be NULL, and is modified to point to the newly created + lwres_context_t. + + When the lightweight resolver needs to perform dynamic memory + allocation, it will call malloc_function to allocate memory and + free_function to free it. If malloc_function and free_function are + NULL, memory is allocated using malloc and free. It is not + permitted to have a NULL malloc_function and a non-NULL free_function + or vice versa. arg is passed as the first parameter to the memory + allocation functions. If malloc_function and free_function are NULL, + arg is unused and should be passed as NULL. + + Once memory for the structure has been allocated, it is initialized + using lwres_conf_init() and returned via *contextp. + + lwres_context_destroy() destroys a #lwres_context_t, closing its + socket. contextp is a pointer to a pointer to the context that is to + be destroyed. The pointer will be set to NULL when the context has + been destroyed. + + The context holds a serial number that is used to identify resolver + request packets and associate responses with the corresponding + requests. This serial number is controlled using + lwres_context_initserial() and lwres_context_nextserial(). + lwres_context_initserial() sets the serial number for context *ctx to + serial. lwres_context_nextserial() increments the serial number and + returns the previous value. + + Memory for a lightweight resolver context is allocated and freed using + lwres_context_allocmem() and lwres_context_freemem(). These use + whatever allocations were defined when the context was created with + lwres_context_create(). lwres_context_allocmem() allocates len bytes + of memory and if successful returns a pointer to the allocated + storage. lwres_context_freemem() frees len bytes of space starting at + location mem. + + lwres_context_sendrecv() performs I/O for the context ctx. Data are + read and written from the context's socket. It writes data from + sendbase -- typically a lightweight resolver query packet -- and waits + for a reply which is copied to the receive buffer at recvbase. The + number of bytes that were written to this receive buffer is returned + in *recvd_len. + +\section context_return Return Values + + lwres_context_create() returns #LWRES_R_NOMEMORY if memory for the + struct lwres_context could not be allocated, #LWRES_R_SUCCESS + otherwise. + + Successful calls to the memory allocator lwres_context_allocmem() + return a pointer to the start of the allocated space. It returns NULL + if memory could not be allocated. + + #LWRES_R_SUCCESS is returned when lwres_context_sendrecv() completes + successfully. #LWRES_R_IOERROR is returned if an I/O error occurs and + #LWRES_R_TIMEOUT is returned if lwres_context_sendrecv() times out + waiting for a response. + +\section context_see See Also + + lwres_conf_init(), malloc, free. + */ #include <config.h> #include <fcntl.h> @@ -37,7 +105,7 @@ #include "context_p.h" #include "assert_p.h" -/* +/*! * Some systems define the socket length argument as an int, some as size_t, * some as socklen_t. The last is what the current POSIX standard mandates. * This definition is here so it can be portable but easily changed if needed. @@ -46,7 +114,7 @@ #define LWRES_SOCKADDR_LEN_T unsigned int #endif -/* +/*! * Make a socket nonblocking. */ #ifndef MAKE_NONBLOCKING @@ -69,9 +137,16 @@ lwres_malloc(void *, size_t); static void lwres_free(void *, void *, size_t); +/*! + * lwres_result_t + */ static lwres_result_t context_connect(lwres_context_t *); +/*% + * Creates a #lwres_context_t structure for use in + * lightweight resolver operations. + */ lwres_result_t lwres_context_create(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, @@ -118,6 +193,12 @@ lwres_context_create(lwres_context_t **contextp, void *arg, return (LWRES_R_SUCCESS); } +/*% +Destroys a #lwres_context_t, closing its socket. +contextp is a pointer to a pointer to the context that is +to be destroyed. The pointer will be set to NULL +when the context has been destroyed. + */ void lwres_context_destroy(lwres_context_t **contextp) { lwres_context_t *ctx; @@ -134,7 +215,7 @@ lwres_context_destroy(lwres_context_t **contextp) { CTXFREE(ctx, sizeof(lwres_context_t)); } - +/*% Increments the serial number and returns the previous value. */ lwres_uint32_t lwres_context_nextserial(lwres_context_t *ctx) { REQUIRE(ctx != NULL); @@ -142,6 +223,7 @@ lwres_context_nextserial(lwres_context_t *ctx) { return (ctx->serial++); } +/*% Sets the serial number for context *ctx to serial. */ void lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t serial) { REQUIRE(ctx != NULL); @@ -149,6 +231,7 @@ lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t serial) { ctx->serial = serial; } +/*% Frees len bytes of space starting at location mem. */ void lwres_context_freemem(lwres_context_t *ctx, void *mem, size_t len) { REQUIRE(mem != NULL); @@ -157,6 +240,7 @@ lwres_context_freemem(lwres_context_t *ctx, void *mem, size_t len) { CTXFREE(mem, len); } +/*% Allocates len bytes of memory and if successful returns a pointer to the allocated storage. */ void * lwres_context_allocmem(lwres_context_t *ctx, size_t len) { REQUIRE(len != 0U); @@ -334,6 +418,7 @@ lwres_context_recv(lwres_context_t *ctx, return (LWRES_R_SUCCESS); } +/*% performs I/O for the context ctx. */ lwres_result_t lwres_context_sendrecv(lwres_context_t *ctx, void *sendbase, int sendlen, diff --git a/contrib/bind9/lib/lwres/context_p.h b/contrib/bind9/lib/lwres/context_p.h index 3e22bc00d45e..d255ef6d72be 100644 --- a/contrib/bind9/lib/lwres/context_p.h +++ b/contrib/bind9/lib/lwres/context_p.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,42 +15,48 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: context_p.h,v 1.12.206.1 2004/03/06 08:15:30 marka Exp $ */ +/* $Id: context_p.h,v 1.13.18.2 2005/04/29 00:17:17 marka Exp $ */ #ifndef LWRES_CONTEXT_P_H #define LWRES_CONTEXT_P_H 1 -/* +/*! \file */ + +/*@{*/ +/** * Helper functions, assuming the context is always called "ctx" in * the scope these functions are called from. */ #define CTXMALLOC(len) ctx->malloc(ctx->arg, (len)) #define CTXFREE(addr, len) ctx->free(ctx->arg, (addr), (len)) +/*@}*/ #define LWRES_DEFAULT_TIMEOUT 120 /* 120 seconds for a reply */ -/* +/** * Not all the attributes here are actually settable by the application at * this time. */ struct lwres_context { - unsigned int timeout; /* time to wait for reply */ - lwres_uint32_t serial; /* serial number state */ + 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 */ - lwres_addr_t address; /* address to send to */ + int sock; /*%< socket to send on */ + lwres_addr_t address; /*%< address to send to */ + /*@{*/ /* * Function pointers for allocating memory. */ lwres_malloc_t malloc; lwres_free_t free; void *arg; + /*@}*/ - /* + /*% * resolv.conf-like data */ lwres_conf_t confdata; diff --git a/contrib/bind9/lib/lwres/gai_strerror.c b/contrib/bind9/lib/lwres/gai_strerror.c index 06b7fbe1efd1..0dcfe40a8540 100644 --- a/contrib/bind9/lib/lwres/gai_strerror.c +++ b/contrib/bind9/lib/lwres/gai_strerror.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004, 2006 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004-2006 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,12 +15,40 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gai_strerror.c,v 1.14.2.1.10.3 2006/08/25 05:25:50 marka Exp $ */ +/* $Id: gai_strerror.c,v 1.16.18.4 2006/08/25 05:25:51 marka Exp $ */ + +/*! \file gai_strerror.c + * lwres_gai_strerror() returns an error message corresponding to an + * error code returned by getaddrinfo(). The following error codes and + * their meaning are defined in \link netdb.h include/lwres/netdb.h.\endlink + * + * \li #EAI_ADDRFAMILY address family for hostname not supported + * \li #EAI_AGAIN temporary failure in name resolution + * \li #EAI_BADFLAGS invalid value for #ai_flags + * \li #EAI_FAIL non-recoverable failure in name resolution + * \li #EAI_FAMILY ai_family not supported + * \li #EAI_MEMORY memory allocation failure + * \li #EAI_NODATA no address associated with hostname + * \li #EAI_NONAME hostname or servname not provided, or not known + * \li #EAI_SERVICE servname not supported for ai_socktype + * \li #EAI_SOCKTYPE ai_socktype not supported + * \li #EAI_SYSTEM system error returned in errno + * + * The message invalid error code is returned if ecode is out of range. + * + * ai_flags, ai_family and ai_socktype are elements of the struct + * addrinfo used by lwres_getaddrinfo(). + * + * \section gai_strerror_see See Also + * + * strerror, lwres_getaddrinfo(), getaddrinfo(), RFC2133. + */ #include <config.h> #include <lwres/netdb.h> +/*% Text of error messages. */ static const char *gai_messages[] = { "no error", "address family for hostname not supported", @@ -38,6 +66,7 @@ static const char *gai_messages[] = { "bad protocol" }; +/*% Returns an error message corresponding to an error code returned by getaddrinfo() */ char * lwres_gai_strerror(int ecode) { union { diff --git a/contrib/bind9/lib/lwres/getaddrinfo.c b/contrib/bind9/lib/lwres/getaddrinfo.c index 9ad10dfd7eb3..e06ca29ea53d 100644 --- a/contrib/bind9/lib/lwres/getaddrinfo.c +++ b/contrib/bind9/lib/lwres/getaddrinfo.c @@ -18,7 +18,118 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getaddrinfo.c,v 1.41.206.6 2006/11/13 11:57:41 marka Exp $ */ +/* $Id: getaddrinfo.c,v 1.43.18.6 2006/11/14 01:07:28 marka Exp $ */ + +/*! \file */ + +/** + * lwres_getaddrinfo() is used to get a list of IP addresses and port + * numbers for host hostname and service servname. The function is the + * lightweight resolver's implementation of getaddrinfo() as defined in + * RFC2133. hostname and servname are pointers to null-terminated strings + * or NULL. hostname is either a host name or a numeric host address + * string: a dotted decimal IPv4 address or an IPv6 address. servname is + * either a decimal port number or a service name as listed in + * /etc/services. + * + * If the operating system does not provide a struct addrinfo, the + * following structure is used: + * + * \code + * 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 + * }; + * \endcode + * + * + * hints is an optional pointer to a 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 *hints: + * + * <ul> + * <li>ai_family: + * The protocol family that should be used. When ai_family is set + * to PF_UNSPEC, it means the caller will accept any protocol + * family supported by the operating system.</li> + * + * <li>ai_socktype: + * denotes the type of socket -- SOCK_STREAM, SOCK_DGRAM or + * SOCK_RAW -- that is wanted. When ai_socktype is zero the caller + * will accept any socket type.</li> + * + * <li>ai_protocol: + * indicates which transport protocol is wanted: IPPROTO_UDP or + * IPPROTO_TCP. If ai_protocol is zero the caller will accept any + * protocol.</li> + * + * <li>ai_flags: + * Flag bits. If the AI_CANONNAME bit is set, a successful call to + * lwres_getaddrinfo() will return a null-terminated string + * containing the canonical name of the specified hostname in + * ai_canonname of the first addrinfo structure returned. Setting + * the AI_PASSIVE bit indicates that the returned socket address + * structure is intended for used in a call to bind(2). In this + * case, if the hostname argument is a NULL pointer, then the IP + * address portion of the socket address structure will be set to + * INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 + * address.<br /><br /> + * + * When ai_flags does not set the AI_PASSIVE bit, the returned + * socket address structure will be ready for use in a call to + * connect(2) for a connection-oriented protocol or connect(2), + * sendto(2), or 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 hostname is a NULL + * pointer and AI_PASSIVE is not set in ai_flags.<br /><br /> + * + * If ai_flags is set to AI_NUMERICHOST it indicates that hostname + * should be treated as a numeric string defining an IPv4 or IPv6 + * address and no name resolution should be attempted. + * </li></ul> + * + * All other elements of the struct addrinfo passed via hints must be + * zero. + * + * A hints of NULL is treated as if the caller provided a struct addrinfo + * initialized to zero with ai_familyset to PF_UNSPEC. + * + * After a successful call to lwres_getaddrinfo(), *res is a pointer to a + * linked list of one or more addrinfo structures. Each struct addrinfo + * in this list cn be processed by following the ai_next pointer, until a + * NULL pointer is encountered. The three members ai_family, ai_socktype, + * and ai_protocol in each returned addrinfo structure contain the + * corresponding arguments for a call to socket(2). For each addrinfo + * structure in the list, the ai_addr member points to a filled-in socket + * address structure of length ai_addrlen. + * + * All of the information returned by lwres_getaddrinfo() is dynamically + * allocated: the addrinfo structures, and the socket address structures + * and canonical host name strings pointed to by the addrinfostructures. + * Memory allocated for the dynamically allocated structures created by a + * successful call to lwres_getaddrinfo() is released by + * lwres_freeaddrinfo(). ai is a pointer to a struct addrinfo created by + * a call to lwres_getaddrinfo(). + * + * \section lwresreturn RETURN VALUES + * + * lwres_getaddrinfo() returns zero on success or one of the error codes + * listed in gai_strerror() if an error occurs. If both hostname and + * servname are NULL lwres_getaddrinfo() returns #EAI_NONAME. + * + * \section lwressee SEE ALSO + * + * lwres(3), lwres_getaddrinfo(), lwres_freeaddrinfo(), + * lwres_gai_strerror(), RFC2133, getservbyname(3), connect(2), + * sendto(2), sendmsg(2), socket(2). + */ #include <config.h> @@ -35,6 +146,8 @@ #define SIN6(addr) ((struct sockaddr_in6 *)(addr)) #define SUN(addr) ((struct sockaddr_un *)(addr)) +/*! \struct addrinfo + */ static struct addrinfo *ai_reverse(struct addrinfo *oai), *ai_clone(struct addrinfo *oai, int family), @@ -55,7 +168,7 @@ static void set_order(int, int (**)(const char *, int, struct addrinfo **, #define FOUND_MAX 2 #define ISC_AI_MASK (AI_PASSIVE|AI_CANONNAME|AI_NUMERICHOST) - +/*% Get a list of IP addresses and port numbers for host hostname and service servname. */ int lwres_getaddrinfo(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res) @@ -137,7 +250,7 @@ lwres_getaddrinfo(const char *hostname, const char *servname, } #ifdef AF_LOCAL - /* + /*! * First, deal with AF_LOCAL. If the family was not set, * then assume AF_LOCAL if the first character of the * hostname/servname is '/'. @@ -575,6 +688,7 @@ add_ipv6(const char *hostname, int flags, struct addrinfo **aip, return (result); } +/*% Free address info. */ void lwres_freeaddrinfo(struct addrinfo *ai) { struct addrinfo *ai_next; @@ -617,7 +731,7 @@ get_local(const char *name, int socktype, struct addrinfo **res) { } #endif -/* +/*! * Allocate an addrinfo structure, and a sockaddr structure * of the specificed length. We initialize: * ai_addrlen diff --git a/contrib/bind9/lib/lwres/gethost.c b/contrib/bind9/lib/lwres/gethost.c index 9c362b92c892..3cd6e4a1e3a8 100644 --- a/contrib/bind9/lib/lwres/gethost.c +++ b/contrib/bind9/lib/lwres/gethost.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,139 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gethost.c,v 1.29.206.1 2004/03/06 08:15:30 marka Exp $ */ +/* $Id: gethost.c,v 1.30.18.2 2005/04/29 00:17:17 marka Exp $ */ + +/*! \file */ + +/** + * These functions provide hostname-to-address and address-to-hostname + * lookups by means of the lightweight resolver. They are similar to the + * standard gethostent(3) functions provided by most operating systems. + * They use a struct hostent which is usually defined in <namedb.h>. + * + * \code + * 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 + * \endcode + * + * The members of this structure are: + * + * \li h_name: + * The official (canonical) name of the host. + * + * \li h_aliases: + * A NULL-terminated array of alternate names (nicknames) for the + * host. + * + * \li h_addrtype: + * The type of address being returned -- PF_INET or PF_INET6. + * + * \li h_length: + * The length of the address in bytes. + * + * \li h_addr_list: + * A NULL terminated array of network addresses for the host. Host + * addresses are returned in network byte order. + * + * For backward compatibility with very old software, h_addr is the first + * address in h_addr_list. + * + * lwres_gethostent(), lwres_sethostent(), lwres_endhostent(), + * lwres_gethostent_r(), lwres_sethostent_r() and lwres_endhostent_r() + * provide iteration over the known host entries on systems that provide + * such functionality through facilities like /etc/hosts or NIS. The + * lightweight resolver does not currently implement these functions; it + * only provides them as stub functions that always return failure. + * + * lwres_gethostbyname() and lwres_gethostbyname2() look up the hostname + * name. lwres_gethostbyname() always looks for an IPv4 address while + * lwres_gethostbyname2() looks for an address of protocol family af: + * either PF_INET or PF_INET6 -- IPv4 or IPV6 addresses respectively. + * Successful calls of the functions return a struct hostent for the name + * that was looked up. NULL is returned if the lookups by + * lwres_gethostbyname() or lwres_gethostbyname2() fail. + * + * Reverse lookups of addresses are performed by lwres_gethostbyaddr(). + * addr is an address of length len bytes and protocol family type -- + * PF_INET or PF_INET6. lwres_gethostbyname_r() is a thread-safe function + * for forward lookups. If an error occurs, an error code is returned in + * *error. resbuf is a pointer to a struct hostent which is initialised + * by a successful call to lwres_gethostbyname_r() . buf is a buffer of + * length len bytes which is used to store the h_name, h_aliases, and + * h_addr_list elements of the struct hostent returned in resbuf. + * Successful calls to lwres_gethostbyname_r() return resbuf, which is a + * pointer to the struct hostent it created. + * + * lwres_gethostbyaddr_r() is a thread-safe function that performs a + * reverse lookup of address addr which is len bytes long and is of + * protocol family type -- PF_INET or PF_INET6. If an error occurs, the + * error code is returned in *error. The other function parameters are + * identical to those in lwres_gethostbyname_r(). resbuf is a pointer to + * a struct hostent which is initialised by a successful call to + * lwres_gethostbyaddr_r(). buf is a buffer of length len bytes which is + * used to store the h_name, h_aliases, and h_addr_list elements of the + * struct hostent returned in resbuf. Successful calls to + * lwres_gethostbyaddr_r() return resbuf, which is a pointer to the + * struct hostent it created. + * + * \section gethost_return Return Values + * + * The functions lwres_gethostbyname(), lwres_gethostbyname2(), + * lwres_gethostbyaddr(), and lwres_gethostent() return NULL to indicate + * an error. In this case the global variable lwres_h_errno will contain + * one of the following error codes defined in \link netdb.h <lwres/netdb.h>:\endlink + * + * \li #HOST_NOT_FOUND: + * The host or address was not found. + * + * \li #TRY_AGAIN: + * A recoverable error occurred, e.g., a timeout. Retrying the + * lookup may succeed. + * + * \li #NO_RECOVERY: + * A non-recoverable error occurred. + * + * \li #NO_DATA: + * The name exists, but has no address information associated with + * it (or vice versa in the case of a reverse lookup). The code + * NO_ADDRESS is accepted as a synonym for NO_DATA for backwards + * compatibility. + * + * lwres_hstrerror() translates these error codes to suitable error + * messages. + * + * lwres_gethostent() and lwres_gethostent_r() always return NULL. + * + * Successful calls to lwres_gethostbyname_r() and + * lwres_gethostbyaddr_r() return resbuf, a pointer to the struct hostent + * that was initialised by these functions. They return NULL if the + * lookups fail or if buf was too small to hold the list of addresses and + * names referenced by the h_name, h_aliases, and h_addr_list elements of + * the struct hostent. If buf was too small, both lwres_gethostbyname_r() + * and lwres_gethostbyaddr_r() set the global variable errno to ERANGE. + * + * \section gethost_see See Also + * + * gethostent(), \link getipnode.c getipnode\endlink, lwres_hstrerror() + * + * \section gethost_bugs Bugs + * + * lwres_gethostbyname(), lwres_gethostbyname2(), lwres_gethostbyaddr() + * and lwres_endhostent() are not thread safe; they return pointers to + * static data and provide error codes through a global variable. + * Thread-safe versions for name and address lookup are provided by + * lwres_gethostbyname_r(), and lwres_gethostbyaddr_r() respectively. + * + * The resolver daemon does not currently support any non-DNS name + * services such as /etc/hosts or NIS, consequently the above functions + * don't, either. + */ #include <config.h> @@ -34,6 +166,7 @@ static struct hostent *he = NULL; static int copytobuf(struct hostent *, struct hostent *, char *, int); +/*% Always looks for an IPv4 address. */ struct hostent * lwres_gethostbyname(const char *name) { @@ -44,6 +177,7 @@ lwres_gethostbyname(const char *name) { return (he); } +/*% Looks for either an IPv4 or IPv6 address. */ struct hostent * lwres_gethostbyname2(const char *name, int af) { if (he != NULL) @@ -53,6 +187,7 @@ lwres_gethostbyname2(const char *name, int af) { return (he); } +/*% Reverse lookup of addresses. */ struct hostent * lwres_gethostbyaddr(const char *addr, int len, int type) { @@ -63,6 +198,7 @@ lwres_gethostbyaddr(const char *addr, int len, int type) { return (he); } +/*% Stub function. Always returns failure. */ struct hostent * lwres_gethostent(void) { if (he != NULL) @@ -71,6 +207,7 @@ lwres_gethostent(void) { return (NULL); } +/*% Stub function. Always returns failure. */ void lwres_sethostent(int stayopen) { /* @@ -79,6 +216,7 @@ lwres_sethostent(int stayopen) { UNUSED(stayopen); } +/*% Stub function. Always returns failure. */ void lwres_endhostent(void) { /* @@ -86,6 +224,7 @@ lwres_endhostent(void) { */ } +/*% Thread-safe function for forward lookups. */ struct hostent * lwres_gethostbyname_r(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error) @@ -105,6 +244,7 @@ lwres_gethostbyname_r(const char *name, struct hostent *resbuf, return (resbuf); } +/*% Thread-safe reverse lookup. */ struct hostent * lwres_gethostbyaddr_r(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, @@ -125,6 +265,7 @@ lwres_gethostbyaddr_r(const char *addr, int len, int type, return (resbuf); } +/*% Stub function. Always returns failure. */ struct hostent * lwres_gethostent_r(struct hostent *resbuf, char *buf, int buflen, int *error) { UNUSED(resbuf); @@ -134,6 +275,7 @@ lwres_gethostent_r(struct hostent *resbuf, char *buf, int buflen, int *error) { return (NULL); } +/*% Stub function. Always returns failure. */ void lwres_sethostent_r(int stayopen) { /* @@ -142,6 +284,7 @@ lwres_sethostent_r(int stayopen) { UNUSED(stayopen); } +/*% Stub function. Always returns failure. */ void lwres_endhostent_r(void) { /* diff --git a/contrib/bind9/lib/lwres/getipnode.c b/contrib/bind9/lib/lwres/getipnode.c index 9b1a07bdda7b..46eed144ad03 100644 --- a/contrib/bind9/lib/lwres/getipnode.c +++ b/contrib/bind9/lib/lwres/getipnode.c @@ -15,7 +15,110 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getipnode.c,v 1.30.2.4.2.6 2005/04/29 00:03:32 marka Exp $ */ +/* $Id: getipnode.c,v 1.37.18.3 2005/04/29 00:17:18 marka Exp $ */ + +/*! \file */ + +/** + * These functions perform thread safe, protocol independent + * nodename-to-address and address-to-nodename translation as defined in + * RFC2553. This use a struct hostent which is defined in namedb.h: + * + * \code + * 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 + * \endcode + * + * The members of this structure are: + * + * \li h_name: + * The official (canonical) name of the host. + * + * \li h_aliases: + * A NULL-terminated array of alternate names (nicknames) for the + * host. + * + * \li h_addrtype: + * The type of address being returned - usually PF_INET or + * PF_INET6. + * + * \li h_length: + * The length of the address in bytes. + * + * \li h_addr_list: + * A NULL terminated array of network addresses for the host. Host + * addresses are returned in network byte order. + * + * lwres_getipnodebyname() looks up addresses of protocol family af for + * the hostname name. The flags parameter contains ORed flag bits to + * specify the types of addresses that are searched for, and the types of + * addresses that are returned. The flag bits are: + * + * \li #AI_V4MAPPED: + * This is used with an af of #AF_INET6, and causes IPv4 addresses + * to be returned as IPv4-mapped IPv6 addresses. + * + * \li #AI_ALL: + * This is used with an af of #AF_INET6, and causes all known + * addresses (IPv6 and IPv4) to be returned. If #AI_V4MAPPED is + * also set, the IPv4 addresses are return as mapped IPv6 + * addresses. + * + * \li #AI_ADDRCONFIG: + * Only return an IPv6 or IPv4 address if here is an active + * network interface of that type. This is not currently + * implemented in the BIND 9 lightweight resolver, and the flag is + * ignored. + * + * \li #AI_DEFAULT: + * This default sets the #AI_V4MAPPED and #AI_ADDRCONFIG flag bits. + * + * lwres_getipnodebyaddr() performs a reverse lookup of address src which + * is len bytes long. af denotes the protocol family, typically PF_INET + * or PF_INET6. + * + * lwres_freehostent() releases all the memory associated with the struct + * hostent pointer. Any memory allocated for the h_name, h_addr_list + * and h_aliases is freed, as is the memory for the hostent structure + * itself. + * + * \section getipnode_return Return Values + * + * If an error occurs, lwres_getipnodebyname() and + * lwres_getipnodebyaddr() set *error_num to an appropriate error code + * and the function returns a NULL pointer. The error codes and their + * meanings are defined in \link netdb.h <lwres/netdb.h>\endlink: + * + * \li #HOST_NOT_FOUND: + * No such host is known. + * + * \li #NO_ADDRESS: + * The server recognised the request and the name but no address + * is available. Another type of request to the name server for + * the domain might return an answer. + * + * \li #TRY_AGAIN: + * A temporary and possibly transient error occurred, such as a + * failure of a server to respond. The request may succeed if + * retried. + * + * \li #NO_RECOVERY: + * An unexpected failure occurred, and retrying the request is + * pointless. + * + * lwres_hstrerror() translates these error codes to suitable error + * messages. + * + * \section getipnode_see See Also + * + * getaddrinfo.c, gethost.c, getnameinfo.c, herror.c, RFC2553 + */ #include <config.h> @@ -80,7 +183,7 @@ hostfromname(lwres_gabnresponse_t *name, int af); *** Public functions. ***/ -/* +/*! * AI_V4MAPPED + AF_INET6 * If no IPv6 address then a query for IPv4 and map returned values. * @@ -222,6 +325,7 @@ lwres_getipnodebyname(const char *name, int af, int flags, int *error_num) { return (he3); } +/*% performs a reverse lookup of address src which is len bytes long. af denotes the protocol family, typically #PF_INET or PF_INET6. */ struct hostent * lwres_getipnodebyaddr(const void *src, size_t len, int af, int *error_num) { struct hostent *he1, *he2; @@ -345,6 +449,7 @@ lwres_getipnodebyaddr(const void *src, size_t len, int af, int *error_num) { return (he1); } +/*% releases all the memory associated with the struct hostent pointer */ void lwres_freehostent(struct hostent *he) { char **cpp; diff --git a/contrib/bind9/lib/lwres/getnameinfo.c b/contrib/bind9/lib/lwres/getnameinfo.c index 059c5291bd3f..d1874a038eea 100644 --- a/contrib/bind9/lib/lwres/getnameinfo.c +++ b/contrib/bind9/lib/lwres/getnameinfo.c @@ -1,5 +1,5 @@ /* - * Portions Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Portions Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Portions Copyright (C) 1999-2001, 2003 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getnameinfo.c,v 1.30.2.3.2.4 2004/08/28 06:25:24 marka Exp $ */ +/* $Id: getnameinfo.c,v 1.34.18.3 2005/04/29 00:17:18 marka Exp $ */ + +/*! \file */ /* * Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. @@ -53,6 +55,62 @@ * but INRIA implementation returns EAI_xxx defined for getaddrinfo(). */ + +/** + * This function is equivalent to the getnameinfo(3) function defined in + * RFC2133. lwres_getnameinfo() returns the hostname for the struct + * sockaddr sa which is salen bytes long. The hostname is of length + * hostlen and is returned via *host. The maximum length of the hostname + * is 1025 bytes: #NI_MAXHOST. + * + * The name of the service associated with the port number in sa is + * returned in *serv. It is servlen bytes long. The maximum length of the + * service name is #NI_MAXSERV - 32 bytes. + * + * The flags argument sets the following bits: + * + * \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. + * + * \li #NI_NUMERICHOST + * Return the address in numeric form, as if calling inet_ntop(), + * instead of a host name. + * + * \li #NI_NAMEREQD + * A name is required. If the hostname cannot be found in the DNS + * and this flag is set, a non-zero error code is returned. If the + * hostname is not found and the flag is not set, the address is + * returned in numeric form. + * + * \li #NI_NUMERICSERV + * The service name is returned as a digit string representing the + * port number. + * + * \li #NI_DGRAM + * Specifies that the service being looked up is a datagram + * service, and causes getservbyport() to be called with a second + * argument of "udp" instead of its default of "tcp". This is + * required for the few ports (512-514) that have different + * services for UDP and TCP. + * + * \section getnameinfo_return Return Values + * + * lwres_getnameinfo() returns 0 on success or a non-zero error code if + * an error occurs. + * + * \section getname_see See Also + * + * RFC2133, getservbyport(), + * lwres_getnamebyaddr(). lwres_net_ntop(). + * + * \section getnameinfo_bugs Bugs + * + * RFC2133 fails to define what the nonzero return values of + * getnameinfo() are. + */ + #include <config.h> #include <stdio.h> @@ -67,12 +125,13 @@ #define SUCCESS 0 +/*% afd structure definition */ static struct afd { int a_af; size_t a_addrlen; size_t a_socklen; } afdl [] = { - /* + /*! * First entry is linked last... */ { AF_INET, sizeof(struct in_addr), sizeof(struct sockaddr_in) }, @@ -88,7 +147,7 @@ static struct afd { #define ENI_SALEN 6 #define ENI_NOSOCKET 7 -/* +/*! * The test against 0 is there to keep the Solaris compiler * from complaining about "end-of-loop code not reached". */ @@ -97,6 +156,7 @@ static struct afd { if (result != 0) goto cleanup; \ } while (0) +/*% lightweight resolver socket address structure to hostname and service name */ int lwres_getnameinfo(const struct sockaddr *sa, size_t salen, char *host, size_t hostlen, char *serv, size_t servlen, int flags) diff --git a/contrib/bind9/lib/lwres/getrrset.c b/contrib/bind9/lib/lwres/getrrset.c index 6160039bf4b3..6b7e5e5125af 100644 --- a/contrib/bind9/lib/lwres/getrrset.c +++ b/contrib/bind9/lib/lwres/getrrset.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000-2003 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,77 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getrrset.c,v 1.11.2.3.2.2 2004/03/06 08:15:31 marka Exp $ */ +/* $Id: getrrset.c,v 1.14.18.2 2005/04/29 00:17:18 marka Exp $ */ + +/*! \file */ + +/** + * DESCRIPTION + * + * lwres_getrrsetbyname() gets a set of resource records associated with + * a hostname, class, and type. hostname is a pointer a to + * null-terminated string. The flags field is currently unused and must + * be zero. + * + * After a successful call to lwres_getrrsetbyname(), *res is a pointer + * to an #rrsetinfo structure, containing a list of one or more #rdatainfo + * structures containing resource records and potentially another list of + * rdatainfo structures containing SIG resource records associated with + * those records. The members #rri_rdclass and #rri_rdtype are copied from + * the parameters. #rri_ttl and #rri_name are properties of the obtained + * rrset. The resource records contained in #rri_rdatas and #rri_sigs are + * in uncompressed DNS wire format. Properties of the rdataset are + * represented in the #rri_flags bitfield. If the #RRSET_VALIDATED bit is + * set, the data has been DNSSEC validated and the signatures verified. + * + * All of the information returned by lwres_getrrsetbyname() is + * dynamically allocated: the rrsetinfo and rdatainfo structures, and the + * canonical host name strings pointed to by the rrsetinfostructure. + * Memory allocated for the dynamically allocated structures created by a + * successful call to lwres_getrrsetbyname() is released by + * lwres_freerrset(). rrset is a pointer to a struct rrset created by a + * call to lwres_getrrsetbyname(). + * + * The following structures are used: + * + * \code + * struct rdatainfo { + * unsigned int rdi_length; // length of data + * unsigned char *rdi_data; // record data + * }; + * + * struct rrsetinfo { + * unsigned int rri_flags; // RRSET_VALIDATED... + * unsigned int rri_rdclass; // class number + * unsigned int rri_rdtype; // RR type number + * unsigned int rri_ttl; // time to live + * unsigned int rri_nrdatas; // size of rdatas array + * unsigned int rri_nsigs; // size of sigs array + * char *rri_name; // canonical name + * struct rdatainfo *rri_rdatas; // individual records + * struct rdatainfo *rri_sigs; // individual signatures + * }; + * \endcode + * + * \section getrrset_return Return Values + * + * lwres_getrrsetbyname() returns zero on success, and one of the + * following error codes if an error occurred: + * + * \li #ERRSET_NONAME: the name does not exist + * + * \li #ERRSET_NODATA: + * the name exists, but does not have data of the desired type + * + * \li #ERRSET_NOMEMORY: + * memory could not be allocated + * + * \li #ERRSET_INVAL: + * a parameter is invalid + * + * \li #ERRSET_FAIL: + * other failure + */ #include <config.h> @@ -29,6 +99,9 @@ #include "assert_p.h" +/*! + * Structure to map results + */ static unsigned int lwresult_to_result(lwres_result_t lwresult) { switch (lwresult) { @@ -40,7 +113,8 @@ lwresult_to_result(lwres_result_t lwresult) { } } -/* +/*@{*/ +/*! * malloc / calloc functions that guarantee to only * return NULL if there is an error, like they used * to before the ANSI C committee broke them. @@ -61,7 +135,9 @@ sane_calloc(size_t number, size_t size) { memset(mem, 0, len); return (mem); } +/*@}*/ +/*% Returns a set of resource records associated with a hostname, class, and type. hostname is a pointer a to null-terminated string. */ int lwres_getrrsetbyname(const char *hostname, unsigned int rdclass, unsigned int rdtype, unsigned int flags, @@ -191,6 +267,7 @@ lwres_getrrsetbyname(const char *hostname, unsigned int rdclass, return (result); } +/*% Releases memory allocated for the dynamically allocated structures created by a successful call to lwres_getrrsetbyname(). */ void lwres_freerrset(struct rrsetinfo *rrset) { unsigned int i; diff --git a/contrib/bind9/lib/lwres/herror.c b/contrib/bind9/lib/lwres/herror.c index 1d0756a05b0a..42b6c7121bef 100644 --- a/contrib/bind9/lib/lwres/herror.c +++ b/contrib/bind9/lib/lwres/herror.c @@ -1,5 +1,5 @@ /* - * Portions Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Portions Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Portions Copyright (C) 2000, 2001, 2003 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -48,10 +48,31 @@ * SUCH DAMAGE. */ +/*! \file herror.c + lwres_herror() prints the string s on stderr followed by the string + generated by lwres_hstrerror() for the error code stored in the global + variable lwres_h_errno. + + lwres_hstrerror() returns an appropriate string for the error code + gievn by err. The values of the error codes and messages are as + follows: + +\li #NETDB_SUCCESS: Resolver Error 0 (no error) + +\li #HOST_NOT_FOUND: Unknown host + +\li #TRY_AGAIN: Host name lookup failure + +\li #NO_RECOVERY: Unknown server error + +\li #NO_DATA: No address associated with name + + */ + #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)herror.c 8.1 (Berkeley) 6/4/93"; static const char rcsid[] = - "$Id: herror.c,v 1.10.12.2 2004/03/06 08:15:31 marka Exp $"; + "$Id: herror.c,v 1.13.18.2 2005/04/29 00:17:18 marka Exp $"; #endif /* LIBC_SCCS and not lint */ #include <config.h> @@ -63,22 +84,22 @@ static const char rcsid[] = LIBLWRES_EXTERNAL_DATA int lwres_h_errno; -/* +/*! * these have never been declared in any header file so make them static */ static const char *h_errlist[] = { - "Resolver Error 0 (no error)", - "Unknown host", /* 1 HOST_NOT_FOUND */ - "Host name lookup failure", /* 2 TRY_AGAIN */ - "Unknown server error", /* 3 NO_RECOVERY */ - "No address associated with name", /* 4 NO_ADDRESS */ + "Resolver Error 0 (no error)", /*%< 0 no error */ + "Unknown host", /*%< 1 HOST_NOT_FOUND */ + "Host name lookup failure", /*%< 2 TRY_AGAIN */ + "Unknown server error", /*%< 3 NO_RECOVERY */ + "No address associated with name", /*%< 4 NO_ADDRESS */ }; static int h_nerr = { sizeof(h_errlist) / sizeof(h_errlist[0]) }; -/* +/*! * herror -- * print the error indicated by the h_errno value. */ @@ -87,7 +108,7 @@ lwres_herror(const char *s) { fprintf(stderr, "%s: %s\n", s, lwres_hstrerror(lwres_h_errno)); } -/* +/*! * hstrerror -- * return the string associated with a given "host" errno value. */ diff --git a/contrib/bind9/lib/lwres/include/Makefile.in b/contrib/bind9/lib/lwres/include/Makefile.in index dc075b95dc1c..7501060ed148 100644 --- a/contrib/bind9/lib/lwres/include/Makefile.in +++ b/contrib/bind9/lib/lwres/include/Makefile.in @@ -13,7 +13,7 @@ # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -# $Id: Makefile.in,v 1.5.206.1 2004/03/06 08:15:33 marka Exp $ +# $Id: Makefile.in,v 1.6 2004/03/05 05:12:49 marka Exp $ srcdir = @srcdir@ VPATH = @srcdir@ diff --git a/contrib/bind9/lib/lwres/include/lwres/Makefile.in b/contrib/bind9/lib/lwres/include/lwres/Makefile.in index 48c28f6207d0..98b8f488ef27 100644 --- a/contrib/bind9/lib/lwres/include/lwres/Makefile.in +++ b/contrib/bind9/lib/lwres/include/lwres/Makefile.in @@ -13,7 +13,7 @@ # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -# $Id: Makefile.in,v 1.19.12.3 2004/03/08 09:05:11 marka Exp $ +# $Id: Makefile.in,v 1.21 2004/03/05 05:12:52 marka Exp $ srcdir = @srcdir@ VPATH = @srcdir@ diff --git a/contrib/bind9/lib/lwres/include/lwres/context.h b/contrib/bind9/lib/lwres/include/lwres/context.h index 962b142ec144..bd2444638b9c 100644 --- a/contrib/bind9/lib/lwres/include/lwres/context.h +++ b/contrib/bind9/lib/lwres/include/lwres/context.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,18 +15,20 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: context.h,v 1.14.206.1 2004/03/06 08:15:34 marka Exp $ */ +/* $Id: context.h,v 1.15.18.2 2005/04/29 00:17:21 marka Exp $ */ #ifndef LWRES_CONTEXT_H #define LWRES_CONTEXT_H 1 +/*! \file */ + #include <stddef.h> #include <lwres/lang.h> #include <lwres/int.h> #include <lwres/result.h> -/* +/*! * Used to set various options such as timeout, authentication, etc */ typedef struct lwres_context lwres_context_t; @@ -51,7 +53,7 @@ typedef void (*lwres_free_t)(void *arg, void *mem, size_t length); * Share /etc/resolv.conf data between contexts. */ -/* +/*! * _SERVERMODE * Don't allocate and connect a socket to the server, since the * caller _is_ a server. @@ -63,7 +65,7 @@ lwres_context_create(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function, unsigned int flags); -/* +/**< * Allocate a lwres context. This is used in all lwres calls. * * Memory management can be replaced here by passing in two functions. @@ -75,28 +77,22 @@ lwres_context_create(lwres_context_t **contextp, void *arg, * * If they are NULL, the standard malloc() and free() will be used. * - * Requires: - * - * contextp != NULL && contextp == NULL. + *\pre contextp != NULL && contextp == NULL. * - * Returns: - * - * Returns 0 on success, non-zero on failure. + *\return Returns 0 on success, non-zero on failure. */ void lwres_context_destroy(lwres_context_t **contextp); -/* +/**< * Frees all memory associated with a lwres context. * - * Requires: - * - * contextp != NULL && contextp == NULL. + *\pre contextp != NULL && contextp == NULL. */ lwres_uint32_t lwres_context_nextserial(lwres_context_t *ctx); -/* +/**< * XXXMLG Document */ diff --git a/contrib/bind9/lib/lwres/include/lwres/int.h b/contrib/bind9/lib/lwres/include/lwres/int.h index 2523924e18cb..337316e21f4a 100644 --- a/contrib/bind9/lib/lwres/include/lwres/int.h +++ b/contrib/bind9/lib/lwres/include/lwres/int.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: int.h,v 1.7.206.1 2004/03/06 08:15:34 marka Exp $ */ +/* $Id: int.h,v 1.8.18.2 2005/04/29 00:17:21 marka Exp $ */ #ifndef LWRES_INT_H #define LWRES_INT_H 1 +/*! \file */ + typedef char lwres_int8_t; typedef unsigned char lwres_uint8_t; typedef short lwres_int16_t; diff --git a/contrib/bind9/lib/lwres/include/lwres/ipv6.h b/contrib/bind9/lib/lwres/include/lwres/ipv6.h index 5dc06d6a25bf..06dab596959e 100644 --- a/contrib/bind9/lib/lwres/include/lwres/ipv6.h +++ b/contrib/bind9/lib/lwres/include/lwres/ipv6.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ipv6.h,v 1.9.206.1 2004/03/06 08:15:34 marka Exp $ */ +/* $Id: ipv6.h,v 1.10.18.2 2005/04/29 00:17:21 marka Exp $ */ #ifndef LWRES_IPV6_H #define LWRES_IPV6_H 1 @@ -24,7 +24,7 @@ ***** Module Info *****/ -/* +/*! \file ipv6.h * IPv6 definitions for systems which do not support IPv6. */ @@ -39,6 +39,7 @@ *** Types. ***/ +/*% in6_addr structure */ struct in6_addr { union { lwres_uint8_t _S6_u8[16]; @@ -46,10 +47,13 @@ struct in6_addr { lwres_uint32_t _S6_u32[4]; } _S6_un; }; +/*@{*/ +/*% IP v6 types */ #define s6_addr _S6_un._S6_u8 #define s6_addr8 _S6_un._S6_u8 #define s6_addr16 _S6_un._S6_u16 #define s6_addr32 _S6_un._S6_u32 +/*@}*/ #define IN6ADDR_ANY_INIT {{{ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 }}} #define IN6ADDR_LOOPBACK_INIT {{{ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 }}} @@ -57,6 +61,7 @@ struct in6_addr { LIBLWRES_EXTERNAL_DATA extern const struct in6_addr in6addr_any; LIBLWRES_EXTERNAL_DATA extern const struct in6_addr in6addr_loopback; +/*% used in getaddrinfo.c and getnameinfo.c */ struct sockaddr_in6 { #ifdef LWRES_PLATFORM_HAVESALEN lwres_uint8_t sin6_len; @@ -74,13 +79,14 @@ struct sockaddr_in6 { #define SIN6_LEN 1 #endif +/*% in6_pktinfo structure */ struct in6_pktinfo { - struct in6_addr ipi6_addr; /* src/dst IPv6 address */ - unsigned int ipi6_ifindex; /* send/recv interface index */ + struct in6_addr ipi6_addr; /*%< src/dst IPv6 address */ + unsigned int ipi6_ifindex; /*%< send/recv interface index */ }; -/* - * Unspecified +/*! + * Unspecified IPv6 address */ #define IN6_IS_ADDR_UNSPECIFIED(a) \ (((a)->s6_addr32[0] == 0) && \ diff --git a/contrib/bind9/lib/lwres/include/lwres/lang.h b/contrib/bind9/lib/lwres/include/lwres/lang.h index bd99ec017e38..a38f19dcf8f5 100644 --- a/contrib/bind9/lib/lwres/include/lwres/lang.h +++ b/contrib/bind9/lib/lwres/include/lwres/lang.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lang.h,v 1.6.206.1 2004/03/06 08:15:35 marka Exp $ */ +/* $Id: lang.h,v 1.7.18.2 2005/04/29 00:17:21 marka Exp $ */ #ifndef LWRES_LANG_H #define LWRES_LANG_H 1 +/*! \file */ + #ifdef __cplusplus #define LWRES_LANG_BEGINDECLS extern "C" { #define LWRES_LANG_ENDDECLS } diff --git a/contrib/bind9/lib/lwres/include/lwres/list.h b/contrib/bind9/lib/lwres/include/lwres/list.h index 9b6178799344..c22c59680bb3 100644 --- a/contrib/bind9/lib/lwres/include/lwres/list.h +++ b/contrib/bind9/lib/lwres/include/lwres/list.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 1997-2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: list.h,v 1.7.206.1 2004/03/06 08:15:35 marka Exp $ */ +/* $Id: list.h,v 1.8.18.2 2005/04/29 00:17:22 marka Exp $ */ #ifndef LWRES_LIST_H #define LWRES_LIST_H 1 +/*! \file */ + #define LWRES_LIST(type) struct { type *head, *tail; } #define LWRES_LIST_INIT(list) \ do { (list).head = NULL; (list).tail = NULL; } while (0) diff --git a/contrib/bind9/lib/lwres/include/lwres/lwbuffer.h b/contrib/bind9/lib/lwres/include/lwres/lwbuffer.h index 97f7b9d98d7d..51b1aadd6e84 100644 --- a/contrib/bind9/lib/lwres/include/lwres/lwbuffer.h +++ b/contrib/bind9/lib/lwres/include/lwres/lwbuffer.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,17 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwbuffer.h,v 1.15.206.1 2004/03/06 08:15:35 marka Exp $ */ +/* $Id: lwbuffer.h,v 1.16.18.2 2005/04/29 00:17:22 marka Exp $ */ -#ifndef LWRES_LWBUFFER_H -#define LWRES_LWBUFFER_H 1 -/***** - ***** Module Info - *****/ - -/* - * Buffers +/*! \file lwbuffer.h * * A buffer is a region of memory, together with a set of related subregions. * Buffers are used for parsing and I/O operations. @@ -51,6 +44,7 @@ * region is empty. If the current offset advances beyond the chosen offset, * the active region will also be empty. * + * \verbatim * /----- used region -----\/-- available --\ * +----------------------------------------+ * | consumed | remaining | | @@ -68,9 +62,11 @@ * a-b == consumed region. * b-d == remaining region. * b-c == optional active region. + * \endverbatim * * The following invariants are maintained by all routines: * + *\verbatim * length > 0 * * base is a valid pointer to length bytes of memory @@ -81,24 +77,28 @@ * * 0 <= active <= used * (although active < current implies empty active region) + *\endverbatim * - * MP: + * \li MP: * Buffers have no synchronization. Clients must ensure exclusive * access. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: + * \li Resources: * Memory: 1 pointer + 6 unsigned integers per buffer. * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ +#ifndef LWRES_LWBUFFER_H +#define LWRES_LWBUFFER_H 1 + /*** *** Imports ***/ @@ -116,32 +116,35 @@ LWRES_LANG_BEGINDECLS #define LWRES_BUFFER_VALID(b) ((b) != NULL && \ (b)->magic == LWRES_BUFFER_MAGIC) -/* +/*! * The following macros MUST be used only on valid buffers. It is the * caller's responsibility to ensure this by using the LWRES_BUFFER_VALID * check above, or by calling another lwres_buffer_*() function (rather than * another macro.) */ -/* +/*! * Get the length of the used region of buffer "b" */ #define LWRES_BUFFER_USEDCOUNT(b) ((b)->used) -/* +/*! * Get the length of the available region of buffer "b" */ #define LWRES_BUFFER_AVAILABLECOUNT(b) ((b)->length - (b)->used) #define LWRES_BUFFER_REMAINING(b) ((b)->used - (b)->current) -/* +/*! * Note that the buffer structure is public. This is principally so buffer * operations can be implemented using macros. Applications are strongly * discouraged from directly manipulating the structure. */ typedef struct lwres_buffer lwres_buffer_t; +/*! + * Buffer data structure + */ struct lwres_buffer { unsigned int magic; unsigned char *base; @@ -158,7 +161,7 @@ struct lwres_buffer { void lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length); -/* +/**< * Make 'b' refer to the 'length'-byte region starting at base. * * Requires: @@ -171,7 +174,7 @@ lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length); void lwres_buffer_invalidate(lwres_buffer_t *b); -/* +/**< * Make 'b' an invalid buffer. * * Requires: @@ -184,7 +187,7 @@ lwres_buffer_invalidate(lwres_buffer_t *b); void lwres_buffer_add(lwres_buffer_t *b, unsigned int n); -/* +/**< * Increase the 'used' region of 'b' by 'n' bytes. * * Requires: @@ -197,7 +200,7 @@ lwres_buffer_add(lwres_buffer_t *b, unsigned int n); void lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n); -/* +/**< * Decrease the 'used' region of 'b' by 'n' bytes. * * Requires: @@ -210,7 +213,7 @@ lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n); void lwres_buffer_clear(lwres_buffer_t *b); -/* +/**< * Make the used region empty. * * Requires: @@ -223,9 +226,10 @@ lwres_buffer_clear(lwres_buffer_t *b); * */ + void lwres_buffer_first(lwres_buffer_t *b); -/* +/**< * Make the consumed region empty. * * Requires: @@ -240,7 +244,7 @@ lwres_buffer_first(lwres_buffer_t *b); void lwres_buffer_forward(lwres_buffer_t *b, unsigned int n); -/* +/**< * Increase the 'consumed' region of 'b' by 'n' bytes. * * Requires: @@ -253,7 +257,7 @@ lwres_buffer_forward(lwres_buffer_t *b, unsigned int n); void lwres_buffer_back(lwres_buffer_t *b, unsigned int n); -/* +/**< * Decrease the 'consumed' region of 'b' by 'n' bytes. * * Requires: @@ -266,7 +270,7 @@ lwres_buffer_back(lwres_buffer_t *b, unsigned int n); lwres_uint8_t lwres_buffer_getuint8(lwres_buffer_t *b); -/* +/**< * Read an unsigned 8-bit integer from 'b' and return it. * * Requires: @@ -286,7 +290,7 @@ lwres_buffer_getuint8(lwres_buffer_t *b); void lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val); -/* +/**< * Store an unsigned 8-bit integer from 'val' into 'b'. * * Requires: @@ -300,7 +304,7 @@ lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val); lwres_uint16_t lwres_buffer_getuint16(lwres_buffer_t *b); -/* +/**< * Read an unsigned 16-bit integer in network byte order from 'b', convert * it to host byte order, and return it. * @@ -321,7 +325,7 @@ lwres_buffer_getuint16(lwres_buffer_t *b); void lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val); -/* +/**< * Store an unsigned 16-bit integer in host byte order from 'val' * into 'b' in network byte order. * @@ -336,7 +340,7 @@ lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val); lwres_uint32_t lwres_buffer_getuint32(lwres_buffer_t *b); -/* +/**< * Read an unsigned 32-bit integer in network byte order from 'b', convert * it to host byte order, and return it. * @@ -357,7 +361,7 @@ lwres_buffer_getuint32(lwres_buffer_t *b); void lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val); -/* +/**< * Store an unsigned 32-bit integer in host byte order from 'val' * into 'b' in network byte order. * @@ -373,7 +377,7 @@ lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val); void lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, unsigned int length); -/* +/**< * Copy 'length' bytes of memory at 'base' into 'b'. * * Requires: @@ -386,7 +390,7 @@ lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, void lwres_buffer_getmem(lwres_buffer_t *b, unsigned char *base, unsigned int length); -/* +/**< * Copy 'length' bytes of memory from 'b' into 'base'. * * Requires: diff --git a/contrib/bind9/lib/lwres/include/lwres/lwpacket.h b/contrib/bind9/lib/lwres/include/lwres/lwpacket.h index 48f6a34862ae..c37353d95f04 100644 --- a/contrib/bind9/lib/lwres/include/lwres/lwpacket.h +++ b/contrib/bind9/lib/lwres/include/lwres/lwpacket.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 1999-2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwpacket.h,v 1.17.206.1 2004/03/06 08:15:35 marka Exp $ */ +/* $Id: lwpacket.h,v 1.18.18.2 2005/04/29 00:17:22 marka Exp $ */ #ifndef LWRES_LWPACKET_H #define LWRES_LWPACKET_H 1 @@ -24,89 +24,124 @@ #include <lwres/lwbuffer.h> #include <lwres/result.h> +/*% lwres_lwpacket_t */ typedef struct lwres_lwpacket lwres_lwpacket_t; +/*% lwres_lwpacket structure */ struct lwres_lwpacket { + /*! The overall packet length, including the + * entire packet header. + * This field is filled in by the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint32_t length; + /*! Specifies the header format. Currently, + * there is only one format, #LWRES_LWPACKETVERSION_0. + * This field is filled in by the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint16_t version; + /*! Specifies library-defined flags for this packet, such as + * whether the packet is a request or a reply. None of + * these are definable by the caller, but library-defined values + * can be set by the caller. For example, one bit in this field + * indicates if the packet is a request or a response. + * This field is filled in by + * the application wits the exception of the + * #LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library + * in the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint16_t pktflags; + /*! Set by the requestor and is returned in all replies. + * If two 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. + * (The library does not do this by default on replies, but + * does so on requests.) + */ lwres_uint32_t serial; + /*! Opcodes between 0x04000000 and 0xffffffff + * are application defined. Opcodes between + * 0x00000000 and 0x03ffffff are + * reserved for library use. + * This field is filled in by the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint32_t opcode; + /*! Only valid for results. + * Results between 0x04000000 and 0xffffffff are application + * defined. + * Results between 0x00000000 and 0x03ffffff are reserved for + * library use. + * (This is the same reserved range defined in <isc/resultclass.h>, + * so it + * would be trivial to map ISC_R_* result codes into packet result + * codes when appropriate.) + * This field is filled in by the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint32_t result; + /*! Set to the maximum buffer size that the receiver can + * handle on requests, and the size of the buffer needed to + * satisfy a request + * when the buffer is too large for replies. + * This field is supplied by the application. + */ lwres_uint32_t recvlength; + /*! The packet level auth type used. + * Authtypes between 0x1000 and 0xffff are application defined. + * Authtypes + * between 0x0000 and 0x0fff are reserved for library use. + * This is currently + * unused and MUST be set to zero. + */ lwres_uint16_t authtype; + /*! The length of the authentication data. + * See the specific + * authtypes for more information on what is contained + * in this field. This is currently unused, and + * MUST be set to zero. + */ lwres_uint16_t authlength; }; -#define LWRES_LWPACKET_LENGTH (4 * 5 + 2 * 4) +#define LWRES_LWPACKET_LENGTH (4 * 5 + 2 * 4) /*%< Overall length. */ -#define LWRES_LWPACKETFLAG_RESPONSE 0x0001U /* if set, pkt is a response */ +#define LWRES_LWPACKETFLAG_RESPONSE 0x0001U /*%< If set, pkt is a response. */ -#define LWRES_LWPACKETVERSION_0 0 +#define LWRES_LWPACKETVERSION_0 0 /*%< Header format. */ -/* - * "length" is the overall packet length, including the entire packet header. - * - * "version" specifies the header format. Currently, there is only one - * format, LWRES_LWPACKETVERSION_0. - * - * "flags" specifies library-defined flags for this packet. None of these - * are definable by the caller, but library-defined values can be set by - * the caller. For example, one bit in this field indicates if the packet - * is a request or a response. - * - * "serial" is set by the requestor and is returned in all replies. If two - * 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. (The library does not do this by default on replies, but - * does so on requests.) - * - * "opcode" is application defined. Opcodes between 0x04000000 and 0xffffffff - * are application defined. Opcodes between 0x00000000 and 0x03ffffff are - * reserved for library use. - * - * "result" is application defined, and valid only on replies. - * Results between 0x04000000 and 0xffffffff are application defined. - * Results between 0x00000000 and 0x03ffffff are reserved for library use. - * (This is the same reserved range defined in <isc/resultclass.h>, so it - * would be trivial to map ISC_R_* result codes into packet result codes - * when appropriate.) +/*! \file lwpacket.h * - * "recvlength" is set to 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. - * - * "authtype" is the packet level auth type used. - * Authtypes between 0x1000 and 0xffff are application defined. Authtypes - * between 0x0000 and 0x0fff are reserved for library use. This is currently - * unused and MUST be set to zero. - * - * "authlen" is the length of the authentication data. See the specific - * authtypes for more information on what is contained in this field. This - * is currently unused, and MUST be set to zero. * * The remainder of the packet consists of two regions, one described by * "authlen" and one of "length - authlen - sizeof(lwres_lwpacket_t)". * * That is: * + * \code * pkt header * authlen bytes of auth information * data bytes - */ - -/* + * \endcode + * * Currently defined opcodes: * - * NOOP. Success is always returned, with the packet contents echoed. + *\li #LWRES_OPCODE_NOOP. Success is always returned, with the packet contents echoed. * - * GETADDRSBYNAME. Return all known addresses for a given name. + *\li #LWRES_OPCODE_GETADDRSBYNAME. Return all known addresses for a given name. * This may return NIS or /etc/hosts info as well as DNS * information. Flags will be provided to indicate ip4/ip6 * addresses are desired. * - * GETNAMEBYADDR. Return the hostname for the given address. Once + *\li #LWRES_OPCODE_GETNAMEBYADDR. Return the hostname for the given address. Once * again, it will return data from multiple sources. */ diff --git a/contrib/bind9/lib/lwres/include/lwres/lwres.h b/contrib/bind9/lib/lwres/include/lwres/lwres.h index 7260b00f11ce..b245363aa700 100644 --- a/contrib/bind9/lib/lwres/include/lwres/lwres.h +++ b/contrib/bind9/lib/lwres/include/lwres/lwres.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres.h,v 1.49.12.3 2004/03/08 09:05:11 marka Exp $ */ +/* $Id: lwres.h,v 1.51.18.2 2005/04/29 00:17:22 marka Exp $ */ #ifndef LWRES_LWRES_H #define LWRES_LWRES_H 1 @@ -28,14 +28,16 @@ #include <lwres/lwpacket.h> #include <lwres/platform.h> -/* +/*! \file */ + +/*! * Design notes: * * Each opcode has two structures and three functions which operate on each * structure. For example, using the "no operation/ping" opcode as an * example: * - * lwres_nooprequest_t: + * <ul><li>lwres_nooprequest_t: * * lwres_nooprequest_render() takes a lwres_nooprequest_t and * and renders it into wire format, storing the allocated @@ -43,20 +45,20 @@ * is no longer needed, it must be freed by * lwres_context_freemem(). All other memory used by the * caller must be freed manually, including the - * lwres_nooprequest_t passed in. + * lwres_nooprequest_t passed in.<br /><br /> * * lwres_nooprequest_parse() takes a wire format message and * breaks it out into a lwres_nooprequest_t. The structure * must be freed via lwres_nooprequest_free() when it is no longer - * needed. + * needed.<br /><br /> * * lwres_nooprequest_free() releases into the lwres_context_t - * any space allocated during parsing. + * any space allocated during parsing.</li> * - * lwres_noopresponse_t: + * <li>lwres_noopresponse_t: * * The functions used are similar to the three used for - * requests, just with different names. + * requests, just with different names.</li></ul> * * Typically, the client will use request_render, response_parse, and * response_free, while the daemon will use request_parse, response_render, @@ -64,62 +66,57 @@ * * The basic flow of a typical client is: * - * fill in a request_t, and call the render function. + * \li fill in a request_t, and call the render function. * - * Transmit the buffer returned to the daemon. + * \li Transmit the buffer returned to the daemon. * - * Wait for a response. + * \li Wait for a response. * - * When a response is received, parse it into a response_t. + * \li When a response is received, parse it into a response_t. * - * free the request buffer using lwres_context_freemem(). + * \li free the request buffer using lwres_context_freemem(). * - * free the response structure and its associated buffer using + * \li free the response structure and its associated buffer using * response_free(). */ -#define LWRES_UDP_PORT 921 -#define LWRES_RECVLENGTH 16384 -#define LWRES_ADDR_MAXLEN 16 /* changing this breaks ABI */ -#define LWRES_RESOLV_CONF "/etc/resolv.conf" +#define LWRES_UDP_PORT 921 /*%< UDP Port Number */ +#define LWRES_RECVLENGTH 16384 /*%< Maximum Packet Length */ +#define LWRES_ADDR_MAXLEN 16 /*%< changing this breaks ABI */ +#define LWRES_RESOLV_CONF "/etc/resolv.conf" /*%< Location of resolv.conf */ -/* - * Flags. - * - * These flags are only relevant to rrset queries. - * - * TRUSTNOTREQUIRED: DNSSEC is not required (input) - * SECUREDATA: The data was crypto-verified with DNSSEC (output) - * - */ +/*% DNSSEC is not required (input). Only relevant to rrset queries. */ #define LWRES_FLAG_TRUSTNOTREQUIRED 0x00000001U +/*% The data was crypto-verified with DNSSEC (output). */ #define LWRES_FLAG_SECUREDATA 0x00000002U -/* - * no-op - */ +/*% no-op */ #define LWRES_OPCODE_NOOP 0x00000000U +/*% lwres_nooprequest_t */ typedef struct { /* public */ lwres_uint16_t datalength; unsigned char *data; } lwres_nooprequest_t; +/*% lwres_noopresponse_t */ typedef struct { /* public */ lwres_uint16_t datalength; unsigned char *data; } lwres_noopresponse_t; -/* - * get addresses by name - */ +/*% get addresses by name */ #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U +/*% lwres_addr_t */ typedef struct lwres_addr lwres_addr_t; + +/*% LWRES_LIST */ typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; +/*% lwres_addr */ struct lwres_addr { lwres_uint32_t family; lwres_uint16_t length; @@ -127,6 +124,7 @@ struct lwres_addr { LWRES_LINK(lwres_addr_t) link; }; +/*% lwres_gabnrequest_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -135,6 +133,7 @@ typedef struct { char *name; } lwres_gabnrequest_t; +/*% lwres_gabnresponse_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -145,21 +144,22 @@ typedef struct { lwres_uint16_t realnamelen; lwres_uint16_t *aliaslen; lwres_addrlist_t addrs; - /* if base != NULL, it will be freed when this structure is freed. */ + /*! if base != NULL, it will be freed when this structure is freed. */ void *base; size_t baselen; } lwres_gabnresponse_t; -/* - * get name by address - */ +/*% get name by address */ #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U + +/*% lwres_gnbarequest_t */ typedef struct { /* public */ lwres_uint32_t flags; lwres_addr_t addr; } lwres_gnbarequest_t; +/*% lwres_gnbaresponse_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -168,16 +168,15 @@ typedef struct { char **aliases; lwres_uint16_t realnamelen; lwres_uint16_t *aliaslen; - /* if base != NULL, it will be freed when this structure is freed. */ + /*! if base != NULL, it will be freed when this structure is freed. */ void *base; size_t baselen; } lwres_gnbaresponse_t; -/* - * get rdata by name - */ +/*% get rdata by name */ #define LWRES_OPCODE_GETRDATABYNAME 0x00010003U +/*% lwres_grbnrequest_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -187,6 +186,7 @@ typedef struct { char *name; } lwres_grbnrequest_t; +/*% lwres_grbnresponse_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -201,58 +201,59 @@ typedef struct { lwres_uint16_t *rdatalen; unsigned char **sigs; lwres_uint16_t *siglen; - /* if base != NULL, it will be freed when this structure is freed. */ + /*% if base != NULL, it will be freed when this structure is freed. */ void *base; size_t baselen; } lwres_grbnresponse_t; +/*% Used by lwres_getrrsetbyname() */ #define LWRDATA_VALIDATED 0x00000001 -/* +/*! * resolv.conf data */ -#define LWRES_CONFMAXNAMESERVERS 3 /* max 3 "nameserver" entries */ -#define LWRES_CONFMAXLWSERVERS 1 /* max 1 "lwserver" entry */ -#define LWRES_CONFMAXSEARCH 8 /* max 8 domains in "search" entry */ -#define LWRES_CONFMAXLINELEN 256 /* max size of a line */ -#define LWRES_CONFMAXSORTLIST 10 +#define LWRES_CONFMAXNAMESERVERS 3 /*%< max 3 "nameserver" entries */ +#define LWRES_CONFMAXLWSERVERS 1 /*%< max 1 "lwserver" entry */ +#define LWRES_CONFMAXSEARCH 8 /*%< max 8 domains in "search" entry */ +#define LWRES_CONFMAXLINELEN 256 /*%< max size of a line */ +#define LWRES_CONFMAXSORTLIST 10 /*%< max 10 */ + +/*% lwres_conf_t */ typedef struct { lwres_context_t *lwctx; lwres_addr_t nameservers[LWRES_CONFMAXNAMESERVERS]; - lwres_uint8_t nsnext; /* index for next free slot */ + lwres_uint8_t nsnext; /*%< index for next free slot */ lwres_addr_t lwservers[LWRES_CONFMAXLWSERVERS]; - lwres_uint8_t lwnext; /* index for next free slot */ + lwres_uint8_t lwnext; /*%< index for next free slot */ char *domainname; char *search[LWRES_CONFMAXSEARCH]; - lwres_uint8_t searchnxt; /* index for next free slot */ + lwres_uint8_t searchnxt; /*%< index for next free slot */ struct { lwres_addr_t addr; - /* mask has a non-zero 'family' and 'length' if set */ + /*% mask has a non-zero 'family' and 'length' if set */ lwres_addr_t mask; } sortlist[LWRES_CONFMAXSORTLIST]; lwres_uint8_t sortlistnxt; - lwres_uint8_t resdebug; /* non-zero if 'options debug' set */ - lwres_uint8_t ndots; /* set to n in 'options ndots:n' */ - lwres_uint8_t no_tld_query; /* non-zero if 'options no_tld_query' */ + lwres_uint8_t resdebug; /*%< non-zero if 'options debug' set */ + lwres_uint8_t ndots; /*%< set to n in 'options ndots:n' */ + lwres_uint8_t no_tld_query; /*%< non-zero if 'options no_tld_query' */ } lwres_conf_t; -#define LWRES_ADDRTYPE_V4 0x00000001U /* ipv4 */ -#define LWRES_ADDRTYPE_V6 0x00000002U /* ipv6 */ +#define LWRES_ADDRTYPE_V4 0x00000001U /*%< ipv4 */ +#define LWRES_ADDRTYPE_V6 0x00000002U /*%< ipv6 */ -#define LWRES_MAX_ALIASES 16 /* max # of aliases */ -#define LWRES_MAX_ADDRS 64 /* max # of addrs */ +#define LWRES_MAX_ALIASES 16 /*%< max # of aliases */ +#define LWRES_MAX_ADDRS 64 /*%< max # of addrs */ LWRES_LANG_BEGINDECLS -/* - * This is in host byte order. - */ +/*% This is in host byte order. */ LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port; LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf; @@ -276,12 +277,12 @@ lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, void lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -295,12 +296,12 @@ lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp); void lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -332,12 +333,12 @@ lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, void lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -351,12 +352,12 @@ lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp); void lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -387,12 +388,12 @@ lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, void lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -406,12 +407,12 @@ lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp); void lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -426,12 +427,12 @@ lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp); lwres_result_t lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); -/* +/**< * Allocate space and render into wire format a noop request packet. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * b != NULL, and points to a lwres_buffer_t. The contents of the * buffer structure will be initialized to contain the wire-format @@ -455,7 +456,7 @@ lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, lwres_result_t lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp); -/* +/**< * Parse a noop request. Note that to get here, the lwpacket must have * already been parsed and removed by the caller, otherwise it would be * pretty hard for it to know this is the right function to call. @@ -474,12 +475,12 @@ lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp); void lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -493,7 +494,7 @@ lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp); lwres_result_t lwres_conf_parse(lwres_context_t *ctx, const char *filename); -/* +/**< * parses a resolv.conf-format file and stores the results in the structure * pointed to by *ctx. * @@ -509,7 +510,7 @@ lwres_conf_parse(lwres_context_t *ctx, const char *filename); lwres_result_t lwres_conf_print(lwres_context_t *ctx, FILE *fp); -/* +/**< * Prints a resolv.conf-format of confdata output to fp. * * Requires: @@ -518,7 +519,7 @@ lwres_conf_print(lwres_context_t *ctx, FILE *fp); void lwres_conf_init(lwres_context_t *ctx); -/* +/**< * sets all internal fields to a default state. Used to initialize a new * lwres_conf_t structure (not reset a used on). * @@ -528,7 +529,7 @@ lwres_conf_init(lwres_context_t *ctx); void lwres_conf_clear(lwres_context_t *ctx); -/* +/**< * frees all internally allocated memory in confdata. Uses the memory * routines supplied by ctx. * @@ -538,8 +539,7 @@ lwres_conf_clear(lwres_context_t *ctx); lwres_conf_t * lwres_conf_get(lwres_context_t *ctx); -/* - * returns a pointer to the current config structure. +/**< * Be extremely cautions in modifying the contents of this structure; it * needs an API to return the various bits of data, walk lists, etc. * diff --git a/contrib/bind9/lib/lwres/include/lwres/netdb.h.in b/contrib/bind9/lib/lwres/include/lwres/netdb.h.in index 7bf545f4e2fb..eaef63b9066d 100644 --- a/contrib/bind9/lib/lwres/include/lwres/netdb.h.in +++ b/contrib/bind9/lib/lwres/include/lwres/netdb.h.in @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: netdb.h.in,v 1.34.206.1 2004/03/06 08:15:35 marka Exp $ */ +/* $Id: netdb.h.in,v 1.35.18.2 2005/04/29 00:17:22 marka Exp $ */ + +/*! \file */ #ifndef LWRES_NETDB_H #define LWRES_NETDB_H 1 diff --git a/contrib/bind9/lib/lwres/include/lwres/platform.h.in b/contrib/bind9/lib/lwres/include/lwres/platform.h.in index e995aa46c0e5..f69e09fcfd39 100644 --- a/contrib/bind9/lib/lwres/include/lwres/platform.h.in +++ b/contrib/bind9/lib/lwres/include/lwres/platform.h.in @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: platform.h.in,v 1.12.2.1.10.5 2005/06/08 02:08:32 marka Exp $ */ +/* $Id: platform.h.in,v 1.14.18.5 2005/06/08 02:07:59 marka Exp $ */ + +/*! \file */ #ifndef LWRES_PLATFORM_H #define LWRES_PLATFORM_H 1 @@ -108,4 +110,11 @@ #endif #endif +/* + * Tell Emacs to use C mode on this file. + * Local Variables: + * mode: c + * End: + */ + #endif /* LWRES_PLATFORM_H */ diff --git a/contrib/bind9/lib/lwres/include/lwres/result.h b/contrib/bind9/lib/lwres/include/lwres/result.h index 617ae32225ba..6253fb28a2ee 100644 --- a/contrib/bind9/lib/lwres/include/lwres/result.h +++ b/contrib/bind9/lib/lwres/include/lwres/result.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: result.h,v 1.14.206.1 2004/03/06 08:15:36 marka Exp $ */ +/* $Id: result.h,v 1.15.18.2 2005/04/29 00:17:23 marka Exp $ */ #ifndef LWRES_RESULT_H #define LWRES_RESULT_H 1 +/*! \file */ + typedef unsigned int lwres_result_t; #define LWRES_R_SUCCESS 0 diff --git a/contrib/bind9/lib/lwres/include/lwres/stdlib.h b/contrib/bind9/lib/lwres/include/lwres/stdlib.h index f5d4db281872..6855fcf49a76 100644 --- a/contrib/bind9/lib/lwres/include/lwres/stdlib.h +++ b/contrib/bind9/lib/lwres/include/lwres/stdlib.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: stdlib.h,v 1.2.4.1 2005/06/08 02:08:32 marka Exp $ */ +/* $Id: stdlib.h,v 1.2.2.1 2005/06/08 02:08:01 marka Exp $ */ #ifndef LWRES_STDLIB_H #define LWRES_STDLIB_H 1 diff --git a/contrib/bind9/lib/lwres/include/lwres/version.h b/contrib/bind9/lib/lwres/include/lwres/version.h index 1b291ceeae9e..252b9031c87a 100644 --- a/contrib/bind9/lib/lwres/include/lwres/version.h +++ b/contrib/bind9/lib/lwres/include/lwres/version.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.h,v 1.2.224.3 2004/03/08 09:05:11 marka Exp $ */ +/* $Id: version.h,v 1.3.18.2 2005/04/29 00:17:23 marka Exp $ */ + +/*! \file */ #include <lwres/platform.h> diff --git a/contrib/bind9/lib/lwres/lwbuffer.c b/contrib/bind9/lib/lwres/lwbuffer.c index 69009f00aebc..519159226048 100644 --- a/contrib/bind9/lib/lwres/lwbuffer.c +++ b/contrib/bind9/lib/lwres/lwbuffer.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,99 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwbuffer.c,v 1.10.206.1 2004/03/06 08:15:31 marka Exp $ */ +/* $Id: lwbuffer.c,v 1.11.18.2 2005/04/29 00:17:18 marka Exp $ */ + +/*! \file */ + +/** + * These functions provide bounds checked access to a region of memory + * where data is being read or written. They are based on, and similar + * to, the isc_buffer_ functions in the ISC library. + * + * A buffer is a region of memory, together with a set of related + * subregions. The used region and the available 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. + * + * The used region is further subdivided into two disjoint regions: the + * consumed region and the remaining region. 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 current offset (if + * any). The remaining 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. + * + * The active region 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. + * + * + * \verbatim + * /------------entire length---------------\\ + * /----- used region -----\\/-- available --\\ + * +----------------------------------------+ + * | consumed | remaining | | + * +----------------------------------------+ + * a b c d e + * + * a == base of buffer. + * b == current pointer. Can be anywhere between a and d. + * c == active pointer. Meaningful between b and d. + * d == used pointer. + * e == length of buffer. + * + * a-e == entire length of buffer. + * a-d == used region. + * a-b == consumed region. + * b-d == remaining region. + * b-c == optional active region. + * \endverbatim + * + * lwres_buffer_init() initializes the lwres_buffer_t *b and assocates it + * with the memory region of size length bytes starting at location base. + * + * lwres_buffer_invalidate() marks the buffer *b as invalid. Invalidating + * a buffer after use is not required, but makes it possible to catch its + * possible accidental use. + * + * The functions lwres_buffer_add() and lwres_buffer_subtract() + * respectively increase and decrease the used space in buffer *b by n + * bytes. lwres_buffer_add() checks for buffer overflow and + * lwres_buffer_subtract() checks for underflow. These functions do not + * allocate or deallocate memory. They just change the value of used. + * + * A buffer is re-initialised by lwres_buffer_clear(). The function sets + * used , current and active to zero. + * + * lwres_buffer_first() makes the consumed region of buffer *p empty by + * setting current to zero (the start of the buffer). + * + * lwres_buffer_forward() increases the consumed region of buffer *b by n + * bytes, checking for overflow. Similarly, lwres_buffer_back() decreases + * buffer b's consumed region by n bytes and checks for underflow. + * + * lwres_buffer_getuint8() reads an unsigned 8-bit integer from *b and + * returns it. lwres_buffer_putuint8() writes the unsigned 8-bit integer + * val to buffer *b. + * + * lwres_buffer_getuint16() and lwres_buffer_getuint32() are identical to + * lwres_buffer_putuint8() except that they respectively read an unsigned + * 16-bit or 32-bit integer in network byte order from b. Similarly, + * lwres_buffer_putuint16() and lwres_buffer_putuint32() writes the + * unsigned 16-bit or 32-bit integer val to buffer b, in network byte + * order. + * + * Arbitrary amounts of data are read or written from a lightweight + * resolver buffer with lwres_buffer_getmem() and lwres_buffer_putmem() + * respectively. lwres_buffer_putmem() copies length bytes of memory at + * base to b. Conversely, lwres_buffer_getmem() copies length bytes of + * memory from b to base. + */ #include <config.h> @@ -42,12 +134,10 @@ lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length) b->active = 0; } +/* Make 'b' an invalid buffer. */ void lwres_buffer_invalidate(lwres_buffer_t *b) { - /* - * Make 'b' an invalid buffer. - */ REQUIRE(LWRES_BUFFER_VALID(b)); @@ -59,12 +149,10 @@ lwres_buffer_invalidate(lwres_buffer_t *b) b->active = 0; } +/* Increase the 'used' region of 'b' by 'n' bytes. */ void lwres_buffer_add(lwres_buffer_t *b, unsigned int n) { - /* - * Increase the 'used' region of 'b' by 'n' bytes. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used + n <= b->length); @@ -72,12 +160,10 @@ lwres_buffer_add(lwres_buffer_t *b, unsigned int n) b->used += n; } +/* Decrease the 'used' region of 'b' by 'n' bytes. */ void lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n) { - /* - * Decrease the 'used' region of 'b' by 'n' bytes. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used >= n); @@ -89,12 +175,10 @@ lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n) b->active = b->used; } +/* Make the used region empty. */ void lwres_buffer_clear(lwres_buffer_t *b) { - /* - * Make the used region empty. - */ REQUIRE(LWRES_BUFFER_VALID(b)); @@ -103,24 +187,20 @@ lwres_buffer_clear(lwres_buffer_t *b) b->active = 0; } +/* Make the consumed region empty. */ void lwres_buffer_first(lwres_buffer_t *b) { - /* - * Make the consumed region empty. - */ REQUIRE(LWRES_BUFFER_VALID(b)); b->current = 0; } +/* Increase the 'consumed' region of 'b' by 'n' bytes. */ void lwres_buffer_forward(lwres_buffer_t *b, unsigned int n) { - /* - * Increase the 'consumed' region of 'b' by 'n' bytes. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->current + n <= b->used); @@ -128,12 +208,10 @@ lwres_buffer_forward(lwres_buffer_t *b, unsigned int n) b->current += n; } +/* Decrease the 'consumed' region of 'b' by 'n' bytes. */ void lwres_buffer_back(lwres_buffer_t *b, unsigned int n) { - /* - * Decrease the 'consumed' region of 'b' by 'n' bytes. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(n <= b->current); @@ -141,15 +219,13 @@ lwres_buffer_back(lwres_buffer_t *b, unsigned int n) b->current -= n; } +/* Read an unsigned 8-bit integer from 'b' and return it. */ lwres_uint8_t lwres_buffer_getuint8(lwres_buffer_t *b) { unsigned char *cp; lwres_uint8_t result; - /* - * Read an unsigned 8-bit integer from 'b' and return it. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used - b->current >= 1); @@ -162,6 +238,7 @@ lwres_buffer_getuint8(lwres_buffer_t *b) return (result); } +/* Put an unsigned 8-bit integer */ void lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val) { @@ -176,16 +253,13 @@ lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val) cp[0] = (val & 0x00ff); } +/* Read an unsigned 16-bit integer in network byte order from 'b', convert it to host byte order, and return it. */ lwres_uint16_t lwres_buffer_getuint16(lwres_buffer_t *b) { unsigned char *cp; lwres_uint16_t result; - /* - * Read an unsigned 16-bit integer in network byte order from 'b', - * convert it to host byte order, and return it. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used - b->current >= 2); @@ -199,6 +273,7 @@ lwres_buffer_getuint16(lwres_buffer_t *b) return (result); } +/* Put an unsigned 16-bit integer. */ void lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val) { @@ -214,17 +289,13 @@ lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val) cp[1] = (val & 0x00ff); } +/* Read an unsigned 32-bit integer in network byte order from 'b', convert it to host byte order, and return it. */ lwres_uint32_t lwres_buffer_getuint32(lwres_buffer_t *b) { unsigned char *cp; lwres_uint32_t result; - /* - * Read an unsigned 32-bit integer in network byte order from 'b', - * convert it to host byte order, and return it. - */ - REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used - b->current >= 4); @@ -239,6 +310,7 @@ lwres_buffer_getuint32(lwres_buffer_t *b) return (result); } +/* Put an unsigned 32-bit integer. */ void lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val) { @@ -256,6 +328,7 @@ lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val) cp[3] = (unsigned char)(val & 0x000000ff); } +/* copies length bytes of memory at base to b */ void lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, unsigned int length) @@ -270,6 +343,7 @@ lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, b->used += length; } +/* copies length bytes of memory at b to base */ void lwres_buffer_getmem(lwres_buffer_t *b, unsigned char *base, unsigned int length) diff --git a/contrib/bind9/lib/lwres/lwconfig.c b/contrib/bind9/lib/lwres/lwconfig.c index 4b4886bf0ea9..cf4f6a7f0549 100644 --- a/contrib/bind9/lib/lwres/lwconfig.c +++ b/contrib/bind9/lib/lwres/lwconfig.c @@ -15,26 +15,43 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwconfig.c,v 1.33.2.1.2.10 2006/10/03 23:50:50 marka Exp $ */ - -/*** - *** Module for parsing resolv.conf files. - *** - *** entry points are: - *** lwres_conf_init(lwres_context_t *ctx) - *** intializes data structure for subsequent config parsing. - *** - *** lwres_conf_parse(lwres_context_t *ctx, const char *filename) - *** parses a file and fills in the data structure. - *** - *** lwres_conf_print(lwres_context_t *ctx, FILE *fp) - *** prints the config data structure to the FILE. - *** - *** lwres_conf_clear(lwres_context_t *ctx) - *** frees up all the internal memory used by the config data - *** structure, returning it to the lwres_context_t. - *** - ***/ +/* $Id: lwconfig.c,v 1.38.18.5 2006/10/03 23:50:51 marka Exp $ */ + +/*! \file */ + +/** + * Module for parsing resolv.conf files. + * + * lwres_conf_init() creates an empty lwres_conf_t structure for + * lightweight resolver context ctx. + * + * lwres_conf_clear() frees up all the internal memory used by that + * lwres_conf_t structure in resolver context ctx. + * + * lwres_conf_parse() opens the file filename and parses it to initialise + * the resolver context ctx's lwres_conf_t structure. + * + * lwres_conf_print() prints the lwres_conf_t structure for resolver + * context ctx to the FILE fp. + * + * \section lwconfig_return Return Values + * + * lwres_conf_parse() returns #LWRES_R_SUCCESS if it successfully read and + * parsed filename. It returns #LWRES_R_FAILURE if filename could not be + * opened or contained incorrect resolver statements. + * + * lwres_conf_print() returns #LWRES_R_SUCCESS unless an error occurred + * when converting the network addresses to a numeric host address + * string. If this happens, the function returns #LWRES_R_FAILURE. + * + * \section lwconfig_see See Also + * + * stdio(3), \link resolver resolver \endlink + * + * \section files Files + * + * /etc/resolv.conf + */ #include <config.h> @@ -109,7 +126,7 @@ lwresaddr2af(int lwresaddrtype) } -/* +/*! * Eat characters from FP until EOL or EOF. Returns EOF or '\n' */ static int @@ -124,7 +141,7 @@ eatline(FILE *fp) { } -/* +/*! * Eats white space up to next newline or non-whitespace character (of * EOF). Returns the last character read. Comments are considered white * space. @@ -144,7 +161,7 @@ eatwhite(FILE *fp) { } -/* +/*! * Skip over any leading whitespace and then read in the next sequence of * non-whitespace characters. In this context newline is not considered * whitespace. Returns EOF on end-of-file, or the character @@ -203,6 +220,7 @@ lwres_strdup(lwres_context_t *ctx, const char *str) { return (p); } +/*% intializes data structure for subsequent config parsing. */ void lwres_conf_init(lwres_context_t *ctx) { int i; @@ -232,6 +250,7 @@ lwres_conf_init(lwres_context_t *ctx) { } } +/*% Frees up all the internal memory used by the config data structure, returning it to the lwres_context_t. */ void lwres_conf_clear(lwres_context_t *ctx) { int i; @@ -542,6 +561,7 @@ lwres_conf_parseoption(lwres_context_t *ctx, FILE *fp) { return (LWRES_R_SUCCESS); } +/*% parses a file and fills in the data structure. */ lwres_result_t lwres_conf_parse(lwres_context_t *ctx, const char *filename) { FILE *fp = NULL; @@ -600,6 +620,7 @@ lwres_conf_parse(lwres_context_t *ctx, const char *filename) { return (ret); } +/*% Prints the config data structure to the FILE. */ lwres_result_t lwres_conf_print(lwres_context_t *ctx, FILE *fp) { int i; @@ -695,6 +716,7 @@ lwres_conf_print(lwres_context_t *ctx, FILE *fp) { return (LWRES_R_SUCCESS); } +/*% Returns a pointer to the current config structure. */ lwres_conf_t * lwres_conf_get(lwres_context_t *ctx) { REQUIRE(ctx != NULL); diff --git a/contrib/bind9/lib/lwres/lwinetaton.c b/contrib/bind9/lib/lwres/lwinetaton.c index aa630271e8e7..cc4b9bd39041 100644 --- a/contrib/bind9/lib/lwres/lwinetaton.c +++ b/contrib/bind9/lib/lwres/lwinetaton.c @@ -1,5 +1,5 @@ /* - * Portions Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Portions Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Portions Copyright (C) 1996-2001, 2003 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -68,9 +68,11 @@ * SOFTWARE. */ +/*! \file lwinetaton.c + */ #if defined(LIBC_SCCS) && !defined(lint) static char sccsid[] = "@(#)inet_addr.c 8.1 (Berkeley) 6/17/93"; -static char rcsid[] = "$Id: lwinetaton.c,v 1.10.2.1.2.1 2004/03/06 08:15:32 marka Exp $"; +static char rcsid[] = "$Id: lwinetaton.c,v 1.12.18.2 2005/04/29 00:17:19 marka Exp $"; #endif /* LIBC_SCCS and not lint */ #include <config.h> @@ -84,7 +86,7 @@ static char rcsid[] = "$Id: lwinetaton.c,v 1.10.2.1.2.1 2004/03/06 08:15:32 mark #include "assert_p.h" -/* +/*! * Check whether "cp" is a valid ascii representation * of an Internet address and convert to a binary address. * Returns 1 if the address is valid, 0 if not. diff --git a/contrib/bind9/lib/lwres/lwinetntop.c b/contrib/bind9/lib/lwres/lwinetntop.c index 78cd0b033e33..e65656fbec7b 100644 --- a/contrib/bind9/lib/lwres/lwinetntop.c +++ b/contrib/bind9/lib/lwres/lwinetntop.c @@ -15,9 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/*! \file lwinetntop.c + */ #if defined(LIBC_SCCS) && !defined(lint) static char rcsid[] = - "$Id: lwinetntop.c,v 1.9.12.5 2005/11/04 00:16:34 marka Exp $"; + "$Id: lwinetntop.c,v 1.12.18.4 2005/11/03 23:02:24 marka Exp $"; #endif /* LIBC_SCCS and not lint */ #include <config.h> @@ -45,7 +47,7 @@ static const char *inet_ntop6(const unsigned char *src, char *dst, size_t size); #endif -/* char * +/*! char * * lwres_net_ntop(af, src, dst, size) * convert a network format address to presentation format. * return: @@ -69,7 +71,7 @@ lwres_net_ntop(int af, const void *src, char *dst, size_t size) { /* NOTREACHED */ } -/* const char * +/*! const char * * inet_ntop4(src, dst, size) * format an IPv4 address * return: @@ -96,7 +98,7 @@ inet_ntop4(const unsigned char *src, char *dst, size_t size) { return (dst); } -/* const char * +/*! const char * * inet_ntop6(src, dst, size) * convert IPv6 binary address into presentation (printable) format * author: @@ -105,7 +107,7 @@ inet_ntop4(const unsigned char *src, char *dst, size_t size) { #ifdef AF_INET6 static const char * inet_ntop6(const unsigned char *src, char *dst, size_t size) { - /* + /*! * Note that int32_t and int16_t need only be "at least" large enough * to contain a value of the specified size. On some systems, like * Crays, there is no such thing as an integer variable with 16 bits. diff --git a/contrib/bind9/lib/lwres/lwinetpton.c b/contrib/bind9/lib/lwres/lwinetpton.c index e24334b1c82d..5155fd1704d2 100644 --- a/contrib/bind9/lib/lwres/lwinetpton.c +++ b/contrib/bind9/lib/lwres/lwinetpton.c @@ -15,8 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/*! \file lwinetpton.c + */ + #if defined(LIBC_SCCS) && !defined(lint) -static char rcsid[] = "$Id: lwinetpton.c,v 1.6.206.3 2005/03/31 23:56:15 marka Exp $"; +static char rcsid[] = "$Id: lwinetpton.c,v 1.7.18.3 2005/04/27 05:02:48 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include <config.h> @@ -38,7 +41,8 @@ static char rcsid[] = "$Id: lwinetpton.c,v 1.6.206.3 2005/03/31 23:56:15 marka E static int inet_pton4(const char *src, unsigned char *dst); static int inet_pton6(const char *src, unsigned char *dst); -/* int +/*! + * int * lwres_net_pton(af, src, dst) * convert from presentation format (which usually means ASCII printable) * to network format (which is usually some kind of binary format). @@ -63,7 +67,7 @@ lwres_net_pton(int af, const char *src, void *dst) { /* NOTREACHED */ } -/* int +/*! int * inet_pton4(src, dst) * like inet_aton() but without all the hexadecimal and shorthand. * return: @@ -110,7 +114,7 @@ inet_pton4(const char *src, unsigned char *dst) { return (1); } -/* int +/*! int * inet_pton6(src, dst) * convert presentation level address to network order binary form. * return: diff --git a/contrib/bind9/lib/lwres/lwpacket.c b/contrib/bind9/lib/lwres/lwpacket.c index 6e28df02d677..964b46548829 100644 --- a/contrib/bind9/lib/lwres/lwpacket.c +++ b/contrib/bind9/lib/lwres/lwpacket.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,46 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwpacket.c,v 1.13.206.1 2004/03/06 08:15:32 marka Exp $ */ +/* $Id: lwpacket.c,v 1.14.18.2 2005/04/29 00:17:19 marka Exp $ */ + +/*! \file */ + +/** + * These functions rely on a struct lwres_lwpacket which is defined in + * \link lwpacket.h lwres/lwpacket.h.\endlink + * + * The following opcodes are currently defined: + * + * \li #LWRES_OPCODE_NOOP + * Success is always returned and the packet contents are + * echoed. The \link lwres_noop.c lwres_noop_*()\endlink functions should be used for this + * type. + * + * \li #LWRES_OPCODE_GETADDRSBYNAME + * returns all known addresses for a given name. The + * \link lwres_gabn.c lwres_gabn_*()\endlink functions should be used for this type. + * + * \li #LWRES_OPCODE_GETNAMEBYADDR + * return the hostname for the given address. The + * \link lwres_gnba.c lwres_gnba_*() \endlink functions should be used for this type. + * + * lwres_lwpacket_renderheader() transfers the contents of lightweight + * resolver packet structure #lwres_lwpacket_t *pkt in network byte + * order to the lightweight resolver buffer, *b. + * + * lwres_lwpacket_parseheader() performs the converse operation. It + * transfers data in network byte order from buffer *b to resolver + * packet *pkt. The contents of the buffer b should correspond to a + * #lwres_lwpacket_t. + * + * \section lwpacket_return Return Values + * + * Successful calls to lwres_lwpacket_renderheader() and + * lwres_lwpacket_parseheader() return #LWRES_R_SUCCESS. If there is + * insufficient space to copy data between the buffer *b and + * lightweight resolver packet *pkt both functions return + * #LWRES_R_UNEXPECTEDEND. + */ #include <config.h> @@ -29,9 +68,12 @@ #include "assert_p.h" +/*% Length of Packet */ #define LWPACKET_LENGTH \ (sizeof(lwres_uint16_t) * 4 + sizeof(lwres_uint32_t) * 5) +/*% transfers the contents of lightweight resolver packet structure lwres_lwpacket_t *pkt in network byte order to the lightweight resolver buffer, *b. */ + lwres_result_t lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt) { REQUIRE(b != NULL); @@ -53,6 +95,8 @@ lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt) { return (LWRES_R_SUCCESS); } +/*% transfers data in network byte order from buffer *b to resolver packet *pkt. The contents of the buffer b should correspond to a lwres_lwpacket_t. */ + lwres_result_t lwres_lwpacket_parseheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt) { lwres_uint32_t space; diff --git a/contrib/bind9/lib/lwres/lwres_gabn.c b/contrib/bind9/lib/lwres/lwres_gabn.c index 9df87ce6706c..c6f113971503 100644 --- a/contrib/bind9/lib/lwres/lwres_gabn.c +++ b/contrib/bind9/lib/lwres/lwres_gabn.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,92 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres_gabn.c,v 1.27.12.3 2004/03/08 09:05:10 marka Exp $ */ +/* $Id: lwres_gabn.c,v 1.29.18.2 2005/04/29 00:17:19 marka Exp $ */ + +/*! \file lwres_gabn.c + These are low-level routines for creating and parsing lightweight + resolver name-to-address lookup request and response messages. + + There are four main functions for the getaddrbyname opcode. One render + function converts a getaddrbyname request structure -- + 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 -- + 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. + + These structures are defined in \link lwres.h <lwres/lwres.h>.\endlink They are shown below. + +\code +#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; +\endcode + + lwres_gabnrequest_render() uses resolver context ctx to convert + getaddrbyname request structure req to canonical format. The packet + header structure pkt is initialised and transferred to buffer b. The + contents of *req are then appended to the buffer in canonical format. + lwres_gabnresponse_render() performs the same task, except it converts + a getaddrbyname response structure lwres_gabnresponse_t to the + lightweight resolver's canonical format. + + lwres_gabnrequest_parse() uses context ctx to convert the contents of + packet pkt to a lwres_gabnrequest_t structure. Buffer b provides space + to be used for storing this structure. When the function succeeds, the + resulting lwres_gabnrequest_t is made available through *structp. + lwres_gabnresponse_parse() offers the same semantics as + lwres_gabnrequest_parse() except it yields a lwres_gabnresponse_t + structure. + + lwres_gabnresponse_free() and lwres_gabnrequest_free() release the + memory in resolver context ctx that was allocated to the + lwres_gabnresponse_t or lwres_gabnrequest_t structures referenced via + structp. Any memory associated with ancillary buffers and strings for + those structures is also discarded. + +\section lwres_gabn_return Return Values + + The getaddrbyname opcode functions lwres_gabnrequest_render(), + lwres_gabnresponse_render() lwres_gabnrequest_parse() and + lwres_gabnresponse_parse() all return #LWRES_R_SUCCESS on success. They + return #LWRES_R_NOMEMORY if memory allocation fails. + #LWRES_R_UNEXPECTEDEND is returned if the available space in the buffer + b is too small to accommodate the packet header or the + lwres_gabnrequest_t and lwres_gabnresponse_t structures. + lwres_gabnrequest_parse() and lwres_gabnresponse_parse() will return + #LWRES_R_UNEXPECTEDEND if the buffer is not empty after decoding the + received packet. These functions will return #LWRES_R_FAILURE if + pktflags in the packet header structure #lwres_lwpacket_t indicate that + the packet is not a response to an earlier query. + +\section lwres_gabn_see See Also + + \link lwpacket.c lwres_lwpacket \endlink + */ #include <config.h> @@ -31,6 +116,7 @@ #include "context_p.h" #include "assert_p.h" +/*% uses resolver context ctx to convert getaddrbyname request structure req to canonical format. */ lwres_result_t lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -97,7 +183,7 @@ lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, return (LWRES_R_SUCCESS); } - +/*% converts a getaddrbyname response structure lwres_gabnresponse_t to the lightweight resolver's canonical format. */ lwres_result_t lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -194,7 +280,7 @@ lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, return (LWRES_R_SUCCESS); } - +/*% Uses context ctx to convert the contents of packet pkt to a lwres_gabnrequest_t structure. */ lwres_result_t lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp) @@ -243,6 +329,8 @@ lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (LWRES_R_SUCCESS); } +/*% Offers the same semantics as lwres_gabnrequest_parse() except it yields a lwres_gabnresponse_t structure. */ + lwres_result_t lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp) @@ -372,6 +460,7 @@ lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Release the memory in resolver context ctx that was allocated to the lwres_gabnrequest_t. */ void lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp) { @@ -386,6 +475,7 @@ lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp) CTXFREE(gabn, sizeof(lwres_gabnrequest_t)); } +/*% Release the memory in resolver context ctx that was allocated to the lwres_gabnresponse_t. */ void lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp) { diff --git a/contrib/bind9/lib/lwres/lwres_gnba.c b/contrib/bind9/lib/lwres/lwres_gnba.c index a11c0665792d..5f4164873f74 100644 --- a/contrib/bind9/lib/lwres/lwres_gnba.c +++ b/contrib/bind9/lib/lwres/lwres_gnba.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000-2002 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,88 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres_gnba.c,v 1.20.2.2.8.4 2004/03/08 09:05:11 marka Exp $ */ +/* $Id: lwres_gnba.c,v 1.23.18.2 2005/04/29 00:17:20 marka Exp $ */ + +/*! \file lwres_gnba.c + These are low-level routines for creating and parsing lightweight + resolver address-to-name lookup request and response messages. + + There are four main functions for the getnamebyaddr opcode. One + render function converts a getnamebyaddr request structure -- + lwres_gnbarequest_t -- to the lightweight resolver's canonical + format. It is complemented by a parse function that converts a + packet in this canonical format to a getnamebyaddr request + structure. Another render function converts the getnamebyaddr + response structure -- 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. + + These structures are defined in \link lwres.h <lwres/lwres.h.>\endlink They are shown + below. + +\code +#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; +\endcode + + lwres_gnbarequest_render() uses resolver context ctx to convert + getnamebyaddr request structure req to canonical format. The packet + header structure pkt is initialised and transferred to buffer b. + The contents of *req are then appended to the buffer in canonical + format. lwres_gnbaresponse_render() performs the same task, except + it converts a getnamebyaddr response structure lwres_gnbaresponse_t + to the lightweight resolver's canonical format. + + lwres_gnbarequest_parse() uses context ctx to convert the contents + of packet pkt to a lwres_gnbarequest_t structure. Buffer b provides + space to be used for storing this structure. When the function + succeeds, the resulting lwres_gnbarequest_t is made available + through *structp. lwres_gnbaresponse_parse() offers the same +semantics as lwres_gnbarequest_parse() except it yields a + lwres_gnbaresponse_t structure. + + lwres_gnbaresponse_free() and lwres_gnbarequest_free() release the + memory in resolver context ctx that was allocated to the + lwres_gnbaresponse_t or lwres_gnbarequest_t structures referenced + via structp. Any memory associated with ancillary buffers and + strings for those structures is also discarded. + +\section lwres_gbna_return Return Values + + The getnamebyaddr opcode functions lwres_gnbarequest_render(), + lwres_gnbaresponse_render() lwres_gnbarequest_parse() and + lwres_gnbaresponse_parse() all return #LWRES_R_SUCCESS on success. + They return #LWRES_R_NOMEMORY if memory allocation fails. + #LWRES_R_UNEXPECTEDEND is returned if the available space in the + buffer b is too small to accommodate the packet header or the + lwres_gnbarequest_t and lwres_gnbaresponse_t structures. + lwres_gnbarequest_parse() and lwres_gnbaresponse_parse() will + return #LWRES_R_UNEXPECTEDEND if the buffer is not empty after + decoding the received packet. These functions will return + #LWRES_R_FAILURE if pktflags in the packet header structure + #lwres_lwpacket_t indicate that the packet is not a response to an + earlier query. + +\section lwres_gbna_see See Also + + \link lwpacket.c lwres_packet\endlink + + */ #include <config.h> @@ -31,6 +112,7 @@ #include "context_p.h" #include "assert_p.h" +/*% Uses resolver context ctx to convert getnamebyaddr request structure req to canonical format. */ lwres_result_t lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -88,6 +170,7 @@ lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req, return (LWRES_R_SUCCESS); } +/*% Converts a getnamebyaddr response structure lwres_gnbaresponse_t to the lightweight resolver's canonical format. */ lwres_result_t lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -159,6 +242,7 @@ lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, return (LWRES_R_SUCCESS); } +/*% Uses context ctx to convert the contents of packet pkt to a lwres_gnbarequest_t structure. */ lwres_result_t lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp) @@ -202,6 +286,8 @@ lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Offers the same semantics as lwres_gnbarequest_parse() except it yields a lwres_gnbaresponse_t structure. */ + lwres_result_t lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbaresponse_t **structp) @@ -292,6 +378,7 @@ lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Release the memory in resolver context ctx that was allocated to the lwres_gnbarequest_t. */ void lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp) { @@ -306,6 +393,7 @@ lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp) CTXFREE(gnba, sizeof(lwres_gnbarequest_t)); } +/*% Release the memory in resolver context ctx that was allocated to the lwres_gnbaresponse_t. */ void lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp) { diff --git a/contrib/bind9/lib/lwres/lwres_grbn.c b/contrib/bind9/lib/lwres/lwres_grbn.c index f8147fc622e8..976708e323b5 100644 --- a/contrib/bind9/lib/lwres/lwres_grbn.c +++ b/contrib/bind9/lib/lwres/lwres_grbn.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres_grbn.c,v 1.4.12.3 2004/03/08 09:05:11 marka Exp $ */ +/* $Id: lwres_grbn.c,v 1.6.18.2 2005/04/29 00:17:20 marka Exp $ */ + +/*! \file lwres_grbn.c + + */ #include <config.h> @@ -31,6 +35,7 @@ #include "context_p.h" #include "assert_p.h" +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ lwres_result_t lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -103,6 +108,7 @@ lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req, return (LWRES_R_SUCCESS); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ lwres_result_t lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -190,6 +196,7 @@ lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req, return (LWRES_R_SUCCESS); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ lwres_result_t lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp) @@ -243,6 +250,7 @@ lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (LWRES_R_SUCCESS); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ lwres_result_t lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_grbnresponse_t **structp) @@ -376,6 +384,7 @@ lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ void lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp) { @@ -390,6 +399,7 @@ lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp) CTXFREE(grbn, sizeof(lwres_grbnrequest_t)); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ void lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp) { diff --git a/contrib/bind9/lib/lwres/lwres_noop.c b/contrib/bind9/lib/lwres/lwres_noop.c index f67c2b3cb0c5..e76bc4dde6e1 100644 --- a/contrib/bind9/lib/lwres/lwres_noop.c +++ b/contrib/bind9/lib/lwres/lwres_noop.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,87 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres_noop.c,v 1.14.206.1 2004/03/06 08:15:33 marka Exp $ */ +/* $Id: lwres_noop.c,v 1.15.18.2 2005/04/29 00:17:20 marka Exp $ */ + +/*! \file */ + +/** + * These are low-level routines for creating and parsing lightweight + * resolver no-op request and response messages. + * + * The no-op message is analogous to a ping packet: a packet is sent to + * the resolver daemon and is simply echoed back. The opcode is intended + * to allow a client to determine if the server is operational or not. + * + * There are four main functions for the no-op opcode. One render + * function converts a no-op request structure -- 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 -- 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. + * + * These structures are defined in \link lwres.h <lwres/lwres.h.> \endlink They are shown below. + * + * \code + * #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; + * \endcode + * + * 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. + * + * lwres_nooprequest_render() uses resolver context ctx to convert no-op + * request structure req to canonical format. The packet header structure + * pkt is initialised and transferred to buffer b. The contents of *req + * are then appended to the buffer in canonical format. + * lwres_noopresponse_render() performs the same task, except it converts + * a no-op response structure lwres_noopresponse_t to the lightweight + * resolver's canonical format. + * + * lwres_nooprequest_parse() uses context ctx to convert the contents of + * packet pkt to a lwres_nooprequest_t structure. Buffer b provides space + * to be used for storing this structure. When the function succeeds, the + * resulting lwres_nooprequest_t is made available through *structp. + * lwres_noopresponse_parse() offers the same semantics as + * lwres_nooprequest_parse() except it yields a lwres_noopresponse_t + * structure. + * + * lwres_noopresponse_free() and lwres_nooprequest_free() release the + * memory in resolver context ctx that was allocated to the + * lwres_noopresponse_t or lwres_nooprequest_t structures referenced via + * structp. + * + * \section lwres_noop_return Return Values + * + * The no-op opcode functions lwres_nooprequest_render(), + * lwres_noopresponse_render() lwres_nooprequest_parse() and + * lwres_noopresponse_parse() all return #LWRES_R_SUCCESS on success. They + * return #LWRES_R_NOMEMORY if memory allocation fails. + * #LWRES_R_UNEXPECTEDEND is returned if the available space in the buffer + * b is too small to accommodate the packet header or the + * lwres_nooprequest_t and lwres_noopresponse_t structures. + * lwres_nooprequest_parse() and lwres_noopresponse_parse() will return + * #LWRES_R_UNEXPECTEDEND if the buffer is not empty after decoding the + * received packet. These functions will return #LWRES_R_FAILURE if + * pktflags in the packet header structure #lwres_lwpacket_t indicate that + * the packet is not a response to an earlier query. + * + * \section lwres_noop_see See Also + * + * lwpacket.c + */ #include <config.h> @@ -31,6 +111,7 @@ #include "context_p.h" #include "assert_p.h" +/*% Uses resolver context ctx to convert no-op request structure req to canonical format. */ lwres_result_t lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -82,6 +163,8 @@ lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, return (LWRES_R_SUCCESS); } +/*% Converts a no-op response structure lwres_noopresponse_t to the lightweight resolver's canonical format. */ + lwres_result_t lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -132,6 +215,7 @@ lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, return (LWRES_R_SUCCESS); } +/*% Uses context ctx to convert the contents of packet pkt to a lwres_nooprequest_t structure. */ lwres_result_t lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp) @@ -179,6 +263,7 @@ lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Offers the same semantics as lwres_nooprequest_parse() except it yields a lwres_noopresponse_t structure. */ lwres_result_t lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_noopresponse_t **structp) @@ -226,6 +311,7 @@ lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Release the memory in resolver context ctx. */ void lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp) { @@ -240,6 +326,7 @@ lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp) CTXFREE(noop, sizeof(lwres_noopresponse_t)); } +/*% Release the memory in resolver context ctx. */ void lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp) { diff --git a/contrib/bind9/lib/lwres/lwresutil.c b/contrib/bind9/lib/lwres/lwresutil.c index 1035f17057a9..6d6764fcd306 100644 --- a/contrib/bind9/lib/lwres/lwresutil.c +++ b/contrib/bind9/lib/lwres/lwresutil.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,86 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwresutil.c,v 1.29.206.1 2004/03/06 08:15:33 marka Exp $ */ +/* $Id: lwresutil.c,v 1.30.18.2 2005/04/29 00:17:20 marka Exp $ */ + +/*! \file */ + +/** + * lwres_string_parse() retrieves a DNS-encoded string starting the + * current pointer of lightweight resolver buffer b: i.e. b->current. + * When the function returns, the address of the first byte of the + * encoded string is returned via *c and the length of that string is + * given by *len. The buffer's current pointer is advanced to point at + * the character following the string length, the encoded string, and + * the trailing NULL character. + * + * lwres_addr_parse() extracts an address from the buffer b. The + * buffer's current pointer b->current is presumed to point at an + * encoded address: the address preceded by a 32-bit protocol family + * identifier and a 16-bit length field. The encoded address is copied + * to addr->address and addr->length indicates the size in bytes of + * the address that was copied. b->current is advanced to point at the + * next byte of available data in the buffer following the encoded + * address. + * + * lwres_getaddrsbyname() and lwres_getnamebyaddr() use the + * lwres_gnbaresponse_t structure defined below: + * + * \code + * 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; + * \endcode + * + * The contents of this structure are not manipulated directly but + * they are controlled through the \link lwres_gabn.c lwres_gabn*\endlink functions. + * + * The lightweight resolver uses lwres_getaddrsbyname() to perform + * foward lookups. Hostname name is looked up using the resolver + * context ctx for memory allocation. addrtypes is a bitmask + * indicating which type of addresses are to be looked up. Current + * values for this bitmask are #LWRES_ADDRTYPE_V4 for IPv4 addresses + * and #LWRES_ADDRTYPE_V6 for IPv6 addresses. Results of the lookup are + * returned in *structp. + * + * lwres_getnamebyaddr() performs reverse lookups. Resolver context + * ctx is used for memory allocation. The address type is indicated by + * addrtype: #LWRES_ADDRTYPE_V4 or #LWRES_ADDRTYPE_V6. The address to be + * looked up is given by addr and its length is addrlen bytes. The + * result of the function call is made available through *structp. + * + * \section lwresutil_return Return Values + * + * Successful calls to lwres_string_parse() and lwres_addr_parse() + * return #LWRES_R_SUCCESS. Both functions return #LWRES_R_FAILURE if + * the buffer is corrupt or #LWRES_R_UNEXPECTEDEND if the buffer has + * less space than expected for the components of the encoded string + * or address. + * + * lwres_getaddrsbyname() returns #LWRES_R_SUCCESS on success and it + * returns #LWRES_R_NOTFOUND if the hostname name could not be found. + * + * #LWRES_R_SUCCESS is returned by a successful call to + * lwres_getnamebyaddr(). + * + * Both lwres_getaddrsbyname() and lwres_getnamebyaddr() return + * #LWRES_R_NOMEMORY when memory allocation requests fail and + * #LWRES_R_UNEXPECTEDEND if the buffers used for sending queries and + * receiving replies are too small. + * + * \section lwresutil_see See Also + * + * lwbuffer.c, lwres_gabn.c + */ #include <config.h> @@ -31,7 +110,8 @@ #include "assert_p.h" #include "context_p.h" -/* +/*% Parse data. */ +/*! * Requires: * * The "current" pointer in "b" points to encoded raw data. @@ -78,7 +158,8 @@ lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len) return (LWRES_R_SUCCESS); } -/* +/*% Retrieves a DNS-encoded string. */ +/*! * Requires: * * The "current" pointer in "b" point to an encoded string. @@ -133,6 +214,7 @@ lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len) return (LWRES_R_SUCCESS); } +/*% Extracts an address from the buffer b. */ lwres_result_t lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr) { @@ -154,6 +236,7 @@ lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr) return (LWRES_R_SUCCESS); } +/*% Used to perform forward lookups. */ lwres_result_t lwres_getaddrsbyname(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp) @@ -268,6 +351,7 @@ lwres_getaddrsbyname(lwres_context_t *ctx, const char *name, } +/*% Used to perform reverse lookups. */ lwres_result_t lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, @@ -376,6 +460,7 @@ lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype, return (ret); } +/*% Get rdata by name. */ lwres_result_t lwres_getrdatabyname(lwres_context_t *ctx, const char *name, lwres_uint16_t rdclass, lwres_uint16_t rdtype, diff --git a/contrib/bind9/lib/lwres/man/Makefile.in b/contrib/bind9/lib/lwres/man/Makefile.in index a591a2a24a3a..e28123cd21dc 100644 --- a/contrib/bind9/lib/lwres/man/Makefile.in +++ b/contrib/bind9/lib/lwres/man/Makefile.in @@ -13,7 +13,7 @@ # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -# $Id: Makefile.in,v 1.6.206.1 2004/03/06 08:15:36 marka Exp $ +# $Id: Makefile.in,v 1.7 2004/03/05 05:12:55 marka Exp $ srcdir = @srcdir@ VPATH = @srcdir@ diff --git a/contrib/bind9/lib/lwres/man/lwres.3 b/contrib/bind9/lib/lwres/man/lwres.3 index 886f1f1b1a8c..968e8f857af2 100644 --- a/contrib/bind9/lib/lwres/man/lwres.3 +++ b/contrib/bind9/lib/lwres/man/lwres.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres.3,v 1.15.206.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres.3,v 1.17.18.11 2007/01/30 00:23:44 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -159,4 +159,7 @@ bit should be set. \fBresolver\fR(5), \fBlwresd\fR(8). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres.docbook b/contrib/bind9/lib/lwres/man/lwres.docbook index 83258a9dd743..2a94ec80acee 100644 --- a/contrib/bind9/lib/lwres/man/lwres.docbook +++ b/contrib/bind9/lib/lwres/man/lwres.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,23 +18,28 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres.docbook,v 1.3.206.3 2005/05/12 21:36:11 sra Exp $ --> - +<!-- $Id: lwres.docbook,v 1.4.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> -<refmeta> -<refentrytitle>lwres</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> + + <refmeta> + <refentrytitle>lwres</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> + <refnamediv> + <refname>lwres</refname> + <refpurpose>introduction to the lightweight resolver library</refpurpose> + </refnamediv> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -44,217 +49,218 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres</refname> -<refpurpose>introduction to the lightweight resolver library</refpurpose> -</refnamediv> - -<refsynopsisdiv> -<funcsynopsis> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo> </funcsynopsis> -</refsynopsisdiv> + </refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> -<para> -The BIND 9 lightweight resolver library is a simple, name service -independent stub resolver library. It provides hostname-to-address -and address-to-hostname lookup services to applications by -transmitting lookup requests to a resolver daemon -<command>lwresd</command> -running on the local host. The resover daemon performs the -lookup using the DNS or possibly other name service protocols, -and returns the results to the application through the library. -The library and resolver daemon communicate using a simple -UDP-based protocol. -</para> -</refsect1> + <refsect1> + <title>DESCRIPTION</title> + <para> + The BIND 9 lightweight resolver library is a simple, name service + independent stub resolver library. It provides hostname-to-address + and address-to-hostname lookup services to applications by + transmitting lookup requests to a resolver daemon + <command>lwresd</command> + running on the local host. The resover daemon performs the + lookup using the DNS or possibly other name service protocols, + and returns the results to the application through the library. + The library and resolver daemon communicate using a simple + UDP-based protocol. + </para> + </refsect1> -<refsect1> -<title>OVERVIEW</title> -<para> -The lwresd library implements multiple name service APIs. -The standard -<function>gethostbyname()</function>, -<function>gethostbyaddr()</function>, -<function>gethostbyname_r()</function>, -<function>gethostbyaddr_r()</function>, -<function>getaddrinfo()</function>, -<function>getipnodebyname()</function>, -and -<function>getipnodebyaddr()</function> -functions are all supported. To allow the lwres library to coexist -with system libraries that define functions of the same name, -the library defines these functions with names prefixed by -<literal>lwres_</literal>. -To define the standard names, applications must include the -header file -<filename><lwres/netdb.h></filename> -which contains macro definitions mapping the standard function names -into -<literal>lwres_</literal> -prefixed ones. Operating system vendors who integrate the lwres -library into their base distributions should rename the functions -in the library proper so that the renaming macros are not needed. -</para> -<para> -The library also provides a native API consisting of the functions -<function>lwres_getaddrsbyname()</function> -and -<function>lwres_getnamebyaddr()</function>. -These may be called by applications that require more detailed -control over the lookup process than the standard functions -provide. -</para> -<para> -In addition to these name service independent address lookup -functions, the library implements a new, experimental API -for looking up arbitrary DNS resource records, using the -<function>lwres_getaddrsbyname()</function> -function. -</para> -<para> -Finally, there is a low-level API for converting lookup -requests and responses to and from raw lwres protocol packets. -This API can be used by clients requiring nonblocking operation, -and is also used when implementing the server side of the lwres -protocol, for example in the -<command>lwresd</command> -resolver daemon. The use of this low-level API in clients -and servers is outlined in the following sections. -</para> -</refsect1> -<refsect1> -<title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title> -<para> -When a client program wishes to make an lwres request using the -native low-level API, it typically performs the following -sequence of actions. -</para> -<para> -(1) Allocate or use an existing <type>lwres_packet_t</type>, -called <varname>pkt</varname> below. -</para> -<para> -(2) Set <structfield>pkt.recvlength</structfield> to the maximum length we will accept. -This is done so the receiver of our packets knows how large our receive -buffer is. The "default" is a constant in -<filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>. -</para> -<para> -(3) Set <structfield>pkt.serial</structfield> -to a unique serial number. This value is echoed -back to the application by the remote server. -</para> -<para> -(4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to 0. -</para> -<para> -(5) Set <structfield>pkt.result</structfield> to 0. -</para> -<para> -(6) Call <function>lwres_*request_render()</function>, -or marshall in the data using the primitives -such as <function>lwres_packet_render()</function> -and storing the packet data. -</para> -<para> -(7) Transmit the resulting buffer. -</para> -<para> -(8) Call <function>lwres_*response_parse()</function> -to parse any packets received. -</para> -<para> -(9) Verify that the opcode and serial match a request, and process the -packet specific information contained in the body. -</para> -</refsect1> -<refsect1> -<title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title> -<para> -When implementing the server side of the lightweight resolver -protocol using the lwres library, a sequence of actions like the -following is typically involved in processing each request packet. -</para> -<para> -Note that the same <type>lwres_packet_t</type> is used -in both the <function>_parse()</function> and <function>_render()</function> calls, -with only a few modifications made -to the packet header's contents between uses. This method is recommended -as it keeps the serial, opcode, and other fields correct. -</para> -<para> -(1) When a packet is received, call <function>lwres_*request_parse()</function> to -unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below) -as well as a data specific type, such as <type>lwres_gabnrequest_t</type>. -</para> -<para> -(2) Process the request in the data specific type. -</para> -<para> -(3) Set the <structfield>pkt.result</structfield>, -<structfield>pkt.recvlength</structfield> as above. All other fields can -be left untouched since they were filled in by the <function>*_parse()</function> call -above. If using <function>lwres_*response_render()</function>, -<structfield>pkt.pktflags</structfield> will be set up -properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be -set. -</para> -<para> -(4) Call the data specific rendering function, such as -<function>lwres_gabnresponse_render()</function>. -</para> -<para> -(5) Send the resulting packet to the client. -</para> -<para> -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <refsect1> + <title>OVERVIEW</title> + <para> + The lwresd library implements multiple name service APIs. + The standard + <function>gethostbyname()</function>, + <function>gethostbyaddr()</function>, + <function>gethostbyname_r()</function>, + <function>gethostbyaddr_r()</function>, + <function>getaddrinfo()</function>, + <function>getipnodebyname()</function>, + and + <function>getipnodebyaddr()</function> + functions are all supported. To allow the lwres library to coexist + with system libraries that define functions of the same name, + the library defines these functions with names prefixed by + <literal>lwres_</literal>. + To define the standard names, applications must include the + header file + <filename><lwres/netdb.h></filename> + which contains macro definitions mapping the standard function names + into + <literal>lwres_</literal> + prefixed ones. Operating system vendors who integrate the lwres + library into their base distributions should rename the functions + in the library proper so that the renaming macros are not needed. + </para> + <para> + The library also provides a native API consisting of the functions + <function>lwres_getaddrsbyname()</function> + and + <function>lwres_getnamebyaddr()</function>. + These may be called by applications that require more detailed + control over the lookup process than the standard functions + provide. + </para> + <para> + In addition to these name service independent address lookup + functions, the library implements a new, experimental API + for looking up arbitrary DNS resource records, using the + <function>lwres_getaddrsbyname()</function> + function. + </para> + <para> + Finally, there is a low-level API for converting lookup + requests and responses to and from raw lwres protocol packets. + This API can be used by clients requiring nonblocking operation, + and is also used when implementing the server side of the lwres + protocol, for example in the + <command>lwresd</command> + resolver daemon. The use of this low-level API in clients + and servers is outlined in the following sections. + </para> + </refsect1> + <refsect1> + <title>CLIENT-SIDE LOW-LEVEL API CALL FLOW</title> + <para> + When a client program wishes to make an lwres request using the + native low-level API, it typically performs the following + sequence of actions. + </para> + <para> + (1) Allocate or use an existing <type>lwres_packet_t</type>, + called <varname>pkt</varname> below. + </para> + <para> + (2) Set <structfield>pkt.recvlength</structfield> to the maximum length + we will accept. + This is done so the receiver of our packets knows how large our receive + buffer is. The "default" is a constant in + <filename>lwres.h</filename>: <constant>LWRES_RECVLENGTH = 4096</constant>. + </para> + <para> + (3) Set <structfield>pkt.serial</structfield> + to a unique serial number. This value is echoed + back to the application by the remote server. + </para> + <para> + (4) Set <structfield>pkt.pktflags</structfield>. Usually this is set to + 0. + </para> + <para> + (5) Set <structfield>pkt.result</structfield> to 0. + </para> + <para> + (6) Call <function>lwres_*request_render()</function>, + or marshall in the data using the primitives + such as <function>lwres_packet_render()</function> + and storing the packet data. + </para> + <para> + (7) Transmit the resulting buffer. + </para> + <para> + (8) Call <function>lwres_*response_parse()</function> + to parse any packets received. + </para> + <para> + (9) Verify that the opcode and serial match a request, and process the + packet specific information contained in the body. + </para> + </refsect1> + <refsect1> + <title>SERVER-SIDE LOW-LEVEL API CALL FLOW</title> + <para> + When implementing the server side of the lightweight resolver + protocol using the lwres library, a sequence of actions like the + following is typically involved in processing each request packet. + </para> + <para> + Note that the same <type>lwres_packet_t</type> is used + in both the <function>_parse()</function> and <function>_render()</function> calls, + with only a few modifications made + to the packet header's contents between uses. This method is + recommended + as it keeps the serial, opcode, and other fields correct. + </para> + <para> + (1) When a packet is received, call <function>lwres_*request_parse()</function> to + unmarshall it. This returns a <type>lwres_packet_t</type> (also called <varname>pkt</varname>, below) + as well as a data specific type, such as <type>lwres_gabnrequest_t</type>. + </para> + <para> + (2) Process the request in the data specific type. + </para> + <para> + (3) Set the <structfield>pkt.result</structfield>, + <structfield>pkt.recvlength</structfield> as above. All other fields + can + be left untouched since they were filled in by the <function>*_parse()</function> call + above. If using <function>lwres_*response_render()</function>, + <structfield>pkt.pktflags</structfield> will be set up + properly. Otherwise, the <constant>LWRES_LWPACKETFLAG_RESPONSE</constant> bit should be + set. + </para> + <para> + (4) Call the data specific rendering function, such as + <function>lwres_gabnresponse_render()</function>. + </para> + <para> + (5) Send the resulting packet to the client. + </para> + <para></para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_noop</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_gnba</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_context</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_config</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum> -</citerefentry>. + <citerefentry> + <refentrytitle>lwresd</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>. -</para> -</refsect1> -</refentry> + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres.html b/contrib/bind9/lib/lwres/man/lwres.html index 02af1f7d98c8..e4bbc098fa16 100644 --- a/contrib/bind9/lib/lwres/man/lwres.html +++ b/contrib/bind9/lib/lwres/man/lwres.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres.html,v 1.4.2.1.4.12 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres.html,v 1.5.18.18 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres — introduction to the lightweight resolver library</p> @@ -32,185 +32,187 @@ <div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre></div> </div> <div class="refsect1" lang="en"> -<a name="id2549397"></a><h2>DESCRIPTION</h2> -<p> -The BIND 9 lightweight resolver library is a simple, name service -independent stub resolver library. It provides hostname-to-address -and address-to-hostname lookup services to applications by -transmitting lookup requests to a resolver daemon -<span><strong class="command">lwresd</strong></span> -running on the local host. The resover daemon performs the -lookup using the DNS or possibly other name service protocols, -and returns the results to the application through the library. -The library and resolver daemon communicate using a simple -UDP-based protocol. -</p> +<a name="id2543348"></a><h2>DESCRIPTION</h2> +<p> + The BIND 9 lightweight resolver library is a simple, name service + independent stub resolver library. It provides hostname-to-address + and address-to-hostname lookup services to applications by + transmitting lookup requests to a resolver daemon + <span><strong class="command">lwresd</strong></span> + running on the local host. The resover daemon performs the + lookup using the DNS or possibly other name service protocols, + and returns the results to the application through the library. + The library and resolver daemon communicate using a simple + UDP-based protocol. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549410"></a><h2>OVERVIEW</h2> -<p> -The lwresd library implements multiple name service APIs. -The standard -<code class="function">gethostbyname()</code>, -<code class="function">gethostbyaddr()</code>, -<code class="function">gethostbyname_r()</code>, -<code class="function">gethostbyaddr_r()</code>, -<code class="function">getaddrinfo()</code>, -<code class="function">getipnodebyname()</code>, -and -<code class="function">getipnodebyaddr()</code> -functions are all supported. To allow the lwres library to coexist -with system libraries that define functions of the same name, -the library defines these functions with names prefixed by -<code class="literal">lwres_</code>. -To define the standard names, applications must include the -header file -<code class="filename"><lwres/netdb.h></code> -which contains macro definitions mapping the standard function names -into -<code class="literal">lwres_</code> -prefixed ones. Operating system vendors who integrate the lwres -library into their base distributions should rename the functions -in the library proper so that the renaming macros are not needed. -</p> -<p> -The library also provides a native API consisting of the functions -<code class="function">lwres_getaddrsbyname()</code> -and -<code class="function">lwres_getnamebyaddr()</code>. -These may be called by applications that require more detailed -control over the lookup process than the standard functions -provide. -</p> -<p> -In addition to these name service independent address lookup -functions, the library implements a new, experimental API -for looking up arbitrary DNS resource records, using the -<code class="function">lwres_getaddrsbyname()</code> -function. -</p> -<p> -Finally, there is a low-level API for converting lookup -requests and responses to and from raw lwres protocol packets. -This API can be used by clients requiring nonblocking operation, -and is also used when implementing the server side of the lwres -protocol, for example in the -<span><strong class="command">lwresd</strong></span> -resolver daemon. The use of this low-level API in clients -and servers is outlined in the following sections. -</p> +<a name="id2543361"></a><h2>OVERVIEW</h2> +<p> + The lwresd library implements multiple name service APIs. + The standard + <code class="function">gethostbyname()</code>, + <code class="function">gethostbyaddr()</code>, + <code class="function">gethostbyname_r()</code>, + <code class="function">gethostbyaddr_r()</code>, + <code class="function">getaddrinfo()</code>, + <code class="function">getipnodebyname()</code>, + and + <code class="function">getipnodebyaddr()</code> + functions are all supported. To allow the lwres library to coexist + with system libraries that define functions of the same name, + the library defines these functions with names prefixed by + <code class="literal">lwres_</code>. + To define the standard names, applications must include the + header file + <code class="filename"><lwres/netdb.h></code> + which contains macro definitions mapping the standard function names + into + <code class="literal">lwres_</code> + prefixed ones. Operating system vendors who integrate the lwres + library into their base distributions should rename the functions + in the library proper so that the renaming macros are not needed. + </p> +<p> + The library also provides a native API consisting of the functions + <code class="function">lwres_getaddrsbyname()</code> + and + <code class="function">lwres_getnamebyaddr()</code>. + These may be called by applications that require more detailed + control over the lookup process than the standard functions + provide. + </p> +<p> + In addition to these name service independent address lookup + functions, the library implements a new, experimental API + for looking up arbitrary DNS resource records, using the + <code class="function">lwres_getaddrsbyname()</code> + function. + </p> +<p> + Finally, there is a low-level API for converting lookup + requests and responses to and from raw lwres protocol packets. + This API can be used by clients requiring nonblocking operation, + and is also used when implementing the server side of the lwres + protocol, for example in the + <span><strong class="command">lwresd</strong></span> + resolver daemon. The use of this low-level API in clients + and servers is outlined in the following sections. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549474"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2> -<p> -When a client program wishes to make an lwres request using the -native low-level API, it typically performs the following -sequence of actions. -</p> -<p> -(1) Allocate or use an existing <span class="type">lwres_packet_t</span>, -called <code class="varname">pkt</code> below. -</p> -<p> -(2) Set <em class="structfield"><code>pkt.recvlength</code></em> to the maximum length we will accept. -This is done so the receiver of our packets knows how large our receive -buffer is. The "default" is a constant in -<code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>. -</p> -<p> -(3) Set <em class="structfield"><code>pkt.serial</code></em> -to a unique serial number. This value is echoed -back to the application by the remote server. -</p> -<p> -(4) Set <em class="structfield"><code>pkt.pktflags</code></em>. Usually this is set to 0. -</p> -<p> -(5) Set <em class="structfield"><code>pkt.result</code></em> to 0. -</p> -<p> -(6) Call <code class="function">lwres_*request_render()</code>, -or marshall in the data using the primitives -such as <code class="function">lwres_packet_render()</code> -and storing the packet data. -</p> -<p> -(7) Transmit the resulting buffer. -</p> -<p> -(8) Call <code class="function">lwres_*response_parse()</code> -to parse any packets received. -</p> -<p> -(9) Verify that the opcode and serial match a request, and process the -packet specific information contained in the body. -</p> +<a name="id2543425"></a><h2>CLIENT-SIDE LOW-LEVEL API CALL FLOW</h2> +<p> + When a client program wishes to make an lwres request using the + native low-level API, it typically performs the following + sequence of actions. + </p> +<p> + (1) Allocate or use an existing <span class="type">lwres_packet_t</span>, + called <code class="varname">pkt</code> below. + </p> +<p> + (2) Set <em class="structfield"><code>pkt.recvlength</code></em> to the maximum length + we will accept. + This is done so the receiver of our packets knows how large our receive + buffer is. The "default" is a constant in + <code class="filename">lwres.h</code>: <code class="constant">LWRES_RECVLENGTH = 4096</code>. + </p> +<p> + (3) Set <em class="structfield"><code>pkt.serial</code></em> + to a unique serial number. This value is echoed + back to the application by the remote server. + </p> +<p> + (4) Set <em class="structfield"><code>pkt.pktflags</code></em>. Usually this is set to + 0. + </p> +<p> + (5) Set <em class="structfield"><code>pkt.result</code></em> to 0. + </p> +<p> + (6) Call <code class="function">lwres_*request_render()</code>, + or marshall in the data using the primitives + such as <code class="function">lwres_packet_render()</code> + and storing the packet data. + </p> +<p> + (7) Transmit the resulting buffer. + </p> +<p> + (8) Call <code class="function">lwres_*response_parse()</code> + to parse any packets received. + </p> +<p> + (9) Verify that the opcode and serial match a request, and process the + packet specific information contained in the body. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549689"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2> -<p> -When implementing the server side of the lightweight resolver -protocol using the lwres library, a sequence of actions like the -following is typically involved in processing each request packet. -</p> -<p> -Note that the same <span class="type">lwres_packet_t</span> is used -in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls, -with only a few modifications made -to the packet header's contents between uses. This method is recommended -as it keeps the serial, opcode, and other fields correct. -</p> -<p> -(1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to -unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below) -as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>. -</p> -<p> -(2) Process the request in the data specific type. -</p> -<p> -(3) Set the <em class="structfield"><code>pkt.result</code></em>, -<em class="structfield"><code>pkt.recvlength</code></em> as above. All other fields can -be left untouched since they were filled in by the <code class="function">*_parse()</code> call -above. If using <code class="function">lwres_*response_render()</code>, -<em class="structfield"><code>pkt.pktflags</code></em> will be set up -properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be -set. -</p> -<p> -(4) Call the data specific rendering function, such as -<code class="function">lwres_gabnresponse_render()</code>. -</p> -<p> -(5) Send the resulting packet to the client. -</p> -<p> -</p> +<a name="id2543573"></a><h2>SERVER-SIDE LOW-LEVEL API CALL FLOW</h2> +<p> + When implementing the server side of the lightweight resolver + protocol using the lwres library, a sequence of actions like the + following is typically involved in processing each request packet. + </p> +<p> + Note that the same <span class="type">lwres_packet_t</span> is used + in both the <code class="function">_parse()</code> and <code class="function">_render()</code> calls, + with only a few modifications made + to the packet header's contents between uses. This method is + recommended + as it keeps the serial, opcode, and other fields correct. + </p> +<p> + (1) When a packet is received, call <code class="function">lwres_*request_parse()</code> to + unmarshall it. This returns a <span class="type">lwres_packet_t</span> (also called <code class="varname">pkt</code>, below) + as well as a data specific type, such as <span class="type">lwres_gabnrequest_t</span>. + </p> +<p> + (2) Process the request in the data specific type. + </p> +<p> + (3) Set the <em class="structfield"><code>pkt.result</code></em>, + <em class="structfield"><code>pkt.recvlength</code></em> as above. All other fields + can + be left untouched since they were filled in by the <code class="function">*_parse()</code> call + above. If using <code class="function">lwres_*response_render()</code>, + <em class="structfield"><code>pkt.pktflags</code></em> will be set up + properly. Otherwise, the <code class="constant">LWRES_LWPACKETFLAG_RESPONSE</code> bit should be + set. + </p> +<p> + (4) Call the data specific rendering function, such as + <code class="function">lwres_gabnresponse_render()</code>. + </p> +<p> + (5) Send the resulting packet to the client. + </p> +<p></p> </div> <div class="refsect1" lang="en"> -<a name="id2549774"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>, +<a name="id2543656"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_noop</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_noop</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_gnba</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_gnba</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_context</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_context</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_config</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_config</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>, + <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>, -<span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>. + <span class="citerefentry"><span class="refentrytitle">lwresd</span>(8)</span>. -</p> + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_buffer.3 b/contrib/bind9/lib/lwres/man/lwres_buffer.3 index 62312379c1b4..4bebafa960aa 100644 --- a/contrib/bind9/lib/lwres/man/lwres_buffer.3 +++ b/contrib/bind9/lib/lwres/man/lwres_buffer.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_buffer.3,v 1.12.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_buffer.3,v 1.15.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_buffer .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,37 +36,37 @@ lwres_buffer_init, lwres_buffer_invalidate, lwres_buffer_add, lwres_buffer_subtr #include <lwres/lwbuffer.h> .fi .HP 23 -.BI "void lwres_buffer_init(lwres_buffer_t\ *b, void\ *base, unsigned\ int\ length);" +.BI "void lwres_buffer_init(lwres_buffer_t\ *" "b" ", void\ *" "base" ", unsigned\ int\ " "length" ");" .HP 29 -.BI "void lwres_buffer_invalidate(lwres_buffer_t\ *b);" +.BI "void lwres_buffer_invalidate(lwres_buffer_t\ *" "b" ");" .HP 22 -.BI "void lwres_buffer_add(lwres_buffer_t\ *b, unsigned\ int\ n);" +.BI "void lwres_buffer_add(lwres_buffer_t\ *" "b" ", unsigned\ int\ " "n" ");" .HP 27 -.BI "void lwres_buffer_subtract(lwres_buffer_t\ *b, unsigned\ int\ n);" +.BI "void lwres_buffer_subtract(lwres_buffer_t\ *" "b" ", unsigned\ int\ " "n" ");" .HP 24 -.BI "void lwres_buffer_clear(lwres_buffer_t\ *b);" +.BI "void lwres_buffer_clear(lwres_buffer_t\ *" "b" ");" .HP 24 -.BI "void lwres_buffer_first(lwres_buffer_t\ *b);" +.BI "void lwres_buffer_first(lwres_buffer_t\ *" "b" ");" .HP 26 -.BI "void lwres_buffer_forward(lwres_buffer_t\ *b, unsigned\ int\ n);" +.BI "void lwres_buffer_forward(lwres_buffer_t\ *" "b" ", unsigned\ int\ " "n" ");" .HP 23 -.BI "void lwres_buffer_back(lwres_buffer_t\ *b, unsigned\ int\ n);" +.BI "void lwres_buffer_back(lwres_buffer_t\ *" "b" ", unsigned\ int\ " "n" ");" .HP 36 -.BI "lwres_uint8_t lwres_buffer_getuint8(lwres_buffer_t\ *b);" +.BI "lwres_uint8_t lwres_buffer_getuint8(lwres_buffer_t\ *" "b" ");" .HP 27 -.BI "void lwres_buffer_putuint8(lwres_buffer_t\ *b, lwres_uint8_t\ val);" +.BI "void lwres_buffer_putuint8(lwres_buffer_t\ *" "b" ", lwres_uint8_t\ " "val" ");" .HP 38 -.BI "lwres_uint16_t lwres_buffer_getuint16(lwres_buffer_t\ *b);" +.BI "lwres_uint16_t lwres_buffer_getuint16(lwres_buffer_t\ *" "b" ");" .HP 28 -.BI "void lwres_buffer_putuint16(lwres_buffer_t\ *b, lwres_uint16_t\ val);" +.BI "void lwres_buffer_putuint16(lwres_buffer_t\ *" "b" ", lwres_uint16_t\ " "val" ");" .HP 38 -.BI "lwres_uint32_t lwres_buffer_getuint32(lwres_buffer_t\ *b);" +.BI "lwres_uint32_t lwres_buffer_getuint32(lwres_buffer_t\ *" "b" ");" .HP 28 -.BI "void lwres_buffer_putuint32(lwres_buffer_t\ *b, lwres_uint32_t\ val);" +.BI "void lwres_buffer_putuint32(lwres_buffer_t\ *" "b" ", lwres_uint32_t\ " "val" ");" .HP 25 -.BI "void lwres_buffer_putmem(lwres_buffer_t\ *b, const\ unsigned\ char\ *base, unsigned\ int\ length);" +.BI "void lwres_buffer_putmem(lwres_buffer_t\ *" "b" ", const\ unsigned\ char\ *" "base" ", unsigned\ int\ " "length" ");" .HP 25 -.BI "void lwres_buffer_getmem(lwres_buffer_t\ *b, unsigned\ char\ *base, unsigned\ int\ length);" +.BI "void lwres_buffer_getmem(lwres_buffer_t\ *" "b" ", unsigned\ char\ *" "base" ", unsigned\ int\ " "length" ");" .SH "DESCRIPTION" .PP These functions provide bounds checked access to a region of memory where data is being read or written. They are based on, and similar to, the @@ -92,8 +92,7 @@ The \fIactive region\fR is an (optional) subregion of the remaining region. It extends from the current offset to an offset in the remaining region. Initially, the active region is empty. If the current offset advances beyond the chosen offset, the active region will also be empty. .PP -.sp -.RS 3n +.RS 4 .nf /\-\-\-\-\-\-\-\-\-\-\-\-entire length\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\\\\ /\-\-\-\-\- used region \-\-\-\-\-\\\\/\-\- available \-\-\\\\ @@ -101,11 +100,23 @@ is an (optional) subregion of the remaining region. It extends from the current | consumed | remaining | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ a b c d e +.fi +.RE +.sp +.PP +.RS 4 +.nf a == base of buffer. b == current pointer. Can be anywhere between a and d. c == active pointer. Meaningful between b and d. d == used pointer. e == length of buffer. +.fi +.RE +.sp +.PP +.RS 4 +.nf a\-e == entire length of buffer. a\-d == used region. a\-b == consumed region. @@ -146,8 +157,7 @@ used. .PP A buffer is re\-initialised by \fBlwres_buffer_clear()\fR. The function sets -used -, +used, current and active @@ -217,4 +227,7 @@ bytes of memory from to \fIbase\fR. .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_buffer.docbook b/contrib/bind9/lib/lwres/man/lwres_buffer.docbook index c70aee508e77..ab0c5608d86a 100644 --- a/contrib/bind9/lib/lwres/man/lwres_buffer.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_buffer.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,23 +18,23 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_buffer.docbook,v 1.3.206.3 2005/05/12 21:36:11 sra Exp $ --> - +<!-- $Id: lwres_buffer.docbook,v 1.4.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_buffer</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_buffer</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -44,350 +44,351 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_buffer_init</refname> -<refname>lwres_buffer_invalidate</refname> -<refname>lwres_buffer_add</refname> -<refname>lwres_buffer_subtract</refname> -<refname>lwres_buffer_clear</refname> -<refname>lwres_buffer_first</refname> -<refname>lwres_buffer_forward</refname> -<refname>lwres_buffer_back</refname> -<refname>lwres_buffer_getuint8</refname> -<refname>lwres_buffer_putuint8</refname> -<refname>lwres_buffer_getuint16</refname> -<refname>lwres_buffer_putuint16</refname> -<refname>lwres_buffer_getuint32</refname> -<refname>lwres_buffer_putuint32</refname> -<refname>lwres_buffer_putmem</refname> -<refname>lwres_buffer_getmem</refname> -<refpurpose>lightweight resolver buffer management</refpurpose> -</refnamediv> + <refnamediv> + <refname>lwres_buffer_init</refname> + <refname>lwres_buffer_invalidate</refname> + <refname>lwres_buffer_add</refname> + <refname>lwres_buffer_subtract</refname> + <refname>lwres_buffer_clear</refname> + <refname>lwres_buffer_first</refname> + <refname>lwres_buffer_forward</refname> + <refname>lwres_buffer_back</refname> + <refname>lwres_buffer_getuint8</refname> + <refname>lwres_buffer_putuint8</refname> + <refname>lwres_buffer_getuint16</refname> + <refname>lwres_buffer_putuint16</refname> + <refname>lwres_buffer_getuint32</refname> + <refname>lwres_buffer_putuint32</refname> + <refname>lwres_buffer_putmem</refname> + <refname>lwres_buffer_getmem</refname> + <refpurpose>lightweight resolver buffer management</refpurpose> + </refnamediv> -<refsynopsisdiv> + <refsynopsisdiv> -<funcsynopsis> + <funcsynopsis> <funcsynopsisinfo> #include <lwres/lwbuffer.h> </funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_init</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>void *base</paramdef> -<paramdef>unsigned int length</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>void *<parameter>base</parameter></paramdef> + <paramdef>unsigned int <parameter>length</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_invalidate</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_add</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>unsigned int n</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned int <parameter>n</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_subtract</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>unsigned int n</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned int <parameter>n</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_clear</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_first</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_forward</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>unsigned int n</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned int <parameter>n</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_back</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>unsigned int n</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned int <parameter>n</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_uint8_t <function>lwres_buffer_getuint8</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_putuint8</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_uint8_t val</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_uint8_t <parameter>val</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_uint16_t <function>lwres_buffer_getuint16</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_putuint16</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_uint16_t val</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_uint16_t <parameter>val</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_uint32_t <function>lwres_buffer_getuint32</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_putuint32</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_uint32_t val</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_uint32_t <parameter>val</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_putmem</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>const unsigned char *base</paramdef> -<paramdef>unsigned int length</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>const unsigned char *<parameter>base</parameter></paramdef> + <paramdef>unsigned int <parameter>length</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_buffer_getmem</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>unsigned char *base</paramdef> -<paramdef>unsigned int length</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>unsigned char *<parameter>base</parameter></paramdef> + <paramdef>unsigned int <parameter>length</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> + </refsynopsisdiv> -<refsect1> + <refsect1> -<title>DESCRIPTION</title> -<para> -These functions provide bounds checked access to a region of memory -where data is being read or written. -They are based on, and similar to, the -<literal>isc_buffer_</literal> -functions in the ISC library. -</para> -<para> -A buffer is a region of memory, together with a set of related -subregions. -The <emphasis>used region</emphasis> and the -<emphasis>available</emphasis> region are disjoint, and -their union is the buffer's region. -The used region extends from the beginning of the buffer region to the -last used byte. -The available region extends from one byte greater than the last used -byte to the end of the buffer's region. -The size of the used region can be changed using various -buffer commands. -Initially, the used region is empty. -</para> -<para> -The used region is further subdivided into two disjoint regions: the -<emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>. -The union of these two regions is the used region. -The consumed region extends from the beginning of the used region to -the byte before the <emphasis>current</emphasis> offset (if any). -The <emphasis>remaining</emphasis> region the current pointer to the end of the used -region. -The size of the consumed region can be changed using various -buffer commands. -Initially, the consumed region is empty. -</para> -<para> -The <emphasis>active region</emphasis> is an (optional) subregion of the remaining -region. -It extends from the current offset to an offset in the -remaining region. -Initially, the active region is empty. -If the current offset advances beyond the chosen offset, -the active region will also be empty. -</para> -<para> -<programlisting> - + <title>DESCRIPTION</title> + <para> + These functions provide bounds checked access to a region of memory + where data is being read or written. + They are based on, and similar to, the + <literal>isc_buffer_</literal> + functions in the ISC library. + </para> + <para> + A buffer is a region of memory, together with a set of related + subregions. + The <emphasis>used region</emphasis> and the + <emphasis>available</emphasis> region are disjoint, and + their union is the buffer's region. + The used region extends from the beginning of the buffer region to the + last used byte. + The available region extends from one byte greater than the last used + byte to the end of the buffer's region. + The size of the used region can be changed using various + buffer commands. + Initially, the used region is empty. + </para> + <para> + The used region is further subdivided into two disjoint regions: the + <emphasis>consumed region</emphasis> and the <emphasis>remaining region</emphasis>. + The union of these two regions is the used region. + The consumed region extends from the beginning of the used region to + the byte before the <emphasis>current</emphasis> offset (if any). + The <emphasis>remaining</emphasis> region the current pointer to the end + of the used + region. + The size of the consumed region can be changed using various + buffer commands. + Initially, the consumed region is empty. + </para> + <para> + The <emphasis>active region</emphasis> is an (optional) subregion of the + remaining + region. + It extends from the current offset to an offset in the + remaining region. + Initially, the active region is empty. + If the current offset advances beyond the chosen offset, + the active region will also be empty. + </para> + <para><programlisting> /------------entire length---------------\\ /----- used region -----\\/-- available --\\ +----------------------------------------+ | consumed | remaining | | +----------------------------------------+ a b c d e - + </programlisting> + </para> + <para><programlisting> a == base of buffer. b == current pointer. Can be anywhere between a and d. c == active pointer. Meaningful between b and d. d == used pointer. e == length of buffer. - + </programlisting> + </para> + <para><programlisting> a-e == entire length of buffer. a-d == used region. a-b == consumed region. b-d == remaining region. b-c == optional active region. </programlisting> -</para> -<para> -<function>lwres_buffer_init()</function> -initializes the -<type>lwres_buffer_t</type> -<parameter>*b</parameter> -and assocates it with the memory region of size -<parameter>length</parameter> -bytes starting at location -<parameter>base.</parameter> -</para> -<para> -<function>lwres_buffer_invalidate()</function> -marks the buffer -<parameter>*b</parameter> -as invalid. Invalidating a buffer after use is not required, -but makes it possible to catch its possible accidental use. -</para> -<para> -The functions -<function>lwres_buffer_add()</function> -and -<function>lwres_buffer_subtract()</function> -respectively increase and decrease the used space in -buffer -<parameter>*b</parameter> -by -<parameter>n</parameter> -bytes. -<function>lwres_buffer_add()</function> -checks for buffer overflow and -<function>lwres_buffer_subtract()</function> -checks for underflow. -These functions do not allocate or deallocate memory. -They just change the value of -<structfield>used</structfield>. -</para> -<para> -A buffer is re-initialised by -<function>lwres_buffer_clear()</function>. -The function sets -<structfield>used</structfield> , -<structfield>current</structfield> -and -<structfield>active</structfield> -to zero. -</para> -<para> -<function>lwres_buffer_first</function> -makes the consumed region of buffer -<parameter>*p</parameter> -empty by setting -<structfield>current</structfield> -to zero (the start of the buffer). -</para> -<para> -<function>lwres_buffer_forward()</function> -increases the consumed region of buffer -<parameter>*b</parameter> -by -<parameter>n</parameter> -bytes, checking for overflow. -Similarly, -<function>lwres_buffer_back()</function> -decreases buffer -<parameter>b</parameter>'s -consumed region by -<parameter>n</parameter> -bytes and checks for underflow. -</para> -<para> -<function>lwres_buffer_getuint8()</function> -reads an unsigned 8-bit integer from -<parameter>*b</parameter> -and returns it. -<function>lwres_buffer_putuint8()</function> -writes the unsigned 8-bit integer -<parameter>val</parameter> -to buffer -<parameter>*b</parameter>. -</para> -<para> -<function>lwres_buffer_getuint16()</function> -and -<function>lwres_buffer_getuint32()</function> -are identical to -<function>lwres_buffer_putuint8()</function> -except that they respectively read an unsigned 16-bit or 32-bit integer -in network byte order from -<parameter>b</parameter>. -Similarly, -<function>lwres_buffer_putuint16()</function> -and -<function>lwres_buffer_putuint32()</function> -writes the unsigned 16-bit or 32-bit integer -<parameter>val</parameter> -to buffer -<parameter>b</parameter>, -in network byte order. -</para> -<para> -Arbitrary amounts of data are read or written from a lightweight -resolver buffer with -<function>lwres_buffer_getmem()</function> -and -<function>lwres_buffer_putmem()</function> -respectively. -<function>lwres_buffer_putmem()</function> -copies -<parameter>length</parameter> -bytes of memory at -<parameter>base</parameter> -to -<parameter>b</parameter>. -Conversely, -<function>lwres_buffer_getmem()</function> -copies -<parameter>length</parameter> -bytes of memory from -<parameter>b</parameter> -to -<parameter>base</parameter>. -</para> -</refsect1> -</refentry> + </para> + <para><function>lwres_buffer_init()</function> + initializes the + <type>lwres_buffer_t</type> + <parameter>*b</parameter> + and assocates it with the memory region of size + <parameter>length</parameter> + bytes starting at location + <parameter>base.</parameter> + </para> + <para><function>lwres_buffer_invalidate()</function> + marks the buffer <parameter>*b</parameter> + as invalid. Invalidating a buffer after use is not required, + but makes it possible to catch its possible accidental use. + </para> + <para> + The functions + <function>lwres_buffer_add()</function> + and + <function>lwres_buffer_subtract()</function> + respectively increase and decrease the used space in + buffer + <parameter>*b</parameter> + by + <parameter>n</parameter> + bytes. + <function>lwres_buffer_add()</function> + checks for buffer overflow and + <function>lwres_buffer_subtract()</function> + checks for underflow. + These functions do not allocate or deallocate memory. + They just change the value of + <structfield>used</structfield>. + </para> + <para> + A buffer is re-initialised by + <function>lwres_buffer_clear()</function>. + The function sets + <structfield>used</structfield>, + <structfield>current</structfield> + and + <structfield>active</structfield> + to zero. + </para> + <para><function>lwres_buffer_first</function> + makes the consumed region of buffer + <parameter>*p</parameter> + empty by setting + <structfield>current</structfield> + to zero (the start of the buffer). + </para> + <para><function>lwres_buffer_forward()</function> + increases the consumed region of buffer + <parameter>*b</parameter> + by + <parameter>n</parameter> + bytes, checking for overflow. + Similarly, + <function>lwres_buffer_back()</function> + decreases buffer + <parameter>b</parameter>'s + consumed region by + <parameter>n</parameter> + bytes and checks for underflow. + </para> + <para><function>lwres_buffer_getuint8()</function> + reads an unsigned 8-bit integer from + <parameter>*b</parameter> + and returns it. + <function>lwres_buffer_putuint8()</function> + writes the unsigned 8-bit integer + <parameter>val</parameter> + to buffer + <parameter>*b</parameter>. + </para> + <para><function>lwres_buffer_getuint16()</function> + and + <function>lwres_buffer_getuint32()</function> + are identical to + <function>lwres_buffer_putuint8()</function> + except that they respectively read an unsigned 16-bit or 32-bit integer + in network byte order from + <parameter>b</parameter>. + Similarly, + <function>lwres_buffer_putuint16()</function> + and + <function>lwres_buffer_putuint32()</function> + writes the unsigned 16-bit or 32-bit integer + <parameter>val</parameter> + to buffer + <parameter>b</parameter>, + in network byte order. + </para> + <para> + Arbitrary amounts of data are read or written from a lightweight + resolver buffer with + <function>lwres_buffer_getmem()</function> + and + <function>lwres_buffer_putmem()</function> + respectively. + <function>lwres_buffer_putmem()</function> + copies + <parameter>length</parameter> + bytes of memory at + <parameter>base</parameter> + to + <parameter>b</parameter>. + Conversely, + <function>lwres_buffer_getmem()</function> + copies + <parameter>length</parameter> + bytes of memory from + <parameter>b</parameter> + to + <parameter>base</parameter>. + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_buffer.html b/contrib/bind9/lib/lwres/man/lwres_buffer.html index 9443fbda1e4c..ed3e427be4ff 100644 --- a/contrib/bind9/lib/lwres/man/lwres_buffer.html +++ b/contrib/bind9/lib/lwres/man/lwres_buffer.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_buffer.html,v 1.4.2.1.4.10 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_buffer.html,v 1.5.18.16 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_buffer</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_buffer_init, lwres_buffer_invalidate, lwres_buffer_add, lwres_buffer_subtract, lwres_buffer_clear, lwres_buffer_first, lwres_buffer_forward, lwres_buffer_back, lwres_buffer_getuint8, lwres_buffer_putuint8, lwres_buffer_getuint16, lwres_buffer_putuint16, lwres_buffer_getuint32, lwres_buffer_putuint32, lwres_buffer_putmem, lwres_buffer_getmem — lightweight resolver buffer management</p> @@ -38,60 +38,45 @@ <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_init</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>void * </td> +<td> +<var class="pdparam">base</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>unsigned int </td> <td> -<code>)</code>;</td> +<var class="pdparam">length</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_invalidate</b>(</code></td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">b</var><code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_add</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>unsigned int </td> <td> -<code>)</code>;</td> +<var class="pdparam">n</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -99,71 +84,47 @@ void <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_subtract</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>unsigned int </td> <td> -<code>)</code>;</td> +<var class="pdparam">n</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_clear</b>(</code></td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> -</tr> -</table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<var class="pdparam">b</var><code>)</code>;</td> +</tr></table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_first</b>(</code></td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">b</var><code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_forward</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>unsigned int </td> <td> -<code>)</code>;</td> +<var class="pdparam">n</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -171,127 +132,87 @@ void <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_back</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>unsigned int </td> <td> -<code>)</code>;</td> +<var class="pdparam">n</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> lwres_uint8_t <b class="fsfunc">lwres_buffer_getuint8</b>(</code></td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">b</var><code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_putuint8</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_uint8_t </td> <td> -<code>)</code>;</td> +<var class="pdparam">val</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> lwres_uint16_t <b class="fsfunc">lwres_buffer_getuint16</b>(</code></td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">b</var><code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_putuint16</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_uint16_t </td> <td> -<code>)</code>;</td> +<var class="pdparam">val</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> lwres_uint32_t <b class="fsfunc">lwres_buffer_getuint32</b>(</code></td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">b</var><code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_putuint32</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_uint32_t </td> <td> -<code>)</code>;</td> +<var class="pdparam">val</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -299,24 +220,21 @@ void <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_putmem</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>const unsigned char * </td> +<td> +<var class="pdparam">base</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>unsigned int </td> <td> -<code>)</code>;</td> +<var class="pdparam">length</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> @@ -324,89 +242,91 @@ void <td><code class="funcdef"> void <b class="fsfunc">lwres_buffer_getmem</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>unsigned char * </td> +<td> +<var class="pdparam">base</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>unsigned int </td> <td> -<code>)</code>;</td> +<var class="pdparam">length</var><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549674"></a><h2>DESCRIPTION</h2> +<a name="id2543892"></a><h2>DESCRIPTION</h2> <p> -These functions provide bounds checked access to a region of memory -where data is being read or written. -They are based on, and similar to, the -<code class="literal">isc_buffer_</code> -functions in the ISC library. -</p> + These functions provide bounds checked access to a region of memory + where data is being read or written. + They are based on, and similar to, the + <code class="literal">isc_buffer_</code> + functions in the ISC library. + </p> <p> -A buffer is a region of memory, together with a set of related -subregions. -The <span class="emphasis"><em>used region</em></span> and the -<span class="emphasis"><em>available</em></span> region are disjoint, and -their union is the buffer's region. -The used region extends from the beginning of the buffer region to the -last used byte. -The available region extends from one byte greater than the last used -byte to the end of the buffer's region. -The size of the used region can be changed using various -buffer commands. -Initially, the used region is empty. -</p> + A buffer is a region of memory, together with a set of related + subregions. + The <span class="emphasis"><em>used region</em></span> and the + <span class="emphasis"><em>available</em></span> region are disjoint, and + their union is the buffer's region. + The used region extends from the beginning of the buffer region to the + last used byte. + The available region extends from one byte greater than the last used + byte to the end of the buffer's region. + The size of the used region can be changed using various + buffer commands. + Initially, the used region is empty. + </p> <p> -The used region is further subdivided into two disjoint regions: the -<span class="emphasis"><em>consumed region</em></span> and the <span class="emphasis"><em>remaining region</em></span>. -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 <span class="emphasis"><em>current</em></span> offset (if any). -The <span class="emphasis"><em>remaining</em></span> region the current pointer to the end of the used -region. -The size of the consumed region can be changed using various -buffer commands. -Initially, the consumed region is empty. -</p> + The used region is further subdivided into two disjoint regions: the + <span class="emphasis"><em>consumed region</em></span> and the <span class="emphasis"><em>remaining region</em></span>. + 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 <span class="emphasis"><em>current</em></span> offset (if any). + The <span class="emphasis"><em>remaining</em></span> region the current pointer to the end + of the used + region. + The size of the consumed region can be changed using various + buffer commands. + Initially, the consumed region is empty. + </p> <p> -The <span class="emphasis"><em>active region</em></span> is an (optional) subregion of the remaining -region. -It extends from the current offset to an offset in the -remaining region. -Initially, the active region is empty. -If the current offset advances beyond the chosen offset, -the active region will also be empty. -</p> -<p> -</p> + The <span class="emphasis"><em>active region</em></span> is an (optional) subregion of the + remaining + region. + It extends from the current offset to an offset in the + remaining region. + Initially, the active region is empty. + If the current offset advances beyond the chosen offset, + the active region will also be empty. + </p> <pre class="programlisting"> - /------------entire length---------------\\ /----- used region -----\\/-- available --\\ +----------------------------------------+ | consumed | remaining | | +----------------------------------------+ a b c d e - + </pre> +<p> + </p> +<pre class="programlisting"> a == base of buffer. b == current pointer. Can be anywhere between a and d. c == active pointer. Meaningful between b and d. d == used pointer. e == length of buffer. - + </pre> +<p> + </p> +<pre class="programlisting"> a-e == entire length of buffer. a-d == used region. a-b == consumed region. @@ -414,129 +334,122 @@ the active region will also be empty. b-c == optional active region. </pre> <p> -</p> -<p> -<code class="function">lwres_buffer_init()</code> -initializes the -<span class="type">lwres_buffer_t</span> -<em class="parameter"><code>*b</code></em> -and assocates it with the memory region of size -<em class="parameter"><code>length</code></em> -bytes starting at location -<em class="parameter"><code>base.</code></em> -</p> -<p> -<code class="function">lwres_buffer_invalidate()</code> -marks the buffer -<em class="parameter"><code>*b</code></em> -as invalid. Invalidating a buffer after use is not required, -but makes it possible to catch its possible accidental use. -</p> -<p> -The functions -<code class="function">lwres_buffer_add()</code> -and -<code class="function">lwres_buffer_subtract()</code> -respectively increase and decrease the used space in -buffer -<em class="parameter"><code>*b</code></em> -by -<em class="parameter"><code>n</code></em> -bytes. -<code class="function">lwres_buffer_add()</code> -checks for buffer overflow and -<code class="function">lwres_buffer_subtract()</code> -checks for underflow. -These functions do not allocate or deallocate memory. -They just change the value of -<em class="structfield"><code>used</code></em>. -</p> -<p> -A buffer is re-initialised by -<code class="function">lwres_buffer_clear()</code>. -The function sets -<em class="structfield"><code>used</code></em> , -<em class="structfield"><code>current</code></em> -and -<em class="structfield"><code>active</code></em> -to zero. -</p> -<p> -<code class="function">lwres_buffer_first</code> -makes the consumed region of buffer -<em class="parameter"><code>*p</code></em> -empty by setting -<em class="structfield"><code>current</code></em> -to zero (the start of the buffer). -</p> -<p> -<code class="function">lwres_buffer_forward()</code> -increases the consumed region of buffer -<em class="parameter"><code>*b</code></em> -by -<em class="parameter"><code>n</code></em> -bytes, checking for overflow. -Similarly, -<code class="function">lwres_buffer_back()</code> -decreases buffer -<em class="parameter"><code>b</code></em>'s -consumed region by -<em class="parameter"><code>n</code></em> -bytes and checks for underflow. -</p> + </p> +<p><code class="function">lwres_buffer_init()</code> + initializes the + <span class="type">lwres_buffer_t</span> + <em class="parameter"><code>*b</code></em> + and assocates it with the memory region of size + <em class="parameter"><code>length</code></em> + bytes starting at location + <em class="parameter"><code>base.</code></em> + </p> +<p><code class="function">lwres_buffer_invalidate()</code> + marks the buffer <em class="parameter"><code>*b</code></em> + as invalid. Invalidating a buffer after use is not required, + but makes it possible to catch its possible accidental use. + </p> <p> -<code class="function">lwres_buffer_getuint8()</code> -reads an unsigned 8-bit integer from -<em class="parameter"><code>*b</code></em> -and returns it. -<code class="function">lwres_buffer_putuint8()</code> -writes the unsigned 8-bit integer -<em class="parameter"><code>val</code></em> -to buffer -<em class="parameter"><code>*b</code></em>. -</p> + The functions + <code class="function">lwres_buffer_add()</code> + and + <code class="function">lwres_buffer_subtract()</code> + respectively increase and decrease the used space in + buffer + <em class="parameter"><code>*b</code></em> + by + <em class="parameter"><code>n</code></em> + bytes. + <code class="function">lwres_buffer_add()</code> + checks for buffer overflow and + <code class="function">lwres_buffer_subtract()</code> + checks for underflow. + These functions do not allocate or deallocate memory. + They just change the value of + <em class="structfield"><code>used</code></em>. + </p> <p> -<code class="function">lwres_buffer_getuint16()</code> -and -<code class="function">lwres_buffer_getuint32()</code> -are identical to -<code class="function">lwres_buffer_putuint8()</code> -except that they respectively read an unsigned 16-bit or 32-bit integer -in network byte order from -<em class="parameter"><code>b</code></em>. -Similarly, -<code class="function">lwres_buffer_putuint16()</code> -and -<code class="function">lwres_buffer_putuint32()</code> -writes the unsigned 16-bit or 32-bit integer -<em class="parameter"><code>val</code></em> -to buffer -<em class="parameter"><code>b</code></em>, -in network byte order. -</p> + A buffer is re-initialised by + <code class="function">lwres_buffer_clear()</code>. + The function sets + <em class="structfield"><code>used</code></em>, + <em class="structfield"><code>current</code></em> + and + <em class="structfield"><code>active</code></em> + to zero. + </p> +<p><code class="function">lwres_buffer_first</code> + makes the consumed region of buffer + <em class="parameter"><code>*p</code></em> + empty by setting + <em class="structfield"><code>current</code></em> + to zero (the start of the buffer). + </p> +<p><code class="function">lwres_buffer_forward()</code> + increases the consumed region of buffer + <em class="parameter"><code>*b</code></em> + by + <em class="parameter"><code>n</code></em> + bytes, checking for overflow. + Similarly, + <code class="function">lwres_buffer_back()</code> + decreases buffer + <em class="parameter"><code>b</code></em>'s + consumed region by + <em class="parameter"><code>n</code></em> + bytes and checks for underflow. + </p> +<p><code class="function">lwres_buffer_getuint8()</code> + reads an unsigned 8-bit integer from + <em class="parameter"><code>*b</code></em> + and returns it. + <code class="function">lwres_buffer_putuint8()</code> + writes the unsigned 8-bit integer + <em class="parameter"><code>val</code></em> + to buffer + <em class="parameter"><code>*b</code></em>. + </p> +<p><code class="function">lwres_buffer_getuint16()</code> + and + <code class="function">lwres_buffer_getuint32()</code> + are identical to + <code class="function">lwres_buffer_putuint8()</code> + except that they respectively read an unsigned 16-bit or 32-bit integer + in network byte order from + <em class="parameter"><code>b</code></em>. + Similarly, + <code class="function">lwres_buffer_putuint16()</code> + and + <code class="function">lwres_buffer_putuint32()</code> + writes the unsigned 16-bit or 32-bit integer + <em class="parameter"><code>val</code></em> + to buffer + <em class="parameter"><code>b</code></em>, + in network byte order. + </p> <p> -Arbitrary amounts of data are read or written from a lightweight -resolver buffer with -<code class="function">lwres_buffer_getmem()</code> -and -<code class="function">lwres_buffer_putmem()</code> -respectively. -<code class="function">lwres_buffer_putmem()</code> -copies -<em class="parameter"><code>length</code></em> -bytes of memory at -<em class="parameter"><code>base</code></em> -to -<em class="parameter"><code>b</code></em>. -Conversely, -<code class="function">lwres_buffer_getmem()</code> -copies -<em class="parameter"><code>length</code></em> -bytes of memory from -<em class="parameter"><code>b</code></em> -to -<em class="parameter"><code>base</code></em>. -</p> + Arbitrary amounts of data are read or written from a lightweight + resolver buffer with + <code class="function">lwres_buffer_getmem()</code> + and + <code class="function">lwres_buffer_putmem()</code> + respectively. + <code class="function">lwres_buffer_putmem()</code> + copies + <em class="parameter"><code>length</code></em> + bytes of memory at + <em class="parameter"><code>base</code></em> + to + <em class="parameter"><code>b</code></em>. + Conversely, + <code class="function">lwres_buffer_getmem()</code> + copies + <em class="parameter"><code>length</code></em> + bytes of memory from + <em class="parameter"><code>b</code></em> + to + <em class="parameter"><code>base</code></em>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_config.3 b/contrib/bind9/lib/lwres/man/lwres_config.3 index 0a239235144b..5a4123d10dab 100644 --- a/contrib/bind9/lib/lwres/man/lwres_config.3 +++ b/contrib/bind9/lib/lwres/man/lwres_config.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_config.3,v 1.12.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_config.3,v 1.15.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_config .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,15 +36,15 @@ lwres_conf_init, lwres_conf_clear, lwres_conf_parse, lwres_conf_print, lwres_con #include <lwres/lwres.h> .fi .HP 21 -.BI "void lwres_conf_init(lwres_context_t\ *ctx);" +.BI "void lwres_conf_init(lwres_context_t\ *" "ctx" ");" .HP 22 -.BI "void lwres_conf_clear(lwres_context_t\ *ctx);" +.BI "void lwres_conf_clear(lwres_context_t\ *" "ctx" ");" .HP 32 -.BI "lwres_result_t lwres_conf_parse(lwres_context_t\ *ctx, const\ char\ *filename);" +.BI "lwres_result_t lwres_conf_parse(lwres_context_t\ *" "ctx" ", const\ char\ *" "filename" ");" .HP 32 -.BI "lwres_result_t lwres_conf_print(lwres_context_t\ *ctx, FILE\ *fp);" +.BI "lwres_result_t lwres_conf_print(lwres_context_t\ *" "ctx" ", FILE\ *" "fp" ");" .HP 30 -.BI "lwres_conf_t * lwres_conf_get(lwres_context_t\ *ctx);" +.BI "lwres_conf_t * lwres_conf_get(lwres_context_t\ *" "ctx" ");" .SH "DESCRIPTION" .PP \fBlwres_conf_init()\fR @@ -100,4 +100,7 @@ unless an error occurred when converting the network addresses to a numeric host .PP \fI/etc/resolv.conf\fR .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_config.docbook b/contrib/bind9/lib/lwres/man/lwres_config.docbook index 03426beb3274..13113d3fc447 100644 --- a/contrib/bind9/lib/lwres/man/lwres_config.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_config.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_config.docbook,v 1.2.206.3 2005/05/12 21:36:12 sra Exp $ --> - +<!-- $Id: lwres_config.docbook,v 1.3.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> + <refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_config</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_config</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,131 +45,129 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_conf_init</refname> -<refname>lwres_conf_clear</refname> -<refname>lwres_conf_parse</refname> -<refname>lwres_conf_print</refname> -<refname>lwres_conf_get</refname> -<refpurpose>lightweight resolver configuration</refpurpose> -</refnamediv> + <refnamediv> + <refname>lwres_conf_init</refname> + <refname>lwres_conf_clear</refname> + <refname>lwres_conf_parse</refname> + <refname>lwres_conf_print</refname> + <refname>lwres_conf_get</refname> + <refpurpose>lightweight resolver configuration</refpurpose> + </refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_conf_init</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_conf_clear</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_conf_parse</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>const char *filename</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>const char *<parameter>filename</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_conf_print</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>FILE *fp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>FILE *<parameter>fp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_conf_t * <function>lwres_conf_get</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> + </refsynopsisdiv> + + <refsect1> + <title>DESCRIPTION</title> + + <para><function>lwres_conf_init()</function> + creates an empty + <type>lwres_conf_t</type> + structure for lightweight resolver context + <parameter>ctx</parameter>. + </para> + + <para><function>lwres_conf_clear()</function> + frees up all the internal memory used by + that + <type>lwres_conf_t</type> + structure in resolver context + <parameter>ctx</parameter>. + </para> -<refsect1> -<title>DESCRIPTION</title> -<para> -<function>lwres_conf_init()</function> -creates an empty -<type>lwres_conf_t</type> -structure for lightweight resolver context -<parameter>ctx</parameter>. -</para> -<para> -<function>lwres_conf_clear()</function> -frees up all the internal memory used by -that -<type>lwres_conf_t</type> -structure in resolver context -<parameter>ctx</parameter>. -</para> -<para> -<function>lwres_conf_parse()</function> -opens the file -<parameter>filename</parameter> -and parses it to initialise the resolver context -<parameter>ctx</parameter>'s -<type>lwres_conf_t</type> -structure. -</para> -<para> -<function>lwres_conf_print()</function> -prints the -<type>lwres_conf_t</type> -structure for resolver context -<parameter>ctx</parameter> -to the -<type>FILE</type> -<parameter>fp</parameter>. -</para> -</refsect1> -<refsect1> + <para><function>lwres_conf_parse()</function> + opens the file + <parameter>filename</parameter> + and parses it to initialise the resolver context + <parameter>ctx</parameter>'s + <type>lwres_conf_t</type> + structure. + </para> -<title>RETURN VALUES</title> -<para> -<function>lwres_conf_parse()</function> -returns -<errorcode>LWRES_R_SUCCESS</errorcode> -if it successfully read and parsed -<parameter>filename</parameter>. -It returns -<errorcode>LWRES_R_FAILURE</errorcode> -if -<parameter>filename</parameter> -could not be opened or contained incorrect -resolver statements. -</para> -<para> -<function>lwres_conf_print()</function> -returns -<errorcode>LWRES_R_SUCCESS</errorcode> -unless an error occurred when converting the network addresses to a -numeric host address string. -If this happens, the function returns -<errorcode>LWRES_R_FAILURE</errorcode>. -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>stdio</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, -<citerefentry> -<refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum> -</citerefentry>. -</para> -</refsect1> -<refsect1> -<title>FILES</title> -<para> -<filename>/etc/resolv.conf</filename> -</para> -</refsect1> -</refentry> + <para><function>lwres_conf_print()</function> + prints the + <type>lwres_conf_t</type> + structure for resolver context + <parameter>ctx</parameter> + to the + <type>FILE</type> + <parameter>fp</parameter>. + </para> + </refsect1> + <refsect1> + + <title>RETURN VALUES</title> + + <para><function>lwres_conf_parse()</function> + returns <errorcode>LWRES_R_SUCCESS</errorcode> + if it successfully read and parsed + <parameter>filename</parameter>. + It returns <errorcode>LWRES_R_FAILURE</errorcode> + if <parameter>filename</parameter> + could not be opened or contained incorrect + resolver statements. + </para> + + <para><function>lwres_conf_print()</function> + returns <errorcode>LWRES_R_SUCCESS</errorcode> + unless an error occurred when converting the network addresses to a + numeric host address string. + If this happens, the function returns + <errorcode>LWRES_R_FAILURE</errorcode>. + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>stdio</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>resolver</refentrytitle><manvolnum>5</manvolnum> + </citerefentry>. + </para> + </refsect1> + <refsect1> + <title>FILES</title> + <para><filename>/etc/resolv.conf</filename> + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_config.html b/contrib/bind9/lib/lwres/man/lwres_config.html index 339a48784333..efa33d85424c 100644 --- a/contrib/bind9/lib/lwres/man/lwres_config.html +++ b/contrib/bind9/lib/lwres/man/lwres_config.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_config.html,v 1.4.2.1.4.11 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_config.html,v 1.5.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_config</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_conf_init, lwres_conf_clear, lwres_conf_parse, lwres_conf_print, lwres_conf_get — lightweight resolver configuration</p> @@ -31,56 +31,36 @@ <h2>Synopsis</h2> <div class="funcsynopsis"> <pre class="funcsynopsisinfo">#include <lwres/lwres.h></pre> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_conf_init</b>(</code></td> -<td> </td> +<td>lwres_context_t * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<var class="pdparam">ctx</var><code>)</code>;</td> +</tr></table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_conf_clear</b>(</code></td> -<td> </td> +<td>lwres_context_t * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">ctx</var><code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_conf_parse</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>const char * </td> <td> -<code>)</code>;</td> +<var class="pdparam">filename</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -88,113 +68,89 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_conf_print</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>FILE * </td> <td> -<code>)</code>;</td> +<var class="pdparam">fp</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> <td><code class="funcdef"> lwres_conf_t * <b class="fsfunc">lwres_conf_get</b>(</code></td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> +<td>lwres_context_t * </td> <td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">ctx</var><code>)</code>;</td> +</tr></table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549475"></a><h2>DESCRIPTION</h2> -<p> -<code class="function">lwres_conf_init()</code> -creates an empty -<span class="type">lwres_conf_t</span> -structure for lightweight resolver context -<em class="parameter"><code>ctx</code></em>. -</p> -<p> -<code class="function">lwres_conf_clear()</code> -frees up all the internal memory used by -that -<span class="type">lwres_conf_t</span> -structure in resolver context -<em class="parameter"><code>ctx</code></em>. -</p> -<p> -<code class="function">lwres_conf_parse()</code> -opens the file -<em class="parameter"><code>filename</code></em> -and parses it to initialise the resolver context -<em class="parameter"><code>ctx</code></em>'s -<span class="type">lwres_conf_t</span> -structure. -</p> -<p> -<code class="function">lwres_conf_print()</code> -prints the -<span class="type">lwres_conf_t</span> -structure for resolver context -<em class="parameter"><code>ctx</code></em> -to the -<span class="type">FILE</span> -<em class="parameter"><code>fp</code></em>. -</p> +<a name="id2543441"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_conf_init()</code> + creates an empty + <span class="type">lwres_conf_t</span> + structure for lightweight resolver context + <em class="parameter"><code>ctx</code></em>. + </p> +<p><code class="function">lwres_conf_clear()</code> + frees up all the internal memory used by + that + <span class="type">lwres_conf_t</span> + structure in resolver context + <em class="parameter"><code>ctx</code></em>. + </p> +<p><code class="function">lwres_conf_parse()</code> + opens the file + <em class="parameter"><code>filename</code></em> + and parses it to initialise the resolver context + <em class="parameter"><code>ctx</code></em>'s + <span class="type">lwres_conf_t</span> + structure. + </p> +<p><code class="function">lwres_conf_print()</code> + prints the + <span class="type">lwres_conf_t</span> + structure for resolver context + <em class="parameter"><code>ctx</code></em> + to the + <span class="type">FILE</span> + <em class="parameter"><code>fp</code></em>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549546"></a><h2>RETURN VALUES</h2> -<p> -<code class="function">lwres_conf_parse()</code> -returns -<span class="errorcode">LWRES_R_SUCCESS</span> -if it successfully read and parsed -<em class="parameter"><code>filename</code></em>. -It returns -<span class="errorcode">LWRES_R_FAILURE</span> -if -<em class="parameter"><code>filename</code></em> -could not be opened or contained incorrect -resolver statements. -</p> -<p> -<code class="function">lwres_conf_print()</code> -returns -<span class="errorcode">LWRES_R_SUCCESS</span> -unless an error occurred when converting the network addresses to a -numeric host address string. -If this happens, the function returns -<span class="errorcode">LWRES_R_FAILURE</span>. -</p> +<a name="id2543508"></a><h2>RETURN VALUES</h2> +<p><code class="function">lwres_conf_parse()</code> + returns <span class="errorcode">LWRES_R_SUCCESS</span> + if it successfully read and parsed + <em class="parameter"><code>filename</code></em>. + It returns <span class="errorcode">LWRES_R_FAILURE</span> + if <em class="parameter"><code>filename</code></em> + could not be opened or contained incorrect + resolver statements. + </p> +<p><code class="function">lwres_conf_print()</code> + returns <span class="errorcode">LWRES_R_SUCCESS</span> + unless an error occurred when converting the network addresses to a + numeric host address string. + If this happens, the function returns + <span class="errorcode">LWRES_R_FAILURE</span>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549586"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">stdio</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>. -</p> +<a name="id2543545"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">stdio</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">resolver</span>(5)</span>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549612"></a><h2>FILES</h2> -<p> -<code class="filename">/etc/resolv.conf</code> -</p> +<a name="id2543571"></a><h2>FILES</h2> +<p><code class="filename">/etc/resolv.conf</code> + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_context.3 b/contrib/bind9/lib/lwres/man/lwres_context.3 index ba68e408cce9..8883a01a22ee 100644 --- a/contrib/bind9/lib/lwres/man/lwres_context.3 +++ b/contrib/bind9/lib/lwres/man/lwres_context.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001, 2003 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_context.3,v 1.13.2.2.2.7 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_context.3,v 1.17.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_context .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,19 +36,19 @@ lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_con #include <lwres/lwres.h> .fi .HP 36 -.BI "lwres_result_t lwres_context_create(lwres_context_t\ **contextp, void\ *arg, lwres_malloc_t\ malloc_function, lwres_free_t\ free_function);" +.BI "lwres_result_t lwres_context_create(lwres_context_t\ **" "contextp" ", void\ *" "arg" ", lwres_malloc_t\ " "malloc_function" ", lwres_free_t\ " "free_function" ");" .HP 37 -.BI "lwres_result_t lwres_context_destroy(lwres_context_t\ **contextp);" +.BI "lwres_result_t lwres_context_destroy(lwres_context_t\ **" "contextp" ");" .HP 30 -.BI "void lwres_context_initserial(lwres_context_t\ *ctx, lwres_uint32_t\ serial);" +.BI "void lwres_context_initserial(lwres_context_t\ *" "ctx" ", lwres_uint32_t\ " "serial" ");" .HP 40 -.BI "lwres_uint32_t lwres_context_nextserial(lwres_context_t\ *ctx);" +.BI "lwres_uint32_t lwres_context_nextserial(lwres_context_t\ *" "ctx" ");" .HP 27 -.BI "void lwres_context_freemem(lwres_context_t\ *ctx, void\ *mem, size_t\ len);" +.BI "void lwres_context_freemem(lwres_context_t\ *" "ctx" ", void\ *" "mem" ", size_t\ " "len" ");" .HP 28 -.BI "void lwres_context_allocmem(lwres_context_t\ *ctx, size_t\ len);" +.BI "void lwres_context_allocmem(lwres_context_t\ *" "ctx" ", size_t\ " "len" ");" .HP 30 -.BI "void * lwres_context_sendrecv(lwres_context_t\ *ctx, void\ *sendbase, int\ sendlen, void\ *recvbase, int\ recvlen, int\ *recvd_len);" +.BI "void * lwres_context_sendrecv(lwres_context_t\ *" "ctx" ", void\ *" "sendbase" ", int\ " "sendlen" ", void\ *" "recvbase" ", int\ " "recvlen" ", int\ *" "recvd_len" ");" .SH "DESCRIPTION" .PP \fBlwres_context_create()\fR @@ -72,7 +72,8 @@ to free it. If \fImalloc_function\fR and \fIfree_function\fR -are NULL, memory is allocated using .Xr malloc 3 and +are NULL, memory is allocated using +\fBmalloc\fR(3). and \fBfree\fR(3). It is not permitted to have a NULL \fImalloc_function\fR and a non\-NULL @@ -161,6 +162,9 @@ times out waiting for a response. .PP \fBlwres_conf_init\fR(3), \fBmalloc\fR(3), -\fBfree\fR(3 ). +\fBfree\fR(3). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001, 2003 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_context.docbook b/contrib/bind9/lib/lwres/man/lwres_context.docbook index 48d43362e1ee..65f157ced23a 100644 --- a/contrib/bind9/lib/lwres/man/lwres_context.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_context.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_context.docbook,v 1.3.2.2.2.3 2005/05/12 21:36:12 sra Exp $ --> - +<!-- $Id: lwres_context.docbook,v 1.5.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> -<refmeta> -<refentrytitle>lwres_context</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_context</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -46,255 +46,217 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_context_create</refname> -<refname>lwres_context_destroy</refname> -<refname>lwres_context_nextserial</refname> -<refname>lwres_context_initserial</refname> -<refname>lwres_context_freemem</refname> -<refname>lwres_context_allocmem</refname> -<refname>lwres_context_sendrecv</refname> -<refpurpose>lightweight resolver context management</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_context_create</refname> + <refname>lwres_context_destroy</refname> + <refname>lwres_context_nextserial</refname> + <refname>lwres_context_initserial</refname> + <refname>lwres_context_freemem</refname> + <refname>lwres_context_allocmem</refname> + <refname>lwres_context_sendrecv</refname> + <refpurpose>lightweight resolver context management</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_context_create</function></funcdef> -<paramdef>lwres_context_t **contextp</paramdef> -<paramdef>void *arg</paramdef> -<paramdef>lwres_malloc_t malloc_function</paramdef> -<paramdef>lwres_free_t free_function</paramdef> -</funcprototype> + <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + <paramdef>lwres_malloc_t <parameter>malloc_function</parameter></paramdef> + <paramdef>lwres_free_t <parameter>free_function</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_context_destroy</function></funcdef> -<paramdef>lwres_context_t **contextp</paramdef> -</funcprototype> + <paramdef>lwres_context_t **<parameter>contextp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_context_initserial</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_uint32_t serial</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_uint32_t <parameter>serial</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_uint32_t <function>lwres_context_nextserial</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_context_freemem</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>void *mem</paramdef> -<paramdef>size_t len</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>void *<parameter>mem</parameter></paramdef> + <paramdef>size_t <parameter>len</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_context_allocmem</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>size_t len</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>size_t <parameter>len</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void * <function>lwres_context_sendrecv</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>void *sendbase</paramdef> -<paramdef>int sendlen</paramdef> -<paramdef>void *recvbase</paramdef> -<paramdef>int recvlen</paramdef> -<paramdef>int *recvd_len</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>void *<parameter>sendbase</parameter></paramdef> + <paramdef>int <parameter>sendlen</parameter></paramdef> + <paramdef>void *<parameter>recvbase</parameter></paramdef> + <paramdef>int <parameter>recvlen</parameter></paramdef> + <paramdef>int *<parameter>recvd_len</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> -<para> -<function>lwres_context_create()</function> -creates a -<type>lwres_context_t</type> -structure for use in lightweight resolver operations. -It holds a socket and other data needed for communicating -with a resolver daemon. -The new -<type>lwres_context_t</type> -is returned through -<parameter>contextp</parameter>, - -a pointer to a -<type>lwres_context_t</type> -pointer. This -<type>lwres_context_t</type> -pointer must initially be NULL, and is modified -to point to the newly created -<type>lwres_context_t</type>. - -</para> -<para> -When the lightweight resolver needs to perform dynamic memory -allocation, it will call -<parameter>malloc_function</parameter> -to allocate memory and -<parameter>free_function</parameter> - -to free it. If -<parameter>malloc_function</parameter> -and -<parameter>free_function</parameter> + </refsynopsisdiv> + <refsect1> + <title>DESCRIPTION</title> -are NULL, memory is allocated using -.Xr malloc 3 -and -<citerefentry> -<refentrytitle>free</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>. + <para><function>lwres_context_create()</function> + creates a <type>lwres_context_t</type> structure for use in + lightweight resolver operations. It holds a socket and other + data needed for communicating with a resolver daemon. The new + <type>lwres_context_t</type> is returned through + <parameter>contextp</parameter>, a pointer to a + <type>lwres_context_t</type> pointer. This + <type>lwres_context_t</type> pointer must initially be NULL, and + is modified to point to the newly created + <type>lwres_context_t</type>. + </para> + <para> + When the lightweight resolver needs to perform dynamic memory + allocation, it will call + <parameter>malloc_function</parameter> + to allocate memory and + <parameter>free_function</parameter> + to free it. If + <parameter>malloc_function</parameter> + and + <parameter>free_function</parameter> + are NULL, memory is allocated using + <citerefentry> + <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + and + <citerefentry> + <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. -It is not permitted to have a NULL -<parameter>malloc_function</parameter> -and a non-NULL -<parameter>free_function</parameter> -or vice versa. -<parameter>arg</parameter> -is passed as the first parameter to the memory -allocation functions. -If -<parameter>malloc_function</parameter> -and -<parameter>free_function</parameter> -are NULL, -<parameter>arg</parameter> + It is not permitted to have a NULL + <parameter>malloc_function</parameter> and a non-NULL + <parameter>free_function</parameter> or vice versa. + <parameter>arg</parameter> is passed as the first parameter to + the memory allocation functions. If + <parameter>malloc_function</parameter> and + <parameter>free_function</parameter> are NULL, + <parameter>arg</parameter> is unused and should be passed as + NULL. + </para> -is unused and should be passed as NULL. -</para> -<para> -Once memory for the structure has been allocated, -it is initialized using -<citerefentry> -<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum> -</citerefentry> + <para> + Once memory for the structure has been allocated, + it is initialized using + <citerefentry> + <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + and returned via <parameter>*contextp</parameter>. + </para> -and returned via -<parameter>*contextp</parameter>. + <para><function>lwres_context_destroy()</function> + destroys a <type>lwres_context_t</type>, closing its socket. + <parameter>contextp</parameter> is a pointer to a pointer to the + context that is to be destroyed. The pointer will be set to + NULL when the context has been destroyed. + </para> -</para> -<para> -<function>lwres_context_destroy()</function> -destroys a -<type>lwres_context_t</type>, + <para> + The context holds a serial number that is used to identify + resolver request packets and associate responses with the + corresponding requests. This serial number is controlled using + <function>lwres_context_initserial()</function> and + <function>lwres_context_nextserial()</function>. + <function>lwres_context_initserial()</function> sets the serial + number for context <parameter>*ctx</parameter> to + <parameter>serial</parameter>. + <function>lwres_context_nextserial()</function> increments the + serial number and returns the previous value. + </para> -closing its socket. -<parameter>contextp</parameter> -is a pointer to a pointer to the context that is to be destroyed. -The pointer will be set to NULL when the context has been destroyed. -</para> -<para> -The context holds a serial number that is used to identify resolver -request packets and associate responses with the corresponding requests. -This serial number is controlled using -<function>lwres_context_initserial()</function> -and -<function>lwres_context_nextserial()</function>. -<function>lwres_context_initserial()</function> -sets the serial number for context -<parameter>*ctx</parameter> -to -<parameter>serial</parameter>. + <para> + Memory for a lightweight resolver context is allocated and freed + using <function>lwres_context_allocmem()</function> and + <function>lwres_context_freemem()</function>. These use + whatever allocations were defined when the context was created + with <function>lwres_context_create()</function>. + <function>lwres_context_allocmem()</function> allocates + <parameter>len</parameter> bytes of memory and if successful + returns a pointer to the allocated storage. + <function>lwres_context_freemem()</function> frees + <parameter>len</parameter> bytes of space starting at location + <parameter>mem</parameter>. + </para> -<function>lwres_context_nextserial()</function> -increments the serial number and returns the previous value. -</para> -<para> -Memory for a lightweight resolver context is allocated and freed using -<function>lwres_context_allocmem()</function> -and -<function>lwres_context_freemem()</function>. -These use whatever allocations were defined when the context was -created with -<function>lwres_context_create()</function>. -<function>lwres_context_allocmem()</function> -allocates -<parameter>len</parameter> -bytes of memory and if successful returns a pointer to the allocated -storage. -<function>lwres_context_freemem()</function> -frees -<parameter>len</parameter> -bytes of space starting at location -<parameter>mem</parameter>. + <para><function>lwres_context_sendrecv()</function> + performs I/O for the context <parameter>ctx</parameter>. Data + are read and written from the context's socket. It writes data + from <parameter>sendbase</parameter> — typically a + lightweight resolver query packet — and waits for a reply + which is copied to the receive buffer at + <parameter>recvbase</parameter>. The number of bytes that were + written to this receive buffer is returned in + <parameter>*recvd_len</parameter>. + </para> + </refsect1> -</para> -<para> -<function>lwres_context_sendrecv()</function> -performs I/O for the context -<parameter>ctx</parameter>. + <refsect1> + <title>RETURN VALUES</title> -Data are read and written from the context's socket. -It writes data from -<parameter>sendbase</parameter> -— typically a lightweight resolver query packet — -and waits for a reply which is copied to the receive buffer at -<parameter>recvbase</parameter>. + <para><function>lwres_context_create()</function> + returns <errorcode>LWRES_R_NOMEMORY</errorcode> if memory for + the <type>struct lwres_context</type> could not be allocated, + <errorcode>LWRES_R_SUCCESS</errorcode> otherwise. + </para> + <para> + Successful calls to the memory allocator + <function>lwres_context_allocmem()</function> + return a pointer to the start of the allocated space. + It returns NULL if memory could not be allocated. + </para> + <para><errorcode>LWRES_R_SUCCESS</errorcode> + is returned when + <function>lwres_context_sendrecv()</function> + completes successfully. + <errorcode>LWRES_R_IOERROR</errorcode> + is returned if an I/O error occurs and + <errorcode>LWRES_R_TIMEOUT</errorcode> + is returned if + <function>lwres_context_sendrecv()</function> + times out waiting for a response. + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -The number of bytes that were written to this receive buffer is -returned in -<parameter>*recvd_len</parameter>. + <citerefentry> + <refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -</para> -</refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> -<function>lwres_context_create()</function> -returns -<errorcode>LWRES_R_NOMEMORY</errorcode> -if memory for the -<type>struct lwres_context</type> -could not be allocated, -<errorcode>LWRES_R_SUCCESS</errorcode> -otherwise. -</para> -<para> -Successful calls to the memory allocator -<function>lwres_context_allocmem()</function> -return a pointer to the start of the allocated space. -It returns NULL if memory could not be allocated. -</para> -<para> -<errorcode>LWRES_R_SUCCESS</errorcode> -is returned when -<function>lwres_context_sendrecv()</function> -completes successfully. -<errorcode>LWRES_R_IOERROR</errorcode> -is returned if an I/O error occurs and -<errorcode>LWRES_R_TIMEOUT</errorcode> -is returned if -<function>lwres_context_sendrecv()</function> -times out waiting for a response. -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>lwres_conf_init</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>malloc</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>free</refentrytitle><manvolnum>3 -</manvolnum> -</citerefentry>. -</para> -</refsect1> -</refentry> + <citerefentry> + <refentrytitle>free</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_context.html b/contrib/bind9/lib/lwres/man/lwres_context.html index 6f7fbecec2b4..f2aa7e1711f6 100644 --- a/contrib/bind9/lib/lwres/man/lwres_context.html +++ b/contrib/bind9/lib/lwres/man/lwres_context.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_context.html,v 1.5.2.2.2.12 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_context.html,v 1.7.18.16 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_context</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_context_create, lwres_context_destroy, lwres_context_nextserial, lwres_context_initserial, lwres_context_freemem, lwres_context_allocmem, lwres_context_sendrecv — lightweight resolver context management</p> @@ -36,106 +36,81 @@ <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_context_create</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t ** </td> +<td> +<var class="pdparam">contextp</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>void * </td> +<td> +<var class="pdparam">arg</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_malloc_t </td> +<td> +<var class="pdparam">malloc_function</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_free_t </td> <td> -<code>)</code>;</td> +<var class="pdparam">free_function</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_context_destroy</b>(</code></td> -<td> </td> +<td>lwres_context_t ** </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">contextp</var><code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_context_initserial</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_uint32_t </td> <td> -<code>)</code>;</td> +<var class="pdparam">serial</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> lwres_uint32_t <b class="fsfunc">lwres_context_nextserial</b>(</code></td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> +<td>lwres_context_t * </td> <td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">ctx</var><code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_context_freemem</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>void * </td> +<td> +<var class="pdparam">mem</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>size_t </td> <td> -<code>)</code>;</td> +<var class="pdparam">len</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -143,19 +118,15 @@ void <td><code class="funcdef"> void <b class="fsfunc">lwres_context_allocmem</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>size_t </td> <td> -<code>)</code>;</td> +<var class="pdparam">len</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> @@ -163,214 +134,162 @@ void <td><code class="funcdef"> void * <b class="fsfunc">lwres_context_sendrecv</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>void * </td> +<td> +<var class="pdparam">sendbase</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">sendlen</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>void * </td> +<td> +<var class="pdparam">recvbase</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">recvlen</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>int * </td> <td> -<code>)</code>;</td> +<var class="pdparam">recvd_len</var><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549540"></a><h2>DESCRIPTION</h2> -<p> -<code class="function">lwres_context_create()</code> -creates a -<span class="type">lwres_context_t</span> -structure for use in lightweight resolver operations. -It holds a socket and other data needed for communicating -with a resolver daemon. -The new -<span class="type">lwres_context_t</span> -is returned through -<em class="parameter"><code>contextp</code></em>, - -a pointer to a -<span class="type">lwres_context_t</span> -pointer. This -<span class="type">lwres_context_t</span> -pointer must initially be NULL, and is modified -to point to the newly created -<span class="type">lwres_context_t</span>. - -</p> -<p> -When the lightweight resolver needs to perform dynamic memory -allocation, it will call -<em class="parameter"><code>malloc_function</code></em> -to allocate memory and -<em class="parameter"><code>free_function</code></em> - -to free it. If -<em class="parameter"><code>malloc_function</code></em> -and -<em class="parameter"><code>free_function</code></em> - -are NULL, memory is allocated using -.Xr malloc 3 -and -<span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>. - -It is not permitted to have a NULL -<em class="parameter"><code>malloc_function</code></em> -and a non-NULL -<em class="parameter"><code>free_function</code></em> -or vice versa. -<em class="parameter"><code>arg</code></em> -is passed as the first parameter to the memory -allocation functions. -If -<em class="parameter"><code>malloc_function</code></em> -and -<em class="parameter"><code>free_function</code></em> -are NULL, -<em class="parameter"><code>arg</code></em> - -is unused and should be passed as NULL. -</p> +<a name="id2543531"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_context_create()</code> + creates a <span class="type">lwres_context_t</span> structure for use in + lightweight resolver operations. It holds a socket and other + data needed for communicating with a resolver daemon. The new + <span class="type">lwres_context_t</span> is returned through + <em class="parameter"><code>contextp</code></em>, a pointer to a + <span class="type">lwres_context_t</span> pointer. This + <span class="type">lwres_context_t</span> pointer must initially be NULL, and + is modified to point to the newly created + <span class="type">lwres_context_t</span>. + </p> <p> -Once memory for the structure has been allocated, -it is initialized using -<span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span> + When the lightweight resolver needs to perform dynamic memory + allocation, it will call + <em class="parameter"><code>malloc_function</code></em> + to allocate memory and + <em class="parameter"><code>free_function</code></em> + to free it. If + <em class="parameter"><code>malloc_function</code></em> + and + <em class="parameter"><code>free_function</code></em> + are NULL, memory is allocated using + <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>. + and + <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>. -and returned via -<em class="parameter"><code>*contextp</code></em>. - -</p> -<p> -<code class="function">lwres_context_destroy()</code> -destroys a -<span class="type">lwres_context_t</span>, - -closing its socket. -<em class="parameter"><code>contextp</code></em> -is a pointer to a pointer to the context that is to be destroyed. -The pointer will be set to NULL when the context has been destroyed. -</p> + It is not permitted to have a NULL + <em class="parameter"><code>malloc_function</code></em> and a non-NULL + <em class="parameter"><code>free_function</code></em> or vice versa. + <em class="parameter"><code>arg</code></em> is passed as the first parameter to + the memory allocation functions. If + <em class="parameter"><code>malloc_function</code></em> and + <em class="parameter"><code>free_function</code></em> are NULL, + <em class="parameter"><code>arg</code></em> is unused and should be passed as + NULL. + </p> <p> -The context holds a serial number that is used to identify resolver -request packets and associate responses with the corresponding requests. -This serial number is controlled using -<code class="function">lwres_context_initserial()</code> -and -<code class="function">lwres_context_nextserial()</code>. -<code class="function">lwres_context_initserial()</code> -sets the serial number for context -<em class="parameter"><code>*ctx</code></em> -to -<em class="parameter"><code>serial</code></em>. - -<code class="function">lwres_context_nextserial()</code> -increments the serial number and returns the previous value. -</p> + Once memory for the structure has been allocated, + it is initialized using + <span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span> + and returned via <em class="parameter"><code>*contextp</code></em>. + </p> +<p><code class="function">lwres_context_destroy()</code> + destroys a <span class="type">lwres_context_t</span>, closing its socket. + <em class="parameter"><code>contextp</code></em> is a pointer to a pointer to the + context that is to be destroyed. The pointer will be set to + NULL when the context has been destroyed. + </p> <p> -Memory for a lightweight resolver context is allocated and freed using -<code class="function">lwres_context_allocmem()</code> -and -<code class="function">lwres_context_freemem()</code>. -These use whatever allocations were defined when the context was -created with -<code class="function">lwres_context_create()</code>. -<code class="function">lwres_context_allocmem()</code> -allocates -<em class="parameter"><code>len</code></em> -bytes of memory and if successful returns a pointer to the allocated -storage. -<code class="function">lwres_context_freemem()</code> -frees -<em class="parameter"><code>len</code></em> -bytes of space starting at location -<em class="parameter"><code>mem</code></em>. - -</p> + The context holds a serial number that is used to identify + resolver request packets and associate responses with the + corresponding requests. This serial number is controlled using + <code class="function">lwres_context_initserial()</code> and + <code class="function">lwres_context_nextserial()</code>. + <code class="function">lwres_context_initserial()</code> sets the serial + number for context <em class="parameter"><code>*ctx</code></em> to + <em class="parameter"><code>serial</code></em>. + <code class="function">lwres_context_nextserial()</code> increments the + serial number and returns the previous value. + </p> <p> -<code class="function">lwres_context_sendrecv()</code> -performs I/O for the context -<em class="parameter"><code>ctx</code></em>. - -Data are read and written from the context's socket. -It writes data from -<em class="parameter"><code>sendbase</code></em> -— typically a lightweight resolver query packet — -and waits for a reply which is copied to the receive buffer at -<em class="parameter"><code>recvbase</code></em>. - -The number of bytes that were written to this receive buffer is -returned in -<em class="parameter"><code>*recvd_len</code></em>. - -</p> + Memory for a lightweight resolver context is allocated and freed + using <code class="function">lwres_context_allocmem()</code> and + <code class="function">lwres_context_freemem()</code>. These use + whatever allocations were defined when the context was created + with <code class="function">lwres_context_create()</code>. + <code class="function">lwres_context_allocmem()</code> allocates + <em class="parameter"><code>len</code></em> bytes of memory and if successful + returns a pointer to the allocated storage. + <code class="function">lwres_context_freemem()</code> frees + <em class="parameter"><code>len</code></em> bytes of space starting at location + <em class="parameter"><code>mem</code></em>. + </p> +<p><code class="function">lwres_context_sendrecv()</code> + performs I/O for the context <em class="parameter"><code>ctx</code></em>. Data + are read and written from the context's socket. It writes data + from <em class="parameter"><code>sendbase</code></em> — typically a + lightweight resolver query packet — and waits for a reply + which is copied to the receive buffer at + <em class="parameter"><code>recvbase</code></em>. The number of bytes that were + written to this receive buffer is returned in + <em class="parameter"><code>*recvd_len</code></em>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549789"></a><h2>RETURN VALUES</h2> -<p> -<code class="function">lwres_context_create()</code> -returns -<span class="errorcode">LWRES_R_NOMEMORY</span> -if memory for the -<span class="type">struct lwres_context</span> -could not be allocated, -<span class="errorcode">LWRES_R_SUCCESS</span> -otherwise. -</p> +<a name="id2543719"></a><h2>RETURN VALUES</h2> +<p><code class="function">lwres_context_create()</code> + returns <span class="errorcode">LWRES_R_NOMEMORY</span> if memory for + the <span class="type">struct lwres_context</span> could not be allocated, + <span class="errorcode">LWRES_R_SUCCESS</span> otherwise. + </p> <p> -Successful calls to the memory allocator -<code class="function">lwres_context_allocmem()</code> -return a pointer to the start of the allocated space. -It returns NULL if memory could not be allocated. -</p> -<p> -<span class="errorcode">LWRES_R_SUCCESS</span> -is returned when -<code class="function">lwres_context_sendrecv()</code> -completes successfully. -<span class="errorcode">LWRES_R_IOERROR</span> -is returned if an I/O error occurs and -<span class="errorcode">LWRES_R_TIMEOUT</span> -is returned if -<code class="function">lwres_context_sendrecv()</code> -times out waiting for a response. -</p> + Successful calls to the memory allocator + <code class="function">lwres_context_allocmem()</code> + return a pointer to the start of the allocated space. + It returns NULL if memory could not be allocated. + </p> +<p><span class="errorcode">LWRES_R_SUCCESS</span> + is returned when + <code class="function">lwres_context_sendrecv()</code> + completes successfully. + <span class="errorcode">LWRES_R_IOERROR</span> + is returned if an I/O error occurs and + <span class="errorcode">LWRES_R_TIMEOUT</span> + is returned if + <code class="function">lwres_context_sendrecv()</code> + times out waiting for a response. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549841"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>, +<a name="id2543769"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">lwres_conf_init</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">malloc</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">free</span>(3 -)</span>. -</p> + <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_gabn.3 b/contrib/bind9/lib/lwres/man/lwres_gabn.3 index 593ebc5cb3cc..69d311f28627 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gabn.3 +++ b/contrib/bind9/lib/lwres/man/lwres_gabn.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_gabn.3,v 1.13.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_gabn.3,v 1.16.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_gabn .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,17 +36,17 @@ lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lw #include <lwres/lwres.h> .fi .HP 40 -.BI "lwres_result_t lwres_gabnrequest_render(lwres_context_t\ *ctx, lwres_gabnrequest_t\ *req, lwres_lwpacket_t\ *pkt, lwres_buffer_t\ *b);" +.BI "lwres_result_t lwres_gabnrequest_render(lwres_context_t\ *" "ctx" ", lwres_gabnrequest_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");" .HP 41 -.BI "lwres_result_t lwres_gabnresponse_render(lwres_context_t\ *ctx, lwres_gabnresponse_t\ *req, lwres_lwpacket_t\ *pkt, lwres_buffer_t\ *b);" +.BI "lwres_result_t lwres_gabnresponse_render(lwres_context_t\ *" "ctx" ", lwres_gabnresponse_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");" .HP 39 -.BI "lwres_result_t lwres_gabnrequest_parse(lwres_context_t\ *ctx, lwres_buffer_t\ *b, lwres_lwpacket_t\ *pkt, lwres_gabnrequest_t\ **structp);" +.BI "lwres_result_t lwres_gabnrequest_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gabnrequest_t\ **" "structp" ");" .HP 40 -.BI "lwres_result_t lwres_gabnresponse_parse(lwres_context_t\ *ctx, lwres_buffer_t\ *b, lwres_lwpacket_t\ *pkt, lwres_gabnresponse_t\ **structp);" +.BI "lwres_result_t lwres_gabnresponse_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gabnresponse_t\ **" "structp" ");" .HP 29 -.BI "void lwres_gabnresponse_free(lwres_context_t\ *ctx, lwres_gabnresponse_t\ **structp);" +.BI "void lwres_gabnresponse_free(lwres_context_t\ *" "ctx" ", lwres_gabnresponse_t\ **" "structp" ");" .HP 28 -.BI "void lwres_gabnrequest_free(lwres_context_t\ *ctx, lwres_gabnrequest_t\ **structp);" +.BI "void lwres_gabnrequest_free(lwres_context_t\ *" "ctx" ", lwres_gabnrequest_t\ **" "structp" ");" .SH "DESCRIPTION" .PP These are low\-level routines for creating and parsing lightweight resolver name\-to\-address lookup request and response messages. @@ -59,18 +59,36 @@ There are four main functions for the getaddrbyname opcode. One render function .PP These structures are defined in \fI<lwres/lwres.h>\fR. They are shown below. -.sp -.RS 3n +.PP +.RS 4 .nf #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U +.fi +.RE +.sp +.PP +.RS 4 +.nf typedef struct lwres_addr lwres_addr_t; typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; +.fi +.RE +.sp +.PP +.RS 4 +.nf typedef struct { lwres_uint32_t flags; lwres_uint32_t addrtypes; lwres_uint16_t namelen; char *name; } lwres_gabnrequest_t; +.fi +.RE +.sp +.PP +.RS 4 +.nf typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -169,6 +187,9 @@ in the packet header structure indicate that the packet is not a response to an earlier query. .SH "SEE ALSO" .PP -\fBlwres_packet\fR(3 ) +\fBlwres_packet\fR(3) .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_gabn.docbook b/contrib/bind9/lib/lwres/man/lwres_gabn.docbook index 6e90ea3905b3..3b81acfc6f95 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gabn.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_gabn.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_gabn.docbook,v 1.3.206.3 2005/05/12 21:36:12 sra Exp $ --> - +<!-- $Id: lwres_gabn.docbook,v 1.4.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> -<refmeta> -<refentrytitle>lwres_gabn</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_gabn</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,106 +45,114 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_gabnrequest_render</refname> -<refname>lwres_gabnresponse_render</refname> -<refname>lwres_gabnrequest_parse</refname> -<refname>lwres_gabnresponse_parse</refname> -<refname>lwres_gabnresponse_free</refname> -<refname>lwres_gabnrequest_free</refname> -<refpurpose>lightweight resolver getaddrbyname message handling</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_gabnrequest_render</refname> + <refname>lwres_gabnresponse_render</refname> + <refname>lwres_gabnrequest_parse</refname> + <refname>lwres_gabnresponse_parse</refname> + <refname>lwres_gabnresponse_free</refname> + <refname>lwres_gabnrequest_free</refname> + <refpurpose>lightweight resolver getaddrbyname message handling</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_gabnrequest_render</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_gabnrequest_t *req</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_gabnrequest_t *<parameter>req</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_gabnresponse_render</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_gabnresponse_t *req</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_gabnresponse_t *<parameter>req</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_gabnrequest_parse</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_gabnrequest_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_gabnresponse_parse</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_gabnresponse_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_gabnresponse_free</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_gabnresponse_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_gabnrequest_free</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_gabnrequest_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_gabnrequest_t **<parameter>structp</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> -<para> -These are low-level routines for creating and parsing -lightweight resolver name-to-address lookup request and -response messages. -</para><para> -There are four main functions for the getaddrbyname opcode. -One render function converts a getaddrbyname request structure — -<type>lwres_gabnrequest_t</type> — -to the lighweight resolver's canonical format. -It is complemented by a parse function that converts a packet in this -canonical format to a getaddrbyname request structure. -Another render function converts the getaddrbyname response structure — -<type>lwres_gabnresponse_t</type> — -to the canonical format. -This is complemented by a parse function which converts a packet in -canonical format to a getaddrbyname response structure. -</para> -<para> -These structures are defined in -<filename><lwres/lwres.h></filename>. -They are shown below. -<programlisting> + </refsynopsisdiv> + <refsect1> + <title>DESCRIPTION</title> + <para> + These are low-level routines for creating and parsing + lightweight resolver name-to-address lookup request and + response messages. + </para> + <para> + There are four main functions for the getaddrbyname opcode. + One render function converts a getaddrbyname request structure — + <type>lwres_gabnrequest_t</type> — + to the lighweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a getaddrbyname request structure. + Another render function converts the getaddrbyname response structure + — <type>lwres_gabnresponse_t</type> — + to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a getaddrbyname response structure. + </para> + <para> + These structures are defined in + <filename><lwres/lwres.h></filename>. + They are shown below. + </para> + <para><programlisting> #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U - +</programlisting> + </para> + <para><programlisting> typedef struct lwres_addr lwres_addr_t; typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; - +</programlisting> + </para> + <para><programlisting> typedef struct { lwres_uint32_t flags; lwres_uint32_t addrtypes; lwres_uint16_t namelen; char *name; } lwres_gabnrequest_t; - +</programlisting> + </para> + <para><programlisting> typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -158,114 +166,95 @@ typedef struct { size_t baselen; } lwres_gabnresponse_t; </programlisting> -</para> -<para> -<function>lwres_gabnrequest_render()</function> -uses resolver context -<parameter>ctx</parameter> -to convert getaddrbyname request structure -<parameter>req</parameter> -to canonical format. -The packet header structure -<parameter>pkt</parameter> -is initialised and transferred to -buffer -<parameter>b</parameter>. + </para> + + <para><function>lwres_gabnrequest_render()</function> + uses resolver context <parameter>ctx</parameter> to convert + getaddrbyname request structure <parameter>req</parameter> to + canonical format. The packet header structure + <parameter>pkt</parameter> is initialised and transferred to + buffer <parameter>b</parameter>. + + The contents of <parameter>*req</parameter> are then appended to + the buffer in canonical format. + <function>lwres_gabnresponse_render()</function> performs the + same task, except it converts a getaddrbyname response structure + <type>lwres_gabnresponse_t</type> to the lightweight resolver's + canonical format. + </para> -The contents of -<parameter>*req</parameter> -are then appended to the buffer in canonical format. -<function>lwres_gabnresponse_render()</function> -performs the same task, except it converts a getaddrbyname response structure -<type>lwres_gabnresponse_t</type> -to the lightweight resolver's canonical format. -</para> -<para> -<function>lwres_gabnrequest_parse()</function> -uses context -<parameter>ctx</parameter> -to convert the contents of packet -<parameter>pkt</parameter> -to a -<type>lwres_gabnrequest_t</type> -structure. -Buffer -<parameter>b</parameter> -provides space to be used for storing this structure. -When the function succeeds, the resulting -<type>lwres_gabnrequest_t</type> -is made available through -<parameter>*structp</parameter>. + <para><function>lwres_gabnrequest_parse()</function> + uses context <parameter>ctx</parameter> to convert the contents + of packet <parameter>pkt</parameter> to a + <type>lwres_gabnrequest_t</type> structure. Buffer + <parameter>b</parameter> provides space to be used for storing + this structure. When the function succeeds, the resulting + <type>lwres_gabnrequest_t</type> is made available through + <parameter>*structp</parameter>. -<function>lwres_gabnresponse_parse()</function> -offers the same semantics as -<function>lwres_gabnrequest_parse()</function> -except it yields a -<type>lwres_gabnresponse_t</type> -structure. -</para> -<para> -<function>lwres_gabnresponse_free()</function> -and -<function>lwres_gabnrequest_free()</function> -release the memory in resolver context -<parameter>ctx</parameter> -that was allocated to the -<type>lwres_gabnresponse_t</type> -or -<type>lwres_gabnrequest_t</type> -structures referenced via -<parameter>structp</parameter>. + <function>lwres_gabnresponse_parse()</function> offers the same + semantics as <function>lwres_gabnrequest_parse()</function> + except it yields a <type>lwres_gabnresponse_t</type> structure. + </para> -Any memory associated with ancillary buffers and strings for those -structures is also discarded. -</para> -</refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> -The getaddrbyname opcode functions -<function>lwres_gabnrequest_render()</function>, -<function>lwres_gabnresponse_render()</function> -<function>lwres_gabnrequest_parse()</function> -and -<function>lwres_gabnresponse_parse()</function> -all return -<errorcode>LWRES_R_SUCCESS</errorcode> -on success. -They return -<errorcode>LWRES_R_NOMEMORY</errorcode> -if memory allocation fails. -<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> -is returned if the available space in the buffer -<parameter>b</parameter> -is too small to accommodate the packet header or the -<type>lwres_gabnrequest_t</type> -and -<type>lwres_gabnresponse_t</type> -structures. -<function>lwres_gabnrequest_parse()</function> -and -<function>lwres_gabnresponse_parse()</function> -will return -<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> -if the buffer is not empty after decoding the received packet. -These functions will return -<errorcode>LWRES_R_FAILURE</errorcode> -if -<structfield>pktflags</structfield> -in the packet header structure -<type>lwres_lwpacket_t</type> -indicate that the packet is not a response to an earlier query. -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>lwres_packet</refentrytitle><manvolnum>3 -</manvolnum> -</citerefentry> -</para> -</refsect1> -</refentry> + <para><function>lwres_gabnresponse_free()</function> + and <function>lwres_gabnrequest_free()</function> release the + memory in resolver context <parameter>ctx</parameter> that was + allocated to the <type>lwres_gabnresponse_t</type> or + <type>lwres_gabnrequest_t</type> structures referenced via + <parameter>structp</parameter>. + + Any memory associated with ancillary buffers and strings for + those structures is also discarded. + </para> + </refsect1> + <refsect1> + <title>RETURN VALUES</title> + <para> + The getaddrbyname opcode functions + <function>lwres_gabnrequest_render()</function>, + <function>lwres_gabnresponse_render()</function> + <function>lwres_gabnrequest_parse()</function> + and + <function>lwres_gabnresponse_parse()</function> + all return + <errorcode>LWRES_R_SUCCESS</errorcode> + on success. + They return + <errorcode>LWRES_R_NOMEMORY</errorcode> + if memory allocation fails. + <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> + is returned if the available space in the buffer + <parameter>b</parameter> + is too small to accommodate the packet header or the + <type>lwres_gabnrequest_t</type> + and + <type>lwres_gabnresponse_t</type> + structures. + <function>lwres_gabnrequest_parse()</function> + and + <function>lwres_gabnresponse_parse()</function> + will return + <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> + if the buffer is not empty after decoding the received packet. + These functions will return + <errorcode>LWRES_R_FAILURE</errorcode> + if + <structfield>pktflags</structfield> + in the packet header structure + <type>lwres_lwpacket_t</type> + indicate that the packet is not a response to an earlier query. + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_gabn.html b/contrib/bind9/lib/lwres/man/lwres_gabn.html index fce25c517032..e27954b1676e 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gabn.html +++ b/contrib/bind9/lib/lwres/man/lwres_gabn.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_gabn.html,v 1.6.2.1.4.11 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_gabn.html,v 1.7.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_gabn</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_gabnrequest_render, lwres_gabnresponse_render, lwres_gabnrequest_parse, lwres_gabnresponse_parse, lwres_gabnresponse_free, lwres_gabnrequest_free — lightweight resolver getaddrbyname message handling</p> @@ -36,29 +36,27 @@ <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_gabnrequest_render</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_gabnrequest_t * </td> +<td> +<var class="pdparam">req</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> +<var class="pdparam">b</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -66,29 +64,27 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_gabnresponse_render</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_gabnresponse_t * </td> +<td> +<var class="pdparam">req</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> +<var class="pdparam">b</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -96,29 +92,27 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_gabnrequest_parse</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gabnrequest_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -126,29 +120,27 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_gabnresponse_parse</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gabnresponse_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -156,19 +148,15 @@ lwres_result_t <td><code class="funcdef"> void <b class="fsfunc">lwres_gabnresponse_free</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gabnresponse_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> @@ -176,61 +164,66 @@ void <td><code class="funcdef"> void <b class="fsfunc">lwres_gabnrequest_free</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gabnrequest_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549528"></a><h2>DESCRIPTION</h2> +<a name="id2543522"></a><h2>DESCRIPTION</h2> <p> -These are low-level routines for creating and parsing -lightweight resolver name-to-address lookup request and -response messages. -</p> + These are low-level routines for creating and parsing + lightweight resolver name-to-address lookup request and + response messages. + </p> <p> -There are four main functions for the getaddrbyname opcode. -One render function converts a getaddrbyname request structure — -<span class="type">lwres_gabnrequest_t</span> — -to the lighweight resolver's canonical format. -It is complemented by a parse function that converts a packet in this -canonical format to a getaddrbyname request structure. -Another render function converts the getaddrbyname response structure — -<span class="type">lwres_gabnresponse_t</span> — -to the canonical format. -This is complemented by a parse function which converts a packet in -canonical format to a getaddrbyname response structure. -</p> + There are four main functions for the getaddrbyname opcode. + One render function converts a getaddrbyname request structure — + <span class="type">lwres_gabnrequest_t</span> — + to the lighweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a getaddrbyname request structure. + Another render function converts the getaddrbyname response structure + — <span class="type">lwres_gabnresponse_t</span> — + to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a getaddrbyname response structure. + </p> <p> -These structures are defined in -<code class="filename"><lwres/lwres.h></code>. -They are shown below. -</p> + These structures are defined in + <code class="filename"><lwres/lwres.h></code>. + They are shown below. + </p> <pre class="programlisting"> #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U - +</pre> +<p> + </p> +<pre class="programlisting"> typedef struct lwres_addr lwres_addr_t; typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; - +</pre> +<p> + </p> +<pre class="programlisting"> typedef struct { lwres_uint32_t flags; lwres_uint32_t addrtypes; lwres_uint16_t namelen; char *name; } lwres_gabnrequest_t; - +</pre> +<p> + </p> +<pre class="programlisting"> typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -245,113 +238,87 @@ typedef struct { } lwres_gabnresponse_t; </pre> <p> -</p> -<p> -<code class="function">lwres_gabnrequest_render()</code> -uses resolver context -<em class="parameter"><code>ctx</code></em> -to convert getaddrbyname request structure -<em class="parameter"><code>req</code></em> -to canonical format. -The packet header structure -<em class="parameter"><code>pkt</code></em> -is initialised and transferred to -buffer -<em class="parameter"><code>b</code></em>. + </p> +<p><code class="function">lwres_gabnrequest_render()</code> + uses resolver context <em class="parameter"><code>ctx</code></em> to convert + getaddrbyname request structure <em class="parameter"><code>req</code></em> to + canonical format. The packet header structure + <em class="parameter"><code>pkt</code></em> is initialised and transferred to + buffer <em class="parameter"><code>b</code></em>. -The contents of -<em class="parameter"><code>*req</code></em> -are then appended to the buffer in canonical format. -<code class="function">lwres_gabnresponse_render()</code> -performs the same task, except it converts a getaddrbyname response structure -<span class="type">lwres_gabnresponse_t</span> -to the lightweight resolver's canonical format. -</p> -<p> -<code class="function">lwres_gabnrequest_parse()</code> -uses context -<em class="parameter"><code>ctx</code></em> -to convert the contents of packet -<em class="parameter"><code>pkt</code></em> -to a -<span class="type">lwres_gabnrequest_t</span> -structure. -Buffer -<em class="parameter"><code>b</code></em> -provides space to be used for storing this structure. -When the function succeeds, the resulting -<span class="type">lwres_gabnrequest_t</span> -is made available through -<em class="parameter"><code>*structp</code></em>. + The contents of <em class="parameter"><code>*req</code></em> are then appended to + the buffer in canonical format. + <code class="function">lwres_gabnresponse_render()</code> performs the + same task, except it converts a getaddrbyname response structure + <span class="type">lwres_gabnresponse_t</span> to the lightweight resolver's + canonical format. + </p> +<p><code class="function">lwres_gabnrequest_parse()</code> + uses context <em class="parameter"><code>ctx</code></em> to convert the contents + of packet <em class="parameter"><code>pkt</code></em> to a + <span class="type">lwres_gabnrequest_t</span> structure. Buffer + <em class="parameter"><code>b</code></em> provides space to be used for storing + this structure. When the function succeeds, the resulting + <span class="type">lwres_gabnrequest_t</span> is made available through + <em class="parameter"><code>*structp</code></em>. -<code class="function">lwres_gabnresponse_parse()</code> -offers the same semantics as -<code class="function">lwres_gabnrequest_parse()</code> -except it yields a -<span class="type">lwres_gabnresponse_t</span> -structure. -</p> -<p> -<code class="function">lwres_gabnresponse_free()</code> -and -<code class="function">lwres_gabnrequest_free()</code> -release the memory in resolver context -<em class="parameter"><code>ctx</code></em> -that was allocated to the -<span class="type">lwres_gabnresponse_t</span> -or -<span class="type">lwres_gabnrequest_t</span> -structures referenced via -<em class="parameter"><code>structp</code></em>. + <code class="function">lwres_gabnresponse_parse()</code> offers the same + semantics as <code class="function">lwres_gabnrequest_parse()</code> + except it yields a <span class="type">lwres_gabnresponse_t</span> structure. + </p> +<p><code class="function">lwres_gabnresponse_free()</code> + and <code class="function">lwres_gabnrequest_free()</code> release the + memory in resolver context <em class="parameter"><code>ctx</code></em> that was + allocated to the <span class="type">lwres_gabnresponse_t</span> or + <span class="type">lwres_gabnrequest_t</span> structures referenced via + <em class="parameter"><code>structp</code></em>. -Any memory associated with ancillary buffers and strings for those -structures is also discarded. -</p> + Any memory associated with ancillary buffers and strings for + those structures is also discarded. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549720"></a><h2>RETURN VALUES</h2> +<a name="id2543667"></a><h2>RETURN VALUES</h2> <p> -The getaddrbyname opcode functions -<code class="function">lwres_gabnrequest_render()</code>, -<code class="function">lwres_gabnresponse_render()</code> -<code class="function">lwres_gabnrequest_parse()</code> -and -<code class="function">lwres_gabnresponse_parse()</code> -all return -<span class="errorcode">LWRES_R_SUCCESS</span> -on success. -They return -<span class="errorcode">LWRES_R_NOMEMORY</span> -if memory allocation fails. -<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> -is returned if the available space in the buffer -<em class="parameter"><code>b</code></em> -is too small to accommodate the packet header or the -<span class="type">lwres_gabnrequest_t</span> -and -<span class="type">lwres_gabnresponse_t</span> -structures. -<code class="function">lwres_gabnrequest_parse()</code> -and -<code class="function">lwres_gabnresponse_parse()</code> -will return -<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> -if the buffer is not empty after decoding the received packet. -These functions will return -<span class="errorcode">LWRES_R_FAILURE</span> -if -<em class="structfield"><code>pktflags</code></em> -in the packet header structure -<span class="type">lwres_lwpacket_t</span> -indicate that the packet is not a response to an earlier query. -</p> + The getaddrbyname opcode functions + <code class="function">lwres_gabnrequest_render()</code>, + <code class="function">lwres_gabnresponse_render()</code> + <code class="function">lwres_gabnrequest_parse()</code> + and + <code class="function">lwres_gabnresponse_parse()</code> + all return + <span class="errorcode">LWRES_R_SUCCESS</span> + on success. + They return + <span class="errorcode">LWRES_R_NOMEMORY</span> + if memory allocation fails. + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + is returned if the available space in the buffer + <em class="parameter"><code>b</code></em> + is too small to accommodate the packet header or the + <span class="type">lwres_gabnrequest_t</span> + and + <span class="type">lwres_gabnresponse_t</span> + structures. + <code class="function">lwres_gabnrequest_parse()</code> + and + <code class="function">lwres_gabnresponse_parse()</code> + will return + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + if the buffer is not empty after decoding the received packet. + These functions will return + <span class="errorcode">LWRES_R_FAILURE</span> + if + <em class="structfield"><code>pktflags</code></em> + in the packet header structure + <span class="type">lwres_lwpacket_t</span> + indicate that the packet is not a response to an earlier query. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549853"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3 -)</span> -</p> +<a name="id2543733"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span> + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_gai_strerror.3 b/contrib/bind9/lib/lwres/man/lwres_gai_strerror.3 index e6efcd09a81d..4fd03e2a8f4e 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gai_strerror.3 +++ b/contrib/bind9/lib/lwres/man/lwres_gai_strerror.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" 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.13.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_gai_strerror.3,v 1.16.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_gai_strerror .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -30,56 +30,78 @@ .\" disable justification (adjust text to left margin only) .ad l .SH "NAME" -gai_strerror \- print suitable error string +lwres_gai_strerror \- print suitable error string .SH "SYNOPSIS" .nf #include <lwres/netdb.h> .fi .HP 20 -.BI "char * gai_strerror(int\ ecode);" +.BI "char * gai_strerror(int\ " "ecode" ");" .SH "DESCRIPTION" .PP \fBlwres_gai_strerror()\fR returns an error message corresponding to an error code returned by \fBgetaddrinfo()\fR. The following error codes and their meaning are defined in \fIinclude/lwres/netdb.h\fR. -.TP 3n +.PP \fBEAI_ADDRFAMILY\fR +.RS 4 address family for hostname not supported -.TP 3n +.RE +.PP \fBEAI_AGAIN\fR +.RS 4 temporary failure in name resolution -.TP 3n +.RE +.PP \fBEAI_BADFLAGS\fR +.RS 4 invalid value for \fBai_flags\fR -.TP 3n +.RE +.PP \fBEAI_FAIL\fR +.RS 4 non\-recoverable failure in name resolution -.TP 3n +.RE +.PP \fBEAI_FAMILY\fR +.RS 4 \fBai_family\fR not supported -.TP 3n +.RE +.PP \fBEAI_MEMORY\fR +.RS 4 memory allocation failure -.TP 3n +.RE +.PP \fBEAI_NODATA\fR +.RS 4 no address associated with hostname -.TP 3n +.RE +.PP \fBEAI_NONAME\fR +.RS 4 hostname or servname not provided, or not known -.TP 3n +.RE +.PP \fBEAI_SERVICE\fR +.RS 4 servname not supported for \fBai_socktype\fR -.TP 3n +.RE +.PP \fBEAI_SOCKTYPE\fR +.RS 4 \fBai_socktype\fR not supported -.TP 3n +.RE +.PP \fBEAI_SYSTEM\fR +.RS 4 system error returned in errno +.RE The message invalid error code is returned if @@ -101,4 +123,7 @@ used by \fBgetaddrinfo\fR(3), \fBRFC2133\fR(). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_gai_strerror.docbook b/contrib/bind9/lib/lwres/man/lwres_gai_strerror.docbook index f34836d2a2c4..77a211b57a2c 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gai_strerror.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_gai_strerror.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_gai_strerror.docbook,v 1.3.206.3 2005/05/12 21:36:13 sra Exp $ --> - +<!-- $Id: lwres_gai_strerror.docbook,v 1.4.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> -<refmeta> -<refentrytitle>lwres_gai_strerror</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_gai_strerror</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,133 +45,156 @@ </copyright> </docinfo> -<refnamediv> -<refname>gai_strerror</refname> -<refpurpose>print suitable error string</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_gai_strerror</refname> + <refpurpose>print suitable error string</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> char * <function>gai_strerror</function></funcdef> -<paramdef>int ecode</paramdef> -</funcprototype> + <paramdef>int <parameter>ecode</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> + </refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> -<para> -<function>lwres_gai_strerror()</function> -returns an error message corresponding to an error code returned by -<function>getaddrinfo()</function>. -The following error codes and their meaning are defined in -<filename>include/lwres/netdb.h</filename>. -<variablelist> -<varlistentry><term><errorcode>EAI_ADDRFAMILY</errorcode></term> -<listitem> -<para> -address family for hostname not supported -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_AGAIN</errorcode></term> -<listitem> -<para> -temporary failure in name resolution -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_BADFLAGS</errorcode></term> -<listitem> -<para> -invalid value for -<constant>ai_flags</constant> -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_FAIL</errorcode></term> -<listitem> -<para> -non-recoverable failure in name resolution -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_FAMILY</errorcode></term> -<listitem> -<para> -<constant>ai_family</constant> not supported -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_MEMORY</errorcode></term> -<listitem> -<para> -memory allocation failure -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_NODATA</errorcode></term> -<listitem> -<para> -no address associated with hostname -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_NONAME</errorcode></term> -<listitem> -<para> -hostname or servname not provided, or not known -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_SERVICE</errorcode></term> -<listitem> -<para> -servname not supported for <constant>ai_socktype</constant> -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_SOCKTYPE</errorcode></term> -<listitem> -<para> -<constant>ai_socktype</constant> not supported -</para> -</listitem></varlistentry> -<varlistentry><term><errorcode>EAI_SYSTEM</errorcode></term> -<listitem> -<para> -system error returned in errno -</para> -</listitem></varlistentry> -</variablelist> -The message <errorname>invalid error code</errorname> is returned if -<parameter>ecode</parameter> -is out of range. -</para> -<para> -<constant>ai_flags</constant>, -<constant>ai_family</constant> -and -<constant>ai_socktype</constant> -are elements of the -<type>struct addrinfo</type> -used by -<function>lwres_getaddrinfo()</function>. -</para> -</refsect1> + <refsect1> + <title>DESCRIPTION</title> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <para><function>lwres_gai_strerror()</function> + returns an error message corresponding to an error code returned by + <function>getaddrinfo()</function>. + The following error codes and their meaning are defined in + <filename>include/lwres/netdb.h</filename>. + <variablelist> + <varlistentry> + <term><errorcode>EAI_ADDRFAMILY</errorcode></term> + <listitem> + <para> + address family for hostname not supported + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_AGAIN</errorcode></term> + <listitem> + <para> + temporary failure in name resolution + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_BADFLAGS</errorcode></term> + <listitem> + <para> + invalid value for + <constant>ai_flags</constant> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_FAIL</errorcode></term> + <listitem> + <para> + non-recoverable failure in name resolution + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_FAMILY</errorcode></term> + <listitem> + <para><constant>ai_family</constant> not supported + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_MEMORY</errorcode></term> + <listitem> + <para> + memory allocation failure + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_NODATA</errorcode></term> + <listitem> + <para> + no address associated with hostname + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_NONAME</errorcode></term> + <listitem> + <para> + hostname or servname not provided, or not known + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_SERVICE</errorcode></term> + <listitem> + <para> + servname not supported for <constant>ai_socktype</constant> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_SOCKTYPE</errorcode></term> + <listitem> + <para><constant>ai_socktype</constant> not supported + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EAI_SYSTEM</errorcode></term> + <listitem> + <para> + system error returned in errno + </para> + </listitem> + </varlistentry> + </variablelist> + The message <errorname>invalid error code</errorname> is returned if + <parameter>ecode</parameter> + is out of range. + </para> + <para><constant>ai_flags</constant>, + <constant>ai_family</constant> + and + <constant>ai_socktype</constant> + are elements of the + <type>struct addrinfo</type> + used by + <function>lwres_getaddrinfo()</function>. + </para> + </refsect1> -<citerefentry> -<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>RFC2133</refentrytitle> -</citerefentry>. -</para> -</refsect1> -</refentry> + <citerefentry> + <refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>RFC2133</refentrytitle> + </citerefentry>. + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_gai_strerror.html b/contrib/bind9/lib/lwres/man/lwres_gai_strerror.html index 4b244e3c8c03..967325309509 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gai_strerror.html +++ b/contrib/bind9/lib/lwres/man/lwres_gai_strerror.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,111 +14,111 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_gai_strerror.html,v 1.5.2.1.4.12 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_gai_strerror.html,v 1.6.18.18 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_gai_strerror</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> -<p>gai_strerror — print suitable error string</p> +<p>lwres_gai_strerror — print suitable error string</p> </div> <div class="refsynopsisdiv"> <h2>Synopsis</h2> <div class="funcsynopsis"> <pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre> -<p><code class="funcdef"> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> +<td><code class="funcdef"> char * -<b class="fsfunc">gai_strerror</b>(</code>int ecode<code>)</code>;</p> +<b class="fsfunc">gai_strerror</b>(</code></td> +<td>int </td> +<td> +<var class="pdparam">ecode</var><code>)</code>;</td> +</tr></table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549408"></a><h2>DESCRIPTION</h2> -<p> -<code class="function">lwres_gai_strerror()</code> -returns an error message corresponding to an error code returned by -<code class="function">getaddrinfo()</code>. -The following error codes and their meaning are defined in -<code class="filename">include/lwres/netdb.h</code>. -</p> +<a name="id2543361"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_gai_strerror()</code> + returns an error message corresponding to an error code returned by + <code class="function">getaddrinfo()</code>. + The following error codes and their meaning are defined in + <code class="filename">include/lwres/netdb.h</code>. + </p> <div class="variablelist"><dl> <dt><span class="term"><span class="errorcode">EAI_ADDRFAMILY</span></span></dt> <dd><p> -address family for hostname not supported -</p></dd> + address family for hostname not supported + </p></dd> <dt><span class="term"><span class="errorcode">EAI_AGAIN</span></span></dt> <dd><p> -temporary failure in name resolution -</p></dd> + temporary failure in name resolution + </p></dd> <dt><span class="term"><span class="errorcode">EAI_BADFLAGS</span></span></dt> <dd><p> -invalid value for -<code class="constant">ai_flags</code> -</p></dd> + invalid value for + <code class="constant">ai_flags</code> + </p></dd> <dt><span class="term"><span class="errorcode">EAI_FAIL</span></span></dt> <dd><p> -non-recoverable failure in name resolution -</p></dd> + non-recoverable failure in name resolution + </p></dd> <dt><span class="term"><span class="errorcode">EAI_FAMILY</span></span></dt> -<dd><p> -<code class="constant">ai_family</code> not supported -</p></dd> +<dd><p><code class="constant">ai_family</code> not supported + </p></dd> <dt><span class="term"><span class="errorcode">EAI_MEMORY</span></span></dt> <dd><p> -memory allocation failure -</p></dd> + memory allocation failure + </p></dd> <dt><span class="term"><span class="errorcode">EAI_NODATA</span></span></dt> <dd><p> -no address associated with hostname -</p></dd> + no address associated with hostname + </p></dd> <dt><span class="term"><span class="errorcode">EAI_NONAME</span></span></dt> <dd><p> -hostname or servname not provided, or not known -</p></dd> + hostname or servname not provided, or not known + </p></dd> <dt><span class="term"><span class="errorcode">EAI_SERVICE</span></span></dt> <dd><p> -servname not supported for <code class="constant">ai_socktype</code> -</p></dd> + servname not supported for <code class="constant">ai_socktype</code> + </p></dd> <dt><span class="term"><span class="errorcode">EAI_SOCKTYPE</span></span></dt> -<dd><p> -<code class="constant">ai_socktype</code> not supported -</p></dd> +<dd><p><code class="constant">ai_socktype</code> not supported + </p></dd> <dt><span class="term"><span class="errorcode">EAI_SYSTEM</span></span></dt> <dd><p> -system error returned in errno -</p></dd> + system error returned in errno + </p></dd> </dl></div> <p> -The message <span class="errorname">invalid error code</span> is returned if -<em class="parameter"><code>ecode</code></em> -is out of range. -</p> -<p> -<code class="constant">ai_flags</code>, -<code class="constant">ai_family</code> -and -<code class="constant">ai_socktype</code> -are elements of the -<span class="type">struct addrinfo</span> -used by -<code class="function">lwres_getaddrinfo()</code>. -</p> + The message <span class="errorname">invalid error code</span> is returned if + <em class="parameter"><code>ecode</code></em> + is out of range. + </p> +<p><code class="constant">ai_flags</code>, + <code class="constant">ai_family</code> + and + <code class="constant">ai_socktype</code> + are elements of the + <span class="type">struct addrinfo</span> + used by + <code class="function">lwres_getaddrinfo()</code>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549605"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">strerror</span>(3)</span>, +<a name="id2543576"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">strerror</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">getaddrinfo</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">getaddrinfo</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>. -</p> + <span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.3 b/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.3 index fe52cd52cf2d..9d198d62db09 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.3 +++ b/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001, 2003 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_getaddrinfo.3,v 1.16.2.1.8.7 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_getaddrinfo.3,v 1.20.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_getaddrinfo .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,14 +36,14 @@ lwres_getaddrinfo, lwres_freeaddrinfo \- socket address structure to host and se #include <lwres/netdb.h> .fi .HP 22 -.BI "int lwres_getaddrinfo(const\ char\ *hostname, const\ char\ *servname, const\ struct\ addrinfo\ *hints, struct\ addrinfo\ **res);" +.BI "int lwres_getaddrinfo(const\ char\ *" "hostname" ", const\ char\ *" "servname" ", const\ struct\ addrinfo\ *" "hints" ", struct\ addrinfo\ **" "res" ");" .HP 24 -.BI "void lwres_freeaddrinfo(struct\ addrinfo\ *ai);" +.BI "void lwres_freeaddrinfo(struct\ addrinfo\ *" "ai" ");" .PP If the operating system does not provide a \fBstruct addrinfo\fR, the following structure is used: -.sp -.RS 3n +.PP +.RS 4 .nf struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ @@ -82,14 +82,17 @@ is either a decimal port number or a service name as listed in is an optional pointer to a \fBstruct addrinfo\fR. This structure can be used to provide hints concerning the type of socket that the caller supports or wishes to use. The caller can supply the following structure elements in \fI*hints\fR: -.TP 3n +.PP \fBai_family\fR +.RS 4 The protocol family that should be used. When \fBai_family\fR is set to \fBPF_UNSPEC\fR, it means the caller will accept any protocol family supported by the operating system. -.TP 3n +.RE +.PP \fBai_socktype\fR +.RS 4 denotes the type of socket \(em \fBSOCK_STREAM\fR, \fBSOCK_DGRAM\fR @@ -98,13 +101,17 @@ or \(em that is wanted. When \fBai_socktype\fR is zero the caller will accept any socket type. -.TP 3n +.RE +.PP \fBai_protocol\fR +.RS 4 indicates which transport protocol is wanted: IPPROTO_UDP or IPPROTO_TCP. If \fBai_protocol\fR is zero the caller will accept any protocol. -.TP 3n +.RE +.PP \fBai_flags\fR +.RS 4 Flag bits. If the \fBAI_CANONNAME\fR bit is set, a successful call to @@ -129,11 +136,11 @@ When does not set the \fBAI_PASSIVE\fR bit, the returned socket address structure will be ready for use in a call to -\fBconnect\fR(2 ) +\fBconnect\fR(2) for a connection\-oriented protocol or \fBconnect\fR(2), \fBsendto\fR(2), or -\fBsendmsg\fR(2 ) +\fBsendmsg\fR(2) if a connectionless protocol was chosen. The IP address portion of the socket address structure will be set to the loopback address if \fIhostname\fR is a @@ -150,6 +157,7 @@ is set to it indicates that \fIhostname\fR should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted. +.RE .PP All other elements of the \fBstruct addrinfo\fR @@ -208,7 +216,7 @@ created by a call to .PP \fBlwres_getaddrinfo()\fR returns zero on success or one of the error codes listed in -\fBgai_strerror\fR(3 ) +\fBgai_strerror\fR(3) if an error occurs. If both \fIhostname\fR and @@ -232,4 +240,7 @@ returns \fBsendmsg\fR(2), \fBsocket\fR(2). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001, 2003 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.docbook b/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.docbook index 190721923b11..fa7c086566d4 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_getaddrinfo.docbook,v 1.5.206.4 2005/05/12 21:36:14 sra Exp $ --> - +<!-- $Id: lwres_getaddrinfo.docbook,v 1.7.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_getaddrinfo</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_getaddrinfo</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -46,37 +46,37 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_getaddrinfo</refname> -<refname>lwres_freeaddrinfo</refname> -<refpurpose>socket address structure to host and service name</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_getaddrinfo</refname> + <refname>lwres_freeaddrinfo</refname> + <refpurpose>socket address structure to host and service name</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> int <function>lwres_getaddrinfo</function></funcdef> -<paramdef>const char *hostname</paramdef> -<paramdef>const char *servname</paramdef> -<paramdef>const struct addrinfo *hints</paramdef> -<paramdef>struct addrinfo **res</paramdef> -</funcprototype> + <paramdef>const char *<parameter>hostname</parameter></paramdef> + <paramdef>const char *<parameter>servname</parameter></paramdef> + <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef> + <paramdef>struct addrinfo **<parameter>res</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_freeaddrinfo</function></funcdef> -<paramdef>struct addrinfo *ai</paramdef> -</funcprototype> + <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef> + </funcprototype> </funcsynopsis> -<para> -If the operating system does not provide a -<type>struct addrinfo</type>, -the following structure is used: - -<programlisting> + <para> + If the operating system does not provide a + <type>struct addrinfo</type>, + the following structure is used: + </para> + <para><programlisting> struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ int ai_family; /* PF_xxx */ @@ -88,301 +88,300 @@ struct addrinfo { struct addrinfo *ai_next; /* next structure in linked list */ }; </programlisting> -</para> - -</refsynopsisdiv> - -<refsect1> -<title>DESCRIPTION</title> -<para> -<function>lwres_getaddrinfo()</function> -is used to get a list of IP addresses and port numbers for host -<parameter>hostname</parameter> -and service -<parameter>servname</parameter>. - -The function is the lightweight resolver's implementation of -<function>getaddrinfo()</function> -as defined in RFC2133. -<parameter>hostname</parameter> -and -<parameter>servname</parameter> -are pointers to null-terminated -strings or -<type>NULL</type>. - -<parameter>hostname</parameter> -is either a host name or a numeric host address string: a dotted decimal -IPv4 address or an IPv6 address. -<parameter>servname</parameter> -is either a decimal port number or a service name as listed in -<filename>/etc/services</filename>. -</para> - -<para> -<parameter>hints</parameter> -is an optional pointer to a -<type>struct addrinfo</type>. -This structure can be used to provide hints concerning the type of socket -that the caller supports or wishes to use. -The caller can supply the following structure elements in -<parameter>*hints</parameter>: - -<variablelist> -<varlistentry><term><constant>ai_family</constant></term> -<listitem> -<para>The protocol family that should be used. -When -<constant>ai_family</constant> -is set to -<type>PF_UNSPEC</type>, -it means the caller will accept any protocol family supported by the -operating system. -</para></listitem></varlistentry> -<varlistentry><term><constant>ai_socktype</constant></term> -<listitem> -<para> -denotes the type of socket — -<type>SOCK_STREAM</type>, -<type>SOCK_DGRAM</type> -or -<type>SOCK_RAW</type> -— that is wanted. -When -<constant>ai_socktype</constant> -is zero the caller will accept any socket type. -</para> -</listitem> -</varlistentry> -<varlistentry><term><constant>ai_protocol</constant></term> -<listitem> -<para> -indicates which transport protocol is wanted: IPPROTO_UDP or -IPPROTO_TCP. -If -<constant>ai_protocol</constant> -is zero the caller will accept any protocol. -</para> -</listitem> -</varlistentry> -<varlistentry><term><constant>ai_flags</constant></term> -<listitem> -<para> -Flag bits. -If the -<type>AI_CANONNAME</type> -bit is set, a successful call to -<function>lwres_getaddrinfo()</function> -will return a null-terminated string containing the canonical name -of the specified hostname in -<constant>ai_canonname</constant> -of the first -<type>addrinfo</type> -structure returned. -Setting the -<type>AI_PASSIVE</type> -bit indicates that the returned socket address structure is intended -for used in a call to -<citerefentry> -<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum> -</citerefentry>. - -In this case, if the hostname argument is a -<type>NULL</type> -pointer, then the IP address portion of the socket -address structure will be set to -<type>INADDR_ANY</type> -for an IPv4 address or -<type>IN6ADDR_ANY_INIT</type> -for an IPv6 address. -</para> -<para> -When -<constant>ai_flags</constant> -does not set the -<type>AI_PASSIVE</type> -bit, the returned socket address structure will be ready -for use in a call to -<citerefentry> -<refentrytitle>connect</refentrytitle><manvolnum>2 -</manvolnum> -</citerefentry> -for a connection-oriented protocol or -<citerefentry> -<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum> -</citerefentry>, - -or -<citerefentry> -<refentrytitle>sendmsg</refentrytitle><manvolnum>2 -</manvolnum> -</citerefentry> -if a connectionless protocol was chosen. -The IP address portion of the socket address structure will be -set to the loopback address if -<parameter>hostname</parameter> -is a -<type>NULL</type> -pointer and -<type>AI_PASSIVE</type> -is not set in -<constant>ai_flags</constant>. -</para> -<para> -If -<constant>ai_flags</constant> -is set to -<type>AI_NUMERICHOST</type> -it indicates that -<parameter>hostname</parameter> -should be treated as a numeric string defining an IPv4 or IPv6 address -and no name resolution should be attempted. -</para> -</listitem> -</varlistentry> -</variablelist> -</para> - -<para> -All other elements of the <type>struct addrinfo</type> passed -via <parameter>hints</parameter> must be zero. -</para> - -<para> -A <parameter>hints</parameter> of <type>NULL</type> is treated as if -the caller provided a <type>struct addrinfo</type> initialized to zero -with <constant>ai_family</constant>set to -<constant>PF_UNSPEC</constant>. -</para> - -<para> -After a successful call to -<function>lwres_getaddrinfo()</function>, -<parameter>*res</parameter> -is a pointer to a linked list of one or more -<type>addrinfo</type> -structures. -Each -<type>struct addrinfo</type> -in this list cn be processed by following -the -<constant>ai_next</constant> -pointer, until a -<type>NULL</type> -pointer is encountered. -The three members -<constant>ai_family</constant>, -<constant>ai_socktype</constant>, -and -<constant>ai_protocol</constant> -in each -returned -<type>addrinfo</type> -structure contain the corresponding arguments for a call to -<citerefentry> -<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum> -</citerefentry>. -For each -<type>addrinfo</type> -structure in the list, the -<constant>ai_addr</constant> -member points to a filled-in socket address structure of length -<constant>ai_addrlen</constant>. -</para> - -<para> -All of the information returned by -<function>lwres_getaddrinfo()</function> -is dynamically allocated: the addrinfo structures, and the socket -address structures and canonical host name strings pointed to by the -<constant>addrinfo</constant>structures. -Memory allocated for the dynamically allocated structures created by -a successful call to -<function>lwres_getaddrinfo()</function> -is released by -<function>lwres_freeaddrinfo()</function>. -<parameter>ai</parameter> -is a pointer to a -<type>struct addrinfo</type> -created by a call to -<function>lwres_getaddrinfo()</function>. -</para> - -</refsect1> - -<refsect1> -<title>RETURN VALUES</title> -<para> -<function>lwres_getaddrinfo()</function> -returns zero on success or one of the error codes listed in -<citerefentry> -<refentrytitle>gai_strerror</refentrytitle><manvolnum>3 -</manvolnum> -</citerefentry> -if an error occurs. -If both -<parameter>hostname</parameter> -and -<parameter>servname</parameter> -are -<type>NULL</type> -<function>lwres_getaddrinfo()</function> -returns -<errorcode>EAI_NONAME</errorcode>. - -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>RFC2133</refentrytitle> -</citerefentry>, - -<citerefentry> -<refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum> -</citerefentry>. -</para> - -</refsect1> -</refentry> + </para> + + </refsynopsisdiv> + + <refsect1> + <title>DESCRIPTION</title> + + <para><function>lwres_getaddrinfo()</function> + is used to get a list of IP addresses and port numbers for host + <parameter>hostname</parameter> and service + <parameter>servname</parameter>. + + The function is the lightweight resolver's implementation of + <function>getaddrinfo()</function> as defined in RFC2133. + <parameter>hostname</parameter> and + <parameter>servname</parameter> are pointers to null-terminated + strings or <type>NULL</type>. + + <parameter>hostname</parameter> is either a host name or a + numeric host address string: a dotted decimal IPv4 address or an + IPv6 address. <parameter>servname</parameter> is either a + decimal port number or a service name as listed in + <filename>/etc/services</filename>. + </para> + + <para><parameter>hints</parameter> + is an optional pointer to a + <type>struct addrinfo</type>. + This structure can be used to provide hints concerning the type of + socket + that the caller supports or wishes to use. + The caller can supply the following structure elements in + <parameter>*hints</parameter>: + + <variablelist> + <varlistentry> + <term><constant>ai_family</constant></term> + <listitem> + <para> + The protocol family that should be used. + When + <constant>ai_family</constant> + is set to + <type>PF_UNSPEC</type>, + it means the caller will accept any protocol family supported by + the + operating system. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>ai_socktype</constant></term> + <listitem> + <para> + denotes the type of socket — + <type>SOCK_STREAM</type>, + <type>SOCK_DGRAM</type> + or + <type>SOCK_RAW</type> + — that is wanted. + When + <constant>ai_socktype</constant> + is zero the caller will accept any socket type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>ai_protocol</constant></term> + <listitem> + <para> + indicates which transport protocol is wanted: IPPROTO_UDP or + IPPROTO_TCP. + If + <constant>ai_protocol</constant> + is zero the caller will accept any protocol. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>ai_flags</constant></term> + <listitem> + <para> + Flag bits. + If the + <type>AI_CANONNAME</type> + bit is set, a successful call to + <function>lwres_getaddrinfo()</function> + will return a null-terminated string containing the canonical + name + of the specified hostname in + <constant>ai_canonname</constant> + of the first + <type>addrinfo</type> + structure returned. + Setting the + <type>AI_PASSIVE</type> + bit indicates that the returned socket address structure is + intended + for used in a call to + <citerefentry> + <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>. + + In this case, if the hostname argument is a + <type>NULL</type> + pointer, then the IP address portion of the socket + address structure will be set to + <type>INADDR_ANY</type> + for an IPv4 address or + <type>IN6ADDR_ANY_INIT</type> + for an IPv6 address. + </para> + <para> + When + <constant>ai_flags</constant> + does not set the + <type>AI_PASSIVE</type> + bit, the returned socket address structure will be ready + for use in a call to + <citerefentry> + <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> + </citerefentry> + for a connection-oriented protocol or + <citerefentry> + <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>, + + or + <citerefentry> + <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum> + </citerefentry> + if a connectionless protocol was chosen. + The IP address portion of the socket address structure will be + set to the loopback address if + <parameter>hostname</parameter> + is a + <type>NULL</type> + pointer and + <type>AI_PASSIVE</type> + is not set in + <constant>ai_flags</constant>. + </para> + <para> + If + <constant>ai_flags</constant> + is set to + <type>AI_NUMERICHOST</type> + it indicates that + <parameter>hostname</parameter> + should be treated as a numeric string defining an IPv4 or IPv6 + address + and no name resolution should be attempted. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + All other elements of the <type>struct addrinfo</type> passed + via <parameter>hints</parameter> must be zero. + </para> + + <para> + A <parameter>hints</parameter> of <type>NULL</type> is + treated as if + the caller provided a <type>struct addrinfo</type> initialized to zero + with <constant>ai_family</constant>set to + <constant>PF_UNSPEC</constant>. + </para> + + <para> + After a successful call to + <function>lwres_getaddrinfo()</function>, + <parameter>*res</parameter> + is a pointer to a linked list of one or more + <type>addrinfo</type> + structures. + Each + <type>struct addrinfo</type> + in this list cn be processed by following + the + <constant>ai_next</constant> + pointer, until a + <type>NULL</type> + pointer is encountered. + The three members + <constant>ai_family</constant>, + <constant>ai_socktype</constant>, + and + <constant>ai_protocol</constant> + in each + returned + <type>addrinfo</type> + structure contain the corresponding arguments for a call to + <citerefentry> + <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>. + For each + <type>addrinfo</type> + structure in the list, the + <constant>ai_addr</constant> + member points to a filled-in socket address structure of length + <constant>ai_addrlen</constant>. + </para> + + <para> + All of the information returned by + <function>lwres_getaddrinfo()</function> + is dynamically allocated: the addrinfo structures, and the socket + address structures and canonical host name strings pointed to by the + <constant>addrinfo</constant>structures. + Memory allocated for the dynamically allocated structures created by + a successful call to + <function>lwres_getaddrinfo()</function> + is released by + <function>lwres_freeaddrinfo()</function>. + <parameter>ai</parameter> + is a pointer to a + <type>struct addrinfo</type> + created by a call to + <function>lwres_getaddrinfo()</function>. + </para> + + </refsect1> + + <refsect1> + <title>RETURN VALUES</title> + + <para><function>lwres_getaddrinfo()</function> + returns zero on success or one of the error codes listed in + <citerefentry> + <refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + if an error occurs. If both <parameter>hostname</parameter> and + <parameter>servname</parameter> are <type>NULL</type> + <function>lwres_getaddrinfo()</function> returns + <errorcode>EAI_NONAME</errorcode>. + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>RFC2133</refentrytitle> + </citerefentry>, + + <citerefentry> + <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum> + </citerefentry>. + </para> + + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.html b/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.html index 375c319c9c69..d2dcdd95a609 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.html +++ b/contrib/bind9/lib/lwres/man/lwres_getaddrinfo.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_getaddrinfo.html,v 1.8.2.1.4.12 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_getaddrinfo.html,v 1.10.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_getaddrinfo</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_getaddrinfo, lwres_freeaddrinfo — socket address structure to host and service name</p> @@ -36,54 +36,43 @@ <td><code class="funcdef"> int <b class="fsfunc">lwres_getaddrinfo</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">hostname</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">servname</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>const struct addrinfo * </td> +<td> +<var class="pdparam">hints</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>struct addrinfo ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">res</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_freeaddrinfo</b>(</code></td> -<td> </td> +<td>struct addrinfo * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">ai</var><code>)</code>;</td> +</tr></table> </div> <p> -If the operating system does not provide a -<span class="type">struct addrinfo</span>, -the following structure is used: - -</p> + If the operating system does not provide a + <span class="type">struct addrinfo</span>, + the following structure is used: + </p> <pre class="programlisting"> struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ @@ -97,250 +86,237 @@ struct addrinfo { }; </pre> <p> -</p> + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549448"></a><h2>DESCRIPTION</h2> -<p> -<code class="function">lwres_getaddrinfo()</code> -is used to get a list of IP addresses and port numbers for host -<em class="parameter"><code>hostname</code></em> -and service -<em class="parameter"><code>servname</code></em>. +<a name="id2543412"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_getaddrinfo()</code> + is used to get a list of IP addresses and port numbers for host + <em class="parameter"><code>hostname</code></em> and service + <em class="parameter"><code>servname</code></em>. -The function is the lightweight resolver's implementation of -<code class="function">getaddrinfo()</code> -as defined in RFC2133. -<em class="parameter"><code>hostname</code></em> -and -<em class="parameter"><code>servname</code></em> -are pointers to null-terminated -strings or -<span class="type">NULL</span>. + The function is the lightweight resolver's implementation of + <code class="function">getaddrinfo()</code> as defined in RFC2133. + <em class="parameter"><code>hostname</code></em> and + <em class="parameter"><code>servname</code></em> are pointers to null-terminated + strings or <span class="type">NULL</span>. -<em class="parameter"><code>hostname</code></em> -is either a host name or a numeric host address string: a dotted decimal -IPv4 address or an IPv6 address. -<em class="parameter"><code>servname</code></em> -is either a decimal port number or a service name as listed in -<code class="filename">/etc/services</code>. -</p> -<p> -<em class="parameter"><code>hints</code></em> -is an optional pointer to a -<span class="type">struct addrinfo</span>. -This structure can be used to provide hints concerning the type of socket -that the caller supports or wishes to use. -The caller can supply the following structure elements in -<em class="parameter"><code>*hints</code></em>: + <em class="parameter"><code>hostname</code></em> is either a host name or a + numeric host address string: a dotted decimal IPv4 address or an + IPv6 address. <em class="parameter"><code>servname</code></em> is either a + decimal port number or a service name as listed in + <code class="filename">/etc/services</code>. + </p> +<p><em class="parameter"><code>hints</code></em> + is an optional pointer to a + <span class="type">struct addrinfo</span>. + This structure can be used to provide hints concerning the type of + socket + that the caller supports or wishes to use. + The caller can supply the following structure elements in + <em class="parameter"><code>*hints</code></em>: -</p> + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">ai_family</code></span></dt> -<dd><p>The protocol family that should be used. -When -<code class="constant">ai_family</code> -is set to -<span class="type">PF_UNSPEC</span>, -it means the caller will accept any protocol family supported by the -operating system. -</p></dd> +<dd><p> + The protocol family that should be used. + When + <code class="constant">ai_family</code> + is set to + <span class="type">PF_UNSPEC</span>, + it means the caller will accept any protocol family supported by + the + operating system. + </p></dd> <dt><span class="term"><code class="constant">ai_socktype</code></span></dt> <dd><p> -denotes the type of socket — -<span class="type">SOCK_STREAM</span>, -<span class="type">SOCK_DGRAM</span> -or -<span class="type">SOCK_RAW</span> -— that is wanted. -When -<code class="constant">ai_socktype</code> -is zero the caller will accept any socket type. -</p></dd> + denotes the type of socket — + <span class="type">SOCK_STREAM</span>, + <span class="type">SOCK_DGRAM</span> + or + <span class="type">SOCK_RAW</span> + — that is wanted. + When + <code class="constant">ai_socktype</code> + is zero the caller will accept any socket type. + </p></dd> <dt><span class="term"><code class="constant">ai_protocol</code></span></dt> <dd><p> -indicates which transport protocol is wanted: IPPROTO_UDP or -IPPROTO_TCP. -If -<code class="constant">ai_protocol</code> -is zero the caller will accept any protocol. -</p></dd> + indicates which transport protocol is wanted: IPPROTO_UDP or + IPPROTO_TCP. + If + <code class="constant">ai_protocol</code> + is zero the caller will accept any protocol. + </p></dd> <dt><span class="term"><code class="constant">ai_flags</code></span></dt> <dd> <p> -Flag bits. -If the -<span class="type">AI_CANONNAME</span> -bit is set, a successful call to -<code class="function">lwres_getaddrinfo()</code> -will return a null-terminated string containing the canonical name -of the specified hostname in -<code class="constant">ai_canonname</code> -of the first -<span class="type">addrinfo</span> -structure returned. -Setting the -<span class="type">AI_PASSIVE</span> -bit indicates that the returned socket address structure is intended -for used in a call to -<span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>. + Flag bits. + If the + <span class="type">AI_CANONNAME</span> + bit is set, a successful call to + <code class="function">lwres_getaddrinfo()</code> + will return a null-terminated string containing the canonical + name + of the specified hostname in + <code class="constant">ai_canonname</code> + of the first + <span class="type">addrinfo</span> + structure returned. + Setting the + <span class="type">AI_PASSIVE</span> + bit indicates that the returned socket address structure is + intended + for used in a call to + <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>. -In this case, if the hostname argument is a -<span class="type">NULL</span> -pointer, then the IP address portion of the socket -address structure will be set to -<span class="type">INADDR_ANY</span> -for an IPv4 address or -<span class="type">IN6ADDR_ANY_INIT</span> -for an IPv6 address. -</p> + In this case, if the hostname argument is a + <span class="type">NULL</span> + pointer, then the IP address portion of the socket + address structure will be set to + <span class="type">INADDR_ANY</span> + for an IPv4 address or + <span class="type">IN6ADDR_ANY_INIT</span> + for an IPv6 address. + </p> <p> -When -<code class="constant">ai_flags</code> -does not set the -<span class="type">AI_PASSIVE</span> -bit, the returned socket address structure will be ready -for use in a call to -<span class="citerefentry"><span class="refentrytitle">connect</span>(2 -)</span> -for a connection-oriented protocol or -<span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>, + When + <code class="constant">ai_flags</code> + does not set the + <span class="type">AI_PASSIVE</span> + bit, the returned socket address structure will be ready + for use in a call to + <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span> + for a connection-oriented protocol or + <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>, -<span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>, + <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>, -or -<span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2 -)</span> -if a connectionless protocol was chosen. -The IP address portion of the socket address structure will be -set to the loopback address if -<em class="parameter"><code>hostname</code></em> -is a -<span class="type">NULL</span> -pointer and -<span class="type">AI_PASSIVE</span> -is not set in -<code class="constant">ai_flags</code>. -</p> + or + <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span> + if a connectionless protocol was chosen. + The IP address portion of the socket address structure will be + set to the loopback address if + <em class="parameter"><code>hostname</code></em> + is a + <span class="type">NULL</span> + pointer and + <span class="type">AI_PASSIVE</span> + is not set in + <code class="constant">ai_flags</code>. + </p> <p> -If -<code class="constant">ai_flags</code> -is set to -<span class="type">AI_NUMERICHOST</span> -it indicates that -<em class="parameter"><code>hostname</code></em> -should be treated as a numeric string defining an IPv4 or IPv6 address -and no name resolution should be attempted. -</p> + If + <code class="constant">ai_flags</code> + is set to + <span class="type">AI_NUMERICHOST</span> + it indicates that + <em class="parameter"><code>hostname</code></em> + should be treated as a numeric string defining an IPv4 or IPv6 + address + and no name resolution should be attempted. + </p> </dd> </dl></div> <p> -</p> + </p> <p> -All other elements of the <span class="type">struct addrinfo</span> passed -via <em class="parameter"><code>hints</code></em> must be zero. -</p> + All other elements of the <span class="type">struct addrinfo</span> passed + via <em class="parameter"><code>hints</code></em> must be zero. + </p> <p> -A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is treated as if -the caller provided a <span class="type">struct addrinfo</span> initialized to zero -with <code class="constant">ai_family</code>set to -<code class="constant">PF_UNSPEC</code>. -</p> + A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is + treated as if + the caller provided a <span class="type">struct addrinfo</span> initialized to zero + with <code class="constant">ai_family</code>set to + <code class="constant">PF_UNSPEC</code>. + </p> <p> -After a successful call to -<code class="function">lwres_getaddrinfo()</code>, -<em class="parameter"><code>*res</code></em> -is a pointer to a linked list of one or more -<span class="type">addrinfo</span> -structures. -Each -<span class="type">struct addrinfo</span> -in this list cn be processed by following -the -<code class="constant">ai_next</code> -pointer, until a -<span class="type">NULL</span> -pointer is encountered. -The three members -<code class="constant">ai_family</code>, -<code class="constant">ai_socktype</code>, -and -<code class="constant">ai_protocol</code> -in each -returned -<span class="type">addrinfo</span> -structure contain the corresponding arguments for a call to -<span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>. -For each -<span class="type">addrinfo</span> -structure in the list, the -<code class="constant">ai_addr</code> -member points to a filled-in socket address structure of length -<code class="constant">ai_addrlen</code>. -</p> + After a successful call to + <code class="function">lwres_getaddrinfo()</code>, + <em class="parameter"><code>*res</code></em> + is a pointer to a linked list of one or more + <span class="type">addrinfo</span> + structures. + Each + <span class="type">struct addrinfo</span> + in this list cn be processed by following + the + <code class="constant">ai_next</code> + pointer, until a + <span class="type">NULL</span> + pointer is encountered. + The three members + <code class="constant">ai_family</code>, + <code class="constant">ai_socktype</code>, + and + <code class="constant">ai_protocol</code> + in each + returned + <span class="type">addrinfo</span> + structure contain the corresponding arguments for a call to + <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>. + For each + <span class="type">addrinfo</span> + structure in the list, the + <code class="constant">ai_addr</code> + member points to a filled-in socket address structure of length + <code class="constant">ai_addrlen</code>. + </p> <p> -All of the information returned by -<code class="function">lwres_getaddrinfo()</code> -is dynamically allocated: the addrinfo structures, and the socket -address structures and canonical host name strings pointed to by the -<code class="constant">addrinfo</code>structures. -Memory allocated for the dynamically allocated structures created by -a successful call to -<code class="function">lwres_getaddrinfo()</code> -is released by -<code class="function">lwres_freeaddrinfo()</code>. -<em class="parameter"><code>ai</code></em> -is a pointer to a -<span class="type">struct addrinfo</span> -created by a call to -<code class="function">lwres_getaddrinfo()</code>. -</p> + All of the information returned by + <code class="function">lwres_getaddrinfo()</code> + is dynamically allocated: the addrinfo structures, and the socket + address structures and canonical host name strings pointed to by the + <code class="constant">addrinfo</code>structures. + Memory allocated for the dynamically allocated structures created by + a successful call to + <code class="function">lwres_getaddrinfo()</code> + is released by + <code class="function">lwres_freeaddrinfo()</code>. + <em class="parameter"><code>ai</code></em> + is a pointer to a + <span class="type">struct addrinfo</span> + created by a call to + <code class="function">lwres_getaddrinfo()</code>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549874"></a><h2>RETURN VALUES</h2> -<p> -<code class="function">lwres_getaddrinfo()</code> -returns zero on success or one of the error codes listed in -<span class="citerefentry"><span class="refentrytitle">gai_strerror</span>(3 -)</span> -if an error occurs. -If both -<em class="parameter"><code>hostname</code></em> -and -<em class="parameter"><code>servname</code></em> -are -<span class="type">NULL</span> -<code class="function">lwres_getaddrinfo()</code> -returns -<span class="errorcode">EAI_NONAME</span>. - -</p> +<a name="id2543789"></a><h2>RETURN VALUES</h2> +<p><code class="function">lwres_getaddrinfo()</code> + returns zero on success or one of the error codes listed in + <span class="citerefentry"><span class="refentrytitle">gai_strerror</span>(3)</span> + if an error occurs. If both <em class="parameter"><code>hostname</code></em> and + <em class="parameter"><code>servname</code></em> are <span class="type">NULL</span> + <code class="function">lwres_getaddrinfo()</code> returns + <span class="errorcode">EAI_NONAME</span>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549912"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, +<a name="id2543827"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_gai_strerror</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_gai_strerror</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>, + <span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>, -<span class="citerefentry"><span class="refentrytitle">getservbyname</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">getservbyname</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>, + <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>, -<span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>, + <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>, -<span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>, + <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>, -<span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>, + <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>, -<span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>. -</p> + <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_gethostent.3 b/contrib/bind9/lib/lwres/man/lwres_gethostent.3 index 6fe933d753ba..e6fbcd7c04cb 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gethostent.3 +++ b/contrib/bind9/lib/lwres/man/lwres_gethostent.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_gethostent.3,v 1.16.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_gethostent.3,v 1.19.18.10 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_gethostent .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,37 +36,37 @@ lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent #include <lwres/netdb.h> .fi .HP 37 -.BI "struct hostent * lwres_gethostbyname(const\ char\ *name);" +.BI "struct hostent * lwres_gethostbyname(const\ char\ *" "name" ");" .HP 38 -.BI "struct hostent * lwres_gethostbyname2(const\ char\ *name, int\ af);" +.BI "struct hostent * lwres_gethostbyname2(const\ char\ *" "name" ", int\ " "af" ");" .HP 37 -.BI "struct hostent * lwres_gethostbyaddr(const\ char\ *addr, int\ len, int\ type);" +.BI "struct hostent * lwres_gethostbyaddr(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ");" .HP 34 .BI "struct hostent * lwres_gethostent(void);" .HP 22 -.BI "void lwres_sethostent(int\ stayopen);" +.BI "void lwres_sethostent(int\ " "stayopen" ");" .HP 22 .BI "void lwres_endhostent(void);" .HP 39 -.BI "struct hostent * lwres_gethostbyname_r(const\ char\ *name, struct\ hostent\ *resbuf, char\ *buf, int\ buflen, int\ *error);" +.BI "struct hostent * lwres_gethostbyname_r(const\ char\ *" "name" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");" .HP 39 -.BI "struct hostent * lwres_gethostbyaddr_r(const\ char\ *addr, int\ len, int\ type, struct\ hostent\ *resbuf, char\ *buf, int\ buflen, int\ *error);" +.BI "struct hostent * lwres_gethostbyaddr_r(const\ char\ *" "addr" ", int\ " "len" ", int\ " "type" ", struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");" .HP 36 -.BI "struct hostent * lwres_gethostent_r(struct\ hostent\ *resbuf, char\ *buf, int\ buflen, int\ *error);" +.BI "struct hostent * lwres_gethostent_r(struct\ hostent\ *" "resbuf" ", char\ *" "buf" ", int\ " "buflen" ", int\ *" "error" ");" .HP 24 -.BI "void lwres_sethostent_r(int\ stayopen);" +.BI "void lwres_sethostent_r(int\ " "stayopen" ");" .HP 24 .BI "void lwres_endhostent_r(void);" .SH "DESCRIPTION" .PP These functions provide hostname\-to\-address and address\-to\-hostname lookups by means of the lightweight resolver. They are similar to the standard -\fBgethostent\fR(3 ) +\fBgethostent\fR(3) functions provided by most operating systems. They use a \fBstruct hostent\fR which is usually defined in \fI<namedb.h>\fR. -.sp -.RS 3n +.PP +.RS 4 .nf struct hostent { char *h_name; /* official name of host */ @@ -81,26 +81,36 @@ struct hostent { .sp .PP The members of this structure are: -.TP 3n +.PP \fBh_name\fR +.RS 4 The official (canonical) name of the host. -.TP 3n +.RE +.PP \fBh_aliases\fR +.RS 4 A NULL\-terminated array of alternate names (nicknames) for the host. -.TP 3n +.RE +.PP \fBh_addrtype\fR +.RS 4 The type of address being returned \(em \fBPF_INET\fR or \fBPF_INET6\fR. -.TP 3n +.RE +.PP \fBh_length\fR +.RS 4 The length of the address in bytes. -.TP 3n +.RE +.PP \fBh_addr_list\fR +.RS 4 A \fBNULL\fR terminated array of network addresses for the host. Host addresses are returned in network byte order. +.RE .PP For backward compatibility with very old software, \fBh_addr\fR @@ -158,8 +168,7 @@ is a thread\-safe function for forward lookups. If an error occurs, an error cod is a pointer to a \fBstruct hostent\fR which is initialised by a successful call to -\fBlwres_gethostbyname_r()\fR -. +\fBlwres_gethostbyname_r()\fR. \fIbuf\fR is a buffer of length \fIlen\fR @@ -222,20 +231,28 @@ return NULL to indicate an error. In this case the global variable \fBlwres_h_errno\fR will contain one of the following error codes defined in \fI<lwres/netdb.h>\fR: -.TP 3n +.PP \fBHOST_NOT_FOUND\fR +.RS 4 The host or address was not found. -.TP 3n +.RE +.PP \fBTRY_AGAIN\fR +.RS 4 A recoverable error occurred, e.g., a timeout. Retrying the lookup may succeed. -.TP 3n +.RE +.PP \fBNO_RECOVERY\fR +.RS 4 A non\-recoverable error occurred. -.TP 3n +.RE +.PP \fBNO_DATA\fR +.RS 4 The name exists, but has no address information associated with it (or vice versa in the case of a reverse lookup). The code NO_ADDRESS is accepted as a synonym for NO_DATA for backwards compatibility. +.RE .PP -\fBlwres_hstrerror\fR(3 ) +\fBlwres_hstrerror\fR(3) translates these error codes to suitable error messages. .PP \fBlwres_gethostent()\fR @@ -274,7 +291,7 @@ to .PP \fBgethostent\fR(3), \fBlwres_getipnode\fR(3), -\fBlwres_hstrerror\fR(3 ) +\fBlwres_hstrerror\fR(3) .SH "BUGS" .PP \fBlwres_gethostbyname()\fR, @@ -292,4 +309,7 @@ The resolver daemon does not currently support any non\-DNS name services such a or \fBNIS\fR, consequently the above functions don't, either. .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_gethostent.docbook b/contrib/bind9/lib/lwres/man/lwres_gethostent.docbook index 9f92d3b3134c..41a3bc37f2be 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gethostent.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_gethostent.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_gethostent.docbook,v 1.5.206.3 2005/05/13 01:22:36 marka Exp $ --> - +<!-- $Id: lwres_gethostent.docbook,v 1.6.18.4 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_gethostent</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_gethostent</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -44,125 +44,124 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_gethostbyname</refname> -<refname>lwres_gethostbyname2</refname> -<refname>lwres_gethostbyaddr</refname> -<refname>lwres_gethostent</refname> -<refname>lwres_sethostent</refname> -<refname>lwres_endhostent</refname> -<refname>lwres_gethostbyname_r</refname> -<refname>lwres_gethostbyaddr_r</refname> -<refname>lwres_gethostent_r</refname> -<refname>lwres_sethostent_r</refname> -<refname>lwres_endhostent_r</refname> -<refpurpose>lightweight resolver get network host entry</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_gethostbyname</refname> + <refname>lwres_gethostbyname2</refname> + <refname>lwres_gethostbyaddr</refname> + <refname>lwres_gethostent</refname> + <refname>lwres_sethostent</refname> + <refname>lwres_endhostent</refname> + <refname>lwres_gethostbyname_r</refname> + <refname>lwres_gethostbyaddr_r</refname> + <refname>lwres_gethostent_r</refname> + <refname>lwres_sethostent_r</refname> + <refname>lwres_endhostent_r</refname> + <refpurpose>lightweight resolver get network host entry</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> struct hostent * <function>lwres_gethostbyname</function></funcdef> -<paramdef>const char *name</paramdef> -</funcprototype> + <paramdef>const char *<parameter>name</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> struct hostent * <function>lwres_gethostbyname2</function></funcdef> -<paramdef>const char *name</paramdef> -<paramdef>int af</paramdef> -</funcprototype> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>int <parameter>af</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> struct hostent * <function>lwres_gethostbyaddr</function></funcdef> -<paramdef>const char *addr</paramdef> -<paramdef>int len</paramdef> -<paramdef>int type</paramdef> -</funcprototype> + <paramdef>const char *<parameter>addr</parameter></paramdef> + <paramdef>int <parameter>len</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> struct hostent * <function>lwres_gethostent</function></funcdef> -<paramdef>void</paramdef> -</funcprototype> + <paramdef>void</paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_sethostent</function></funcdef> -<paramdef>int stayopen</paramdef> -</funcprototype> + <paramdef>int <parameter>stayopen</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_endhostent</function></funcdef> -<paramdef>void</paramdef> -</funcprototype> + <paramdef>void</paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> struct hostent * <function>lwres_gethostbyname_r</function></funcdef> -<paramdef>const char *name</paramdef> -<paramdef>struct hostent *resbuf</paramdef> -<paramdef>char *buf</paramdef> -<paramdef>int buflen</paramdef> -<paramdef>int *error</paramdef> -</funcprototype> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>buflen</parameter></paramdef> + <paramdef>int *<parameter>error</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> struct hostent * <function>lwres_gethostbyaddr_r</function></funcdef> -<paramdef>const char *addr</paramdef> -<paramdef>int len</paramdef> -<paramdef>int type</paramdef> -<paramdef>struct hostent *resbuf</paramdef> -<paramdef>char *buf</paramdef> -<paramdef>int buflen</paramdef> -<paramdef>int *error</paramdef> -</funcprototype> + <paramdef>const char *<parameter>addr</parameter></paramdef> + <paramdef>int <parameter>len</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>buflen</parameter></paramdef> + <paramdef>int *<parameter>error</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> struct hostent * <function>lwres_gethostent_r</function></funcdef> -<paramdef>struct hostent *resbuf</paramdef> -<paramdef>char *buf</paramdef> -<paramdef>int buflen</paramdef> -<paramdef>int *error</paramdef> -</funcprototype> + <paramdef>struct hostent *<parameter>resbuf</parameter></paramdef> + <paramdef>char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>buflen</parameter></paramdef> + <paramdef>int *<parameter>error</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_sethostent_r</function></funcdef> -<paramdef>int stayopen</paramdef> -</funcprototype> + <paramdef>int <parameter>stayopen</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_endhostent_r</function></funcdef> -<paramdef>void</paramdef> -</funcprototype> + <paramdef>void</paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> - -<refsect1> -<title>DESCRIPTION</title> -<para> -These functions provide hostname-to-address and -address-to-hostname lookups by means of the lightweight resolver. -They are similar to the standard -<citerefentry> -<refentrytitle>gethostent</refentrytitle><manvolnum>3 -</manvolnum> -</citerefentry> -functions provided by most operating systems. -They use a -<type>struct hostent</type> -which is usually defined in -<filename><namedb.h></filename>. + </refsynopsisdiv> -<programlisting> + <refsect1> + <title>DESCRIPTION</title> + <para> + These functions provide hostname-to-address and + address-to-hostname lookups by means of the lightweight resolver. + They are similar to the standard + <citerefentry> + <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + functions provided by most operating systems. + They use a + <type>struct hostent</type> + which is usually defined in + <filename><namedb.h></filename>. + </para> + <para><programlisting> struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ @@ -172,250 +171,269 @@ struct hostent { }; #define h_addr h_addr_list[0] /* address, for backward compatibility */ </programlisting> -</para> -<para> -The members of this structure are: -<variablelist> -<varlistentry><term><constant>h_name</constant></term> -<listitem> -<para> -The official (canonical) name of the host. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>h_aliases</constant></term> -<listitem> -<para> -A NULL-terminated array of alternate names (nicknames) for the host. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>h_addrtype</constant></term> -<listitem> -<para> -The type of address being returned — -<type>PF_INET</type> -or -<type>PF_INET6</type>. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>h_length</constant></term> -<listitem> -<para> -The length of the address in bytes. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>h_addr_list</constant></term> -<listitem> -<para> -A <type>NULL</type> -terminated array of network addresses for the host. -Host addresses are returned in network byte order. -</para> -</listitem></varlistentry> -</variablelist> -</para> -<para> -For backward compatibility with very old software, -<constant>h_addr</constant> -is the first address in -<constant>h_addr_list.</constant> -</para> -<para> -<function>lwres_gethostent()</function>, -<function>lwres_sethostent()</function>, -<function>lwres_endhostent()</function>, -<function>lwres_gethostent_r()</function>, -<function>lwres_sethostent_r()</function> -and -<function>lwres_endhostent_r()</function> -provide iteration over the known host entries on systems that -provide such functionality through facilities like -<filename>/etc/hosts</filename> -or NIS. The lightweight resolver does not currently implement -these functions; it only provides them as stub functions that always -return failure. -</para> + </para> + <para> + The members of this structure are: + <variablelist> + <varlistentry> + <term><constant>h_name</constant></term> + <listitem> + <para> + The official (canonical) name of the host. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_aliases</constant></term> + <listitem> + <para> + A NULL-terminated array of alternate names (nicknames) for the + host. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_addrtype</constant></term> + <listitem> + <para> + The type of address being returned — + <type>PF_INET</type> + or + <type>PF_INET6</type>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_length</constant></term> + <listitem> + <para> + The length of the address in bytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_addr_list</constant></term> + <listitem> + <para> + A <type>NULL</type> + terminated array of network addresses for the host. + Host addresses are returned in network byte order. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + For backward compatibility with very old software, + <constant>h_addr</constant> + is the first address in + <constant>h_addr_list.</constant> + </para> + <para><function>lwres_gethostent()</function>, + <function>lwres_sethostent()</function>, + <function>lwres_endhostent()</function>, + <function>lwres_gethostent_r()</function>, + <function>lwres_sethostent_r()</function> + and + <function>lwres_endhostent_r()</function> + provide iteration over the known host entries on systems that + provide such functionality through facilities like + <filename>/etc/hosts</filename> + or NIS. The lightweight resolver does not currently implement + these functions; it only provides them as stub functions that always + return failure. + </para> -<para> -<function>lwres_gethostbyname()</function> and -<function>lwres_gethostbyname2()</function> look up the hostname -<parameter>name</parameter>. -<function>lwres_gethostbyname()</function> always looks for an IPv4 -address while <function>lwres_gethostbyname2()</function> looks for an -address of protocol family <parameter>af</parameter>: either -<type>PF_INET</type> or <type>PF_INET6</type> — IPv4 or IPV6 -addresses respectively. Successful calls of the functions return a -<type>struct hostent</type>for the name that was looked up. -<type>NULL</type> is returned if the lookups by -<function>lwres_gethostbyname()</function> or -<function>lwres_gethostbyname2()</function> fail. -</para> + <para><function>lwres_gethostbyname()</function> + and <function>lwres_gethostbyname2()</function> look up the + hostname <parameter>name</parameter>. + <function>lwres_gethostbyname()</function> always looks for an + IPv4 address while <function>lwres_gethostbyname2()</function> + looks for an address of protocol family + <parameter>af</parameter>: either <type>PF_INET</type> or + <type>PF_INET6</type> — IPv4 or IPV6 addresses + respectively. Successful calls of the functions return a + <type>struct hostent</type>for the name that was looked up. + <type>NULL</type> is returned if the lookups by + <function>lwres_gethostbyname()</function> or + <function>lwres_gethostbyname2()</function> fail. + </para> -<para> -Reverse lookups of addresses are performed by -<function>lwres_gethostbyaddr()</function>. -<parameter>addr</parameter> is an address of length -<parameter>len</parameter> bytes and protocol family -<parameter>type</parameter> — <type>PF_INET</type> or -<type>PF_INET6</type>. -<function>lwres_gethostbyname_r()</function> is a thread-safe function -for forward lookups. If an error occurs, an error code is returned in -<parameter>*error</parameter>. -<parameter>resbuf</parameter> is a pointer to a <type>struct -hostent</type> which is initialised by a successful call to -<function>lwres_gethostbyname_r()</function> . -<parameter>buf</parameter> is a buffer of length -<parameter>len</parameter> bytes which is used to store the -<constant>h_name</constant>, <constant>h_aliases</constant>, and -<constant>h_addr_list</constant> elements of the <type>struct -hostent</type> returned in <parameter>resbuf</parameter>. -Successful calls to <function>lwres_gethostbyname_r()</function> -return <parameter>resbuf</parameter>, -which is a pointer to the <type>struct hostent</type> it created. -</para> + <para> + Reverse lookups of addresses are performed by + <function>lwres_gethostbyaddr()</function>. + <parameter>addr</parameter> is an address of length + <parameter>len</parameter> bytes and protocol family + <parameter>type</parameter> — <type>PF_INET</type> or + <type>PF_INET6</type>. + <function>lwres_gethostbyname_r()</function> is a + thread-safe function + for forward lookups. If an error occurs, an error code is returned in + <parameter>*error</parameter>. + <parameter>resbuf</parameter> is a pointer to a + <type>struct hostent</type> which is initialised by a successful call to + <function>lwres_gethostbyname_r()</function>. + <parameter>buf</parameter> is a buffer of length + <parameter>len</parameter> bytes which is used to store the + <constant>h_name</constant>, <constant>h_aliases</constant>, and + <constant>h_addr_list</constant> elements of the + <type>struct hostent</type> returned in <parameter>resbuf</parameter>. + Successful calls to <function>lwres_gethostbyname_r()</function> + return <parameter>resbuf</parameter>, + which is a pointer to the <type>struct hostent</type> it created. + </para> -<para> -<function>lwres_gethostbyaddr_r()</function> is a thread-safe function -that performs a reverse lookup of address <parameter>addr</parameter> -which is <parameter>len</parameter> bytes long and is of protocol -family <parameter>type</parameter> — <type>PF_INET</type> or -<type>PF_INET6</type>. If an error occurs, the error code is returned -in <parameter>*error</parameter>. The other function parameters are -identical to those in <function>lwres_gethostbyname_r()</function>. -<parameter>resbuf</parameter> is a pointer to a <type>struct -hostent</type> which is initialised by a successful call to -<function>lwres_gethostbyaddr_r()</function>. -<parameter>buf</parameter> is a buffer of length -<parameter>len</parameter> bytes which is used to store the -<constant>h_name</constant>, <constant>h_aliases</constant>, and -<constant>h_addr_list</constant> elements of the <type>struct -hostent</type> returned in <parameter>resbuf</parameter>. Successful -calls to <function>lwres_gethostbyaddr_r()</function> return -<parameter>resbuf</parameter>, which is a pointer to the -<function>struct hostent()</function> it created. -</para> + <para><function>lwres_gethostbyaddr_r()</function> + is a thread-safe function + that performs a reverse lookup of address <parameter>addr</parameter> + which is <parameter>len</parameter> bytes long and is of + protocol + family <parameter>type</parameter> — <type>PF_INET</type> or + <type>PF_INET6</type>. If an error occurs, the error code is returned + in <parameter>*error</parameter>. The other function + parameters are + identical to those in <function>lwres_gethostbyname_r()</function>. + <parameter>resbuf</parameter> is a pointer to a + <type>struct hostent</type> which is initialised by a successful call to + <function>lwres_gethostbyaddr_r()</function>. + <parameter>buf</parameter> is a buffer of length + <parameter>len</parameter> bytes which is used to store the + <constant>h_name</constant>, <constant>h_aliases</constant>, and + <constant>h_addr_list</constant> elements of the + <type>struct hostent</type> returned in <parameter>resbuf</parameter>. + Successful calls to <function>lwres_gethostbyaddr_r()</function> return + <parameter>resbuf</parameter>, which is a pointer to the + <function>struct hostent()</function> it created. + </para> -</refsect1> + </refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> -The functions -<function>lwres_gethostbyname()</function>, -<function>lwres_gethostbyname2()</function>, -<function>lwres_gethostbyaddr()</function>, -and -<function>lwres_gethostent()</function> -return NULL to indicate an error. In this case the global variable -<type>lwres_h_errno</type> -will contain one of the following error codes defined in -<filename><lwres/netdb.h></filename>: + <refsect1> + <title>RETURN VALUES</title> + <para> + The functions + <function>lwres_gethostbyname()</function>, + <function>lwres_gethostbyname2()</function>, + <function>lwres_gethostbyaddr()</function>, + and + <function>lwres_gethostent()</function> + return NULL to indicate an error. In this case the global variable + <type>lwres_h_errno</type> + will contain one of the following error codes defined in + <filename><lwres/netdb.h></filename>: -<variablelist> -<varlistentry><term><constant>HOST_NOT_FOUND</constant></term> -<listitem> -<para> -The host or address was not found. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>TRY_AGAIN</constant></term> -<listitem> -<para> -A recoverable error occurred, e.g., a timeout. -Retrying the lookup may succeed. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>NO_RECOVERY</constant></term> -<listitem> -<para> -A non-recoverable error occurred. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>NO_DATA</constant></term> -<listitem> -<para> -The name exists, but has no address information -associated with it (or vice versa in the case -of a reverse lookup). The code NO_ADDRESS -is accepted as a synonym for NO_DATA for backwards -compatibility. -</para> -</listitem></varlistentry> -</variablelist> -</para> + <variablelist> + <varlistentry> + <term><constant>HOST_NOT_FOUND</constant></term> + <listitem> + <para> + The host or address was not found. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>TRY_AGAIN</constant></term> + <listitem> + <para> + A recoverable error occurred, e.g., a timeout. + Retrying the lookup may succeed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>NO_RECOVERY</constant></term> + <listitem> + <para> + A non-recoverable error occurred. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>NO_DATA</constant></term> + <listitem> + <para> + The name exists, but has no address information + associated with it (or vice versa in the case + of a reverse lookup). The code NO_ADDRESS + is accepted as a synonym for NO_DATA for backwards + compatibility. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> -<para> -<citerefentry> -<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3 -</manvolnum> -</citerefentry> -translates these error codes to suitable error messages. -</para> + <para><citerefentry> + <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + translates these error codes to suitable error messages. + </para> -<para> -<function>lwres_gethostent()</function> -and -<function>lwres_gethostent_r()</function> -always return -<type>NULL</type>. -</para> + <para><function>lwres_gethostent()</function> + and <function>lwres_gethostent_r()</function> + always return <type>NULL</type>. + </para> -<para> -Successful calls to <function>lwres_gethostbyname_r()</function> and -<function>lwres_gethostbyaddr_r()</function> return -<parameter>resbuf</parameter>, a pointer to the <type>struct -hostent</type> that was initialised by these functions. They return -<type>NULL</type> if the lookups fail or if <parameter>buf</parameter> -was too small to hold the list of addresses and names referenced by -the <constant>h_name</constant>, <constant>h_aliases</constant>, and -<constant>h_addr_list</constant> elements of the <type>struct -hostent</type>. If <parameter>buf</parameter> was too small, both -<function>lwres_gethostbyname_r()</function> and -<function>lwres_gethostbyaddr_r()</function> set the global variable -<type>errno</type> to <errorcode>ERANGE</errorcode>. -</para> + <para> + Successful calls to <function>lwres_gethostbyname_r()</function> and + <function>lwres_gethostbyaddr_r()</function> return + <parameter>resbuf</parameter>, a pointer to the + <type>struct hostent</type> that was initialised by these functions. They return + <type>NULL</type> if the lookups fail or if <parameter>buf</parameter> + was too small to hold the list of addresses and names referenced by + the <constant>h_name</constant>, <constant>h_aliases</constant>, and + <constant>h_addr_list</constant> elements of the + <type>struct hostent</type>. + If <parameter>buf</parameter> was too small, both + <function>lwres_gethostbyname_r()</function> and + <function>lwres_gethostbyaddr_r()</function> set the global + variable + <type>errno</type> to <errorcode>ERANGE</errorcode>. + </para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>gethostent</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_getipnode</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3 -</manvolnum> -</citerefentry> -</para> -</refsect1> + <citerefentry> + <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + </para> + </refsect1> -<refsect1> -<title>BUGS</title> -<para> -<function>lwres_gethostbyname()</function>, -<function>lwres_gethostbyname2()</function>, -<function>lwres_gethostbyaddr()</function> -and -<function>lwres_endhostent()</function> -are not thread safe; they return pointers to static data and -provide error codes through a global variable. -Thread-safe versions for name and address lookup are provided by -<function>lwres_gethostbyname_r()</function>, -and -<function>lwres_gethostbyaddr_r()</function> -respectively. -</para> -<para> -The resolver daemon does not currently support any non-DNS -name services such as -<filename>/etc/hosts</filename> -or -<type>NIS</type>, -consequently the above functions don't, either. -</para> -</refsect1> -</refentry> + <refsect1> + <title>BUGS</title> + <para><function>lwres_gethostbyname()</function>, + <function>lwres_gethostbyname2()</function>, + <function>lwres_gethostbyaddr()</function> + and + <function>lwres_endhostent()</function> + are not thread safe; they return pointers to static data and + provide error codes through a global variable. + Thread-safe versions for name and address lookup are provided by + <function>lwres_gethostbyname_r()</function>, + and + <function>lwres_gethostbyaddr_r()</function> + respectively. + </para> + <para> + The resolver daemon does not currently support any non-DNS + name services such as + <filename>/etc/hosts</filename> + or + <type>NIS</type>, + consequently the above functions don't, either. + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_gethostent.html b/contrib/bind9/lib/lwres/man/lwres_gethostent.html index fefc67b88631..0b7ba4423e32 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gethostent.html +++ b/contrib/bind9/lib/lwres/man/lwres_gethostent.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_gethostent.html,v 1.8.2.1.4.10 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_gethostent.html,v 1.9.18.15 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_gethostent</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr, lwres_gethostent, lwres_sethostent, lwres_endhostent, lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r, lwres_sethostent_r, lwres_endhostent_r — lightweight resolver get network host entry</p> @@ -31,40 +31,28 @@ <h2>Synopsis</h2> <div class="funcsynopsis"> <pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> <td><code class="funcdef"> struct hostent * <b class="fsfunc">lwres_gethostbyname</b>(</code></td> -<td> </td> +<td>const char * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">name</var><code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> struct hostent * <b class="fsfunc">lwres_gethostbyname2</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">name</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>int </td> <td> -<code>)</code>;</td> +<var class="pdparam">af</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -72,68 +60,79 @@ struct hostent * <td><code class="funcdef"> struct hostent * <b class="fsfunc">lwres_gethostbyaddr</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">addr</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">len</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>int </td> <td> -<code>)</code>;</td> +<var class="pdparam">type</var><code>)</code>;</td> </tr> </table> -<p><code class="funcdef"> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> +<td><code class="funcdef"> struct hostent * -<b class="fsfunc">lwres_gethostent</b>(</code>void<code>)</code>;</p> -<p><code class="funcdef"> +<b class="fsfunc">lwres_gethostent</b>(</code></td> +<td> </td> +<td> +<code>)</code>;</td> +</tr></table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> +<td><code class="funcdef"> void -<b class="fsfunc">lwres_sethostent</b>(</code>int stayopen<code>)</code>;</p> -<p><code class="funcdef"> +<b class="fsfunc">lwres_sethostent</b>(</code></td> +<td>int </td> +<td> +<var class="pdparam">stayopen</var><code>)</code>;</td> +</tr></table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> +<td><code class="funcdef"> void -<b class="fsfunc">lwres_endhostent</b>(</code>void<code>)</code>;</p> +<b class="fsfunc">lwres_endhostent</b>(</code></td> +<td> </td> +<td> +<code>)</code>;</td> +</tr></table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> <tr> <td><code class="funcdef"> struct hostent * <b class="fsfunc">lwres_gethostbyname_r</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">name</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>struct hostent * </td> +<td> +<var class="pdparam">resbuf</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>char * </td> +<td> +<var class="pdparam">buf</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">buflen</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>int * </td> <td> -<code>)</code>;</td> +<var class="pdparam">error</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -141,44 +140,45 @@ struct hostent * <td><code class="funcdef"> struct hostent * <b class="fsfunc">lwres_gethostbyaddr_r</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">addr</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">len</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">type</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>struct hostent * </td> +<td> +<var class="pdparam">resbuf</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>char * </td> +<td> +<var class="pdparam">buf</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">buflen</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>int * </td> <td> -<code>)</code>;</td> +<var class="pdparam">error</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -186,54 +186,60 @@ struct hostent * <td><code class="funcdef"> struct hostent * <b class="fsfunc">lwres_gethostent_r</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>struct hostent * </td> +<td> +<var class="pdparam">resbuf</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>char * </td> +<td> +<var class="pdparam">buf</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">buflen</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>int * </td> <td> -<code>)</code>;</td> +<var class="pdparam">error</var><code>)</code>;</td> </tr> </table> -<p><code class="funcdef"> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> +<td><code class="funcdef"> void -<b class="fsfunc">lwres_sethostent_r</b>(</code>int stayopen<code>)</code>;</p> -<p><code class="funcdef"> +<b class="fsfunc">lwres_sethostent_r</b>(</code></td> +<td>int </td> +<td> +<var class="pdparam">stayopen</var><code>)</code>;</td> +</tr></table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> +<td><code class="funcdef"> void -<b class="fsfunc">lwres_endhostent_r</b>(</code>void<code>)</code>;</p> +<b class="fsfunc">lwres_endhostent_r</b>(</code></td> +<td> </td> +<td> +<code>)</code>;</td> +</tr></table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549606"></a><h2>DESCRIPTION</h2> +<a name="id2543608"></a><h2>DESCRIPTION</h2> <p> -These functions provide hostname-to-address and -address-to-hostname lookups by means of the lightweight resolver. -They are similar to the standard -<span class="citerefentry"><span class="refentrytitle">gethostent</span>(3 -)</span> -functions provided by most operating systems. -They use a -<span class="type">struct hostent</span> -which is usually defined in -<code class="filename"><namedb.h></code>. - -</p> + These functions provide hostname-to-address and + address-to-hostname lookups by means of the lightweight resolver. + They are similar to the standard + <span class="citerefentry"><span class="refentrytitle">gethostent</span>(3)</span> + functions provided by most operating systems. + They use a + <span class="type">struct hostent</span> + which is usually defined in + <code class="filename"><namedb.h></code>. + </p> <pre class="programlisting"> struct hostent { char *h_name; /* official name of host */ @@ -245,219 +251,216 @@ struct hostent { #define h_addr h_addr_list[0] /* address, for backward compatibility */ </pre> <p> -</p> + </p> <p> -The members of this structure are: -</p> + The members of this structure are: + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">h_name</code></span></dt> <dd><p> -The official (canonical) name of the host. -</p></dd> + The official (canonical) name of the host. + </p></dd> <dt><span class="term"><code class="constant">h_aliases</code></span></dt> <dd><p> -A NULL-terminated array of alternate names (nicknames) for the host. -</p></dd> + A NULL-terminated array of alternate names (nicknames) for the + host. + </p></dd> <dt><span class="term"><code class="constant">h_addrtype</code></span></dt> <dd><p> -The type of address being returned — -<span class="type">PF_INET</span> -or -<span class="type">PF_INET6</span>. -</p></dd> + The type of address being returned — + <span class="type">PF_INET</span> + or + <span class="type">PF_INET6</span>. + </p></dd> <dt><span class="term"><code class="constant">h_length</code></span></dt> <dd><p> -The length of the address in bytes. -</p></dd> + The length of the address in bytes. + </p></dd> <dt><span class="term"><code class="constant">h_addr_list</code></span></dt> <dd><p> -A <span class="type">NULL</span> -terminated array of network addresses for the host. -Host addresses are returned in network byte order. -</p></dd> + A <span class="type">NULL</span> + terminated array of network addresses for the host. + Host addresses are returned in network byte order. + </p></dd> </dl></div> <p> -</p> -<p> -For backward compatibility with very old software, -<code class="constant">h_addr</code> -is the first address in -<code class="constant">h_addr_list.</code> -</p> + </p> <p> -<code class="function">lwres_gethostent()</code>, -<code class="function">lwres_sethostent()</code>, -<code class="function">lwres_endhostent()</code>, -<code class="function">lwres_gethostent_r()</code>, -<code class="function">lwres_sethostent_r()</code> -and -<code class="function">lwres_endhostent_r()</code> -provide iteration over the known host entries on systems that -provide such functionality through facilities like -<code class="filename">/etc/hosts</code> -or NIS. The lightweight resolver does not currently implement -these functions; it only provides them as stub functions that always -return failure. -</p> + For backward compatibility with very old software, + <code class="constant">h_addr</code> + is the first address in + <code class="constant">h_addr_list.</code> + </p> +<p><code class="function">lwres_gethostent()</code>, + <code class="function">lwres_sethostent()</code>, + <code class="function">lwres_endhostent()</code>, + <code class="function">lwres_gethostent_r()</code>, + <code class="function">lwres_sethostent_r()</code> + and + <code class="function">lwres_endhostent_r()</code> + provide iteration over the known host entries on systems that + provide such functionality through facilities like + <code class="filename">/etc/hosts</code> + or NIS. The lightweight resolver does not currently implement + these functions; it only provides them as stub functions that always + return failure. + </p> +<p><code class="function">lwres_gethostbyname()</code> + and <code class="function">lwres_gethostbyname2()</code> look up the + hostname <em class="parameter"><code>name</code></em>. + <code class="function">lwres_gethostbyname()</code> always looks for an + IPv4 address while <code class="function">lwres_gethostbyname2()</code> + looks for an address of protocol family + <em class="parameter"><code>af</code></em>: either <span class="type">PF_INET</span> or + <span class="type">PF_INET6</span> — IPv4 or IPV6 addresses + respectively. Successful calls of the functions return a + <span class="type">struct hostent</span>for the name that was looked up. + <span class="type">NULL</span> is returned if the lookups by + <code class="function">lwres_gethostbyname()</code> or + <code class="function">lwres_gethostbyname2()</code> fail. + </p> <p> -<code class="function">lwres_gethostbyname()</code> and -<code class="function">lwres_gethostbyname2()</code> look up the hostname -<em class="parameter"><code>name</code></em>. -<code class="function">lwres_gethostbyname()</code> always looks for an IPv4 -address while <code class="function">lwres_gethostbyname2()</code> looks for an -address of protocol family <em class="parameter"><code>af</code></em>: either -<span class="type">PF_INET</span> or <span class="type">PF_INET6</span> — IPv4 or IPV6 -addresses respectively. Successful calls of the functions return a -<span class="type">struct hostent</span>for the name that was looked up. -<span class="type">NULL</span> is returned if the lookups by -<code class="function">lwres_gethostbyname()</code> or -<code class="function">lwres_gethostbyname2()</code> fail. -</p> -<p> -Reverse lookups of addresses are performed by -<code class="function">lwres_gethostbyaddr()</code>. -<em class="parameter"><code>addr</code></em> is an address of length -<em class="parameter"><code>len</code></em> bytes and protocol family -<em class="parameter"><code>type</code></em> — <span class="type">PF_INET</span> or -<span class="type">PF_INET6</span>. -<code class="function">lwres_gethostbyname_r()</code> is a thread-safe function -for forward lookups. If an error occurs, an error code is returned in -<em class="parameter"><code>*error</code></em>. -<em class="parameter"><code>resbuf</code></em> is a pointer to a <span class="type">struct -hostent</span> which is initialised by a successful call to -<code class="function">lwres_gethostbyname_r()</code> . -<em class="parameter"><code>buf</code></em> is a buffer of length -<em class="parameter"><code>len</code></em> bytes which is used to store the -<code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and -<code class="constant">h_addr_list</code> elements of the <span class="type">struct -hostent</span> returned in <em class="parameter"><code>resbuf</code></em>. -Successful calls to <code class="function">lwres_gethostbyname_r()</code> -return <em class="parameter"><code>resbuf</code></em>, -which is a pointer to the <span class="type">struct hostent</span> it created. -</p> -<p> -<code class="function">lwres_gethostbyaddr_r()</code> is a thread-safe function -that performs a reverse lookup of address <em class="parameter"><code>addr</code></em> -which is <em class="parameter"><code>len</code></em> bytes long and is of protocol -family <em class="parameter"><code>type</code></em> — <span class="type">PF_INET</span> or -<span class="type">PF_INET6</span>. If an error occurs, the error code is returned -in <em class="parameter"><code>*error</code></em>. The other function parameters are -identical to those in <code class="function">lwres_gethostbyname_r()</code>. -<em class="parameter"><code>resbuf</code></em> is a pointer to a <span class="type">struct -hostent</span> which is initialised by a successful call to -<code class="function">lwres_gethostbyaddr_r()</code>. -<em class="parameter"><code>buf</code></em> is a buffer of length -<em class="parameter"><code>len</code></em> bytes which is used to store the -<code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and -<code class="constant">h_addr_list</code> elements of the <span class="type">struct -hostent</span> returned in <em class="parameter"><code>resbuf</code></em>. Successful -calls to <code class="function">lwres_gethostbyaddr_r()</code> return -<em class="parameter"><code>resbuf</code></em>, which is a pointer to the -<code class="function">struct hostent()</code> it created. -</p> + Reverse lookups of addresses are performed by + <code class="function">lwres_gethostbyaddr()</code>. + <em class="parameter"><code>addr</code></em> is an address of length + <em class="parameter"><code>len</code></em> bytes and protocol family + <em class="parameter"><code>type</code></em> — <span class="type">PF_INET</span> or + <span class="type">PF_INET6</span>. + <code class="function">lwres_gethostbyname_r()</code> is a + thread-safe function + for forward lookups. If an error occurs, an error code is returned in + <em class="parameter"><code>*error</code></em>. + <em class="parameter"><code>resbuf</code></em> is a pointer to a + <span class="type">struct hostent</span> which is initialised by a successful call to + <code class="function">lwres_gethostbyname_r()</code>. + <em class="parameter"><code>buf</code></em> is a buffer of length + <em class="parameter"><code>len</code></em> bytes which is used to store the + <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and + <code class="constant">h_addr_list</code> elements of the + <span class="type">struct hostent</span> returned in <em class="parameter"><code>resbuf</code></em>. + Successful calls to <code class="function">lwres_gethostbyname_r()</code> + return <em class="parameter"><code>resbuf</code></em>, + which is a pointer to the <span class="type">struct hostent</span> it created. + </p> +<p><code class="function">lwres_gethostbyaddr_r()</code> + is a thread-safe function + that performs a reverse lookup of address <em class="parameter"><code>addr</code></em> + which is <em class="parameter"><code>len</code></em> bytes long and is of + protocol + family <em class="parameter"><code>type</code></em> — <span class="type">PF_INET</span> or + <span class="type">PF_INET6</span>. If an error occurs, the error code is returned + in <em class="parameter"><code>*error</code></em>. The other function + parameters are + identical to those in <code class="function">lwres_gethostbyname_r()</code>. + <em class="parameter"><code>resbuf</code></em> is a pointer to a + <span class="type">struct hostent</span> which is initialised by a successful call to + <code class="function">lwres_gethostbyaddr_r()</code>. + <em class="parameter"><code>buf</code></em> is a buffer of length + <em class="parameter"><code>len</code></em> bytes which is used to store the + <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and + <code class="constant">h_addr_list</code> elements of the + <span class="type">struct hostent</span> returned in <em class="parameter"><code>resbuf</code></em>. + Successful calls to <code class="function">lwres_gethostbyaddr_r()</code> return + <em class="parameter"><code>resbuf</code></em>, which is a pointer to the + <code class="function">struct hostent()</code> it created. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2550013"></a><h2>RETURN VALUES</h2> +<a name="id2543959"></a><h2>RETURN VALUES</h2> <p> -The functions -<code class="function">lwres_gethostbyname()</code>, -<code class="function">lwres_gethostbyname2()</code>, -<code class="function">lwres_gethostbyaddr()</code>, -and -<code class="function">lwres_gethostent()</code> -return NULL to indicate an error. In this case the global variable -<span class="type">lwres_h_errno</span> -will contain one of the following error codes defined in -<code class="filename"><lwres/netdb.h></code>: + The functions + <code class="function">lwres_gethostbyname()</code>, + <code class="function">lwres_gethostbyname2()</code>, + <code class="function">lwres_gethostbyaddr()</code>, + and + <code class="function">lwres_gethostent()</code> + return NULL to indicate an error. In this case the global variable + <span class="type">lwres_h_errno</span> + will contain one of the following error codes defined in + <code class="filename"><lwres/netdb.h></code>: -</p> + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">HOST_NOT_FOUND</code></span></dt> <dd><p> -The host or address was not found. -</p></dd> + The host or address was not found. + </p></dd> <dt><span class="term"><code class="constant">TRY_AGAIN</code></span></dt> <dd><p> -A recoverable error occurred, e.g., a timeout. -Retrying the lookup may succeed. -</p></dd> + A recoverable error occurred, e.g., a timeout. + Retrying the lookup may succeed. + </p></dd> <dt><span class="term"><code class="constant">NO_RECOVERY</code></span></dt> <dd><p> -A non-recoverable error occurred. -</p></dd> + A non-recoverable error occurred. + </p></dd> <dt><span class="term"><code class="constant">NO_DATA</code></span></dt> <dd><p> -The name exists, but has no address information -associated with it (or vice versa in the case -of a reverse lookup). The code NO_ADDRESS -is accepted as a synonym for NO_DATA for backwards -compatibility. -</p></dd> + The name exists, but has no address information + associated with it (or vice versa in the case + of a reverse lookup). The code NO_ADDRESS + is accepted as a synonym for NO_DATA for backwards + compatibility. + </p></dd> </dl></div> <p> -</p> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3 -)</span> -translates these error codes to suitable error messages. -</p> + </p> +<p><span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span> + translates these error codes to suitable error messages. + </p> +<p><code class="function">lwres_gethostent()</code> + and <code class="function">lwres_gethostent_r()</code> + always return <span class="type">NULL</span>. + </p> <p> -<code class="function">lwres_gethostent()</code> -and -<code class="function">lwres_gethostent_r()</code> -always return -<span class="type">NULL</span>. -</p> -<p> -Successful calls to <code class="function">lwres_gethostbyname_r()</code> and -<code class="function">lwres_gethostbyaddr_r()</code> return -<em class="parameter"><code>resbuf</code></em>, a pointer to the <span class="type">struct -hostent</span> that was initialised by these functions. They return -<span class="type">NULL</span> if the lookups fail or if <em class="parameter"><code>buf</code></em> -was too small to hold the list of addresses and names referenced by -the <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and -<code class="constant">h_addr_list</code> elements of the <span class="type">struct -hostent</span>. If <em class="parameter"><code>buf</code></em> was too small, both -<code class="function">lwres_gethostbyname_r()</code> and -<code class="function">lwres_gethostbyaddr_r()</code> set the global variable -<span class="type">errno</span> to <span class="errorcode">ERANGE</span>. -</p> + Successful calls to <code class="function">lwres_gethostbyname_r()</code> and + <code class="function">lwres_gethostbyaddr_r()</code> return + <em class="parameter"><code>resbuf</code></em>, a pointer to the + <span class="type">struct hostent</span> that was initialised by these functions. They return + <span class="type">NULL</span> if the lookups fail or if <em class="parameter"><code>buf</code></em> + was too small to hold the list of addresses and names referenced by + the <code class="constant">h_name</code>, <code class="constant">h_aliases</code>, and + <code class="constant">h_addr_list</code> elements of the + <span class="type">struct hostent</span>. + If <em class="parameter"><code>buf</code></em> was too small, both + <code class="function">lwres_gethostbyname_r()</code> and + <code class="function">lwres_gethostbyaddr_r()</code> set the global + variable + <span class="type">errno</span> to <span class="errorcode">ERANGE</span>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2550173"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">gethostent</span>(3)</span>, +<a name="id2544193"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">gethostent</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_getipnode</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3 -)</span> -</p> + <span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span> + </p> </div> <div class="refsect1" lang="en"> -<a name="id2550209"></a><h2>BUGS</h2> -<p> -<code class="function">lwres_gethostbyname()</code>, -<code class="function">lwres_gethostbyname2()</code>, -<code class="function">lwres_gethostbyaddr()</code> -and -<code class="function">lwres_endhostent()</code> -are not thread safe; they return pointers to static data and -provide error codes through a global variable. -Thread-safe versions for name and address lookup are provided by -<code class="function">lwres_gethostbyname_r()</code>, -and -<code class="function">lwres_gethostbyaddr_r()</code> -respectively. -</p> +<a name="id2544227"></a><h2>BUGS</h2> +<p><code class="function">lwres_gethostbyname()</code>, + <code class="function">lwres_gethostbyname2()</code>, + <code class="function">lwres_gethostbyaddr()</code> + and + <code class="function">lwres_endhostent()</code> + are not thread safe; they return pointers to static data and + provide error codes through a global variable. + Thread-safe versions for name and address lookup are provided by + <code class="function">lwres_gethostbyname_r()</code>, + and + <code class="function">lwres_gethostbyaddr_r()</code> + respectively. + </p> <p> -The resolver daemon does not currently support any non-DNS -name services such as -<code class="filename">/etc/hosts</code> -or -<span class="type">NIS</span>, -consequently the above functions don't, either. -</p> + The resolver daemon does not currently support any non-DNS + name services such as + <code class="filename">/etc/hosts</code> + or + <span class="type">NIS</span>, + consequently the above functions don't, either. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_getipnode.3 b/contrib/bind9/lib/lwres/man/lwres_getipnode.3 index f7ab62b581b2..9c9f374b8f13 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getipnode.3 +++ b/contrib/bind9/lib/lwres/man/lwres_getipnode.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001, 2003 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_getipnode.3,v 1.13.2.2.4.7 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_getipnode.3,v 1.17.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_getipnode .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,11 +36,11 @@ lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent \- lightweight r #include <lwres/netdb.h> .fi .HP 39 -.BI "struct hostent * lwres_getipnodebyname(const\ char\ *name, int\ af, int\ flags, int\ *error_num);" +.BI "struct hostent * lwres_getipnodebyname(const\ char\ *" "name" ", int\ " "af" ", int\ " "flags" ", int\ *" "error_num" ");" .HP 39 -.BI "struct hostent * lwres_getipnodebyaddr(const\ void\ *src, size_t\ len, int\ af, int\ *error_num);" +.BI "struct hostent * lwres_getipnodebyaddr(const\ void\ *" "src" ", size_t\ " "len" ", int\ " "af" ", int\ *" "error_num" ");" .HP 23 -.BI "void lwres_freehostent(struct\ hostent\ *he);" +.BI "void lwres_freehostent(struct\ hostent\ *" "he" ");" .SH "DESCRIPTION" .PP These functions perform thread safe, protocol independent nodename\-to\-address and address\-to\-nodename translation as defined in RFC2553. @@ -49,8 +49,8 @@ They use a \fBstruct hostent\fR which is defined in \fInamedb.h\fR: -.sp -.RS 3n +.PP +.RS 4 .nf struct hostent { char *h_name; /* official name of host */ @@ -65,26 +65,36 @@ struct hostent { .sp .PP The members of this structure are: -.TP 3n +.PP \fBh_name\fR +.RS 4 The official (canonical) name of the host. -.TP 3n +.RE +.PP \fBh_aliases\fR +.RS 4 A NULL\-terminated array of alternate names (nicknames) for the host. -.TP 3n +.RE +.PP \fBh_addrtype\fR +.RS 4 The type of address being returned \- usually \fBPF_INET\fR or \fBPF_INET6\fR. -.TP 3n +.RE +.PP \fBh_length\fR +.RS 4 The length of the address in bytes. -.TP 3n +.RE +.PP \fBh_addr_list\fR +.RS 4 A \fBNULL\fR terminated array of network addresses for the host. Host addresses are returned in network byte order. +.RE .PP \fBlwres_getipnodebyname()\fR looks up addresses of protocol family @@ -93,26 +103,34 @@ for the hostname \fIname\fR. The \fIflags\fR parameter contains ORed flag bits to specify the types of addresses that are searched for, and the types of addresses that are returned. The flag bits are: -.TP 3n +.PP \fBAI_V4MAPPED\fR +.RS 4 This is used with an \fIaf\fR of AF_INET6, and causes IPv4 addresses to be returned as IPv4\-mapped IPv6 addresses. -.TP 3n +.RE +.PP \fBAI_ALL\fR +.RS 4 This is used with an \fIaf\fR of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned. If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped IPv6 addresses. -.TP 3n +.RE +.PP \fBAI_ADDRCONFIG\fR +.RS 4 Only return an IPv6 or IPv4 address if here is an active network interface of that type. This is not currently implemented in the BIND 9 lightweight resolver, and the flag is ignored. -.TP 3n +.RE +.PP \fBAI_DEFAULT\fR +.RS 4 This default sets the \fBAI_V4MAPPED\fR and \fBAI_ADDRCONFIG\fR flag bits. +.RE .PP \fBlwres_getipnodebyaddr()\fR performs a reverse lookup of address @@ -150,20 +168,28 @@ to an appropriate error code and the function returns a \fBNULL\fR pointer. The error codes and their meanings are defined in \fI<lwres/netdb.h>\fR: -.TP 3n +.PP \fBHOST_NOT_FOUND\fR +.RS 4 No such host is known. -.TP 3n +.RE +.PP \fBNO_ADDRESS\fR +.RS 4 The server recognised the request and the name but no address is available. Another type of request to the name server for the domain might return an answer. -.TP 3n +.RE +.PP \fBTRY_AGAIN\fR +.RS 4 A temporary and possibly transient error occurred, such as a failure of a server to respond. The request may succeed if retried. -.TP 3n +.RE +.PP \fBNO_RECOVERY\fR +.RS 4 An unexpected failure occurred, and retrying the request is pointless. +.RE .PP -\fBlwres_hstrerror\fR(3 ) +\fBlwres_hstrerror\fR(3) translates these error codes to suitable error messages. .SH "SEE ALSO" .PP @@ -174,4 +200,7 @@ translates these error codes to suitable error messages. \fBlwres_getnameinfo\fR(3), \fBlwres_hstrerror\fR(3). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001, 2003 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_getipnode.docbook b/contrib/bind9/lib/lwres/man/lwres_getipnode.docbook index 94de72c0fe70..6bd480377bb1 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getipnode.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_getipnode.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_getipnode.docbook,v 1.4.2.2.4.3 2005/05/12 21:36:14 sra Exp $ --> - +<!-- $Id: lwres_getipnode.docbook,v 1.6.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_getipnode</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_getipnode</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -46,57 +46,58 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_getipnodebyname</refname> -<refname>lwres_getipnodebyaddr</refname> -<refname>lwres_freehostent</refname> -<refpurpose>lightweight resolver nodename / address translation API</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_getipnodebyname</refname> + <refname>lwres_getipnodebyaddr</refname> + <refname>lwres_freehostent</refname> + <refpurpose>lightweight resolver nodename / address translation API</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> struct hostent * <function>lwres_getipnodebyname</function></funcdef> -<paramdef>const char *name</paramdef> -<paramdef>int af</paramdef> -<paramdef>int flags</paramdef> -<paramdef>int *error_num</paramdef> -</funcprototype> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>int <parameter>af</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + <paramdef>int *<parameter>error_num</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> struct hostent * <function>lwres_getipnodebyaddr</function></funcdef> -<paramdef>const void *src</paramdef> -<paramdef>size_t len</paramdef> -<paramdef>int af</paramdef> -<paramdef>int *error_num</paramdef> -</funcprototype> + <paramdef>const void *<parameter>src</parameter></paramdef> + <paramdef>size_t <parameter>len</parameter></paramdef> + <paramdef>int <parameter>af</parameter></paramdef> + <paramdef>int *<parameter>error_num</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_freehostent</function></funcdef> -<paramdef>struct hostent *he</paramdef> -</funcprototype> + <paramdef>struct hostent *<parameter>he</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> + </refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> + <refsect1> + <title>DESCRIPTION</title> -<para> -These functions perform thread safe, protocol independent -nodename-to-address and address-to-nodename -translation as defined in RFC2553. -</para> + <para> + These functions perform thread safe, protocol independent + nodename-to-address and address-to-nodename + translation as defined in RFC2553. + </para> -<para> -They use a -<type>struct hostent</type> -which is defined in -<filename>namedb.h</filename>: -<programlisting> + <para> + They use a + <type>struct hostent</type> + which is defined in + <filename>namedb.h</filename>: + </para> + <para><programlisting> struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ @@ -106,218 +107,225 @@ struct hostent { }; #define h_addr h_addr_list[0] /* address, for backward compatibility */ </programlisting> -</para> - -<para> -The members of this structure are: -<variablelist> -<varlistentry><term><constant>h_name</constant></term> -<listitem> -<para> -The official (canonical) name of the host. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>h_aliases</constant></term> -<listitem> -<para> -A NULL-terminated array of alternate names (nicknames) for the host. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>h_addrtype</constant></term> -<listitem> -<para> -The type of address being returned - usually -<type>PF_INET</type> -or -<type>PF_INET6</type>. + </para> -</para> -</listitem></varlistentry> -<varlistentry><term><constant>h_length</constant></term> -<listitem> -<para> -The length of the address in bytes. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>h_addr_list</constant></term> -<listitem> -<para> -A -<type>NULL</type> -terminated array of network addresses for the host. -Host addresses are returned in network byte order. -</para> -</listitem></varlistentry> -</variablelist> -</para> -<para> -<function>lwres_getipnodebyname()</function> -looks up addresses of protocol family -<parameter>af</parameter> + <para> + The members of this structure are: + <variablelist> + <varlistentry> + <term><constant>h_name</constant></term> + <listitem> + <para> + The official (canonical) name of the host. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_aliases</constant></term> + <listitem> + <para> + A NULL-terminated array of alternate names (nicknames) for the + host. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_addrtype</constant></term> + <listitem> + <para> + The type of address being returned - usually + <type>PF_INET</type> + or + <type>PF_INET6</type>. -for the hostname -<parameter>name</parameter>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_length</constant></term> + <listitem> + <para> + The length of the address in bytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>h_addr_list</constant></term> + <listitem> + <para> + A + <type>NULL</type> + terminated array of network addresses for the host. + Host addresses are returned in network byte order. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> -The -<parameter>flags</parameter> -parameter contains ORed flag bits to -specify the types of addresses that are searched -for, and the types of addresses that are returned. -The flag bits are: -<variablelist> -<varlistentry><term><constant>AI_V4MAPPED</constant></term> -<listitem> -<para> -This is used with an -<parameter>af</parameter> -of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped -IPv6 addresses. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>AI_ALL</constant></term> -<listitem> -<para> -This is used with an -<parameter>af</parameter> -of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned. -If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped -IPv6 addresses. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>AI_ADDRCONFIG</constant></term> -<listitem> -<para> -Only return an IPv6 or IPv4 address if here is an active network -interface of that type. This is not currently implemented -in the BIND 9 lightweight resolver, and the flag is ignored. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>AI_DEFAULT</constant></term> -<listitem> -<para> -This default sets the -<constant>AI_V4MAPPED</constant> -and -<constant>AI_ADDRCONFIG</constant> -flag bits. -</para> -</listitem></varlistentry> -</variablelist> -</para> -<para> -<function>lwres_getipnodebyaddr()</function> -performs a reverse lookup -of address -<parameter>src</parameter> -which is -<parameter>len</parameter> -bytes long. -<parameter>af</parameter> -denotes the protocol family, typically -<type>PF_INET</type> -or -<type>PF_INET6</type>. + <para><function>lwres_getipnodebyname()</function> + looks up addresses of protocol family <parameter>af</parameter> + for the hostname <parameter>name</parameter>. The + <parameter>flags</parameter> parameter contains ORed flag bits + to specify the types of addresses that are searched for, and the + types of addresses that are returned. The flag bits are: -</para> -<para> -<function>lwres_freehostent()</function> -releases all the memory associated with -the -<type>struct hostent</type> -pointer -<parameter>he</parameter>. + <variablelist> + <varlistentry> + <term><constant>AI_V4MAPPED</constant></term> + <listitem> + <para> + This is used with an + <parameter>af</parameter> + of AF_INET6, and causes IPv4 addresses to be returned as + IPv4-mapped + IPv6 addresses. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>AI_ALL</constant></term> + <listitem> + <para> + This is used with an + <parameter>af</parameter> + of AF_INET6, and causes all known addresses (IPv6 and IPv4) to + be returned. + If AI_V4MAPPED is also set, the IPv4 addresses are return as + mapped + IPv6 addresses. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>AI_ADDRCONFIG</constant></term> + <listitem> + <para> + Only return an IPv6 or IPv4 address if here is an active network + interface of that type. This is not currently implemented + in the BIND 9 lightweight resolver, and the flag is ignored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>AI_DEFAULT</constant></term> + <listitem> + <para> + This default sets the + <constant>AI_V4MAPPED</constant> + and + <constant>AI_ADDRCONFIG</constant> + flag bits. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> -Any memory allocated for the -<constant>h_name</constant>, + <para><function>lwres_getipnodebyaddr()</function> + performs a reverse lookup of address <parameter>src</parameter> + which is <parameter>len</parameter> bytes long. + <parameter>af</parameter> denotes the protocol family, typically + <type>PF_INET</type> or <type>PF_INET6</type>. + </para> + <para><function>lwres_freehostent()</function> + releases all the memory associated with the <type>struct + hostent</type> pointer <parameter>he</parameter>. Any memory + allocated for the <constant>h_name</constant>, + <constant>h_addr_list</constant> and + <constant>h_aliases</constant> is freed, as is the memory for + the <type>hostent</type> structure itself. + </para> + </refsect1> + <refsect1> + <title>RETURN VALUES</title> + <para> + If an error occurs, + <function>lwres_getipnodebyname()</function> + and + <function>lwres_getipnodebyaddr()</function> + set + <parameter>*error_num</parameter> + to an appropriate error code and the function returns a + <type>NULL</type> + pointer. + The error codes and their meanings are defined in + <filename><lwres/netdb.h></filename>: + <variablelist> + <varlistentry> + <term><constant>HOST_NOT_FOUND</constant></term> + <listitem> + <para> + No such host is known. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>NO_ADDRESS</constant></term> + <listitem> + <para> + The server recognised the request and the name but no address is + available. Another type of request to the name server for the + domain might return an answer. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>TRY_AGAIN</constant></term> + <listitem> + <para> + A temporary and possibly transient error occurred, such as a + failure of a server to respond. The request may succeed if + retried. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>NO_RECOVERY</constant></term> + <listitem> + <para> + An unexpected failure occurred, and retrying the request + is pointless. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para><citerefentry> + <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + translates these error codes to suitable error messages. + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>RFC2553</refentrytitle> + </citerefentry>, -<constant>h_addr_list</constant> -and -<constant>h_aliases</constant> -is freed, as is the memory for the -<type>hostent</type> -structure itself. -</para> -</refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> -If an error occurs, -<function>lwres_getipnodebyname()</function> -and -<function>lwres_getipnodebyaddr()</function> -set -<parameter>*error_num</parameter> -to an appropriate error code and the function returns a -<type>NULL</type> -pointer. -The error codes and their meanings are defined in -<filename><lwres/netdb.h></filename>: -<variablelist> -<varlistentry><term><constant>HOST_NOT_FOUND</constant></term> -<listitem> -<para> -No such host is known. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>NO_ADDRESS</constant></term> -<listitem> -<para> -The server recognised the request and the name but no address is -available. Another type of request to the name server for the -domain might return an answer. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>TRY_AGAIN</constant></term> -<listitem> -<para> -A temporary and possibly transient error occurred, such as a -failure of a server to respond. The request may succeed if -retried. -</para> -</listitem></varlistentry> -<varlistentry><term><constant>NO_RECOVERY</constant></term> -<listitem> -<para> -An unexpected failure occurred, and retrying the request -is pointless. -</para> -</listitem></varlistentry> -</variablelist> -</para> -<para> -<citerefentry> -<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3 -</manvolnum> -</citerefentry> -translates these error codes to suitable error messages. -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>RFC2553</refentrytitle> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_gethostent</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <citerefentry> + <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>. -</para> -</refsect1> -</refentry> + <citerefentry> + <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_getipnode.html b/contrib/bind9/lib/lwres/man/lwres_getipnode.html index 779da9067383..a585f1d09dc7 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getipnode.html +++ b/contrib/bind9/lib/lwres/man/lwres_getipnode.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_getipnode.html,v 1.7.2.1.4.11 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_getipnode.html,v 1.9.18.16 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_getipnode</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_getipnodebyname, lwres_getipnodebyaddr, lwres_freehostent — lightweight resolver nodename / address translation API</p> @@ -36,29 +36,27 @@ <td><code class="funcdef"> struct hostent * <b class="fsfunc">lwres_getipnodebyname</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">name</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">af</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">flags</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>int * </td> <td> -<code>)</code>;</td> +<var class="pdparam">error_num</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -66,62 +64,52 @@ struct hostent * <td><code class="funcdef"> struct hostent * <b class="fsfunc">lwres_getipnodebyaddr</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const void * </td> +<td> +<var class="pdparam">src</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>size_t </td> +<td> +<var class="pdparam">len</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">af</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>int * </td> <td> -<code>)</code>;</td> +<var class="pdparam">error_num</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_freehostent</b>(</code></td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> +<td>struct hostent * </td> <td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">he</var><code>)</code>;</td> +</tr></table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549461"></a><h2>DESCRIPTION</h2> +<a name="id2543431"></a><h2>DESCRIPTION</h2> <p> -These functions perform thread safe, protocol independent -nodename-to-address and address-to-nodename -translation as defined in RFC2553. -</p> + These functions perform thread safe, protocol independent + nodename-to-address and address-to-nodename + translation as defined in RFC2553. + </p> <p> -They use a -<span class="type">struct hostent</span> -which is defined in -<code class="filename">namedb.h</code>: -</p> + They use a + <span class="type">struct hostent</span> + which is defined in + <code class="filename">namedb.h</code>: + </p> <pre class="programlisting"> struct hostent { char *h_name; /* official name of host */ @@ -133,184 +121,159 @@ struct hostent { #define h_addr h_addr_list[0] /* address, for backward compatibility */ </pre> <p> -</p> + </p> <p> -The members of this structure are: -</p> + The members of this structure are: + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">h_name</code></span></dt> <dd><p> -The official (canonical) name of the host. -</p></dd> + The official (canonical) name of the host. + </p></dd> <dt><span class="term"><code class="constant">h_aliases</code></span></dt> <dd><p> -A NULL-terminated array of alternate names (nicknames) for the host. -</p></dd> + A NULL-terminated array of alternate names (nicknames) for the + host. + </p></dd> <dt><span class="term"><code class="constant">h_addrtype</code></span></dt> <dd><p> -The type of address being returned - usually -<span class="type">PF_INET</span> -or -<span class="type">PF_INET6</span>. + The type of address being returned - usually + <span class="type">PF_INET</span> + or + <span class="type">PF_INET6</span>. -</p></dd> + </p></dd> <dt><span class="term"><code class="constant">h_length</code></span></dt> <dd><p> -The length of the address in bytes. -</p></dd> + The length of the address in bytes. + </p></dd> <dt><span class="term"><code class="constant">h_addr_list</code></span></dt> <dd><p> -A -<span class="type">NULL</span> -terminated array of network addresses for the host. -Host addresses are returned in network byte order. -</p></dd> + A + <span class="type">NULL</span> + terminated array of network addresses for the host. + Host addresses are returned in network byte order. + </p></dd> </dl></div> <p> -</p> -<p> -<code class="function">lwres_getipnodebyname()</code> -looks up addresses of protocol family -<em class="parameter"><code>af</code></em> - -for the hostname -<em class="parameter"><code>name</code></em>. + </p> +<p><code class="function">lwres_getipnodebyname()</code> + looks up addresses of protocol family <em class="parameter"><code>af</code></em> + for the hostname <em class="parameter"><code>name</code></em>. The + <em class="parameter"><code>flags</code></em> parameter contains ORed flag bits + to specify the types of addresses that are searched for, and the + types of addresses that are returned. The flag bits are: -The -<em class="parameter"><code>flags</code></em> -parameter contains ORed flag bits to -specify the types of addresses that are searched -for, and the types of addresses that are returned. -The flag bits are: -</p> + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">AI_V4MAPPED</code></span></dt> <dd><p> -This is used with an -<em class="parameter"><code>af</code></em> -of AF_INET6, and causes IPv4 addresses to be returned as IPv4-mapped -IPv6 addresses. -</p></dd> + This is used with an + <em class="parameter"><code>af</code></em> + of AF_INET6, and causes IPv4 addresses to be returned as + IPv4-mapped + IPv6 addresses. + </p></dd> <dt><span class="term"><code class="constant">AI_ALL</code></span></dt> <dd><p> -This is used with an -<em class="parameter"><code>af</code></em> -of AF_INET6, and causes all known addresses (IPv6 and IPv4) to be returned. -If AI_V4MAPPED is also set, the IPv4 addresses are return as mapped -IPv6 addresses. -</p></dd> + This is used with an + <em class="parameter"><code>af</code></em> + of AF_INET6, and causes all known addresses (IPv6 and IPv4) to + be returned. + If AI_V4MAPPED is also set, the IPv4 addresses are return as + mapped + IPv6 addresses. + </p></dd> <dt><span class="term"><code class="constant">AI_ADDRCONFIG</code></span></dt> <dd><p> -Only return an IPv6 or IPv4 address if here is an active network -interface of that type. This is not currently implemented -in the BIND 9 lightweight resolver, and the flag is ignored. -</p></dd> + Only return an IPv6 or IPv4 address if here is an active network + interface of that type. This is not currently implemented + in the BIND 9 lightweight resolver, and the flag is ignored. + </p></dd> <dt><span class="term"><code class="constant">AI_DEFAULT</code></span></dt> <dd><p> -This default sets the -<code class="constant">AI_V4MAPPED</code> -and -<code class="constant">AI_ADDRCONFIG</code> -flag bits. -</p></dd> + This default sets the + <code class="constant">AI_V4MAPPED</code> + and + <code class="constant">AI_ADDRCONFIG</code> + flag bits. + </p></dd> </dl></div> <p> -</p> -<p> -<code class="function">lwres_getipnodebyaddr()</code> -performs a reverse lookup -of address -<em class="parameter"><code>src</code></em> -which is -<em class="parameter"><code>len</code></em> -bytes long. -<em class="parameter"><code>af</code></em> -denotes the protocol family, typically -<span class="type">PF_INET</span> -or -<span class="type">PF_INET6</span>. - -</p> -<p> -<code class="function">lwres_freehostent()</code> -releases all the memory associated with -the -<span class="type">struct hostent</span> -pointer -<em class="parameter"><code>he</code></em>. - -Any memory allocated for the -<code class="constant">h_name</code>, - -<code class="constant">h_addr_list</code> -and -<code class="constant">h_aliases</code> -is freed, as is the memory for the -<span class="type">hostent</span> -structure itself. -</p> + </p> +<p><code class="function">lwres_getipnodebyaddr()</code> + performs a reverse lookup of address <em class="parameter"><code>src</code></em> + which is <em class="parameter"><code>len</code></em> bytes long. + <em class="parameter"><code>af</code></em> denotes the protocol family, typically + <span class="type">PF_INET</span> or <span class="type">PF_INET6</span>. + </p> +<p><code class="function">lwres_freehostent()</code> + releases all the memory associated with the <span class="type">struct + hostent</span> pointer <em class="parameter"><code>he</code></em>. Any memory + allocated for the <code class="constant">h_name</code>, + <code class="constant">h_addr_list</code> and + <code class="constant">h_aliases</code> is freed, as is the memory for + the <span class="type">hostent</span> structure itself. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549832"></a><h2>RETURN VALUES</h2> +<a name="id2543689"></a><h2>RETURN VALUES</h2> <p> -If an error occurs, -<code class="function">lwres_getipnodebyname()</code> -and -<code class="function">lwres_getipnodebyaddr()</code> -set -<em class="parameter"><code>*error_num</code></em> -to an appropriate error code and the function returns a -<span class="type">NULL</span> -pointer. -The error codes and their meanings are defined in -<code class="filename"><lwres/netdb.h></code>: -</p> + If an error occurs, + <code class="function">lwres_getipnodebyname()</code> + and + <code class="function">lwres_getipnodebyaddr()</code> + set + <em class="parameter"><code>*error_num</code></em> + to an appropriate error code and the function returns a + <span class="type">NULL</span> + pointer. + The error codes and their meanings are defined in + <code class="filename"><lwres/netdb.h></code>: + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">HOST_NOT_FOUND</code></span></dt> <dd><p> -No such host is known. -</p></dd> + No such host is known. + </p></dd> <dt><span class="term"><code class="constant">NO_ADDRESS</code></span></dt> <dd><p> -The server recognised the request and the name but no address is -available. Another type of request to the name server for the -domain might return an answer. -</p></dd> + The server recognised the request and the name but no address is + available. Another type of request to the name server for the + domain might return an answer. + </p></dd> <dt><span class="term"><code class="constant">TRY_AGAIN</code></span></dt> <dd><p> -A temporary and possibly transient error occurred, such as a -failure of a server to respond. The request may succeed if -retried. -</p></dd> + A temporary and possibly transient error occurred, such as a + failure of a server to respond. The request may succeed if + retried. + </p></dd> <dt><span class="term"><code class="constant">NO_RECOVERY</code></span></dt> <dd><p> -An unexpected failure occurred, and retrying the request -is pointless. -</p></dd> + An unexpected failure occurred, and retrying the request + is pointless. + </p></dd> </dl></div> <p> -</p> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3 -)</span> -translates these error codes to suitable error messages. -</p> + </p> +<p><span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span> + translates these error codes to suitable error messages. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549923"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">RFC2553</span></span>, +<a name="id2543786"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">RFC2553</span></span>, -<span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_gethostent</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>. -</p> + <span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_getnameinfo.3 b/contrib/bind9/lib/lwres/man/lwres_getnameinfo.3 index a9af04be5447..449f59130fdf 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getnameinfo.3 +++ b/contrib/bind9/lib/lwres/man/lwres_getnameinfo.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_getnameinfo.3,v 1.15.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_getnameinfo.3,v 1.18.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_getnameinfo .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,7 +36,7 @@ lwres_getnameinfo \- lightweight resolver socket address structure to hostname a #include <lwres/netdb.h> .fi .HP 22 -.BI "int lwres_getnameinfo(const\ struct\ sockaddr\ *sa, size_t\ salen, char\ *host, size_t\ hostlen, char\ *serv, size_t\ servlen, int\ flags);" +.BI "int lwres_getnameinfo(const\ struct\ sockaddr\ *" "sa" ", size_t\ " "salen" ", char\ *" "host" ", size_t\ " "hostlen" ", char\ *" "serv" ", size_t\ " "servlen" ", int\ " "flags" ");" .SH "DESCRIPTION" .PP This function is equivalent to the @@ -68,21 +68,31 @@ bytes long. The maximum length of the service name is The \fIflags\fR argument sets the following bits: -.TP 3n +.PP \fBNI_NOFQDN\fR +.RS 4 A fully qualified domain name is not required for local hosts. The local part of the fully qualified domain name is returned instead. -.TP 3n +.RE +.PP \fBNI_NUMERICHOST\fR +.RS 4 Return the address in numeric form, as if calling inet_ntop(), instead of a host name. -.TP 3n +.RE +.PP \fBNI_NAMEREQD\fR +.RS 4 A name is required. If the hostname cannot be found in the DNS and this flag is set, a non\-zero error code is returned. If the hostname is not found and the flag is not set, the address is returned in numeric form. -.TP 3n +.RE +.PP \fBNI_NUMERICSERV\fR +.RS 4 The service name is returned as a digit string representing the port number. -.TP 3n +.RE +.PP \fBNI_DGRAM\fR +.RS 4 Specifies that the service being looked up is a datagram service, and causes getservbyport() to be called with a second argument of "udp" instead of its default of "tcp". This is required for the few ports (512\-514) that have different services for UDP and TCP. +.RE .SH "RETURN VALUES" .PP \fBlwres_getnameinfo()\fR @@ -101,4 +111,7 @@ RFC2133 fails to define what the nonzero return values of \fBgetnameinfo\fR(3) are. .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_getnameinfo.docbook b/contrib/bind9/lib/lwres/man/lwres_getnameinfo.docbook index b6e10ac3ab05..4886196db636 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getnameinfo.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_getnameinfo.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_getnameinfo.docbook,v 1.3.206.3 2005/05/12 21:36:15 sra Exp $ --> - +<!-- $Id: lwres_getnameinfo.docbook,v 1.4.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_getnameinfo</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_getnameinfo</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,126 +45,161 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_getnameinfo</refname> -<refpurpose>lightweight resolver socket address structure to hostname and service name</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_getnameinfo</refname> + <refpurpose>lightweight resolver socket address structure to hostname and + service name + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> int <function>lwres_getnameinfo</function></funcdef> -<paramdef>const struct sockaddr *sa</paramdef> -<paramdef>size_t salen</paramdef> -<paramdef>char *host</paramdef> -<paramdef>size_t hostlen</paramdef> -<paramdef>char *serv</paramdef> -<paramdef>size_t servlen</paramdef> -<paramdef>int flags</paramdef> -</funcprototype> + <paramdef>const struct sockaddr *<parameter>sa</parameter></paramdef> + <paramdef>size_t <parameter>salen</parameter></paramdef> + <paramdef>char *<parameter>host</parameter></paramdef> + <paramdef>size_t <parameter>hostlen</parameter></paramdef> + <paramdef>char *<parameter>serv</parameter></paramdef> + <paramdef>size_t <parameter>servlen</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> + </refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> + <refsect1> + <title>DESCRIPTION</title> -<para> This function is equivalent to the <citerefentry> -<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry> function defined in RFC2133. -<function>lwres_getnameinfo()</function> returns the hostname for the -<type>struct sockaddr</type> <parameter>sa</parameter> which is -<parameter>salen</parameter> bytes long. The hostname is of length -<parameter>hostlen</parameter> and is returned via -<parameter>*host.</parameter> The maximum length of the hostname is -1025 bytes: <constant>NI_MAXHOST</constant>.</para> + <para> + This function is equivalent to the + <citerefentry> + <refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> function defined in RFC2133. + <function>lwres_getnameinfo()</function> returns the + hostname for the + <type>struct sockaddr</type> <parameter>sa</parameter> which + is + <parameter>salen</parameter> bytes long. The hostname is of + length + <parameter>hostlen</parameter> and is returned via + <parameter>*host.</parameter> The maximum length of the + hostname is + 1025 bytes: <constant>NI_MAXHOST</constant>. + </para> -<para> The name of the service associated with the port number in -<parameter>sa</parameter> is returned in <parameter>*serv.</parameter> -It is <parameter>servlen</parameter> bytes long. The maximum length -of the service name is <constant>NI_MAXSERV</constant> - 32 bytes. -</para> + <para> The name of the service associated with the port number in + <parameter>sa</parameter> is returned in <parameter>*serv.</parameter> + It is <parameter>servlen</parameter> bytes long. The + maximum length + of the service name is <constant>NI_MAXSERV</constant> - 32 + bytes. + </para> -<para> The <parameter>flags</parameter> argument sets the following -bits: -<variablelist> -<varlistentry><term><constant>NI_NOFQDN</constant></term> -<listitem> -<para> -A fully qualified domain name is not required for local hosts. -The local part of the fully qualified domain name is returned instead. -</para></listitem></varlistentry> -<varlistentry><term><constant>NI_NUMERICHOST</constant></term> -<listitem> -<para> -Return the address in numeric form, as if calling inet_ntop(), -instead of a host name. -</para></listitem></varlistentry> -<varlistentry><term><constant>NI_NAMEREQD</constant></term> -<listitem> -<para> -A name is required. If the hostname cannot be found in the DNS and -this flag is set, a non-zero error code is returned. -If the hostname is not found and the flag is not set, the -address is returned in numeric form. -</para></listitem></varlistentry> -<varlistentry><term><constant>NI_NUMERICSERV</constant></term> -<listitem> -<para> -The service name is returned as a digit string representing the port number. -</para></listitem></varlistentry> -<varlistentry><term><constant>NI_DGRAM</constant></term> -<listitem> -<para> -Specifies that the service being looked up is a datagram -service, and causes getservbyport() to be called with a second -argument of "udp" instead of its default of "tcp". This is required -for the few ports (512-514) that have different services for UDP and -TCP. -</para></listitem></varlistentry> -</variablelist> -</para> -</refsect1> + <para> + The <parameter>flags</parameter> argument sets the + following + bits: + <variablelist> + <varlistentry> + <term><constant>NI_NOFQDN</constant></term> + <listitem> + <para> + A fully qualified domain name is not required for local hosts. + The local part of the fully qualified domain name is returned + instead. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>NI_NUMERICHOST</constant></term> + <listitem> + <para> + Return the address in numeric form, as if calling inet_ntop(), + instead of a host name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>NI_NAMEREQD</constant></term> + <listitem> + <para> + A name is required. If the hostname cannot be found in the DNS + and + this flag is set, a non-zero error code is returned. + If the hostname is not found and the flag is not set, the + address is returned in numeric form. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>NI_NUMERICSERV</constant></term> + <listitem> + <para> + The service name is returned as a digit string representing the + port number. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>NI_DGRAM</constant></term> + <listitem> + <para> + Specifies that the service being looked up is a datagram + service, and causes getservbyport() to be called with a second + argument of "udp" instead of its default of "tcp". This is + required + for the few ports (512-514) that have different services for UDP + and + TCP. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> -<function>lwres_getnameinfo()</function> -returns 0 on success or a non-zero error code if an error occurs. -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>RFC2133</refentrytitle> -</citerefentry>, -<citerefentry> -<refentrytitle>getservbyport</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, -<citerefentry> -<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, -<citerefentry> -<refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, -<citerefentry> -<refentrytitle>lwres_getnamebyaddr</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>. -<citerefentry> -<refentrytitle>lwres_net_ntop</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>. -</para> -</refsect1> -<refsect1> -<title>BUGS</title> -<para> -RFC2133 fails to define what the nonzero return values of -<citerefentry> -<refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum> -</citerefentry> -are. -</para> -</refsect1> -</refentry> + <refsect1> + <title>RETURN VALUES</title> + <para><function>lwres_getnameinfo()</function> + returns 0 on success or a non-zero error code if an error occurs. + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>RFC2133</refentrytitle> + </citerefentry>, + <citerefentry> + <refentrytitle>getservbyport</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>lwres_getnameinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>lwres_getnamebyaddr</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + <citerefentry> + <refentrytitle>lwres_net_ntop</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + </para> + </refsect1> + <refsect1> + <title>BUGS</title> + <para> + RFC2133 fails to define what the nonzero return values of + <citerefentry> + <refentrytitle>getnameinfo</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + are. + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_getnameinfo.html b/contrib/bind9/lib/lwres/man/lwres_getnameinfo.html index 311173012576..312cfe53e213 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getnameinfo.html +++ b/contrib/bind9/lib/lwres/man/lwres_getnameinfo.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,18 +14,20 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_getnameinfo.html,v 1.5.2.1.4.12 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_getnameinfo.html,v 1.6.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_getnameinfo</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> -<p>lwres_getnameinfo — lightweight resolver socket address structure to hostname and service name</p> +<p>lwres_getnameinfo — lightweight resolver socket address structure to hostname and + service name + </p> </div> <div class="refsynopsisdiv"> <h2>Synopsis</h2> @@ -36,124 +38,139 @@ <td><code class="funcdef"> int <b class="fsfunc">lwres_getnameinfo</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const struct sockaddr * </td> +<td> +<var class="pdparam">sa</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>size_t </td> +<td> +<var class="pdparam">salen</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>char * </td> +<td> +<var class="pdparam">host</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>size_t </td> +<td> +<var class="pdparam">hostlen</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>char * </td> +<td> +<var class="pdparam">serv</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>size_t </td> +<td> +<var class="pdparam">servlen</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>int </td> <td> -<code>)</code>;</td> +<var class="pdparam">flags</var><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549427"></a><h2>DESCRIPTION</h2> -<p> This function is equivalent to the <span class="citerefentry"><span class="refentrytitle">getnameinfo</span>(3)</span> function defined in RFC2133. -<code class="function">lwres_getnameinfo()</code> returns the hostname for the -<span class="type">struct sockaddr</span> <em class="parameter"><code>sa</code></em> which is -<em class="parameter"><code>salen</code></em> bytes long. The hostname is of length -<em class="parameter"><code>hostlen</code></em> and is returned via -<em class="parameter"><code>*host.</code></em> The maximum length of the hostname is -1025 bytes: <code class="constant">NI_MAXHOST</code>.</p> +<a name="id2543393"></a><h2>DESCRIPTION</h2> +<p> + This function is equivalent to the + <span class="citerefentry"><span class="refentrytitle">getnameinfo</span>(3)</span> function defined in RFC2133. + <code class="function">lwres_getnameinfo()</code> returns the + hostname for the + <span class="type">struct sockaddr</span> <em class="parameter"><code>sa</code></em> which + is + <em class="parameter"><code>salen</code></em> bytes long. The hostname is of + length + <em class="parameter"><code>hostlen</code></em> and is returned via + <em class="parameter"><code>*host.</code></em> The maximum length of the + hostname is + 1025 bytes: <code class="constant">NI_MAXHOST</code>. + </p> <p> The name of the service associated with the port number in -<em class="parameter"><code>sa</code></em> is returned in <em class="parameter"><code>*serv.</code></em> -It is <em class="parameter"><code>servlen</code></em> bytes long. The maximum length -of the service name is <code class="constant">NI_MAXSERV</code> - 32 bytes. -</p> -<p> The <em class="parameter"><code>flags</code></em> argument sets the following -bits: -</p> + <em class="parameter"><code>sa</code></em> is returned in <em class="parameter"><code>*serv.</code></em> + It is <em class="parameter"><code>servlen</code></em> bytes long. The + maximum length + of the service name is <code class="constant">NI_MAXSERV</code> - 32 + bytes. + </p> +<p> + The <em class="parameter"><code>flags</code></em> argument sets the + following + bits: + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">NI_NOFQDN</code></span></dt> <dd><p> -A fully qualified domain name is not required for local hosts. -The local part of the fully qualified domain name is returned instead. -</p></dd> + A fully qualified domain name is not required for local hosts. + The local part of the fully qualified domain name is returned + instead. + </p></dd> <dt><span class="term"><code class="constant">NI_NUMERICHOST</code></span></dt> <dd><p> -Return the address in numeric form, as if calling inet_ntop(), -instead of a host name. -</p></dd> + Return the address in numeric form, as if calling inet_ntop(), + instead of a host name. + </p></dd> <dt><span class="term"><code class="constant">NI_NAMEREQD</code></span></dt> <dd><p> -A name is required. If the hostname cannot be found in the DNS and -this flag is set, a non-zero error code is returned. -If the hostname is not found and the flag is not set, the -address is returned in numeric form. -</p></dd> + A name is required. If the hostname cannot be found in the DNS + and + this flag is set, a non-zero error code is returned. + If the hostname is not found and the flag is not set, the + address is returned in numeric form. + </p></dd> <dt><span class="term"><code class="constant">NI_NUMERICSERV</code></span></dt> <dd><p> -The service name is returned as a digit string representing the port number. -</p></dd> + The service name is returned as a digit string representing the + port number. + </p></dd> <dt><span class="term"><code class="constant">NI_DGRAM</code></span></dt> <dd><p> -Specifies that the service being looked up is a datagram -service, and causes getservbyport() to be called with a second -argument of "udp" instead of its default of "tcp". This is required -for the few ports (512-514) that have different services for UDP and -TCP. -</p></dd> + Specifies that the service being looked up is a datagram + service, and causes getservbyport() to be called with a second + argument of "udp" instead of its default of "tcp". This is + required + for the few ports (512-514) that have different services for UDP + and + TCP. + </p></dd> </dl></div> <p> -</p> + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549553"></a><h2>RETURN VALUES</h2> -<p> -<code class="function">lwres_getnameinfo()</code> -returns 0 on success or a non-zero error code if an error occurs. -</p> +<a name="id2543534"></a><h2>RETURN VALUES</h2> +<p><code class="function">lwres_getnameinfo()</code> + returns 0 on success or a non-zero error code if an error occurs. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549634"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>, -<span class="citerefentry"><span class="refentrytitle">getservbyport</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_getnamebyaddr</span>(3)</span>. -<span class="citerefentry"><span class="refentrytitle">lwres_net_ntop</span>(3)</span>. -</p> +<a name="id2543546"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>, + <span class="citerefentry"><span class="refentrytitle">getservbyport</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_getnameinfo</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">lwres_getnamebyaddr</span>(3)</span>. + <span class="citerefentry"><span class="refentrytitle">lwres_net_ntop</span>(3)</span>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549692"></a><h2>BUGS</h2> +<a name="id2543604"></a><h2>BUGS</h2> <p> -RFC2133 fails to define what the nonzero return values of -<span class="citerefentry"><span class="refentrytitle">getnameinfo</span>(3)</span> -are. -</p> + RFC2133 fails to define what the nonzero return values of + <span class="citerefentry"><span class="refentrytitle">getnameinfo</span>(3)</span> + are. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.3 b/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.3 index 1aeca283cd75..548b8e7e1711 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.3 +++ b/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_getrrsetbyname.3,v 1.11.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_getrrsetbyname.3,v 1.14.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_getrrsetbyname .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Oct 18, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,18 +36,24 @@ lwres_getrrsetbyname, lwres_freerrset \- retrieve DNS records #include <lwres/netdb.h> .fi .HP 25 -.BI "int lwres_getrrsetbyname(const\ char\ *hostname, unsigned\ int\ rdclass, unsigned\ int\ rdtype, unsigned\ int\ flags, struct\ rrsetinfo\ **res);" +.BI "int lwres_getrrsetbyname(const\ char\ *" "hostname" ", unsigned\ int\ " "rdclass" ", unsigned\ int\ " "rdtype" ", unsigned\ int\ " "flags" ", struct\ rrsetinfo\ **" "res" ");" .HP 21 -.BI "void lwres_freerrset(struct\ rrsetinfo\ *rrset);" +.BI "void lwres_freerrset(struct\ rrsetinfo\ *" "rrset" ");" .PP The following structures are used: -.sp -.RS 3n +.PP +.RS 4 .nf struct rdatainfo { unsigned int rdi_length; /* length of data */ unsigned char *rdi_data; /* record data */ }; +.fi +.RE +.sp +.PP +.RS 4 +.nf struct rrsetinfo { unsigned int rri_flags; /* RRSET_VALIDATED... */ unsigned int rri_rdclass; /* class number */ @@ -120,24 +126,39 @@ created by a call to .PP \fBlwres_getrrsetbyname()\fR returns zero on success, and one of the following error codes if an error occurred: -.TP 3n +.PP \fBERRSET_NONAME\fR +.RS 4 the name does not exist -.TP 3n +.RE +.PP \fBERRSET_NODATA\fR +.RS 4 the name exists, but does not have data of the desired type -.TP 3n +.RE +.PP \fBERRSET_NOMEMORY\fR +.RS 4 memory could not be allocated -.TP 3n +.RE +.PP \fBERRSET_INVAL\fR +.RS 4 a parameter is invalid -.TP 3n +.RE +.PP \fBERRSET_FAIL\fR +.RS 4 other failure -.TP 3n +.RE +.PP +.RS 4 +.RE .SH "SEE ALSO" .PP \fBlwres\fR(3). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook b/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook index 53c33bef7b34..2fd996b366f0 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_getrrsetbyname.docbook,v 1.3.206.3 2005/05/12 21:36:15 sra Exp $ --> - +<!-- $Id: lwres_getrrsetbyname.docbook,v 1.4.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> + <refentryinfo> + <date>Oct 18, 2000</date> + </refentryinfo> -<date>Oct 18, 2000</date> -</refentryinfo> -<refmeta> -<refentrytitle>lwres_getrrsetbyname</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_getrrsetbyname</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,40 +45,43 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_getrrsetbyname</refname> -<refname>lwres_freerrset</refname> -<refpurpose>retrieve DNS records</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_getrrsetbyname</refname> + <refname>lwres_freerrset</refname> + <refpurpose>retrieve DNS records</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> int <function>lwres_getrrsetbyname</function></funcdef> -<paramdef>const char *hostname</paramdef> -<paramdef>unsigned int rdclass</paramdef> -<paramdef>unsigned int rdtype</paramdef> -<paramdef>unsigned int flags</paramdef> -<paramdef>struct rrsetinfo **res</paramdef> -</funcprototype> + <paramdef>const char *<parameter>hostname</parameter></paramdef> + <paramdef>unsigned int <parameter>rdclass</parameter></paramdef> + <paramdef>unsigned int <parameter>rdtype</parameter></paramdef> + <paramdef>unsigned int <parameter>flags</parameter></paramdef> + <paramdef>struct rrsetinfo **<parameter>res</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_freerrset</function></funcdef> -<paramdef>struct rrsetinfo *rrset</paramdef> -</funcprototype> + <paramdef>struct rrsetinfo *<parameter>rrset</parameter></paramdef> + </funcprototype> </funcsynopsis> -<para> -The following structures are used: -<programlisting> + <para> + The following structures are used: + </para> + <para><programlisting> struct rdatainfo { unsigned int rdi_length; /* length of data */ unsigned char *rdi_data; /* record data */ }; - +</programlisting> + </para> + <para><programlisting> struct rrsetinfo { unsigned int rri_flags; /* RRSET_VALIDATED... */ unsigned int rri_rdclass; /* class number */ @@ -91,134 +94,130 @@ struct rrsetinfo { struct rdatainfo *rri_sigs; /* individual signatures */ }; </programlisting> -</para> -</refsynopsisdiv> - -<refsect1> -<title>DESCRIPTION</title> -<para> -<function>lwres_getrrsetbyname()</function> -gets a set of resource records associated with a -<parameter>hostname</parameter>, - -<parameter>class</parameter>, - -and -<parameter>type</parameter>. - -<parameter>hostname</parameter> -is -a pointer a to null-terminated string. The -<parameter>flags</parameter> -field is currently unused and must be zero. -</para> -<para> -After a successful call to -<function>lwres_getrrsetbyname()</function>, - -<parameter>*res</parameter> -is a pointer to an -<type>rrsetinfo</type> -structure, containing a list of one or more -<type>rdatainfo</type> -structures containing resource records and potentially another list of -<type>rdatainfo</type> -structures containing SIG resource records -associated with those records. -The members -<constant>rri_rdclass</constant> -and -<constant>rri_rdtype</constant> -are copied from the parameters. -<constant>rri_ttl</constant> -and -<constant>rri_name</constant> -are properties of the obtained rrset. -The resource records contained in -<constant>rri_rdatas</constant> -and -<constant>rri_sigs</constant> -are in uncompressed DNS wire format. -Properties of the rdataset are represented in the -<constant>rri_flags</constant> -bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC -validated and the signatures verified. -</para> -<para> -All of the information returned by -<function>lwres_getrrsetbyname()</function> -is dynamically allocated: the -<constant>rrsetinfo</constant> -and -<constant>rdatainfo</constant> -structures, -and the canonical host name strings pointed to by the -<constant>rrsetinfo</constant>structure. - -Memory allocated for the dynamically allocated structures created by -a successful call to -<function>lwres_getrrsetbyname()</function> -is released by -<function>lwres_freerrset()</function>. - -<parameter>rrset</parameter> -is a pointer to a -<type>struct rrset</type> -created by a call to -<function>lwres_getrrsetbyname()</function>. - -</para> -<para> -</para> -</refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> -<function>lwres_getrrsetbyname()</function> -returns zero on success, and one of the following error -codes if an error occurred: -<variablelist> - -<varlistentry><term><constant>ERRSET_NONAME</constant></term> -<listitem><para> -the name does not exist -</para></listitem></varlistentry> - -<varlistentry><term><constant>ERRSET_NODATA</constant></term> -<listitem><para> -the name exists, but does not have data of the desired type -</para></listitem></varlistentry> - -<varlistentry><term><constant>ERRSET_NOMEMORY</constant></term> -<listitem><para> -memory could not be allocated -</para></listitem></varlistentry> - -<varlistentry><term><constant>ERRSET_INVAL</constant></term> -<listitem><para> -a parameter is invalid -</para></listitem></varlistentry> - -<varlistentry><term><constant>ERRSET_FAIL</constant></term> -<listitem><para> -other failure -</para></listitem></varlistentry> - -<varlistentry><term><constant></constant></term> -<listitem><para> -</para></listitem></varlistentry> - -</variablelist> - -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>. -</para> - -</refsect1> -</refentry> + </para> + </refsynopsisdiv> + + <refsect1> + <title>DESCRIPTION</title> + <para><function>lwres_getrrsetbyname()</function> + gets a set of resource records associated with a + <parameter>hostname</parameter>, <parameter>class</parameter>, + and <parameter>type</parameter>. + <parameter>hostname</parameter> is a pointer a to + null-terminated string. The <parameter>flags</parameter> field + is currently unused and must be zero. + </para> + <para> + After a successful call to + <function>lwres_getrrsetbyname()</function>, + <parameter>*res</parameter> is a pointer to an + <type>rrsetinfo</type> structure, containing a list of one or + more <type>rdatainfo</type> structures containing resource + records and potentially another list of <type>rdatainfo</type> + structures containing SIG resource records associated with those + records. The members <constant>rri_rdclass</constant> and + <constant>rri_rdtype</constant> are copied from the parameters. + <constant>rri_ttl</constant> and <constant>rri_name</constant> + are properties of the obtained rrset. The resource records + contained in <constant>rri_rdatas</constant> and + <constant>rri_sigs</constant> are in uncompressed DNS wire + format. Properties of the rdataset are represented in the + <constant>rri_flags</constant> bitfield. If the RRSET_VALIDATED + bit is set, the data has been DNSSEC validated and the + signatures verified. + </para> + <para> + All of the information returned by + <function>lwres_getrrsetbyname()</function> is dynamically + allocated: the <constant>rrsetinfo</constant> and + <constant>rdatainfo</constant> structures, and the canonical + host name strings pointed to by the + <constant>rrsetinfo</constant>structure. + + Memory allocated for the dynamically allocated structures + created by a successful call to + <function>lwres_getrrsetbyname()</function> is released by + <function>lwres_freerrset()</function>. + + <parameter>rrset</parameter> is a pointer to a <type>struct + rrset</type> created by a call to + <function>lwres_getrrsetbyname()</function>. + </para> + <para></para> + </refsect1> + <refsect1> + <title>RETURN VALUES</title> + <para><function>lwres_getrrsetbyname()</function> + returns zero on success, and one of the following error codes if + an error occurred: + <variablelist> + + <varlistentry> + <term><constant>ERRSET_NONAME</constant></term> + <listitem> + <para> + the name does not exist + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>ERRSET_NODATA</constant></term> + <listitem> + <para> + the name exists, but does not have data of the desired type + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>ERRSET_NOMEMORY</constant></term> + <listitem> + <para> + memory could not be allocated + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>ERRSET_INVAL</constant></term> + <listitem> + <para> + a parameter is invalid + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>ERRSET_FAIL</constant></term> + <listitem> + <para> + other failure + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant/></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + + </variablelist> + + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + </para> + + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.html b/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.html index 6cbed6fafe15..092536735673 100644 --- a/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.html +++ b/contrib/bind9/lib/lwres/man/lwres_getrrsetbyname.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_getrrsetbyname.html,v 1.5.2.1.4.11 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_getrrsetbyname.html,v 1.6.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_getrrsetbyname</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_getrrsetbyname, lwres_freerrset — retrieve DNS records</p> @@ -36,62 +36,56 @@ <td><code class="funcdef"> int <b class="fsfunc">lwres_getrrsetbyname</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">hostname</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>unsigned int </td> +<td> +<var class="pdparam">rdclass</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>unsigned int </td> +<td> +<var class="pdparam">rdtype</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>unsigned int </td> +<td> +<var class="pdparam">flags</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>struct rrsetinfo ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">res</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_freerrset</b>(</code></td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> +<td>struct rrsetinfo * </td> <td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">rrset</var><code>)</code>;</td> +</tr></table> </div> <p> -The following structures are used: -</p> + The following structures are used: + </p> <pre class="programlisting"> struct rdatainfo { unsigned int rdi_length; /* length of data */ unsigned char *rdi_data; /* record data */ }; - +</pre> +<p> + </p> +<pre class="programlisting"> struct rrsetinfo { unsigned int rri_flags; /* RRSET_VALIDATED... */ unsigned int rri_rdclass; /* class number */ @@ -105,126 +99,94 @@ struct rrsetinfo { }; </pre> <p> -</p> + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549443"></a><h2>DESCRIPTION</h2> -<p> -<code class="function">lwres_getrrsetbyname()</code> -gets a set of resource records associated with a -<em class="parameter"><code>hostname</code></em>, - -<em class="parameter"><code>class</code></em>, - -and -<em class="parameter"><code>type</code></em>. - -<em class="parameter"><code>hostname</code></em> -is -a pointer a to null-terminated string. The -<em class="parameter"><code>flags</code></em> -field is currently unused and must be zero. -</p> +<a name="id2543414"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_getrrsetbyname()</code> + gets a set of resource records associated with a + <em class="parameter"><code>hostname</code></em>, <em class="parameter"><code>class</code></em>, + and <em class="parameter"><code>type</code></em>. + <em class="parameter"><code>hostname</code></em> is a pointer a to + null-terminated string. The <em class="parameter"><code>flags</code></em> field + is currently unused and must be zero. + </p> <p> -After a successful call to -<code class="function">lwres_getrrsetbyname()</code>, - -<em class="parameter"><code>*res</code></em> -is a pointer to an -<span class="type">rrsetinfo</span> -structure, containing a list of one or more -<span class="type">rdatainfo</span> -structures containing resource records and potentially another list of -<span class="type">rdatainfo</span> -structures containing SIG resource records -associated with those records. -The members -<code class="constant">rri_rdclass</code> -and -<code class="constant">rri_rdtype</code> -are copied from the parameters. -<code class="constant">rri_ttl</code> -and -<code class="constant">rri_name</code> -are properties of the obtained rrset. -The resource records contained in -<code class="constant">rri_rdatas</code> -and -<code class="constant">rri_sigs</code> -are in uncompressed DNS wire format. -Properties of the rdataset are represented in the -<code class="constant">rri_flags</code> -bitfield. If the RRSET_VALIDATED bit is set, the data has been DNSSEC -validated and the signatures verified. -</p> + After a successful call to + <code class="function">lwres_getrrsetbyname()</code>, + <em class="parameter"><code>*res</code></em> is a pointer to an + <span class="type">rrsetinfo</span> structure, containing a list of one or + more <span class="type">rdatainfo</span> structures containing resource + records and potentially another list of <span class="type">rdatainfo</span> + structures containing SIG resource records associated with those + records. The members <code class="constant">rri_rdclass</code> and + <code class="constant">rri_rdtype</code> are copied from the parameters. + <code class="constant">rri_ttl</code> and <code class="constant">rri_name</code> + are properties of the obtained rrset. The resource records + contained in <code class="constant">rri_rdatas</code> and + <code class="constant">rri_sigs</code> are in uncompressed DNS wire + format. Properties of the rdataset are represented in the + <code class="constant">rri_flags</code> bitfield. If the RRSET_VALIDATED + bit is set, the data has been DNSSEC validated and the + signatures verified. + </p> <p> -All of the information returned by -<code class="function">lwres_getrrsetbyname()</code> -is dynamically allocated: the -<code class="constant">rrsetinfo</code> -and -<code class="constant">rdatainfo</code> -structures, -and the canonical host name strings pointed to by the -<code class="constant">rrsetinfo</code>structure. - -Memory allocated for the dynamically allocated structures created by -a successful call to -<code class="function">lwres_getrrsetbyname()</code> -is released by -<code class="function">lwres_freerrset()</code>. + All of the information returned by + <code class="function">lwres_getrrsetbyname()</code> is dynamically + allocated: the <code class="constant">rrsetinfo</code> and + <code class="constant">rdatainfo</code> structures, and the canonical + host name strings pointed to by the + <code class="constant">rrsetinfo</code>structure. -<em class="parameter"><code>rrset</code></em> -is a pointer to a -<span class="type">struct rrset</span> -created by a call to -<code class="function">lwres_getrrsetbyname()</code>. + Memory allocated for the dynamically allocated structures + created by a successful call to + <code class="function">lwres_getrrsetbyname()</code> is released by + <code class="function">lwres_freerrset()</code>. -</p> -<p> -</p> + <em class="parameter"><code>rrset</code></em> is a pointer to a <span class="type">struct + rrset</span> created by a call to + <code class="function">lwres_getrrsetbyname()</code>. + </p> +<p></p> </div> <div class="refsect1" lang="en"> -<a name="id2549623"></a><h2>RETURN VALUES</h2> -<p> -<code class="function">lwres_getrrsetbyname()</code> -returns zero on success, and one of the following error -codes if an error occurred: -</p> +<a name="id2543526"></a><h2>RETURN VALUES</h2> +<p><code class="function">lwres_getrrsetbyname()</code> + returns zero on success, and one of the following error codes if + an error occurred: + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">ERRSET_NONAME</code></span></dt> <dd><p> -the name does not exist -</p></dd> + the name does not exist + </p></dd> <dt><span class="term"><code class="constant">ERRSET_NODATA</code></span></dt> <dd><p> -the name exists, but does not have data of the desired type -</p></dd> + the name exists, but does not have data of the desired type + </p></dd> <dt><span class="term"><code class="constant">ERRSET_NOMEMORY</code></span></dt> <dd><p> -memory could not be allocated -</p></dd> + memory could not be allocated + </p></dd> <dt><span class="term"><code class="constant">ERRSET_INVAL</code></span></dt> <dd><p> -a parameter is invalid -</p></dd> + a parameter is invalid + </p></dd> <dt><span class="term"><code class="constant">ERRSET_FAIL</code></span></dt> <dd><p> -other failure -</p></dd> + other failure + </p></dd> <dt><span class="term"><code class="constant"></code></span></dt> -<dd><p> -</p></dd> +<dd><p></p></dd> </dl></div> <p> -</p> + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549697"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>. -</p> +<a name="id2543626"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_gnba.3 b/contrib/bind9/lib/lwres/man/lwres_gnba.3 index dc546d2ab2ec..1c6574f08e82 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gnba.3 +++ b/contrib/bind9/lib/lwres/man/lwres_gnba.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_gnba.3,v 1.13.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_gnba.3,v 1.16.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_gnba .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -38,15 +38,15 @@ lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lw .HP 40 .BI "lwres_result_t lwres_gnbarequest_render(lwres_context_t\ *" "ctx" ", lwres_gnbarequest_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");" .HP 41 -.BI "lwres_result_t lwres_gnbaresponse_render(lwres_context_t\ *ctx, lwres_gnbaresponse_t\ *req, lwres_lwpacket_t\ *pkt, lwres_buffer_t\ *b);" +.BI "lwres_result_t lwres_gnbaresponse_render(lwres_context_t\ *" "ctx" ", lwres_gnbaresponse_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");" .HP 39 -.BI "lwres_result_t lwres_gnbarequest_parse(lwres_context_t\ *ctx, lwres_buffer_t\ *b, lwres_lwpacket_t\ *pkt, lwres_gnbarequest_t\ **structp);" +.BI "lwres_result_t lwres_gnbarequest_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gnbarequest_t\ **" "structp" ");" .HP 40 -.BI "lwres_result_t lwres_gnbaresponse_parse(lwres_context_t\ *ctx, lwres_buffer_t\ *b, lwres_lwpacket_t\ *pkt, lwres_gnbaresponse_t\ **structp);" +.BI "lwres_result_t lwres_gnbaresponse_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_gnbaresponse_t\ **" "structp" ");" .HP 29 -.BI "void lwres_gnbaresponse_free(lwres_context_t\ *ctx, lwres_gnbaresponse_t\ **structp);" +.BI "void lwres_gnbaresponse_free(lwres_context_t\ *" "ctx" ", lwres_gnbaresponse_t\ **" "structp" ");" .HP 28 -.BI "void lwres_gnbarequest_free(lwres_context_t\ *ctx, lwres_gnbarequest_t\ **structp);" +.BI "void lwres_gnbarequest_free(lwres_context_t\ *" "ctx" ", lwres_gnbarequest_t\ **" "structp" ");" .SH "DESCRIPTION" .PP These are low\-level routines for creating and parsing lightweight resolver address\-to\-name lookup request and response messages. @@ -59,14 +59,26 @@ to the canonical format. This is complemented by a parse function which converts .PP These structures are defined in \fIlwres/lwres.h\fR. They are shown below. -.sp -.RS 3n +.PP +.RS 4 .nf #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U +.fi +.RE +.sp +.PP +.RS 4 +.nf typedef struct { lwres_uint32_t flags; lwres_addr_t addr; } lwres_gnbarequest_t; +.fi +.RE +.sp +.PP +.RS 4 +.nf typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -165,4 +177,7 @@ indicate that the packet is not a response to an earlier query. .PP \fBlwres_packet\fR(3). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_gnba.docbook b/contrib/bind9/lib/lwres/man/lwres_gnba.docbook index 753148642efe..5a768898ccb3 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gnba.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_gnba.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_gnba.docbook,v 1.4.206.3 2005/05/12 21:36:15 sra Exp $ --> - +<!-- $Id: lwres_gnba.docbook,v 1.5.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_gnba</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_gnba</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,114 +45,120 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_gnbarequest_render</refname> -<refname>lwres_gnbaresponse_render</refname> -<refname>lwres_gnbarequest_parse</refname> -<refname>lwres_gnbaresponse_parse</refname> -<refname>lwres_gnbaresponse_free</refname> -<refname>lwres_gnbarequest_free</refname> -<refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose> -</refnamediv> + <refnamediv> + <refname>lwres_gnbarequest_render</refname> + <refname>lwres_gnbaresponse_render</refname> + <refname>lwres_gnbarequest_parse</refname> + <refname>lwres_gnbaresponse_parse</refname> + <refname>lwres_gnbaresponse_free</refname> + <refname>lwres_gnbarequest_free</refname> + <refpurpose>lightweight resolver getnamebyaddress message handling</refpurpose> + </refnamediv> -<refsynopsisdiv> + <refsynopsisdiv> -<funcsynopsis> + <funcsynopsis> <funcsynopsisinfo> #include <lwres/lwres.h> </funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_gnbarequest_render</function> </funcdef> -<paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> -<paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef> -<paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> -<paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_gnbarequest_t *<parameter>req</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_gnbaresponse_render</function> </funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_gnbaresponse_t *req</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_gnbaresponse_t *<parameter>req</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_gnbarequest_parse</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_gnbarequest_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_gnbaresponse_parse</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_gnbaresponse_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_gnbaresponse_free</function> </funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_gnbaresponse_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_gnbarequest_free</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_gnbarequest_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_gnbarequest_t **<parameter>structp</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> + </refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> -<para> -These are low-level routines for creating and parsing -lightweight resolver address-to-name lookup request and -response messages. -</para> -<para> -There are four main functions for the getnamebyaddr opcode. -One render function converts a getnamebyaddr request structure — -<type>lwres_gnbarequest_t</type> — -to the lightweight resolver's canonical format. -It is complemented by a parse function that converts a packet in this -canonical format to a getnamebyaddr request structure. -Another render function converts the getnamebyaddr response structure — -<type>lwres_gnbaresponse_t</type> -to the canonical format. -This is complemented by a parse function which converts a packet in -canonical format to a getnamebyaddr response structure. -</para> -<para> -These structures are defined in -<filename>lwres/lwres.h</filename>. -They are shown below. -<programlisting> + <refsect1> + <title>DESCRIPTION</title> + <para> + These are low-level routines for creating and parsing + lightweight resolver address-to-name lookup request and + response messages. + </para> + <para> + There are four main functions for the getnamebyaddr opcode. + One render function converts a getnamebyaddr request structure — + <type>lwres_gnbarequest_t</type> — + to the lightweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a getnamebyaddr request structure. + Another render function converts the getnamebyaddr response structure + — + <type>lwres_gnbaresponse_t</type> + to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a getnamebyaddr response structure. + </para> + <para> + These structures are defined in + <filename>lwres/lwres.h</filename>. + They are shown below. + </para> + <para><programlisting> #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U - +</programlisting> + </para> + <para><programlisting> typedef struct { lwres_uint32_t flags; lwres_addr_t addr; } lwres_gnbarequest_t; - +</programlisting> + </para> + <para><programlisting> typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -164,111 +170,92 @@ typedef struct { size_t baselen; } lwres_gnbaresponse_t; </programlisting> -</para> -<para> -<function>lwres_gnbarequest_render()</function> -uses resolver context -<varname>ctx</varname> -to convert getnamebyaddr request structure -<varname>req</varname> -to canonical format. -The packet header structure -<varname>pkt</varname> -is initialised and transferred to -buffer -<varname>b</varname>. -The contents of -<varname>*req</varname> -are then appended to the buffer in canonical format. -<function>lwres_gnbaresponse_render()</function> -performs the same task, except it converts a getnamebyaddr response structure -<type>lwres_gnbaresponse_t</type> -to the lightweight resolver's canonical format. -</para> -<para> -<function>lwres_gnbarequest_parse()</function> -uses context -<varname>ctx</varname> -to convert the contents of packet -<varname>pkt</varname> -to a -<type>lwres_gnbarequest_t</type> -structure. -Buffer -<varname>b</varname> -provides space to be used for storing this structure. -When the function succeeds, the resulting -<type>lwres_gnbarequest_t</type> -is made available through -<varname>*structp</varname>. -<function>lwres_gnbaresponse_parse()</function> -offers the same semantics as -<function>lwres_gnbarequest_parse()</function> -except it yields a -<type>lwres_gnbaresponse_t</type> -structure. -</para> -<para> -<function>lwres_gnbaresponse_free()</function> -and -<function>lwres_gnbarequest_free()</function> -release the memory in resolver context -<varname>ctx</varname> -that was allocated to the -<type>lwres_gnbaresponse_t</type> -or -<type>lwres_gnbarequest_t</type> -structures referenced via -<varname>structp</varname>. -Any memory associated with ancillary buffers and strings for those -structures is also discarded. -</para> -</refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> -The getnamebyaddr opcode functions -<function>lwres_gnbarequest_render()</function>, -<function>lwres_gnbaresponse_render()</function> -<function>lwres_gnbarequest_parse()</function> -and -<function>lwres_gnbaresponse_parse()</function> -all return -<errorcode>LWRES_R_SUCCESS</errorcode> -on success. -They return -<errorcode>LWRES_R_NOMEMORY</errorcode> -if memory allocation fails. -<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> -is returned if the available space in the buffer -<varname>b</varname> -is too small to accommodate the packet header or the -<type>lwres_gnbarequest_t</type> -and -<type>lwres_gnbaresponse_t</type> -structures. -<function>lwres_gnbarequest_parse()</function> -and -<function>lwres_gnbaresponse_parse()</function> -will return -<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> -if the buffer is not empty after decoding the received packet. -These functions will return -<errorcode>LWRES_R_FAILURE</errorcode> -if -<structfield>pktflags</structfield> -in the packet header structure -<type>lwres_lwpacket_t</type> -indicate that the packet is not a response to an earlier query. -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>lwres_packet</refentrytitle> -<manvolnum>3</manvolnum> -</citerefentry>. -</para> -</refsect1> -</refentry> + </para> + + <para><function>lwres_gnbarequest_render()</function> + uses resolver context <varname>ctx</varname> to convert + getnamebyaddr request structure <varname>req</varname> to + canonical format. The packet header structure + <varname>pkt</varname> is initialised and transferred to buffer + <varname>b</varname>. The contents of <varname>*req</varname> + are then appended to the buffer in canonical format. + <function>lwres_gnbaresponse_render()</function> performs the + same task, except it converts a getnamebyaddr response structure + <type>lwres_gnbaresponse_t</type> to the lightweight resolver's + canonical format. + </para> + + <para><function>lwres_gnbarequest_parse()</function> + uses context <varname>ctx</varname> to convert the contents of + packet <varname>pkt</varname> to a + <type>lwres_gnbarequest_t</type> structure. Buffer + <varname>b</varname> provides space to be used for storing this + structure. When the function succeeds, the resulting + <type>lwres_gnbarequest_t</type> is made available through + <varname>*structp</varname>. + <function>lwres_gnbaresponse_parse()</function> offers the same + semantics as <function>lwres_gnbarequest_parse()</function> + except it yields a <type>lwres_gnbaresponse_t</type> structure. + </para> + + <para><function>lwres_gnbaresponse_free()</function> + and <function>lwres_gnbarequest_free()</function> release the + memory in resolver context <varname>ctx</varname> that was + allocated to the <type>lwres_gnbaresponse_t</type> or + <type>lwres_gnbarequest_t</type> structures referenced via + <varname>structp</varname>. Any memory associated with + ancillary buffers and strings for those structures is also + discarded. + </para> + </refsect1> + + <refsect1> + <title>RETURN VALUES</title> + <para> + The getnamebyaddr opcode functions + <function>lwres_gnbarequest_render()</function>, + <function>lwres_gnbaresponse_render()</function> + <function>lwres_gnbarequest_parse()</function> + and + <function>lwres_gnbaresponse_parse()</function> + all return + <errorcode>LWRES_R_SUCCESS</errorcode> + on success. + They return + <errorcode>LWRES_R_NOMEMORY</errorcode> + if memory allocation fails. + <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> + is returned if the available space in the buffer + <varname>b</varname> + is too small to accommodate the packet header or the + <type>lwres_gnbarequest_t</type> + and + <type>lwres_gnbaresponse_t</type> + structures. + <function>lwres_gnbarequest_parse()</function> + and + <function>lwres_gnbaresponse_parse()</function> + will return + <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> + if the buffer is not empty after decoding the received packet. + These functions will return + <errorcode>LWRES_R_FAILURE</errorcode> + if + <structfield>pktflags</structfield> + in the packet header structure + <type>lwres_lwpacket_t</type> + indicate that the packet is not a response to an earlier query. + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_gnba.html b/contrib/bind9/lib/lwres/man/lwres_gnba.html index 4d07580fd0e5..aac60c648e61 100644 --- a/contrib/bind9/lib/lwres/man/lwres_gnba.html +++ b/contrib/bind9/lib/lwres/man/lwres_gnba.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_gnba.html,v 1.6.2.1.4.11 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_gnba.html,v 1.7.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_gnba</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_gnbarequest_render, lwres_gnbaresponse_render, lwres_gnbarequest_parse, lwres_gnbaresponse_parse, lwres_gnbaresponse_free, lwres_gnbarequest_free — lightweight resolver getnamebyaddress message handling</p> @@ -39,31 +39,25 @@ lwres_result_t <b class="fsfunc">lwres_gnbarequest_render</b> (</code></td> -<td> </td> -<td> -<var class="pdparam">ctx</var>, </td> -</tr> -<tr> -<td> </td> -<td> </td> +<td>lwres_context_t * </td> <td> <var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gnbarequest_t * </td> <td> <var class="pdparam">req</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_lwpacket_t * </td> <td> <var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_buffer_t * </td> <td> <var class="pdparam">b</var><code>)</code>;</td> </tr> @@ -74,29 +68,27 @@ lwres_result_t lwres_result_t <b class="fsfunc">lwres_gnbaresponse_render</b> (</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_gnbaresponse_t * </td> +<td> +<var class="pdparam">req</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> +<var class="pdparam">b</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -104,29 +96,27 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_gnbarequest_parse</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gnbarequest_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -134,29 +124,27 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_gnbaresponse_parse</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gnbaresponse_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -165,19 +153,15 @@ lwres_result_t void <b class="fsfunc">lwres_gnbaresponse_free</b> (</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gnbaresponse_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> @@ -185,56 +169,59 @@ void <td><code class="funcdef"> void <b class="fsfunc">lwres_gnbarequest_free</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gnbarequest_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549540"></a><h2>DESCRIPTION</h2> +<a name="id2543525"></a><h2>DESCRIPTION</h2> <p> -These are low-level routines for creating and parsing -lightweight resolver address-to-name lookup request and -response messages. -</p> + These are low-level routines for creating and parsing + lightweight resolver address-to-name lookup request and + response messages. + </p> <p> -There are four main functions for the getnamebyaddr opcode. -One render function converts a getnamebyaddr request structure — -<span class="type">lwres_gnbarequest_t</span> — -to the lightweight resolver's canonical format. -It is complemented by a parse function that converts a packet in this -canonical format to a getnamebyaddr request structure. -Another render function converts the getnamebyaddr response structure — -<span class="type">lwres_gnbaresponse_t</span> -to the canonical format. -This is complemented by a parse function which converts a packet in -canonical format to a getnamebyaddr response structure. -</p> + There are four main functions for the getnamebyaddr opcode. + One render function converts a getnamebyaddr request structure — + <span class="type">lwres_gnbarequest_t</span> — + to the lightweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a getnamebyaddr request structure. + Another render function converts the getnamebyaddr response structure + — + <span class="type">lwres_gnbaresponse_t</span> + to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a getnamebyaddr response structure. + </p> <p> -These structures are defined in -<code class="filename">lwres/lwres.h</code>. -They are shown below. -</p> + These structures are defined in + <code class="filename">lwres/lwres.h</code>. + They are shown below. + </p> <pre class="programlisting"> #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U - +</pre> +<p> + </p> +<pre class="programlisting"> typedef struct { lwres_uint32_t flags; lwres_addr_t addr; } lwres_gnbarequest_t; - +</pre> +<p> + </p> +<pre class="programlisting"> typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -247,109 +234,83 @@ typedef struct { } lwres_gnbaresponse_t; </pre> <p> -</p> -<p> -<code class="function">lwres_gnbarequest_render()</code> -uses resolver context -<code class="varname">ctx</code> -to convert getnamebyaddr request structure -<code class="varname">req</code> -to canonical format. -The packet header structure -<code class="varname">pkt</code> -is initialised and transferred to -buffer -<code class="varname">b</code>. -The contents of -<code class="varname">*req</code> -are then appended to the buffer in canonical format. -<code class="function">lwres_gnbaresponse_render()</code> -performs the same task, except it converts a getnamebyaddr response structure -<span class="type">lwres_gnbaresponse_t</span> -to the lightweight resolver's canonical format. -</p> -<p> -<code class="function">lwres_gnbarequest_parse()</code> -uses context -<code class="varname">ctx</code> -to convert the contents of packet -<code class="varname">pkt</code> -to a -<span class="type">lwres_gnbarequest_t</span> -structure. -Buffer -<code class="varname">b</code> -provides space to be used for storing this structure. -When the function succeeds, the resulting -<span class="type">lwres_gnbarequest_t</span> -is made available through -<code class="varname">*structp</code>. -<code class="function">lwres_gnbaresponse_parse()</code> -offers the same semantics as -<code class="function">lwres_gnbarequest_parse()</code> -except it yields a -<span class="type">lwres_gnbaresponse_t</span> -structure. -</p> -<p> -<code class="function">lwres_gnbaresponse_free()</code> -and -<code class="function">lwres_gnbarequest_free()</code> -release the memory in resolver context -<code class="varname">ctx</code> -that was allocated to the -<span class="type">lwres_gnbaresponse_t</span> -or -<span class="type">lwres_gnbarequest_t</span> -structures referenced via -<code class="varname">structp</code>. -Any memory associated with ancillary buffers and strings for those -structures is also discarded. -</p> + </p> +<p><code class="function">lwres_gnbarequest_render()</code> + uses resolver context <code class="varname">ctx</code> to convert + getnamebyaddr request structure <code class="varname">req</code> to + canonical format. The packet header structure + <code class="varname">pkt</code> is initialised and transferred to buffer + <code class="varname">b</code>. The contents of <code class="varname">*req</code> + are then appended to the buffer in canonical format. + <code class="function">lwres_gnbaresponse_render()</code> performs the + same task, except it converts a getnamebyaddr response structure + <span class="type">lwres_gnbaresponse_t</span> to the lightweight resolver's + canonical format. + </p> +<p><code class="function">lwres_gnbarequest_parse()</code> + uses context <code class="varname">ctx</code> to convert the contents of + packet <code class="varname">pkt</code> to a + <span class="type">lwres_gnbarequest_t</span> structure. Buffer + <code class="varname">b</code> provides space to be used for storing this + structure. When the function succeeds, the resulting + <span class="type">lwres_gnbarequest_t</span> is made available through + <code class="varname">*structp</code>. + <code class="function">lwres_gnbaresponse_parse()</code> offers the same + semantics as <code class="function">lwres_gnbarequest_parse()</code> + except it yields a <span class="type">lwres_gnbaresponse_t</span> structure. + </p> +<p><code class="function">lwres_gnbaresponse_free()</code> + and <code class="function">lwres_gnbarequest_free()</code> release the + memory in resolver context <code class="varname">ctx</code> that was + allocated to the <span class="type">lwres_gnbaresponse_t</span> or + <span class="type">lwres_gnbarequest_t</span> structures referenced via + <code class="varname">structp</code>. Any memory associated with + ancillary buffers and strings for those structures is also + discarded. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549733"></a><h2>RETURN VALUES</h2> +<a name="id2543665"></a><h2>RETURN VALUES</h2> <p> -The getnamebyaddr opcode functions -<code class="function">lwres_gnbarequest_render()</code>, -<code class="function">lwres_gnbaresponse_render()</code> -<code class="function">lwres_gnbarequest_parse()</code> -and -<code class="function">lwres_gnbaresponse_parse()</code> -all return -<span class="errorcode">LWRES_R_SUCCESS</span> -on success. -They return -<span class="errorcode">LWRES_R_NOMEMORY</span> -if memory allocation fails. -<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> -is returned if the available space in the buffer -<code class="varname">b</code> -is too small to accommodate the packet header or the -<span class="type">lwres_gnbarequest_t</span> -and -<span class="type">lwres_gnbaresponse_t</span> -structures. -<code class="function">lwres_gnbarequest_parse()</code> -and -<code class="function">lwres_gnbaresponse_parse()</code> -will return -<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> -if the buffer is not empty after decoding the received packet. -These functions will return -<span class="errorcode">LWRES_R_FAILURE</span> -if -<em class="structfield"><code>pktflags</code></em> -in the packet header structure -<span class="type">lwres_lwpacket_t</span> -indicate that the packet is not a response to an earlier query. -</p> + The getnamebyaddr opcode functions + <code class="function">lwres_gnbarequest_render()</code>, + <code class="function">lwres_gnbaresponse_render()</code> + <code class="function">lwres_gnbarequest_parse()</code> + and + <code class="function">lwres_gnbaresponse_parse()</code> + all return + <span class="errorcode">LWRES_R_SUCCESS</span> + on success. + They return + <span class="errorcode">LWRES_R_NOMEMORY</span> + if memory allocation fails. + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + is returned if the available space in the buffer + <code class="varname">b</code> + is too small to accommodate the packet header or the + <span class="type">lwres_gnbarequest_t</span> + and + <span class="type">lwres_gnbaresponse_t</span> + structures. + <code class="function">lwres_gnbarequest_parse()</code> + and + <code class="function">lwres_gnbaresponse_parse()</code> + will return + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + if the buffer is not empty after decoding the received packet. + These functions will return + <span class="errorcode">LWRES_R_FAILURE</span> + if + <em class="structfield"><code>pktflags</code></em> + in the packet header structure + <span class="type">lwres_lwpacket_t</span> + indicate that the packet is not a response to an earlier query. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549866"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>. -</p> +<a name="id2543731"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_hstrerror.3 b/contrib/bind9/lib/lwres/man/lwres_hstrerror.3 index d6fc8f5feb7f..6fa744ea0c43 100644 --- a/contrib/bind9/lib/lwres/man/lwres_hstrerror.3 +++ b/contrib/bind9/lib/lwres/man/lwres_hstrerror.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_hstrerror.3,v 1.13.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_hstrerror.3,v 1.16.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_hstrerror .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,9 +36,9 @@ lwres_herror, lwres_hstrerror \- lightweight resolver error message generation #include <lwres/netdb.h> .fi .HP 18 -.BI "void lwres_herror(const\ char\ *s);" +.BI "void lwres_herror(const\ char\ *" "s" ");" .HP 29 -.BI "const char * lwres_hstrerror(int\ err);" +.BI "const char * lwres_hstrerror(int\ " "err" ");" .SH "DESCRIPTION" .PP \fBlwres_herror()\fR @@ -54,21 +54,31 @@ for the error code stored in the global variable \fBlwres_hstrerror()\fR returns an appropriate string for the error code gievn by \fIerr\fR. The values of the error codes and messages are as follows: -.TP 3n +.PP \fBNETDB_SUCCESS\fR +.RS 4 Resolver Error 0 (no error) -.TP 3n +.RE +.PP \fBHOST_NOT_FOUND\fR +.RS 4 Unknown host -.TP 3n +.RE +.PP \fBTRY_AGAIN\fR +.RS 4 Host name lookup failure -.TP 3n +.RE +.PP \fBNO_RECOVERY\fR +.RS 4 Unknown server error -.TP 3n +.RE +.PP \fBNO_DATA\fR +.RS 4 No address associated with name +.RE .SH "RETURN VALUES" .PP The string @@ -83,4 +93,7 @@ is not a valid error code. \fBherror\fR(3), \fBlwres_hstrerror\fR(3). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_hstrerror.docbook b/contrib/bind9/lib/lwres/man/lwres_hstrerror.docbook index a36c072ef394..8150e8c5fe17 100644 --- a/contrib/bind9/lib/lwres/man/lwres_hstrerror.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_hstrerror.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_hstrerror.docbook,v 1.4.206.3 2005/05/12 21:36:15 sra Exp $ --> - +<!-- $Id: lwres_hstrerror.docbook,v 1.5.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_hstrerror</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_hstrerror</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,95 +45,108 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_herror</refname> -<refname>lwres_hstrerror</refname> -<refpurpose>lightweight resolver error message generation</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_herror</refname> + <refname>lwres_hstrerror</refname> + <refpurpose>lightweight resolver error message generation</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_herror</function></funcdef> -<paramdef>const char *s</paramdef> -</funcprototype> + <paramdef>const char *<parameter>s</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> const char * <function>lwres_hstrerror</function></funcdef> -<paramdef>int err</paramdef> -</funcprototype> + <paramdef>int <parameter>err</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> + </refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> + <refsect1> + <title>DESCRIPTION</title> -<para> -<function>lwres_herror()</function> prints the string -<parameter>s</parameter> on <type>stderr</type> followed by the string -generated by <function>lwres_hstrerror()</function> for the error code -stored in the global variable <constant>lwres_h_errno</constant>. -</para> + <para><function>lwres_herror()</function> + prints the string <parameter>s</parameter> on + <type>stderr</type> followed by the string generated by + <function>lwres_hstrerror()</function> for the error code stored + in the global variable <constant>lwres_h_errno</constant>. + </para> -<para> -<function>lwres_hstrerror()</function> returns an appropriate string -for the error code gievn by <parameter>err</parameter>. The values of -the error codes and messages are as follows: + <para><function>lwres_hstrerror()</function> + returns an appropriate string for the error code gievn by + <parameter>err</parameter>. The values of the error codes and + messages are as follows: -<variablelist> -<varlistentry><term><errorcode>NETDB_SUCCESS</errorcode></term> -<listitem> -<para> -<errorname>Resolver Error 0 (no error)</errorname> -</para></listitem></varlistentry> -<varlistentry><term><errorcode>HOST_NOT_FOUND</errorcode></term> -<listitem> -<para> -<errorname>Unknown host</errorname> -</para></listitem></varlistentry> -<varlistentry><term><errorcode>TRY_AGAIN</errorcode></term> -<listitem> -<para> -<errorname>Host name lookup failure</errorname> -</para></listitem></varlistentry> -<varlistentry><term><errorcode>NO_RECOVERY</errorcode></term> -<listitem> -<para> -<errorname>Unknown server error</errorname> -</para></listitem></varlistentry> -<varlistentry><term><errorcode>NO_DATA</errorcode></term> -<listitem> -<para> -<errorname>No address associated with name</errorname> -</para></listitem></varlistentry> -</variablelist> -</para> -</refsect1> + <variablelist> + <varlistentry> + <term><errorcode>NETDB_SUCCESS</errorcode></term> + <listitem> + <para><errorname>Resolver Error 0 (no error)</errorname> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>HOST_NOT_FOUND</errorcode></term> + <listitem> + <para><errorname>Unknown host</errorname> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>TRY_AGAIN</errorcode></term> + <listitem> + <para><errorname>Host name lookup failure</errorname> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>NO_RECOVERY</errorcode></term> + <listitem> + <para><errorname>Unknown server error</errorname> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>NO_DATA</errorcode></term> + <listitem> + <para><errorname>No address associated with name</errorname> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> -The string <errorname>Unknown resolver error</errorname> is returned by -<function>lwres_hstrerror()</function> -when the value of -<constant>lwres_h_errno</constant> -is not a valid error code. -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>herror</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, + <refsect1> + <title>RETURN VALUES</title> + <para> + The string <errorname>Unknown resolver error</errorname> is returned by + <function>lwres_hstrerror()</function> + when the value of + <constant>lwres_h_errno</constant> + is not a valid error code. + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>herror</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, -<citerefentry> -<refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>. -</para> + <citerefentry> + <refentrytitle>lwres_hstrerror</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + </para> -</refsect1> -</refentry> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_hstrerror.html b/contrib/bind9/lib/lwres/man/lwres_hstrerror.html index d2f1e4aa706b..b52ff069decb 100644 --- a/contrib/bind9/lib/lwres/man/lwres_hstrerror.html +++ b/contrib/bind9/lib/lwres/man/lwres_hstrerror.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_hstrerror.html,v 1.5.2.1.4.12 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_hstrerror.html,v 1.6.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_hstrerror</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_herror, lwres_hstrerror — lightweight resolver error message generation</p> @@ -31,70 +31,74 @@ <h2>Synopsis</h2> <div class="funcsynopsis"> <pre class="funcsynopsisinfo">#include <lwres/netdb.h></pre> -<p><code class="funcdef"> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"><tr> +<td><code class="funcdef"> void -<b class="fsfunc">lwres_herror</b>(</code>const char *s<code>)</code>;</p> -<p><code class="funcdef"> +<b class="fsfunc">lwres_herror</b>(</code></td> +<td>const char * </td> +<td> +<var class="pdparam">s</var><code>)</code>;</td> +</tr></table> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> +<td><code class="funcdef"> const char * -<b class="fsfunc">lwres_hstrerror</b>(</code>int err<code>)</code>;</p> +<b class="fsfunc">lwres_hstrerror</b>(</code></td> +<td>int </td> +<td> +<var class="pdparam">err</var><code>)</code>;</td> +</tr></table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549424"></a><h2>DESCRIPTION</h2> -<p> -<code class="function">lwres_herror()</code> prints the string -<em class="parameter"><code>s</code></em> on <span class="type">stderr</span> followed by the string -generated by <code class="function">lwres_hstrerror()</code> for the error code -stored in the global variable <code class="constant">lwres_h_errno</code>. -</p> -<p> -<code class="function">lwres_hstrerror()</code> returns an appropriate string -for the error code gievn by <em class="parameter"><code>err</code></em>. The values of -the error codes and messages are as follows: +<a name="id2543379"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_herror()</code> + prints the string <em class="parameter"><code>s</code></em> on + <span class="type">stderr</span> followed by the string generated by + <code class="function">lwres_hstrerror()</code> for the error code stored + in the global variable <code class="constant">lwres_h_errno</code>. + </p> +<p><code class="function">lwres_hstrerror()</code> + returns an appropriate string for the error code gievn by + <em class="parameter"><code>err</code></em>. The values of the error codes and + messages are as follows: -</p> + </p> <div class="variablelist"><dl> <dt><span class="term"><span class="errorcode">NETDB_SUCCESS</span></span></dt> -<dd><p> -<span class="errorname">Resolver Error 0 (no error)</span> -</p></dd> +<dd><p><span class="errorname">Resolver Error 0 (no error)</span> + </p></dd> <dt><span class="term"><span class="errorcode">HOST_NOT_FOUND</span></span></dt> -<dd><p> -<span class="errorname">Unknown host</span> -</p></dd> +<dd><p><span class="errorname">Unknown host</span> + </p></dd> <dt><span class="term"><span class="errorcode">TRY_AGAIN</span></span></dt> -<dd><p> -<span class="errorname">Host name lookup failure</span> -</p></dd> +<dd><p><span class="errorname">Host name lookup failure</span> + </p></dd> <dt><span class="term"><span class="errorcode">NO_RECOVERY</span></span></dt> -<dd><p> -<span class="errorname">Unknown server error</span> -</p></dd> +<dd><p><span class="errorname">Unknown server error</span> + </p></dd> <dt><span class="term"><span class="errorcode">NO_DATA</span></span></dt> -<dd><p> -<span class="errorname">No address associated with name</span> -</p></dd> +<dd><p><span class="errorname">No address associated with name</span> + </p></dd> </dl></div> <p> -</p> + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549536"></a><h2>RETURN VALUES</h2> +<a name="id2543497"></a><h2>RETURN VALUES</h2> <p> -The string <span class="errorname">Unknown resolver error</span> is returned by -<code class="function">lwres_hstrerror()</code> -when the value of -<code class="constant">lwres_h_errno</code> -is not a valid error code. -</p> + The string <span class="errorname">Unknown resolver error</span> is returned by + <code class="function">lwres_hstrerror()</code> + when the value of + <code class="constant">lwres_h_errno</code> + is not a valid error code. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549555"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">herror</span>(3)</span>, +<a name="id2543517"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">herror</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>. -</p> + <span class="citerefentry"><span class="refentrytitle">lwres_hstrerror</span>(3)</span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_inetntop.3 b/contrib/bind9/lib/lwres/man/lwres_inetntop.3 index 6395e60099a7..4cb09f807610 100644 --- a/contrib/bind9/lib/lwres/man/lwres_inetntop.3 +++ b/contrib/bind9/lib/lwres/man/lwres_inetntop.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_inetntop.3,v 1.12.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_inetntop.3,v 1.15.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_inetntop .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,7 +36,7 @@ lwres_net_ntop \- lightweight resolver IP address presentation #include <lwres/net.h> .fi .HP 28 -.BI "const char * lwres_net_ntop(int\ af, const\ void\ *src, char\ *dst, size_t\ size);" +.BI "const char * lwres_net_ntop(int\ " "af" ", const\ void\ *" "src" ", char\ *" "dst" ", size_t\ " "size" ");" .SH "DESCRIPTION" .PP \fBlwres_net_ntop()\fR @@ -71,4 +71,7 @@ is not supported. \fBinet_ntop\fR(3), \fBerrno\fR(3). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_inetntop.docbook b/contrib/bind9/lib/lwres/man/lwres_inetntop.docbook index 651ef04d91bd..7b80fe41f39f 100644 --- a/contrib/bind9/lib/lwres/man/lwres_inetntop.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_inetntop.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_inetntop.docbook,v 1.3.206.3 2005/05/12 21:36:15 sra Exp $ --> - +<!-- $Id: lwres_inetntop.docbook,v 1.4.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_inetntop</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_inetntop</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,70 +45,76 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_net_ntop</refname> -<refpurpose>lightweight resolver IP address presentation</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_net_ntop</refname> + <refpurpose>lightweight resolver IP address presentation</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/net.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> const char * <function>lwres_net_ntop</function></funcdef> -<paramdef>int af</paramdef> -<paramdef>const void *src</paramdef> -<paramdef>char *dst</paramdef> -<paramdef>size_t size</paramdef> -</funcprototype> + <paramdef>int <parameter>af</parameter></paramdef> + <paramdef>const void *<parameter>src</parameter></paramdef> + <paramdef>char *<parameter>dst</parameter></paramdef> + <paramdef>size_t <parameter>size</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> + </refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> + <refsect1> + <title>DESCRIPTION</title> -<para> -<function>lwres_net_ntop()</function> converts an IP address of -protocol family <parameter>af</parameter> — IPv4 or IPv6 — -at location <parameter>src</parameter> from network format to its -conventional representation as a string. For IPv4 addresses, that -string would be a dotted-decimal. An IPv6 address would be -represented in colon notation as described in RFC1884. -</para> + <para><function>lwres_net_ntop()</function> + converts an IP address of protocol family + <parameter>af</parameter> — IPv4 or IPv6 — at + location <parameter>src</parameter> from network format to its + conventional representation as a string. For IPv4 addresses, + that string would be a dotted-decimal. An IPv6 address would be + represented in colon notation as described in RFC1884. + </para> -<para> -The generated string is copied to <parameter>dst</parameter> provided -<parameter>size</parameter> indicates it is long enough to store the -ASCII representation of the address. -</para> + <para> + The generated string is copied to <parameter>dst</parameter> + provided + <parameter>size</parameter> indicates it is long enough to + store the + ASCII representation of the address. + </para> -</refsect1> -<refsect1> -<title>RETURN VALUES</title> + </refsect1> + <refsect1> + <title>RETURN VALUES</title> -<para> -If successful, the function returns <parameter>dst</parameter>: -a pointer to a string containing the presentation format of the -address. <function>lwres_net_ntop()</function> returns -<type>NULL</type> and sets the global variable -<constant>errno</constant> to <errorcode>EAFNOSUPPORT</errorcode> if -the protocol family given in <parameter>af</parameter> is not -supported. -</para> + <para> + If successful, the function returns <parameter>dst</parameter>: + a pointer to a string containing the presentation format of the + address. <function>lwres_net_ntop()</function> returns + <type>NULL</type> and sets the global variable + <constant>errno</constant> to <errorcode>EAFNOSUPPORT</errorcode> if + the protocol family given in <parameter>af</parameter> is + not + supported. + </para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>RFC1884</refentrytitle> -</citerefentry>, -<citerefentry> -<refentrytitle>inet_ntop</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, -<citerefentry> -<refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>. -</para> -</refsect1> -</refentry> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>RFC1884</refentrytitle> + </citerefentry>, + <citerefentry> + <refentrytitle>inet_ntop</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_inetntop.html b/contrib/bind9/lib/lwres/man/lwres_inetntop.html index ca5c0bd693af..532d500ef1af 100644 --- a/contrib/bind9/lib/lwres/man/lwres_inetntop.html +++ b/contrib/bind9/lib/lwres/man/lwres_inetntop.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_inetntop.html,v 1.5.2.1.4.12 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_inetntop.html,v 1.6.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_inetntop</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_net_ntop — lightweight resolver IP address presentation</p> @@ -36,68 +36,68 @@ <td><code class="funcdef"> const char * <b class="fsfunc">lwres_net_ntop</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>int </td> +<td> +<var class="pdparam">af</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>const void * </td> +<td> +<var class="pdparam">src</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>char * </td> +<td> +<var class="pdparam">dst</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>size_t </td> <td> -<code>)</code>;</td> +<var class="pdparam">size</var><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549419"></a><h2>DESCRIPTION</h2> -<p> -<code class="function">lwres_net_ntop()</code> converts an IP address of -protocol family <em class="parameter"><code>af</code></em> — IPv4 or IPv6 — -at location <em class="parameter"><code>src</code></em> from network format to its -conventional representation as a string. For IPv4 addresses, that -string would be a dotted-decimal. An IPv6 address would be -represented in colon notation as described in RFC1884. -</p> +<a name="id2543379"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_net_ntop()</code> + converts an IP address of protocol family + <em class="parameter"><code>af</code></em> — IPv4 or IPv6 — at + location <em class="parameter"><code>src</code></em> from network format to its + conventional representation as a string. For IPv4 addresses, + that string would be a dotted-decimal. An IPv6 address would be + represented in colon notation as described in RFC1884. + </p> <p> -The generated string is copied to <em class="parameter"><code>dst</code></em> provided -<em class="parameter"><code>size</code></em> indicates it is long enough to store the -ASCII representation of the address. -</p> + The generated string is copied to <em class="parameter"><code>dst</code></em> + provided + <em class="parameter"><code>size</code></em> indicates it is long enough to + store the + ASCII representation of the address. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549452"></a><h2>RETURN VALUES</h2> +<a name="id2543411"></a><h2>RETURN VALUES</h2> <p> -If successful, the function returns <em class="parameter"><code>dst</code></em>: -a pointer to a string containing the presentation format of the -address. <code class="function">lwres_net_ntop()</code> returns -<span class="type">NULL</span> and sets the global variable -<code class="constant">errno</code> to <span class="errorcode">EAFNOSUPPORT</span> if -the protocol family given in <em class="parameter"><code>af</code></em> is not -supported. -</p> + If successful, the function returns <em class="parameter"><code>dst</code></em>: + a pointer to a string containing the presentation format of the + address. <code class="function">lwres_net_ntop()</code> returns + <span class="type">NULL</span> and sets the global variable + <code class="constant">errno</code> to <span class="errorcode">EAFNOSUPPORT</span> if + the protocol family given in <em class="parameter"><code>af</code></em> is + not + supported. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549483"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">RFC1884</span></span>, -<span class="citerefentry"><span class="refentrytitle">inet_ntop</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span>. -</p> +<a name="id2543444"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">RFC1884</span></span>, + <span class="citerefentry"><span class="refentrytitle">inet_ntop</span>(3)</span>, + <span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_noop.3 b/contrib/bind9/lib/lwres/man/lwres_noop.3 index e32c2f8020f1..78841096fb1b 100644 --- a/contrib/bind9/lib/lwres/man/lwres_noop.3 +++ b/contrib/bind9/lib/lwres/man/lwres_noop.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_noop.3,v 1.14.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_noop.3,v 1.17.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_noop .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,17 +36,17 @@ lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lw #include <lwres/lwres.h> .fi .HP 40 -.BI "lwres_result_t lwres_nooprequest_render(lwres_context_t\ *ctx, lwres_nooprequest_t\ *req, lwres_lwpacket_t\ *pkt, lwres_buffer_t\ *b);" +.BI "lwres_result_t lwres_nooprequest_render(lwres_context_t\ *" "ctx" ", lwres_nooprequest_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");" .HP 41 -.BI "lwres_result_t lwres_noopresponse_render(lwres_context_t\ *ctx, lwres_noopresponse_t\ *req, lwres_lwpacket_t\ *pkt, lwres_buffer_t\ *b);" +.BI "lwres_result_t lwres_noopresponse_render(lwres_context_t\ *" "ctx" ", lwres_noopresponse_t\ *" "req" ", lwres_lwpacket_t\ *" "pkt" ", lwres_buffer_t\ *" "b" ");" .HP 39 -.BI "lwres_result_t lwres_nooprequest_parse(lwres_context_t\ *ctx, lwres_buffer_t\ *b, lwres_lwpacket_t\ *pkt, lwres_nooprequest_t\ **structp);" +.BI "lwres_result_t lwres_nooprequest_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_nooprequest_t\ **" "structp" ");" .HP 40 -.BI "lwres_result_t lwres_noopresponse_parse(lwres_context_t\ *ctx, lwres_buffer_t\ *b, lwres_lwpacket_t\ *pkt, lwres_noopresponse_t\ **structp);" +.BI "lwres_result_t lwres_noopresponse_parse(lwres_context_t\ *" "ctx" ", lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ", lwres_noopresponse_t\ **" "structp" ");" .HP 29 -.BI "void lwres_noopresponse_free(lwres_context_t\ *ctx, lwres_noopresponse_t\ **structp);" +.BI "void lwres_noopresponse_free(lwres_context_t\ *" "ctx" ", lwres_noopresponse_t\ **" "structp" ");" .HP 28 -.BI "void lwres_nooprequest_free(lwres_context_t\ *ctx, lwres_nooprequest_t\ **structp);" +.BI "void lwres_nooprequest_free(lwres_context_t\ *" "ctx" ", lwres_nooprequest_t\ **" "structp" ");" .SH "DESCRIPTION" .PP These are low\-level routines for creating and parsing lightweight resolver no\-op request and response messages. @@ -63,14 +63,26 @@ to the canonical format. This is complemented by a parse function which converts .PP These structures are defined in \fIlwres/lwres.h\fR. They are shown below. -.sp -.RS 3n +.PP +.RS 4 .nf #define LWRES_OPCODE_NOOP 0x00000000U +.fi +.RE +.sp +.PP +.RS 4 +.nf typedef struct { lwres_uint16_t datalength; unsigned char *data; } lwres_nooprequest_t; +.fi +.RE +.sp +.PP +.RS 4 +.nf typedef struct { lwres_uint16_t datalength; unsigned char *data; @@ -78,6 +90,7 @@ typedef struct { .fi .RE .sp +.PP Although the structures have different types, they are identical. This is because the no\-op opcode simply echos whatever data was sent: the response is therefore identical to the request. .PP \fBlwres_nooprequest_render()\fR @@ -162,6 +175,9 @@ in the packet header structure indicate that the packet is not a response to an earlier query. .SH "SEE ALSO" .PP -\fBlwres_packet\fR(3 ) +\fBlwres_packet\fR(3) .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_noop.docbook b/contrib/bind9/lib/lwres/man/lwres_noop.docbook index fcb3c5933ab7..cef6d875db24 100644 --- a/contrib/bind9/lib/lwres/man/lwres_noop.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_noop.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_noop.docbook,v 1.4.206.3 2005/05/12 21:36:16 sra Exp $ --> - +<!-- $Id: lwres_noop.docbook,v 1.5.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_noop</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_noop</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,200 +45,211 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_nooprequest_render</refname> -<refname>lwres_noopresponse_render</refname> -<refname>lwres_nooprequest_parse</refname> -<refname>lwres_noopresponse_parse</refname> -<refname>lwres_noopresponse_free</refname> -<refname>lwres_nooprequest_free</refname> -<refpurpose>lightweight resolver no-op message handling</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_nooprequest_render</refname> + <refname>lwres_noopresponse_render</refname> + <refname>lwres_nooprequest_parse</refname> + <refname>lwres_noopresponse_parse</refname> + <refname>lwres_noopresponse_free</refname> + <refname>lwres_nooprequest_free</refname> + <refpurpose>lightweight resolver no-op message handling</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo> #include <lwres/lwres.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_nooprequest_render</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_nooprequest_t *req</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_nooprequest_t *<parameter>req</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_noopresponse_render</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_noopresponse_t *req</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_noopresponse_t *<parameter>req</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_nooprequest_parse</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_nooprequest_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_noopresponse_parse</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -<paramdef>lwres_noopresponse_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_noopresponse_free</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_noopresponse_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_noopresponse_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> void <function>lwres_nooprequest_free</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_nooprequest_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_nooprequest_t **<parameter>structp</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> -<para> -These are low-level routines for creating and parsing -lightweight resolver no-op request and response messages. -</para> -<para> -The no-op message is analogous to a <command>ping</command> packet: -a packet is sent to the resolver daemon and is simply echoed back. -The opcode is intended to allow a client to determine if the server is -operational or not. -</para> -<para> -There are four main functions for the no-op opcode. -One render function converts a no-op request structure — -<type>lwres_nooprequest_t</type> — -to the lighweight resolver's canonical format. -It is complemented by a parse function that converts a packet in this -canonical format to a no-op request structure. -Another render function converts the no-op response structure — -<type>lwres_noopresponse_t</type> -to the canonical format. -This is complemented by a parse function which converts a packet in -canonical format to a no-op response structure. -</para> -<para> -These structures are defined in -<filename>lwres/lwres.h</filename>. + </refsynopsisdiv> + <refsect1> + <title>DESCRIPTION</title> + <para> + These are low-level routines for creating and parsing + lightweight resolver no-op request and response messages. + </para> + <para> + The no-op message is analogous to a <command>ping</command> + packet: + a packet is sent to the resolver daemon and is simply echoed back. + The opcode is intended to allow a client to determine if the server is + operational or not. + </para> + <para> + There are four main functions for the no-op opcode. + One render function converts a no-op request structure — + <type>lwres_nooprequest_t</type> — + to the lighweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a no-op request structure. + Another render function converts the no-op response structure — + <type>lwres_noopresponse_t</type> + to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a no-op response structure. + </para> + <para> + These structures are defined in + <filename>lwres/lwres.h</filename>. -They are shown below. -<programlisting> + They are shown below. + </para> + <para><programlisting> #define LWRES_OPCODE_NOOP 0x00000000U - +</programlisting> + </para> + <para><programlisting> typedef struct { lwres_uint16_t datalength; unsigned char *data; } lwres_nooprequest_t; - +</programlisting> + </para> + <para><programlisting> typedef struct { lwres_uint16_t datalength; unsigned char *data; } lwres_noopresponse_t; </programlisting> -Although the structures have different types, they are identical. -This is because the no-op opcode simply echos whatever data was sent: -the response is therefore identical to the request. -</para> + </para> + <para> + Although the structures have different types, they are identical. + This is because the no-op opcode simply echos whatever data was sent: + the response is therefore identical to the request. + </para> -<para> -<function>lwres_nooprequest_render()</function> uses resolver -context <parameter>ctx</parameter> to convert no-op request structure -<parameter>req</parameter> to canonical format. The packet header -structure <parameter>pkt</parameter> is initialised and transferred to -buffer <parameter>b</parameter>. The contents of -<parameter>*req</parameter> are then appended to the buffer in -canonical format. <function>lwres_noopresponse_render()</function> -performs the same task, except it converts a no-op response structure -<type>lwres_noopresponse_t</type> to the lightweight resolver's -canonical format. -</para> + <para><function>lwres_nooprequest_render()</function> + uses resolver context <parameter>ctx</parameter> to convert + no-op request structure <parameter>req</parameter> to canonical + format. The packet header structure <parameter>pkt</parameter> + is initialised and transferred to buffer + <parameter>b</parameter>. The contents of + <parameter>*req</parameter> are then appended to the buffer in + canonical format. + <function>lwres_noopresponse_render()</function> performs the + same task, except it converts a no-op response structure + <type>lwres_noopresponse_t</type> to the lightweight resolver's + canonical format. + </para> -<para> -<function>lwres_nooprequest_parse()</function> uses context -<parameter>ctx</parameter> to convert the contents of packet -<parameter>pkt</parameter> to a <type>lwres_nooprequest_t</type> -structure. Buffer <parameter>b</parameter> provides space to be used -for storing this structure. When the function succeeds, the resulting -<type>lwres_nooprequest_t</type> is made available through -<parameter>*structp</parameter>. -<function>lwres_noopresponse_parse()</function> offers the same -semantics as <function>lwres_nooprequest_parse()</function> except it -yields a <type>lwres_noopresponse_t</type> structure. -</para> + <para><function>lwres_nooprequest_parse()</function> + uses context <parameter>ctx</parameter> to convert the contents + of packet <parameter>pkt</parameter> to a + <type>lwres_nooprequest_t</type> structure. Buffer + <parameter>b</parameter> provides space to be used for storing + this structure. When the function succeeds, the resulting + <type>lwres_nooprequest_t</type> is made available through + <parameter>*structp</parameter>. + <function>lwres_noopresponse_parse()</function> offers the same + semantics as <function>lwres_nooprequest_parse()</function> + except it yields a <type>lwres_noopresponse_t</type> structure. + </para> -<para> -<function>lwres_noopresponse_free()</function> and -<function>lwres_nooprequest_free()</function> release the memory in -resolver context <parameter>ctx</parameter> that was allocated to the -<type>lwres_noopresponse_t</type> or <type>lwres_nooprequest_t</type> -structures referenced via <parameter>structp</parameter>. -</para> + <para><function>lwres_noopresponse_free()</function> + and <function>lwres_nooprequest_free()</function> release the + memory in resolver context <parameter>ctx</parameter> that was + allocated to the <type>lwres_noopresponse_t</type> or + <type>lwres_nooprequest_t</type> structures referenced via + <parameter>structp</parameter>. + </para> -</refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> -The no-op opcode functions -<function>lwres_nooprequest_render()</function>, + </refsect1> + <refsect1> + <title>RETURN VALUES</title> + <para> + The no-op opcode functions + <function>lwres_nooprequest_render()</function>, -<function>lwres_noopresponse_render()</function> -<function>lwres_nooprequest_parse()</function> -and -<function>lwres_noopresponse_parse()</function> -all return -<errorcode>LWRES_R_SUCCESS</errorcode> -on success. -They return -<errorcode>LWRES_R_NOMEMORY</errorcode> -if memory allocation fails. -<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> -is returned if the available space in the buffer -<parameter>b</parameter> -is too small to accommodate the packet header or the -<type>lwres_nooprequest_t</type> -and -<type>lwres_noopresponse_t</type> -structures. -<function>lwres_nooprequest_parse()</function> -and -<function>lwres_noopresponse_parse()</function> -will return -<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> -if the buffer is not empty after decoding the received packet. -These functions will return -<errorcode>LWRES_R_FAILURE</errorcode> -if -<constant>pktflags</constant> -in the packet header structure -<type>lwres_lwpacket_t</type> -indicate that the packet is not a response to an earlier query. -</para> -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>lwres_packet</refentrytitle><manvolnum>3 -</manvolnum> -</citerefentry> -</para> -</refsect1> -</refentry> + <function>lwres_noopresponse_render()</function> + <function>lwres_nooprequest_parse()</function> + and + <function>lwres_noopresponse_parse()</function> + all return + <errorcode>LWRES_R_SUCCESS</errorcode> + on success. + They return + <errorcode>LWRES_R_NOMEMORY</errorcode> + if memory allocation fails. + <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> + is returned if the available space in the buffer + <parameter>b</parameter> + is too small to accommodate the packet header or the + <type>lwres_nooprequest_t</type> + and + <type>lwres_noopresponse_t</type> + structures. + <function>lwres_nooprequest_parse()</function> + and + <function>lwres_noopresponse_parse()</function> + will return + <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> + if the buffer is not empty after decoding the received packet. + These functions will return + <errorcode>LWRES_R_FAILURE</errorcode> + if + <constant>pktflags</constant> + in the packet header structure + <type>lwres_lwpacket_t</type> + indicate that the packet is not a response to an earlier query. + </para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>lwres_packet</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + </para> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_noop.html b/contrib/bind9/lib/lwres/man/lwres_noop.html index 145bcac0844e..4705ecbf0eed 100644 --- a/contrib/bind9/lib/lwres/man/lwres_noop.html +++ b/contrib/bind9/lib/lwres/man/lwres_noop.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_noop.html,v 1.7.2.1.4.11 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_noop.html,v 1.8.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_noop</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_nooprequest_render, lwres_noopresponse_render, lwres_nooprequest_parse, lwres_noopresponse_parse, lwres_noopresponse_free, lwres_nooprequest_free — lightweight resolver no-op message handling</p> @@ -37,29 +37,27 @@ <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_nooprequest_render</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_nooprequest_t * </td> +<td> +<var class="pdparam">req</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> +<var class="pdparam">b</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -67,29 +65,27 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_noopresponse_render</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_noopresponse_t * </td> +<td> +<var class="pdparam">req</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_buffer_t * </td> <td> -<code>)</code>;</td> +<var class="pdparam">b</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -97,29 +93,27 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_nooprequest_parse</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_nooprequest_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -127,29 +121,27 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_noopresponse_parse</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_lwpacket_t * </td> +<td> +<var class="pdparam">pkt</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_noopresponse_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -157,19 +149,15 @@ lwres_result_t <td><code class="funcdef"> void <b class="fsfunc">lwres_noopresponse_free</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_noopresponse_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> @@ -177,149 +165,153 @@ void <td><code class="funcdef"> void <b class="fsfunc">lwres_nooprequest_free</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_nooprequest_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549528"></a><h2>DESCRIPTION</h2> +<a name="id2543522"></a><h2>DESCRIPTION</h2> <p> -These are low-level routines for creating and parsing -lightweight resolver no-op request and response messages. -</p> + These are low-level routines for creating and parsing + lightweight resolver no-op request and response messages. + </p> <p> -The no-op message is analogous to a <span><strong class="command">ping</strong></span> packet: -a packet is sent to the resolver daemon and is simply echoed back. -The opcode is intended to allow a client to determine if the server is -operational or not. -</p> + The no-op message is analogous to a <span><strong class="command">ping</strong></span> + packet: + a packet is sent to the resolver daemon and is simply echoed back. + The opcode is intended to allow a client to determine if the server is + operational or not. + </p> <p> -There are four main functions for the no-op opcode. -One render function converts a no-op request structure — -<span class="type">lwres_nooprequest_t</span> — -to the lighweight resolver's canonical format. -It is complemented by a parse function that converts a packet in this -canonical format to a no-op request structure. -Another render function converts the no-op response structure — -<span class="type">lwres_noopresponse_t</span> -to the canonical format. -This is complemented by a parse function which converts a packet in -canonical format to a no-op response structure. -</p> + There are four main functions for the no-op opcode. + One render function converts a no-op request structure — + <span class="type">lwres_nooprequest_t</span> — + to the lighweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a no-op request structure. + Another render function converts the no-op response structure — + <span class="type">lwres_noopresponse_t</span> + to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a no-op response structure. + </p> <p> -These structures are defined in -<code class="filename">lwres/lwres.h</code>. + These structures are defined in + <code class="filename">lwres/lwres.h</code>. -They are shown below. -</p> + They are shown below. + </p> <pre class="programlisting"> #define LWRES_OPCODE_NOOP 0x00000000U - +</pre> +<p> + </p> +<pre class="programlisting"> typedef struct { lwres_uint16_t datalength; unsigned char *data; } lwres_nooprequest_t; - +</pre> +<p> + </p> +<pre class="programlisting"> typedef struct { lwres_uint16_t datalength; unsigned char *data; } lwres_noopresponse_t; </pre> <p> -Although the structures have different types, they are identical. -This is because the no-op opcode simply echos whatever data was sent: -the response is therefore identical to the request. -</p> -<p> -<code class="function">lwres_nooprequest_render()</code> uses resolver -context <em class="parameter"><code>ctx</code></em> to convert no-op request structure -<em class="parameter"><code>req</code></em> to canonical format. The packet header -structure <em class="parameter"><code>pkt</code></em> is initialised and transferred to -buffer <em class="parameter"><code>b</code></em>. The contents of -<em class="parameter"><code>*req</code></em> are then appended to the buffer in -canonical format. <code class="function">lwres_noopresponse_render()</code> -performs the same task, except it converts a no-op response structure -<span class="type">lwres_noopresponse_t</span> to the lightweight resolver's -canonical format. -</p> + </p> <p> -<code class="function">lwres_nooprequest_parse()</code> uses context -<em class="parameter"><code>ctx</code></em> to convert the contents of packet -<em class="parameter"><code>pkt</code></em> to a <span class="type">lwres_nooprequest_t</span> -structure. Buffer <em class="parameter"><code>b</code></em> provides space to be used -for storing this structure. When the function succeeds, the resulting -<span class="type">lwres_nooprequest_t</span> is made available through -<em class="parameter"><code>*structp</code></em>. -<code class="function">lwres_noopresponse_parse()</code> offers the same -semantics as <code class="function">lwres_nooprequest_parse()</code> except it -yields a <span class="type">lwres_noopresponse_t</span> structure. -</p> -<p> -<code class="function">lwres_noopresponse_free()</code> and -<code class="function">lwres_nooprequest_free()</code> release the memory in -resolver context <em class="parameter"><code>ctx</code></em> that was allocated to the -<span class="type">lwres_noopresponse_t</span> or <span class="type">lwres_nooprequest_t</span> -structures referenced via <em class="parameter"><code>structp</code></em>. -</p> + Although the structures have different types, they are identical. + This is because the no-op opcode simply echos whatever data was sent: + the response is therefore identical to the request. + </p> +<p><code class="function">lwres_nooprequest_render()</code> + uses resolver context <em class="parameter"><code>ctx</code></em> to convert + no-op request structure <em class="parameter"><code>req</code></em> to canonical + format. The packet header structure <em class="parameter"><code>pkt</code></em> + is initialised and transferred to buffer + <em class="parameter"><code>b</code></em>. The contents of + <em class="parameter"><code>*req</code></em> are then appended to the buffer in + canonical format. + <code class="function">lwres_noopresponse_render()</code> performs the + same task, except it converts a no-op response structure + <span class="type">lwres_noopresponse_t</span> to the lightweight resolver's + canonical format. + </p> +<p><code class="function">lwres_nooprequest_parse()</code> + uses context <em class="parameter"><code>ctx</code></em> to convert the contents + of packet <em class="parameter"><code>pkt</code></em> to a + <span class="type">lwres_nooprequest_t</span> structure. Buffer + <em class="parameter"><code>b</code></em> provides space to be used for storing + this structure. When the function succeeds, the resulting + <span class="type">lwres_nooprequest_t</span> is made available through + <em class="parameter"><code>*structp</code></em>. + <code class="function">lwres_noopresponse_parse()</code> offers the same + semantics as <code class="function">lwres_nooprequest_parse()</code> + except it yields a <span class="type">lwres_noopresponse_t</span> structure. + </p> +<p><code class="function">lwres_noopresponse_free()</code> + and <code class="function">lwres_nooprequest_free()</code> release the + memory in resolver context <em class="parameter"><code>ctx</code></em> that was + allocated to the <span class="type">lwres_noopresponse_t</span> or + <span class="type">lwres_nooprequest_t</span> structures referenced via + <em class="parameter"><code>structp</code></em>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549797"></a><h2>RETURN VALUES</h2> +<a name="id2543672"></a><h2>RETURN VALUES</h2> <p> -The no-op opcode functions -<code class="function">lwres_nooprequest_render()</code>, + The no-op opcode functions + <code class="function">lwres_nooprequest_render()</code>, -<code class="function">lwres_noopresponse_render()</code> -<code class="function">lwres_nooprequest_parse()</code> -and -<code class="function">lwres_noopresponse_parse()</code> -all return -<span class="errorcode">LWRES_R_SUCCESS</span> -on success. -They return -<span class="errorcode">LWRES_R_NOMEMORY</span> -if memory allocation fails. -<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> -is returned if the available space in the buffer -<em class="parameter"><code>b</code></em> -is too small to accommodate the packet header or the -<span class="type">lwres_nooprequest_t</span> -and -<span class="type">lwres_noopresponse_t</span> -structures. -<code class="function">lwres_nooprequest_parse()</code> -and -<code class="function">lwres_noopresponse_parse()</code> -will return -<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> -if the buffer is not empty after decoding the received packet. -These functions will return -<span class="errorcode">LWRES_R_FAILURE</span> -if -<code class="constant">pktflags</code> -in the packet header structure -<span class="type">lwres_lwpacket_t</span> -indicate that the packet is not a response to an earlier query. -</p> + <code class="function">lwres_noopresponse_render()</code> + <code class="function">lwres_nooprequest_parse()</code> + and + <code class="function">lwres_noopresponse_parse()</code> + all return + <span class="errorcode">LWRES_R_SUCCESS</span> + on success. + They return + <span class="errorcode">LWRES_R_NOMEMORY</span> + if memory allocation fails. + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + is returned if the available space in the buffer + <em class="parameter"><code>b</code></em> + is too small to accommodate the packet header or the + <span class="type">lwres_nooprequest_t</span> + and + <span class="type">lwres_noopresponse_t</span> + structures. + <code class="function">lwres_nooprequest_parse()</code> + and + <code class="function">lwres_noopresponse_parse()</code> + will return + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + if the buffer is not empty after decoding the received packet. + These functions will return + <span class="errorcode">LWRES_R_FAILURE</span> + if + <code class="constant">pktflags</code> + in the packet header structure + <span class="type">lwres_lwpacket_t</span> + indicate that the packet is not a response to an earlier query. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549861"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3 -)</span> -</p> +<a name="id2543738"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">lwres_packet</span>(3)</span> + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_packet.3 b/contrib/bind9/lib/lwres/man/lwres_packet.3 index 35a8f10ca88d..141090852f50 100644 --- a/contrib/bind9/lib/lwres/man/lwres_packet.3 +++ b/contrib/bind9/lib/lwres/man/lwres_packet.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_packet.3,v 1.15.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_packet.3,v 1.18.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_packet .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,19 +36,25 @@ lwres_lwpacket_renderheader, lwres_lwpacket_parseheader \- lightweight resolver #include <lwres/lwpacket.h> .fi .HP 43 -.BI "lwres_result_t lwres_lwpacket_renderheader(lwres_buffer_t\ *b, lwres_lwpacket_t\ *pkt);" +.BI "lwres_result_t lwres_lwpacket_renderheader(lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ");" .HP 42 -.BI "lwres_result_t lwres_lwpacket_parseheader(lwres_buffer_t\ *b, lwres_lwpacket_t\ *pkt);" +.BI "lwres_result_t lwres_lwpacket_parseheader(lwres_buffer_t\ *" "b" ", lwres_lwpacket_t\ *" "pkt" ");" .SH "DESCRIPTION" .PP These functions rely on a \fBstruct lwres_lwpacket\fR which is defined in \fIlwres/lwpacket.h\fR. -.sp -.RS 3n +.PP +.RS 4 .nf typedef struct lwres_lwpacket lwres_lwpacket_t; +.fi +.RE +.sp +.PP +.RS 4 +.nf struct lwres_lwpacket { lwres_uint32_t length; lwres_uint16_t version; @@ -65,45 +71,69 @@ struct lwres_lwpacket { .sp .PP The elements of this structure are: -.TP 3n +.PP \fBlength\fR +.RS 4 the overall packet length, including the entire packet header. This field is filled in by the lwres_gabn_*() and lwres_gnba_*() calls. -.TP 3n +.RE +.PP \fBversion\fR +.RS 4 the header format. There is currently only one format, \fBLWRES_LWPACKETVERSION_0\fR. This field is filled in by the lwres_gabn_*() and lwres_gnba_*() calls. -.TP 3n +.RE +.PP \fBpktflags\fR +.RS 4 library\-defined flags for this packet: for instance whether the packet is a request or a reply. Flag values can be set, but not defined by the caller. This field is filled in by the application wit the exception of the LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the lwres_gabn_*() and lwres_gnba_*() calls. -.TP 3n +.RE +.PP \fBserial\fR +.RS 4 is set by the requestor and is returned in all replies. If two or more packets from the same source have the same serial number and are from the same source, they are assumed to be duplicates and the latter ones may be dropped. This field must be set by the application. -.TP 3n +.RE +.PP \fBopcode\fR +.RS 4 indicates the operation. Opcodes between 0x00000000 and 0x03ffffff are reserved for use by the lightweight resolver library. Opcodes between 0x04000000 and 0xffffffff are application defined. This field is filled in by the lwres_gabn_*() and lwres_gnba_*() calls. -.TP 3n +.RE +.PP \fBresult\fR +.RS 4 is only valid for replies. Results between 0x04000000 and 0xffffffff are application defined. Results between 0x00000000 and 0x03ffffff are reserved for library use. This field is filled in by the lwres_gabn_*() and lwres_gnba_*() calls. -.TP 3n +.RE +.PP \fBrecvlength\fR +.RS 4 is the maximum buffer size that the receiver can handle on requests and the size of the buffer needed to satisfy a request when the buffer is too large for replies. This field is supplied by the application. -.TP 3n +.RE +.PP \fBauthtype\fR +.RS 4 defines the packet level authentication that is used. Authorisation types between 0x1000 and 0xffff are application defined and types between 0x0000 and 0x0fff are reserved for library use. Currently these are not used and must be zero. -.TP 3n +.RE +.PP \fBauthlen\fR +.RS 4 gives the length of the authentication data. Since packet authentication is currently not used, this must be zero. +.RE .PP The following opcodes are currently defined: -.TP 3n +.PP \fBNOOP\fR +.RS 4 Success is always returned and the packet contents are echoed. The lwres_noop_*() functions should be used for this type. -.TP 3n +.RE +.PP \fBGETADDRSBYNAME\fR +.RS 4 returns all known addresses for a given name. The lwres_gabn_*() functions should be used for this type. -.TP 3n +.RE +.PP \fBGETNAMEBYADDR\fR +.RS 4 return the hostname for the given address. The lwres_gnba_*() functions should be used for this type. +.RE .PP \fBlwres_lwpacket_renderheader()\fR transfers the contents of lightweight resolver packet structure @@ -134,4 +164,7 @@ and lightweight resolver packet both functions return \fBLWRES_R_UNEXPECTEDEND\fR. .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_packet.docbook b/contrib/bind9/lib/lwres/man/lwres_packet.docbook index 226f9942c9ae..71b3e1bc881d 100644 --- a/contrib/bind9/lib/lwres/man/lwres_packet.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_packet.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_packet.docbook,v 1.6.206.3 2005/05/12 21:36:16 sra Exp $ --> - +<!-- $Id: lwres_packet.docbook,v 1.7.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> -<refentrytitle>lwres_packet</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_packet</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,41 +45,44 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_lwpacket_renderheader</refname> -<refname>lwres_lwpacket_parseheader</refname> -<refpurpose>lightweight resolver packet handling functions</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_lwpacket_renderheader</refname> + <refname>lwres_lwpacket_parseheader</refname> + <refpurpose>lightweight resolver packet handling functions</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/lwpacket.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_lwpacket_renderheader</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_lwpacket_parseheader</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_lwpacket_t *pkt</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_lwpacket_t *<parameter>pkt</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> -<refsect1> -<title>DESCRIPTION</title> -<para> -These functions rely on a -<type>struct lwres_lwpacket</type> -which is defined in -<filename>lwres/lwpacket.h</filename>. + </refsynopsisdiv> + <refsect1> + <title>DESCRIPTION</title> + <para> + These functions rely on a + <type>struct lwres_lwpacket</type> + which is defined in + <filename>lwres/lwpacket.h</filename>. + </para> -<programlisting> + <para><programlisting> typedef struct lwres_lwpacket lwres_lwpacket_t; - + </programlisting> + </para> + <para><programlisting> struct lwres_lwpacket { lwres_uint32_t length; lwres_uint16_t version; @@ -92,142 +95,197 @@ struct lwres_lwpacket { lwres_uint16_t authlength; }; </programlisting> -</para> + </para> -<para> -The elements of this structure are: -<variablelist> -<varlistentry><term><constant>length</constant></term> -<listitem> -<para> -the overall packet length, including the entire packet header. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. -</para></listitem></varlistentry> -<varlistentry><term><constant>version</constant></term> -<listitem> -<para> -the header format. There is currently only one format, -<type>LWRES_LWPACKETVERSION_0</type>. + <para> + The elements of this structure are: + <variablelist> + <varlistentry> + <term><constant>length</constant></term> + <listitem> + <para> + the overall packet length, including the entire packet header. + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>version</constant></term> + <listitem> + <para> + the header format. There is currently only one format, + <type>LWRES_LWPACKETVERSION_0</type>. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. -</para></listitem></varlistentry> -<varlistentry><term><constant>pktflags</constant></term> -<listitem> -<para> -library-defined flags for this packet: for instance whether the packet -is a request or a reply. Flag values can be set, but not defined by -the caller. -This field is filled in by the application wit the exception of the -LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the -lwres_gabn_*() and lwres_gnba_*() calls. -</para></listitem></varlistentry> -<varlistentry><term><constant>serial</constant></term> -<listitem> -<para> -is set by the requestor and is returned in all replies. If two or more -packets from the same source have the same serial number and are from -the same source, they are assumed to be duplicates and the latter ones -may be dropped. -This field must be set by the application. -</para></listitem></varlistentry> -<varlistentry><term><constant>opcode</constant></term> -<listitem> -<para> -indicates the operation. -Opcodes between 0x00000000 and 0x03ffffff are -reserved for use by the lightweight resolver library. Opcodes between -0x04000000 and 0xffffffff are application defined. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. -</para></listitem></varlistentry> -<varlistentry><term><constant>result</constant></term> -<listitem> -<para> -is only valid for replies. -Results between 0x04000000 and 0xffffffff are application defined. -Results between 0x00000000 and 0x03ffffff are reserved for library use. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. -</para></listitem></varlistentry> -<varlistentry><term><constant>recvlength</constant></term> -<listitem> -<para> -is the maximum buffer size that the receiver can handle on requests -and the size of the buffer needed to satisfy a request when the buffer -is too large for replies. -This field is supplied by the application. -</para></listitem></varlistentry> -<varlistentry><term><constant>authtype</constant></term> -<listitem> -<para> -defines the packet level authentication that is used. -Authorisation types between 0x1000 and 0xffff are application defined -and types between 0x0000 and 0x0fff are reserved for library use. -Currently these are not used and must be zero. -</para></listitem></varlistentry> -<varlistentry><term><constant>authlen</constant></term> -<listitem> -<para> -gives the length of the authentication data. -Since packet authentication is currently not used, this must be zero. -</para></listitem></varlistentry> -</variablelist> -</para> -<para> -The following opcodes are currently defined: -<variablelist> -<varlistentry><term><constant>NOOP</constant></term> -<listitem> -<para> -Success is always returned and the packet contents are echoed. -The lwres_noop_*() functions should be used for this type. -</para></listitem></varlistentry> -<varlistentry><term><constant>GETADDRSBYNAME</constant></term> -<listitem> -<para> -returns all known addresses for a given name. -The lwres_gabn_*() functions should be used for this type. -</para></listitem></varlistentry> -<varlistentry><term><constant>GETNAMEBYADDR</constant></term> -<listitem> -<para> -return the hostname for the given address. -The lwres_gnba_*() functions should be used for this type. -</para></listitem></varlistentry> -</variablelist> -</para> + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>pktflags</constant></term> + <listitem> + <para> + library-defined flags for this packet: for instance whether the + packet + is a request or a reply. Flag values can be set, but not defined + by + the caller. + This field is filled in by the application wit the exception of + the + LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in + the + lwres_gabn_*() and lwres_gnba_*() calls. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>serial</constant></term> + <listitem> + <para> + is set by the requestor and is returned in all replies. If two + or more + packets from the same source have the same serial number and are + from + the same source, they are assumed to be duplicates and the + latter ones + may be dropped. + This field must be set by the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>opcode</constant></term> + <listitem> + <para> + indicates the operation. + Opcodes between 0x00000000 and 0x03ffffff are + reserved for use by the lightweight resolver library. Opcodes + between + 0x04000000 and 0xffffffff are application defined. + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>result</constant></term> + <listitem> + <para> + is only valid for replies. + Results between 0x04000000 and 0xffffffff are application + defined. + Results between 0x00000000 and 0x03ffffff are reserved for + library use. + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>recvlength</constant></term> + <listitem> + <para> + is the maximum buffer size that the receiver can handle on + requests + and the size of the buffer needed to satisfy a request when the + buffer + is too large for replies. + This field is supplied by the application. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>authtype</constant></term> + <listitem> + <para> + defines the packet level authentication that is used. + Authorisation types between 0x1000 and 0xffff are application + defined + and types between 0x0000 and 0x0fff are reserved for library + use. + Currently these are not used and must be zero. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>authlen</constant></term> + <listitem> + <para> + gives the length of the authentication data. + Since packet authentication is currently not used, this must be + zero. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + The following opcodes are currently defined: + <variablelist> + <varlistentry> + <term><constant>NOOP</constant></term> + <listitem> + <para> + Success is always returned and the packet contents are echoed. + The lwres_noop_*() functions should be used for this type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>GETADDRSBYNAME</constant></term> + <listitem> + <para> + returns all known addresses for a given name. + The lwres_gabn_*() functions should be used for this type. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>GETNAMEBYADDR</constant></term> + <listitem> + <para> + return the hostname for the given address. + The lwres_gnba_*() functions should be used for this type. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> -<para> -<function>lwres_lwpacket_renderheader()</function> transfers the -contents of lightweight resolver packet structure -<type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in network -byte order to the lightweight resolver buffer, -<parameter>*b</parameter>. -</para> + <para><function>lwres_lwpacket_renderheader()</function> + transfers the contents of lightweight resolver packet structure + <type>lwres_lwpacket_t</type> <parameter>*pkt</parameter> in + network byte order to the lightweight resolver buffer, + <parameter>*b</parameter>. + </para> -<para> -<function>lwres_lwpacket_parseheader()</function> performs the -converse operation. It transfers data in network byte order from -buffer <parameter>*b</parameter> to resolver packet -<parameter>*pkt</parameter>. The contents of the buffer -<parameter>b</parameter> should correspond to a -<type>lwres_lwpacket_t</type>. -</para> + <para><function>lwres_lwpacket_parseheader()</function> + performs the converse operation. It transfers data in network + byte order from buffer <parameter>*b</parameter> to resolver + packet <parameter>*pkt</parameter>. The contents of the buffer + <parameter>b</parameter> should correspond to a + <type>lwres_lwpacket_t</type>. + </para> -</refsect1> + </refsect1> -<refsect1> -<title>RETURN VALUES</title> -<para> Successful calls to -<function>lwres_lwpacket_renderheader()</function> and -<function>lwres_lwpacket_parseheader()</function> return -<errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient -space to copy data between the buffer <parameter>*b</parameter> and -lightweight resolver packet <parameter>*pkt</parameter> both functions -return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>. -</para> + <refsect1> + <title>RETURN VALUES</title> + <para> + Successful calls to + <function>lwres_lwpacket_renderheader()</function> and + <function>lwres_lwpacket_parseheader()</function> return + <errorcode>LWRES_R_SUCCESS</errorcode>. If there is insufficient + space to copy data between the buffer <parameter>*b</parameter> and + lightweight resolver packet <parameter>*pkt</parameter> both + functions + return <errorcode>LWRES_R_UNEXPECTEDEND</errorcode>. + </para> -</refsect1> -</refentry> + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_packet.html b/contrib/bind9/lib/lwres/man/lwres_packet.html index 32bb81ee94be..eeb7ebd84074 100644 --- a/contrib/bind9/lib/lwres/man/lwres_packet.html +++ b/contrib/bind9/lib/lwres/man/lwres_packet.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_packet.html,v 1.8.2.1.4.12 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_packet.html,v 1.9.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_packet</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_lwpacket_renderheader, lwres_lwpacket_parseheader — lightweight resolver packet handling functions</p> @@ -36,19 +36,15 @@ <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_lwpacket_renderheader</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_lwpacket_t * </td> <td> -<code>)</code>;</td> +<var class="pdparam">pkt</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> @@ -56,35 +52,33 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_lwpacket_parseheader</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_lwpacket_t * </td> <td> -<code>)</code>;</td> +<var class="pdparam">pkt</var><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549430"></a><h2>DESCRIPTION</h2> +<a name="id2543389"></a><h2>DESCRIPTION</h2> <p> -These functions rely on a -<span class="type">struct lwres_lwpacket</span> -which is defined in -<code class="filename">lwres/lwpacket.h</code>. - -</p> + These functions rely on a + <span class="type">struct lwres_lwpacket</span> + which is defined in + <code class="filename">lwres/lwpacket.h</code>. + </p> <pre class="programlisting"> typedef struct lwres_lwpacket lwres_lwpacket_t; - + </pre> +<p> + </p> +<pre class="programlisting"> struct lwres_lwpacket { lwres_uint32_t length; lwres_uint16_t version; @@ -98,129 +92,144 @@ struct lwres_lwpacket { }; </pre> <p> -</p> + </p> <p> -The elements of this structure are: -</p> + The elements of this structure are: + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">length</code></span></dt> <dd><p> -the overall packet length, including the entire packet header. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. -</p></dd> + the overall packet length, including the entire packet header. + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + </p></dd> <dt><span class="term"><code class="constant">version</code></span></dt> <dd><p> -the header format. There is currently only one format, -<span class="type">LWRES_LWPACKETVERSION_0</span>. + the header format. There is currently only one format, + <span class="type">LWRES_LWPACKETVERSION_0</span>. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. -</p></dd> + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + </p></dd> <dt><span class="term"><code class="constant">pktflags</code></span></dt> <dd><p> -library-defined flags for this packet: for instance whether the packet -is a request or a reply. Flag values can be set, but not defined by -the caller. -This field is filled in by the application wit the exception of the -LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in the -lwres_gabn_*() and lwres_gnba_*() calls. -</p></dd> + library-defined flags for this packet: for instance whether the + packet + is a request or a reply. Flag values can be set, but not defined + by + the caller. + This field is filled in by the application wit the exception of + the + LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library in + the + lwres_gabn_*() and lwres_gnba_*() calls. + </p></dd> <dt><span class="term"><code class="constant">serial</code></span></dt> <dd><p> -is set by the requestor and is returned in all replies. If two or more -packets from the same source have the same serial number and are from -the same source, they are assumed to be duplicates and the latter ones -may be dropped. -This field must be set by the application. -</p></dd> + is set by the requestor and is returned in all replies. If two + or more + packets from the same source have the same serial number and are + from + the same source, they are assumed to be duplicates and the + latter ones + may be dropped. + This field must be set by the application. + </p></dd> <dt><span class="term"><code class="constant">opcode</code></span></dt> <dd><p> -indicates the operation. -Opcodes between 0x00000000 and 0x03ffffff are -reserved for use by the lightweight resolver library. Opcodes between -0x04000000 and 0xffffffff are application defined. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. -</p></dd> + indicates the operation. + Opcodes between 0x00000000 and 0x03ffffff are + reserved for use by the lightweight resolver library. Opcodes + between + 0x04000000 and 0xffffffff are application defined. + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + </p></dd> <dt><span class="term"><code class="constant">result</code></span></dt> <dd><p> -is only valid for replies. -Results between 0x04000000 and 0xffffffff are application defined. -Results between 0x00000000 and 0x03ffffff are reserved for library use. -This field is filled in by the lwres_gabn_*() and lwres_gnba_*() -calls. -</p></dd> + is only valid for replies. + Results between 0x04000000 and 0xffffffff are application + defined. + Results between 0x00000000 and 0x03ffffff are reserved for + library use. + This field is filled in by the lwres_gabn_*() and lwres_gnba_*() + calls. + </p></dd> <dt><span class="term"><code class="constant">recvlength</code></span></dt> <dd><p> -is the maximum buffer size that the receiver can handle on requests -and the size of the buffer needed to satisfy a request when the buffer -is too large for replies. -This field is supplied by the application. -</p></dd> + is the maximum buffer size that the receiver can handle on + requests + and the size of the buffer needed to satisfy a request when the + buffer + is too large for replies. + This field is supplied by the application. + </p></dd> <dt><span class="term"><code class="constant">authtype</code></span></dt> <dd><p> -defines the packet level authentication that is used. -Authorisation types between 0x1000 and 0xffff are application defined -and types between 0x0000 and 0x0fff are reserved for library use. -Currently these are not used and must be zero. -</p></dd> + defines the packet level authentication that is used. + Authorisation types between 0x1000 and 0xffff are application + defined + and types between 0x0000 and 0x0fff are reserved for library + use. + Currently these are not used and must be zero. + </p></dd> <dt><span class="term"><code class="constant">authlen</code></span></dt> <dd><p> -gives the length of the authentication data. -Since packet authentication is currently not used, this must be zero. -</p></dd> + gives the length of the authentication data. + Since packet authentication is currently not used, this must be + zero. + </p></dd> </dl></div> <p> -</p> + </p> <p> -The following opcodes are currently defined: -</p> + The following opcodes are currently defined: + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">NOOP</code></span></dt> <dd><p> -Success is always returned and the packet contents are echoed. -The lwres_noop_*() functions should be used for this type. -</p></dd> + Success is always returned and the packet contents are echoed. + The lwres_noop_*() functions should be used for this type. + </p></dd> <dt><span class="term"><code class="constant">GETADDRSBYNAME</code></span></dt> <dd><p> -returns all known addresses for a given name. -The lwres_gabn_*() functions should be used for this type. -</p></dd> + returns all known addresses for a given name. + The lwres_gabn_*() functions should be used for this type. + </p></dd> <dt><span class="term"><code class="constant">GETNAMEBYADDR</code></span></dt> <dd><p> -return the hostname for the given address. -The lwres_gnba_*() functions should be used for this type. -</p></dd> + return the hostname for the given address. + The lwres_gnba_*() functions should be used for this type. + </p></dd> </dl></div> <p> -</p> -<p> -<code class="function">lwres_lwpacket_renderheader()</code> transfers the -contents of lightweight resolver packet structure -<span class="type">lwres_lwpacket_t</span> <em class="parameter"><code>*pkt</code></em> in network -byte order to the lightweight resolver buffer, -<em class="parameter"><code>*b</code></em>. -</p> -<p> -<code class="function">lwres_lwpacket_parseheader()</code> performs the -converse operation. It transfers data in network byte order from -buffer <em class="parameter"><code>*b</code></em> to resolver packet -<em class="parameter"><code>*pkt</code></em>. The contents of the buffer -<em class="parameter"><code>b</code></em> should correspond to a -<span class="type">lwres_lwpacket_t</span>. -</p> + </p> +<p><code class="function">lwres_lwpacket_renderheader()</code> + transfers the contents of lightweight resolver packet structure + <span class="type">lwres_lwpacket_t</span> <em class="parameter"><code>*pkt</code></em> in + network byte order to the lightweight resolver buffer, + <em class="parameter"><code>*b</code></em>. + </p> +<p><code class="function">lwres_lwpacket_parseheader()</code> + performs the converse operation. It transfers data in network + byte order from buffer <em class="parameter"><code>*b</code></em> to resolver + packet <em class="parameter"><code>*pkt</code></em>. The contents of the buffer + <em class="parameter"><code>b</code></em> should correspond to a + <span class="type">lwres_lwpacket_t</span>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549769"></a><h2>RETURN VALUES</h2> -<p> Successful calls to -<code class="function">lwres_lwpacket_renderheader()</code> and -<code class="function">lwres_lwpacket_parseheader()</code> return -<span class="errorcode">LWRES_R_SUCCESS</span>. If there is insufficient -space to copy data between the buffer <em class="parameter"><code>*b</code></em> and -lightweight resolver packet <em class="parameter"><code>*pkt</code></em> both functions -return <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>. -</p> +<a name="id2543706"></a><h2>RETURN VALUES</h2> +<p> + Successful calls to + <code class="function">lwres_lwpacket_renderheader()</code> and + <code class="function">lwres_lwpacket_parseheader()</code> return + <span class="errorcode">LWRES_R_SUCCESS</span>. If there is insufficient + space to copy data between the buffer <em class="parameter"><code>*b</code></em> and + lightweight resolver packet <em class="parameter"><code>*pkt</code></em> both + functions + return <span class="errorcode">LWRES_R_UNEXPECTEDEND</span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/man/lwres_resutil.3 b/contrib/bind9/lib/lwres/man/lwres_resutil.3 index 907706c424e4..9aebc9f86a00 100644 --- a/contrib/bind9/lib/lwres/man/lwres_resutil.3 +++ b/contrib/bind9/lib/lwres/man/lwres_resutil.3 @@ -1,4 +1,4 @@ -.\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +.\" Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -13,13 +13,13 @@ .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" -.\" $Id: lwres_resutil.3,v 1.14.2.1.8.6 2006/06/29 13:02:31 marka Exp $ +.\" $Id: lwres_resutil.3,v 1.17.18.11 2007/01/30 00:23:45 marka Exp $ .\" .hy 0 .ad l .\" Title: lwres_resutil .\" Author: -.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/> +.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/> .\" Date: Jun 30, 2000 .\" Manual: BIND9 .\" Source: BIND9 @@ -36,13 +36,13 @@ lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr #include <lwres/lwres.h> .fi .HP 34 -.BI "lwres_result_t lwres_string_parse(lwres_buffer_t\ *b, char\ **c, lwres_uint16_t\ *len);" +.BI "lwres_result_t lwres_string_parse(lwres_buffer_t\ *" "b" ", char\ **" "c" ", lwres_uint16_t\ *" "len" ");" .HP 32 -.BI "lwres_result_t lwres_addr_parse(lwres_buffer_t\ *b, lwres_addr_t\ *addr);" +.BI "lwres_result_t lwres_addr_parse(lwres_buffer_t\ *" "b" ", lwres_addr_t\ *" "addr" ");" .HP 36 -.BI "lwres_result_t lwres_getaddrsbyname(lwres_context_t\ *ctx, const\ char\ *name, lwres_uint32_t\ addrtypes, lwres_gabnresponse_t\ **structp);" +.BI "lwres_result_t lwres_getaddrsbyname(lwres_context_t\ *" "ctx" ", const\ char\ *" "name" ", lwres_uint32_t\ " "addrtypes" ", lwres_gabnresponse_t\ **" "structp" ");" .HP 35 -.BI "lwres_result_t lwres_getnamebyaddr(lwres_context_t\ *ctx, lwres_uint32_t\ addrtype, lwres_uint16_t\ addrlen, const\ unsigned\ char\ *addr, lwres_gnbaresponse_t\ **structp);" +.BI "lwres_result_t lwres_getnamebyaddr(lwres_context_t\ *" "ctx" ", lwres_uint32_t\ " "addrtype" ", lwres_uint16_t\ " "addrlen" ", const\ unsigned\ char\ *" "addr" ", lwres_gnbaresponse_t\ **" "structp" ");" .SH "DESCRIPTION" .PP \fBlwres_string_parse()\fR @@ -73,8 +73,8 @@ and use the \fBlwres_gnbaresponse_t\fR structure defined below: -.sp -.RS 3n +.PP +.RS 4 .nf typedef struct { lwres_uint32_t flags; @@ -90,9 +90,9 @@ typedef struct { } lwres_gabnresponse_t; .fi .RE -.sp +.PP The contents of this structure are not manipulated directly but they are controlled through the -\fBlwres_gabn\fR(3 ) +\fBlwres_gabn\fR(3) functions. .PP The lightweight resolver uses @@ -164,4 +164,7 @@ if the buffers used for sending queries and receiving replies are too small. \fBlwres_buffer\fR(3), \fBlwres_gabn\fR(3). .SH "COPYRIGHT" -Copyright \(co 2004, 2005 Internet Systems Consortium, Inc. ("ISC") +Copyright \(co 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") +.br +Copyright \(co 2000, 2001 Internet Software Consortium. +.br diff --git a/contrib/bind9/lib/lwres/man/lwres_resutil.docbook b/contrib/bind9/lib/lwres/man/lwres_resutil.docbook index 7ab2146b40b7..3b60f0681d2f 100644 --- a/contrib/bind9/lib/lwres/man/lwres_resutil.docbook +++ b/contrib/bind9/lib/lwres/man/lwres_resutil.docbook @@ -1,8 +1,8 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" - "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY mdash "—">]> <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -18,24 +18,24 @@ - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_resutil.docbook,v 1.5.206.3 2005/05/12 21:36:16 sra Exp $ --> - +<!-- $Id: lwres_resutil.docbook,v 1.6.18.5 2007/01/29 23:57:21 marka Exp $ --> <refentry> -<refentryinfo> -<date>Jun 30, 2000</date> -</refentryinfo> + <refentryinfo> + <date>Jun 30, 2000</date> + </refentryinfo> -<refmeta> - <refentrytitle>lwres_resutil</refentrytitle> - <manvolnum>3</manvolnum> - <refmiscinfo>BIND9</refmiscinfo> -</refmeta> + <refmeta> + <refentrytitle>lwres_resutil</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>BIND9</refmiscinfo> + </refmeta> <docinfo> <copyright> <year>2004</year> <year>2005</year> + <year>2007</year> <holder>Internet Systems Consortium, Inc. ("ISC")</holder> </copyright> <copyright> @@ -45,89 +45,88 @@ </copyright> </docinfo> -<refnamediv> -<refname>lwres_string_parse</refname> -<refname>lwres_addr_parse</refname> -<refname>lwres_getaddrsbyname</refname> -<refname>lwres_getnamebyaddr</refname> -<refpurpose>lightweight resolver utility functions</refpurpose> -</refnamediv> -<refsynopsisdiv> -<funcsynopsis> + <refnamediv> + <refname>lwres_string_parse</refname> + <refname>lwres_addr_parse</refname> + <refname>lwres_getaddrsbyname</refname> + <refname>lwres_getnamebyaddr</refname> + <refpurpose>lightweight resolver utility functions</refpurpose> + </refnamediv> + <refsynopsisdiv> + <funcsynopsis> <funcsynopsisinfo>#include <lwres/lwres.h></funcsynopsisinfo> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_string_parse</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>char **c</paramdef> -<paramdef>lwres_uint16_t *len</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>char **<parameter>c</parameter></paramdef> + <paramdef>lwres_uint16_t *<parameter>len</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_addr_parse</function></funcdef> -<paramdef>lwres_buffer_t *b</paramdef> -<paramdef>lwres_addr_t *addr</paramdef> -</funcprototype> + <paramdef>lwres_buffer_t *<parameter>b</parameter></paramdef> + <paramdef>lwres_addr_t *<parameter>addr</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_getaddrsbyname</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>const char *name</paramdef> -<paramdef>lwres_uint32_t addrtypes</paramdef> -<paramdef>lwres_gabnresponse_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>lwres_uint32_t <parameter>addrtypes</parameter></paramdef> + <paramdef>lwres_gabnresponse_t **<parameter>structp</parameter></paramdef> + </funcprototype> <funcprototype> -<funcdef> + <funcdef> lwres_result_t <function>lwres_getnamebyaddr</function></funcdef> -<paramdef>lwres_context_t *ctx</paramdef> -<paramdef>lwres_uint32_t addrtype</paramdef> -<paramdef>lwres_uint16_t addrlen</paramdef> -<paramdef>const unsigned char *addr</paramdef> -<paramdef>lwres_gnbaresponse_t **structp</paramdef> -</funcprototype> + <paramdef>lwres_context_t *<parameter>ctx</parameter></paramdef> + <paramdef>lwres_uint32_t <parameter>addrtype</parameter></paramdef> + <paramdef>lwres_uint16_t <parameter>addrlen</parameter></paramdef> + <paramdef>const unsigned char *<parameter>addr</parameter></paramdef> + <paramdef>lwres_gnbaresponse_t **<parameter>structp</parameter></paramdef> + </funcprototype> </funcsynopsis> -</refsynopsisdiv> - -<refsect1> -<title>DESCRIPTION</title> - -<para> -<function>lwres_string_parse()</function> retrieves a DNS-encoded -string starting the current pointer of lightweight resolver buffer -<parameter>b</parameter>: i.e. <constant>b->current</constant>. -When the function returns, the address of the first byte of the -encoded string is returned via <parameter>*c</parameter> and the -length of that string is given by <parameter>*len</parameter>. The -buffer's current pointer is advanced to point at the character -following the string length, the encoded string, and the trailing -<type>NULL</type> character. -</para> - -<para> -<function>lwres_addr_parse()</function> extracts an address from the -buffer <parameter>b</parameter>. The buffer's current pointer -<constant>b->current</constant> is presumed to point at an encoded -address: the address preceded by a 32-bit protocol family identifier -and a 16-bit length field. The encoded address is copied to -<constant>addr->address</constant> and -<constant>addr->length</constant> indicates the size in bytes of -the address that was copied. <constant>b->current</constant> is -advanced to point at the next byte of available data in the buffer -following the encoded address. -</para> - -<para> -<function>lwres_getaddrsbyname()</function> -and -<function>lwres_getnamebyaddr()</function> -use the -<type>lwres_gnbaresponse_t</type> -structure defined below: -<programlisting> + </refsynopsisdiv> + + <refsect1> + <title>DESCRIPTION</title> + + <para><function>lwres_string_parse()</function> + retrieves a DNS-encoded string starting the current pointer of + lightweight resolver buffer <parameter>b</parameter>: i.e. + <constant>b->current</constant>. When the function returns, + the address of the first byte of the encoded string is returned + via <parameter>*c</parameter> and the length of that string is + given by <parameter>*len</parameter>. The buffer's current + pointer is advanced to point at the character following the + string length, the encoded string, and the trailing + <type>NULL</type> character. + </para> + + <para><function>lwres_addr_parse()</function> + extracts an address from the buffer <parameter>b</parameter>. + The buffer's current pointer <constant>b->current</constant> + is presumed to point at an encoded address: the address preceded + by a 32-bit protocol family identifier and a 16-bit length + field. The encoded address is copied to + <constant>addr->address</constant> and + <constant>addr->length</constant> indicates the size in bytes + of the address that was copied. + <constant>b->current</constant> is advanced to point at the + next byte of available data in the buffer following the encoded + address. + </para> + + <para><function>lwres_getaddrsbyname()</function> + and <function>lwres_getnamebyaddr()</function> use the + <type>lwres_gnbaresponse_t</type> structure defined below: + </para> + +<para><programlisting> typedef struct { lwres_uint32_t flags; lwres_uint16_t naliases; @@ -140,97 +139,100 @@ typedef struct { void *base; size_t baselen; } lwres_gabnresponse_t; -</programlisting> -The contents of this structure are not manipulated directly but -they are controlled through the -<citerefentry> -<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3 -</manvolnum> -</citerefentry> -functions. -</para> - -<para> -The lightweight resolver uses -<function>lwres_getaddrsbyname()</function> to perform foward lookups. -Hostname <parameter>name</parameter> is looked up using the resolver -context <parameter>ctx</parameter> for memory allocation. -<parameter>addrtypes</parameter> is a bitmask indicating which type of -addresses are to be looked up. Current values for this bitmask are -<type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and -<type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the -lookup are returned in <parameter>*structp</parameter>. -</para> - -<para> -<function>lwres_getnamebyaddr()</function> performs reverse lookups. -Resolver context <parameter>ctx</parameter> is used for memory -allocation. The address type is indicated by -<parameter>addrtype</parameter>: <type>LWRES_ADDRTYPE_V4</type> or -<type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is given -by <parameter>addr</parameter> and its length is -<parameter>addrlen</parameter> bytes. The result of the function call -is made available through <parameter>*structp</parameter>. -</para> -</refsect1> - -<refsect1> -<title>RETURN VALUES</title> -<para> -Successful calls to -<function>lwres_string_parse()</function> -and -<function>lwres_addr_parse()</function> -return -<errorcode>LWRES_R_SUCCESS.</errorcode> -Both functions return -<errorcode>LWRES_R_FAILURE</errorcode> -if the buffer is corrupt or -<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> -if the buffer has less space than expected for the components of the -encoded string or address. -</para> -<para> -<function>lwres_getaddrsbyname()</function> -returns -<errorcode>LWRES_R_SUCCESS</errorcode> -on success and it returns -<errorcode>LWRES_R_NOTFOUND</errorcode> -if the hostname -<parameter>name</parameter> -could not be found. -</para> -<para> -<errorcode>LWRES_R_SUCCESS</errorcode> -is returned by a successful call to -<function>lwres_getnamebyaddr()</function>. -</para> - -<para> -Both -<function>lwres_getaddrsbyname()</function> -and -<function>lwres_getnamebyaddr()</function> -return -<errorcode>LWRES_R_NOMEMORY</errorcode> -when memory allocation requests fail and -<errorcode>LWRES_R_UNEXPECTEDEND</errorcode> -if the buffers used for sending queries and receiving replies are too -small. -</para> - -</refsect1> -<refsect1> -<title>SEE ALSO</title> -<para> -<citerefentry> -<refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>, - -<citerefentry> -<refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum> -</citerefentry>. -</para> - -</refsect1> -</refentry> +</programlisting></para> + + <para> + The contents of this structure are not manipulated directly but + they are controlled through the + <citerefentry> + <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum> + </citerefentry> + functions. + </para> + + <para> + The lightweight resolver uses + <function>lwres_getaddrsbyname()</function> to perform + foward lookups. + Hostname <parameter>name</parameter> is looked up using the + resolver + context <parameter>ctx</parameter> for memory allocation. + <parameter>addrtypes</parameter> is a bitmask indicating + which type of + addresses are to be looked up. Current values for this bitmask are + <type>LWRES_ADDRTYPE_V4</type> for IPv4 addresses and + <type>LWRES_ADDRTYPE_V6</type> for IPv6 addresses. Results of the + lookup are returned in <parameter>*structp</parameter>. + </para> + + <para><function>lwres_getnamebyaddr()</function> + performs reverse lookups. Resolver context + <parameter>ctx</parameter> is used for memory allocation. The + address type is indicated by <parameter>addrtype</parameter>: + <type>LWRES_ADDRTYPE_V4</type> or + <type>LWRES_ADDRTYPE_V6</type>. The address to be looked up is + given by <parameter>addr</parameter> and its length is + <parameter>addrlen</parameter> bytes. The result of the + function call is made available through + <parameter>*structp</parameter>. + </para> + </refsect1> + + <refsect1> + <title>RETURN VALUES</title> + <para> + Successful calls to + <function>lwres_string_parse()</function> + and + <function>lwres_addr_parse()</function> + return + <errorcode>LWRES_R_SUCCESS.</errorcode> + Both functions return + <errorcode>LWRES_R_FAILURE</errorcode> + if the buffer is corrupt or + <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> + if the buffer has less space than expected for the components of the + encoded string or address. + </para> + + <para><function>lwres_getaddrsbyname()</function> + returns <errorcode>LWRES_R_SUCCESS</errorcode> on success and it + returns <errorcode>LWRES_R_NOTFOUND</errorcode> if the hostname + <parameter>name</parameter> could not be found. + </para> + <para><errorcode>LWRES_R_SUCCESS</errorcode> + is returned by a successful call to + <function>lwres_getnamebyaddr()</function>. + </para> + + <para> + Both + <function>lwres_getaddrsbyname()</function> + and + <function>lwres_getnamebyaddr()</function> + return + <errorcode>LWRES_R_NOMEMORY</errorcode> + when memory allocation requests fail and + <errorcode>LWRES_R_UNEXPECTEDEND</errorcode> + if the buffers used for sending queries and receiving replies are too + small. + </para> + + </refsect1> + <refsect1> + <title>SEE ALSO</title> + <para><citerefentry> + <refentrytitle>lwres_buffer</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>, + + <citerefentry> + <refentrytitle>lwres_gabn</refentrytitle><manvolnum>3</manvolnum> + </citerefentry>. + </para> + + </refsect1> +</refentry><!-- + - Local variables: + - mode: sgml + - End: +--> diff --git a/contrib/bind9/lib/lwres/man/lwres_resutil.html b/contrib/bind9/lib/lwres/man/lwres_resutil.html index a9bc1eea103d..dfa2e1c88dc1 100644 --- a/contrib/bind9/lib/lwres/man/lwres_resutil.html +++ b/contrib/bind9/lib/lwres/man/lwres_resutil.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $Id: lwres_resutil.html,v 1.8.2.1.4.11 2006/06/29 13:02:31 marka Exp $ --> +<!-- $Id: lwres_resutil.html,v 1.9.18.16 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_resutil</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_string_parse, lwres_addr_parse, lwres_getaddrsbyname, lwres_getnamebyaddr — lightweight resolver utility functions</p> @@ -36,24 +36,21 @@ <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_string_parse</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>char ** </td> +<td> +<var class="pdparam">c</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_uint16_t * </td> <td> -<code>)</code>;</td> +<var class="pdparam">len</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -61,19 +58,15 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_addr_parse</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_buffer_t * </td> +<td> +<var class="pdparam">b</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_addr_t * </td> <td> -<code>)</code>;</td> +<var class="pdparam">addr</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em"> @@ -81,29 +74,27 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_getaddrsbyname</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">name</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_uint32_t </td> +<td> +<var class="pdparam">addrtypes</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gabnresponse_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> @@ -111,71 +102,67 @@ lwres_result_t <td><code class="funcdef"> lwres_result_t <b class="fsfunc">lwres_getnamebyaddr</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>lwres_context_t * </td> +<td> +<var class="pdparam">ctx</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_uint32_t </td> +<td> +<var class="pdparam">addrtype</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>lwres_uint16_t </td> +<td> +<var class="pdparam">addrlen</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>const unsigned char * </td> +<td> +<var class="pdparam">addr</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>lwres_gnbaresponse_t ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">structp</var><code>)</code>;</td> </tr> </table> </div> </div> <div class="refsect1" lang="en"> -<a name="id2549485"></a><h2>DESCRIPTION</h2> -<p> -<code class="function">lwres_string_parse()</code> retrieves a DNS-encoded -string starting the current pointer of lightweight resolver buffer -<em class="parameter"><code>b</code></em>: i.e. <code class="constant">b->current</code>. -When the function returns, the address of the first byte of the -encoded string is returned via <em class="parameter"><code>*c</code></em> and the -length of that string is given by <em class="parameter"><code>*len</code></em>. The -buffer's current pointer is advanced to point at the character -following the string length, the encoded string, and the trailing -<span class="type">NULL</span> character. -</p> -<p> -<code class="function">lwres_addr_parse()</code> extracts an address from the -buffer <em class="parameter"><code>b</code></em>. The buffer's current pointer -<code class="constant">b->current</code> 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 -<code class="constant">addr->address</code> and -<code class="constant">addr->length</code> indicates the size in bytes of -the address that was copied. <code class="constant">b->current</code> is -advanced to point at the next byte of available data in the buffer -following the encoded address. -</p> -<p> -<code class="function">lwres_getaddrsbyname()</code> -and -<code class="function">lwres_getnamebyaddr()</code> -use the -<span class="type">lwres_gnbaresponse_t</span> -structure defined below: -</p> +<a name="id2543466"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_string_parse()</code> + retrieves a DNS-encoded string starting the current pointer of + lightweight resolver buffer <em class="parameter"><code>b</code></em>: i.e. + <code class="constant">b->current</code>. When the function returns, + the address of the first byte of the encoded string is returned + via <em class="parameter"><code>*c</code></em> and the length of that string is + given by <em class="parameter"><code>*len</code></em>. The buffer's current + pointer is advanced to point at the character following the + string length, the encoded string, and the trailing + <span class="type">NULL</span> character. + </p> +<p><code class="function">lwres_addr_parse()</code> + extracts an address from the buffer <em class="parameter"><code>b</code></em>. + The buffer's current pointer <code class="constant">b->current</code> + 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 + <code class="constant">addr->address</code> and + <code class="constant">addr->length</code> indicates the size in bytes + of the address that was copied. + <code class="constant">b->current</code> is advanced to point at the + next byte of available data in the buffer following the encoded + address. + </p> +<p><code class="function">lwres_getaddrsbyname()</code> + and <code class="function">lwres_getnamebyaddr()</code> use the + <span class="type">lwres_gnbaresponse_t</span> structure defined below: + </p> <pre class="programlisting"> typedef struct { lwres_uint32_t flags; @@ -191,85 +178,81 @@ typedef struct { } lwres_gabnresponse_t; </pre> <p> -The contents of this structure are not manipulated directly but -they are controlled through the -<span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3 -)</span> -functions. -</p> -<p> -The lightweight resolver uses -<code class="function">lwres_getaddrsbyname()</code> to perform foward lookups. -Hostname <em class="parameter"><code>name</code></em> is looked up using the resolver -context <em class="parameter"><code>ctx</code></em> for memory allocation. -<em class="parameter"><code>addrtypes</code></em> is a bitmask indicating which type of -addresses are to be looked up. Current values for this bitmask are -<span class="type">LWRES_ADDRTYPE_V4</span> for IPv4 addresses and -<span class="type">LWRES_ADDRTYPE_V6</span> for IPv6 addresses. Results of the -lookup are returned in <em class="parameter"><code>*structp</code></em>. -</p> + The contents of this structure are not manipulated directly but + they are controlled through the + <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span> + functions. + </p> <p> -<code class="function">lwres_getnamebyaddr()</code> performs reverse lookups. -Resolver context <em class="parameter"><code>ctx</code></em> is used for memory -allocation. The address type is indicated by -<em class="parameter"><code>addrtype</code></em>: <span class="type">LWRES_ADDRTYPE_V4</span> or -<span class="type">LWRES_ADDRTYPE_V6</span>. The address to be looked up is given -by <em class="parameter"><code>addr</code></em> and its length is -<em class="parameter"><code>addrlen</code></em> bytes. The result of the function call -is made available through <em class="parameter"><code>*structp</code></em>. -</p> + The lightweight resolver uses + <code class="function">lwres_getaddrsbyname()</code> to perform + foward lookups. + Hostname <em class="parameter"><code>name</code></em> is looked up using the + resolver + context <em class="parameter"><code>ctx</code></em> for memory allocation. + <em class="parameter"><code>addrtypes</code></em> is a bitmask indicating + which type of + addresses are to be looked up. Current values for this bitmask are + <span class="type">LWRES_ADDRTYPE_V4</span> for IPv4 addresses and + <span class="type">LWRES_ADDRTYPE_V6</span> for IPv6 addresses. Results of the + lookup are returned in <em class="parameter"><code>*structp</code></em>. + </p> +<p><code class="function">lwres_getnamebyaddr()</code> + performs reverse lookups. Resolver context + <em class="parameter"><code>ctx</code></em> is used for memory allocation. The + address type is indicated by <em class="parameter"><code>addrtype</code></em>: + <span class="type">LWRES_ADDRTYPE_V4</span> or + <span class="type">LWRES_ADDRTYPE_V6</span>. The address to be looked up is + given by <em class="parameter"><code>addr</code></em> and its length is + <em class="parameter"><code>addrlen</code></em> bytes. The result of the + function call is made available through + <em class="parameter"><code>*structp</code></em>. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549693"></a><h2>RETURN VALUES</h2> -<p> -Successful calls to -<code class="function">lwres_string_parse()</code> -and -<code class="function">lwres_addr_parse()</code> -return -<span class="errorcode">LWRES_R_SUCCESS.</span> -Both functions return -<span class="errorcode">LWRES_R_FAILURE</span> -if the buffer is corrupt or -<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> -if the buffer has less space than expected for the components of the -encoded string or address. -</p> +<a name="id2543605"></a><h2>RETURN VALUES</h2> <p> -<code class="function">lwres_getaddrsbyname()</code> -returns -<span class="errorcode">LWRES_R_SUCCESS</span> -on success and it returns -<span class="errorcode">LWRES_R_NOTFOUND</span> -if the hostname -<em class="parameter"><code>name</code></em> -could not be found. -</p> + Successful calls to + <code class="function">lwres_string_parse()</code> + and + <code class="function">lwres_addr_parse()</code> + return + <span class="errorcode">LWRES_R_SUCCESS.</span> + Both functions return + <span class="errorcode">LWRES_R_FAILURE</span> + if the buffer is corrupt or + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + if the buffer has less space than expected for the components of the + encoded string or address. + </p> +<p><code class="function">lwres_getaddrsbyname()</code> + returns <span class="errorcode">LWRES_R_SUCCESS</span> on success and it + returns <span class="errorcode">LWRES_R_NOTFOUND</span> if the hostname + <em class="parameter"><code>name</code></em> could not be found. + </p> +<p><span class="errorcode">LWRES_R_SUCCESS</span> + is returned by a successful call to + <code class="function">lwres_getnamebyaddr()</code>. + </p> <p> -<span class="errorcode">LWRES_R_SUCCESS</span> -is returned by a successful call to -<code class="function">lwres_getnamebyaddr()</code>. -</p> -<p> -Both -<code class="function">lwres_getaddrsbyname()</code> -and -<code class="function">lwres_getnamebyaddr()</code> -return -<span class="errorcode">LWRES_R_NOMEMORY</span> -when memory allocation requests fail and -<span class="errorcode">LWRES_R_UNEXPECTEDEND</span> -if the buffers used for sending queries and receiving replies are too -small. -</p> + Both + <code class="function">lwres_getaddrsbyname()</code> + and + <code class="function">lwres_getnamebyaddr()</code> + return + <span class="errorcode">LWRES_R_NOMEMORY</span> + when memory allocation requests fail and + <span class="errorcode">LWRES_R_UNEXPECTEDEND</span> + if the buffers used for sending queries and receiving replies are too + small. + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549763"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres_buffer</span>(3)</span>, +<a name="id2543676"></a><h2>SEE ALSO</h2> +<p><span class="citerefentry"><span class="refentrytitle">lwres_buffer</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>. -</p> + <span class="citerefentry"><span class="refentrytitle">lwres_gabn</span>(3)</span>. + </p> </div> </div></body> </html> diff --git a/contrib/bind9/lib/lwres/print.c b/contrib/bind9/lib/lwres/print.c index 15522284e5d5..49da0379f228 100644 --- a/contrib/bind9/lib/lwres/print.c +++ b/contrib/bind9/lib/lwres/print.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: print.c,v 1.2.4.7 2005/10/14 01:38:51 marka Exp $ */ +/* $Id: print.c,v 1.2.2.7 2005/10/14 01:28:30 marka Exp $ */ #include <config.h> diff --git a/contrib/bind9/lib/lwres/print_p.h b/contrib/bind9/lib/lwres/print_p.h index 4e27e5519de8..4c2d2bf4f1eb 100644 --- a/contrib/bind9/lib/lwres/print_p.h +++ b/contrib/bind9/lib/lwres/print_p.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: print_p.h,v 1.2.4.1 2004/08/28 06:25:25 marka Exp $ */ +/* $Id: print_p.h,v 1.2.2.1 2004/08/28 06:21:13 marka Exp $ */ #ifndef LWRES_PRINT_P_H #define LWRES_PRINT_P_H 1 diff --git a/contrib/bind9/lib/lwres/strtoul.c b/contrib/bind9/lib/lwres/strtoul.c index 9cda1947724a..3fc8971484ef 100644 --- a/contrib/bind9/lib/lwres/strtoul.c +++ b/contrib/bind9/lib/lwres/strtoul.c @@ -53,7 +53,7 @@ static char sccsid[] = "@(#)strtoul.c 8.1 (Berkeley) 6/4/93"; #endif /* LIBC_SCCS and not lint */ -/* $Id: strtoul.c,v 1.2.4.1 2005/06/08 02:08:31 marka Exp $ */ +/* $Id: strtoul.c,v 1.2.2.1 2005/06/08 02:07:59 marka Exp $ */ #include <config.h> diff --git a/contrib/bind9/lib/lwres/unix/Makefile.in b/contrib/bind9/lib/lwres/unix/Makefile.in index b734bc1ebaca..577e3d308c33 100644 --- a/contrib/bind9/lib/lwres/unix/Makefile.in +++ b/contrib/bind9/lib/lwres/unix/Makefile.in @@ -13,7 +13,7 @@ # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -# $Id: Makefile.in,v 1.1.206.1 2004/03/06 08:15:43 marka Exp $ +# $Id: Makefile.in,v 1.2 2004/03/05 05:12:59 marka Exp $ srcdir = @srcdir@ VPATH = @srcdir@ diff --git a/contrib/bind9/lib/lwres/unix/include/Makefile.in b/contrib/bind9/lib/lwres/unix/include/Makefile.in index 8f3798e4e92b..8ca74894875c 100644 --- a/contrib/bind9/lib/lwres/unix/include/Makefile.in +++ b/contrib/bind9/lib/lwres/unix/include/Makefile.in @@ -13,7 +13,7 @@ # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -# $Id: Makefile.in,v 1.1.206.1 2004/03/06 08:15:43 marka Exp $ +# $Id: Makefile.in,v 1.2 2004/03/05 05:13:03 marka Exp $ srcdir = @srcdir@ VPATH = @srcdir@ diff --git a/contrib/bind9/lib/lwres/unix/include/lwres/Makefile.in b/contrib/bind9/lib/lwres/unix/include/lwres/Makefile.in index e969f5043762..7e0b5945c053 100644 --- a/contrib/bind9/lib/lwres/unix/include/lwres/Makefile.in +++ b/contrib/bind9/lib/lwres/unix/include/lwres/Makefile.in @@ -13,7 +13,7 @@ # OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. -# $Id: Makefile.in,v 1.1.206.1 2004/03/06 08:15:43 marka Exp $ +# $Id: Makefile.in,v 1.2 2004/03/05 05:13:06 marka Exp $ srcdir = @srcdir@ VPATH = @srcdir@ diff --git a/contrib/bind9/lib/lwres/unix/include/lwres/net.h b/contrib/bind9/lib/lwres/unix/include/lwres/net.h index b214de6b1ea4..8fb14ee82ed7 100644 --- a/contrib/bind9/lib/lwres/unix/include/lwres/net.h +++ b/contrib/bind9/lib/lwres/unix/include/lwres/net.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000-2002 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: net.h,v 1.3.12.3 2004/03/08 09:05:12 marka Exp $ */ +/* $Id: net.h,v 1.5.18.2 2005/04/29 00:17:23 marka Exp $ */ #ifndef LWRES_NET_H #define LWRES_NET_H 1 @@ -24,17 +24,15 @@ ***** Module Info *****/ -/* - * Basic Networking Types - * +/*! \file net.h * This module is responsible for defining the following basic networking * types: * - * struct in_addr - * struct in6_addr - * struct sockaddr - * struct sockaddr_in - * struct sockaddr_in6 + *\li struct in_addr + *\li struct in6_addr + *\li struct sockaddr + *\li struct sockaddr_in + *\li struct sockaddr_in6 * * It ensures that the AF_ and PF_ macros are defined. * @@ -42,7 +40,7 @@ * * It declares lwres_net_aton(), lwres_net_ntop(), and lwres_net_pton(). * - * It ensures that INADDR_LOOPBACK, INADDR_ANY and IN6ADDR_ANY_INIT + * It ensures that #INADDR_LOOPBACK, #INADDR_ANY and #IN6ADDR_ANY_INIT * are defined. */ @@ -79,7 +77,7 @@ #define in6_addr in_addr6 /* Required for pre RFC2133 implementations. */ #endif -/* +/*! * Required for some pre RFC2133 implementations. * IN6ADDR_ANY_INIT and IN6ADDR_LOOPBACK_INIT were added in * draft-ietf-ipngwg-bsd-api-04.txt or draft-ietf-ipngwg-bsd-api-05.txt. @@ -94,6 +92,9 @@ #endif #endif +/*! + * Initialize address loopback. See IN6ADDR_ANY_INIT + */ #ifndef IN6ADDR_LOOPBACK_INIT #ifdef s6_addr #define IN6ADDR_LOOPBACK_INIT { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 } } } @@ -102,14 +103,18 @@ #endif #endif +/*% Used by AI_ALL */ #ifndef AF_INET6 #define AF_INET6 99 #endif + +/*% Used to return IPV6 address types. */ #ifndef PF_INET6 #define PF_INET6 AF_INET6 #endif +/*% inaddr Loopback */ #ifndef INADDR_LOOPBACK #define INADDR_LOOPBACK 0x7f000001UL #endif diff --git a/contrib/bind9/lib/lwres/version.c b/contrib/bind9/lib/lwres/version.c index ac3e6c8089e1..33561fdb9562 100644 --- a/contrib/bind9/lib/lwres/version.c +++ b/contrib/bind9/lib/lwres/version.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") + * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * * Permission to use, copy, modify, and distribute this software for any @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.c,v 1.6.12.3 2004/03/08 09:05:11 marka Exp $ */ +/* $Id: version.c,v 1.8.18.2 2005/04/29 00:17:21 marka Exp $ */ + +/*! \file */ #include <lwres/version.h> |