txlyre
/
avram


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on December 10, 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.5 Version Management</title>

<meta name="description" content="avram - a virtual machine code interpreter: 3.5 Version Management">
<meta name="keywords" content="avram - a virtual machine code interpreter: 3.5 Version Management">
<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="Version-Management"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Execution-Modes.html#Execution-Modes" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Error-Reporting.html#Error-Reporting" 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="Library-Reference.html#Library-Reference" 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="Version-Management-1"></a>
<h2 class="section">3.5 Version Management</h2>

<p>The <code>avram</code> library is designed to support any number of backward
<a name="index-versions-1"></a>
compatibility modes with itself, by way of some functions declared in
&lsquo;<tt>vman.h</tt>&rsquo;. The assumption is that the library will go through a
sequence of revisions during its life, each being identified by a unique
number. In the event of a fork in the project, each branch will
attempt to maintain compatibility at least with its own ancestors.
</p>
<dl>
<dt><a name="index-avm_005fset_005fversion"></a><u>Function:</u> void <b>avm_set_version</b><i> (char *<var>number</var>)</i></dt>
<dd><p>This function can be used to delay the demise of a client program that
uses the library but is not updated very often. The argument is a null
terminated string representing a version number, such as <code>&quot;0.13.0&quot;</code>.
</p>
<p>A call to this function requests that all library functions revert to
their behavior as of that version in any cases where the current
behavior is incompatible with it. It will also cause virtual code
applications evaluated with <code>avm_apply</code> to detect a version number
equal to the given one rather than the current one. (See <a href="Version.html#Version">Version</a>.)
</p>
<p>The program will exit with an internal error message if any function in
the library has already interrogated the version number before this
function is called, or if it is passed a null pointer. This problem can
be avoided by calling it prior to any of the <code>avm_initialize</code>
functions with a valid address. The program will exit with the message
</p>
<table><tr><td>&nbsp;</td><td><pre class="display"><code><var>program-name</var>: multiple version specifications</code>
</pre></td></tr></table>

<p>if this function is called more than once, even with the same number.
If the number is not recognized as a present or past version, or is so
old that it is no longer supported, the program will exit with this
message.
</p>
<table><tr><td>&nbsp;</td><td><pre class="display"><code>avram: can't emulate version <var>number</var></code>
</pre></td></tr></table>

<p>Client programs that are built to last should allow the version number
to be specified as an option by the user, and let virtual code
applications that they execute take care of their own backward
compatibility problems. This strategy will at least guard against
changes in the virtual machine specification and other changes that do
not affect the library API.
</p></dd></dl>
<dl>
<dt><a name="index-avm_005fprior_005fto_005fversion"></a><u>Function:</u> int <b>avm_prior_to_version</b><i> (char *<var>number</var>)</i></dt>
<dd><p>This function takes the address of a null terminated string representing
a version number as an argument, such as <code>&quot;0.13.0&quot;</code>, and returns a
non-zero value if the version currently being emulated predates it.
</p>
<p>If no call has been made to <code>avm_set_version</code> prior to the call to
this function, the current version is assumed, and subsequent calls to
<code>avm_set_version</code> will cause an internal error.
</p>
<p>The intended use for this function would be by a maintainer of the
library introducing an enhancement that will not be backward compatible,
who doesn&rsquo;t wish to break existing client programs and virtual code
applications. For example, if a version <code>1.0</code> is developed at some
time in the distant future, and it incorporates a previously unexpected
way of doing something, code similar to the following could be used to
maintain backward compatibility.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">if (avm_prior_to_version(&quot;1.0&quot;))
  {
    /* do it the 0.x way */
  }
else
  {
    /* do it the 1.0-and-later way */
  }
</pre></td></tr></table>

<p>This function will cause an internal error if the parameter does not
match any known past or present version number, or if it is a null pointer.
</p></dd></dl>
<dl>
<dt><a name="index-avm_005fversion"></a><u>Function:</u> char* <b>avm_version</b><i> ()</i></dt>
<dd><p>This function returns the number of the version currently being emulated
as the address of a null terminated string. The string whose address is
returned should not be modified by the caller.
</p>
<p>If no call has been made to <code>avm_set_version</code> prior to the call to
this function, the current version is assumed, and subsequent calls to
<code>avm_set_version</code> will cause an internal error.
</p></dd></dl>

<hr size="1">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Execution-Modes.html#Execution-Modes" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Error-Reporting.html#Error-Reporting" 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="Library-Reference.html#Library-Reference" 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>December 10, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
 </font>
 <br>

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