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

### 3.9.1 Calling existing library functions

Whatever data types a library function manipulates, its argument and its result are each ultimately encoded each by a single list as explained in Type Conversions. This representation allows all library functions to be invoked by a uniform calling convention as detailed below.

Function: list avm_library_call (list library_name, list function_name, list argument, int *fault)

  This function serves as an interpreter of external library functions by taking a library_name, a function_name, and an argument to the result returned by the corresponding library function for the given argument.

  The library and function names should be encoded as lists of character representations, the same as the arguments that would be used with the `library` combinator if it were being invoked by virtual code (with attention to the backward compatibility issue explained in Characters and Strings).

  If an error occurs in the course of evaluating a library function, the integer referenced by fault will be assigned a non-zero value, and the result will be a list of character string representations explaining the error, such as `<'memory overflow'>`, for example. Otherwise, the list returned will encode the result of the library function in a way that depends on the particular function being evaluated.

Function: list avm_have_library_call (list library_name, list function_name, int *fault)

  This function implements the `have` combinator described in Have combinator, which tests for the availability of a library function. The library_name and function_name parameters are as explained above for `avm_library_call`, and `fault` could signal an error similarly for this function as well.

  The result returned will be an error message in the event of an error, or a list of pairs of strings otherwise. The list will be empty if the library function is not available. If the library function is available, the list will contain a single pair, as in

      <(library_name,function_name)>

  In addition, the list representation of the character string `'*'` can be specified as either the library name or the function name or both. This string is interpreted as a wild card and will cause all matching pairs of library and function names to be returned in the list.

Function: void avm_initialize_libfuns ()

  This function initializes some static data structures used by the two functions above. It may be called optionally before the first call to either of them, but will be called automatically if not.

Function: void avm_count_libfuns ()

  This function can be used as an aid to detecting memory leaks. It reclaims any data structures allocated by `avm_initialize_libfuns` and should be called towards the end of a run some time prior to `avm_count_lists` Simple Operations, if the latter is being used.

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

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