.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "ibv_alloc_buf" "3" "2026-05-29" "libibverbs" "Libibverbs Programmer\[cq]s Manual"
.hy
.SH NAME
.PP
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
.SH SYNOPSIS
.IP
.nf
\f[C]
#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);
\f[R]
.fi
.SH DESCRIPTION
.PP
\f[B]ibv_alloc_buf()\f[R] allocates a buffer using the allocation method
selected by the provider for the protection domain \f[I]pd\f[R].
On success it returns the mapped address and stores an opaque buffer
handle in \f[I]buf\f[R].
The handle is used by \f[B]ibv_free_buf()\f[R],
\f[B]ibv_reg_buf_mr()\f[R], \f[B]ibv_reg_mr_ex()\f[R] with
\f[B]IBV_REG_MR_MASK_BUF\f[R], and \f[B]ibv_export_buf_dmabuf_fd()\f[R];
it must not be interpreted by applications.
.PP
\f[B]ibv_free_buf()\f[R] releases a buffer handle returned by
\f[B]ibv_alloc_buf()\f[R].
The protection domain used for allocation must remain valid until the
buffer is freed.
.PP
\f[B]ibv_reg_buf_mr()\f[R] registers a memory region for a buffer
returned by \f[B]ibv_alloc_buf()\f[R].
Applications can register the same buffer through
\f[B]ibv_reg_mr_ex()\f[R] by setting both \f[B]IBV_REG_MR_MASK_BUF\f[R]
and \f[B]IBV_REG_MR_MASK_ADDR\f[R], passing the buffer handle in
\f[C]mr_init_attr->buf\f[R] and the address to register in
\f[C]mr_init_attr->addr\f[R].
When \f[B]IBV_REG_MR_MASK_BUF\f[R] is set the caller must not set
\f[B]IBV_REG_MR_MASK_FD\f[R] or \f[B]IBV_REG_MR_MASK_FD_OFFSET\f[R],
and, for a DMA-buf backed buffer, must not set
\f[B]IBV_REG_MR_MASK_IOVA\f[R]; libibverbs derives these from the buffer
handle and otherwise fails with \f[B]EINVAL\f[R].
The \f[I]pd\f[R] argument must be the same protection domain that was
used to allocate the buffer.
If a different protection domain is supplied, registration fails with
\f[B]EINVAL\f[R].
For ordinary memory it behaves like \f[B]ibv_reg_mr()\f[R].
For provider allocations backed by a DMA-buf, it registers the
corresponding DMA-buf range using the metadata stored in the opaque
\f[I]buf\f[R] handle.
.PP
\f[B]ibv_export_buf_dmabuf_fd()\f[R] 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 \f[B]close(2)\f[R] when no longer needed.
Calling \f[B]ibv_export_buf_dmabuf_fd()\f[R] does not transfer ownership
of the buffer handle or the internal descriptor used by libibverbs.
.SH ARGUMENTS
.TP
\f[I]pd\f[R]
For \f[B]ibv_alloc_buf()\f[R], the protection domain (or parent domain)
to allocate from; its provider selects the buffer\[cq]s backing
allocation method.
It must remain valid until the buffer is freed with
\f[B]ibv_free_buf()\f[R].
For \f[B]ibv_reg_buf_mr()\f[R], the same protection domain that
allocated \f[I]buf\f[R] (otherwise registration fails with
\f[B]EINVAL\f[R]).
.TP
\f[I]size\f[R]
Size of the buffer to allocate, in bytes (\f[B]ibv_alloc_buf()\f[R]).
.TP
\f[I]buf\f[R]
For \f[B]ibv_alloc_buf()\f[R], an output parameter set on success to an
opaque buffer handle.
For \f[B]ibv_free_buf()\f[R] and \f[B]ibv_reg_buf_mr()\f[R], the buffer
handle returned by \f[B]ibv_alloc_buf()\f[R] to be released or
registered, respectively.
For \f[B]ibv_export_buf_dmabuf_fd()\f[R], the buffer handle whose
DMA-buf fd should be exported.
.TP
\f[I]addr\f[R]
The start address to register (\f[B]ibv_reg_buf_mr()\f[R]): the buffer
base returned by \f[B]ibv_alloc_buf()\f[R] or an address within that
buffer.
.TP
\f[I]length\f[R]
Length in bytes to register (\f[B]ibv_reg_buf_mr()\f[R]); \f[I]addr\f[R]
+ \f[I]length\f[R] must stay within the buffer.
.TP
\f[I]access\f[R]
Access flags for the memory region (\f[B]ibv_reg_buf_mr()\f[R]), the
same as for \f[B]ibv_reg_mr()\f[R].
.SH RETURN VALUE
.PP
\f[B]ibv_alloc_buf()\f[R] returns the mapped buffer address on success,
or NULL if the request fails.
.PP
\f[B]ibv_reg_buf_mr()\f[R] returns a pointer to the registered MR on
success, or NULL if the request fails.
.PP
\f[B]ibv_free_buf()\f[R] does not return a value.
.PP
\f[B]ibv_export_buf_dmabuf_fd()\f[R] returns a file descriptor >= 0 on
success, or -1 if the request fails with \f[I]errno\f[R] set.
If \f[I]buf\f[R] is not backed by a DMA-buf, \f[I]errno\f[R] is set to
\f[B]ENODATA\f[R].
.SH NOTES
.PP
Applications running in a CoCo guest that need unprotected/shared memory
should first create a parent domain with
\f[B]IBV_PARENT_DOMAIN_INIT_ATTR_ALLOW_CC_UNPROTECTED_ALLOC\f[R], then
use that parent domain as the \f[I]pd\f[R] argument to
\f[B]ibv_alloc_buf()\f[R] and \f[B]ibv_reg_buf_mr()\f[R] (or
\f[B]ibv_reg_mr_ex()\f[R] with \f[B]IBV_REG_MR_MASK_BUF\f[R]).
.SH SEE ALSO
.PP
\f[B]ibv_alloc_parent_domain\f[R](3), \f[B]ibv_reg_mr\f[R](3),
\f[B]ibv_reg_mr_ex\f[R](3), \f[B]ibv_reg_dmabuf_mr\f[R](3)
