C68 COMPILATION SYSTEM

C68 Linker

NAME

ld - Link files to produce program files or RLL libraries.

SYNOPSIS

ld [options] [cfile_o] [-llibrary]

DESCRIPTION

The LD linker is used to produce binary code that is ready to run. This code can be any of:

After the files comprising a C program have been compiled into object (SROFF) files they must be linked, together with selected library routines, to produce an executable program. This is done by the program LD, which replaces the program LINK that is the traditional linker commonly used on the QL.

LD is much more UNIX like in use than LINK. This is makes it more consistent with the rest of the C68 system which has its origins on UNIX based system. In addition, the LD linker is far more efficient than the original LINK program in that it runs about 3 times faster, and also the resulting program is smaller. It is also possible to run LD in a compatibility mode where it can produce output in the same format as the original LINK program.

The different linkers have used different standards for the way that they store relocation information in the output file. To allow maximum flexibility, the LD version 2.xx series has the ability to produce output that uses a variety of different formats:

If either of these last two formats is required, then the appropriate command line option must be used.

OPTIONS

The following command line options are available for use with the LD linker.
Options Description
-fn The output format required. The values available for n are:
0 GST LINK or Quanta QLINK format
1 LD version 1.xx format
2 LD version 2.xx format
You can also add any combination of the following values although many of them will not make sense unless using LD v2.xx format. For a more detailed discussion of the implications of these settings, see the section concerning the start of the UDATA area later in this document.
4 Set the UDATA area to NOT reuse the relocation area. If you are using GST format, then you would normally use this option as well.
8 Set the UDATA area to NOT reuse the BSS XREF area. This only makes sense if you are either using RLL libraries, or alternatively have used the option (-z xref) to include external references
16 Set the UDATA area to NOT reuse the BSS RLIB area. This only makes sense if you are linking with RLL libraries
32 Set the UDATA area to NOT re-use the BSS XDEF area. This is the normal default for a RLL, but not for other target types.
64 Set the UDATA area to reuse the BSS XDEF area. This is the normal default for everything except a RLL
128 Set the UDATA area to reuse the BSS Header area. Normally if any the BSS XDEF area is present then this would not be re-used
  Default: -f2
-Llibrary path This option allows the order of searching of library files to be changed. The order of searching for libraries is:
  1. Any library directories specified using the -L option. If multiple -L options are specified, then these are searched in the order they are specified on the command line.
  2. The LIB sub-directory of the current program (PROG_USE) setting. For example, if the default program directory is flp1_ then libraries would be expected to be found in flp1_lib_.
  3. The current data (DATA_USE) directory.
If a specified library cannot be found in any of these locations, then an error message will be output.
-llibname Search a statically linked library looking for any modules in the library that will satisfy any of the currently outstanding external references. If any such modules are found then add them to the output file.

Library names are normally specified on the command line after all the object files. This is, however, not mandatory. The libraries and object files are processed in the order specified on the command line. Note that only a single pass of a library is done so that including a library too early in the command line may cause routines to not be included that you might want.

By convention library names are given in a specially compact format. The names for libraries are made up by adding a prefix of lib and an extension of _a to the name specified on the command line. For example the main C library is called libc_a and the maths library is called libm_a.

Thus to link with the math library, you would use -lm, to link with the standard C library -lc. A full library pathname is never given in this parameter, but you can specify a search path (using the -L option). So, if you wanted to link with a private library called libmine_a, which was in a directory flp1_mylib_ then the two options you would need on your command line are :

-Lflp1_mylib_ <object files .... > -lmine It is not actually necessary to specify the default C library (by using -lc) as if there are any outstanding references when all the libraries you have explicitly mentioned have been processed the libc_a library is automatically searched as the last library (although you do no damage if you specify it explicitly). The library includes most of the routines described in the C library description, along with many other run time routines that need to be included.
-mlisting_options This causes a listing file to be produced for the program. The name of the file produced is always output_file_name_map so if no output name has been specified then the map file will be called a_out_map. If the output file had been specified using -otest then the listing file would be called test_map.

