.\" Copyright (C) 2000, 2001, 2003-2005, 2007, 2014-2016, 2018-2020 Internet Systems Consortium, Inc. ("ISC")

.\" 

.\" This Source Code Form is subject to the terms of the Mozilla Public

.\" License, v. 2.0. If a copy of the MPL was not distributed with this

.\" file, You can obtain one at http://mozilla.org/MPL/2.0/.

.\"

.hy 0

.ad l

'\" t

.\"     Title: lwres_context

.\"    Author: 

.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>

.\"      Date: 2007-06-18

.\"    Manual: BIND9

.\"    Source: ISC

.\"  Language: English

.\"

.TH "LWRES_CONTEXT" "3" "2007\-06\-18" "ISC" "BIND9"

.\" -----------------------------------------------------------------

.\" * Define some portability stuff

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" http://bugs.debian.org/507673

.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.\" -----------------------------------------------------------------

.\" * set default formatting

.\" -----------------------------------------------------------------

.\" disable hyphenation

.nh

.\" disable justification (adjust text to left margin only)

.ad l

.\" -----------------------------------------------------------------

.\" * MAIN CONTENT STARTS HERE *

.\" -----------------------------------------------------------------

.SH "NAME"

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

.SH "SYNOPSIS"

.sp

.ft B

.nf

#include <lwres/lwres\&.h>

.fi

.ft

.HP \w'lwres_result_t\ lwres_context_create('u

.BI "lwres_result_t lwres_context_create(lwres_context_t\ **" "contextp" ", void\ *" "arg" ", lwres_malloc_t\ " "malloc_function" ", lwres_free_t\ " "free_function" ");"

.HP \w'lwres_result_t\ lwres_context_destroy('u

.BI "lwres_result_t lwres_context_destroy(lwres_context_t\ **" "contextp" ");"

.HP \w'void\ lwres_context_initserial('u

.BI "void lwres_context_initserial(lwres_context_t\ *" "ctx" ", uint32_t\ " "serial" ");"

.HP \w'uint32_t\ lwres_context_nextserial('u

.BI "uint32_t lwres_context_nextserial(lwres_context_t\ *" "ctx" ");"

.HP \w'void\ lwres_context_freemem('u

.BI "void lwres_context_freemem(lwres_context_t\ *" "ctx" ", void\ *" "mem" ", size_t\ " "len" ");"

.HP \w'void\ lwres_context_allocmem('u

.BI "void lwres_context_allocmem(lwres_context_t\ *" "ctx" ", size_t\ " "len" ");"

.HP \w'void\ *\ lwres_context_sendrecv('u

.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

creates a

\fBlwres_context_t\fR

structure for use in lightweight resolver operations\&. It holds a socket and other data needed for communicating with a resolver daemon\&. The new

\fBlwres_context_t\fR

is returned through

\fIcontextp\fR, a pointer to a

\fBlwres_context_t\fR

pointer\&. This

\fBlwres_context_t\fR

pointer must initially be NULL, and is modified to point to the newly created

\fBlwres_context_t\fR\&.

.PP

When the lightweight resolver needs to perform dynamic memory allocation, it will call

\fImalloc_function\fR

to allocate memory and

\fIfree_function\fR

to free it\&. If

\fImalloc_function\fR

and

\fIfree_function\fR

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

\fIfree_function\fR

or vice versa\&.

\fIarg\fR

is passed as the first parameter to the memory allocation functions\&. If

\fImalloc_function\fR

and

\fIfree_function\fR

are NULL,

\fIarg\fR

is unused and should be passed as NULL\&.

.PP

Once memory for the structure has been allocated, it is initialized using

\fBlwres_conf_init\fR(3)

and returned via

\fI*contextp\fR\&.

.PP

\fBlwres_context_destroy()\fR

destroys a

\fBlwres_context_t\fR, closing its socket\&.

\fIcontextp\fR

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\&.

.PP

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

\fBlwres_context_initserial()\fR

and

\fBlwres_context_nextserial()\fR\&.

\fBlwres_context_initserial()\fR

sets the serial number for context

\fI*ctx\fR

to

\fIserial\fR\&.

\fBlwres_context_nextserial()\fR

increments the serial number and returns the previous value\&.

.PP

Memory for a lightweight resolver context is allocated and freed using

\fBlwres_context_allocmem()\fR

and

\fBlwres_context_freemem()\fR\&. These use whatever allocations were defined when the context was created with

\fBlwres_context_create()\fR\&.

\fBlwres_context_allocmem()\fR

allocates

\fIlen\fR

bytes of memory and if successful returns a pointer to the allocated storage\&.

\fBlwres_context_freemem()\fR

frees

\fIlen\fR

bytes of space starting at location

\fImem\fR\&.

.PP

\fBlwres_context_sendrecv()\fR

performs I/O for the context

\fIctx\fR\&. Data are read and written from the context\*(Aqs socket\&. It writes data from

\fIsendbase\fR

\(em typically a lightweight resolver query packet \(em and waits for a reply which is copied to the receive buffer at

\fIrecvbase\fR\&. The number of bytes that were written to this receive buffer is returned in

\fI*recvd_len\fR\&.

.SH "RETURN VALUES"

.PP

\fBlwres_context_create()\fR

returns

\fBLWRES_R_NOMEMORY\fR

if memory for the

\fBstruct lwres_context\fR

could not be allocated,

\fBLWRES_R_SUCCESS\fR

otherwise\&.

.PP

Successful calls to the memory allocator

\fBlwres_context_allocmem()\fR

return a pointer to the start of the allocated space\&. It returns NULL if memory could not be allocated\&.

.PP

\fBLWRES_R_SUCCESS\fR

is returned when

\fBlwres_context_sendrecv()\fR

completes successfully\&.

\fBLWRES_R_IOERROR\fR

is returned if an I/O error occurs and

\fBLWRES_R_TIMEOUT\fR

is returned if

\fBlwres_context_sendrecv()\fR

times out waiting for a response\&.

.SH "SEE ALSO"

.PP

\fBlwres_conf_init\fR(3),

\fBmalloc\fR(3),

\fBfree\fR(3)\&.

.SH "AUTHOR"

.PP

\fBInternet Systems Consortium, Inc\&.\fR

.SH "COPYRIGHT"

.br

Copyright \(co 2000, 2001, 2003-2005, 2007, 2014-2016, 2018-2020 Internet Systems Consortium, Inc. ("ISC")

.br