FETCH(9)

💖 FETCH(9) — the kernel dev manual, bestie edition 💖

okay so this is FETCH(9) from the Kernel Developer's Manual — like, the whole "fetch data from user-space" situation. grab a strawberry drink 🍓 and let's get into it.

---

✨ NAME ✨

fetch, fubyte, fuword, fuword16, fuword32, fuword64, fueword, fueword32, fueword64 — fetch data from user-space 💅

---

🎀 SYNOPSIS 🎀

first things first, you gotta include these:

#include <sys/types.h>
#include <sys/systm.h>

and then the whole squad of functions, literally all of them, no cap:

int
fubyte(volatile const void *base);

long
fuword(volatile const void *base);

int
fuword16(volatile const void *base);

int32_t
fuword32(volatile const void *base);

int64_t
fuword64(volatile const void *base);

int
fueword(volatile const void *base, long *val);

int
fueword32(volatile const void *base, int32_t *val);

int
fueword64(volatile const void *base, int64_t *val);

---

🦋 DESCRIPTION 🦋

so the fetch functions are designed to copy small amounts of data from user-space of the current process. like, little sips of data, not the whole drink. 🧚

here's the tea on alignment: if the user address is naturally aligned, then the operation will be performed atomically. but if it's not aligned? it may fail or be performed non-atomically, depending on the platform. so like, platform-dependent vibes, bestie. ⚠️

the fetch routines provide the following functionality:

• fubyte() — fetches a byte of data from the user-space address base. the byte read is zero-extended into the results variable. cute and tiny. 🎀
• fuword() — fetches a word of data (long) from the user-space address base.
• fuword16() — fetches 16 bits of data from the user-space address base. the half-word read is zero-extended into the results variable.
• fuword32() — fetches 32 bits of data from the user-space address base.
• fuword64() — fetches 64 bits of data from the user-space address base.
• fueword() — fetches a word of data (long) from the user-space address base and stores the result in the variable pointed by val. it's giving "put it in the group chat" energy 💅
• fueword32() — fetches 32 bits of data from the user-space address base and stores the result in the variable pointed by val.
• fueword64() — fetches 64 bits of data from the user-space address base and stores the result in the variable pointed by val.

💀 okay so important, lowkey a tragedy: the callers of fuword(), fuword32() and fuword64() functions cannot distinguish between -1 read from userspace and function failure. like, same value, two totally different meanings. iconic but also a nightmare, fr fr.

---

🌸 RETURN VALUES 🌸

the fubyte(), fuword(), fuword16(), fuword32(), and fuword64() functions return the data fetched or -1 on failure. slay when it works, -1 when it doesn't. 😭

the fueword(), fueword32() and fueword64() functions return 0 on success and -1 on failure. clean, simple, main character energy. 👑

---

🌈 SEE ALSO 🌈

• copy(9)
• store(9)

like the other half of the friend group, iykyk 🫶

---

and that's the whole page, bestie! this one's from Debian, dated July 22, 2021 — shoutout to the FETCH(9) girlies, periodt. 💜🦋✨