ARES_SET_SOCKET_FUNCTIONS(3)

📦

version 1.34.9 · 5 versions

1.34.9 · alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, centos-stream 10, nixos 26.05 (latest)
1.19.1 · centos-stream 9
1.27.0 · ubuntu noble
1.18.1 · debian bookworm, ubuntu jammy
1.34.8 · debian trixie, fedora 43, fedora 44, nixpkgs unstable, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, centos-stream 10, nixos 26.05

🌸 NAME 🌸

ares_set_socket_functions, ares_set_socket_functions_ex — set socket io callbacks 💖

okay bestie, this one's from the Library Functions Manual and it's giving "build your own entire network transport layer" main character energy. buckle up 🎀

✨ SYNOPSIS ✨

#include <ares.h>

typedef enum {
  ARES_SOCKFUNC_FLAG_NONBLOCKING = 1 << 0
} ares_sockfunc_flags_t;

typedef enum {
  ARES_SOCKET_OPT_SENDBUF_SIZE,
  ARES_SOCKET_OPT_RECVBUF_SIZE,
  ARES_SOCKET_OPT_BIND_DEVICE,
  ARES_SOCKET_OPT_TCP_FASTOPEN
} ares_socket_opt_t;

typedef enum {
  ARES_SOCKET_CONN_TCP_FASTOPEN = 1 << 0
} ares_socket_connect_flags_t;

typedef enum {
  ARES_SOCKET_BIND_TCP = 1 << 0,
  ARES_SOCKET_BIND_CLIENT = 1 << 1
} ares_socket_bind_flags_t;

struct ares_socket_functions_ex {
  unsigned int version; /* ABI Version: must be "1" */
  unsigned int flags;

  ares_socket_t (*asocket)(int domain, int type, int protocol, void *user_data);
  int (*aclose)(ares_socket_t sock, void *user_data);
  int (*asetsockopt)(ares_socket_t sock, ares_socket_opt_t opt, const void *val,
                     ares_socklen_t val_size, void *user_data);
  int (*aconnect)(ares_socket_t sock, const struct sockaddr *address,
                  ares_socklen_t address_len, unsigned int flags,
                  void *user_data);
  ares_ssize_t (*arecvfrom)(ares_socket_t sock, void *buffer, size_t length,
                            int flags, struct sockaddr *address,
                            ares_socklen_t *address_len, void *user_data);
  ares_ssize_t (*asendto)(ares_socket_t sock, const void *buffer, size_t length,
                          int flags, const struct sockaddr *address,
                          ares_socklen_t address_len, void *user_data);
  int (*agetsockname)(ares_socket_t sock, struct sockaddr *address,
                      ares_socklen_t *address_len, void *user_data);
  int (*abind)(ares_socket_t sock, unsigned int flags,
               const struct sockaddr *address, socklen_t address_len,
               void *user_data);
  unsigned int (*aif_nametoindex)(const char *ifname, void *user_data);
  const char *(*aif_indextoname)(unsigned int ifindex, char *ifname_buf,
                                 size_t ifname_buf_len, void *user_data);
};

ares_status_t ares_set_socket_functions_ex(ares_channel_t *channel,
  const struct ares_socket_functions_ex *funcs, void *user_data);

struct ares_socket_functions {
    ares_socket_t (*asocket)(int, int, int, void *);
    int (*aclose)(ares_socket_t, void *);
    int (*aconnect)(ares_socket_t, const struct sockaddr *, ares_socklen_t, void *);
    ares_ssize_t (*arecvfrom)(ares_socket_t, void *, size_t, int,
                              struct sockaddr *, ares_socklen_t *, void *);
    ares_ssize_t (*asendv)(ares_socket_t, const struct iovec *, int, void *);
};

void ares_set_socket_functions(ares_channel_t *channel,
                               const struct ares_socket_functions * functions,
                               void *user_data);

🦋 DESCRIPTION 🦋

