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 May 11, 2020 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 heterogenous address space 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 __deprecated 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 space 68to another. 69.Pp 70.Fn copystr 71is deprecated and should be replaced with 72.Xr strlcpy 9 . 73It will be removed from 74.Fx 13 . 75.Pp 76The 77.Fn copyin 78and 79.Fn copyin_nofault 80functions copy 81.Fa len 82bytes of data from the user-space address 83.Fa uaddr 84to the kernel-space address 85.Fa kaddr . 86.Pp 87The 88.Fn copyout 89and 90.Fn copyout_nofault 91functions copy 92.Fa len 93bytes of data from the kernel-space address 94.Fa kaddr 95to the user-space address 96.Fa uaddr . 97.Pp 98The 99.Fn copyin_nofault 100and 101.Fn copyout_nofault 102functions require that the kernel-space and user-space data be 103accessible without incurring a page fault. 104The source and destination addresses must be physically mapped for 105read and write access, respectively, and neither the source nor 106destination addresses may be pageable. 107.Pp 108The 109.Fn copystr 110function copies a NUL-terminated string, at most 111.Fa len 112bytes long, from kernel-space address 113.Fa kfaddr 114to kernel-space address 115.Fa kdaddr . 116The number of bytes actually copied, including the terminating 117NUL, is returned in 118.Fa *done 119(if 120.Fa done 121is 122.No non- Ns Dv NULL ) . 123.Pp 124The 125.Fn copyinstr 126function copies a NUL-terminated string, at most 127.Fa len 128bytes long, from user-space address 129.Fa uaddr 130to kernel-space address 131.Fa kaddr . 132The number of bytes actually copied, including the terminating 133NUL, is returned in 134.Fa *done 135(if 136.Fa done 137is 138.No non- Ns Dv NULL ) . 139.Sh RETURN VALUES 140The 141.Nm 142functions return 0 on success. 143All but 144.Fn copystr 145return 146.Er EFAULT 147if a bad address is encountered. 148The 149.Fn copyin_nofault 150and 151.Fn copyout_nofault 152functions return 153.Er EFAULT 154if a page fault occurs. 155The 156.Fn copystr 157and 158.Fn copyinstr 159functions return 160.Er ENAMETOOLONG 161if the string is longer than 162.Fa len 163bytes. 164.Sh SEE ALSO 165.Xr fetch 9 , 166.Xr store 9 167