xnu-3789.70.16.tar.gz

[apple/xnu.git] / bsd / man / man9 / copy.9

diff --git a/bsd/man/man9/copy.9 b/bsd/man/man9/copy.9
index 5d82b9da417783732d115cc776c97f90f117359c..5577a12005fdfeaf50f77c12a626c6f373aeb444 100644 (file)
--- a/bsd/man/man9/copy.9
+++ b/bsd/man/man9/copy.9
@@ -1,3 +1,26 @@
+.\"
+.\" Copyright (c) 2008 Apple Inc.  All rights reserved.
+.\"
+.\" @APPLE_LICENSE_HEADER_START@
+.\" 
+.\" This file contains Original Code and/or Modifications of Original Code
+.\" as defined in and that are subject to the Apple Public Source License
+.\" Version 2.0 (the 'License'). You may not use this file except in
+.\" compliance with the License. Please obtain a copy of the License at
+.\" http://www.opensource.apple.com/apsl/ and read it before using this
+.\" file.
+.\" 
+.\" The Original Code and all software distributed under the License are
+.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+.\" Please see the License for the specific language governing rights and
+.\" limitations under the License.
+.\" 
+.\" @APPLE_LICENSE_HEADER_END@
+.\"
+.\"
 .\"    $NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $
 .\"
 .\" Copyright (c) 1996 Jason R. Thorpe.
@@ -34,29 +57,52 @@
 .\"
 .\" $FreeBSD: src/share/man/man9/copy.9,v 1.6.2.5 2001/12/17 11:30:18 ru Exp $
 .\"
-.Dd January 7, 1996
+.Dd October 2, 2008
 .Dt COPY 9
 .Os
 .Sh NAME
 .Nm copy ,
 .Nm copyin ,
+.Nm copyinstr ,
 .Nm copyout ,
-.Nm copystr ,
-.Nm copyinstr
+.Nm copystr
 .Nd kernel copy functions
 .Sh SYNOPSIS
 .In sys/types.h
 .In sys/systm.h
 .Ft int
-.Fn copyin "const void *uaddr" "void *kaddr" "size_t len"
+.Fo copyin
+.Fa "const void *uaddr"
+.Fa "void *kaddr"
+.Fa "size_t len"
+.Fc
 .Ft int
-.Fn copyout "const void *kaddr" "void *uaddr" "size_t len"
+.Fo copyinstr
+.Fa "const void *uaddr"
+.Fa "void *kaddr"
+.Fa "size_t len"
+.Fa "size_t *done"
+.Fc
 .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"
+.Fo copyout
+.Fa "const void *kaddr"
+.Fa "void *uaddr"
+.Fa "size_t len"
+.Fc
 .\" .Ft int
-.\" .Fn copyoutstr "const void *kaddr" "void *uaddr" "size_t len" "size_t *done"
+.\" .Fn copyoutstr
+.\" .Fa "const void *kaddr"
+.\" .Fa "void *uaddr"
+.\" .Fa "size_t len"
+.\" .Fa "size_t *done"
+.\" .Fc
+.Ft int
+.Fo copystr
+.Fa "const void *kfaddr"
+.Fa "void *kdaddr"
+.Fa "size_t len"
+.Fa "size_t *done"
+.Fc
 .Sh DESCRIPTION
 The
 .Nm
@@ -69,6 +115,7 @@ The
 .Nm
 routines provide the following functionality:
 .Bl -tag -width "copyoutstr()"
+.\" ========
 .It Fn copyin
 Copies
 .Pa len
@@ -76,23 +123,7 @@ bytes of data from the user-space address
 .Pa uaddr
 to the kernel-space address
 .Pa kaddr .
-.It Fn copyout
-Copies
-.Pa len
-bytes of data from the kernel-space address
-.Pa kaddr
-to the user-space address
-.Pa uaddr .
-.It Fn copystr
-Copies a NUL-terminated string, at most
-.Pa len
-bytes long, from kernel-space address
-.Pa kfaddr
-to kernel-space address
-.Pa kdaddr .
-The number of bytes actually copied, including the terminating
-NUL, is returned in
-.Pa *done .
+.\" ========
 .It Fn copyinstr
 Copies a NUL-terminated string, at most
 .Pa len
@@ -103,6 +134,15 @@ to kernel-space address
 The number of bytes actually copied, including the terminating
 NUL, is returned in
 .Pa *done .
+.\" ========
+.It Fn copyout
+Copies
+.Pa len
+bytes of data from the kernel-space address
+.Pa kaddr
+to the user-space address
+.Pa uaddr .
+.\" ========
 .\" .It Fn copyoutstr
 .\" Copies a NUL-terminated string, at most
 .\" bytes long, from kernel-space address
@@ -112,25 +152,62 @@ NUL, is returned in
 .\" The number of bytes actually copied, including the terminating
 .\" NUL, is returned in
 .\" .Pa *done .
+.\" ========
+.It Fn copystr
+Copies a NUL-terminated string, at most
+.Pa len
+bytes long, from kernel-space address
+.Pa kfaddr
+to kernel-space address
+.Pa kdaddr .
+The number of bytes actually copied, including the terminating
+NUL, is returned in
+.Pa *done .
 .El
 .Sh RETURN VALUES
 The
 .Nm
-functions return 0 on success or
-.Er EFAULT
-if a bad address is encountered.
-In addition, the
-.Fn copystr ,
+functions return 0 on success or the following error on failure:
+.\" ========
+.Bl -tag -width Er
+.It Bq EFAULT
+If a bad address is encountered. When this error is returned, the contents of the destination buffer (
+.Fa *kaddr
+for
+.Fn copyin ,
+.Fn copyinstr ,
 and
+.Fn copystr ;
+.Fa *uaddr
+for
+.Fn copyout )
+are undefined. For
 .Fn copyinstr
+and
+.Fn copystr ,
+the contents of the
+.Fa *done
+parameter are also undefined on a return of EFAULT.
+.El
+.Pp
+In addition to EFAULT,
+.\" .Fn copystr ,
 .\" .Fn copyinstr ,
 .\" and
 .\" .Fn copyoutstr
-functions return
-.Er ENAMETOOLONG
-if the string is longer than
+.Fn copystr
+and
+.Fn copyinstr
+on failure will return:
+.\" ========
+.Bl -tag -width Er
+.It Bq ENAMETOLONG
+When the string is longer than
 .Pa len
-bytes.
+bytes. On this error return, the destination buffer is not null-terminated, but the
+.Fa *done
+parameter is maintained.
+.EL
 .Sh SEE ALSO
 .Xr fetch 9 ,
 .Xr store 9