1<h2>vm_wire</h2>
2<hr>
3<p>
4<strong>Function</strong> - Modify the target region's paging characteristics.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>kern_return_t   vm_wire</strong>
8                <strong>(host_priv_t</strong>                               <var>host</var>,
9                 <strong>vm_task_t</strong>                          <var>target_task</var>,
10                 <strong>vm_address_t</strong>                           <var>address</var>,
11                 <strong>vm_size_t</strong>                                 <var>size</var>,
12                 <strong>vm_prot_t</strong>                         <var>wired_access</var><strong>);</strong>
13</pre>
14<h3>PARAMETERS</h3>
15<dl>
16<p>
17<dt> <var>host</var> 
18<dd>
19[in host-control send right]
20The control port for the host for which
21information is to be obtained.
22<p>
23<dt> <var>target_task</var> 
24<dd>
25[in task send right]
26The port for the task whose address space contains 
27the region.
28<p>
29<dt> <var>address</var> 
30<dd>
31[in scalar]
32The starting address for the region.
33<p>
34<dt> <var>size</var> 
35<dd>
36[in scalar]
37The number of bytes in the region.
38<p>
39<dt> <var>wired_access</var> 
40<dd>
41[in scalar]
42The pageability of the region. The following values cause
43the region to be wired and protected as specified
44(values may be combined):
45<dl>
46<dt> <strong>VM_PROT_READ</strong>
47<dt> <strong>VM_PROT_WRITE</strong>
48<dt> <strong>VM_PROT_execute</strong>
49</dl>
50<p>
51The following value causes the region to be unwired (made pageable):
52<dl>
53<dt> <strong>VM_PROT_NONE</strong>
54</dl>
55</dl>
56<h3>DESCRIPTION</h3>
57<p>
58The <strong>vm_wire</strong> function sets the pageability privileges
59for a region within the 
60specified task's address space.  <var>wired_access</var> specifies the types
61of accesses to 
62the memory region which must not suffer from (internal) faults
63of any kind after 
64this call returns.  A non-null <var>wired_access</var> value indicates that
65the page is to be 
66"wired" into memory; a null value indicates "un-wiring".  The kernel maintains 
67for the region a count of the number of times the region is wired.  A page is 
68wired into physical memory if any task accessing it has a non-zero wired count 
69for the page.
70<p>
71The region starts at the beginning of the virtual page containing
72<var>address</var>; it ends at the end of the virtual page containing 
73<var>address</var> + <var>size</var> - 1.  Because of this 
74rounding to virtual page boundaries, the amount of memory affected may be 
75greater than <var>size</var>.  Use <strong>host_page_size</strong> to find the current 
76virtual page size.
77<h3>NOTES</h3>
78<p>
79This interface is machine word length specific because of the virtual address
80parameter.
81<h3>RETURN VALUES</h3>
82<dl>
83<p>
84<dt> <strong>KERN_INVALID_ADDRESS</strong>
85<dd>
86The address is illegal or specifies a non-allocated region.
87</dl>
88<h3>RELATED INFORMATION</h3>
89<p>
90Functions:
91<a href="thread_wire.html"><strong>thread_wire</strong></a>.
92