Next: , Previous: Memory Deallocation, Up: Virtual Memory Interface


5.3 Data Transfer

— Function: kern_return_t vm_read (vm_task_t target_task, vm_address_t address, vm_size_t size, vm_offset_t *data, mach_msg_type_number_t *data_count)

The function vm_read allows one task's virtual memory to be read by another task. The target_task is the task whose memory is to be read. address is the first address to be read and must be on a page boundary. size is the number of bytes of data to be read and must be an integral number of pages. data is the array of data copied from the given task, and data_count is the size of the data array in bytes (will be an integral number of pages).

Note that the data array is returned in a newly allocated region; the task reading the data should vm_deallocate this region when it is done with the data.

The function returns KERN_SUCCESS if the memory was successfully read, KERN_INVALID_ADDRESS if an invalid or non-allocated address was specified or there was not size bytes of data following the address, KERN_INVALID_ARGUMENT if the address does not start on a page boundary or the size is not an integral number of pages, KERN_PROTECTION_FAILURE if the address region in the target task is protected against reading and KERN_NO_SPACE if there was not enough room in the callers virtual memory to allocate space for the data to be returned.

— Function: kern_return_t vm_write (vm_task_t target_task, vm_address_t address, vm_offset_t data, mach_msg_type_number_t data_count)

The function vm_write allows a task to write to the virtual memory of target_task. address is the starting address in task to be affected. data is an array of bytes to be written, and data_count the size of the data array.

The current implementation requires that address, data and data_count all be page-aligned. Otherwise, KERN_INVALID_ARGUMENT is returned.

The function returns KERN_SUCCESS if the memory was successfully written, KERN_INVALID_ADDRESS if an invalid or non-allocated address was specified or there was not data_count bytes of allocated memory starting at address and KERN_PROTECTION_FAILURE if the address region in the target task is protected against writing.

— Function: kern_return_t vm_copy (vm_task_t target_task, vm_address_t source_address, vm_size_t count, vm_offset_t dest_address)

The function vm_copy causes the source memory range to be copied to the destination address. The source and destination memory ranges may overlap. The destination address range must already be allocated and writable; the source range must be readable.

vm_copy is equivalent to vm_read followed by vm_write.

The current implementation requires that address, data and data_count all be page-aligned. Otherwise, KERN_INVALID_ARGUMENT is returned.

The function returns KERN_SUCCESS if the memory was successfully written, KERN_INVALID_ADDRESS if an invalid or non-allocated address was specified or there was insufficient memory allocated at one of the addresses and KERN_PROTECTION_FAILURE if the destination region was not writable or the source region was not readable.