1.\" 2.\" Copyright (c) 2008 Apple Inc. All rights reserved. 3.\" 4.\" @APPLE_LICENSE_HEADER_START@ 5.\" 6.\" This file contains Original Code and/or Modifications of Original Code 7.\" as defined in and that are subject to the Apple Public Source License 8.\" Version 2.0 (the 'License'). You may not use this file except in 9.\" compliance with the License. Please obtain a copy of the License at 10.\" http://www.opensource.apple.com/apsl/ and read it before using this 11.\" file. 12.\" 13.\" The Original Code and all software distributed under the License are 14.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18.\" Please see the License for the specific language governing rights and 19.\" limitations under the License. 20.\" 21.\" @APPLE_LICENSE_HEADER_END@ 22.\" 23.\" 24.\" $NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $ 25.\" 26.\" Copyright (c) 1996 Jason R. Thorpe. 27.\" All rights reserved. 28.\" 29.\" This code is derived from software contributed by Kenneth Stailey. 30.\" 31.\" Redistribution and use in source and binary forms, with or without 32.\" modification, are permitted provided that the following conditions 33.\" are met: 34.\" 1. Redistributions of source code must retain the above copyright 35.\" notice, this list of conditions and the following disclaimer. 36.\" 2. Redistributions in binary form must reproduce the above copyright 37.\" notice, this list of conditions and the following disclaimer in the 38.\" documentation and/or other materials provided with the distribution. 39.\" 3. All advertising materials mentioning features or use of this software 40.\" must display the following acknowledgement: 41.\" This product includes software developed for the NetBSD Project 42.\" by Jason R. Thorpe. 43.\" 4. The name of the author may not be used to endorse or promote products 44.\" derived from this software without specific prior written permission. 45.\" 46.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 47.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 48.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 49.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 50.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 51.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 52.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 53.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 54.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 55.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 56.\" SUCH DAMAGE. 57.\" 58.\" $FreeBSD: src/share/man/man9/copy.9,v 1.6.2.5 2001/12/17 11:30:18 ru Exp $ 59.\" 60.Dd October 2, 2008 61.Dt COPY 9 62.Os 63.Sh NAME 64.Nm copy , 65.Nm copyin , 66.Nm copyinstr , 67.Nm copyout , 68.Nm copystr 69.Nd kernel copy functions 70.Sh SYNOPSIS 71.In sys/types.h 72.In sys/systm.h 73.Ft int 74.Fo copyin 75.Fa "const void *uaddr" 76.Fa "void *kaddr" 77.Fa "size_t len" 78.Fc 79.Ft int 80.Fo copyinstr 81.Fa "const void *uaddr" 82.Fa "void *kaddr" 83.Fa "size_t len" 84.Fa "size_t *done" 85.Fc 86.Ft int 87.Fo copyout 88.Fa "const void *kaddr" 89.Fa "void *uaddr" 90.Fa "size_t len" 91.Fc 92.\" .Ft int 93.\" .Fn copyoutstr 94.\" .Fa "const void *kaddr" 95.\" .Fa "void *uaddr" 96.\" .Fa "size_t len" 97.\" .Fa "size_t *done" 98.\" .Fc 99.Ft int 100.Fo copystr 101.Fa "const void *kfaddr" 102.Fa "void *kdaddr" 103.Fa "size_t len" 104.Fa "size_t *done" 105.Fc 106.Sh DESCRIPTION 107The 108.Nm 109functions are designed to copy contiguous data from one address 110to another. 111All but 112.Fn copystr 113copy data from user-space to kernel-space or vice-versa. 114.Pp 115The 116.Nm 117routines provide the following functionality: 118.Bl -tag -width "copyoutstr()" 119.\" ======== 120.It Fn copyin 121Copies 122.Pa len 123bytes of data from the user-space address 124.Pa uaddr 125to the kernel-space address 126.Pa kaddr . 127.\" ======== 128.It Fn copyinstr 129Copies a NUL-terminated string, at most 130.Pa len 131bytes long, from user-space address 132.Pa uaddr 133to kernel-space address 134.Pa kaddr . 135The number of bytes actually copied, including the terminating 136NUL, is returned in 137.Pa *done . 138.\" ======== 139.It Fn copyout 140Copies 141.Pa len 142bytes of data from the kernel-space address 143.Pa kaddr 144to the user-space address 145.Pa uaddr . 146.\" ======== 147.\" .It Fn copyoutstr 148.\" Copies a NUL-terminated string, at most 149.\" bytes long, from kernel-space address 150.\" .Pa kaddr 151.\" to user-space address 152.\" .Pa uaddr . 153.\" The number of bytes actually copied, including the terminating 154.\" NUL, is returned in 155.\" .Pa *done . 156.\" ======== 157.It Fn copystr 158Copies a NUL-terminated string, at most 159.Pa len 160bytes long, from kernel-space address 161.Pa kfaddr 162to kernel-space address 163.Pa kdaddr . 164The number of bytes actually copied, including the terminating 165NUL, is returned in 166.Pa *done . 167.El 168.Sh RETURN VALUES 169The 170.Nm 171functions return 0 on success or the following error on failure: 172.\" ======== 173.Bl -tag -width Er 174.It Bq EFAULT 175If a bad address is encountered. 176When this error is returned, the contents of the destination buffer ( 177.Fa *kaddr 178for 179.Fn copyin , 180.Fn copyinstr , 181and 182.Fn copystr ; 183.Fa *uaddr 184for 185.Fn copyout ) 186are undefined. 187For 188.Fn copyinstr 189and 190.Fn copystr , 191the contents of the 192.Fa *done 193parameter are also undefined on a return of EFAULT. 194.El 195.Pp 196In addition to EFAULT, 197.\" .Fn copystr , 198.\" .Fn copyinstr , 199.\" and 200.\" .Fn copyoutstr 201.Fn copystr 202and 203.Fn copyinstr 204on failure will return: 205.\" ======== 206.Bl -tag -width Er 207.It Bq ENAMETOLONG 208When the string is longer than 209.Pa len 210bytes. 211On this error return, the destination buffer is not null-terminated, but the 212.Fa *done 213parameter is maintained. 214.El 215.Sh SEE ALSO 216.Xr fetch 9 , 217.Xr store 9 218