drm_gem_handle_create_tail(9)

📦 version 7.3.1, in nixpkgs unstable

💖 drm_gem_handle_create_tail(9) 💖

okay bestie so we're in the Kernel API Manual today, and this one is literally a kernel-internals page — drm_gem_handle_create_tail(9). it's the internal handle-maker. the tail-end bestie. the one that does the messy part. let's get into it 🎀

✨ SYNOPSIS ✨

int drm_gem_handle_create_tail (struct drm_file *file_priv , struct
       drm_gem_object *obj , u32 *handlep );

that's the whole signature, no cap. takes three things, hands you back an int. 👑

🫶 ARGUMENTS 🫶

  • file_priv — the drm file-private structure you're registering the handle for. this is whose handle it becomes 💅
  • obj — the object getting registered. the actual star of the show ✨
  • handlep — a pointer where the newly created handle gets handed back to whoever called. it's giving "you get a handle, you get a handle" 🎁

🌸 DESCRIPTION 🌸

okay so listen. this function expects the drm_device.object_name_lock to already be held when you call it — you hold it, not her — and she will drop it before returning. like, she takes the lock from your hands and puts it away on her way out the door 🚪✨ and the whole reason is to dodge races when you're establishing new handles while importing an object from either an flink name or a dma-buf. race conditions are NOT the vibe, so we prevent them 🧚

🚨 and bestie, important: handles must be released again through drm_gem_handle_delete. not optional. no skipping. that's how it stays clean 💀

so when does that releasing happen? two ways, and both are the system doing it for you-ish:

  1. when userspace closes file_priv — then all attached handles get released 💖
  2. through the GEM_CLOSE ioctl, for individual handles 🎀

🌈 SEE ALSO 🌈

the whole friend group, fr fr. kernel file ./drivers/gpu/drm/drm_gem.c and then this absolutely iconic list:

like… that's the entire group chat and every single one of them is relevant. read them. iykyk 🦋

💜 that's the whole page bestie, go forth and make handles responsibly 💜

this iconic little page lives in ./drivers/gpu/drm, dated October 2026 — and drm_gem_handle_create_tail(9) will see you next time, mwah 💋🌸

📦 where this page comes from