contrib/bind-9.2.4rc7/lib/lwres/man/lwres_context.3

   1 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
   9 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  10 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  11 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  12 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  13 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  14 .\" PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .\" $Id: lwres_context.3,v 1.13.2.3 2004/03/15 04:45:01 marka Exp $
  17 .\"
  18 .TH "LWRES_CONTEXT" "3" "Jun 30, 2000" "BIND9" ""
  19 .SH NAME
  20 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
  21 .SH SYNOPSIS
  22 \fB#include <lwres/lwres.h>
  23 .sp
  24 .na
  25 lwres_result_t
  26 lwres_context_create(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function);
  27 .ad
  28 .sp
  29 .na
  30 lwres_result_t
  31 lwres_context_destroy(lwres_context_t **contextp);
  32 .ad
  33 .sp
  34 .na
  35 void
  36 lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t serial);
  37 .ad
  38 .sp
  39 .na
  40 lwres_uint32_t
  41 lwres_context_nextserial(lwres_context_t *ctx);
  42 .ad
  43 .sp
  44 .na
  45 void
  46 lwres_context_freemem(lwres_context_t *ctx, void *mem, size_t len);
  47 .ad
  48 .sp
  49 .na
  50 void
  51 lwres_context_allocmem(lwres_context_t *ctx, size_t len);
  52 .ad
  53 .sp
  54 .na
  55 void *
  56 lwres_context_sendrecv(lwres_context_t *ctx, void *sendbase, int sendlen, void *recvbase, int recvlen, int *recvd_len);
  57 .ad
  58 \fR
  59 .SH "DESCRIPTION"
  60 .PP
  61 \fBlwres_context_create()\fR
  62 creates a
  63 \fBlwres_context_t\fR
  64 structure for use in lightweight resolver operations.
  65 It holds a socket and other data needed for communicating
  66 with a resolver daemon.
  67 The new
  68 \fBlwres_context_t\fR
  69 is returned through
  70 \fIcontextp\fR,
  71 a pointer to a
  72 \fBlwres_context_t\fR
  73 pointer. This
  74 \fBlwres_context_t\fR
  75 pointer must initially be NULL, and is modified
  76 to point to the newly created
  77 \fBlwres_context_t\fR.
  78 .PP
  79 When the lightweight resolver needs to perform dynamic memory
  80 allocation, it will call
  81 \fImalloc_function\fR
  82 to allocate memory and
  83 \fIfree_function\fR
  84 to free it. If
  85 \fImalloc_function\fR
  86 and
  87 \fIfree_function\fR
  88 are NULL, memory is allocated using
  89 \&.Xr malloc 3
  90 and
  91 \fBfree\fR(3).
  92 It is not permitted to have a NULL
  93 \fImalloc_function\fR
  94 and a non-NULL
  95 \fIfree_function\fR
  96 or vice versa.
  97 \fIarg\fR
  98 is passed as the first parameter to the memory
  99 allocation functions.
 100 If
 101 \fImalloc_function\fR
 102 and
 103 \fIfree_function\fR
 104 are NULL,
 105 \fIarg\fR
 106 is unused and should be passed as NULL.
 107 .PP
 108 Once memory for the structure has been allocated,
 109 it is initialized using
 110 \fBlwres_conf_init\fR(3)
 111 and returned via
 112 \fI*contextp\fR.
 113 .PP
 114 \fBlwres_context_destroy()\fR
 115 destroys a
 116 \fBlwres_context_t\fR,
 117 closing its socket.
 118 \fIcontextp\fR
 119 is a pointer to a pointer to the context that is to be destroyed.
 120 The pointer will be set to NULL when the context has been destroyed.
 121 .PP
 122 The context holds a serial number that is used to identify resolver
 123 request packets and associate responses with the corresponding requests.
 124 This serial number is controlled using
 125 \fBlwres_context_initserial()\fR
 126 and
 127 \fBlwres_context_nextserial()\fR.
 128 \fBlwres_context_initserial()\fR
 129 sets the serial number for context
 130 \fI*ctx\fR
 131 to
 132 \fIserial\fR.
 133 \fBlwres_context_nextserial()\fR
 134 increments the serial number and returns the previous value.
 135 .PP
 136 Memory for a lightweight resolver context is allocated and freed using
 137 \fBlwres_context_allocmem()\fR
 138 and
 139 \fBlwres_context_freemem()\fR.
 140 These use whatever allocations were defined when the context was
 141 created with
 142 \fBlwres_context_create()\fR.
 143 \fBlwres_context_allocmem()\fR
 144 allocates
 145 \fIlen\fR
 146 bytes of memory and if successful returns a pointer to the allocated
 147 storage.
 148 \fBlwres_context_freemem()\fR
 149 frees
 150 \fIlen\fR
 151 bytes of space starting at location
 152 \fImem\fR.
 153 .PP
 154 \fBlwres_context_sendrecv()\fR
 155 performs I/O for the context
 156 \fIctx\fR.
 157 Data are read and written from the context's socket.
 158 It writes data from
 159 \fIsendbase\fR
 160 \(em typically a lightweight resolver query packet \(em
 161 and waits for a reply which is copied to the receive buffer at
 162 \fIrecvbase\fR.
 163 The number of bytes that were written to this receive buffer is
 164 returned in
 165 \fI*recvd_len\fR.
 166 .SH "RETURN VALUES"
 167 .PP
 168 \fBlwres_context_create()\fR
 169 returns
 170 LWRES_R_NOMEMORY
 171 if memory for the
 172 \fBstruct lwres_context\fR
 173 could not be allocated,
 174 LWRES_R_SUCCESS
 175 otherwise.
 176 .PP
 177 Successful calls to the memory allocator
 178 \fBlwres_context_allocmem()\fR
 179 return a pointer to the start of the allocated space.
 180 It returns NULL if memory could not be allocated.
 181 .PP
 182 LWRES_R_SUCCESS
 183 is returned when
 184 \fBlwres_context_sendrecv()\fR
 185 completes successfully.
 186 LWRES_R_IOERROR
 187 is returned if an I/O error occurs and
 188 LWRES_R_TIMEOUT
 189 is returned if
 190 \fBlwres_context_sendrecv()\fR
 191 times out waiting for a response.
 192 .SH "SEE ALSO"
 193 .PP
 194 \fBlwres_conf_init\fR(3),
 195 \fBmalloc\fR(3),
 196 \fBfree\fR(3).