1.\" $NetBSD: copy.9,v 1.19 2008/09/12 00:35:12 simonb Exp $ 2.\" 3.\" Copyright (c) 1996, 2002 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 August 28, 2005 36.Dt COPY 9 37.Os 38.Sh NAME 39.Nm copy , 40.Nm copyin , 41.Nm copyout , 42.Nm copystr , 43.Nm copyinstr , 44.Nm copyoutstr 45.Nd kernel space to/from user space copy functions 46.Sh SYNOPSIS 47.In sys/types.h 48.In sys/systm.h 49.Ft int 50.Fn copyin "const void *uaddr" "void *kaddr" "size_t len" 51.Ft int 52.Fn copyout "const void *kaddr" "void *uaddr" "size_t len" 53.Ft int 54.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done" 55.Ft int 56.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done" 57.Ft int 58.Fn copyoutstr "const void *kaddr" "void *uaddr" "size_t len" "size_t *done" 59.Ft int 60.Fn copyin_proc "struct proc *p" "const void *uaddr" "void *kaddr" "size_t len" 61.Ft int 62.Fn copyout_proc "struct proc *p" "const void *kaddr" "void *uaddr" "size_t len" 63.Ft int 64.Fn ioctl_copyin "int ioctlflags" "const void *src" "void *dst" "size_t len" 65.Ft int 66.Fn ioctl_copyout "int ioctlflags" "const void *src" "void *dst" "size_t len" 67.Sh DESCRIPTION 68The 69.Nm 70functions are designed to copy contiguous data from one address 71to another. 72All but 73.Fn copystr 74copy data from user-space to kernel-space or vice-versa. 75.Pp 76The 77.Nm 78routines provide the following functionality: 79.Bl -tag -width "copyout_proc()" 80.It Fn copyin 81Copies 82.Fa len 83bytes of data from the user-space address 84.Fa uaddr 85in the current process to the kernel-space address 86.Fa kaddr . 87.It Fn copyout 88Copies 89.Fa len 90bytes of data from the kernel-space address 91.Fa kaddr 92to the user-space address 93.Fa uaddr 94in the current process. 95.It Fn copystr 96Copies a NUL-terminated string, at most 97.Fa len 98bytes long, from kernel-space address 99.Fa kfaddr 100to kernel-space address 101.Fa kdaddr . 102If the 103.Fa done 104argument is non-NULL, 105the number of bytes actually copied, including the terminating 106NUL, is returned in 107.Fa *done . 108.It Fn copyinstr 109Copies a NUL-terminated string, at most 110.Fa len 111bytes long, from user-space address 112.Fa uaddr 113in the current process to kernel-space address 114.Fa kaddr . 115If the 116.Fa done 117argument is non-NULL, 118the number of bytes actually copied, including the terminating 119NUL, is returned in 120.Fa *done . 121.It Fn copyoutstr 122Copies a NUL-terminated string, at most 123.Fa len 124bytes long, from kernel-space address 125.Fa kaddr 126to user-space address 127.Fa uaddr 128in the current process. 129If the 130.Fa done 131argument is non-NULL, 132the number of bytes actually copied, including the terminating 133NUL, is returned in 134.Fa *done . 135.It Fn copyin_proc 136Like 137.Fn copyin , 138except it operates on the address space of the process 139.Fa p . 140.It Fn copyout_proc 141Like 142.Fn copyout , 143except it operates on the address space of the process 144.Fa p . 145.It Fn ioctl_copyin 146Like 147.Fn copyin , 148except it operates on kernel adresses when the 149.Dv FKIOCTL 150flag is passed in 151.Fa ioctlflags 152from the ioctl call. 153.It Fn ioctl_copyout 154Like 155.Fn copyout , 156except it operates on kernel adresses when the 157.Dv FKIOCTL 158flag is passed in 159.Fa ioctlflags 160from the ioctl call. 161.El 162.Sh RETURN VALUES 163The 164.Nm 165functions return 0 on success or 166.Er EFAULT 167if a bad address is encountered. 168In addition, the 169.Fn copystr , 170.Fn copyinstr , 171and 172.Fn copyoutstr 173functions return 174.Er ENAMETOOLONG 175if the string is longer than 176.Fa len 177bytes. 178.Sh SEE ALSO 179.Xr fetch 9 , 180.Xr store 9 181