1.\" $OpenBSD: copy.9,v 1.14 2007/05/31 19:20:00 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: May 31 2007 $ 37.Dt COPY 9 38.Os 39.Sh NAME 40.Nm copy 41.Nd kernel copy functions 42.Sh SYNOPSIS 43.Fd #include <sys/types.h> 44.Fd #include <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.Sh DESCRIPTION 56The 57.Nm 58functions are designed to copy contiguous data from one address to another. 59All but 60.Fn copystr 61copy data from user-space to kernel-space or vice-versa. 62.Pp 63The 64.Nm 65routines provide the following functionality: 66.Bl -tag -width "copyoutstr()" 67.It Fn copyin 68Copies 69.Fa len 70bytes of data from the user-space address 71.Fa uaddr 72to the kernel-space address 73.Fa kaddr . 74.It Fn copyout 75Copies 76.Fa len 77bytes of data from the kernel-space address 78.Fa kaddr 79to the user-space address 80.Fa uaddr . 81.It Fn copystr 82Copies a null-terminated string, at most 83.Fa len 84bytes long, from kernel-space address 85.Fa kfaddr 86to kernel-space address 87.Fa kdaddr . 88The number of bytes actually copied, including the terminating null, 89is returned in 90.Fa *done , 91if 92.Fa done 93is not 94.Dv NULL . 95.It Fn copyinstr 96Copies a null-terminated string, at most 97.Fa len 98bytes long, from user-space address 99.Fa uaddr 100to kernel-space address 101.Fa kaddr . 102The number of bytes actually copied, including the terminating null, 103is returned in 104.Fa *done , 105if 106.Fa done 107is not 108.Dv NULL . 109.It Fn copyoutstr 110Copies a null-terminated string, at most 111.Fa len 112bytes long, from kernel-space address 113.Fa kaddr 114to user-space address 115.Fa uaddr . 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.El 124.Sh RETURN VALUES 125The 126.Nm 127functions return 0 on success or 128.Er EFAULT 129if a bad address is encountered. 130In addition, the 131.Fn copystr , 132.Fn copyinstr , 133and 134.Fn copyoutstr 135functions return 136.Er ENAMETOOLONG 137if the string is longer than 138.Fa len 139bytes. 140.\" .Sh SEE ALSO 141