The amount of detail included in the map file will depend on the options supplied. There must be at least one option, but you can specify more than one by simply concatenating them together (e.g. -mls). The options available are:
a A symbol listing will be produced in address order
l A library listing will be produced. This will indicate each library that is searched and where it is located. If the m option is also used, then the library detail lines will be inserted at the appropriate points in the module listing
m A module listing will be produced showing the details of each module that is included in the link. This will be in the order in which the modules are included.
s A symbol listing will be produced giving symbols in alphabetical order, and showing for each symbol where it is defined
x A cross-reference listing will be produced showing for each symbol where it has been called from. This option will also imply the l option as that information is also listed for each symbol.

Note, however, this will miss any cases where the reference to a symbol is in the same module that it is defined in as this is handled purely at the assembler stage.

There is also a listing summary produced that shows the link statistics. This is inserted after the library/module listings and before the more detailed symbol listings.

Note that if the -v option is used and there is no listing file being produced, then this summary information is written instead to the console.

Default:
-ooutputfile This allows the name of the output file to be specified. For example using a -otest would cause a program called test to be produced

Default: -oa_out
-Rname[/version] This indicates that LD is to build a RLL rather than a normal program. The name part of the parameter is the name that will be given to the RLL thing. This has a maximum length of 16 characters - and more than this will be ignored.

