DRM_IOCTL_PR...FD_TO_HANDLE(9)

💖 NAME 💖

DRM_IOCTL_PRIME_FD_TO_HANDLE — convert a DMA-BUF FD to a GEM handle, bestie 💅

Okay so this is the DRM_IOCTL_PR...FD_TO_HANDLE(9) page from the Kernel API Manual — and it's literally the import-side glow-up: DMA-BUF FD in, GEM handle out. No cap. ✨

✨ SYNOPSIS ✨

DRM_IOCTL_PRIME_FD_TO_HANDLE

🎀 DESCRIPTION 🎀

So user-space sets drm_prime_handle.fd with a DMA-BUF file descriptor to import 🫶, and gets back a GEM handle in drm_prime_handle.handle. And drm_prime_handle.flags? Unused. Iconic but unused. 💀

Now here's the tea: if an existing GEM handle refers to the memory object backing the DMA-BUF, that GEM handle is returned. So user-space which needs to handle arbitrary DMA-BUFs must have a user-space lookup data structure to manually reference-count duplicated GEM handles. For more information see DRM_IOCTL_GEM_CLOSE — she explains the close side. 💅

The import can fail for any driver-specific reason, e.g. because import is only supported for DMA-BUFs allocated on this DRM device. So yes, driver-specific chaos is possible, no universal slay. 😭

Support for importing DMA-BUFs is advertised via DRM_PRIME_CAP_IMPORT ✨.

🌈 SEE ALSO 🌈

Every single ref from the original is here — no skipping, bestie:

• Kernel file: ./tools/perf/trace/beauty/include/uapi/drm/drm.h
• struct drm_gem_close(9)
• struct drm_gem_flink(9)
• struct drm_gem_open(9)
• struct drm_gem_change_handle(9)
• DRM_CAP_DUMB_BUFFER(9)
• DRM_CAP_VBLANK_HIGH_CRTC(9)
• DRM_CAP_DUMB_PREFERRED_DEPTH(9)
• DRM_CAP_DUMB_PREFER_SHADOW(9)
• DRM_CAP_PRIME(9)
• DRM_PRIME_CAP_IMPORT(9)
• DRM_PRIME_CAP_EXPORT(9)
• DRM_CAP_TIMESTAMP_MONOTONIC(9)
• DRM_CAP_ASYNC_PAGE_FLIP(9)
• DRM_CAP_CURSOR_WIDTH(9)
• DRM_CAP_CURSOR_HEIGHT(9)
• DRM_CAP_ADDFB2_MODIFIERS(9)
• DRM_CAP_PAGE_FLIP_TARGET(9)
• DRM_CAP_CRTC_IN_VBLANK_EVENT(9)
• DRM_CAP_SYNCOBJ(9)
• DRM_CAP_SYNCOBJ_TIMELINE(9)
• DRM_CAP_ATOMIC_ASYNC_PAGE_FLIP(9)
• DRM_CLIENT_CAP_STEREO_3D(9)
• DRM_CLIENT_CAP_UNIVERSAL_PLANES(9)
• DRM_CLIENT_CAP_ATOMIC(9)
• DRM_CLIENT_CAP_ASPECT_RATIO(9)
• DRM_CLIENT_CAP_WRITEBACK_CONNECTORS(9)
• DRM_CLIENT_CAP_CURSOR_PLANE_HOTSPOT(9)
• DRM_CLIENT_CAP_PLANE_COLOR_PIPELINE(9)
• struct drm_syncobj_eventfd(9)
• DRM_IOCTL_GEM_CLOSE(9)
• DRM_IOCTL_PRIME_HANDLE_TO_FD(9)
• DRM_IOCTL_MODE_RMFB(9)
• DRM_IOCTL_MODE_CREATE_DUMB(9)
• DRM_IOCTL_MODE_GETFB2(9)
• DRM_IOCTL_SYNCOBJ_EVENTFD(9)
• DRM_IOCTL_MODE_CLOSEFB(9)
• DRM_IOCTL_SET_CLIENT_NAME(9)
• DRM_IOCTL_GEM_CHANGE_HANDLE(9)
• struct drm_event(9)
• DRM_EVENT_VBLANK(9)
• DRM_EVENT_FLIP_COMPLETE(9)
• DRM_EVENT_CRTC_SEQUENCE(9)

Cute sign-off tea: source/version ./tools/perf/trace/beauty/incl..., date October 2026, page DRM_IOCTL_PR...FD_TO_HANDLE(9). Bye bestie! 🫶💖