.\" Extracted by src2man from /build/rpma-11eW7Q/rpma-1.3.0/src/include/librpma.h
.\" Text automatically generated by txt2man
.TH rpma_recv 3 "29 May 2023" "RPMA" "RPMA Programmer's Manual"
.SH NAME
\fBrpma_recv \fP- initiate the receive operation
.SH SYNOPSIS
.nf
.fam C
      #include <librpma.h>

      struct rpma_conn;
      struct rpma_mr_local;
      int \fBrpma_recv\fP(struct rpma_conn *conn, struct rpma_mr_local *dst, size_t offset, size_t len,
                      const void *op_context);

.fam T
.fi
.fam T
.fi
.SH DESCRIPTION
\fBrpma_recv\fP() initiates the receive operation which prepares a buffer for a message sent from
other side of the connection. Please see \fBrpma_send\fP(3).
.PP
All buffers prepared via \fBrpma_recv\fP(3) form an unordered set. When a message arrives it is placed
in one of the buffers awaitaning and a completion for the receive operation is generated.
.PP
A buffer for an incoming message have to be prepared beforehand.
.PP
The order of buffers in the set does not affect the order of completions of receive operations
get via \fBrpma_cq_get_wc\fP(3).
.PP
op_context is returned in the wr_id field of the completion (struct ibv_wc).
.SH NOTE
In the RDMA standard, receive requests form an ordered queue.
The RPMA does NOT inherit this guarantee.
.SH RETURN VALUE
The \fBrpma_recv\fP() function returns 0 on success or a negative error code on failure.
.SH ERRORS
\fBrpma_recv\fP() can fail with the following errors:
.IP \(bu 3
RPMA_E_INVAL - conn == NULL
.IP \(bu 3
RPMA_E_INVAL - dst == NULL && (offset != 0 || len != 0)
.IP \(bu 3
RPMA_E_PROVIDER - \fBibv_post_recv\fP(3) failed
.SH SEE ALSO
\fBrpma_conn_req_connect\fP(3), \fBrpma_mr_reg\fP(3), \fBlibrpma\fP(7) and https://pmem.io/rpma/