IBV_GET_DEVICE_LIST(3)

📦
version 62.0 · 9 versions
, in alpine 3.24, centos-stream 10, centos-stream 9, ubuntu jammy

💖 ibv_get_device_list — get and release the list of available RDMA devices 💖

okay bestie, this one lives in the Libibverbs Programmer's Manual (section 3, ibv_get_device_list(3)), and it's literally just "gimme the devices" + "okay put them back." iconic duo energy. let's go 🫶

✨ SYNOPSIS ✨

#include <infiniband/verbs.h>

struct ibv_device **ibv_get_device_list(int *num_devices);

void ibv_free_device_list(struct ibv_device **list);

🌸 DESCRIPTION 🌸

ibv_get_device_list() hands you a NULL-terminated array of the RDMA devices that are currently available. slay. 💅

The num_devices argument is optional — like, it's totally fine to pass nothing. But if it's not NULL, it gets set to the number of devices returned in the array. so you always know how many you got. no guessing, no cap.

ibv_free_device_list() frees that array of devices that ibv_get_device_list() gave you. that's it. that's the whole job. 🎀

🔥 RETURN VALUE 🔥

ibv_get_device_list() returns the array of available RDMA devices. if the request fails, it sets errno and returns NULL. 😭

and pssst — the zero-devices case is not an error, okay? if no devices are found, num_devices gets set to 0 and a non-NULL value is returned. so don't panic and don't leak it, just free it like a normal array. 💀

ibv_free_device_list() returns no value. it's giving "void function, zero drama." ✨

💀 ERRORS 💀

  • EPERM — Permission denied. (rude.)
  • ENOSYS — No kernel support for RDMA.
  • ENOMEM — Insufficient memory to complete the operation.

💜 NOTES 💜

okay this part is important, bestie, listen up 👑

Client code should open all the devices it intends to use with ibv_open_device() before calling ibv_free_device_list(). because once you free that array with ibv_free_device_list(), the only devices you can still use are the ones you already opened. pointers to unopened devices are no longer valid — like, dead, gone, don't touch them. 🙈

also: setting the environment variable IBV_SHOW_WARNINGS will cause warnings to be emitted to stderr if a kernel verbs device is discovered, but no corresponding userspace driver can be found for it. so if something's acting sus, that's your vibe check. 🔍

🧚 STATIC LINKING 🧚

okay so this is the part where things get real. if libibverbs is statically linked to the application, then all provider drivers must also be statically linked. the library will not load dynamic providers when static linking is used. periodt.

To link the providers, set the RDMA_STATIC_PROVIDERS define to the comma separated list of desired providers when compiling the application. and the special keyword all will statically link all supported libibverbs providers. iykyk. 🌈

This is intended to be used along with pkg-config(1) to setup the proper flags for libibverbs linking. 🔧

⚠️ if this is not done then ibv_get_device_list will always return an empty list. like... empty empty. nothing. zero devices. 😭 so please don't skip this step.

Using only dynamic linking for libibverbs applications is strongly recommended. like, the manual is basically begging you. take the hint bestie 🫶

🦋 SEE ALSO 🦋

👑 AUTHOR 👑

Dotan Barak <dotanba@gmail.com> — thank you for your service, king 🫡💖

okay that's the whole page, bestie! this gorgeous little doc is from libibverbs, dated 2006-10-31, and it's still out here doing the most. go open your devices before you free them, stan static linking responsibly, and drink some water 💜✨🎀

📦 where this page comes from