---
name: "ibv_alloc_buf"
section: "3"
platform: "linux"
package: "rdma-core"
version: "65.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ibv_alloc_buf"
---

# ibv\_alloc\_buf(3)

allocate provider-aware buffers and register them as memory regions

## NAME

ibv\_alloc\_buf, ibv\_free\_buf, ibv\_reg\_buf\_mr, ibv\_export\_buf\_dmabuf\_fd - allocate provider-aware buffers and register them as memory regions

## SYNOPSIS

-

  ```
  #include <infiniband/verbs.h>
  void *ibv_alloc_buf(struct ibv_pd *pd, size_t size, struct ibv_buf **buf);
  void ibv_free_buf(struct ibv_buf *buf);
  struct ibv_mr *ibv_reg_buf_mr(struct ibv_pd *pd, struct ibv_buf *buf, void *addr,
                                size_t length, int access);
  int ibv_export_buf_dmabuf_fd(struct ibv_buf *buf);
  ```

## DESCRIPTION

**ibv\_alloc\_buf()** allocates a buffer using the allocation method selected by the provider for the protection domain *pd*. On success it returns the mapped address and stores an opaque buffer handle in *buf*. The handle is used by **ibv\_free\_buf()**, **ibv\_reg\_buf\_mr()**, **ibv\_reg\_mr\_ex()** with **IBV\_REG\_MR\_MASK\_BUF**, and **ibv\_export\_buf\_dmabuf\_fd()**; it must not be interpreted by applications.

**ibv\_free\_buf()** releases a buffer handle returned by **ibv\_alloc\_buf()**. The protection domain used for allocation must remain valid until the buffer is freed.

**ibv\_reg\_buf\_mr()** registers a memory region for a buffer returned by **ibv\_alloc\_buf()**. Applications can register the same buffer through **ibv\_reg\_mr\_ex()** by setting both **IBV\_REG\_MR\_MASK\_BUF** and **IBV\_REG\_MR\_MASK\_ADDR**, passing the buffer handle in `mr_init_attr->buf` and the address to register in `mr_init_attr->addr`. When **IBV\_REG\_MR\_MASK\_BUF** is set the caller must not set **IBV\_REG\_MR\_MASK\_FD** or **IBV\_REG\_MR\_MASK\_FD\_OFFSET**, and, for a DMA-buf backed buffer, must not set **IBV\_REG\_MR\_MASK\_IOVA**; libibverbs derives these from the buffer handle and otherwise fails with **EINVAL**. The *pd* argument must be the same protection domain that was used to allocate the buffer. If a different protection domain is supplied, registration fails with **EINVAL**. For ordinary memory it behaves like **ibv\_reg\_mr()**. For provider allocations backed by a DMA-buf, it registers the corresponding DMA-buf range using the metadata stored in the opaque *buf* handle.

**ibv\_export\_buf\_dmabuf\_fd()** exports a new file descriptor for a buffer that is backed by a DMA-buf. This allows applications to pass provider-allocated memory to other APIs that import DMA-buf file descriptors. The returned file descriptor is owned by the caller and should be closed with **[close(2)](/close/2.md)** when no longer needed. Calling **ibv\_export\_buf\_dmabuf\_fd()** does not transfer ownership of the buffer handle or the internal descriptor used by libibverbs.

## ARGUMENTS

- *pd*

  For **ibv\_alloc\_buf()**, the protection domain (or parent domain) to allocate from; its provider selects the buffer’s backing allocation method. It must remain valid until the buffer is freed with **ibv\_free\_buf()**. For **ibv\_reg\_buf\_mr()**, the same protection domain that allocated *buf* (otherwise registration fails with **EINVAL**).

- *size*

  Size of the buffer to allocate, in bytes (**ibv\_alloc\_buf()**).

- *buf*

  For **ibv\_alloc\_buf()**, an output parameter set on success to an opaque buffer handle. For **ibv\_free\_buf()** and **ibv\_reg\_buf\_mr()**, the buffer handle returned by **ibv\_alloc\_buf()** to be released or registered, respectively. For **ibv\_export\_buf\_dmabuf\_fd()**, the buffer handle whose DMA-buf fd should be exported.

- *addr*

  The start address to register (**ibv\_reg\_buf\_mr()**): the buffer base returned by **ibv\_alloc\_buf()** or an address within that buffer.

- *length*

  Length in bytes to register (**ibv\_reg\_buf\_mr()**); *addr* + *length* must stay within the buffer.

- *access*

  Access flags for the memory region (**ibv\_reg\_buf\_mr()**), the same as for **ibv\_reg\_mr()**.

## RETURN VALUE

**ibv\_alloc\_buf()** returns the mapped buffer address on success, or NULL if the request fails.

**ibv\_reg\_buf\_mr()** returns a pointer to the registered MR on success, or NULL if the request fails.

**ibv\_free\_buf()** does not return a value.

**ibv\_export\_buf\_dmabuf\_fd()** returns a file descriptor \>= 0 on success, or -1 if the request fails with *errno* set. If *buf* is not backed by a DMA-buf, *errno* is set to **ENODATA**.

## NOTES

Applications running in a CoCo guest that need unprotected/shared memory should first create a parent domain with **IBV\_PARENT\_DOMAIN\_INIT\_ATTR\_ALLOW\_CC\_UNPROTECTED\_ALLOC**, then use that parent domain as the *pd* argument to **ibv\_alloc\_buf()** and **ibv\_reg\_buf\_mr()** (or **ibv\_reg\_mr\_ex()** with **IBV\_REG\_MR\_MASK\_BUF**).

## SEE ALSO

[**ibv\_alloc\_parent\_domain**(3)](/ibv_alloc_parent_domain/3.md), [**ibv\_reg\_mr**(3)](/ibv_reg_mr/3.md), [**ibv\_reg\_mr\_ex**(3)](/ibv_reg_mr_ex/3.md), **ibv\_reg\_dmabuf\_mr**(3)