Commands Reference, Volume 3

ld Command

Purpose

Links object files.

Syntax

ld [ -DNumber ] [ -eLabel ] [ -G ] [ -HNumber ] [ -K ] [ -m ] [ -M ] [ -oName ] [ -r ] [ -s ] [ -SNumber ] [ -TNumber ] [ -u Name ] ... [ -v ] [ -z ] [ -ZString ] ... [ -bOption ] ... [ -LDirectory ] ... { -fFileID ... -lName ... InputFile ... }

Description

The ld command, also called the linkage editor or binder, combines object files, archives, and import files into one output object file, resolving external references. It produces an executable object file that can be run. In addition, if you specify the ld command without the -s flag, you can use the output file as an InputFile parameter in another call to the ld command. By default, the ld command creates and places its output in the a.out file.

The ld command can relink a program without requiring that you list all input object files again. For example, if one object file from a large program has changed, you can relink the program by listing the new object file and the old program on the command line, along with any shared libraries required by the program. See Examples.

The ld command links input files in the order you specify on the command line. If you specify a file more than once, only the first occurrence of the file is processed. You must specify at least one input file, either with the -bI (uppercase letter i), -bimport, -bkeepfile, -f, or -l (lowercase letter L) flag or as an InputFile parameter. (The -bI, -bimport, or -bkeepfile flag is the -b flag used with the I, import, or keepfile option.)

Use the cc command to link files when you are producing programs that run under the operating system. Because the cc command calls the ld command with common options and necessary support libraries, you do not need to specify them on the command line. (This information is read from the /etc/xlC.cfg or /etc/vac.cfb configuration file.)

Linking Mode

The ld command can link 32-bit objects and programs as well as 64-bit objects and programs, but 32-bit and 64-bit objects may not be linked together. To specify the mode for linking, you can use the OBJECT_MODE environment variable or the -b32 or -b64 options.

Archive Files

Archive files are composite objects, which usually contain import files and object files, including shared objects. If an archive file contains another archive file or a member whose type is not recognized, the ld command issues a warning and ignores the unrecognized member. If an object file contained in an archive file has the F_LOADONLY bit set in the XCOFF header, the ld command ignores the member. This bit is usually used to designate old versions of shared objects that remain in the archive file to allow existing applications to load and run. New applications link with the new version of the shared object, that is, another member of the archive.

Shared Objects

A shared object, usually created by another call to the ld command, is an object file with the F_SHROBJ bit set in the XCOFF header. A shared object defines external symbols that are resolved at run time. If you specify the -bnso or -bnoautoimp option, the ld command processes a shared object as an ordinary object file, and if the file is stripped, the link fails.

Ordinarily, a shared object used as input is only listed in the loader section of the output file if a symbol in the shared object is actually referenced. When the run-time linker is used, however, you might want shared objects to be listed even if there are no symbols referenced. When the -brtl option is used, all shared objects listed on the command-line that are not archive members are listed in the output file. The system loader loads all such shared objects when the program runs, and the symbols exported by these shared objects may be used by the run-time linker. Shared objects that are archive members are not loaded automatically unless automatic loading is enabled by an import file in the archive. To enable automatic loading, see Import and Export File Format (-bI: and -bE: Flags).

Import and Export Files

Import files are ASCII files that identify the external symbols to resolve at run time. An import file identifies the shared object defining the imported symbols. The system loader finds and resolves those symbols at run time. If the first line of an import file begins with #! (#, exclamation point), you can specify the file on the command line as an ordinary InputFile. Otherwise, you must use the -bI or -bimport option to specify the import file.

Export files are ASCII files that identify external symbols that are made available for another executable object file to import. The file format of an export file is the same as the file format of an import file.

Libraries

Libraries are files whose names end in .a, or possibly .so. To designate a library, you can specify an absolute or relative path name or use the -l (lowercase letter L) flag in the form -lName. The last form designates a libName.a file, or in dynamic mode, a libName.so file, to be searched for in several directories. These search directories include any directories specified by -L flags and the standard library directories /usr/lib and /lib.

Processing

The ld command processes all input files in the same manner, whether they are archives or not. It includes the symbol tables of all objects, discarding only symbol definitions that duplicate existing symbols. Unlike some other versions of the ld command, you do not need to order archive files so references precede definitions. Furthermore, you do not need to list an archive file more than once on the command line.

The order of the ld command flags does not affect how they are processed, except for the flags used with input object files, libraries, and import files. These flags are: -L, -f, -l (lowercase letter L), -bkeepfile, and -bI (uppercase letter i). The flags are processed in the following order:

