LOADER_$INTRO Domain/OS LOADER_$INTRO
NAME
intro - the Domain/OS loader
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/loader.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/loader.ins.pas';
DESCRIPTION
The loader_$ calls are the programming interface to the Domain/OS loader.
They allow a program to dynamically modify the contents and properties of
the executable and data segments of a process' address space at run time.
The following is a list of the loader_$ calls.
loader_$clear_inlib clear the installed library list
loader_$cond_load ensure a module is loaded
loader_$inlib create a privately installed library
loader_$inquire_image get image information
loader_$inquire_known_lib get information on known libraries
loader_$inquire_section get information on an image section
loader_$inquire_stat get a load history summation
loader_$kg_define add to the Known Global Table (KGT)
loader_$kg_lookup look up a symbol
loader_$load load a module
loader_$lookup_stack_size get the stack size requirement of an image
loader_$lookup_start_addr get the start address of an image
loader_$unload unload a loaded module
Constants
loader_$kg_symbol
A special value passed in the fourth argument to loader_$kg_define
or loader_$kg_lookup to specify a symbol in the Known Global Table
(KGT).
library_$init_section_name
The name of the initialization section of a known library.
loader_$string_maxlen
The maximum number of bytes in a string that can be passed to a
loader_$ call.
Data Types
loader_$opts
A small set of options that affect the loading of program modules.
The set can contain a combination of the following elements:
loader_$copy_proc
Copy the object module text into the address space, instead of
mapping it.
loader_$install
Put all defined globals into the Known Global Table (KGT).
loader_$no_unresolveds
Do not load the module if it has unresolved globals. (Compare
with loader_$no_dynamic, below.)
loader_$dont_redefine
Do not redefine any already known symbols in the Known Global
Table (KGT).
loader_$load_writable
Map the object module text in the address space as writable.
loader_$keep_on_exec
Keep the module loaded across UNIX exec(2) calls.
loader_$no_dynamic
Do not load the module if there are unresolvable references.
This differs from loader_$no_unresolveds in that
loader_$no_unresolveds forbids a module to be loaded if it con-
tains any external references; loader_$no_dynamic forbids a
module to be loaded if it contains external references that are
not in the Known Global Table.
loader_$string_index
An index into a string argument to a loader_$ call.
loader_$string
An array of loader_$string_maxlen bytes for passing string arguments
to loader_$ calls.
loader_$handle_t
An handle for referring to a loaded image.
loader_$kg_lookup_opts
A small set of options to restrict searches of the Known Global
Table (KGT). This type can assume a combination of the following
values:
loader_$kg_force_load
Load symbols from shared libraries if not loaded already.
loader_$kg_public_only
Look up only symbols in the public address space and ignore
privately installed symbols.
loader_$kg_function_only
Look up only symbols marked as functions.
loader_$kg_data_only
Look up only symbols marked as data.
loader_$sym_flags
A small set of symbol attributes returned by loader_$kg_lookup.
This type can assume a combination of the following values:
loader_$sym_loaded
The symbol is currently loaded.
loader_$sym_known
The symbol is publically available.
loader_$sym_dynamic
The symbol will not be loaded until the symbol is executed.
loader_$sym_function
The symbol is known to be a function.
loader_$sym_data
The symbol is known to be a data symbol.
loader_$sym_section
The symbol is a section name.
loader_$kg_define_opts
A small set of options to modify definitions of new known globals.
This type can assume a combination of the following values:
loader_$kg_keep_on_exec
Keep the symbol in the Known Global Table (KGT) across UNIX
exec(2) calls.
loader_$kg_function
Mark the symbol as a function.
loader_$image
A record containing information about an executable image loaded
into memory. The following diagram illustrates the format:
15 0
______________________________________________________________
| image_uid |
|_____________________________________________________________|
| image_uid |
|_____________________________________________________________|
| image_uid |
|_____________________________________________________________|
| image_uid |
|_____________________________________________________________|
| handle |
|_____________________________________________________________|
| handle |
|_____________________________________________________________|
| next_handle |
|_____________________________________________________________|
| next_handle |
|_____________________________________________________________|
| nsects |
|_____________________________________________________________|
| nsects |
|_____________________________________________________________|
| image_base |
|_____________________________________________________________|
| image_base |
|_____________________________________________________________|
| opts |
______________________________________________________________
15 0
image_uid
The UID of the object containing the image.
handle
The handle for the image.
next_handle
The handle for the next loaded image.
nsects
The number of sections in the image.
image_base
The offset of image base in the image file.
opts The options the module was loaded with.
loader_$section
A record containing information on a section of an executable image.
The following diagram illustrates the format:
15 0
______________________________________________________________
| addr |
|_____________________________________________________________|
| addr |
|_____________________________________________________________|
| paddr |
|_____________________________________________________________|
| paddr |
|_____________________________________________________________|
| len |
|_____________________________________________________________|
| len |
|_____________________________________________________________|
| sect_num |
|_____________________________________________________________|
| sect_num |
|_____________________________________________________________|
| name |
|_____________________________________________________________|
| name |
|_____________________________________________________________|
| name_len |
______________________________________________________________
15 0
addr The address at which the section is loaded.
paddr
The expected start address (from the object module).
len The length of the section.
sect_num
The section number as found in object module.
name A pointer to the name of the section in the same address space
as the image.
name_len
The number of significant bytes in name.
loader_$known_lib
A packed record containing information about a known library. The
following diagram illustrates the format:
15 0
______________________________________________________________
| lib_uid |
|_____________________________________________________________|
| lib_uid |
|_____________________________________________________________|
| lib_uid |
|_____________________________________________________________|
| lib_uid |
|_____________________________________________________________|
| handle |
|_____________________________________________________________|
| handle |
|_____________________________________________________________|
| Not Used |d |g |i |
______________________________________________________________
15 3 2 1 0
lib_uid
The UID of the library object.
handle
An internal handle for the loader.
dynamic
The field labeled "d" is the dynamic bit that, if true, indi-
cates the library is loaded dynamically at run time. If false
the library is not loaded dynamically.
global
The field labeled "g" is the global bit that, if true, indi-
cates the library must be in global space. If false the
library need not be global.
inlib
The field labeled "i" is the inlib bit that, if true, indicates
the library was installed privately at load time. If false the
library was not installed privately at load time.
library_$init_ptr_t
A pointer to a library initialization routine.
library_$init_section_t
An array of pointers to library initialization routines.
Errors
loader_$abs_reloc_needed
Attempted to load a program that needs relocation that can't be done
at load time.
loader_$abs_space_used
The address space specified by the absolute program was already
occupied.
loader_$bkpts_in_obj
A debugger has crashed and left breakpoints installed in the module.
loader_$cannot_unload
loader_$unload cannot unload the specified module. Check that the
module was loaded according to the requirements set by
loader_$unload.
loader_$dnx60_required
A DN160, DN460, or DN660 is required to execute this object module.
loader_$end_of_image_list
There are no more images in the list.
loader_$error_with_shared_lib
There was an error in loading one of the shared libraries.
loader_$incompatible_load_mode
An invalid combination of arguments was passed to the loader.
loader_$invalid_image_handle
The image handle passed into the loader is invalid.
loader_$invalid_section_number
An invalid section number was requested from the loader.
loader_$linking_required
The module can't be loaded without a linking phase.
loader_$m020_required
A processor with a 68020 CPU is needed to run the program.
loader_$m881_required
A processor with a 68881 floating-point accelerator is needed to run
the program.
loader_$mfpa_required
A processor with a FPA floating-point accelerator is needed to run
the program.
loader_$no_copy_space
There is not enough address space to copy the object module into -
the disk may be full.
loader_$no_kg_space
There is not enough address space to build the Known Global Table
(KGT).
loader_$no_module_for_mach_type
A compound executable contains no module appropriate to the machine
type.
loader_$no_rw_space
There is not enough address space for the read/write section of the
program module - the disk may be full.
loader_$not_a_program
The program module is not in a recognizable format.
loader_$obsolete_systype
The systype specified by the program is obsolete and can't be loaded
anymore.
loader_$obsolete_systype_sys3
The sys3 systype is no longer supported.
loader_$peb_required
A Peripheral Enhancement Board (PEB) floating-point accelerator is
required to run the program.
loader_$pic_required
The load context requires position independent code (relocatable
object modules).
loader_$space_used
The address space specified for use by the loader is already occu-
pied.
loader_$too_many_sections
The program module has too many sections for the loader to deal
with.
loader_$too_many_undefined
The program module has too many undefined symbols for the loader to
deal with.
loader_$undef_glbl
An undefined symbol was referenced.
loader_$undef_glbl_in_lib
An undefined symbol was referenced in a global library.
loader_$wrong_version
The object module format is incompatible with this software release.
loader_$xrev_incompatible
Cannot mix incompatible software revisions.