Library-Reference.html 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166
  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. Library Reference</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3. Library Reference">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3. Library Reference">
  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="Library-Reference"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <tr><td valign="middle" align="left">[<a href="Vacant-Address-Space.html#Vacant-Address-Space" title="Previous section in reading order"> &lt; </a>]</td>
  42. <td valign="middle" align="left">[<a href="Lists.html#Lists" 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="Virtual-Machine-Specification.html#Virtual-Machine-Specification" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  45. <td valign="middle" align="left">[<a href="avram.html#Top" 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="Library-Reference-1"></a>
  58. <h1 class="chapter">3. Library Reference</h1>
  59. <p>Much of the code developed for <code>avram</code> may be reusable in other
  60. projects, so it has been packaged into a library and documented in this
  61. chapter. For ease of reference, this chapter is organized with a
  62. separate section for each source file. For the most part, each source
  63. file encapsulates an abstract type and a number of related functions,
  64. except for a few cases where C makes such a design awkward. An attempt
  65. has been made to present the sections in a readable order as far as
  66. possible.
  67. </p>
  68. <p>The documentation in this chapter is confined to the application program
  69. interface (API), and does not delve unnecessarily into any details of the
  70. <a name="index-API"></a>
  71. implementation. A reader wishing to extend, modify, or troubleshoot the
  72. library itself can find additional information in the source code
  73. comments. These are more likely to be in sync with the code than this
  74. document may be, and are more readily accessible to someone working with
  75. the code.
  76. </p>
  77. <p>Some general points pertaining to the library are the following.
  78. </p>
  79. <ul>
  80. <li> Unlike the previous chapter, this chapter uses the word
  81. &ldquo;function&rdquo; in the C sense rather than the mathematical sense of the word.
  82. </li><li> Internal errors are internal from the user&rsquo;s point of view, not
  83. the developer&rsquo;s (<a href="Internal-Errors.html#Internal-Errors">Internal Errors</a>). Invoking these functions in
  84. ways that are contrary to their specifications can certainly cause
  85. internal errors (not to mention segfaults).
  86. </li><li> The library is definitely not thread safe, and thread safety is
  87. <a name="index-threads"></a>
  88. not a planned enhancement. The amount of locking required to make it
  89. thread safe would probably incur an objectionable performance penalty
  90. due to the complexity of the shared data structures involved, in
  91. addition to being very difficult to get right. If you need these
  92. facilities in a concurrent application, consider spawning a process for
  93. <a name="index-spawning-processes-3"></a>
  94. each client of the library so as to keep their address spaces separate.
  95. </li><li> The library files are built from the standard source
  96. distribution using GNU <code>libtool</code>. In the default directory
  97. hierarchy, they will be found
  98. either in &lsquo;<tt>/usr/lib/libavram.*</tt>&rsquo; or in &lsquo;<tt>/usr/local/lib/libavram.*</tt>&rsquo;.
  99. These directories will differ in a non-standard installation.
  100. </li><li> The header files will probably be
  101. located in either &lsquo;<tt>/usr/include/avm/*.h</tt>&rsquo; or
  102. &lsquo;<tt>/usr/local/include/avm/*.h</tt>&rsquo; for a standard installation.
  103. </li><li> All exported functions, macros and constants are
  104. preceded with <code>avm_</code>, so as to reduce the chance of name clashes
  105. with other libraries. Not all type declarations or field identifiers
  106. follow this convention, because that would be far too tedious.
  107. </li><li> The library header files are designed to be compatible with C++
  108. <a name="index-C_002b_002b"></a>
  109. but have been tested only with C. Please refer to platform specific
  110. documentation for further information on how to link library modules
  111. with your own code.
  112. </li></ul>
  113. <table class="menu" border="0" cellspacing="0">
  114. <tr><td align="left" valign="top"><a href="Lists.html#Lists">3.1 Lists</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
  115. </td></tr>
  116. <tr><td align="left" valign="top"><a href="Characters-and-Strings.html#Characters-and-Strings">3.2 Characters and Strings</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
  117. </td></tr>
  118. <tr><td align="left" valign="top"><a href="File-Manipulation.html#File-Manipulation">3.3 File Manipulation</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
  119. </td></tr>
  120. <tr><td align="left" valign="top"><a href="Invocation.html#Invocation">3.4 Invocation</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
  121. </td></tr>
  122. <tr><td align="left" valign="top"><a href="Version-Management.html#Version-Management">3.5 Version Management</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
  123. </td></tr>
  124. <tr><td align="left" valign="top"><a href="Error-Reporting.html#Error-Reporting">3.6 Error Reporting</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
  125. </td></tr>
  126. <tr><td align="left" valign="top"><a href="Profiling.html#Profiling">3.7 Profiling</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
  127. </td></tr>
  128. <tr><td align="left" valign="top"><a href="Emulation-Primitives.html#Emulation-Primitives">3.8 Emulation Primitives</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
  129. </td></tr>
  130. <tr><td align="left" valign="top"><a href="External-Library-Maintenance.html#External-Library-Maintenance">3.9 External Library Maintenance</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
  131. </td></tr>
  132. </table>
  133. <hr size="1">
  134. <table cellpadding="1" cellspacing="1" border="0">
  135. <tr><td valign="middle" align="left">[<a href="Vacant-Address-Space.html#Vacant-Address-Space" title="Previous section in reading order"> &lt; </a>]</td>
  136. <td valign="middle" align="left">[<a href="Lists.html#Lists" title="Next section in reading order"> &gt; </a>]</td>
  137. <td valign="middle" align="left"> &nbsp; </td>
  138. <td valign="middle" align="left">[<a href="Virtual-Machine-Specification.html#Virtual-Machine-Specification" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  139. <td valign="middle" align="left">[<a href="avram.html#Top" title="Up section"> Up </a>]</td>
  140. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  141. <td valign="middle" align="left"> &nbsp; </td>
  142. <td valign="middle" align="left"> &nbsp; </td>
  143. <td valign="middle" align="left"> &nbsp; </td>
  144. <td valign="middle" align="left"> &nbsp; </td>
  145. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  146. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  147. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  148. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  149. </tr></table>
  150. <p>
  151. <font size="-1">
  152. This document was generated on <i>December 10, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  153. </font>
  154. <br>
  155. </p>
  156. </body>
  157. </html>