1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
<table class="head">
<tr>
<td class="head-ltitle">COPY(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">COPY(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">copy</code>, <code class="Nm">copyin</code>,
<code class="Nm">copyin_nofault</code>, <code class="Nm">copyout</code>,
<code class="Nm">copyout_nofault</code>, <code class="Nm">copystr</code>,
<code class="Nm">copyinstr</code> — <span class="Nd">heterogeneous
address space copy functions</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/types.h</a>></code>
<br/>
<code class="In">#include <<a class="In">sys/systm.h</a>></code></p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">copyin</code>(<var class="Fa" style="white-space: nowrap;">const
void *uaddr</var>, <var class="Fa" style="white-space: nowrap;">void
*kaddr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">copyin_nofault</code>(<var class="Fa" style="white-space: nowrap;">const
void *uaddr</var>, <var class="Fa" style="white-space: nowrap;">void
*kaddr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">copyout</code>(<var class="Fa" style="white-space: nowrap;">const
void *kaddr</var>, <var class="Fa" style="white-space: nowrap;">void
*uaddr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">copyout_nofault</code>(<var class="Fa" style="white-space: nowrap;">const
void *kaddr</var>, <var class="Fa" style="white-space: nowrap;">void
*uaddr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int __deprecated</var>
<br/>
<code class="Fn">copystr</code>(<var class="Fa" style="white-space: nowrap;">const
void *kfaddr</var>, <var class="Fa" style="white-space: nowrap;">void
*kdaddr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>, <var class="Fa" style="white-space: nowrap;">size_t
*done</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">copyinstr</code>(<var class="Fa" style="white-space: nowrap;">const
void *uaddr</var>, <var class="Fa" style="white-space: nowrap;">void
*kaddr</var>, <var class="Fa" style="white-space: nowrap;">size_t len</var>,
<var class="Fa" style="white-space: nowrap;">size_t *done</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">copy</code> functions are designed to copy
contiguous data from one address space to another.</p>
<p class="Pp" id="copystr"><a class="permalink" href="#copystr"><code class="Fn">copystr</code></a>()
is deprecated and should be replaced with <a class="Xr">strlcpy(9)</a>. It
will be removed from <span class="Ux">FreeBSD 13</span>.</p>
<p class="Pp" id="copyin">The
<a class="permalink" href="#copyin"><code class="Fn">copyin</code></a>() and
<code class="Fn">copyin_nofault</code>() functions copy
<var class="Fa">len</var> bytes of data from the user-space address
<var class="Fa">uaddr</var> to the kernel-space address
<var class="Fa">kaddr</var>.</p>
<p class="Pp" id="copyout">The
<a class="permalink" href="#copyout"><code class="Fn">copyout</code></a>()
and
<a class="permalink" href="#copyout_nofault"><code class="Fn" id="copyout_nofault">copyout_nofault</code></a>()
functions copy <var class="Fa">len</var> bytes of data from the kernel-space
address <var class="Fa">kaddr</var> to the user-space address
<var class="Fa">uaddr</var>.</p>
<p class="Pp" id="copyin_nofault">The
<a class="permalink" href="#copyin_nofault"><code class="Fn">copyin_nofault</code></a>()
and
<a class="permalink" href="#copyout_nofault~2"><code class="Fn" id="copyout_nofault~2">copyout_nofault</code></a>()
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.</p>
<p class="Pp" id="copystr~2">The
<a class="permalink" href="#copystr~2"><code class="Fn">copystr</code></a>()
function copies a NUL-terminated string, at most <var class="Fa">len</var>
bytes long, from kernel-space address <var class="Fa">kfaddr</var> to
kernel-space address <var class="Fa">kdaddr</var>. The number of bytes
actually copied, including the terminating NUL, is returned in
<var class="Fa">*done</var> (if <var class="Fa">done</var> is
<span class="No">non-</span><code class="Dv">NULL</code>).</p>
<p class="Pp" id="copyinstr">The
<a class="permalink" href="#copyinstr"><code class="Fn">copyinstr</code></a>()
function copies a NUL-terminated string, at most <var class="Fa">len</var>
bytes long, from user-space address <var class="Fa">uaddr</var> to
kernel-space address <var class="Fa">kaddr</var>. The number of bytes
actually copied, including the terminating NUL, is returned in
<var class="Fa">*done</var> (if <var class="Fa">done</var> is
<span class="No">non-</span><code class="Dv">NULL</code>).</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">The <code class="Nm">copy</code> functions return 0 on success.
All but <code class="Fn">copystr</code>() return
<code class="Er">EFAULT</code> if a bad address is encountered. The
<code class="Fn">copyin_nofault</code>() and
<code class="Fn">copyout_nofault</code>() functions return
<code class="Er">EFAULT</code> if a page fault occurs. The
<code class="Fn">copystr</code>() and <code class="Fn">copyinstr</code>()
functions return <code class="Er">ENAMETOOLONG</code> if the string is
longer than <var class="Fa">len</var> bytes.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">fetch(9)</a>, <a class="Xr">store(9)</a></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">May 11, 2020</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
