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