extract_iter_to_sg(9)

✨ extract_iter_to_sg(9) ✨

okay so bestie, this one lives in the Kernel API Manual and it's literally the glow-up your scatterlist has been waiting for 💅

🎀 NAME 🎀

extract_iter_to_sg — extract pages from an iterator and add them to an sglist. no cap, that's the whole vibe 🦋

🌸 SYNOPSIS 🌸

ssize_t extract_iter_to_sg (struct iov_iter *iter , size_t maxsize ,
       struct sg_table *sgtable , unsigned int sg_max , iov_iter_extraction_t
       extraction_flags );

💖 ARGUMENTS 💖

• iter — the iterator you're extracting from, the main character of this whole operation 👑
• maxsize — how much of the iterator to copy, like your portion control but for bytes 🍓
• sgtable — the scatterlist table that gets filled in, she's the canvas bestie 🎨
• sg_max — the maximum number of elements in sgtable that may be filled, aka the hard limit, respect it 🙈
• extraction_flags — flags to qualify the request, the little seasoning on top ✨

🦋 DESCRIPTION 🦋

So what it does: it extracts the page fragments from the given amount of the source iterator and adds them to a scatterlist that refers to all of those bits — up to a maximum addition of sg_max elements. slay 💫

Now here's the tea on pinning, and this part matters:

• The pages referred to by UBUF- and IOVEC-type iterators are extracted and pinned 🔥
• BVEC-, KVEC-, FOLIOQ- and XARRAY-type are extracted but aren't pinned 🫶
• DISCARD-type is not supported — she's simply not invited to the party 💀

No end mark is placed on the scatterlist; that's left to the caller. yes, that's your job bestie, don't forget 😭

extraction_flags can have ITER_ALLOW_P2PDMA set to request peer-to-peer DMA be allowed on the pages extracted. fancy, iconic, love that for you 🌈

If it's successful, sgtable->nents is updated to include the number of elements added, and the number of bytes added is returned. meanwhile sgtable->orig_nents is left unaltered — untouched, unbothered, living her life 💜

Also important: the iov_iter_extract_mode function should be used to query how cleanup should be performed. like, please check before you yolo the teardown 🧚

---

⭐ SEE ALSO ⭐

Kernel file ./lib/scatterlist.c and honestly the whole scatterlist friend group:

• sg_nents(9), sg_nents_for_len(9), sg_nents_for_dma(9), sg_last(9)
• sg_init_table(9), sg_init_one(9)
• __sg_free_table(9), sg_free_append_table(9), sg_free_table(9)
• __sg_alloc_table(9), sg_alloc_table(9), sg_alloc_append_table_from_pages(9), sg_alloc_table_from_pages_segment(9)
• sgl_alloc_order(9), sgl_alloc(9), sgl_free_n_order(9), sgl_free_order(9), sgl_free(9)
• sg_miter_start(9), sg_miter_skip(9), sg_miter_next(9), sg_miter_stop(9)
• sg_copy_buffer(9), sg_copy_from_buffer(9), sg_copy_to_buffer(9), sg_pcopy_from_buffer(9), sg_pcopy_to_buffer(9), sg_zero_buffer(9)

---

that's the whole page, ily, go pin some pages responsibly 💖 sourced from ./lib, dated October 2026, and filed under extract_iter_to_sg(9) — periodt ✨🎀