ib_sa_join_multicast(9)

🦋 ib_sa_join_multicast(9) — the Kernel API Manual page, bestie edition 🦋

Okay so picture this: you're in the Kernel API Manual, section 9, and you've just stumbled onto ib_sa_join_multicast. Don't panic 💅 — this is genuinely one of the more chill ones, and I'm gonna walk you through it like we're texting at 2am.

---

✨ SYNOPSIS ✨

struct ib_sa_multicast * ib_sa_join_multicast (struct ib_sa_client
*client , struct ib_device *device , u32 port_num , struct
ib_sa_mcmember_rec *rec , ib_sa_comp_mask comp_mask , gfp_t gfp_mask ,
int (*callback)(int status, struct ib_sa_multicast *multicast) , void
*context );

That's a whole lot of parameters, I know 😭 but lowkey every single one of them has a job. Iconic, honestly.

---

🌸 ARGUMENTS 🌸

• client — the SA client. Like, who is doing the asking, y'know?
• device — the device that's associated with the multicast group 🫶
• port_num — which port on that specified device you want tied to the multicast group.
• rec — the SA multicast member record, aka the thing holding all the group attributes.
• comp_mask — the component mask, and no cap this is important: it tells you which of the group attributes in rec are actually valid. vibe check for the record ✨
• gfp_mask — the GFP mask used for memory allocations. memory stuff, moving on 💀
• callback — your user callback, invoked once the join operation completes. She reports back, periodt.
• context — a user specified context that gets stored right there with the ib_sa_multicast structure. your little souvenir 🎀

---

🔥 DESCRIPTION 🔥

So this call kicks off a multicast join request with the SA for the specified multicast group. That's the whole main character move.

If the join operation is started successfully, it hands you back an ib_sa_multicast structure, and that's your little tracker for the multicast operation. The way that this matters: users must free this structure by calling ib_free_multicast, even if the join operation later fails. Reread that. Yes, even if. The callback status being non-zero does not get you out of your cleanup duties, bestie 🙈

If the join operation fails, status will be non-zero. Free the struct anyway. I said what I said 💅

When it fails, status comes back non-zero, and here are the failures that are possible:

• -ETIMEDOUT — the request timed out ⏰
• -EIO — an error occurred sending the query 😭
• -EINVAL — the MCMemberRecord values differed from the existing group's. mismatch energy, we hate to see it
• -ENETRESET — this one means a fatal error has occurred on the multicast group, and the user must rejoin the group to continue using it. not a drill, actual requirement 🚨

---

⭐ SEE ALSO ⭐

• Kernel file ./include/rdma/ib_sa.h struct sa_path_rec_roce(9)
• ib_sa_register_client(9)
• ib_sa_unregister_client(9)
• ib_init_ah_from_mcmember(9)
• ib_sa_pack_path(9)
• ib_sa_pack_service(9)
• ib_sa_unpack_service(9)
• ib_sa_unpack_path(9)

Go read them, they're all baddies in their own right 👑

---

And that's the page, fr fr 💖 It lives in ./include/rdma, dated October 2026 — so go forth, join that multicast group, free that struct, and slay ✨🦋🌸