1.\" $OpenBSD: copy.9,v 1.16 2013/06/04 19:27:04 schwarze 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: June 4 2013 $ 37.Dt COPY 9 38.Os 39.Sh NAME 40.Nm copy 41.Nd kernel copy functions 42.Sh SYNOPSIS 43.In sys/types.h 44.In sys/systm.h 45.Ft int 46.Fn copyin "const void *uaddr" "void *kaddr" "size_t len" 47.Ft int 48.Fn copyout "const void *kaddr" "void *uaddr" "size_t len" 49.Ft int 50.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done" 51.Ft int 52.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done" 53.Ft int 54.Fn copyoutstr "const void *kaddr" "void *uaddr" "size_t len" "size_t *done" 55.Ft int 56.Fn kcopy "const void *kfaddr" "void *kdaddr" "size_t len" 57.Sh DESCRIPTION 58The 59.Nm 60functions are designed to copy contiguous data from one address to another. 61All but 62.Fn copystr 63and 64.Fn kcopy 65copy data from user-space to kernel-space or vice-versa. 66.Pp 67The 68.Nm 69routines provide the following functionality: 70.Bl -tag -width "copyoutstr()" 71.It Fn copyin 72Copies 73.Fa len 74bytes of data from the user-space address 75.Fa uaddr 76to the kernel-space address 77.Fa kaddr . 78.It Fn copyout 79Copies 80.Fa len 81bytes of data from the kernel-space address 82.Fa kaddr 83to the user-space address 84.Fa uaddr . 85.It Fn copystr 86Copies a null-terminated string, at most 87.Fa len 88bytes long, from kernel-space address 89.Fa kfaddr 90to kernel-space address 91.Fa kdaddr . 92The number of bytes actually copied, including the terminating null, 93is returned in 94.Fa *done , 95if 96.Fa done 97is not 98.Dv NULL . 99.Pp 100Unlike the other 101.Nm 102functions, 103.Fn copystr 104does 105.Em not 106support returning 107.Er EFAULT 108when a bad address is encountered. 109.It Fn copyinstr 110Copies a null-terminated string, at most 111.Fa len 112bytes long, from user-space address 113.Fa uaddr 114to kernel-space address 115.Fa kaddr . 116The number of bytes actually copied, including the terminating null, 117is returned in 118.Fa *done , 119if 120.Fa done 121is not 122.Dv NULL . 123.It Fn copyoutstr 124Copies a null-terminated string, at most 125.Fa len 126bytes long, from kernel-space address 127.Fa kaddr 128to user-space address 129.Fa uaddr . 130The number of bytes actually copied, including the terminating null, 131is returned in 132.Fa *done , 133if 134.Fa done 135is not 136.Dv NULL . 137.It Fn kcopy 138Copies 139.Fa len 140bytes of data from the kernel-space address 141.Fa kfaddr 142to the kernel-space address 143.Fa kdaddr . 144.El 145.Sh RETURN VALUES 146The 147.Nm 148functions return 0 on success or 149.Er EFAULT 150if a bad address is encountered. 151In addition, the 152.Fn copystr , 153.Fn copyinstr , 154and 155.Fn copyoutstr 156functions return 157.Er ENAMETOOLONG 158if the string is longer than 159.Fa len 160bytes. 161.\" .Sh SEE ALSO 162