1. The -L flag adds a directory to the list of search directories to locate libraries specified by the -l (lowercase letter L) flag. The directories are searched in the order specified. All -L flags are processed before any -l flags are processed.
2. The ld command processes the InputFile parameters, the files specified by the -f flag and libraries specified by the -l (lowercase letter L) flag in the order specified.
3. The ld command processes import files specified by the -bI (uppercase letter i) flag in the order specified after processing all other object files and libraries. You can specify an import file as an input file without the -bI flag if it is necessary to process the file before processing some object files. In this case, the first line of the import file must begin with the #! (#, exclamation point) symbols, and the import file is processed with other input files as described in step 2.
4. The -bkeepfile option names an input file on which the ld command does not perform garbage collection. If the specified input file is also specified as an InputFile parameter or listed in a file specified by the -f flag, the -bkeepfile option does not affect the order in which the file is processed. Otherwise, the file is processed in order along with other input files, as described in step 2.

An output file produced by the ld command has execute permission set, unless you specify the -r flag or -bnox option or errors were reported while linking. An existing output file is not overwritten if any severe errors occurred, or if the output file was specified as an input file and any errors occurred.

Symbols

The ld command uses the following predefined symbols to provide special address locations and can be declared in C syntax as extern char name[ ].The symbol names are:

The only way to use these symbols is to take their addresses. If an input file redefines any of these symbols, there may be unpredictable results. An additional predefined symbol, _ptrgl, is used by compilers to implement calls using function pointers.

Garbage Collection

By default, the ld command performs garbage collection, deleting control sections (CSECTs) that are not referenced when generating the output file.

A CSECT is an indivisible unit of coding or data. A CSECT references another CSECT if it contains a relocation entry (RLD) referring to a symbol contained in the other CSECT. A referenced CSECT causes all CSECTs it references to be referenced as well. In addition, a CSECT is referenced if it contains exported symbols, symbols specified with the -u flag, or the symbol designated as the entry point with the -e flag.

If a symbol is not referenced but is needed in the output file, you can export the symbol, specify the symbol with the -u flag, or suppress garbage collection. To suppress garbage collection, use the -r flag or -bnogc option. To suppress garbage collection for individual object files, use the -bkeepfile option or the -bgcbypass option. Even when garbage collection is suppressed, unreferenced internal symbols are deleted.

Ignored and Unsupported Flags

For compatibility with other versions of the ld command, some flags are recognized but ignored. These flags produce a message stating that the flag and its operand were ignored. An ignored flag does not cause the ld command to stop without further processing. The following flags are ignored:

-ANumber         -bnostrcmpct     -n
-bfilelist       -bstrcmpct       -N
-bfl             -BNumber         -Q
-bforceimp       -d               -RNumber
-bi              -i               -VNumber
-binsert         -j[Key:]Number   -x
-bnoforceimp     -kKey:Path       -YNumber

Flags that the ld command does not support result in an error message. After all unsupported flags are diagnosed, the ld command stops without further processing.

Flags

The ld command conforms to the XPG Utility Syntax Guidelines, except that the argument -- only applies to the next operand, not to the remaining operands on the command line. For example, in the command line:

ld -- -s -v

The -s is treated as a filename and the -v is treated as a flag. To have -v treated as a filename, specify:

ld -- -s -- -v 

The Binder

The ld command verifies the command-line arguments and calls the binder (by default the /usr/ccs/bin/bind file), passing a generated list of binder subcommands. The binder program actually links the files. Although the binder is usually called by the ld command, you can start the binder directly. In this case, the binder reads commands from standard input.

Two options affect the calling of the binder. The binder option specifies which binder to call, and the nobind option prevents the ld command from calling a binder. Other binder options affect the binder subcommands that are generated.

If the ld command does not detect any errors in the options or command-line arguments, it calls the binder. The binder is called with a command line of the form:

bind [quiet_opt] [loadmap_opt]

The default value for quiet_opt is quiet and the default value for the loadmap_opt is the null string, so the default command line is:

/usr/ccs/bin/bind quiet

Options (-bOptions)

The following values are possible for the Options variable of the -b flag. You can list more than one option after the -b flag, separating them with a single blank.

1. In the following list of binder options, two option names separated by the word or are synonymous.
2. The FileID indicates a path name. You can use either a relative or a full path name.
3. For a non-repeatable option that is followed by an argument, you can negate the option using a null argument. That is, specify only the option and the colon.
4. If you specify conflicting options, the last one takes precedence.

