osfmk/man/vm_wire.html

   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]
  20 The control port for the host for which
  21 information is to be obtained.
  22 <p>
  23 <dt> <var>target_task</var>
  24 <dd>
  25 [in task send right]
  26 The port for the task whose address space contains
  27 the region.
  28 <p>
  29 <dt> <var>address</var>
  30 <dd>
  31 [in scalar]
  32 The starting address for the region.
  33 <p>
  34 <dt> <var>size</var>
  35 <dd>
  36 [in scalar]
  37 The number of bytes in the region.
  38 <p>
  39 <dt> <var>wired_access</var>
  40 <dd>
  41 [in scalar]
  42 The pageability of the region. The following values cause
  43 the 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>
  51 The 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>
  58 The <strong>vm_wire</strong> function sets the pageability privileges
  59 for a region within the
  60 specified task's address space.  <var>wired_access</var> specifies the types
  61 of accesses to
  62 the memory region which must not suffer from (internal) faults
  63 of any kind after
  64 this call returns.  A non-null <var>wired_access</var> value indicates that
  65 the page is to be
  66 "wired" into memory; a null value indicates "un-wiring".  The kernel maintains
  67 for the region a count of the number of times the region is wired.  A page is
  68 wired into physical memory if any task accessing it has a non-zero wired count
  69 for the page.
  70 <p>
  71 The 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
  74 rounding to virtual page boundaries, the amount of memory affected may be
  75 greater than <var>size</var>.  Use <strong>host_page_size</strong> to find the current
  76 virtual page size.
  77 <h3>NOTES</h3>
  78 <p>
  79 This interface is machine word length specific because of the virtual address
  80 parameter.
  81 <h3>RETURN VALUES</h3>
  82 <dl>
  83 <p>
  84 <dt> <strong>KERN_INVALID_ADDRESS</strong>
  85 <dd>
  86 The address is illegal or specifies a non-allocated region.
  87 </dl>
  88 <h3>RELATED INFORMATION</h3>
  89 <p>
  90 Functions:
  91 <a href="thread_wire.html"><strong>thread_wire</strong></a>.