---
name: "lwres_context_create"
section: "3"
platform: "linux"
package: "libbind-dev"
version: "1:9.11.5.P4+dfsg-5.1+deb10u7"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/lwres_context_create"
---

# lwres\_context\_create(3)

lightweight resolver context management

## 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

## SYNOPSIS

```
#include <lwres/lwres.h>
```

**lwres\_result\_t lwres\_context\_create(lwres\_context\_t \*\****contextp***, void \****arg***, lwres\_malloc\_t** *malloc\_function***, lwres\_free\_t** *free\_function***);**

**lwres\_result\_t lwres\_context\_destroy(lwres\_context\_t \*\****contextp***);**

**void lwres\_context\_initserial(lwres\_context\_t \****ctx***, uint32\_t** *serial***);**

**uint32\_t lwres\_context\_nextserial(lwres\_context\_t \****ctx***);**

**void lwres\_context\_freemem(lwres\_context\_t \****ctx***, void \****mem***, size\_t** *len***);**

**void lwres\_context\_allocmem(lwres\_context\_t \****ctx***, size\_t** *len***);**

**void \* lwres\_context\_sendrecv(lwres\_context\_t \****ctx***, void \****sendbase***, int** *sendlen***, void \****recvbase***, int** *recvlen***, int \****recvd\_len***);**

## DESCRIPTION

**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**(3)](/malloc/3.md). and [**free**(3)](/free/3.md). 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**(3)](/lwres_conf_init/3.md) 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*.

## 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.

## SEE ALSO

[**lwres\_conf\_init**(3)](/lwres_conf_init/3.md), [**malloc**(3)](/malloc/3.md), [**free**(3)](/free/3.md).

## AUTHOR

**Internet Systems Consortium, Inc.**

## COPYRIGHT

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