-2,147,483,640 to -2,147,000,000
-1,999,999,999 to -1,000,000,000
   -99,999,999 to -50,000,000
             0
    50,000,000 to 99,999,999
 1,000,000,000 to 1,999,999,999
 2,147,000,000 to 2,147,483,640

# autoload 
#! (foo.o) 

-bautoload:<archive_name>(foo.o)

Run-time Linking

By default, references to symbols in shared objects are bound at link time. That is, the output module associates an imported symbol with a definition in a specific shared object. At load time, the definition in the specified shared object is used even if other shared objects export the same symbol.

You can cause your program to use the run-time linker, allowing some symbols to be rebound at load time. To create a program that uses the run-time linker, link the program with the -brtl option. The way that shared modules are linked affects the rebinding of symbols.

You can build shared objects enabled for run-time linking by using the -G flag. You can fully enable run-time linking for existing shared objects by relinking them with the rtl_enable command, as long as they have not been stripped.

Import and Export File Format (-bI: and -bE: Flags)

Each line within an import or export file must list a single symbol, followed by optional keywords or an optional address. Keywords are svc, svc32, svc3264, svc64, syscall, syscall32, syscall3264, syscall64, symbolic, nosymbolic, nosymbolic-, list, cm, bss, and weak. Only the keyword weak may be used in conjunction with another keyword.

In an import file, you can specify an address after the symbol to map data CSECTs to a shared memory segment and eliminate the need to use the assembler. You can also use one of the keywords cm, bss, or weak to specify the storage class of an imported symbol. When the autoexp option is used, the storage class of an imported symbol affects which symbols are automatically exported. If any other keyword is specified in an import file, the keyword is ignored.

In an export file, you can use the svc or syscall keyword after a name to indicate that it is a system call. This is needed when linking kernel extensions. You can use the symbolic, nosymbolic, or nosymbolic- keyword to associate an attribute with an exported symbol. For more information, see Attributes of Exported Symbols. You can use the list keyword to cause a symbol to be listed in the loader section of the output file, although it will not be marked as an exported symbol. This can be used for applications that want to process some symbols at run time. Listed symbols are not processed by the system loader or the run-time linker. A symbol address and the keywords cm and bss are ignored in an export file. The weak keyword can be used to specify weak symbol binding, and may be used with another attribute.

The ld command treats import and export files according to the following guidelines:

• A blank line is ignored.
• A line beginning with an * (asterisk) is a comment and is ignored.

• A line beginning with a # (#, blank space) provides operands to the setopt binder subcommand (-bdbg:Option). For example, a line containing # verbose causes the binder to list each symbol as it is read from the file. These option settings are active only while processing the file. The # 32, # 64, # no32, and # no64 options can be used to specify whether the listed symbols should be used for 32-bit links, 64-bit links, or both.

  32-bit and 64-bit Import File Options

  32	This option is used in an import or export file to specify that subsequent symbols should be processed when linking in 32-bit mode, but ignored when linking in 64-bit mode. If no 32 or 64 option is specified, all symbols are processed in both 32- and 64-bit modes.
  64	This option is used in an import or export file to specify that subsequent symbols should be processed when linking in 64-bit mode, but ignored when linking in 32-bit mode. If no 32 or 64 option is specified, all symbols are processed in both 32- and 64-bit modes.
  no32 or no64	Override a previous 32 or 64. Subsequent symbols are processed in both 32- and 64-bit modes.

• When processing an import file, a line beginning with a #! (#, exclamation point) provides the shared library name to be associated with subsequent import symbols. The line can occur more than once and applies to subsequent symbols until the next line beginning with #! is read. This file name information is placed in the loader section of the XCOFF object file. It is used by the system loader to locate the appropriate object file at execution time. If the import file name is ipath/ifile (imember), the file name placed in the loader section is determined based on the import file name and the contents of the #! line of the import file, as follows:

  #!	(Nothing after the #!) Use null path, null file, and null number. This is treated as a deferred import by the system loader.
  #! ()	Use ipath, ifile, and imember. This line can be used if the import file is specified as an InputFile parameter on the command line. The file must begin with #! in this case. This line can also be used to restore the default name if it was changed by another #! line.
  #! path/file (member)	Use the specified path, file, and member.
  #! path/file	Use the specified path and file, and a null member.
  #! file	Use a null path, the specified file, and a null member. At run time, a list of directories is searched to find the shared object.
  #! (member)	Use ipath, ifile, and the specified member. At run time, a list of directories is searched to find the shared object.
  #! file (member)	Use a null path and specified file and member. At run time, a list of directories is searched to find the shared object.
  #! .	(A single dot) This name refers to the main executable. Use this file name when you are creating a shared object that imports symbols from multiple main programs with different names. The main program must export symbols imported by other modules, or loading will fail. This import file name can be used with or without the run-time linker.
  #! ..	(Two dots) Use this name to list symbols that will be resolved by the run-time linker. Use this file name to create shared objects that will be used by programs making use of the run-time linker. If you use a module that imports symbols from .. in a program that was not linked with the rtllib option, symbols will be unresolved, and references to such symbols will result in undefined behavior.

