STRUCT KMEM_CACHE_ARGS(9)

📦 version 7.3.1, in nixpkgs unstable

💅 struct kmem_cache_args(9) 💅

okay bestie, welcome to the Kernel API Manual — this page is all about struct kmem_cache_args, aka the less common arguments you can hand to kmem_cache_create(). it's giving "advanced settings panel" energy 🎀

✨ NAME ✨

struct kmem_cache_args — the less common arguments for kmem_cache_create() 🫶

🌸 SYNOPSIS 🌸

struct kmem_cache_args {
    unsigned int align;
    unsigned int useroffset;
    unsigned int usersize;
    unsigned int freeptr_offset;
    bool use_freeptr_offset;
    void (*ctor)(void *);
    unsigned int sheaf_capacity;
 };

🦋 Members 🦋

  • align — the required alignment for the objects ✨ 0 means no specific alignment is requested, ngl very chill of it.
  • useroffset — usercopy region offset 💖 0 is a totally valid offset, but only when usersize is non-0. iykyk.
  • usersize — usercopy region size 🎀 0 means no usercopy region is specified, periodt.
  • freeptr_offset — a custom offset for the free pointer in caches that have SLAB_TYPESAFE_BY_RCU or a ctor 🔥 so by default, SLAB_TYPESAFE_BY_RCU and ctor caches place the free pointer outside of the object. which… can make the object grow in size 😭 cache creators who have a reason to avoid that can specify a custom free pointer offset inside their own data structure, and that's where the free pointer gets placed. for caches with SLAB_TYPESAFE_BY_RCU, the caller must ensure that the free pointer does not overlay fields required to guard against object recycling (peep SLAB_TYPESAFE_BY_RCU for the deets 👀). for caches with ctor, the caller must ensure that the free pointer does not overlay fields initialized by the constructor. currently, only caches with SLAB_TYPESAFE_BY_RCU or ctor may specify freeptr_offset. using 0 as a value for freeptr_offset is valid. if freeptr_offset is specified, use_freeptr_offset must be set true. no cap.
  • use_freeptr_offset — whether a freeptr_offset is used 💅
  • ctor — a constructor for the objects 🌈 the constructor is invoked for each object in a newly allocated slab page. it is the cache user's responsibility to free an object in the same state as after calling the constructor, or to deal appropriately with any differences between a freshly constructed and a reallocated object. main character responsibility, fr fr. NULL means no constructor.
  • sheaf_capacity — enable sheaves of the given capacity for the cache 🌾 with a non-zero value, allocations from the cache go through caching arrays called sheaves. each cpu has a main sheaf that's always present, plus a spare sheaf that may be not present. when both become empty, there's an attempt to replace an empty sheaf with a full sheaf from the per-node barn. it's giving organizational queen energy 👑 when no full sheaf is available, and gfp flags allow blocking, a sheaf is allocated and filled from slab(s) using bulk allocation. otherwise the allocation falls back to the normal operation allocating a single object from a slab. analogically, when freeing and both percpu sheaves are full, the barn may replace it with an empty sheaf, unless it's over capacity. in that case a sheaf is bulk freed to slab pages. the sheaves do not enforce NUMA placement of objects, so allocations via kmem_cache_alloc_node with a node specified other than NUMA_NO_NODE will bypass them 💀 bulk allocation and free operations also try to use the cpu sheaves and barn, but fallback to using slab pages directly. when slub_debug is enabled for the cache, the sheaf_capacity argument is ignored 🙈 0 means no sheaves will be created.

💜 Description 💜

any uninitialized fields of the structure are interpreted as unused ✨ the exception is freeptr_offset where 0 is a valid value, so use_freeptr_offset must also be set to true in order to interpret the field as used. for useroffset, 0 is also valid, but only with non-0 usersize.

when NULL args is passed to kmem_cache_create, it is equivalent to all fields unused 🫶

🔍 SEE ALSO 🔍

kernel file ./include/linux/slab.h, plus all these icons: SLAB_HWCACHE_ALIGN(9), SLAB_TYPESAFE_BY_RCU(9), SLAB_ACCOUNT(9), SLAB_RECLAIM_ACCOUNT(9), kmem_cache_create_usercopy(9), kmem_cache_create(9), krealloc_node_align(9), kmem_cache_alloc(9), kmem_cache_charge(9), kmalloc(9), kmalloc_nolock(9), __alloc_objs(9), __alloc_flex(9), kmalloc_obj(9), kmalloc_objs(9), kmalloc_flex(9), kmalloc_array(9), krealloc_array(9), kcalloc(9), kzalloc(9), kvmalloc_node(9), kvrealloc_node_align(9), kmalloc_size_roundup(9) 🌟

💖 that's the whole page bestie, go forth and cache responsibly 💖

okay so this came from ./include/linux and it's dated October 2026 — if you're reading struct kmem_cache_args(9) way later, bestie you're iconic for keeping up 🧚✨

📦 where this page comes from