osfmk/man/vm_region.html

   1 <h2>vm_region</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Return description of a virtual memory region.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   vm_region</strong>
   8                  <strong>(vm_task_t</strong>                    <var>target_task</var>,
   9                   <strong>vm_address_t</strong>                     <var>address</var>,
  10                   <strong>vm_size_t</strong>                           <var>size</var>,
  11                   <strong>vm_region_flavor_t</strong>                <var>flavor</var>,
  12                   <strong>vm_region_info_t</strong>                    <var>info</var>,
  13                   <strong>mach_msg_type_number_t</strong>        <var>info_count</var>,
  14                   <strong>memory_object_name_t</strong>         <var>object_name</var><strong>);</strong>
  15 </pre>
  16 <h3>PARAMETERS</h3>
  17 <dl>
  18 <p>
  19 <dt> <var>target_task</var>
  20 <dd>
  21 [in task send right]
  22 The port for the task whose address space contains
  23 the region.
  24 <p>
  25 <dt> <var>address</var>
  26 <dd>
  27 [pointer to in/out scalar]
  28 The address at which to start looking for a
  29 region.  The function returns the starting address actually used.
  30 <p>
  31 <dt> <var>size</var>
  32 <dd>
  33 [out scalar]
  34 The number of bytes in the located region.  The number
  35 converts to an integral number of virtual pages.
  36 <p>
  37 <dt> <var>flavor</var>
  38 <dd>
  39 [in scalar]
  40 The type of information to be returned.  Valid values are:
  41 <dl>
  42 <p>
  43 <dt> <strong>VM_REGION_BASIC_INFO</strong>
  44 <dd>
  45 Basic information about the region (size, inheritance, etc.).
  46 This information is declared by the
  47      <strong>vm_region_basic_info</strong> structure.
  48 </dl>
  49 <p>
  50 <dt> <var>info</var>
  51 <dd>
  52 [out structure]
  53 Returned region information.
  54 <p>
  55 <dt> <var>info_count</var>
  56 <dd>
  57 [in/out scalar]
  58 On input, the maximum size of the buffer; on output, the
  59 size returned (in natural-sized units).
  60 <p>
  61 <dt> <var>object_name</var>
  62 <dd>
  63      This parameter is no longer used.
  64 </dl>
  65 <h3>DESCRIPTION</h3>
  66 <p>
  67 The <strong>vm_region</strong> function returns information on a region
  68 within the specified
  69 task's address space.
  70 The function begins looking at <var>address</var> and continues until it
  71 finds an allocated
  72 region.  If the input address is within a region, the function
  73 uses the start of that
  74 region.  The starting address for the located region is returned in <var>address</var>.
  75 <h3>NOTES</h3>
  76 <p>
  77 This interface is machine word length specific because of the virtual address
  78 parameter.
  79 <h3>RETURN VALUES</h3>
  80 <dl>
  81 <p>
  82 <dt> <strong>KERN_INVALID_ADDRESS</strong>
  83 <dd>
  84 There is no region at or beyond the specified starting address.
  85 </dl>
  86 <h3>RELATED INFORMATION</h3>
  87 <p>
  88 Functions:
  89 <a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
  90 <a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,
  91 <a href="vm_inherit.html"><strong>vm_inherit</strong></a>,
  92 <a href="vm_protect.html"><strong>vm_protect</strong></a>,
  93 <a href="vm_behavior_set.html"><strong>vm_behavior_set</strong></a>.
  94 <p>
  95 Data Structures:
  96 <a href="vm_region_basic_info.html"><strong>vm_region_basic_info</strong></a>.