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

.\"	$NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $
.\"
.\" Copyright (c) 1996 Jason R. Thorpe.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed by Kenneth Stailey.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed for the NetBSD Project
.\"	by Jason R. Thorpe.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" 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 $
.\"
.Dd January 7, 1996
.Dt COPY 9
.Os
.Sh NAME
.Nm copy ,
.Nm copyin ,
.Nm copyout ,
.Nm copystr ,
.Nm copyinstr
.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"
.Ft int
.Fn copyout "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"
.\" .Ft int
.\" .Fn copyoutstr "const void *kaddr" "void *uaddr" "size_t len" "size_t *done"
.Sh DESCRIPTION
The
.Nm
functions are designed to copy contiguous data from one address
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
.Pa len
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
bytes long, from user-space address
.Pa uaddr
to kernel-space address
.Pa kaddr .
The number of bytes actually copied, including the terminating
NUL, is returned in
.Pa *done .
.\" .It Fn copyoutstr
.\" Copies a NUL-terminated string, at most
.\" bytes long, from kernel-space address
.\" .Pa kaddr
.\" to user-space address
.\" .Pa uaddr .
.\" 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 ,
and
.Fn copyinstr
.\" .Fn copyinstr ,
.\" and
.\" .Fn copyoutstr
functions return
.Er ENAMETOOLONG
if the string is longer than
.Pa len
bytes.
.Sh SEE ALSO
.Xr fetch 9 ,
.Xr store 9
Commit	Line	Data
9bccf70c A	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: src/share/man/man9/copy.9,v 1.6.2.5 2001/12/17 11:30:18 ru Exp $
	36	.\"
	37	.Dd January 7, 1996
	38	.Dt COPY 9
	39	.Os
	40	.Sh NAME
	41	.Nm copy ,
	42	.Nm copyin ,
	43	.Nm copyout ,
	44	.Nm copystr ,
	45	.Nm copyinstr
	46	.Nd kernel copy functions
	47	.Sh SYNOPSIS
	48	.In sys/types.h
	49	.In sys/systm.h
	50	.Ft int
	51	.Fn copyin "const void uaddr" "void kaddr" "size_t len"
	52	.Ft int
	53	.Fn copyout "const void kaddr" "void uaddr" "size_t len"
	54	.Ft int
	55	.Fn copystr "const void kfaddr" "void kdaddr" "size_t len" "size_t *done"
	56	.Ft int
	57	.Fn copyinstr "const void uaddr" "void kaddr" "size_t len" "size_t *done"
	58	.\" .Ft int
	59	.\" .Fn copyoutstr "const void kaddr" "void uaddr" "size_t len" "size_t *done"
	60	.Sh DESCRIPTION
	61	The
	62	.Nm
	63	functions are designed to copy contiguous data from one address
	64	to another. All but
65	.Fn copystr
66	copy data from user-space to kernel-space or vice-versa.
67	.Pp
68	The
69	.Nm
70	routines provide the following functionality:
71	.Bl -tag -width "copyoutstr()"
72	.It Fn copyin
73	Copies
74	.Pa len
75	bytes of data from the user-space address
76	.Pa uaddr
77	to the kernel-space address
78	.Pa kaddr .
79	.It Fn copyout
80	Copies
81	.Pa len
82	bytes of data from the kernel-space address
83	.Pa kaddr
84	to the user-space address
85	.Pa uaddr .
86	.It Fn copystr
87	Copies a NUL-terminated string, at most
88	.Pa len
89	bytes long, from kernel-space address
90	.Pa kfaddr
91	to kernel-space address
92	.Pa kdaddr .
93	The number of bytes actually copied, including the terminating
94	NUL, is returned in
95	.Pa *done .
96	.It Fn copyinstr
97	Copies a NUL-terminated string, at most
98	.Pa len
99	bytes long, from user-space address
100	.Pa uaddr
101	to kernel-space address
102	.Pa kaddr .
103	The number of bytes actually copied, including the terminating
104	NUL, is returned in
105	.Pa *done .
106	.\" .It Fn copyoutstr
107	.\" Copies a NUL-terminated string, at most
108	.\" bytes long, from kernel-space address
109	.\" .Pa kaddr
110	.\" to user-space address
111	.\" .Pa uaddr .
112	.\" The number of bytes actually copied, including the terminating
113	.\" NUL, is returned in
114	.\" .Pa *done .
115	.El
116	.Sh RETURN VALUES
117	The
118	.Nm
119	functions return 0 on success or
120	.Er EFAULT
121	if a bad address is encountered.
122	In addition, the
123	.Fn copystr ,
124	and
125	.Fn copyinstr
126	.\" .Fn copyinstr ,
127	.\" and
128	.\" .Fn copyoutstr
129	functions return
130	.Er ENAMETOOLONG
131	if the string is longer than
132	.Pa len
133	bytes.
134	.Sh SEE ALSO
135	.Xr fetch 9 ,
136	.Xr store 9