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