Tornado API Reference : WTX Tcl Library
memBlock [Tcl] - WTX Tcl Memory Block Handling
memBlockCreate - create a memory block
memBlockSet - set the elements in a memory block
memBlockGet - get the elements in a memory block
memBlockGetString - get the memory block contents in string form
memBlockWriteFile - write the memory block contents to a file
memBlockDup - create a new block exactly like a given one
memBlockSwap - switch the endianness of a block
memBlockList - list the handles of all existing memory blocks
memBlockInfo - get information about a memory block
memBlockDelete - delete a memory block, freeing its resources
memBlockDis - disassemble a memory block
This library of Tcl routines implements a memory block data type. The goal is to allow efficient management of blocks of target memory provided by WTX from Tcl programs. In particular, the memory blocks are not converted to string form except when a Tcl program requests it.
WTX routines that return (or accept) blocks of target memory should supply block handles provided by this library.
Blocks have both a "logical" size, specified by their creator, and an allocation size. The allocation size is the amount of heap memory allotted for the block data. The library obtains memory to enlarge blocks in chunks.
Blocks are coded for the endianness of the target that supplied them, and the memBlockSet/Get routines will automatically swap 16 and 32 bit quanities when they are stored to or retrieved from a block.
memBlockCreate - create a memory block
WTX Tcl
memBlockCreate [-L | -B] [-string string] [size] [fillvalue]
This function creates a memory block. A memory block is an internal buffer used to hold buffers of raw binary data that can be manipulated with Tcl without the overhead of converting to a string representation. Memory blocks are accessed with "block handles", short string names that are used as an argument to the commands which manipulate memory blocks. Memory blocks are returned from memory read commands. They are used when writing target memory and other places where the WTX protocol exchanges unstructured data buffers between the host and target.
Memory blocks have an endianness which, by default, is set to big endian (-B). memBlockCreate does not interact with the target server, so if the data in the block is destined for a little-endian target, it should be created with the -L flag. The endianness of a block is only used to determine how the block data should be formatted when it is manipulated in 16- or 32-bit formats, and otherwise has no effect on the internal representation.
A memory block is created with a particular size. However, by "storing" new data past the end of a memory block, it can be extended. "Holes" created by this technique are filled with the fillvalue (zero by default).
Memory blocks can be conveniently initialized with a string if -string is specified. Then the block will automatically have the same length as the string (plus one byte for the terminating NULL character, which is automatically added) although the size can be overridden here also.
A memory block handle.
- bad size
- A NULL or negative value has been asked for.
- too big
- The size value is out of the range.
- virtual memory exhausted
- No more heap memory is available.
wtxtcl, memBlockSet, memBlockGet, memBlockDelete, memBlockDup, memBlockList
memBlockSet - set the elements in a memory block
WTX Tcl
memBlockSet [-b | -w | -l] blockId offset value...
This function changes the contents of the named memory block. The changes begin at the byte offset supplied. If the size of the values is greater than a byte (-b), the 16-bit (-w) or 32-bit (-l) values will be swapped before being stored in the block if the byte order of the block differs from that of the host.
Note that storing a value past the current end of the block causes it to grow.
- bad size: use -b, -w, or -l
- The wrong option was used.
- block not found
- The block ID does not exist.
- block maximum size exceeded
- The block has grown past the maximum size.
- virtual memory exhausted
- There is not enough heap memory to grow the block.
* wtxtcl, memBlockGet
memBlockGet - get the elements in a memory block
WTX Tcl
memBlockGet [-b | -w | -l] blockId [offset] [count]
This function fetches the contents of the named memory block. The fetching begins at the byte offset supplied (or zero if this is not given). If the size of the values is greater than a byte (-b), the 16-bit (-w) or 32-bit (-l) values are swapped before being placed in the result string if the byte order of the block differs from that of the host. count values are fetched; if count is omitted, all the values are fetched. To dump the entire block in the form of a byte vector, use the following command:
memBlockGet $block
A vector of values from the block.
- bad size: use -b, -w, or -l
- The wrong option was used.
- missing block handle
- The block handle option is missing.
- block not found
- The block ID does not exist.
- invalid count
- The count value is negative.
- request exceeds block size
- offset + count is greater than the size of the block.
- virtual memory exhausted
- There is no more host memory available to store values into the block.
* wtxtcl, memBlockGetString, memBlockSet
memBlockGetString - get the memory block contents in string form
WTX Tcl
memBlockGetString blockId [offset] [count]
This function returns the string found in the named memory block. Starting at the given offset, characters are accumulated in the result string until a null character is found, count characters have been transferred, or the block is exhausted, whichever comes first.
The string representation of the memory block contents.
- block not found
- The block ID does not exist.
- invalid count
- The count value is negative.
- request exceeds block size
- The request does not fit in the block.
* wtxtcl, memBlockSet, memBlockGet
memBlockWriteFile - write the memory block contents to a file
WTX Tcl
memBlockWriteFile [-append | -seek offset] blockId [|]file [offset] [count]
This command writes a memory block to the named file. The file name - represents stdout. If the file name starts with the pipe character (|), a pipe to the named process is used instead. An offset and count (in bytes) may be specified. No swapping is done; the block is written in raw binary form.
If a pipe is not selected, by default the file is opened for writing and truncated after the block is written. The -append argument causes the block to be written to the end of the file. The -seek argument opens the file for update (it must exist) and seek before writing; the file is not truncated after writing in this case. Neither -seek nor -append may be used with pipes.
- expecting seek offset
- The option -seek is missing its offset parameter.
- block not found
- The block ID does not exist.
- cannot use -seek or -append with a pipe
- You must change flags or use a file.
- invalid count
- The count value is negative.
- bad offset/count parameters for given block
- The offset is negative or offset + count is greater than the block size.
- bad write mode
- Internal error; you attempted to open a file using an option lower than -1.
- write failed
- The write operation did not succeed.
- could not open output file
- The file or pipe could not be opened.
- could not seek in file
- The seek operation failed.
* wtxtcl, memBlockGet, memBlockGetString
memBlockDup - create a new block exactly like a given one
WTX Tcl
memBlockDup blockId
This function clones a memory block, returning a new block handle. The old block is not modified.
A new block handle.
- block not found
- The block ID does not exist.
- could not duplicate block
- A new block could not be created.
* wtxtcl, memBlockCreate, memBlockDelete
memBlockSwap - switch the endianness of a block
WTX Tcl
memBlockSwap blockId
The endian flag of the named memory block is switched. The data themselves are not reorganized.
- block not found
- The block ID does not exist.
* wtxtcl, memBlockCreate
memBlockList - list the handles of all existing memory blocks
WTX Tcl
memBlockList
This command returns a list of the handles of all existing memory blocks.
A list of all outstanding memory blocks.
This script cleans up all memory blocks:
foreach block [memBlockList] {memBlockDelete $block}
wtxtcl, memBlockCreate, memBlockDelete
memBlockInfo - get information about a memory block
WTX Tcl
memBlockInfo blockId
This function returns a vector of information about a memory block.
A four element list. The first is the size of the block; the second is the amount of memory allocated for the block (this may be larger than the size by a small amount for the sake of efficiency); the third is the endianness of the block (B or L); and the fourth is the block's fill character in hexadecimal.
wtxtcl, memBlockCreate, memBlockList, memBlockDelete, memBlockSwap
memBlockDelete - delete a memory block, freeing its resources
WTX Tcl
memBlockDelete blockId
The named memory block is deleted and the associated heap memory freed. The handle becomes invalid and is never reused.
This script recovers the memory of all existing blocks:
foreach block [memBlockList] {memBlockDelete $block}
wtxtcl, memBlockCreate, memBlockList
memBlockDis - disassemble a memory block
memBlockDis [-printaddr cmd] [-offset n] format blockId [count] addressThis API is not supported anymore. Use and Refer to wtxMemDisassemble for further explanations.
TCL_ERROR
API not supported