lib/liblwres/man/lwres_context.3

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