1.\" $NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $ 2.\" 3.\" Copyright (c) 1996 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.\" $FreeBSD: head/share/man/man9/copy.9 223890 2011-07-09 15:24:12Z kib $ 36.\" 37.Dd July 9, 2011 38.Dt COPY 9 39.Os 40.Sh NAME 41.Nm copy , 42.Nm copyin , 43.Nm copyin_nofault , 44.Nm copyout , 45.Nm copyout_nofault , 46.Nm copystr , 47.Nm copyinstr 48.Nd kernel copy functions 49.Sh SYNOPSIS 50.In sys/types.h 51.In sys/systm.h 52.Ft int 53.Fn copyin "const void *uaddr" "void *kaddr" "size_t len" 54.Ft int 55.Fn copyin_nofault "const void *uaddr" "void *kaddr" "size_t len" 56.Ft int 57.Fn copyout "const void *kaddr" "void *uaddr" "size_t len" 58.Ft int 59.Fn copyout_nofault "const void *kaddr" "void *uaddr" "size_t len" 60.Ft int 61.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done" 62.Ft int 63.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done" 64.\" .Ft int 65.\" .Fn copyoutstr "const void *kaddr" "void *uaddr" "size_t len" "size_t *done" 66.Sh DESCRIPTION 67The 68.Nm 69functions are designed to copy contiguous data from one address 70to another. 71All but 72.Fn copystr 73copy data from user-space to kernel-space or vice-versa. 74.Pp 75The 76.Fn copyin 77and 78.Fn copyin_nofault 79functions copy 80.Fa len 81bytes of data from the user-space address 82.Fa uaddr 83to the kernel-space address 84.Fa kaddr . 85.Pp 86The 87.Fn copyout 88and 89.Fn copyout_nofault 90functions copy 91.Fa len 92bytes of data from the kernel-space address 93.Fa kaddr 94to the user-space address 95.Fa uaddr . 96.Pp 97The 98.Fn copyin_nofault 99and 100.Fn copyout_nofault 101functions require that the kernel-space and user-space data be 102accessible without incurring a page fault. 103The source and destination addresses must be physically mapped for 104read and write access, respectively, and neither the source nor 105destination addresses may be pageable. 106.Pp 107The 108.Fn copystr 109function copies a NUL-terminated string, at most 110.Fa len 111bytes long, from kernel-space address 112.Fa kfaddr 113to kernel-space address 114.Fa kdaddr . 115The number of bytes actually copied, including the terminating 116NUL, is returned in 117.Fa *done 118(if 119.Fa done 120is 121.No non- Ns Dv NULL ) . 122.Pp 123The 124.Fn copyinstr 125function copies a NUL-terminated string, at most 126.Fa len 127bytes long, from user-space address 128.Fa uaddr 129to kernel-space address 130.Fa kaddr . 131The number of bytes actually copied, including the terminating 132NUL, is returned in 133.Fa *done 134(if 135.Fa done 136is 137.No non- Ns Dv NULL ) . 138.\" .It Fn copyoutstr 139.\" Copies a NUL-terminated string, at most 140.\" bytes long, from kernel-space address 141.\" .Fa kaddr 142.\" to user-space address 143.\" .Fa uaddr . 144.\" The number of bytes actually copied, including the terminating 145.\" NUL, is returned in 146.\" .Fa *done . 147.Sh RETURN VALUES 148The 149.Nm 150functions return 0 on success or 151.Er EFAULT 152if a bad address is encountered. 153In addition, the 154.Fn copyin_nofault 155and 156.Fn copyout_nofault 157functions return 158.Er EFAULT 159if a page fault occurs, and the 160.Fn copystr 161and 162.Fn copyinstr 163.\" .Fn copyinstr , 164.\" and 165.\" .Fn copyoutstr 166functions return 167.Er ENAMETOOLONG 168if the string is longer than 169.Fa len 170bytes. 171.Sh SEE ALSO 172.Xr fetch 9 , 173.Xr store 9 174