To automatically load archive members when the -brtl option is used, you can create an import file as follows. If shr.so is a shared object in an archive, create an import file:

# autoload
#! (shr.so)

You can list additional member names on additional lines, if appropriate. You do not need to list symbol names in the import file because the symbols imported from shr.so will be read from shr.so itself.

For more information on creating a shared library, see "How to Create a Shared Library" in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs. For more information on loading and binding, see the load subroutine in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 1.

Attributes of Exported Symbols

When you use run-time linking, a reference to a symbol in the same module can only be rebound if the symbol is exported with the proper attribute. References to symbols with the symbolic attribute cannot be rebound. References to symbols with the nosymbolic attribute can be rebound. References to symbols with the nosymbolic- attribute can be rebound if the symbols are variables. For function symbols, calls using a function pointer can be rebound, while direct function calls cannot be rebound. The nosymbolic- attribute is the default and is provided for compatibility with previous versions of the operating system, but its use is not recommended.

If you are not using the run-time linker, avoid using the nosymbolic attribute because intra-module function calls will be made indirectly through a function descriptor using global-linkage code. Otherwise, the attribute of exported symbols has no effect for modules used with programs that do not use the run-time linker.

You can specify an explicit export attribute for symbols listed in an export file. Most symbols without an explicit attribute are exported with the default export attribute, as specified with the symbolic, nosymbolic, or nosymbolic- options.

The weak export attribute will mark the associated symbol's mapping type with L_WEAK in the loader section.

Imported symbols may only have the weak export attribute. If a symbol is imported from another module, all references to the symbol can be rebound. However, if a symbol is imported at a fixed address, all references are bound to this fixed address and cannot be rebound by the run-time linker. The system loader must resolve deferred imports. The run-time linker never resolves or rebinds references to deferred imports.

For exports of non-imported symbols, the following rules are used.

• If a symbol has the list attribute, it is listed in the loader section symbol table, but the L_EXPORT flag is not set in the symbol table entry. The run-time linker ignores such symbols.
• If a symbol was exported with an explicit attribute, the explicit attribute is used.
• If the symbol is a BSS symbol, it is exported with the nosymbolic attribute.
• Otherwise, the symbol is exported with the global attribute, as specified by the symbolic, nosymbolic, or nosymbolic- option. The default global attribute is nosymbolic-.

Address Maps

The ld command generates address maps, listing the layout of symbols in the output object file. If you use the map (or R) option, unresolved symbols and imported symbols are listed first, followed by the symbols in each section in address order. If you use the calls (or C) option, each symbol that is listed is followed by a list of references from that symbol to other symbols. If you use the xref (or X) option, each symbol that is listed is followed by a list of references to that symbol from other symbols. If you use the smap, scalls, or sxref option, the address map contains the same information as listed by the map, calls, or xref option, respectively, but symbols are listed in alphabetical order.

Internal symbols, with a storage class C_HIDEXT, are printed with the characters < and > (angle brackets) surrounding the symbol name. Names of external symbols, with a storage class C_EXT, are printed without the angle brackets, and those with a storage class of C_WEAKEXT, are printed with the characters { and } surrounding the symbol name.

Information listed about each symbol includes:

• An indication of whether the symbol is imported, exported, or the entry point. An * (asterisk) is used to mark the entry point, I is used to mark imported symbols, and E is used to mark exported symbols.
• Its address (except for imported symbols)
• Length and alignment (for CSECTs and BSS symbols)
• Storage-mapping class
• Symbol type
• Symbol number (used to differentiate between symbols of the same name)
• Symbol name
• Input file information

Storage-mapping classes and symbol types are defined in the /usr/include/syms.h file. In the address maps, only the last two characters are shown, except that storage-mapping class XMC_TC0 is shown as T0.

