txlyre
/
avram


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on November 8, 2012 by texi2html 1.82
texi2html was written by: 
            Lionel Cons <[email protected]> (original author)
            Karl Berry  <[email protected]>
            Olaf Bachmann <[email protected]>
            and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <[email protected]>
-->
<head>
<title>avram - a virtual machine code interpreter: 3.9.1 Calling existing library functions</title>

<meta name="description" content="avram - a virtual machine code interpreter: 3.9.1 Calling existing library functions">
<meta name="keywords" content="avram - a virtual machine code interpreter: 3.9.1 Calling existing library functions">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">

<a name="Calling-existing-library-functions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Implementing-new-library-functions.html#Implementing-new-library-functions" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<hr size="1">
<a name="Calling-existing-library-functions-1"></a>
<h3 class="subsection">3.9.1 Calling existing library functions</h3>

<p>Whatever data types a library function manipulates, its argument and
its result are each ultimately encoded each by a single list as
explained in <a href="Type-Conversions.html#Type-Conversions">Type Conversions</a>. This representation allows all
library functions to be invoked by a uniform calling convention as
detailed below.
</p>
<dl>
<dt><a name="index-avm_005flibrary_005fcall"></a><u>Function:</u> list <b>avm_library_call</b><i> (list <var>library_name</var>, <var>list function_name</var>, list <var>argument</var>, int *<var>fault</var>)</i></dt>
<dd><p>This function serves as an interpreter of external library functions
by taking a <var>library_name</var>, a <var>function_name</var>, and an
<var>argument</var> to the result returned by the corresponding library
function for the given <var>argument</var>.
</p>
<p>The library and function names should be encoded as lists of character
representations, the same as the arguments that would be used with the
<code>library</code> combinator if it were being invoked by virtual code
<a name="index-backward-compatability-1"></a>
(with attention to the backward compatibility issue explained in
<a href="Characters-and-Strings.html#Characters-and-Strings">Characters and Strings</a>).
</p>
<p>If an error occurs in the course of evaluating a library function, the
integer referenced by <var>fault</var> will be assigned a non-zero value,
and the result will be a list of character string representations
explaining the error, such as <code>&lt;'memory overflow'&gt;</code>, 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.
</p></dd></dl>

<dl>
<dt><a name="index-avm_005fhave_005flibrary_005fcall"></a><u>Function:</u> list <b>avm_have_library_call</b><i> (list <var>library_name</var>, list <var>function_name</var>, int *<var>fault</var>)</i></dt>
<dd><p>This function implements the <code>have</code> combinator described in
<a href="Have-combinator.html#Have-combinator">Have combinator</a>, which tests for the availability of a library
function. The <var>library_name</var> and <var>function_name</var> parameters
are as explained above for <code>avm_library_call</code>, and <code>fault</code>
could signal an error similarly for this function as well.
</p>
<p>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
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">&lt;(library_name,function_name)&gt;
</pre></td></tr></table>

<p>In addition, the list representation of the character string
<code>'*'</code> 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.
</p></dd></dl>

<dl>
<dt><a name="index-avm_005finitialize_005flibfuns"></a><u>Function:</u> void <b>avm_initialize_libfuns</b><i> ()</i></dt>
<dd><p>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.
</p></dd></dl>

<dl>
<dt><a name="index-avm_005fcount_005flibfuns"></a><u>Function:</u> void <b>avm_count_libfuns</b><i> ()</i></dt>
<dd><p>This function can be used as an aid to detecting memory leaks. It
reclaims any data structures allocated by
<code>avm_initialize_libfuns</code> and should be called towards the end of
a run some time prior to <code>avm_count_lists</code> <a href="Simple-Operations.html#Simple-Operations">Simple Operations</a>, if the latter is being used.
</p></dd></dl>

<hr size="1">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Implementing-new-library-functions.html#Implementing-new-library-functions" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
 <font size="-1">
  This document was generated on <i>November 8, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
 </font>
 <br>

</p>
</body>
</html>