3. Library Reference

Much of the code developed for avram may be reusable in other projects, so it has been packaged into a library and documented in this chapter. For ease of reference, this chapter is organized with a separate section for each source file. For the most part, each source file encapsulates an abstract type and a number of related functions, except for a few cases where C makes such a design awkward. An attempt has been made to present the sections in a readable order as far as possible.

The documentation in this chapter is confined to the application program interface (API), and does not delve unnecessarily into any details of the implementation. A reader wishing to extend, modify, or troubleshoot the library itself can find additional information in the source code comments. These are more likely to be in sync with the code than this document may be, and are more readily accessible to someone working with the code.

Some general points pertaining to the library are the following.

• Unlike the previous chapter, this chapter uses the word “function” in the C sense rather than the mathematical sense of the word.
• Internal errors are internal from the user’s point of view, not the developer’s (Internal Errors). Invoking these functions in ways that are contrary to their specifications can certainly cause internal errors (not to mention segfaults).
• The library is definitely not thread safe, and thread safety is not a planned enhancement. The amount of locking required to make it thread safe would probably incur an objectionable performance penalty due to the complexity of the shared data structures involved, in addition to being very difficult to get right. If you need these facilities in a concurrent application, consider spawning a process for each client of the library so as to keep their address spaces separate.
• The library files are built from the standard source distribution using GNU libtool. In the default directory hierarchy, they will be found either in ‘/usr/lib/libavram.*’ or in ‘/usr/local/lib/libavram.*’. These directories will differ in a non-standard installation.
• The header files will probably be located in either ‘/usr/include/avm/*.h’ or ‘/usr/local/include/avm/*.h’ for a standard installation.
• All exported functions, macros and constants are preceded with avm_, so as to reduce the chance of name clashes with other libraries. Not all type declarations or field identifiers follow this convention, because that would be far too tedious.
• The library header files are designed to be compatible with C++ but have been tested only with C. Please refer to platform specific documentation for further information on how to link library modules with your own code.

This document was generated on November 8, 2012 using texi2html 1.82.