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