Linker Libraries

Linker Libraries

This section describes the amiga.lib and debug.lib libraries. Unlike the libraries described in the other chapters of the manual, these are not shared run-time libraries. Code from the linker libraries is inserted by the linker into your final program. Only the functions you use are pulled into your code. These libraries are typically supplied by your language or compiler vendor.

amiga.lib

This is the main Amiga scanned linker library, linked with most programs for the Amiga. The major components of amiga.lib are:

Functions for each Amiga ROM routine that copy arguments from the stack to the CPU registers – thereby enabling stack-based C compilers to call register-based Amiga ROM routines.

The negative offset from the library base for each Amiga function. These are called Library Vector Offsets (_LVO).

C functions which simplify many Exec procedures such as the creation and deletion of tasks, ports, and I/O request structures.

C support functions including pseudo-random number generation and a limited set of file and stdio functions designed to work directly with AmigaDOS file handles.

C functions which provide some basic conversions to and from Fast Floating Point (FFP) format numbers.

C support functions to add and remove tasks from the vertical-blanking interval interrupt server chain.

C support functions for ARexx variable handling and message checking.

_boxNote:The Timer, Commodities, and Intuition support functions listed below are valid only for use with Release 2.04 (V37) or a later version of the system software.

C support functions to do common timer device operations.

C functions which support the Commodities system. Included are functions to deal with ToolTypes, and to create various Commodities objects.

Functions which provide support for Intuition’s hook and Boopsi sub-systems.

debug.lib

This link library contains standard I/O (stdio) style functions for communicating with a serial terminal connected to the Amiga via its built-in serial port. Typically this terminal will be a 9600-baud, 8 data-bits, one stop-bit connection to an external terminal or an Amiga running a terminal package. The debug.lib functions allow you to output messages and prompt for input (even from within low level task or interrupt code) without disturbing the Amiga’s display and or current state (other than the serial hardware itself).

No matter how badly the system may have crashed, these functions can usually get a message out. A similar debugging library (currently called ddebug.lib) is available for sending debugging output to the parallel port. This is useful for debugging serial applications. ddebug.lib is not documented here. It contains functions similar to debug.lib but with names starting with ‘D’ instead of ‘K’.

Please refer to the Amiga ROM Kernel Reference Manual: Includes and Autodocs for a detailed description of the functions.

Functions in amiga.lib

Amiga.lib

is the main linker library. Most applications link with and use at least one function in amiga.lib. The functions available are as follows.

Exec Support

This function takes an IORequest and passes it directly to the BEGINIO vector of the proper device. This works exactly like SendIO(), but does not clear the io_Flags field first. This function does not wait for the I/O to complete.

CreateExtIO()

allocates memory for and initializes a new I/O request block of a program-specified number of bytes. The number of bytes must be the size of a legal IORequest (or extended request) or very nasty things will happen. DeleteExtIO() frees up an I/O request as allocated by CreateExtIO(). The mn_Length field determines how much memory to deallocate.

CreatePort()

allocates and initializes a new message port. The message list of the new port will be prepared for use via NewList(). The port will be set to signal your task when a message arrives (PA_SIGNAL). DeletePort() deletes the port created by CreatePort(). All messages that may have been attached to that port must already have been replied to.

CreateStdIO()

allocates memory for and initializes a new IOStdReq structure. DeleteStdIO() frees up an IOStdReq allocated by CreateStdIO().

These functions simplify creation and deletion of subtasks by dynamically allocating and initializing the required structures and stack space. They also add the task to Exec’s task list with the given name and priority. A tc_MemEntry list is provided so that all stack and structure memory allocated by CreateTask() is automatically deallocated when the task is removed. Before deleting a task with DeleteTask(), you must first make sure that the task is not currently executing any system code which might try to signal the task after it is gone.

Prepares a List structure for use; the list will be empty and ready to use.

clib

Generates a pseudo-random number. The seed value is taken from stack, shifted left one position, exclusive-or’ed with hex value $1D872B41 and returned.

RangeRand()

accepts a value from 1 to 65535, and returns a value within that range (a 16-bit integer). Note that this function is implemented in C.

Closes a file.

Gets a character from a file.

Prints a formatted output line to a file.

Puts character to file.

Writes a string to file.

Gets a character from stdin.

Puts format data to stdout.

