---
name: "ares_process_pending_write"
section: "3"
platform: "linux"
package: "c-ares"
version: "1.34.9-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ares_set_pending_write_cb"
---

# ares\_process\_pending\_write(3)

Function for setting a callback which is triggered when there is potential pending data which needs to be written.

Part of [ares\_set\_pending\_write\_cb(3)](/ares_set_pending_write_cb/3.md).

## NAME

ares\_set\_pending\_write\_cb, ares\_process\_pending\_write - Function for setting a callback which is triggered when there is potential pending data which needs to be written.

## SYNOPSIS

```
#include <ares.h>
typedef void (*ares_pending_write_cb)(void *data);
void ares_set_pending_write_cb(
  ares_channel_t        *channel,
  ares_pending_write_cb  callback,
  void                  *user_data);
void ares_process_pending_write(ares_channel_t *channel);
```

## DESCRIPTION

The **[ares\_set\_pending\_write\_cb(3)](/ares_set_pending_write_cb/3.md)** function sets a callback function *callback* in the given ares channel handle *channel* that is invoked whenever there is new pending TCP data to be written.  Since TCP is stream based, if there are multiple queries being enqueued back to back they can be sent as one large buffer. Normally a **[send(2)](/send/2.md)** syscall operation would be triggered for each query.

When setting this callback, an event will be triggered when data is buffered, but not written.  This event is used to wake the caller's event loop which should call **[ares\_process\_pending\_write(3)](/ares_process_pending_write/3.md)** using the channel associated with the callback.  Each time the callback is triggered must result in a call to **[ares\_process\_pending\_write(3)](/ares_process_pending_write/3.md)** from the caller's event loop otherwise stalls and timeouts may occur.  The callback **must not** call any c-ares function on the same channel; its only job is to wake the event loop.  In particular, calling **[ares\_process\_pending\_write(3)](/ares_process_pending_write/3.md)** directly would invalidate any advantage of this use-case.

This is considered an optimization, especially when using TLS-based connections which add additional overhead to the data stream.  Due to the asyncronous nature of c-ares, there is no way to identify when a caller may be finished enqueuing queries via any of the possible public API calls such as **[ares\_getaddrinfo(3)](/ares_getaddrinfo/3.md)** or **[ares\_search\_dnsrec(3)](/ares_search_dnsrec/3.md)**, so this is an enhancement to try to group query send operations together and will rely on the singaling latency involved in waking the user's event loop.

If no callback is set, data will be written immediately to the socket, thus bypassing this optimization.

This option cannot be used with *ARES\_OPT\_EVENT\_THREAD* passed to **[ares\_init\_options(3)](/ares_init_options/3.md)** since the user has no event loop.  This optimization is automatically enabled when using the Event Thread as it sets the callback for its own internal signaling.

## AVAILABILITY

This function was first introduced in c-ares version 1.34.0.

## SEE ALSO

[**ares\_init\_options**(3)](/ares_init_options/3.md)