diff options
Diffstat (limited to 'contrib/bind9/lib/lwres/context.c')
| -rw-r--r-- | contrib/bind9/lib/lwres/context.c | 97 |
1 files changed, 91 insertions, 6 deletions
diff --git a/contrib/bind9/lib/lwres/context.c b/contrib/bind9/lib/lwres/context.c index b606b9d..0da426b 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, |