The (optional) version part is the version number (which is of the form m.nn where m is the major version number and nn is the minor version number. In practise LD will do no validation on this version number beyond checking its length to be 4 characters and will simply copy the value supplied into the RLL header. If the version number information is not supplied, then a value of "1.00" will be used.

The use of this parameter will also modify the default behaviour of LD as follows:

  • The default start-up module is changed to be rll_o as this is the one normally needed when building a RLL.
  • The output program will have any required UDATA space included in the file to simplify the loading process for the RLL Runtime Link Manager (RLM).

-rlibname

 Search a RLL library. A RLL library is one that is dynamically linked to a program at runtime. Although LD does not add it to the output file it does search it to determine which external references would be satisfied by including this library. The same locations will be searched as are specified earlier for the -l option.

The name of a RLL library is made in a similar way to that for statically linked libraries except that the extension is _rll. For example the maths library would be specified by using -rm which would cause LD to look for a RLL library called libm_rll.

RLL libraries can also have what are called "RLL stub libraries". These are small statically linked libraries that need to be linked in to help interface to a RLL. These have the same name as the associated RLL, but with an extension of _rls. Therefore the stub version of the maths library specified using -lm would be libm_rls. LD will look for such a stub library any time a RLL is specified, and if there is one it will statically link it in before the RLL library file. However stub libraries are optional, and no error will be given if no stub library is found.

Note that if a RLL library is linked in, it is necessary for this library to also be present at runtime for the program to run successfully. For more information on the RLL system see the main RLL documentation.

The other point to note is that no RLLs are linked in by default, not even the libc_rll file. This is to ensure that unless the user explicitly asks for RLLs to be used the default action is to do static linking as in earlier releases of the LD linker. When the RLL system is well established this behaviour may well be reversed to make RLL linking the default for the standard C libraries.
-sstartup_file This option specifies a different start-up file from the standard one. Using the special format of -s- means that no start-up module is to be used.

The start-up file is the code that does all the run time relocation that allows C programs to run correctly where they have been loaded under QDOS. Unless you have written your own start-up file that does runtime relocation correctly it is probably best to leave this option alone.

If this parameter is omitted, then the start-up modules that are used will be:
crt_o for standard programs
rll_o for RLL libraries

The start-up file is searched for using the same paths as are used when searching for libraries (as described under the -l option). Examples on when you might want to used different values are:
-screspr_o if you are using C to build code that is going to be loaded as a resident extension rather than used as an EXECable program. For more details see the C68QDOS_doc documentation file.
-s- if you are going to use LD as a replacement for the LINK linker and you are not writing C68 compiled code.

-U Treat all external references as upper case.

This version of LD treats external references as case significant as this is the normal convention for C programs. However LD v1.x and the LINK linkers treat all external references as though they were upper case. Use this option to force compatibility with the way these earlier linkers handled the case of external symbols.

-V Output a message giving information about the version of LD being used. This message will be sent to the listing file if one is to be produced, and otherwise to the console.
-v This means run in verbose mode. It also implies the -V parameter. This will always cause the program version to be output and a link summary to always be produced. If no listing file is being output these will be sent to the console, otherwise to the listing file.
-z option(s) Specify what should be included in the binary file that will be produced. If you want to specify more than one of the available options, then they should all be written using a plus ('+') symbol as the separator.

The options available are:
defs Force a fatal error if undefined symbols remain at the end of the link process. This is the default action.
nodefs Allow undefined symbols. This might be used if you are developing a program and you know the symbols in question will not be used. It can also be used when building a RLL to allow an undefined RLL to be linked in dynamically at run-time. However as any attempt by a program to actually use an undefined symbol is likely to cause a system crash this option should be used with extreme caution.
udata Store any UDATA space as part of the file data rather than simply storing the size required as part of the information in the file header.

This is the default if building a RLL

You are recommended to use this parameter when building code that is to be loaded via RESPR or LRESPR instructions.
xref Include a list of any unsatisfied external references in the program, and the details of the RLL that will satisify them. This is very similar to the -nodefs option mentioned above, except that this option expects you to have used the -r option to specify the RLL that will be used to satisfy the reference at runtime.

This is automatically assumed when the -r parameter is used to link in a RLL.
xdef Include a list of externally visible definitions that are contained in this program or RLL.

This is automatically assumed when you have used the -R parameter to specify that you are building a RLL.

The following options will also be recognised by LD for compatibility with earlier versions, but they will simply be ignored and have no effect. This is because the relevant areas are now allocated dynamically
-buflsize[K] This allowed the user to specify the buffer size in reading the object files and library files.

LD v2 will allocate this area dynamically as required, so it is not necessary to define this explicitly any more.
-bufpsize[K] This allowed the user to specify the size of buffer to hold the complete image of the program that is being linked.

LD v2 will allocate this area dynamically as required, so it is not necessary to define this explicitly any more.

Following the options the object files to link are specified. These may be any valid QL filename, with the directory extensions provided by a C program (eg.test_o, test1_o, etc.). No wildcards are allowed in the LD command line as the order of files linked is important in LD, and this could not be guaranteed if wildcards were used.

The linker produces files that are smaller than the equivalent produced by the GST LINK linker. The program files produced set the job data size field in the QDOS files header. THIS MUST NOT BE MADE SMALLER by any toolkit routine as if this is done the programs produced will FAIL to relocate properly at runtime and crash the QL ! YOU HAVE BEEN WARNED! Making it bigger is a waste of space as this data area is only used during program initialisation, and is not used for the runtime stack or heap.

ENVIRONMENT VARIABLES

The LD linker will make use of the Environment Variables specified below if they are set. These environment variables are processed before the command line options, so in the event of any clash, the command line parameters will take precedence.
LIB_DIR This can be used to specify the default program directory.
LD_OPTS Any parameters that would be valid on the LD command line can be set in this environment variable

START OF UDATA AREA

This section is only relevant to those who are trying to make advanced use of LD. In normal use one will not need to use (or even understand) the contents of this section.

It revolves around the fact that normally the information held in the BSS section of a program or RLL is often only required at initial load time. After that it is no longer required. It would therefore save on memory if this space could be re-used for other purposes. Most programs also contain a UDATA section that is used to hold uninitialised data. If you can re-use this space after the initialisation phase is finished then the program will need less memory to run.

Another aspect to consider is whether any space for the UDATA area should actually be included in the data stored as part of the program file header. Doing so reduces the size of the file stored on disk, but means that the loading process needs to take account of this.

The algorithm used by default with LD is as follows:

This default behaviour can be modified by use of the various -f and -z runtime options.

CHANGE HISTORY

This section details the major changes that have been made to this document. It is intended primarily for those who are upgrading their release of C68 to help them identify when and where new information has been included.
31 Dec 93 DJW Added section on Environment Variables that LD will now recognised
28 Mar 96 DJW Updated to reflect the new options that are now available for use with LD version 2
01 Aug 97 DJW Changes to reflect conversion to HTML format.