ares_set_socket_functions_ex(3) sets a whole little set of callback functions in the given ares channel handle. ✨

🚩 Cannot be used when ARES_OPT_EVENT_THREAD is passed to ares_init_options(3). like, that's a hard no bestie.

This function replaces the now deprecated ares_set_socket_functions(3) call. so yeah, the old one is giving ✨retired✨.

These callback functions will be invoked to create/destroy socket objects and perform io, instead of the normal system calls. A client application can override normal network operation fully through this functionality, and provide its own transport layer. literally you can take the wheel on the entire thing 🚗💨

Some callbacks may be optional and are documented as such below, but failing to implement such callbacks will disable certain features within c-ares. It is strongly recommended to implement all callbacks. fr fr, do all of them — half-implementing is not the vibe 🙈

All callback functions are expected to operate like their system equivalents, and to set errno(2) or WSASetLastError(2) to an appropriate error code on failure. It is strongly recommended that io callbacks are implemented to be asynchronous and indicated as such in the flags member. The io callbacks can return error codes of EAGAIN, EWOULDBLOCK, or WSAEWOULDBLOCK when they would otherwise block. 💅

The user_data value is provided to each callback function invocation to serve as context. your little bag of holding 🎀

The ares_set_socket_functions_ex(3) must provide the following structure members and callbacks (which are different from the ares_set_socket_functions(3) members and callbacks):

unsigned int version — ABI Version of structure. Must be set to a value of "1". no cap, exactly "1".
unsigned int flags — Flags available are specified in ares_sockfunc_flags_t.
ares_socket_t (*asocket)(int domain, int type, int protocol, void * user_data) — REQUIRED. Creates an endpoint for communication and returns a descriptor. domain, type, and protocol each correspond to the parameters of socket(2). Returns a handle to the newly created socket, or ARES_SOCKET_BAD on error. 💀
int (*aclose)(ares_socket_t fd, void * user_data) — REQUIRED. Closes the socket endpoint indicated by fd. See close(2).
int (*asetsockopt)(ares_socket_t fd, ares_socket_opt_t opt, const void * val, ares_socklen_t val_size, void * user_data) — REQUIRED. Set socket option. This shares a similar syntax to the BSD setsockopt(2) call, however c-ares uses different options for portability. The value is a pointer to the desired value, and each option has its own data type listed in the options below defined in ares_socket_opt_t.
int (*aconnect)(ares_socket_t fd, const struct sockaddr * addr, ares_socklen_t addr_len, unsigned int flags, void * user_data) — REQUIRED. Initiate a connection to the address indicated by addr on a socket. Additional flags controlling behavior are in ares_socket_connect_flags_t. See connect(2).
ares_ssize_t (*arecvfrom)(ares_socket_t fd, void * buffer, size_t buf_size, int flags, struct sockaddr * addr, ares_socklen_t * addr_len, void * user_data) — REQUIRED. Receives data from remote socket endpoint, if available. If the addr parameter is not NULL and the connection protocol provides the source address, the callback should fill this in. The flags parameter is currently unused. See recvfrom(2).

For UDP, the callback must fill in the full source address, including the source port, exactly as recvfrom(2) does. c-ares discards a datagram whose source address does not match the server it queried, or whose source port does not match that server's port.

🚨 Security: for compatibility with older callbacks, a reported source port of 0 is treated as unknown and only the address is checked. A callback that does not fill in the source port is therefore insecure: c-ares will accept answers sent from any port on the server's address, for example from another DNS server or any other service or user able to send UDP from that host, and those answers are cached and returned to the application. Such an implementation is non-compliant and should be fixed to report the real source port. like, please fix it bestie 😭🔒

