— Function: void avm_set_version (char *number)

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 "0.13.0".

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 avm_apply to detect a version number equal to the given one rather than the current one. (See Version.)

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 avm_initialize functions with a valid address. The program will exit with the message

          program-name: multiple version specifications

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.

          avram: can't emulate version number

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.

— Function: int avm_prior_to_version (char *number)

This function takes the address of a null terminated string representing a version number as an argument, such as "0.13.0", and returns a non-zero value if the version currently being emulated predates it.

If no call has been made to avm_set_version prior to the call to this function, the current version is assumed, and subsequent calls to avm_set_version will cause an internal error.

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't wish to break existing client programs and virtual code applications. For example, if a version 1.0 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.

          if (avm_prior_to_version("1.0"))
            {
              /* do it the 0.x way */
            }
          else
            {
              /* do it the 1.0-and-later way */
            }

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.

— Function: char* avm_version ()

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.

If no call has been made to avm_set_version prior to the call to this function, the current version is assumed, and subsequent calls to avm_set_version will cause an internal error.