RDMA_GETADDRINFO(3)

📦

version 65.0 · 4 versions

65.0 · alpine 3.24, arch rolling, centos-stream 10, centos-stream 9, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking (latest)
15.1 · freebsd 14.5, freebsd 15.1
50.0 · debian bookworm, ubuntu jammy, ubuntu noble
58.0 · debian trixie, fedora 43, opensuse-leap 16.0, ubuntu questing

, in alpine 3.24, arch rolling, centos-stream 10, centos-stream 9, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

✨ RDMA_GETADDRINFO ✨

okay so bestie, you know how getaddrinfo exists and it's giving "figure out where I'm actually going"? This is that, but for RDMA. Welcome to the librdmacm Programmer's Manual corner of the world, page RDMA_GETADDRINFO(3). Buckle up. 🦋

NAME 💖

rdma_getaddrinfo — Provides transport independent address translation.

literally the glow-up of address resolution. no cap.

SYNOPSIS 🎀

#include <rdma/rdma_cma.h>

int rdma_getaddrinfo (const char *node, const char *service, const
struct rdma_addrinfo *hints, struct rdma_addrinfo **res);

ARGUMENTS 🫶

node — Optional, bestie. It's a name, a dotted-decimal IPv4 address, or an IPv6 hex address that you want resolved. Or just leave it out, she's flexible. 💅
service — The service name or the port number of the address. yes queen.
hints — A reference to an rdma_addrinfo structure stuffed full of hints about the kind of service the caller supports. it's giving "here's what I'm into". ✨
res — A pointer to a linked list of rdma_addrinfo structures holding the response information. the answer key, if you will. 👑

DESCRIPTION 🌸

Resolves the destination node and service address and returns the information you need to establish communication. It's the RDMA functional equivalent of getaddrinfo — same energy, more fabric. 🔥

RETURN VALUE ⭐

Returns 0 on success, or -1 on error (errno will be set to indicate the failure reason), or one of the following nonzero error codes:

EAI_ADDRFAMILY — The specified network host does not have any network addresses in the requested address family. not a single one. 💀
EAI_AGAIN — The name server returned a temporary failure indication. Try again later, babe, it's just not the moment.
EAI_BADFLAGS — hints.ai_flags contains invalid flags. bestie what did you even type. 🙈
EAI_FAIL — The name server returned a permanent failure indication. that's not a "later" situation, that's a forever situation.
EAI_FAMILY — The requested address family is not supported. we do not do that family here.
EAI_MEMORY — Out of memory. 😭
EAI_NODATA — The specified network host exists, but does not have any network addresses defined. she's real but she's empty.
EAI_NONAME — The node or service is not known; or both node and service are NULL.
EAI_SERVICE — The requested service is not available for the requested QP type. It may be available through another QP type. don't give up, just switch it up. 💅
EAI_QPTYPE — The requested socket type is not supported. This could occur, for example, if hints.ai_qptype and hints.ai_port_space are inconsistent (e.g., IBV_QPT_UD and RDMA_PS_TCP, respectively). yeah those two are NOT matching energies.
EAI_SYSTEM — Other system error, check errno for details. The gai_strerror() function translates these error codes to a human readable string, suitable for error reporting. shoutout gai_strerror(), the translator we all need. 🫶

NOTES 🧚

Either node, service, or hints must be provided. Like, at least one of them. pick a lane. 😌

If hints are provided, the operation will be controlled by hints.ai_flags.

If RAI_PASSIVE is specified, the call will resolve address information for use on the passive side of a connection.

If node is provided, rdma_getaddrinfo will attempt to resolve the RDMA address, route, and connection data to the given node.

The hints parameter, if provided, may be used to control the resulting output as indicated below.

If node is not given, rdma_getaddrinfo will attempt to resolve the RDMA addressing information based on the hints.ai_src_addr, hints.ai_dst_addr, or hints.ai_route.

rdma_addrinfo 👑

the main character struct herself. here's every field, no skipping:

ai_flags — Hint flags that control the operation. Supported flags are:
- RAI_PASSIVE — Indicates that the results will be used on the passive/listening side of a connection.
- RAI_NUMERICHOST — If specified, then the node parameter, if provided, must be a numerical network address. This flag suppresses any lengthy address resolution. no long waits, we're going straight to the digits. ✨
- RAI_NOROUTE — If set, this flag suppresses any lengthy route resolution.
- RAI_FAMILY — If set, the ai_family setting should be used as an input hint for interpretting the node parameter.
- RAI_DNS — Indicates that address resolution should use DNS to map the node and service names to addresses. Flag is mutually exclusive with RAI_SA. DNS resolution is the default option. (yes, the typo "interpretting" is canon, we don't touch it 💅)
- RAI_SA — Indicates that address resolution should query the Infiniband SA to map node and service names to addresses. Flag is mutually exclusive with RAI_DNS. SA resolution only applies to Infiniband ports. Non-Infiniband ports will be skipped.
ai_family — Address family for the source and destination address. Supported families are: AF_INET, AF_INET6, and AF_IB.
ai_qp_type — Indicates the type of RDMA QP used for communication. Supported types are: IBV_QPT_UD (unreliable datagram) and IBV_QPT_RC (reliable connected).
ai_port_space — RDMA port space in use. Supported values are: RDMA_PS_UDP, RDMA_PS_TCP, and RDMA_PS_IB.
ai_src_len — The length of the source address referenced by ai_src_addr. This will be 0 if an appropriate source address could not be discovered for a given destination.
ai_dst_len — The length of the destination address referenced by ai_dst_addr. This will be 0 if the RAI_PASSIVE flag was specified as part of the hints.
ai_src_addr — If provided, the address for the local RDMA device.
ai_dst_addr — If provided, the address for the destination RDMA device.
ai_src_canonname — The canonical for the source.
ai_dst_canonname — The canonical for the destination.
ai_route_len — Size of the routing information buffer referenced by ai_route. This will be 0 if the underlying transport does not require routing data, or none could be resolved.
ai_route — Routing information for RDMA transports that require routing data as part of connection establishment. The format of the routing data depends on the underlying transport. If Infiniband transports are used, ai_route will reference an array of struct ibv_path_data on output, if routing data is available. Routing paths may be restricted by setting desired routing data fields on input to rdma_getaddrinfo. For Infiniband, hints.ai_route may reference an array of struct ibv_path_record or struct ibv_path_data on input.
ai_connect_len — Size of connection information referenced by ai_connect. This will be 0 if the underlying transport does not require additional connection information.
ai_connect — Data exchanged as part of the connection establishment process. If provided, ai_connect data must be transferred as private data, with any user supplied private data following it.
ai_next — Pointer to the next rdma_addrinfo structure in the list. Will be NULL if no more structures exist. the end of the thread, bestie. 🌈