xa_reserve(9)

💖 xa_reserve (9) — Kernel API Manual 💖

okay so bestie, welcome to the XArray corner of the kernel, and let me tell you, this one is such a helpful little function. no cap. it's from the Kernel API Manual and it's about to be your new fave 🫶

---

✨ NAME ✨

xa_reserve — Reserve this index in the XArray. literally just claiming your spot 💅

---

🌸 SYNOPSIS 🌸

int xa_reserve (struct xarray *xa , unsigned long index , gfp_t gfp );

---

🎀 ARGUMENTS 🎀

• xa — the XArray. your array, your main character 🌈
• index — index into array. the exact slot we're talking about 💫
• gfp — memory allocation flags. the vibe settings for how we're allowed to grab memory 🍓

---

🦋 DESCRIPTION 🦋

so here's the tea: this function ensures there is somewhere to store an entry at index in the array. like, it makes sure the seat is saved. 🪑

if there is already something stored at index, this function does nothing. no touchy, no drama. 🙈

but if there was nothing there, the entry gets marked as reserved. and here's the key detail bestie — loading from a reserved entry returns a NULL pointer. so it looks empty, but it's reserved empty. iykyk. ⭐

okay important one: if you do not use the entry that you have reserved, call xa_release or xa_erase to free any unnecessary memory. don't just leave it sitting there holding memory hostage, that's not the vibe 😭

---

🧚 CONTEXT 🧚

any context. it takes and releases the xa_lock. it may sleep if the gfp flags permit. so like, it's flexible, but respect the flags, bestie 💜

---

💀 RETURN 💀

• 0 — the reservation succeeded. slay ✨
• -ENOMEM — it failed. out of memory, it happens 😔

---

👑 SEE ALSO 👑

kernel file ./include/linux/xarray.h — that's where the whole squad lives 🔥

• xa_mk_value(9), xa_to_value(9), xa_is_value(9), xa_tag_pointer(9), xa_untag_pointer(9), xa_pointer_tag(9), xa_is_zero(9), xa_is_err(9), xa_err(9), struct xa_limit(9), struct xarray(9), DEFINE_XARRAY_FLAGS(9), DEFINE_XARRAY(9), DEFINE_XARRAY_ALLOC(9), DEFINE_XARRAY_ALLOC1(9)
• xa_init_flags(9), xa_init(9), xa_empty(9), xa_marked(9), xa_for_each_range(9), xa_for_each_start(9), xa_for_each(9), xa_for_each_marked(9)
• xa_store_bh(9), xa_store_irq(9), xa_erase_bh(9), xa_erase_irq(9), xa_cmpxchg(9), xa_cmpxchg_bh(9), xa_cmpxchg_irq(9), xa_insert(9), xa_insert_bh(9), xa_insert_irq(9)
• xa_alloc(9), xa_alloc_bh(9), xa_alloc_irq(9), xa_alloc_cyclic(9), xa_alloc_cyclic_bh(9), xa_alloc_cyclic_irq(9)
• xa_reserve_bh(9), xa_reserve_irq(9), xa_release(9), xa_is_sibling(9), xa_is_retry(9), xa_is_advanced(9), xa_update_node_t(9)
• XA_STATE(9), XA_STATE_ORDER(9), xas_error(9), xas_set_err(9), xas_invalid(9), xas_valid(9), xas_is_node(9), xas_reset(9), xas_retry(9), xas_reload(9), xas_set(9), xas_advance(9), xas_set_order(9), xas_set_update(9)
• xas_next_entry(9), xas_next_marked(9), xas_for_each(9), xas_for_each_marked(9), xas_for_each_conflict(9), xas_prev(9), xas_next(9)

---

and that's the whole page, bestie!! 🌈 this iconic lil' doc came out of ./include/linux and it's dated October 2026 — so like, future-us already read it and approved. periodt. 💅✨🎀💖