Differential D57663 Diff 180925 share/man/man9/copy.9

Changeset View

Standalone View

View Options

share/man/man9/copy.9

Show All 26 Lines

.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,

.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED

.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

.\" SUCH DAMAGE.

.\"

.Dd May 11, 2020

.Dd June 29, 2026

.Dt COPY 9

.Os

.Sh NAME

.Nm copy ,

.Nm copyin ,

.Nm copyin_nofault ,

.Nm copyinptr ,

.Nm copyinptr_nofault ,

.Nm copyout ,

.Nm copyout_nofault ,

.Nm copyoutptr ,

.Nm copyoutptr_nofault ,

.Nm copystr ,

.Nm copyinstr

.Nd heterogeneous address space copy functions

.Sh SYNOPSIS

.In sys/types.h

.In sys/systm.h

.Ft int

.Fn copyin "const void *uaddr" "void *kaddr" "size_t len"

.Ft int

.Fn copyin_nofault "const void *uaddr" "void *kaddr" "size_t len"

.Ft int

.Fn copyinptr "const void *uaddr" "void *kaddr" "size_t len"

.Ft int

.Fn copyinptr_nofault "const void *uaddr" "void *kaddr" "size_t len"

.Ft int

.Fn copyout "const void *kaddr" "void *uaddr" "size_t len"

.Ft int

.Fn copyout_nofault "const void *kaddr" "void *uaddr" "size_t len"

.Ft int

.Fn copyoutptr "const void *kaddr" "void *uaddr" "size_t len"

.Ft int

.Fn copyoutptr_nofault "const void *kaddr" "void *uaddr" "size_t len"

.Ft int __deprecated

.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done"

.Ft int

.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done"

.Sh DESCRIPTION

The

.Nm

functions are designed to copy contiguous data from one address space

Show All 10 Lines

.Fn copyin

and

.Fn copyin_nofault

functions copy

.Fa len

bytes of data from the user-space address

.Fa uaddr

to the kernel-space address

.Fa kaddr .

.Fa kaddr

without preserving the provenance of pointers in the copied object

.Pq see Xr memory_model 7 for further information .

The

.Fn copyinptr

and

.Fn copyinptr_nofault

markjUnsubmitted

Done

You might clarify here that you're talking about user pointers. It's always a bug to copy out kernel capabilities.

markj: You might clarify here that you're talking about user pointers. It's always a bug to copy out…

brooksAuthorUnsubmitted

Done

You might clarify here that you're talking about user pointers. It's always a bug to copy out kernel capabilities.

I've mentioned they are pointers to user-space, though the current implementations don't know the difference. @alfredo.mazzinghi_cl.cam.ac.uk does have patches to use the local-global mechanism to prevent kernel pointer from leaking to userspace so documenting this intent does seem like the right thing to do.

brooks: > You might clarify here that you're talking about user pointers. It's always a bug to copy out…

markjUnsubmitted

Done

function does the same,

- but preserve the provenance of copied pointers.

+ but preserves the provenance of copied pointers.

.Pp

The

.Fn copyout

markj:

functions do the same,

but preserves the provenance of copied pointers to user-space.

.Pp

The

.Fn copyout

and

.Fn copyout_nofault

functions copy

.Fa len

bytes of data from the kernel-space address

.Fa kaddr

to the user-space address

.Fa uaddr .

.Fa uaddr

without preserving the provenance of pointers in the copied object.

markjUnsubmitted

Done

.Fa uaddr

- without perservice pointer provenance.

+ without preserving pointer provenance.

The

.Fn copyoutptr

markj:

The

.Fn copyoutptr

and

.Fn copyoutptr_nofault

functions do the same,

but preserves the provenance of copied pointers to user-space.

.Pp

The

.Fn copyin_nofault

.Fn copyin_nofault ,

.Fn copyinptr_nofault ,

.Fn copyout_nofault ,

and

.Fn copyout_nofault

.Fn 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.

.Pp

The

.Fn copyinptr ,

.Fn copyinptr_nofault ,

.Fn copyoutptr ,

and

.Fn 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.

.Pp

The

.Fn copystr

function copies a NUL-terminated string, at most

.Fa len

bytes long, from kernel-space address

.Fa kfaddr

to kernel-space address

▲ Show 20 Lines • Show All 52 Lines • Show Last 20 Lines