[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated on November 8, 2012 using texi2html 1.82.