Mbedthis Portable Runtime C API
Detailed Description
Mbedthis Portable Runtime (MPR) API.
The MPR provides a cross-platform embeddable set of management and communication services that form a portable run-time core. It provides management for logging, lists, memory, sockets, tasks, timers, threads. It also provides a foundation of safe routines for secure programming, that prevent help minimize buffer overflows and other security threats. The MPR APIs provide constants, structure and class definitions and can be used in both C and C++ programs.
The Standard MPR types are: bool, char, uchar, short, ushort, int, uint, long, ulong, int64, uint64, float, double, MprStr
To differentiate between "C" strings that are dynamically allocated and plain C pointers, we use Str for dynamically allocated strings. In classes, Str means the class owns the storage for the string. When used for the return value or parameter of a method, it means the caller must free the memory using mprFree.
APIs that return dynamically allocated strings require the caller to pass a pointer to hold the allocated buffer as a parameter. APIs that require a user supplied buffer, always require a buffer maximum length parameter. APIs that return statically allocated strings will return them as a return value.
- Warning:
- Most of these APIs are not thread-safe. Be careful if you modify or delete the underlying data while accessing the resource from another thread.
Define Documentation
| #define MPR_MAX_FNAME 128 |
|
|
|
Reasonable size of a file name.
Reasonable length of a file name used by the product. Use where you know the expected file name and it is certain to be less than this limit. |
|
|
Reasonable max path name.
Maximum length of a file path name. Reduced from the system maximum to save memory space. |
Function Documentation
| int mprAddToArray |
( |
MprArray * |
array, |
|
|
void * |
item |
|
) |
|
|
|
|
- Synopsis:
- Add an item to an array
- Overview:
- Add the specified item to the array. The array must have been previously created via mprCreateArray. The array will grow as required to store the item.
- Parameters:
-
| array | Array pointer returned from mprCreateArray. |
| item | Pointer to item to store. |
- Returns:
- Returns a positive integer array index for the inserted item. If the item cannot be inserted due to a memory allocation failure, -1 is returned.
- Stability classification:
- Evolving.
- Library:
- libappweb
- See also:
- mprCreateArray, mprDestroyArray, mprRemoveFromArray
|
|
|
- Synopsis:
- Create an array
- Overview:
- Creates an empty array. MprArray's can store generic pointers and automatically grow as required when items are added to the array. Callers should invoke mprDestoryArray when finished with the array to release allocated storage.
- Returns:
- Returns a pointer to the array.
- Stability classification:
- Evolving.
- Library:
- libappweb
- See also:
- mprAddToArray, mprDestroyArray, mprRemoveFromArray
|
| int mprCreateMemHeap |
( |
char * |
userBuf, |
|
|
int |
initialSize, |
|
|
int |
limit |
|
) |
|
|
|
|
- Synopsis:
- Initialize the memory heap.
- Overview:
- Initialize the memory heap. The Mbedthis malloc subsystem offers several benefits:
- It can pre-allocate memory to ensure memory allocations do not fail
- It can allocate memory out of a static user buffer so that no dynamic memory allocation calls will be made at run-time. Ideal for VxWorks which tends to fragment memory with high dynamic memory loads.
- It can impose memory allocation limits so that other programs are not compromised.
- A memory handler is called on memory allocation failures.
- Parameters:
-
| userBuf | NULL to dynamically allocate memory from the operating system. Set to a valid buffer of length size and memory will be allocated out of that buffer. Ideal for embedded systems such as VxWorks to ensure memory allocations cannot fail. |
| initialSize | Define the size of the supplied user buffer, or if userBuf is NULL, it defines the initial size of dynamic memory to allocate. |
| limit | Specify the maximum amount of dynamic memory to allocate. |
- Returns:
- Returns zero if successful. Otherwise a negative MPR error code.
- Stability classification:
- Evolving.
- Library:
- libappweb
- See also:
- mprMalloc, mprFree
|
| void mprDestroyArray |
( |
MprArray * |
array |
) |
|
|
|
|
- Synopsis:
- Destroy an array
- Overview:
- Destroys an array previously created via mprCreateArray. The array does not have to be empty prior to invoking this function.
- Returns:
- Returns a pointer to the array.
- Stability classification:
- Evolving.
- Library:
- libappweb
- See also:
- mprAddToArray, mprCreateArray, mprRemoveFromArray
|
| void mprFree |
( |
void * |
ptr |
) |
|
|
|
|
- Synopsis:
- Safe replacement for free.
- Overview:
- mprFree should be used to free memory allocated by mprMalloc, mprRealloc or mprCalloc.
- Parameters:
-
| ptr | Memory to free. If NULL, take no action. |
- Remarks:
- mprFree can reduce the overall application code size by allowing the memory block ptr to be NULL.
- See also:
- mprMalloc, mprCalloc, mprRealloc
|
| cchar* mprGetCurrentThreadName |
( |
|
) |
|
|
|
|
- Synopsis:
- Get the current thread name.
- Overview:
- Return a descriptive name for the current thread.
- Returns:
- Returns a pointer to the current threads name. Callers should not free this string.
- See also:
- mprMalloc, mprCalloc, mprRealloc
|
| void* mprMalloc |
( |
uint |
size |
) |
|
|
|
|
- Synopsis:
- Safe replacement for malloc.
- Overview:
- mprMalloc wraps the standard malloc or if BLD_FEATURE_MALLOC is enabled, it will replace malloc with a fast, deterministic embedded memory allocator that is more deterministic with regard to
|
| void* mprRealloc |
( |
void * |
ptr, |
|
|
uint |
size |
|
) |
|
|
|
|
- Synopsis:
- Safe replacement for realloc
- Overview:
- mprRealloc should be used to reallocate memory blocks that have been allocated with mprMalloc or mprStrdup.
- Parameters:
-
| ptr | Memory to reallocate. If NULL, call malloc. |
| size | New size of the required memory block. |
- Returns:
- Returns a pointer to the newly allocated memory block.
- Remarks:
- Do not mix calls to realloc and mprRealloc.
|
| int mprRemoveFromArray |
( |
MprArray * |
array, |
|
|
int |
index |
|
) |
|
|
|
|
- Synopsis:
- Remove the nominated
- Overview:
- Removes the element specified by index, from the array. The array index is provided by mprAddToArray.
- Returns:
- Returns the number of remaining elements in the array. Returns zero when the array is empty.
- Stability classification:
- Evolving.
- Library:
- libappweb
- See also:
- mprAddToArray, mprCreateArray, mprDestroyArray
|
| void mprSetDebugMode |
( |
bool |
on |
) |
|
|
|
|
- Synopsis:
- Turn on debug mode.
- Overview:
- Debug mode disables timeouts and timers. This makes debugging much easier.
- Parameters:
-
| on | TRUE to disable debugging. |
- Stability classification:
- Evolving.
- Library:
- libappweb
|
| char* mprStrdup |
( |
const char * |
str |
) |
|
|
|
|
- Synopsis:
- Safe replacement for strdup
- Overview:
- mprStrdup() should be used as a replacement for strdup wherever possible. It allows the strdup to be copied to be NULL, in which case it will allocate an empty string.
- Parameters:
-
| str | Pointer to string to duplicate. If str is NULL, allocate a new string containing only a trailing NULL character. |
- Returns:
- Returns an allocated string including trailing null.
- Remarks:
- Memory allocated via mprStrdup() must be freed via mprFree().
- See also:
- mprFree, mprMalloc, mprRealloc, mprCalloc
|
|
|