ares_ssize_t (*asendto)(ares_socket_t fd, const void * buffer, size_t length, int flags, const struct sockaddr * address, ares_socklen_t address_len, void * user_data) — REQUIRED. Send data, as provided by the buffer, to the socket endpoint. The flags member may be used on systems that have MSG_NOSIGNAL defined but is otherwise unused. An address is provided primarily to support TCP FastOpen scenarios, which will be NULL in other circumstances. See sendto(2).
int (*agetsockname)(ares_socket_t fd, struct sockaddr * address, ares_socklen_t * address_len, void * user_data) — Optional. Retrieve the local address of a socket and store it into the provided address buffer. May impact DNS Cookies if not provided. See getsockname(2). 🍪
int (*abind)(ares_socket_t fd, unsigned int flags, const struct sockaddr * address, ares_socklen_t address_len, void * user_data) — Optional. Bind the socket to an address. This can be used for client connections to bind the source address for packets before connect, or for server connections to bind to an address and port before listening. Currently c-ares only supports client connections. flags from ares_socket_bind_flags_t can be specified. See bind(2).
unsigned int (*aif_nametoindex)(const char * ifname, void * user_data) — Optional. Convert an interface name into the interface index. If this callback is not specified, then IPv6 Link-Local DNS servers cannot be used. See if_nametoindex(2).
const char * (*aif_indextoname)(unsigned int ifindex, char * ifname_buf, size_t ifname_buf_len, void * user_data) — Optional. Convert an interface index into the interface name. If this callback is not specified, then IPv6 Link-Local DNS servers cannot be used. ifname_buf must be at least IF_NAMESIZE or IFNAMSIZ in size. See if_indextoname(2).

⭐ `ares_sockfunc_flags_t` values ⭐

ARES_SOCKFUNC_FLAG_NONBLOCKING — Used to indicate the implementation of the io functions are asynchronous. 🧚

🍓 `ares_socket_opt_t` values 🍓

ARES_SOCKET_OPT_SENDBUF_SIZE — Set the Send Buffer size. Value is a pointer to an int. (SO_SNDBUF).
ARES_SOCKET_OPT_RECVBUF_SIZE — Set the Receive Buffer size. Value is a pointer to an int. (SO_RCVBUF).
ARES_SOCKET_OPT_BIND_DEVICE — Set the network interface to use as the source for communication. Value is a C string. (SO_BINDTODEVICE)
ARES_SOCKET_OPT_TCP_FASTOPEN — Enable TCP Fast Open. Value is a pointer to an ares_bool_t. On some systems this could be a no-op if it is known it is on by default and return success. Other systems may be a no-op if known the system does not support the feature and returns failure with errno set to ENOSYS or WSASetLastError(WSAEOPNOTSUPP);. 🔥

🌈 `ares_socket_connect_flags_t` values 🌈

ARES_SOCKET_CONN_TCP_FASTOPEN — Connect using TCP Fast Open. zoom zoom ⚡

👑 `ares_socket_bind_flags_t` values 👑

ARES_SOCKET_BIND_TCP — Bind is for a TCP connection.

okay we're literally not done yet — the list keeps going and part 2 has the rest 💅

ARES_SOCKET_BIND_CLIENT — this one means bind is for a client connection, not a server one 👀 like, don't get it twisted bestie.

the actual deets on the callback set 💅

Okay so ares_set_socket_functions(3) sets a whole little squad of callback functions into the ares channel handle you hand it. 🫶 But heads up: you cannot use it when ARES_OPT_EVENT_THREAD is passed to ares_init_options(3) — that combo is a no ✨.

Also, real talk: this function is deprecated as of c-ares 1.34.0 in favor of ares_set_socket_functions_ex(3). So it still works, it's just giving legacy era energy 🎀.

Here's the cute part: ares_set_socket_functions(3) lets you implement only some of the socket functions and just pass NULL for the rest — and c-ares will quietly use its own built-in system functions for those. Literally pick and choose, iykyk ✨.

