.\" Automatically generated by Pandoc 3.11 .\" .TH "ibv_alloc_user_buf" "3" "2026\-08\-19" "libibverbs" "Libibverbs Programmer\(cqs Manual" .SH NAME ibv_alloc_user_buf, ibv_free_user_buf \- associate an ibv_buf with application\-owned memory .SH SYNOPSIS .IP .EX #include \f[B]\f[R] \f[B]struct\f[R] ibv_buf *ibv_alloc_user_buf(\f[B]struct\f[R] ibv_pd *pd, void *addr, size_t size, int dmabuf_fd); void ibv_free_user_buf(\f[B]struct\f[R] ibv_buf *buf); .EE .SH DESCRIPTION \f[B]ibv_alloc_user_buf()\f[R] associates an \f[B]ibv_buf\f[R] with memory the application already owns, either a plain virtual address range or a DMA\-buf. Unlike \f[B]ibv_alloc_buf()\f[R], no memory is allocated; \f[I]addr\f[R] must already be a valid virtual address for that memory, and must remain valid for as long as the returned handle is in use. .PP \f[B]ibv_free_user_buf()\f[R] releases a handle returned by \f[B]ibv_alloc_user_buf()\f[R]. It does not free or otherwise affect the underlying memory; only the handle itself and any bookkeeping \f[B]ibv_alloc_user_buf()\f[R] performed (such as fork protection) are released. .PP The returned handle is meant for providers that accept an \f[B]ibv_buf\f[R] directly without registering an MR, such as driver\-specific control\-buffer descriptors. .PP \f[B]Use of this API is discouraged.\f[R] Applications should allocate buffers with \f[B]ibv_alloc_buf()\f[R] whenever possible. See NOTES below. .SH ARGUMENTS .TP \f[I]pd\f[R] Protection domain the buffer is associated with. .TP \f[I]addr\f[R] Application\-owned virtual address of the buffer. .TP \f[I]size\f[R] Size of the buffer in bytes. .TP \f[I]dmabuf_fd\f[R] A DMA\-buf file descriptor backing the buffer, or \-1 if the buffer is plain virtual memory at \f[I]addr\f[R]. .TP \f[I]buf\f[R] Handle returned by \f[B]ibv_alloc_user_buf()\f[R], to be released with \f[B]ibv_free_user_buf()\f[R]. .SH NOTES \f[B]ibv_alloc_buf()\f[R] is the preferred way to obtain an \f[B]ibv_buf\f[R]. Its allocation is selected by the provider for the protection domain, and therefore accounts for platform requirements such as confidential computing (CoCo), where memory may have to be allocated as unprotected/shared memory (see \f[B]IBV_PARENT_DOMAIN_INIT_ATTR_ALLOW_CC_UNPROTECTED_ALLOC\f[R] in \f[B]ibv_alloc_parent_domain\f[R](3)). .PP \f[B]ibv_alloc_user_buf()\f[R] bypasses this allocator abstraction. Neither libibverbs nor the provider can verify or adjust memory the application allocated itself, so the application is solely responsible for ensuring that the memory is suitable for the device and for the platform it runs on (for example, that it is usable by the device inside a CoCo guest). The application generally does not have enough information to guarantee this in a portable way. .PP Use this API only when the memory must come from a source that \f[B]ibv_alloc_buf()\f[R] cannot provide, such as an existing DMA\-buf allocation shared with another device or subsystem, or memory whose lifetime is managed by the application. Otherwise, use \f[B]ibv_alloc_buf()\f[R]. .SH RETURN VALUE \f[B]ibv_alloc_user_buf()\f[R] returns a buffer handle on success, or NULL if the request fails. .PP \f[B]ibv_free_user_buf()\f[R] does not return a value. .SH SEE ALSO \f[B]ibv_alloc_buf\f[R](3), \f[B]ibv_alloc_parent_domain\f[R](3)