The input file information depends on the type of input file. For object files, source files names obtained from C_FILE symbols table entries are listed. If the object is from an archive file, the object file name is listed in the following format:

ArchiveFileName[ObjectName]

A shared object name is listed between { } (braces). If a shared object is defined by an import file, the name of the import file is listed before the shared object name.

Import symbols have a symbol type of ER, but they have associated file input information. Undefined symbols are also listed with a symbol type of ER, but all other columns, except the symbol number, are left blank.

The -T and -D flags (or pT or pD options) affect the addresses printed in these address maps. For machine-level debugging, it is helpful to choose address so that symbols are listed with the same addresses that they have at run time. For a 32-bit program that does not use privately loaded shared objects, you can choose the proper addresses by specifying the -bpT:0x10000000 and -bpD:0x20000000 options. These options are defined by default in the /etc/xlC.cfg or /etc/vac.cfg file.

Environment Variables

The following environment variables affect the execution of the ld command:

Examples

1. To link several object files and produce an a.out file to run under the operating system, type:

   ld /usr/lib/crt0.o pgm.o subs1.o subs2.o -lc

   The -lc (lowercase letter L) links the libc.a library. A simpler way to accomplish this is to use the cc command (the compiler) to link the files as follows:

   cc  pgm.o  subs1.o  subs2.o

2. To specify the name of the output file, type:

   cc  -o pgm  pgm.o  subs1.o  subs2.o

   This creates the output in the file pgm.

3. To relink pgm if only the object file subs1.o has changed, type:

   cc -o pgm subs1.o pgm

   The CSECTs that originally came from object files pgm.o and subs2.o are read from the file pgm. This technique can speed the linking process if a program consists of many input files, but only a few files change at a time.

4. To link with library subroutines, type:

   cc  pgm.o  subs1.o  subs2.o  mylib.a  -ltools

   This links the object modules pgm.o, subs1.o, and subs2.o, the subroutines from the mylib.a archive, and the subroutine from the library specified by -l (lowercase letter L) flag. (This means the /usr/lib/libtools.a file).

5. To generate a shared object, type:

   ld -o shrsub.o subs1.o subs2.o -bE:shrsub.exp -bM:SRE -lc

   This links the object files subs1.o, subs2.o, and the subroutines from the library libc.a specified by -lc flag. It exports the symbols specified in the file shrsub.exp and stores the linked shared object in file shrsub.o. The -bM:SRE sets the shared object flag in the linked object file.

6. To link with the shared object shrsub.o generated previously, type:

   cc -o pgm pgm.o shrsub.o -L '.'

   This links the object file pgm.o with the exported symbols of shrsub.o. The linked output is stored in the object file pgm. The -L '.' adds the current directory to the library search path that the system loader uses to locate the shrsub.o shared object. At run time, this program is loaded only if it is run from a directory containing an instance of the shrsub.o file or if the shrsub.o file is found in the /usr/lib standard library directory. To allow the program to be run from anywhere, use the option -L `pwd`.

   The list of directories searched by the system loader can be seen using the dump command.

7. To link a program using the libc.a library as a non-shared library, type:

   cc -o pgm pgm.o -bnso -bI:/lib/syscalls.exp

   This links pgm.o with the necessary support libraries and names the output file pgm. For the cc command, the libc.a library is a necessary support library and is usually link-edited to the user's program as a shared library. In this example, the -bnso option directs the ld command to link with the libc.a library as a non-shared library, and the -bI:/lib/syscalls.exp directs the ld command to import the system call functions that are actually contained in the kernel or /usr/lib/boot/unix file. Whenever linking with the -bnso option, any symbols that were both imported and exported (that is, passed through) in a shared object must be explicitly imported, as is done by the -bI:/lib/syscalls.exp option in this example.

   Note
   Any time that /usr/lib/libc.a is linked non-shared, the flag -bI:/lib/syscalls.exp must be used. The application can also have to be linked again whenever an updated release of the operating system is installed. Any application that is statically linked is not binary portable from any fix or release level to any other fix or release level.

Files

Related Information

The ar command, as command, nm command, dump command, rtl_enable command, strip command.

The a.out file format.

The glob subroutine, load subroutine, loadbind subroutine, loadquery subroutine, unload subroutine.

"How to Create a Shared Library" in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

"Large Program Support Overview" in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

"Shared Libraries and Lazy Loading" in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

"Shared Library Overview" in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

"XCOFF (a.out) File Format" in AIX 5L Version 5.2 Files Reference.