Puts character to stdout.

Puts a string to stdout, followed by newline.

Formats data into a string (see Exec RawDoFmt() ).

Math

Converts ASCII string variable into fast floating-point.

ASCII round-off of the provided floating-point string.

Accepts a dual-binary format floating-point number and converts it to FFP format.

Accepts an FFP number and the address of the ASCII string where its converted output is to be stored. The number is converted to a NULL terminated ASCII string and stored at the address provided. Additionally, the base ten (10) exponent in binary form is returned.

Graphics

AddTOF()

adds a task to the vertical-blanking interval interrupt server chain. This frees C programmers from the burden of having to write an assembly language routine to perform this function. The task can be removed with RemTOF().

ARexx

GetRexxVar()

attempts to extract the value of a variable from a running ARexx script/program. SetRexxVar() will attempt to set the value of a particular variable in a running ARexx script.

This function checks to make sure that a RexxMsg is from ARexx directly. Messages used by the Rexx Variable Interface (RVI) routines are required to be directly from ARexx.

Timer

This function waits for a specified period of time before returning to the the caller.

Commodities

ArgArrayInit()

returns an array of strings suitable for sending to icon.library/FindToolType(). This array will be the ToolTypes array of the program’s icon, if it was started from Workbench. It will just be ’argv’ if the program was started from a shell. ArgArrayDone() frees memory and does cleanup required after a call to ArgArrayInit().

These functions look for a particular entry in a ToolType array returned by ArgArrayInit() and return the integer (ArgInt()) or string (ArgString()) associated with that entry. A default value can be passed to each function which will be returned in the event that the requested entry could not be found in the ToolType array.

This function creates a custom commodity object. The action of this object on receiving a commodity message is to call a function of the application programmer’s choice.

This function creates a Commodities debug object. The action of this object on receiving a Commodities message is to print out information about the message through the serial port (using the debug.lib/kprintf() routine). A specified ’id’ will also be displayed.

Creates a Commodities input event filter object that matches a description string. The description string is in the same format as strings expected by commodities.library/SetFilter(). If the description string is NULL, the filter will not match any messages.

This function creates a Commodities sender object. The action of this object on receiving a Commodities message is to copy the Commodities message into a standard Exec Message, to put a supplied id in the message as well, and to send the message off to the message port.

This function creates a Commodities signal object. The action of this object on receiving a Commodities message is to send a signal to a task. The caller is responsible for allocating the signal and determining the proper task ID.

This function creates a Commodities translator object. The action of this object on receiving a Commodities message is to replace that message in the commodities network with a chain of Commodities input messages.

This function creates a triad of commodity objects to accomplish a high-level function.

The three objects are a filter, which is created to match by CxFilter(), a sender created by CxSender(), and a translator which is created by CxTranslate(), so that it swallows any commodity input event messages that are passed down by the filter.

This is the simple way to get a message sent to your program when the user performs a particular input action.

This function returns a linked list of input events which would translate into the string using the supplied keymap (or the system default keymap if the supplied keymap is NULL).

This chain should eventually be freed using FreeIEvents().

This function frees a linked list of input events as obtained from InvertString().

Intuition

These functions invoke hooks. CallHook() expects a parameter packet (“message”) on the stack, while CallHookA() takes a pointer to the message.

Boopsi support functions that ask a specified Boopsi object to perform a specific message. The message is passed in the function call for DoMethodA() and on the stack for DoMethod(). The message is invoked on the object’s true class.

Boopsi support functions that ask a Boopsi object to perform a supplied message as if it was an instance of its superclass. The message is passed in the function call for DoSuperMethodA() and on the stack for DoSuperMethod().

Boopsi support functions that ask a Boopsi object to perform a supplied message as if it was an instance of some other class. The message is passed in the function call for CoerceMethodA() and on the stack for CoerceMethod.

Boopsi support function which invokes the OM_SET method on the superclass of the supplied class for the supplied object. Allows the ops_AttrList to be supplied on the stack (i.e. in a varargs way).

Functions in debug.lib

debug.lib

is a link library that provides useful diagnostic functions that are handy for developing code. It includes the following functions:

Compare two null-terminated strings.

Get a character from the console.

Get a number from the console.

Return a character if present, but don’t wait.

Print formatted data to the console.

Put a character to the console.

Put a string to the console.