mach_vm_region vs mach_vm_region_recurse

Question

What's the difference between mach_vm_region and mach_vm_region_recurse and in which situations would you use which?

The signature of the declaration of the functions are:

kern_return_t mach_vm_region
(
    vm_map_t target_task,
    mach_vm_address_t *address,
    mach_vm_size_t *size,
    vm_region_flavor_t flavor,
    vm_region_info_t info,
    mach_msg_type_number_t *infoCnt,
    mach_port_t *object_name
);
kern_return_t mach_vm_region_recurse
(
    vm_map_t target_task,
    mach_vm_address_t *address,
    mach_vm_size_t *size,
    natural_t *nesting_depth,
    vm_region_recurse_info_t info,
    mach_msg_type_number_t *infoCnt
);

Which function should I use if I want to...

1. find all valid memory addresses for a process?
2. find all private memory for a process?

Answer 1

The difference is that the vm_region_recurse_64 version allows you to look at the contents of submaps. I won't pretend to be an expert on this topic, but as far as I can see, the most common place where you encounter submaps is when traversing the memory where the frameworks are mapped from the dyld cache (starting at SHARED_REGION_BASE_X86_64 = 0x00007FFF7000000 on x86_64 macs).

vm_region seems to return the submap as a single region.

I think there can be private mappings inside a submap.

Here's an example:

                       00007fff70000000-00007fff76c00000 vm_region
                       00007fff70000000-00007fff76c00000 vm_region_recurse_64    (depth=0, is_submap == TRUE)
                       00007fff7695b000-00007fff76a00000 vm_region_recurse_64 #1 (depth=1, is_submap == FALSE)
                       00007fff76a00000-00007fff76c00000 vm_region_recurse_64 #2 (depth=1, is_submap == FALSE)

And here's how vmstat -interleaved -v reports this:

map                    00007fff70000000-00007fff76c00000 r--/rwx process-only submap
unused split lib       00007fff7695b000-00007fff76999000 system shared library region not used by this process
__DATA                 00007fff76999000-00007fff7699a000 /usr/lib/system/libcompiler_rt.dylib
unused split lib       00007fff7699a000-00007fff769a2000 system shared library region not used by this process
__DATA                 00007fff769a2000-00007fff769a3000 /usr/lib/system/libsystem_notify.dylib
unused split lib       00007fff769a3000-00007fff76a00000 system shared library region not used by this process
unused split lib       00007fff76a00000-00007fff76c00000 system shared library region not used by this process