3.1.4.1 Primitive types

A pair of functions in support of this abstraction is prototyped in ‘listfuns.h’. These functions will be of interest mainly to developers wishing to implement an interface to a new library module and make it accessible on the virtual side by way of the library combinator (Library combinator).

Function: void *avm_value_of_list (list operand, list *message, int *fault)

This function takes an operand representing a value used by a library function in the format described above (Type Conversions) and returns a pointer to the value.

The value field in the operand normally will point to the block of memory holding the value, and the operand itself will be a list of character representations whose binary encodings spell out the value as explained above.

The value field need not be initialized on entry but it will be initialized as a side effect of being computed by this function. If it has been initialized due to a previous call with the same operand, this function is a fast constant time operation.

The caller should not free the pointer returned by this function because a reference to its value will remain in the operand. When the operand itself is freed by avm_dispose (Simple Operations), the value will go with it.

If an error occurs during the evaluation of this function, the integer referenced by fault will be set to a non-zero value, and the list referenced by message will be assigned a representation of a list of strings describing the error. The message is freshly created and should be freed by the caller with avm_dispose when no longer needed.

Possible error messages are <'missing value'>, in the case of an empty operand, <'invalid value'> in the case of an operand that is not a list of character representations, and <'memory overflow'> if there was insufficient space to allocate the result.

Function: list avm_list_of_value (void *contents, size_t size, int *fault)

This function performs the inverse operation of avm_value_of_list, taking the address of an area of contiguously stored data and its size in bytes to a list representation. The length of the list returned is equal to the number of bytes of data, size, and each item of the list is a character representation for the corresponding byte as given by Character Table.

A copy of the memory area is made so that the original is no longer needed and may be freed by the caller. A pointer to this copy is returned by subsequent calls to avm_value_of_list when the result returned by this function is used as the operand parameter.

If there is insufficient memory to allocate the result, the integer referenced by fault is set to a non-zero value, and a copy of the message <'memory overflow'> represented as a list is returned. This function could also cause a segmentation fault if it is passed an invalid pointer or a size that overruns the storage area. However, it is acceptable to specify a size that is less than the actual size of the given memory area to construct a list representing only the first part of it. The size must always be greater than zero.

This document was generated on December 10, 2012 using texi2html 1.82.