share/man/man9/copy.9

   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
  67 The
  68 .Nm
  69 functions are designed to copy contiguous data from one address
  70 to another.
  71 All but
  72 .Fn copystr
  73 copy data from user-space to kernel-space or vice-versa.
  74 .Pp
  75 The
  76 .Fn copyin
  77 and
  78 .Fn copyin_nofault
  79 functions copy
  80 .Fa len
  81 bytes of data from the user-space address
  82 .Fa uaddr
  83 to the kernel-space address
  84 .Fa kaddr .
  85 .Pp
  86 The
  87 .Fn copyout
  88 and
  89 .Fn copyout_nofault
  90 functions copy
  91 .Fa len
  92 bytes of data from the kernel-space address
  93 .Fa kaddr
  94 to the user-space address
  95 .Fa uaddr .
  96 .Pp
  97 The
  98 .Fn copyin_nofault
  99 and
 100 .Fn copyout_nofault
 101 functions require that the kernel-space and user-space data be
 102 accessible without incurring a page fault.
 103 The source and destination addresses must be physically mapped for
 104 read and write access, respectively, and neither the source nor
 105 destination addresses may be pageable.
 106 .Pp
 107 The
 108 .Fn copystr
 109 function copies a NUL-terminated string, at most
 110 .Fa len
 111 bytes long, from kernel-space address
 112 .Fa kfaddr
 113 to kernel-space address
 114 .Fa kdaddr .
 115 The number of bytes actually copied, including the terminating
 116 NUL, is returned in
 117 .Fa *done
 118 (if
 119 .Fa done
 120 is
 121 .No non- Ns Dv NULL ) .
 122 .Pp
 123 The
 124 .Fn copyinstr
 125 function copies a NUL-terminated string, at most
 126 .Fa len
 127 bytes long, from user-space address
 128 .Fa uaddr
 129 to kernel-space address
 130 .Fa kaddr .
 131 The number of bytes actually copied, including the terminating
 132 NUL, is returned in
 133 .Fa *done
 134 (if
 135 .Fa done
 136 is
 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
 148 The
 149 .Nm
 150 functions return 0 on success or
 151 .Er EFAULT
 152 if a bad address is encountered.
 153 In addition, the
 154 .Fn copyin_nofault
 155 and
 156 .Fn copyout_nofault
 157 functions return
 158 .Er EFAULT
 159 if a page fault occurs, and the
 160 .Fn copystr
 161 and
 162 .Fn copyinstr
 163 .\" .Fn copyinstr ,
 164 .\" and
 165 .\" .Fn copyoutstr
 166 functions return
 167 .Er ENAMETOOLONG
 168 if the string is longer than
 169 .Fa len
 170 bytes.
 171 .Sh SEE ALSO
 172 .Xr fetch 9 ,
 173 .Xr store 9