prg_mem_copy_create()
Abstract
Allocates a block of memory with the specified size and copies the contents of a source block of memory into the newly allocated block of memory.
Syntax
prg_mem_copy_create (value, alloc_size)
| Argument | Type | Description |
|---|---|---|
value |
void * |
Pointer to the memory to be copied |
alloc_size |
size_t |
Number of bytes requested for the memory allocation |
Return Type
void *
Pointer to the allocated block of memory. The constant PRGC_NIL is returned if the memory allocation fails.
Header
prg_mem_funcs.h
Example
/* obtain the document request message from the request array */
doc_req_msg = Doc_Req_Array [next_request++];
/* copy the document request message */
doc_req_msg = (Doc_Req_Msg *) prg_mem_copy_create (orig_req_msg,
sizeof (Doc_Req_Msg));
/* process the request */
doc_request_message_process (doc_req_msg);
/* store the processed request in the outgoing array */
Doc_Ans_Array [next_answer++] = doc_req_msg;
Details
This function is frequently used in conjunction with the C language pseudo-function sizeof(), which returns the size in bytes of a data structure specified by name. The preceding example illustrates the combined use of prg_mem_copy_create() and sizeof().
Note: If you call prg_mem_copy_create() on a string and use strlen() to determine the length of the memory, the NULL byte that terminates the string will not be copied. To fix this issue, either use prg_string_copy() or add one to the length, as follows: char *new_string = prg_mem_copy_create (old_string, strlen (old_string) + 1);
This function can be applied to data structures or simple data types. However, it should only be used on user-defined data structures, not Riverbed Modeler-defined data structures such as Packet and Distribution, since a raw copy operation will not have the sophistication necessary to produce a usable duplicate, given the internal data structure accounting and referencing methods (ignoring this warning can lead to simulation errors).
Data structures that contain pointers to other data structures can be copied via this function, but the structures referenced by the pointers are not copied by the raw byte transfer. This does not cause problems if the subsidiary structures that are referenced are not modified. However, if modifications are performed on the subsidiary structures through one copy of the parent structure, all copies are affected. If this is undesired, the user’s process code should scan through the original and copy parent structures, individually copying over subsidiary data structures as well.
Please note the information regarding memory management in prg_mem_alloc().
Purpose
Provides a mechanism for conveniently creating a duplicate of any type of data structure.
Errors
- Recoverable Error: Request to allocate (<size>) bytes failed.
- Program Abort: Segmentation violation. (due to invalid pointer argument, or pointer not pointing to a large enough allocated block of memory)
Reference
- use
prg_mem_free()to deallocate a block of memory - use
prg_mem_alloc()to allocate a block of memory - use
prg_mem_copy()to copy a block of memory