int ibv_detach_mcast(struct ibv_qp *qp, const union ibv_gid *gid,
                     uint16_t lid);

Description

ibv_detach_mcast() detaches a Queue Pair from a multicast group.

After the detachment completes, this QP won't get a copy of every multicast message addressed to the group specified by gid and received on the RDMA device port with which the QP is associated.
ibv_detach_mcast() only influence the local RDMA device. In order to stop receiving multicast messages to this RDMA device, a leave request from the multicast group must be sent to the Subnet Administrator (SA), so that the fabric's multicast routing is configured to deliver messages to the local port.

ibv_detach_mcast() must be called with the same attributes that ibv_attach_mcast() was called with.

Detaching a QP from a specific multicast group won't affect receiving messages from other multicast groups that this QP may be attached to.

Detaching a QP from a multicast group can occur in any QP state.

Parameters

Return Values

Examples

Attach a QP to a multicast group and detach it:

struct ibv_qp *qp; /* A pointer to a QP that was created before */
union ibv_gid mgid;
uint16_t mlid;
 
/* need to initialize the value of mgid and mlid according to value from the SA */
mgid.raw = {255,1,0,0,0,2,201,133,0,0,0,0,0,0,0,0};
mlid = 0xc001;
 
if (ibv_attach_mcast(qp, &mgid, mlid)) {
	fprintf(stderr, "Error, ibv_attach_mcast() failed\n");
	return -1;
}
 
if (ibv_detach_mcast(qp, &mgid, mlid)) {
	fprintf(stderr, "Error, ibv_detach_mcast() failed\n");
	return -1;
}

FAQs

How can I send leave request for a multicast group to the SA?

One can do this by using the library rdmacm.

By accident, I attached a QP to the same multicast group more than once, do I have to detach it more than once too?

No. The QP was attached only once to the multicast group and one should call ibv_detach_mcast() only once.

If I detach from a specific multicast group, is there any influence on other multicast groups that this QP may be attached to?

No. Detaching a QP from a specific multicast group doesn't have any influence on other multicast groups that this QP may be attached to.

Written by: Dotan Barak on March 29, 2013.on February 18, 2015.