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
Tables
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
Contact: Richard Gooch
Web Development: Ariel Internet Services