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

# ibv\_poll\_cq(3)

poll a completion queue (CQ)

## NAME

ibv\_poll\_cq - poll a completion queue (CQ)

## SYNOPSIS

```
#include <infiniband/verbs.h>

int ibv_poll_cq(struct ibv_cq *cq, int num_entries,
                struct ibv_wc *wc);
```

## DESCRIPTION

**ibv\_poll\_cq()** polls the CQ *cq* for work completions and returns the first *num\_entries* (or all available completions if the CQ contains fewer than this number) in the array *wc.* The argument *wc* is a pointer to an array of ibv\_wc structs, as defined in \<infiniband/verbs.h\>.

```
struct ibv_wc {
uint64_t                wr_id;          /* ID of the completed Work Request (WR) */
enum ibv_wc_status      status;         /* Status of the operation */
enum ibv_wc_opcode      opcode;         /* Operation type specified in the completed WR */
uint32_t                vendor_err;     /* Vendor error syndrome */
uint32_t                byte_len;       /* Number of bytes transferred */
union {
__be32                  imm_data;         /* Immediate data (in network byte order) */
uint32_t                invalidated_rkey; /* Local RKey that was invalidated */
};
uint32_t                qp_num;         /* Local QP number of completed WR */
uint32_t                src_qp;         /* Source QP number (remote QP number) of completed WR (valid only for UD QPs) */
unsigned int            wc_flags;       /* Flags of the completed WR */
uint16_t                pkey_index;     /* P_Key index (valid only for GSI QPs) */
uint16_t                slid;           /* Source LID */
uint8_t                 sl;             /* Service Level */
uint8_t                 dlid_path_bits; /* DLID path bits (not applicable for multicast messages) */
};

```

The attribute wc\_flags describes the properties of the work completion.  It is either 0 or the bitwise OR of one or more of the following flags:

- **IBV\_WC\_GRH GRH is present (valid only for UD QPs)**

  - **IBV\_WC\_WITH\_IMM Immediate data value is valid**

  - **IBV\_WC\_WITH\_INV Invalidated RKey data value is valid (cannot be combined with IBV\_WC\_WITH\_IMM)**

  - **IBV\_WC\_IP\_CSUM\_OK TCP/UDP checksum over IPv4 and IPv4 header checksum are**

  verified. Valid only when **device\_cap\_flags** in device\_attr indicates current QP is supported by checksum offload.

Not all *wc* attributes are always valid. If the completion status is other than **IBV\_WC\_SUCCESS,** only the following attributes are valid: wr\_id, status, qp\_num, and vendor\_err.

## RETURN VALUE

On success,  **ibv\_poll\_cq()** returns a non-negative value equal to the number of completions found.  On failure, a negative value is returned.

## NOTES

Each polled completion is removed from the CQ and cannot be returned to it.

The user should consume work completions at a rate that prevents CQ overrun from occurrence.  In case of a CQ overrun, the async event **IBV\_EVENT\_CQ\_ERR** will be triggered, and the CQ cannot be used.

IBV\_WC\_DRIVER1 will be reported as a response to IBV\_WR\_DRIVER1 opcode; IBV\_WC\_DRIVER2/IBV\_WC\_DRIVER3 will be reported on specific driver operations.

## SEE ALSO

[**ibv\_post\_send**(3)](/ibv_post_send/3.md), [**ibv\_post\_recv**(3)](/ibv_post_recv/3.md)

## AUTHORS

- Dotan Barak \<dotanba@gmail.com\>