1.\" $NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $ 2.\" 3.\" Copyright (c) 1996 Jason R. Thorpe. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed by Kenneth Stailey. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed for the NetBSD Project 19.\" by Jason R. Thorpe. 20.\" 4. The name of the author may not be used to endorse or promote products 21.\" derived from this software without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 24.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 25.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 26.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 27.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 28.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 29.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 30.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 31.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" $FreeBSD$ 36.\" 37.Dd June 15, 2017 38.Dt COPY 9 39.Os 40.Sh NAME 41.Nm copy , 42.Nm copyin , 43.Nm copyin_nofault , 44.Nm copyout , 45.Nm copyout_nofault , 46.Nm copystr , 47.Nm copyinstr 48.Nd kernel copy functions 49.Sh SYNOPSIS 50.In sys/types.h 51.In sys/systm.h 52.Ft int 53.Fn copyin "const void *uaddr" "void *kaddr" "size_t len" 54.Ft int 55.Fn copyin_nofault "const void *uaddr" "void *kaddr" "size_t len" 56.Ft int 57.Fn copyout "const void *kaddr" "void *uaddr" "size_t len" 58.Ft int 59.Fn copyout_nofault "const void *kaddr" "void *uaddr" "size_t len" 60.Ft int 61.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done" 62.Ft int 63.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done" 64.Sh DESCRIPTION 65The 66.Nm 67functions are designed to copy contiguous data from one address 68to another. 69All but 70.Fn copystr 71copy data from user-space to kernel-space or vice-versa. 72.Pp 73The 74.Fn copyin 75and 76.Fn copyin_nofault 77functions copy 78.Fa len 79bytes of data from the user-space address 80.Fa uaddr 81to the kernel-space address 82.Fa kaddr . 83.Pp 84The 85.Fn copyout 86and 87.Fn copyout_nofault 88functions copy 89.Fa len 90bytes of data from the kernel-space address 91.Fa kaddr 92to the user-space address 93.Fa uaddr . 94.Pp 95The 96.Fn copyin_nofault 97and 98.Fn copyout_nofault 99functions require that the kernel-space and user-space data be 100accessible without incurring a page fault. 101The source and destination addresses must be physically mapped for 102read and write access, respectively, and neither the source nor 103destination addresses may be pageable. 104.Pp 105The 106.Fn copystr 107function copies a NUL-terminated string, at most 108.Fa len 109bytes long, from kernel-space address 110.Fa kfaddr 111to kernel-space address 112.Fa kdaddr . 113The number of bytes actually copied, including the terminating 114NUL, is returned in 115.Fa *done 116(if 117.Fa done 118is 119.No non- Ns Dv NULL ) . 120.Pp 121The 122.Fn copyinstr 123function copies a NUL-terminated string, at most 124.Fa len 125bytes long, from user-space address 126.Fa uaddr 127to kernel-space address 128.Fa kaddr . 129The number of bytes actually copied, including the terminating 130NUL, is returned in 131.Fa *done 132(if 133.Fa done 134is 135.No non- Ns Dv NULL ) . 136.Sh RETURN VALUES 137The 138.Nm 139functions return 0 on success. 140All but 141.Fn copystr 142return 143.Er EFAULT 144if a bad address is encountered. 145The 146.Fn copyin_nofault 147and 148.Fn copyout_nofault 149functions return 150.Er EFAULT 151if a page fault occurs. 152The 153.Fn copystr 154and 155.Fn copyinstr 156functions return 157.Er ENAMETOOLONG 158if the string is longer than 159.Fa len 160bytes. 161.Sh SEE ALSO 162.Xr fetch 9 , 163.Xr store 9 164