Calling-existing-library-functions.html 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
  2. <html>
  3. <!-- Created on December 10, 2012 by texi2html 1.82
  4. texi2html was written by:
  5. Lionel Cons <[email protected]> (original author)
  6. Karl Berry <[email protected]>
  7. Olaf Bachmann <[email protected]>
  8. and many others.
  9. Maintained by: Many creative people.
  10. Send bugs and suggestions to <[email protected]>
  11. -->
  12. <head>
  13. <title>avram - a virtual machine code interpreter: 3.9.1 Calling existing library functions</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3.9.1 Calling existing library functions">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3.9.1 Calling existing library functions">
  16. <meta name="resource-type" content="document">
  17. <meta name="distribution" content="global">
  18. <meta name="Generator" content="texi2html 1.82">
  19. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  20. <style type="text/css">
  21. <!--
  22. a.summary-letter {text-decoration: none}
  23. blockquote.smallquotation {font-size: smaller}
  24. pre.display {font-family: serif}
  25. pre.format {font-family: serif}
  26. pre.menu-comment {font-family: serif}
  27. pre.menu-preformatted {font-family: serif}
  28. pre.smalldisplay {font-family: serif; font-size: smaller}
  29. pre.smallexample {font-size: smaller}
  30. pre.smallformat {font-family: serif; font-size: smaller}
  31. pre.smalllisp {font-size: smaller}
  32. span.roman {font-family:serif; font-weight:normal;}
  33. span.sansserif {font-family:sans-serif; font-weight:normal;}
  34. ul.toc {list-style: none}
  35. -->
  36. </style>
  37. </head>
  38. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  39. <a name="Calling-existing-library-functions"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <tr><td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Previous section in reading order"> &lt; </a>]</td>
  42. <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>
  43. <td valign="middle" align="left"> &nbsp; </td>
  44. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  45. <td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Up section"> Up </a>]</td>
  46. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  47. <td valign="middle" align="left"> &nbsp; </td>
  48. <td valign="middle" align="left"> &nbsp; </td>
  49. <td valign="middle" align="left"> &nbsp; </td>
  50. <td valign="middle" align="left"> &nbsp; </td>
  51. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  52. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  53. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  54. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  55. </tr></table>
  56. <hr size="1">
  57. <a name="Calling-existing-library-functions-1"></a>
  58. <h3 class="subsection">3.9.1 Calling existing library functions</h3>
  59. <p>Whatever data types a library function manipulates, its argument and
  60. its result are each ultimately encoded each by a single list as
  61. explained in <a href="Type-Conversions.html#Type-Conversions">Type Conversions</a>. This representation allows all
  62. library functions to be invoked by a uniform calling convention as
  63. detailed below.
  64. </p>
  65. <dl>
  66. <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>
  67. <dd><p>This function serves as an interpreter of external library functions
  68. by taking a <var>library_name</var>, a <var>function_name</var>, and an
  69. <var>argument</var> to the result returned by the corresponding library
  70. function for the given <var>argument</var>.
  71. </p>
  72. <p>The library and function names should be encoded as lists of character
  73. representations, the same as the arguments that would be used with the
  74. <code>library</code> combinator if it were being invoked by virtual code
  75. <a name="index-backward-compatability-1"></a>
  76. (with attention to the backward compatibility issue explained in
  77. <a href="Characters-and-Strings.html#Characters-and-Strings">Characters and Strings</a>).
  78. </p>
  79. <p>If an error occurs in the course of evaluating a library function, the
  80. integer referenced by <var>fault</var> will be assigned a non-zero value,
  81. and the result will be a list of character string representations
  82. explaining the error, such as <code>&lt;'memory overflow'&gt;</code>, for example.
  83. Otherwise, the list returned will encode the result of the library
  84. function in a way that depends on the particular function being evaluated.
  85. </p></dd></dl>
  86. <dl>
  87. <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>
  88. <dd><p>This function implements the <code>have</code> combinator described in
  89. <a href="Have-combinator.html#Have-combinator">Have combinator</a>, which tests for the availability of a library
  90. function. The <var>library_name</var> and <var>function_name</var> parameters
  91. are as explained above for <code>avm_library_call</code>, and <code>fault</code>
  92. could signal an error similarly for this function as well.
  93. </p>
  94. <p>The result returned will be an error message in the event of an error,
  95. or a list of pairs of strings otherwise. The list will be empty if the
  96. library function is not available. If the library function is
  97. available, the list will contain a single pair, as in
  98. </p>
  99. <table><tr><td>&nbsp;</td><td><pre class="example">&lt;(library_name,function_name)&gt;
  100. </pre></td></tr></table>
  101. <p>In addition, the list representation of the character string
  102. <code>'*'</code> can be specified as either the library name or the function
  103. name or both. This string is interpreted as a wild card and will cause
  104. all matching pairs of library and function names to be returned in the
  105. list.
  106. </p></dd></dl>
  107. <dl>
  108. <dt><a name="index-avm_005finitialize_005flibfuns"></a><u>Function:</u> void <b>avm_initialize_libfuns</b><i> ()</i></dt>
  109. <dd><p>This function initializes some static data structures used by the two
  110. functions above. It may be called optionally before the first call to
  111. either of them, but will be called automatically if not.
  112. </p></dd></dl>
  113. <dl>
  114. <dt><a name="index-avm_005fcount_005flibfuns"></a><u>Function:</u> void <b>avm_count_libfuns</b><i> ()</i></dt>
  115. <dd><p>This function can be used as an aid to detecting memory leaks. It
  116. reclaims any data structures allocated by
  117. <code>avm_initialize_libfuns</code> and should be called towards the end of
  118. 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.
  119. </p></dd></dl>
  120. <hr size="1">
  121. <table cellpadding="1" cellspacing="1" border="0">
  122. <tr><td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Previous section in reading order"> &lt; </a>]</td>
  123. <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>
  124. <td valign="middle" align="left"> &nbsp; </td>
  125. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  126. <td valign="middle" align="left">[<a href="External-Library-Maintenance.html#External-Library-Maintenance" title="Up section"> Up </a>]</td>
  127. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  128. <td valign="middle" align="left"> &nbsp; </td>
  129. <td valign="middle" align="left"> &nbsp; </td>
  130. <td valign="middle" align="left"> &nbsp; </td>
  131. <td valign="middle" align="left"> &nbsp; </td>
  132. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  133. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  134. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  135. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  136. </tr></table>
  137. <p>
  138. <font size="-1">
  139. This document was generated on <i>December 10, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  140. </font>
  141. <br>
  142. </p>
  143. </body>
  144. </html>