All the callback functions are expected to behave exactly like their system equivalents, and to set errno(2) (or WSASetLastError(2)) to an appropriate error code when they fail. And it is strongly recommended that all your io functions behave asynchronously and return error codes of EAGAIN, EWOULDBLOCK, or WSAEWOULDBLOCK when they would otherwise block — otherwise your whole vibe is ruined 😭.

The user_data value gets passed into every single callback invocation so you've got context to work with. 💖

And ares_set_socket_functions(3) must provide the following callbacks (and yes, these are different from the ares_set_socket_functions_ex(3) callbacks — don't mix them up):

ares_socket_t (*asocket)(int domain, int type, int protocol, void * user_data) — creates an endpoint for communication and returns a descriptor. domain, type, and protocol each correspond to the parameters of socket(2). Returns a handle to the newly created socket, or ARES_SOCKET_BAD on error. 🦋
int (*aclose)(ares_socket_t fd, void * user_data) — closes the socket endpoint indicated by fd. See close(2). bye felicia 👋
int (*aconnect)(ares_socket_t fd, const struct sockaddr * addr, ares_socklen_t addr_len, void * user_data) — initiates a connection to the address indicated by addr on a socket. See connect(2). 🤝
ares_ssize_t (*arecvfrom)(ares_socket_t fd, void * buffer, size_t buf_size, int flags, struct sockaddr * addr, ares_socklen_t * addr_len, void * user_data) — receives data from the remote socket endpoint, if it's available. If the addr parameter is not NULL and the connection protocol provides the source address, the callback should fill this in. See recvfrom(2). 📥

For UDP, the callback must fill in the full source address, including the source port, as described above for arecvfrom in ares_set_socket_functions_ex.

⚠️ Security moment, pay attention bestie: a callback that does not fill in the source port is insecure, and c-ares will accept answers sent from any port on the server's address. that's giving open door energy 💀🔓

ares_ssize_t (*asendv)(ares_socket_t fd, const struct iovec * data, int len, void * user_data) — sends data, as provided by the iovec array data, to the socket endpoint. See writev(2). 📤

struct lifetime, aka the part where you can't be sloppy 🙈

The ares_set_socket_functions(3) struct you provide is not copied — it's directly referenced — so it must remain valid throughout the channel's lifetime and the lifetime of any socket created. Like, it has to stay alive the whole time, no cap. 🫶

However! The ares_set_socket_functions_ex(3) struct is duplicated and does not need to survive past the call to the function. slay for that one ✨

when your callbacks get called (read this, fr fr) 🔥

These callback functions are invoked while c-ares is part-way through creating, connecting, writing to, reading from, or closing a socket. So they must only perform the requested socket operation, and must not call any c-ares function on the same channel 😤.

For example, they must not enqueue or cancel queries, process socket events, change the server configuration, or destroy the channel. Doing any of that is not supported. periodt 💅

Work of that kind belongs in a query callback, the server state callback set by ares_set_server_state_callback(3), or the socket state callback (ARES_OPT_SOCK_STATE_CB) described in ares_init_options(3).

Functions may be called on a different channel, though — that door stays open bestie 🚪✨

🌈 AVAILABILITY

ares_socket_functions added in c-ares 1.13.0, ares_socket_functions_ex added in c-ares 1.34.0 ⭐

and that's the whole page, bestie!! 🎀 this iconic lil manual page is dated 8 Oct 2024, and it's the ARES_SET_S...T_FUNCTIONS(3) page from the Library Functions Manual — go forth and implement your sockets responsibly 💖✨🌸

📦 where this page comes from

alpine 3.22: c-ares-doc 1.34.9-r0 · MIT
alpine 3.23: c-ares-doc 1.34.9-r0 · MIT
alpine 3.24: c-ares-doc 1.34.9-r0 · MIT
arch rolling: c-ares 1.34.9-1 · MIT
centos-stream 10: c-ares-devel 1.34.9-1.el10 · MIT
nixos 26.05: c-ares 1.34.9
📜 the page's license: MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms