[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 copyinstr ,
.Nm copyout ,
.Nm copystr
.Nd kernel copy functions
.Sh SYNOPSIS
.In sys/types.h
.In sys/systm.h
.Ft int
.Fo copyin
.Fa "const void *uaddr"
.Fa "void *kaddr"
.Fa "size_t len"
.Fc
.Ft int
.Fo copyinstr
.Fa "const void *uaddr"
.Fa "void *kaddr"
.Fa "size_t len"
.Fa "size_t *done"
.Fc
.Ft int
.Fo copyout
.Fa "const void *kaddr"
.Fa "void *uaddr"
.Fa "size_t len"
.Fc
.\" .Ft int
.\" .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
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 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 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
.\" .Pa kaddr
.\" to user-space address
.\" .Pa uaddr .
.\" 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 ,
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 ,
2d21ac55	43	.Nm copyinstr ,
9bccf70c	44	.Nm copyout ,
2d21ac55	45	.Nm copystr
9bccf70c A	46	.Nd kernel copy functions
	47	.Sh SYNOPSIS
	48	.In sys/types.h
	49	.In sys/systm.h
	50	.Ft int
2d21ac55 A	51	.Fo copyin
	52	.Fa "const void *uaddr"
	53	.Fa "void *kaddr"
	54	.Fa "size_t len"
	55	.Fc
9bccf70c	56	.Ft int
2d21ac55 A	57	.Fo copyinstr
	58	.Fa "const void *uaddr"
	59	.Fa "void *kaddr"
	60	.Fa "size_t len"
	61	.Fa "size_t *done"
	62	.Fc
9bccf70c	63	.Ft int
2d21ac55 A	64	.Fo copyout
	65	.Fa "const void *kaddr"
	66	.Fa "void *uaddr"
	67	.Fa "size_t len"
	68	.Fc
9bccf70c	69	.\" .Ft int
2d21ac55 A	70	.\" .Fn copyoutstr
	71	.\" .Fa "const void *kaddr"
	72	.\" .Fa "void *uaddr"
	73	.\" .Fa "size_t len"
	74	.\" .Fa "size_t *done"
	75	.\" .Fc
	76	.Ft int
	77	.Fo copystr
	78	.Fa "const void *kfaddr"
	79	.Fa "void *kdaddr"
	80	.Fa "size_t len"
	81	.Fa "size_t *done"
	82	.Fc
9bccf70c A	83	.Sh DESCRIPTION
	84	The
	85	.Nm
	86	functions are designed to copy contiguous data from one address
	87	to another. All but
	88	.Fn copystr
	89	copy data from user-space to kernel-space or vice-versa.
	90	.Pp
	91	The
	92	.Nm
	93	routines provide the following functionality:
	94	.Bl -tag -width "copyoutstr()"
2d21ac55	95	.\" ========
9bccf70c A	96	.It Fn copyin
	97	Copies
	98	.Pa len
	99	bytes of data from the user-space address
	100	.Pa uaddr
	101	to the kernel-space address
	102	.Pa kaddr .
2d21ac55	103	.\" ========
9bccf70c A	104	.It Fn copyinstr
	105	Copies a NUL-terminated string, at most
	106	.Pa len
	107	bytes long, from user-space address
	108	.Pa uaddr
	109	to kernel-space address
	110	.Pa kaddr .
	111	The number of bytes actually copied, including the terminating
	112	NUL, is returned in
	113	.Pa *done .
2d21ac55 A	114	.\" ========
	115	.It Fn copyout
	116	Copies
	117	.Pa len
	118	bytes of data from the kernel-space address
	119	.Pa kaddr
	120	to the user-space address
	121	.Pa uaddr .
	122	.\" ========
9bccf70c A	123	.\" .It Fn copyoutstr
	124	.\" Copies a NUL-terminated string, at most
	125	.\" bytes long, from kernel-space address
	126	.\" .Pa kaddr
	127	.\" to user-space address
	128	.\" .Pa uaddr .
	129	.\" The number of bytes actually copied, including the terminating
	130	.\" NUL, is returned in
	131	.\" .Pa *done .
2d21ac55 A	132	.\" ========
	133	.It Fn copystr
	134	Copies a NUL-terminated string, at most
	135	.Pa len
	136	bytes long, from kernel-space address
	137	.Pa kfaddr
	138	to kernel-space address
	139	.Pa kdaddr .
	140	The number of bytes actually copied, including the terminating
	141	NUL, is returned in
	142	.Pa *done .
9bccf70c A	143	.El
	144	.Sh RETURN VALUES
	145	The
	146	.Nm
	147	functions return 0 on success or
	148	.Er EFAULT
	149	if a bad address is encountered.
	150	In addition, the
	151	.Fn copystr ,
	152	and
	153	.Fn copyinstr
	154	.\" .Fn copyinstr ,
	155	.\" and
	156	.\" .Fn copyoutstr
	157	functions return
	158	.Er ENAMETOOLONG
	159	if the string is longer than
	160	.Pa len
	161	bytes.
	162	.Sh SEE ALSO
	163	.Xr fetch 9 ,
	164	.Xr store 9