refcount_sub_and_test(9)

📦 version 7.3.1, in nixpkgs unstable

💅 refcount_sub_and_test(9) — from the Kernel API Manual, bestie

okay so this is refcount_sub_and_test(9) and honestly it's giving "math but make it kernel" 🧮✨

✨ SYNOPSIS ✨

bool refcount_sub_and_test (int i , refcount_t *r );

like, you hand it a number and a refcount, and it hands back a bool. slay.

🎀 ARGUMENTS 🎀

  • i — the amount you wanna subtract from the refcount. how much we're taking off. 💖
  • r — the refcount itself. the main character. the one we're subtracting from. 👑

🌸 DESCRIPTION 🌸

so this one is similar to atomic_dec_and_test, but bestie, it has OPINIONS. like, it will not just quietly do the thing. instead:

  • it will WARN on underflow 😭
  • it will return false on underflow
  • it will ultimately leak on underflow (yes, leak. fr fr. that's the vibe. 💀)
  • and it will fail to decrement when it's saturated at REFCOUNT_SATURATED

so like... it's the cautious one. it's not gonna let you vibe your way into an underflow without saying something about it. 🚨

it also handles the memory ordering for you, which is honestly so thoughtful:

  • it provides release memory ordering, so prior loads and stores are done before — like, everything that came before is wrapped up and put away first 🎁
  • and on success it provides acquire ordering, so free must come after. no cutting in line, periodt. ✋
⚠️ but here's the thing: use of this function is not recommended for the normal reference counting use case — you know, the super common one where references are taken and released one at a time. 🫶

in those cases you should use refcount_dec, or one of its variants, to decrement a reference count instead. like, that's the recommended route. refcount_sub_and_test is not the moment for your normal one-at-a-time situation. iykyk 💅

🌈 RETURN 🌈

  • true — if the resulting refcount is 0 🎉
  • false — otherwise 😌

🦋 SEE ALSO 🦋

Kernel file ./include/linux/refcount.h — go read it, it's iconic 👑

plus all these besties:

that's the whole page, bestie! 💜 straight from ./include/linux, dated October 2026, and yeah — it's refcount_sub_and_test(9), signed, sealed, delivered. mwah 🫶✨🎀

📦 where this page comes from