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.Dd May 11, 2020 36.Dt COPY 9 37.Os 38.Sh NAME 39.Nm copy , 40.Nm copyin , 41.Nm copyin_nofault , 42.Nm copyout , 43.Nm copyout_nofault , 44.Nm copystr , 45.Nm copyinstr 46.Nd heterogenous address space copy functions 47.Sh SYNOPSIS 48.In sys/types.h 49.In sys/systm.h 50.Ft int 51.Fn copyin "const void *uaddr" "void *kaddr" "size_t len" 52.Ft int 53.Fn copyin_nofault "const void *uaddr" "void *kaddr" "size_t len" 54.Ft int 55.Fn copyout "const void *kaddr" "void *uaddr" "size_t len" 56.Ft int 57.Fn copyout_nofault "const void *kaddr" "void *uaddr" "size_t len" 58.Ft int __deprecated 59.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done" 60.Ft int 61.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done" 62.Sh DESCRIPTION 63The 64.Nm 65functions are designed to copy contiguous data from one address space 66to another. 67.Pp 68.Fn copystr 69is deprecated and should be replaced with 70.Xr strlcpy 9 . 71It will be removed from 72.Fx 13 . 73.Pp 74The 75.Fn copyin 76and 77.Fn copyin_nofault 78functions copy 79.Fa len 80bytes of data from the user-space address 81.Fa uaddr 82to the kernel-space address 83.Fa kaddr . 84.Pp 85The 86.Fn copyout 87and 88.Fn copyout_nofault 89functions copy 90.Fa len 91bytes of data from the kernel-space address 92.Fa kaddr 93to the user-space address 94.Fa uaddr . 95.Pp 96The 97.Fn copyin_nofault 98and 99.Fn copyout_nofault 100functions require that the kernel-space and user-space data be 101accessible without incurring a page fault. 102The source and destination addresses must be physically mapped for 103read and write access, respectively, and neither the source nor 104destination addresses may be pageable. 105.Pp 106The 107.Fn copystr 108function copies a NUL-terminated string, at most 109.Fa len 110bytes long, from kernel-space address 111.Fa kfaddr 112to kernel-space address 113.Fa kdaddr . 114The number of bytes actually copied, including the terminating 115NUL, is returned in 116.Fa *done 117(if 118.Fa done 119is 120.No non- Ns Dv NULL ) . 121.Pp 122The 123.Fn copyinstr 124function copies a NUL-terminated string, at most 125.Fa len 126bytes long, from user-space address 127.Fa uaddr 128to kernel-space address 129.Fa kaddr . 130The number of bytes actually copied, including the terminating 131NUL, is returned in 132.Fa *done 133(if 134.Fa done 135is 136.No non- Ns Dv NULL ) . 137.Sh RETURN VALUES 138The 139.Nm 140functions return 0 on success. 141All but 142.Fn copystr 143return 144.Er EFAULT 145if a bad address is encountered. 146The 147.Fn copyin_nofault 148and 149.Fn copyout_nofault 150functions return 151.Er EFAULT 152if a page fault occurs. 153The 154.Fn copystr 155and 156.Fn copyinstr 157functions return 158.Er ENAMETOOLONG 159if the string is longer than 160.Fa len 161bytes. 162.Sh SEE ALSO 163.Xr fetch 9 , 164.Xr store 9 165