[apple/xnu.git] / osfmk / man / vm_region.html

<h2>vm_region</h2>\r<hr>\r<p>\r<strong>Function</strong> - Return description of a virtual memory region.\r<h3>SYNOPSIS</h3>\r<pre>\r<strong>kern_return_t   vm_region</strong>\r                 <strong>(vm_task_t</strong>                    <var>target_task</var>,\r                  <strong>vm_address_t</strong>                     <var>address</var>,\r                  <strong>vm_size_t</strong>                           <var>size</var>,\r                  <strong>vm_region_flavor_t</strong>                <var>flavor</var>,\r                  <strong>vm_region_info_t</strong>                    <var>info</var>,\r                  <strong>mach_msg_type_number_t</strong>        <var>info_count</var>,\r                  <strong>memory_object_name_t</strong>         <var>object_name</var><strong>);</strong>\r</pre>\r<h3>PARAMETERS</h3>\r<dl>\r<p>\r<dt> <var>target_task</var> \r<dd>\r[in task send right]\rThe port for the task whose address space contains \rthe region.\r<p>\r<dt> <var>address</var> \r<dd>\r[pointer to in/out scalar]\rThe address at which to start looking for a\rregion.  The function returns the starting address actually used.\r<p>\r<dt> <var>size</var> \r<dd>\r[out scalar]\rThe number of bytes in the located region.  The number \rconverts to an integral number of virtual pages.\r<p>\r<dt> <var>flavor</var> \r<dd>\r[in scalar]\rThe type of information to be returned.  Valid values are:\r<dl>\r<p>\r<dt> <strong>VM_REGION_BASIC_INFO</strong>\r<dd>\rBasic information about the region (size, inheritance, etc.). \rThis information is declared by the\r     <strong>vm_region_basic_info</strong> structure.\r</dl>\r<p>\r<dt> <var>info</var> \r<dd>\r[out structure]\rReturned region information.\r<p>\r<dt> <var>info_count</var> \r<dd>\r[in/out scalar]\rOn input, the maximum size of the buffer; on output, the \rsize returned (in natural-sized units).\r<p>\r<dt> <var>object_name</var> \r<dd>\r     This parameter is no longer used.\r</dl>\r<h3>DESCRIPTION</h3>\r<p>\rThe <strong>vm_region</strong> function returns information on a region\rwithin the specified \rtask's address space.\rThe function begins looking at <var>address</var> and continues until it\rfinds an allocated \rregion.  If the input address is within a region, the function\ruses the start of that \rregion.  The starting address for the located region is returned in <var>address</var>.\r<h3>NOTES</h3>\r<p>\rThis interface is machine word length specific because of the virtual address\rparameter.\r<h3>RETURN VALUES</h3>\r<dl>\r<p>\r<dt> <strong>KERN_INVALID_ADDRESS</strong>\r<dd>\rThere is no region at or beyond the specified starting address.\r</dl>\r<h3>RELATED INFORMATION</h3>\r<p>\rFunctions:\r<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,\r<a href="vm_deallocate.html"><strong>vm_deallocate</strong></a>,\r<a href="vm_inherit.html"><strong>vm_inherit</strong></a>,\r<a href="vm_protect.html"><strong>vm_protect</strong></a>,\r<a href="vm_behavior_set.html"><strong>vm_behavior_set</strong></a>.\r<p>\rData Structures:\r<a href="vm_region_basic_info.html"><strong>vm_region_basic_info</strong></a>.\r