Document copyin_nofault and copyout_nofault(9)
authorFrançois Tigeot <ftigeot@wolfpond.org>
Mon, 22 Jul 2013 16:02:17 +0000 (18:02 +0200)
committerFrançois Tigeot <ftigeot@wolfpond.org>
Mon, 22 Jul 2013 16:51:47 +0000 (18:51 +0200)
share/man/man9/Makefile
share/man/man9/copy.9

index 6115bed..a1fda93 100644 (file)
@@ -383,8 +383,10 @@ MLINKS+=config_intrhook.9 config_intrhook_disestablish.9 \
        config_intrhook.9 config_intrhook_establish.9
 MLINKS+=contigmalloc.9 contigfree.9
 MLINKS+=copy.9 copyin.9 \
+       copy.9 copyin_nofault.9 \
        copy.9 copyinstr.9 \
        copy.9 copyout.9 \
+       copy.9 copyout_nofault.9 \
        copy.9 copystr.9
 MLINKS+=crit_enter.9 crit_enter_gd.9 \
        crit_enter.9 crit_enter_id.9 \
index 51fcb9f..852a51a 100644 (file)
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD: src/share/man/man9/copy.9,v 1.6.2.5 2001/12/17 11:30:18 ru Exp $
-.\" $DragonFly: src/share/man/man9/copy.9,v 1.3 2007/04/07 19:29:52 swildner Exp $
+.\" $FreeBSD: head/share/man/man9/copy.9 223890 2011-07-09 15:24:12Z kib $
 .\"
-.Dd January 7, 1996
+.Dd July 9, 2011
 .Dt COPY 9
 .Os
 .Sh NAME
 .Nm copy ,
 .Nm copyin ,
+.Nm copyin_nofault ,
 .Nm copyout ,
+.Nm copyout_nofault ,
 .Nm copystr ,
 .Nm copyinstr
 .Nd kernel copy functions
 .Ft int
 .Fn copyin "const void *uaddr" "void *kaddr" "size_t len"
 .Ft int
+.Fn copyin_nofault "const void *uaddr" "void *kaddr" "size_t len"
+.Ft int
 .Fn copyout "const void *kaddr" "void *uaddr" "size_t len"
 .Ft int
+.Fn copyout_nofault "const void *kaddr" "void *uaddr" "size_t len"
+.Ft int
 .Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done"
 .Ft int
 .Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done"
 The
 .Nm
 functions are designed to copy contiguous data from one address
-to another.  All but
+to another.
+All but
 .Fn copystr
 copy data from user-space to kernel-space or vice-versa.
 .Pp
 The
-.Nm
-routines provide the following functionality:
-.Bl -tag -width "copyoutstr()"
-.It Fn copyin
-Copies
+.Fn copyin
+and
+.Fn copyin_nofault
+functions copy
 .Fa len
 bytes of data from the user-space address
 .Fa uaddr
 to the kernel-space address
 .Fa kaddr .
-.It Fn copyout
-Copies
+.Pp
+The
+.Fn copyout
+and
+.Fn copyout_nofault
+functions copy
 .Fa len
 bytes of data from the kernel-space address
 .Fa kaddr
 to the user-space address
 .Fa uaddr .
-.It Fn copystr
-Copies a NUL-terminated string, at most
+.Pp
+The
+.Fn copyin_nofault
+and
+.Fn copyout_nofault
+functions require that the kernel-space and user-space data be
+accessible without incurring a page fault.
+The source and destination addresses must be physically mapped for
+read and write access, respectively, and neither the source nor
+destination addresses may be pageable.
+.Pp
+The
+.Fn copystr
+function copies a NUL-terminated string, at most
 .Fa len
 bytes long, from kernel-space address
 .Fa kfaddr
@@ -93,9 +114,15 @@ to kernel-space address
 .Fa kdaddr .
 The number of bytes actually copied, including the terminating
 NUL, is returned in
-.Fa *done .
-.It Fn copyinstr
-Copies a NUL-terminated string, at most
+.Fa *done
+(if
+.Fa done
+is
+.No non- Ns Dv NULL ) .
+.Pp
+The
+.Fn copyinstr
+function copies a NUL-terminated string, at most
 .Fa len
 bytes long, from user-space address
 .Fa uaddr
@@ -103,7 +130,11 @@ to kernel-space address
 .Fa kaddr .
 The number of bytes actually copied, including the terminating
 NUL, is returned in
-.Fa *done .
+.Fa *done
+(if
+.Fa done
+is
+.No non- Ns Dv NULL ) .
 .\" .It Fn copyoutstr
 .\" Copies a NUL-terminated string, at most
 .\" bytes long, from kernel-space address
@@ -113,7 +144,6 @@ NUL, is returned in
 .\" The number of bytes actually copied, including the terminating
 .\" NUL, is returned in
 .\" .Fa *done .
-.El
 .Sh RETURN VALUES
 The
 .Nm
@@ -121,7 +151,13 @@ functions return 0 on success or
 .Er EFAULT
 if a bad address is encountered.
 In addition, the
-.Fn copystr ,
+.Fn copyin_nofault
+and
+.Fn copyout_nofault
+functions return
+.Er EFAULT
+if a page fault occurs, and the
+.Fn copystr
 and
 .Fn copyinstr
 .\" .Fn copyinstr ,