# The "m" Package

These routines are meant to provide a better memory allocation service than the malloc(3) call. The supplied allocation and deallocation routines perform periodic checks to see if array boundaries have been overrun. A set of memory manipulation and error message routines are also provided in this package.

Library: karma
Link With: -lkarma

#### Functions

m_test_access | Test if a block of memory is accessible.
m_alloc | Allocate Virtual Memory.
m_alloc_no_checks | Allocate Virtual Memory.
m_free | Free Virtual Memory.
m_abort | Print memory error notification message and abort.
m_verify_memory_integrity | Periodically verify memory integrity.
m_get_total_allocated | Get total number of bytes currently allocated.
m_trap_allocations | Trap memory allocations within a certain range and abort.
m_clear | Clear a block of memory
m_calloc | Allocate Virtual Memory and initialise with zeros.
m_free2 | Free Virtual Memory.
m_copy | Copy a block of memory.
m_copy_blocks | Copy multiple blocks of data.
m_copy_and_swap_blocks | Copy and byte-swap multiple blocks of data.
m_fill | Fill memory blocks with a specified value.
m_cmp | Compare two blocks of memory.
m_dup | Duplicate a block of memory into a freshly allocated block.
m_alloc_scratch | Allocate a block of scratch memory.
m_free_scratch | Free the scratch memory.
m_free_and_clear_pointer | Free and clear pointer to a pointer.
m_error_notify | Print memory error notification message.
m_map_fd | Map a file descriptor
m_unmap | Unmap a region of memory.
m_map_test | Test if memory mapping is supported.
m_shm_test_if_available | Test if shared memory available.
m_shm_alloc | Allocate a shared memory segment.
m_shm_delete | Delete a shared memory segment.
m_shm_attach | Attach a shared memory segment to the process address space.
m_shm_detach | Detach a shared memory segment from the process address space.

#### Tables

m_ENVIRONMENT | List of environment variables

## Functions

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag m_test_access (void *start, uaddr size, flag write)

Test if a block of memory is accessible.

Parameters:

- start : The starting address of the memory block.
- size : The size (in bytes) of the memory block.
- write : If TRUE a write test is performed in addition to a read test. This will temporarily change the contents of the memory block. The contents will be restored. If FALSE, only a read test is performed.

Returns: TRUE if the all requested tests succeeded, else FALSE if any test failed.
Multithreading Level: Unsafe
Note:

- The SIGSEGV signal handler is temporarily changed.
- The sigsetjmp(3) and siglongjmp(3) functions are used.
- Since this function makes calls to the Operating System, frequent use may degrade performance.

void * m_alloc (uaddr size)

Allocate Virtual Memory.

Parameters:

- size : The number of bytes to allocate.

Returns: A pointer to the memory on success, else NULL.
Multithreading Level: Safe under POSIX threads.
Note:

- If the environment variable "M_ALLOC_DEBUG" is set to "TRUE" then the routine will print allocation debugging information.
- If the environment variable "M_ALLOC_FAST" is set to "TRUE" then NO periodic integrity check of memory is performed and no debugging
- The "M_ALLOC_MAX_CHECK_INTERVAL" environment variable controls the maximum interval between integrity checks.
- If the environment variable "M_ALLOC_ABORT" is set to "TRUE" then any memory error will cause the programme to abort.

#### EXPERIMENTAL FUNCTION: subject to change without notice

void * m_alloc_no_checks (uaddr size)

Allocate Virtual Memory.

Parameters:

- size : The number of bytes to allocate.

Returns: A pointer to the memory on success, else NULL.
Multithreading Level: Safe under POSIX threads.
Note:

- Periodic memory bounds checks are not performed.
- If the environment variable "M_ALLOC_DEBUG" is set to "TRUE" then the routine will print allocation debugging information.
- If the environment variable "M_ALLOC_FAST" is set to "TRUE" then NO periodic integrity check of memory is performed and no debugging
- The "M_ALLOC_MAX_CHECK_INTERVAL" environment variable controls the maximum interval between integrity checks.
- If the environment variable "M_ALLOC_ABORT" is set to "TRUE" then any memory error will cause the programme to abort.

void m_free (void *ptr)

Free Virtual Memory.

Parameters:

- ptr : The start of a previously allocated block of memory to be freed.

Returns: Nothing.
Multithreading Level: Safe.
Note:

