This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

The mapping and unmapping of memory in another process

Overview

This feature allows for an application to cause memory in another process' address space to be mapped or unmapped. The mmap_peer() and munmap_peer() funcations perform a mmap() and munmap() on behalf of the process specified by pid.

Configuration

Using mmap_peer()

The syntax for the mmap_peer() function is:

void * mmap_peer( pid_t pid,
             void *addr,
             size_t len,
             int prot,
             int flags,
	     int fd,
             off_t off );

void * mmap64_peer( pid_t pid,
             void *addr,
             size_t len,
             int prot,
             int flags,
	     int fd,
             off_t off );

Description

The mmap_peer() function maps a region within the object of the specified process id beginning at off and continuing for len into the address space, and returns the location.

The address returned by mmap_peer() is valid in the context of the process pid only, and the those that are allowed to do this are the root and processes with the same userid as pid.

addr

NULL, or a pointer to where you want the object to be mapped in the calling process's address space.

len

The number of bytes to map into the specified process' address space. Note that this value can't be 0.

pid

The id of the process for which you want to map its memory.

prot

The access capabilities that you want to use for the memory region being mapped. You can combine at least the following protection bits, as defined in <sys/mman.h>:

prot_exec -- the region can be executed.
prot_nocache -- disable caching of the region (e.g. so it can be used to access dual-ported memory).
prot_none -- the region can't be accessed.
prot_read -- the region can be read.
prot_write -- the region can be written.

flags

Flags that specify further information about handling the mapped region. For detailed information about the flags, see the mmap() documentation in the library reference.

fd

The file descriptor for a shared memory object, or nofd if you're mapping physical memory.

off

The offset into shared memory of the location that you want to start mapping.

Returns

The address of the mapped-in object, or MAP_FAILED if an error occurred (errno is set). For additional information, see errno in the Library Reference.

Errors

In addition to the errno codes set by the mmap() and munmap() functions, the following can be set:

ESRCH: The process pid doesn't exist or is terminating.
EPERM: The caller doesn't have permission.

Example

The following example forks into parent and child process, and the parent process will wait for the child process to terminate. The child process does the following:

performs mmap_peer() and stores the returned address
checks to see if the mmap_peer() function failed
performs munmap_peer() and verifies the return value

#include <stdio.h>
#include <string.h>
#include <fcntl.h>
#include <errno.h>
#include <stdlib.h>
#include <process.h>
#include <sys/mman.h>


int main(int argc, char *argv[])
{
 pid_t pid;
 pid_t parent_pid;
 char buff[256];
 const int mmap_len=4096;

 parent_pid=getpid();
 
 pid = fork();
 assert( pid != -1);

 if( pid == 0 ) {		/* This is the child process */
 	void *ptr, *old_ptr;
 	int ret;
 	int failed;

	failed=0;

	old_ptr=mmap_peer( parent_pid, 0, mmap_len, PROT_READ|PROT_WRITE, MAP_SHARED, NOFD, 0);
 	if(old_ptr==MAP_FAILED) {
		SPRNT( buff, sizeof(buff), "mmap_peer failed (errno %d)", errno);
		failed++;
	}
	if(!failed){
		ret=munmap_peer(parent_pid, old_ptr, mmap_len);
		if(ret==-1){
			SPRNT( buff, sizeof(buff), "munmap_peer failed (errno %d)", errno);
		failed++;
		}
	}
 }

	} /* if( pid == 0 ) */
 else {   	/* This is the parent process */
		wait(NULL);
      }
     
return EXIT_SUCCESS;
}

Using munmap_peer()

The syntax for the munmap_peer() function is:

int 
munmap_peer(pid_t pid,
             void *addr,
             size_t len);

Description

The munmap_peer() function removes any mappings for pages in the address range for the specified process starting at addr and continuing for len bytes, rounded up to the next multiple of the page size. Subsequent references to these pages cause a SIGSEGV signal to be set on the process.

If there are no mappings in the specified address range, then munmap_peer() has no effect.

addr: A pointer to where you want to unmap the object in the specified process' address space. addr is the beginning of the range of addresses that you want to unmap.
len: The number of bytes to unmap into the specified process' address space. Note that length of the range of addresses can't be 0.
pid: The id of the process for which you want to unmap its memory.

Returns

0: Success.
-1: Failure; errno is set. For additional information, see errno in the Library Reference.

Errors

EINVAL: The addresses in the specified range are outside the range allowed for the address space of a process.
ENOMEM: The memory manager fails to allocate memory to handle a user's munmap_peer() request. This allocation of memory is necessary for internal structures to represent the new state of mapped memory.