# ControlMem

Controls memory permissions and ownership.

### Synopsis

`Err ControlMem( void *p, int32 size, int32 cmd, Item task )`

### Description

When a task allocates memory, it becomes the owner of that memory. Other tasks cannot write to the memory unless they are given permission by its owner. A task can give another task permission to write to one or more of its memory pages, revoke write permission that was previously granted, or transfer ownership of memory to another task or the system by calling `ControlMem()`.

Each page of memory has a control status that specifies which task owns the memory and which tasks can write to it. Calls to `ControlMem()` change the control status for entire pages. If the p and size arguments (which specify the memory to change) specify any part of a page, the changes apply to the entire page.

A task can grant write permission for a page that it owns (or for some number of contiguous pages) to any number of tasks. To accomplish this, the task must make a separate call to `ControlMem()` for each task that is to be granted write permission.

A task that calls `ControlMem()` must own the memory whose control status it is changing, with one exception: A task that has write access to memory it doesn't own can relinquish its write access (by using MEMC_NOWRITE as the value of the cmd argument). If a task transfers ownership of memory it still retains write access.

### Arguments

p
  A pointer to the memory whose control status to change.

size
  The amount of memory for which to change the control status, in bytes. If the size and p arguments specify any part of a page, the control status is changed for the entire page.

cmd
  A constant that specifies the change to be made to the control status; possible values are listed below.

task
  The item-number task for which to change the control status or zero for global changes (see "Notes").

The possible values of "cmd" are:

MEMC_OKWRITE
  Grants permission to write to this memory to the task specified by the task argument.

MEMC_NOWRITE
  Revokes permission to write to this memory from the task specified by the task argument. If task is 0 revokes write permission for all tasks.

MEMC_GIVE
  If the calling task is the owner of the memory, this transfers ownership of the memory to the task specified by the task argument. If the specified task is 0, it gives the memory back to the system free memory pool.

### Return Value

The procedure returns 0 if the change was successful or an error code (a negative value) if an error occurs. Possible error codes include:

BADITEM
  The task argument does not specify a current task.

ER_Kr_BadMemCmd
  The cmd argument is not one of the valid values.

ER_BadPtr
  The p argument is not a valid pointer to memory.

### Implementation

SWI implemented in kernel folio V20.

### Associated Files

mem.h
  ANSI C Prototype

### Notes

A task can use `ControlMem()` to prevent itself from writing to memory it owns.

A task must own the memory for its I/O buffers.

A task can use `ControlMem()` to return ownership of memory pages to the system, thereby returning them to the system-wide free memory pool. You can do this by using 0 as the value of the task argument.

A task can use `ControlMem()` to unshare or write protect memory from all other tasks. Specify 0 for the task for this to happen.

We would like to support making a piece of memory writable by all other tasks by using task==0 and MEMC_OKWRITE, but this is not implemented yet.

### See Also

``ScavengeMem`(), AllocMemBlocks()`