.\" Automatically generated by Pandoc 3.10.2
.\"
.TH "ibv_qp_attach_comp_cntr" "3" "2026\-02\-09" "libibverbs" "Libibverbs Programmer\(cqs Manual"
.SH NAME
\f[B]ibv_qp_attach_comp_cntr\f[R] \- Attach a completion counter to a QP
.SH SYNOPSIS
.IP
.EX
#include \f[B]<infiniband/verbs.h>\f[R]

int ibv_qp_attach_comp_cntr(\f[B]struct\f[R] ibv_qp *qp,
                            \f[B]struct\f[R] ibv_comp_cntr *comp_cntr,
                            \f[B]struct\f[R] ibv_qp_attach_comp_cntr_attr *attr);
.EE
.SH DESCRIPTION
\f[B]ibv_qp_attach_comp_cntr\f[R]() attaches the completion counter
\f[I]comp_cntr\f[R] to the queue pair \f[I]qp\f[R].
The \f[I]attr\f[R] argument specifies which operation types should
update the counter.
.PP
The QP must be in \f[B]IBV_QPS_RESET\f[R] or \f[B]IBV_QPS_INIT\f[R]
state when attaching a completion counter.
Attempting to attach a counter to a QP in any other state will fail with
EINVAL.
.PP
The completion counter starts collecting values for the specified QP
once attached.
Attaching the same completion counter to multiple QPs will accumulate
values from all attached QPs into the same counter.
.PP
The \f[I]op_mask\f[R] field controls which operation completions are
counted.
Local operations (\f[B]IBV_QP_ATTACH_COMP_CNTR_OP_SEND\f[R],
\f[B]IBV_QP_ATTACH_COMP_CNTR_OP_RECV\f[R],
\f[B]IBV_QP_ATTACH_COMP_CNTR_OP_RDMA_READ\f[R],
\f[B]IBV_QP_ATTACH_COMP_CNTR_OP_RDMA_WRITE\f[R]) count completions
initiated by the local QP.
Remote operations
(\f[B]IBV_QP_ATTACH_COMP_CNTR_OP_REMOTE_RDMA_READ\f[R],
\f[B]IBV_QP_ATTACH_COMP_CNTR_OP_REMOTE_RDMA_WRITE\f[R]) count
completions of incoming RDMA operations initiated by the remote side.
Supported \f[I]op_mask\f[R] values may vary by device and can be queried
using \f[B]ibv_query_comp_cntr_caps\f[R](3); unsupported values will
result in an ENOTSUP error.
.PP
Multiple completion counters can be attached to the same QP, provided
their \f[I]op_mask\f[R] values do not overlap.
Each QP and operation type pair can be associated with at most one
completion counter.
Attempting to attach a counter with an \f[I]op_mask\f[R] that conflicts
with an already attached counter will fail.
.PP
There is no explicit detach operation.
A completion counter is implicitly detached when the QP it is attached
to is destroyed.
A completion counter cannot be destroyed while it is still attached to
any QP; the QP must be destroyed first.
.SH ARGUMENTS
.TP
\f[I]qp\f[R]
The queue pair to attach the completion counter to.
.TP
\f[I]comp_cntr\f[R]
The completion counter to attach, previously created with
\f[B]ibv_create_comp_cntr\f[R]().
.TP
\f[I]attr\f[R]
Attach attributes specifying which operation types update the counter.
.SS ibv_qp_attach_comp_cntr_attr
.IP
.EX
\f[B]enum\f[R] ibv_qp_attach_comp_cntr_op {
    IBV_QP_ATTACH_COMP_CNTR_OP_SEND                    = 1 << 0,
    IBV_QP_ATTACH_COMP_CNTR_OP_RECV                    = 1 << 1,
    IBV_QP_ATTACH_COMP_CNTR_OP_RDMA_READ               = 1 << 2,
    IBV_QP_ATTACH_COMP_CNTR_OP_REMOTE_RDMA_READ        = 1 << 3,
    IBV_QP_ATTACH_COMP_CNTR_OP_RDMA_WRITE              = 1 << 4,
    IBV_QP_ATTACH_COMP_CNTR_OP_REMOTE_RDMA_WRITE       = 1 << 5,
};

\f[B]struct\f[R] ibv_qp_attach_comp_cntr_attr {
    uint32_t comp_mask;
    uint32_t op_mask;
};
.EE
.TP
\f[I]comp_mask\f[R]
Bitmask specifying what fields in the structure are valid.
Used for extensibility, should be set to 0.
.TP
\f[I]op_mask\f[R]
Bitmask of \f[B]ibv_qp_attach_comp_cntr_op\f[R] values specifying which
operation types should update the counter.
.SH RETURN VALUE
\f[B]ibv_qp_attach_comp_cntr\f[R]() returns 0 on success, or the value
of errno on failure (which indicates the failure reason).
.SH ERRORS
.TP
EINVAL
Invalid argument(s) passed.
.TP
ENOTSUP
Requested operation is not supported on this device.
.TP
EBUSY
The \f[I]op_mask\f[R] overlaps with a completion counter already
attached to this QP.
.SH SEE ALSO
\f[B]ibv_create_comp_cntr\f[R](3),
\f[B]ibv_query_comp_cntr_caps\f[R](3), \f[B]ibv_create_qp\f[R](3)
.SH AUTHORS
Michael Margolin \c
.MT mrgolin@amazon.com
.ME \c