- If the environment variable "M_ALLOC_DEBUG" is set to "TRUE" then the routine will print deallocation debugging information.

void m_abort (char *name, char *reason)

Print memory error notification message and abort.

Parameters:

- function_name : The name of the function requesting the memory.
- reason : The reason for the memory allocation.

Returns: Nothing. The process aborts.
Multithreading Level: Unsafe

unsigned int m_verify_memory_integrity (flag force)

Periodically verify memory integrity.

Parameters:

- force : If TRUE, the check is forced, else the check is made periodically.

Returns: The number of corrupted blocks.
Multithreading Level: Safe.

#### EXPERIMENTAL FUNCTION: subject to change without notice

uaddr m_get_total_allocated ()

Get total number of bytes currently allocated.

Parameters:

This function takes no parameters

Returns: The number of bytes allocated.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void m_trap_allocations (uaddr min, uaddr max)

Trap memory allocations within a certain range and abort.

Parameters:

- min : Allocations less than this size will not be trapped.
- max : Allocations equal to or greater than this size will not be trapped.

Returns: Nothing.
Multithreading Level: Unsafe

void m_clear (void *ptr, uaddr length)

Clear a block of memory

Parameters:

- ptr : The memory block to clear.
- length : The length of the block (in bytes) to clear. If this is less than 1 the routine does nothing. This is effective as a no-op.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

- The memory is cleared in long integers and chars.

void * m_calloc (uaddr size)

Allocate Virtual Memory and initialise with zeros.

Parameters:

- size : The number of bytes to allocate.

Returns: A pointer to the memory on success, else NULL.
Multithreading Level: Safe under POSIX threads.

#### EXPERIMENTAL FUNCTION: subject to change without notice

void m_free2 (void *ptr)

Free Virtual Memory.

Parameters:

- ptr : The start of a previously allocated block of memory to be freed. This may be NULL.

Returns: Nothing.
Multithreading Level: Safe.
Note:

- If the environment variable "M_ALLOC_DEBUG" is set to "TRUE" then the routine will print deallocation debugging information.

void m_copy (void *dest, CONST void *source, uaddr length)

Copy a block of memory.

Parameters:

- dest : The destination block of memory.
- source : The source block of memory.
- length : The number of bytes to transfer. If this is zero, it is permissable for source and dest to be NULL.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

- The routine copies long integers and chars.

void m_copy_blocks (void *dest, CONST void *source, unsigned int dest_stride, unsigned int source_stride, unsigned int block_size, unsigned int num_blocks)

Copy multiple blocks of data.

Parameters:

- dest : The destination for the first block copy.
- source : The source for the first block copy.
- dest_stride : The spacing (in bytes) between destintion blocks.
- source_stride : The spacing (in bytes) between source blocks.
- block_size : The size of each block (in bytes).
- num_blocks : The number of blocks to copy.

Returns: Nothing.
Multithreading Level: Unsafe

void m_copy_and_swap_blocks (void *dest, CONST void *source, uaddr dest_stride, uaddr source_stride, uaddr block_size, uaddr num_blocks)

Copy and byte-swap multiple blocks of data.

Parameters:

- dest : The destination for the first block copy.
- source : The source for the first block copy. If this is NULL or the same as dest the swap is performed in-situ, and source_stride is ignored
- dest_stride : The spacing (in bytes) between destintion blocks.
- source_stride : The spacing (in bytes) between source blocks.
- block_size : The size of each block (in bytes).
- num_blocks : The number of blocks to copy and swap.

Returns: Nothing.
Multithreading Level: Unsafe

void m_fill (void *dest, uaddr stride, CONST void *source, uaddr size, unsigned int num)

Fill memory blocks with a specified value.

Parameters:

- dest : The destination.
- stride : The stride (in bytes) of destination blocks.
- source : The fill block.
- size : The size (in bytes) of the fill value block.
- num : The number of destination blocks to fill.

Returns: Nothing.
Multithreading Level: Unsafe

flag m_cmp (CONST void *block1, CONST void *block2, uaddr length)

Compare two blocks of memory.

Parameters:

- block1 : The first memory block.
- block2 : The second memory block.
- length : The number of bytes to compare.

Returns: TRUE if the blocks are equal, else FALSE.
Multithreading Level: Unsafe
Note:

- The routine compares long integers and chars.

