Freeing allocated memory
Many of the BMC Remedy AR System data structures use allocated memory. For input parameters, use the
malloc function to allocate the necessary space. The system dynamically allocates memory for output parameters based on their content. Only you (the caller of the API function) know whether you allocated space for input parameters, and when you are finished with output parameters, you are responsible for freeing all allocated memory. To avoid a buildup of allocated space, free memory as soon as you no longer need it.
To ease the process of freeing memory, the API includes
FreeAR functions, each specialized to free all allocated memory associated with a particular data structure. These functions assume that all structure components are in allocated memory and must not be used if any components of a structure are on the stack. In that case, you must use the
free function to free the memory manually.
FreeAR functions accept these input arguments:
value— Pointer to the structure to free. The function recursively frees all allocated memory in the structure. If you set this to
NULL(or the structure is a list with zero items), the function performs no operations.
freeStruct— Boolean value that specifies whether to free the top-level structure. If you allocated memory for the top-level structure, specify
TRUEto free both the structure and its contents. If you used a stack variable for the top-level structure, specify
FALSEto free only the contents of the structure. The following example illustrates this difference.
When an API function fails (that is,
status is greater than one), the system initializes all output parameters except
ARStatusList. As a result, the only
FreeAR function the program must call is
FreeAR data Structure for the other parameters is unnecessary but harmless.