< Home < Developers < Development Support < Documentation

## 39 Memory Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 39 Memory Manager Memory Manager Functions MemCardInfo MemCmp MemDebugMode MemHandleCardNo MemHandleDataStorage MemHandleFree MemHandleHeapID MemHandleLock MemHandleNew MemHandleResize MemHandleSetOwner MemHandleSize MemHandleToLocalID MemHandleUnlock MemHeapCheck MemHeapCompact MemHeapDynamic MemHeapFlags MemHeapFreeBytes MemHeapID MemHeapScramble MemHeapSize MemLocalIDKind MemLocalIDToGlobal MemLocalIDToLockedPtr MemLocalIDToPtr MemMove MemNumCards MemNumHeaps MemNumRAMHeaps MemPtrCardNo MemPtrDataStorage MemPtrFree MemPtrHeapID MemPtrNew MemPtrRecoverHandle MemPtrResize MemPtrSetOwner MemPtrSize MemPtrToLocalID MemPtrUnlock MemSet MemSetDebugMode MemStoreInfo |  |  |  | This chapter provides reference information for the memory manager. The memory manager API is declared in the header file MemoryMgr.h. For more information on the memory manager, see the chapter "Memory" in the Palm OS Programmer's Companion, vol. I. ## Memory Manager Functions ## MemCardInfo #### Purpose Return information about a memory card. #### Prototype Err MemCardInfo (UInt16 cardNo, Char* cardNameP, Char* manufNameP, UInt16* versionP, UInt32* crDateP, UInt32* romSizeP, UInt32* ramSizeP, UInt32* freeBytesP) #### Parameters #####
cardNo | Card number.
#####
cardNameP | Pointer to character array (32 bytes), or 0.
#####
manufNameP | Pointer to character array (32 bytes), or 0.
#####
versionP | Pointer to version variable, or 0.
#####
crDateP | Pointer to creation date variable, or 0.
#####
romSizeP | Pointer to ROM size variable, or 0.
#####
ramSizeP | Pointer to RAM size variable, or 0.
#####
freeBytesP | Pointer to free byte-count variable, or 0.
#### Result Returns 0 if no error. #### Comments Pass 0 for those variables that you don't want returned. ## MemCmp #### Purpose Compare two blocks of memory. NOTE: Blocks are compared as unsigned bytes. #### Prototype Int16 MemCmp (const void* s1, const void* s2, Int32 numBytes) #### Parameters #####
s1, s2 | Pointers to block of memory.
#####
numBytes | Number of bytes to compare.
#### Result Zero if they match, non-zero if not: + if s1 > s2 - if s1 < s2 #### Compatibility Implemented only if 2.0 New Feature Set is present. MemCmp can be used to test the equality of blocks in memory on all versions that support MemCmp; however, testing the sort ordering of blocks in memory works reliably only on Palm OS® versions 3.5 and higher. On versions earlier than 3.2, MemCmp always returns a positive value if the blocks are unequal. On versions 3.2 and 3.3, MemCmp reliably returns positive to indicate s1 > s2 and negative to indicate s1 < s2 only if the characters that differ are less than 128 apart. If the difference is greater than that, MemCmp may return positive when it should return negative and vice versa. ## MemDebugMode #### Purpose Return the current debugging mode of the memory manager. #### Prototype UInt16 MemDebugMode (void) #### Parameters No parameters. #### Result Returns debug flags as described for MemSetDebugMode. ## MemHandleCardNo #### Purpose Return the card number a chunk resides in. #### Prototype UInt16 MemHandleCardNo (MemHandle h) #### Parameters #####
-> h | Chunk handle.
#### Result Returns the card number. #### Comments Call this routine to retrieve the card number (0 or 1) a movable chunk resides on. #### See Also MemPtrCardNo ## MemHandleDataStorage #### Purpose Return true if the given handle is part of a data storage heap. If not, it's a handle in the dynamic heap. #### Prototype Boolean MemHandleDataStorage (MemHandle h) #### Parameters #####
-> h | Chunk handle.
#### Result Returns true if the handle is part of a data storage heap. #### Comments Called by Fields package routines to determine if they need to worry about data storage write-protection when editing a text field. #### See Also MemPtrDataStorage ## MemHandleFree #### Purpose Dispose of a movable chunk. #### Prototype Err MemHandleFree (MemHandle h) #### Parameters #####
-> h | Chunk handle.
#### Result Returns 0 if no error, or memErrInvalidParam if an error occurs. #### Comments Call this routine to dispose of a movable chunk. #### See Also MemHandleNew ## MemHandleHeapID #### Purpose Return the heap ID of a chunk. #### Prototype UInt16 MemHandleHeapID (MemHandle h) #### Parameters #####
-> h | Chunk handle.
#### Result Returns the heap ID of a chunk. #### Comments Call this routine to get the heap ID of the heap a chunk resides in. #### See Also MemPtrHeapID ## MemHandleLock #### Purpose Lock a chunk and obtain a pointer to the chunk's data. #### Prototype MemPtr MemHandleLock (MemHandle h) #### Parameters #####
-> h | Chunk handle.
#### Result Returns a pointer to the chunk. #### Comments Call this routine to lock a chunk and obtain a pointer to the chunk. MemHandleLock and MemHandleUnlock should be used in pairs. #### See Also MemHandleNew, MemHandleUnlock ## MemHandleNew #### Purpose Allocate a new movable chunk in the dynamic heap and returns a handle to it. #### Prototype MemHandle MemHandleNew (UInt32 size) #### Parameters #####
-> size | The desired size of the chunk.
#### Result Returns a handle to the new chunk, or 0 if unsuccessful. #### Comments Use this call to allocate dynamic memory. Before you can write data to the memory chunk that MemHandleNew allocates, you must call MemHandleLock to lock the chunk and get a pointer to it. #### See Also MemPtrFree, MemPtrNew, MemHandleFree, MemHandleLock ## MemHandleResize #### Purpose Resize a chunk. #### Prototype Err MemHandleResize (MemHandle h, UInt32 newSize) #### Parameters #####
-> h | Chunk handle.
#####
-> newSize | The new desired size.
#### Result #####
0 | No error.
#####
memErrInvalidParam | Invalid parameter passed.
#####
memErrNotEnoughSpace | Not enough free space in heap to grow chunk.
#####
memErrChunkLocked | Can't grow chunk because it's locked.
#### Comments Call this routine to resize a chunk. This routine is always successful when shrinking the size of a chunk, even if the chunk is locked. When growing a chunk, it first attempts to grab free space immediately following the chunk so that the chunk does not have to move. If the chunk has to move to another free area of the heap to grow, it must be movable and have a lock count of 0. On devices running version 2.0 or earlier of Palm OS, the MemHandleResize function tries to resize the chunk only within the same heap, whereas DmResizeRecord will look for space in other data heaps if it can't find enough space in the original heap. #### See Also MemHandleNew, MemHandleSize ## MemHandleSetOwner #### Purpose Set the owner ID of a chunk. #### Prototype Err MemHandleSetOwner (MemHandle h, UInt16 owner) #### Parameters #####
-> h | Chunk handle.
#####
-> owner | New owner ID of the chunk. Specify 0 to set the owner to the operating system.
#### Result Returns 0 if no error, or memErrInvalidParam if an error occurs. #### Comments When you allocate a parameter block to pass to SysUIAppSwitch or SysAppLaunch, you must call MemPtrSetOwner to grant ownership of the parameter block chunk to the OS (your application is originally set as the owner). If the parameter block structure references any chunks by handle, you also must call MemHandleSetOwner to grant ownership of those blocks to the OS. If you don't change the ownership of these chunks, they will get freed before the application you're launching has a chance to use them. ## MemHandleSize #### Purpose Return the requested size of a chunk. #### Prototype UInt32 MemHandleSize (MemHandle h) #### Parameters #####
-> h | Chunk handle.
#### Result Returns the requested size of the chunk. #### Comments Call this routine to get the size originally requested for a chunk. #### See Also MemHandleResize ## MemHandleToLocalID #### Purpose Convert a handle into a local chunk ID which is card relative. #### Prototype LocalID MemHandleToLocalID (MemHandle h) #### Parameters #####
-> h | Chunk handle.
#### Result Returns local ID, or NULL (0) if unsuccessful. #### Comments Call this routine to convert a chunk handle to a local ID. #### See Also MemLocalIDToGlobal, MemLocalIDToLockedPtr ## MemHandleUnlock #### Purpose Unlock a chunk given a chunk handle. #### Prototype Err MemHandleUnlock (MemHandle h) #### Parameters #####
-> h | The chunk handle.
#### Result #####
0 | No error.
#####
memErrInvalidParam | Invalid parameter passed.
#### Comments Call this routine to decrement the lock count for a chunk. MemHandleLock and MemHandleUnlock should be used in pairs. #### See Also MemHandleLock ## MemHeapCheck #### Purpose Check validity of a given heap. #### Prototype Err MemHeapCheck (UInt16 heapID) #### Parameters #####
heapID | ID of heap to check.
#### Result Returns 0 if no error. #### See Also MemDebugMode, MemSetDebugMode ## MemHeapCompact #### Purpose Compact a heap. #### Prototype Err MemHeapCompact (UInt16 heapID) #### Parameters #####
-> heapID | ID of the heap to compact.
#### Result Always returns 0. #### Comments Most applications never need to call this function explicitly. The system software calls this function at various times; for example, during memory allocation (if sufficient free space is not available) and during system reboot. Call this routine to compact a heap and merge all free space. This routine attempts to move all movable chunks to the start of the heap and merge all free space in the center of the heap. ## MemHeapDynamic #### Purpose Return true if the given heap is a dynamic heap. #### Prototype Boolean MemHeapDynamic (UInt16 heapID) #### Parameters #####
heapID | ID of the heap to be tested.
#### Result Returns true if dynamic, false if not. #### Comments Dynamic heaps are used for volatile storage, application stacks, globals, and dynamically allocated memory. NOTE: In Palm OS 3.5, the dynamic heap is sized based on the amount of memory available, and is generally larger than before. #### See Also MemNumHeaps, MemHeapID ## MemHeapFlags #### Purpose Return the heap flags for a heap. #### Prototype UInt16 MemHeapFlags (UInt16 heapID) #### Parameters #####
-> heapID | ID of heap.
#### Result Returns the heap flags. #### Comments Call this routine to retrieve the heap flags for a heap. The flags can be examined to determine if the heap is ROM based or not. ROM-based heaps have the memHeapFlagReadOnly bit set (the memHeapFlagReadOnly mask has a value of 0x0001). #### See Also MemNumHeaps, MemHeapID ## MemHeapFreeBytes #### Purpose Return the total number of free bytes in a heap and the size of the largest free chunk in the heap. #### Prototype Err MemHeapFreeBytes (UInt16 heapID, UInt32* freeP, UInt32* maxP) #### Parameters #####
-> heapID | ID of heap.
#####
<-> freeP | Pointer to a variable of type UInt32 for free bytes.
#####
<-> maxP | Pointer to a variable of type UInt32 for max free chunk size. Do not pass NULL for this argument.
#### Result Always returns 0. #### Comments This routine doesn't compact the heap but may be used to determine in advance whether an allocation request will succeed. Before allocating memory, call this function and test the value returned in maxP to determine whether enough free space to fulfill your allocation request exists. If not, you may make more space available by calling the MemHeapCompact function. Note that both MemPtrNew and MemHandleNew automatically compact the heap if necessary. #### See Also MemHeapSize, MemHeapID, MemHeapCompact ## MemHeapID #### Purpose Return the heap ID for a heap, given its index and the card number. #### Prototype UInt16 MemHeapID (UInt16 cardNo, UInt16 heapIndex) #### Parameters #####
-> cardNo | The card number, either 0 or 1.
#####
-> heapIndex | The heap index, anywhere from 0 to MemNumHeaps - 1.
#### Result Returns the heap ID. #### Comments Call this routine to retrieve the heap ID of a heap, given the heap index and the card number. A heap ID must be used to obtain information on a heap such as its size, free bytes, etc., and is also passed to any routines which manipulate heaps. #### See Also MemNumHeaps ## MemHeapScramble #### Purpose Scramble the specified heap. #### Prototype Err MemHeapScramble (UInt16 heapID) #### Parameters #####
heapID | ID of heap to scramble.
#### Comments The system attempts to move each movable chunk. Useful for debugging. #### Result Always returns 0. #### See Also MemDebugMode, MemSetDebugMode ## MemHeapSize #### Purpose Return the total size of a heap including the heap header. #### Prototype UInt32 MemHeapSize (UInt16 heapID) #### Parameters #####
-> heapID | ID of heap.
#### Result Returns the total size of the heap. #### See Also MemHeapFreeBytes, MemHeapID ## MemLocalIDKind #### Purpose Return whether or not a local ID references a handle or a pointer. #### Prototype LocalIDKind MemLocalIDKind (LocalID local) #### Parameters #####
-> local | Local ID to query
#### Result Returns LocalIDKind, or a memIDHandle or memIDPtr (see MemoryMgr.h). #### Comments This routine determines if the given local ID is to a nonmovable (memIDPtr) or movable (memIDHandle) chunk. ## MemLocalIDToGlobal #### Purpose Convert a local ID, which is card relative, into a global pointer in the designated card. #### Prototype MemPtr MemLocalIDToGlobal (LocalID local, UInt16 cardNo) #### Parameters #####
-> local | The local ID to convert.
#####
-> cardNo | Memory card the chunk resides in.
#### Result Returns pointer or handle to chunk. #### See Also MemLocalIDKind, MemLocalIDToLockedPtr ## MemLocalIDToLockedPtr #### Purpose Return a pointer to a chunk given its local ID and card number. If the local ID references a movable chunk handle, this routine automatically locks the chunk before returning. #### Prototype MemPtr MemLocalIDToLockedPtr (LocalID local, UInt16 cardNo) #### Parameters #####
local | Local chunk ID.
#####
cardNo | Card number.
#### Result Returns pointer to chunk, or 0 if an error occurs. #### See Also MemLocalIDToGlobal, MemLocalIDToPtr, MemLocalIDKind, MemPtrToLocalID, MemHandleToLocalID ## MemLocalIDToPtr #### Purpose Return pointer to chunk, given the local ID and card number. #### Prototype MemPtr MemLocalIDToPtr (LocalID local, UInt16 cardNo) #### Parameters #####
-> local | Local ID to query.
#####
-> cardNo | Card number the chunk resides in.
#### Result Returns a pointer to the chunk, or 0 if error. #### Comments If the local ID references a movable chunk and that chunk is not locked, this function returns 0 to indicate an error. #### See Also MemLocalIDToGlobal, MemLocalIDToLockedPtr ## MemMove #### Purpose Move a range of memory to another range in the dynamic heap. #### Prototype Err MemMove (void* dstP, const void* sP, Int32 numBytes) #### Parameters #####
dstP | Pointer to destination.
#####
sP | Pointer to source.
#####
numBytes | Number of bytes to move.
#### Result Always returns 0. #### Comments Handles overlapping ranges. For operations where the destination is in a data heap, see DmSet, DmWrite, and related functions. ## MemNumCards #### Purpose Return the number of memory card slots in the system. Not all slots need to be populated. #### Prototype UInt16 MemNumCards (void) #### Parameters None. #### Result Returns number of slots in the system. ## MemNumHeaps #### Purpose Return the number of heaps available on a particular card. #### Prototype UInt16 MemNumHeaps (UInt16 cardNo) #### Parameters #####
-> cardNo | The card number; either 0 or 1.
#### Result Number of heaps available, including ROM- and RAM-based heaps. #### Comments Call this routine to retrieve the total number of heaps on a memory card. The information can be obtained by calling MemHeapSize, MemHeapFreeBytes, and MemHeapFlags on each heap using its heap ID. The heap ID is obtained by calling MemHeapID with the card number and the heap index, which can be any value from 0 to MemNumHeaps. ## MemNumRAMHeaps #### Purpose Return the number of RAM heaps in the given card. #### Prototype UInt16 MemNumRAMHeaps (UInt16 cardNo) #### Parameters #####
cardNo | The card number.
#### Result Returns the number of RAM heaps. #### See Also MemNumCards ## MemPtrCardNo #### Purpose Return the card number (0 or 1) a nonmovable chunk resides on. #### Prototype UInt16 MemPtrCardNo (MemPtr p) #### Parameters #####
-> p | Pointer to the chunk.
#### Result Returns the card number. #### See Also MemHandleCardNo ## MemPtrDataStorage #### Purpose Return true if the given pointer is part of a data storage heap; if not, it is a pointer in the dynamic heap. #### Prototype Boolean MemPtrDataStorage (MemPtr p) #### Parameters #####
p | Pointer to a chunk.
#### Result Returns true if the chunk is part of a data storage heap. #### Comments Called by Fields package to determine if it needs to worry about data storage write-protection when editing a text field. #### See Also MemHeapDynamic ## MemPtrFree #### Purpose Macro to dispose of a chunk. #### Prototype Err MemPtrFree (MemPtr p) #### Parameters #####
-> p | Pointer to a chunk.
#### Result #####
0 | If no error or memErrInvalidParam (invalid parameter).
#### Comments Call this routine to dispose of a nonmovable chunk. ## MemPtrHeapID #### Purpose Return the heap ID of a chunk. #### Prototype UInt16 MemPtrHeapID (MemPtr p) #### Parameters #####
-> p | Pointer to the chunk.
#### Result Returns the heap ID of a chunk. #### Comments Call this routine to get the heap ID of the heap a chunk resides in. ## MemPtrNew #### Purpose Allocate a new nonmovable chunk in the dynamic heap. #### Prototype MemPtr MemPtrNew (UInt32 size) #### Parameters #####
-> size | The desired size of the chunk.
#### Result Returns pointer to the new chunk, or 0 if unsuccessful. #### Comments This routine allocates a nonmovable chunk in the dynamic heap and returns a pointer to the chunk. Applications can use it when allocating dynamic memory. In Palm OS 3.5, the dynamic heap is sized based on the amount of memory available, and is generally larger than before. NOTE: You cannot allocate a zero-size reference block. ## MemPtrRecoverHandle #### Purpose Recover the handle of a movable chunk, given a pointer to its data. #### Prototype MemHandle MemPtrRecoverHandle (MemPtr p) #### Parameters #####
-> p | Pointer to the chunk.
#### Result Returns the handle of the chunk, or 0 if unsuccessful. #### Comments Don't call this function for pointers in ROM or nonmovable data chunks. ## MemPtrResize #### Purpose Resize a chunk. #### Prototype Err MemPtrResize (MemPtr p, UInt32 newSize) #### Parameters #####
-> p | Pointer to the chunk.
#####
-> newSize | The new desired size.
#### Result Returns 0 if no error, or memErrNotEnoughSpace memErrInvalidParam, or memErrChunkLocked if an error occurs. #### Comments Call this routine to resize a locked chunk. This routine is always successful when shrinking the size of a chunk. When growing a chunk, it attempts to use free space immediately following the chunk. #### See Also MemPtrSize, MemHandleResize ## MemPtrSetOwner #### Purpose Set the owner ID of a chunk. #### Prototype Err MemPtrSetOwner (MemPtr p, UInt16 owner) #### Parameters #####
-> p | Pointer to the chunk.
#####
-> owner | New owner ID of the chunk. Specify 0 to set the owner to the operating system.
#### Result Returns 0 if no error, or memErrInvalidParam if an error occurs. #### Comments When you allocate a parameter block to pass to SysUIAppSwitch or SysAppLaunch, you must call MemPtrSetOwner or MemHandleSetOwner to grant ownership of the parameter block chunk, and any other chunks referenced in it, to the OS (your application is originally set as the owner). If you don't change the ownership of the parameter block, it will get freed before the application you're launching has a chance to use it. ## MemPtrSize #### Purpose Return the size of a chunk. #### Prototype UInt32 MemPtrSize (MemPtr p) #### Parameters #####
-> p | Pointer to the chunk.
#### Result The requested size of the chunk. #### Comments Call this routine to get the original requested size of a chunk. ## MemPtrToLocalID #### Purpose Convert a pointer into a card-relative local chunk ID. #### Prototype LocalID MemPtrToLocalID (MemPtr p) #### Parameters #####
-> p | Pointer to a chunk.
#### Result Returns the local ID of the chunk. #### Comments Call this routine to convert a chunk pointer to a local ID. #### See Also MemLocalIDToPtr ## MemPtrUnlock #### Purpose Unlock a chunk, given a pointer to the chunk. #### Prototype Err MemPtrUnlock (MemPtr p) #### Parameters #####
p | Pointer to a chunk.
#### Result 0 if no error, or memErrInvalidParam if an error occurs. #### Comments A chunk must not be unlocked more times than it was locked. #### See Also MemHandleLock ## MemSet #### Purpose Set a memory range in a dynamic heap to a specific value. #### Prototype Err MemSet (void* dstP, Int32 numBytes, UInt8 value) #### Parameters #####
dstP | Pointer to the destination.
#####
numBytes | Number of bytes to set.
#####
value | Value to set.
#### Result Always returns 0. #### Comments For operations where the destination is in a data heap, see DmSet, DmWrite, and related functions. ## MemSetDebugMode #### Purpose Set the debugging mode of the memory manager. #### Prototype Err MemSetDebugMode (UInt16 flags) #### Parameters #####
flags | Debug flags.
#### Comments Use the logical OR operator (|) to provide any combination of one, more, or none of the following flags: memDebugModeCheckOnChange memDebugModeCheckOnAll memDebugModeScrambleOnChange memDebugModeScrambleOnAll memDebugModeFillFree memDebugModeAllHeaps memDebugModeRecordMinDynHeapFree #### Result Returns 0 if no error, or -1 if an error occurs. ## MemStoreInfo #### Purpose Return information on either the RAM store or the ROM store for a memory card. #### Prototype Err MemStoreInfo (UInt16 cardNo, UInt16 storeNumber, UInt16* versionP, UInt16* flagsP, Char* nameP, UInt32* crDateP, UInt32* bckUpDateP, UInt32* heapListOffsetP, UInt32* initCodeOffset1P, UInt32* initCodeOffset2P, LocalID* databaseDirIDP) #### Parameters #####
-> cardNo | Card number, either 0 or 1.
#####
-> storeNumber | Store number; 0 for ROM, 1 for RAM.
#####
<-> versionP | Pointer to version variable, or 0.
#####
<-> flagsP | Pointer to flags variable, or 0.
#####
<-> nameP | Pointer to character array (32 bytes), or 0.
#####
<-> crDateP | Pointer to creation date variable, or 0.
#####
<-> bckUpDateP | Pointer to backup date variable, or 0.
#####
<-> heapListOffsetP | Pointer to heapListOffset variable, or 0.
#####
<-> initCodeOffset1P | Pointer to initCodeOffset1 variable, or 0.
#####
<-> initCodeOffset2P | Pointer to initCodeOffset2 variable, or 0.
#####
<-> databaseDirIDP | Pointer to database directory chunk ID variable, or 0.
#### Result Returns 0 if no error, or memErrCardNotPresent, memErrRAMOnlyCard, or memErrInvalidStoreHeader if an error occurs. #### Comments Call this routine to retrieve any or all information on either the RAM store or the ROM store for a card. Pass 0 for variables that you don't wish returned. |