MakeLibrary

construct a library

This function is used for constructing a library vector and data area. The same call is used to constructing devices. Space for the library is allocated from the system's free memory pool. The data portion of the library is initialized. The value of the init parameter may point to a library specific entry point.

MakeLibrary() is limited a maximum of 5461 functions as stored in the vectors table and does not stop if more than 5461 functions are provided. See the BUGS section for more information.

Starting with Kickstart 2.0 (V36), the library base is longword adjusted. The lib_PosSize and lib_NegSize fields of the library structure are adjusted to match.

vectors

pointer to an array of function pointers or function displacements. If the first word of the array is -1, then the array contains relative word displacements (based off of vectors); otherwise, the array contains absolute function pointers. The vector list is terminated by a -1 (of the same size as the pointers).

structure

points to an "InitStruct" data region. If NULL, then it will not be used.

init

If non-NULL, an entry point that will be called before adding the library to the system. Registers are as follows:

d0 = libAddr ;Your library address a0 = segList ;Your AmigaDOS segment list a6 = ExecBase ;Address of exec.library

The result of the init function must be the library address, or NULL for failure. If NULL, the init point must manually deallocate the library base memory (based on the sizes stored in lib_PosSize and lib_NegSize).

dSize

the size of the library data area, including the standard library node data. This must be at leas sizeof(struct Library).

segList

pointer to an AmigaDOS SegList (segment list). This is passed to a library's init code, and is used later for removing the library from memory.

library

the reference address of the library. This is the address used in references to the library, not the beginning of the memory area allocated. If the library vector table require more system memory than is available, this function will return NULL.

MakeLibrary() depends upon MakeFunctions(), which does not check if the number of entries in the table referenced by the functionArray parameter will require more than 65535 bytes of storage. This is a problem because the Library->lib_NegSize member is an unsigned 16 bit integer.

Library and device functions are called with a signed 16 bit displacement relative to the library base address in register A6. Any functions outside this range (-32766..-6) will be unusable. This limits the number usable functions to "only" 5461.

The contents of Library jump tables whose size exceeds 32767 bytes can no longer be changed via SetFunction() as the offset will be clipped to a signed 16 bit value.

MakeLibrary() will, however, allocate as much memory as needed for MakeFunctions() to fill in the entire function array even if it requires more than 65535 bytes to store it.

The MakeLibrary() function expects the dSize parameter, which contains the size of the library base, to be a 32 bit integer which should not be larger than 65553 bytes. However, MakeLibrary() does not check if the library base size exceeds this limit and will allocate as much memory as requested.

These shortcomings in the MakeFunctions() and MakeLibrary() functions can lead to memory leaks when a disk-loaded library or device is expunged because the respective sizes of the function table (goes into Library->lib_NegSize) and the library base (goes into Library->lib_PosSize) will be clipped to the least significant 16 bits of the respective size values.

These bugs exist in all Amiga operating system versions, including Kickstart 1.1 and beyond.

InitStruct(), InitResident(), MakeFunctions(), SetFunction(), "exec/initializers.i", <exec/initializers.h>