void * m_dup (CONST void *original, uaddr size)

Duplicate a block of memory into a freshly allocated block.

Parameters:

- original : The original block of memory.
- size : The size in bytes of the block.

Returns: A pointer to a freshly allocated block which contains identical data as the orginal on success, else NULL.
Multithreading Level: Unsafe

void * m_alloc_scratch (uaddr size, char *function_name)

This routine will allocate a block of scratch memory, which may be re-used by many different routines. The block is reserved until a call is made to m_free_scratch.

Parameters:

- size : The minimum size in bytes of the scratch block.
- function_name : If this is not NULL and a failure occurs, the string is printed and the process aborts.

Returns: A pointer on success to a dynamically allocated block of memory which is valid until the next call to this routine, else NULL.
Multithreading Level: Unsafe

void m_free_scratch ()

Free the scratch memory.

Parameters:

This function takes no parameters

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void m_free_and_clear_pointer (void *ptr)

Free and clear pointer to a pointer.

Parameters:

- ptr : A pointer to a pointer to a block of memory. The block of memory is freed and NULL is written to the memory block pointer. This may be NULL, and the memory block pointer may also be NULL.

Returns: Nothing.
Multithreading Level: Unsafe

void m_error_notify (char *function_name, char *purpose)

Print memory error notification message.

Parameters:

- function_name : The name of the function requesting the memory.
- purpose : The purpose for the memory allocation.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void * m_map_fd (int *fd, uaddr size, flag writable, flag update_on_write, flag warn_unsupported)

Map a file descriptor

Parameters:

- fd : A pointer to the file descriptor to map. If the descriptor is less than 0 then an appropriately chosen file is opened and the newly opened file descriptor is written here.
- size : The size of the region to map.
- writable : If the mapped pages are to be writable, this must be TRUE. If this is FALSE and the memory pages are written to, a segmentation fault occurs.
- update_on_write : If the disc file should be updated when the memory pages are written to, this must be TRUE. If this is FALSE, then a write to a memory page causes the page to be copied into swap space and the process retains a private copy of the page from this point on.
- warn_unsupported : If TRUE, attempts to use unsupported features will generate a warning message.

Returns: A pointer to the mapped file on success, else NULL.
Multithreading Level: Unsafe
Note:

- If update_on_write is FALSE and writable is TRUE, then some systems require the allocation of normal virtual memory equal to the size of the disc file at the time of mapping, while others will dynamically allocate memory from swap space as pages are written into. In the latter case, some systems will cause a segmentation fault if swap space is exhausted, while other systems wait for space to be freed.

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag m_unmap (void *addr, uaddr size)

Unmap a region of memory.

Parameters:

- addr : The start address of the region.
- size : The size of the region.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag m_map_test ()

Test if memory mapping is supported.

Parameters:

This function takes no parameters

Returns: TRUE if supported, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag m_shm_test_if_available ()

Test if shared memory available.

Parameters:

This function takes no parameters

Returns: TRUE if shared memory is available, else FALSE.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

int m_shm_alloc (uaddr size, mode_t prot)

Allocate a shared memory segment.

Parameters:

- size : The size in bytes of the segment.
- prot : The protection mask.

Returns: The shared memory ID on success, else -1.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void m_shm_delete (int shmid)

Delete a shared memory segment.

Parameters:

- shmid : The ID of the shared memory segment to mark for deletion.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

void * m_shm_attach (int shmid, flag reattach, flag writable)

Attach a shared memory segment to the process address space.

Parameters:

- shmid : The ID of the shared memory segment to mark for deletion.
- reattach : If TRUE an existing attachment of the segment is returned, if available.
- writable : If TRUE the segment is given write access. This is ignored if reattach is TRUE.

Returns: The address at which the segment was attached on success, else NULL.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag m_shm_detach (void *addr)

Detach a shared memory segment from the process address space.

Parameters:

- addr : The address of the segment, as returned by m_shm_attach.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

## Tables

m_ENVIRONMENT List of environment variables

Variable | Meaning
M_ALLOC_MAX_CHECK_INTERVAL | Interval between consistency checks
M_ALLOC_DEBUG | If TRUE, enable verbose debugging
M_ALLOC_FAST | If TRUE, skip consistency checks
M_ALLOC_ABORT | If TRUE, memory errors cause an abort

Back to Karma Home Page