NAME
copy, copyin, copyin_nofault, copyinptr, copyinptr_nofault, copyout, copyout_nofault, copyoutptr, copyoutptr_nofault, copystr, copyinstr – heterogeneous address space copy functions
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
copyinptr(const void *uaddr, void *kaddr, size_t len);
int
copyinptr_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
copyoutptr(const void *kaddr, void *uaddr, size_t len);
int
copyoutptr_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);
DESCRIPTION
The copy functions are designed to copy contiguous data from one address space to another.
copystr() is deprecated and should be replaced with strlcpy(3), which has a kernel-to-kernel version. It will be removed from FreeBSD 16.
The copyin() and copyin_nofault() functions copy len bytes of data from the user-space address uaddr to the kernel-space address kaddr without preserving the provenance of pointers in the copied object (see memory_model(7) for further information). The copyinptr() and copyinptr_nofault() functions do the same, but preserves the provenance of copied pointers to user-space.
The copyout() and copyout_nofault() functions copy len bytes of data from the kernel-space address kaddr to the user-space address uaddr without preserving the provenance of pointers in the copied object. The copyoutptr() and copyoutptr_nofault() functions do the same, but preserves the provenance of copied pointers to user-space.
The copyin_nofault(), copyinptr_nofault(), copyout_nofault(), and copyoutptr_nofault() functions require that the kernel-space and user-space data be accessible without incurring a page fault. 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.
The copyinptr(), copyinptr_nofault(), copyoutptr(), and copyoutptr_nofault() functions must be used when copying data which may contain pointers, but they should only be used when necessary to limit the number of code paths that could leak pointers between address spaces.
The copystr() function 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).
The copyinstr() function 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).
RETURN VALUES
The copy functions return 0 on success. All but copystr() return EFAULT if a bad address is encountered. The copyin_nofault() and copyout_nofault() functions return EFAULT if a page fault occurs. The copystr() and copyinstr() functions return ENAMETOOLONG if the string is longer than len bytes.