bsd/man/man9/copy.9

   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
 107 The
 108 .Nm
 109 functions are designed to copy contiguous data from one address
 110 to another.  All but
 111 .Fn copystr
 112 copy data from user-space to kernel-space or vice-versa.
 113 .Pp
 114 The
 115 .Nm
 116 routines provide the following functionality:
 117 .Bl -tag -width "copyoutstr()"
 118 .\" ========
 119 .It Fn copyin
 120 Copies
 121 .Pa len
 122 bytes of data from the user-space address
 123 .Pa uaddr
 124 to the kernel-space address
 125 .Pa kaddr .
 126 .\" ========
 127 .It Fn copyinstr
 128 Copies a NUL-terminated string, at most
 129 .Pa len
 130 bytes long, from user-space address
 131 .Pa uaddr
 132 to kernel-space address
 133 .Pa kaddr .
 134 The number of bytes actually copied, including the terminating
 135 NUL, is returned in
 136 .Pa *done .
 137 .\" ========
 138 .It Fn copyout
 139 Copies
 140 .Pa len
 141 bytes of data from the kernel-space address
 142 .Pa kaddr
 143 to the user-space address
 144 .Pa uaddr .
 145 .\" ========
 146 .\" .It Fn copyoutstr
 147 .\" Copies a NUL-terminated string, at most
 148 .\" bytes long, from kernel-space address
 149 .\" .Pa kaddr
 150 .\" to user-space address
 151 .\" .Pa uaddr .
 152 .\" The number of bytes actually copied, including the terminating
 153 .\" NUL, is returned in
 154 .\" .Pa *done .
 155 .\" ========
 156 .It Fn copystr
 157 Copies a NUL-terminated string, at most
 158 .Pa len
 159 bytes long, from kernel-space address
 160 .Pa kfaddr
 161 to kernel-space address
 162 .Pa kdaddr .
 163 The number of bytes actually copied, including the terminating
 164 NUL, is returned in
 165 .Pa *done .
 166 .El
 167 .Sh RETURN VALUES
 168 The
 169 .Nm
 170 functions return 0 on success or the following error on failure:
 171 .\" ========
 172 .Bl -tag -width Er
 173 .It Bq EFAULT
 174 If a bad address is encountered. When this error is returned, the contents of the destination buffer (
 175 .Fa *kaddr
 176 for
 177 .Fn copyin ,
 178 .Fn copyinstr ,
 179 and
 180 .Fn copystr ;
 181 .Fa *uaddr
 182 for
 183 .Fn copyout )
 184 are undefined. For
 185 .Fn copyinstr
 186 and
 187 .Fn copystr ,
 188 the contents of the
 189 .Fa *done
 190 parameter are also undefined on a return of EFAULT.
 191 .El
 192 .Pp
 193 In addition to EFAULT,
 194 .\" .Fn copystr ,
 195 .\" .Fn copyinstr ,
 196 .\" and
 197 .\" .Fn copyoutstr
 198 .Fn copystr
 199 and
 200 .Fn copyinstr
 201 on failure will return:
 202 .\" ========
 203 .Bl -tag -width Er
 204 .It Bq ENAMETOLONG
 205 When the string is longer than
 206 .Pa len
 207 bytes. On this error return, the destination buffer is not null-terminated, but the
 208 .Fa *done
 209 parameter is maintained.
 210 .EL
 211 .Sh SEE ALSO
 212 .Xr fetch 9 ,
 213 .Xr store 9