xz_dec_init(9)

💅 xz_dec_init(9) — like, the Kernel API Manual, bestie ✨

okay so real talk, this page is from the Kernel API Manual and it's literally all about xz_dec_init(9) 🎀 — the little function that gets your XZ decoder state all set up and ready to slay. Think of it as getting your decoder dressed and out the door 💖

---

🌸 NAME 🌸

xz_dec_init — allocate and initialize a XZ decoder state 🦋

---

✨ SYNOPSIS ✨

struct xz_dec * xz_dec_init (enum xz_mode mode , uint32_t dict_max );

like, that's the whole signature. no cap. 👑

---

🫶 ARGUMENTS 🫶

• mode — the operation mode 🎚️ (yes there are modes, keep reading bestie)
• dict_max — the maximum size of the LZMA2 dictionary (aka the history buffer) for multi-call decoding 💾

⚠️ heads up: dict_max is ignored in single-call mode (mode == XZ_SINGLE). literally doesn't even look at it 🙈

okay so about the dictionary size — an LZMA2 dictionary is always either 2^n bytes or 2^n + 2^(n-1) bytes (that second flavor is less common in practice, ngl), so any other value for dict_max is just... not it. doesn't make sense, don't do it 💀

in the kernel, 64 KiB, 128 KiB, 256 KiB, 512 KiB, and 1 MiB are probably the only reasonable values 💅 — with one exception: for kernel and initramfs images, a bigger dictionary can be totally fine and actually useful, so go off 👑

---

🔥 DESCRIPTION 🔥

okay so this is the part where it gets good. there are three whole vibes here and you need to know which one you're in:

Single-call mode (XZ_SINGLE) ⭐

xz_dec_run decodes the whole stream at once. one and done, periodt. the caller must provide enough output space, otherwise the decoding will straight-up fail 😭. here's the cute part: the output space is used as the dictionary buffer, which is exactly why there's no need to allocate the dictionary as part of the decoder's internal state. it's giving efficiency 💅

and because the output buffer is the workspace, streams encoded using a big dictionary are not a problem in single-call mode 🦋 it's enough that the output buffer is big enough to hold the actual uncompressed data — it can totally be smaller than the dictionary size stored in the stream headers. iconic, frankly.

Multi-call mode with preallocated dictionary (XZ_PREALLOC) 🎀

here, dict_max bytes of memory is preallocated for the LZMA2 dictionary. this way there's no risk that xz_dec_run could run out of memory, since xz_dec_run will never allocate any memory 🔒

but — and this is the catch, bestie — if the preallocated dictionary is too small for decoding the given input stream, xz_dec_run will return XZ_MEMLIMIT_ERROR 💀. so it's super important to know what kind of data will be decoded, or you'll be out here allocating an excessive amount of memory for the dictionary. no wasteful queen behavior 🙈

Multi-call mode with dynamically allocated dictionary (XZ_DYNALLOC) 🌈

dict_max specifies the maximum allowed dictionary size that xz_dec_run may allocate once it has parsed the dictionary size from the stream headers 📜. this way excessive allocations can be avoided while still limiting the maximum memory usage to a sane value — which prevents running the system out of memory when decompressing streams from untrusted sources 🔥. like, security and hygiene, we love to see it.

the return value, bestie 🫶

on success, xz_dec_init returns a pointer to struct xz_dec, which is ready to be used with xz_dec_run. and if memory allocation fails? it returns NULL. that's it. that's the whole mood 😭

---

💜 SEE ALSO 💜

Kernel file ./include/linux/xz.h

• enum xz_mode(9)
• enum xz_ret(9)
• struct xz_buf(9)
• xz_dec_run(9)
• xz_dec_reset(9)
• xz_dec_end(9)
• MicroLZMA decompressor(9)
• xz_dec_microlzma_alloc(9)
• xz_dec_microlzma_reset(9)
• xz_dec_microlzma_run(9)
• xz_dec_microlzma_end(9)

---

✨ ok that's the whole page, go decode something iconic ✨

this lil manual page lives in ./include/linux, dated October 2026, and it's filed under xz_dec_init(9) — catch you in the next one bestie 💖🎀🦋👑