COPY(9)

💅 COPY(9) — the kernel developer's manual, bestie edition 🎀

okay so this is COPY(9) from the Kernel Developer's Manual, and it's literally the glow-up guide for moving bytes between address spaces. buckle up 🦋

---

✨ NAME ✨

copy, copyin, copyin_nofault, copyout, copyout_nofault, copystr, copyinstr — the heterogeneous address space copy functions 💫

(heterogeneous address space = fancy speak for "the two addresses live in different worlds," iykyk)

---

🌸 SYNOPSIS 🌸

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

int
copyin(const void *uaddr, void *kaddr, size_t len);

int
copyin_nofault(const void *uaddr, void *kaddr, size_t len);

int
copyout(const void *kaddr, void *uaddr, size_t len);

int
copyout_nofault(const void *kaddr, void *uaddr, size_t len);

int __deprecated
copystr(const void *kfaddr, void *kdaddr, size_t len, size_t *done);

int
copyinstr(const void *uaddr, void *kaddr, size_t len, size_t *done);

not me pointing out that __deprecated sitting right there in the signature like a warning label 🫶

---

👑 DESCRIPTION 👑

the copy functions are designed to copy contiguous data from one address space to another. that's the whole vibe. contiguous bytes, two worlds, one function call ✨

💀 big heads-up: copystr() is deprecated and should be replaced with strlcpy(9). it will be removed from FreeBSD 13. so like… start migrating, bestie. fr fr.

copyin() and copyin_nofault() copy len bytes of data from the user-space address uaddr to the kernel-space address kaddr. userland ➡️ kernel, slay.

copyout() and copyout_nofault() copy len bytes of data from the kernel-space address kaddr to the user-space address uaddr. kernel ➡️ userland, also slay.

copyin_nofault() and copyout_nofault() require that the kernel-space and user-space data be accessible without incurring a page fault. like, no surprises allowed, periodt. the source and destination addresses must be physically mapped for read and write access, respectively, and neither the source nor destination addresses may be pageable. if any of that isn't true… that's not it. 🙈

copystr() copies a NUL-terminated string, at most len bytes long, from kernel-space address kfaddr to kernel-space address kdaddr. the number of bytes actually copied — including the terminating NUL — is returned in *done (if done is non-NULL). 🍓

copyinstr() copies a NUL-terminated string, at most len bytes long, from user-space address uaddr to kernel-space address kaddr. the number of bytes actually copied — including the terminating NUL — is returned in *done (if done is non-NULL). yes, same deal, different address space, iconic behavior 💅

---

⭐ RETURN VALUES ⭐

• the copy functions return 0 on success. we love a clean zero 🥰
• all of them except copystr() return EFAULT if a bad address is encountered. bad address = vibe check failed.
• copyin_nofault() and copyout_nofault() return EFAULT if a page fault occurs. (remember: those two literally can't be doing page faults, so this is the "you were warned" error 💀)
• copystr() and copyinstr() return ENAMETOOLONG if the string is longer than len bytes. too long, too much, we're not doing that 🎀

---

🌈 SEE ALSO 🌈

• fetch(9)
• store(9)

go read those too, bestie, you'll be obsessed 💜

---

and that's the page!! no cap, you now know COPY(9) better than most. this little gem came to you from the Debian edition, dated May 11, 2020 — so when you cite it in your commit message, cite it with pride 🧚✨ 🫶