ld Command
Purpose
Links object files.
Syntax
ld [ -D Number ] [ -e Label ] [ -G ] [ -H Number ] [ -K ] [ -m ] [ -M ] [ -o Name ] [ -r ] [ -s ] [ -S Number ] [ -T Number ] [ -u Name ] ... [ -v ] [ -V ] [ -z ] [ -Z String ] ... [ -b Option ] ... [ -L Directory ] ... { -f FileID ... -l Name ... InputFile ... }
or
ld -bsvr4 [ -d[y | n
] ] [ -D Number ] [ -e Label ] [ -G ] [ -H Number ] [ -K ] [ -m ] [ -M ] [ -o Name ] [ -r ] [ -R Path ] [ -s ] [ -S Number ] [ -T Number ] [ -u Name ] ... [ -v ] [ -V ] [ -z [ defs | nodefs ] ] [ -z multidefs ] [ -z [text | nowarntext | warntext ] ] ] [ -Z String ] ... [ -b Option ] ... [ -L Directory ] ... { -f FileID ... -l Name ... InputFile ... }
Description
The ld command that is 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 you to again list all input object files. For example, if one object file from a large program is 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 that you specify on the command line. If you specify a file more than once, only the first occurrence of the file is processed. 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 that is 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.cfg 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 that is contained in an archive file has the F_LOADONLY bit set in the XCOFF header, the ld command ignores the member. This bit is 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 that is used as input is only listed in the loader section of the output file if a symbol in the shared object is referenced. When the run-time linker is used, however, you might want shared objects to be listed even if there are no symbols that are referenced. When the -brtl option is used, all shared objects that are 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 runtime 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
- 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:
- 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.
- 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.
- 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.
- 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 that is 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 that is 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:Item Description _text
Specifies the first location of the program. _etext
Specifies the first location after the program. _data
Specifies the first location of the data. _edata
Specifies the first location after the initialized data _end
orend
Specifies the first location after all data. The only way to use these symbols is to take their addresses. If an input file redefines any of these symbols, there might be unpredictable results. An extra predefined symbol,
_ptrgl
, is used by compilers to implement calls by 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 that are 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 that stats 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
Note: When the -bsvr4 option is present on the ld command line, the -R and -z options are redefined.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 —
applies only to the next operand, not to the
remaining operands on the command line. For example, in the command line if you type ld --
-s -v
, the -s is treated as a file name and the
-v is treated as a flag. To treat -v
as a file name, type
ld -- -s -- -v
.
Item | Description |
---|---|
-bOption | Sets special processing options. This flag can be repeated. For more information about these options, see Options (-bOptions). |
-d [y | n ] |
When -dy is specified, ld uses dynamic linking; this option is equivalent to the -b so option. When -dn is specified, ld uses static linking; this option is equivalent to the -b nso option. The default is -dy. This option is valid only when the -bsvr4 option is specified. |
-D Number | Sets the starting address for the initialized data (the data section) of the output file to
Number. If the specified number is -1, the data section starts immediately after
the text section. By default, the data section begins at location 0. If both the -D and -bpD flags are specified, the latter flag takes precedence. Note: The system loader relocates the data section at run time, so the specified number affects the
addresses that are listed in address maps or printed by utilities such as the
dump or nm command.
|
-e Label | Sets the entry point of the executable output file to Label. The default
entry point is __start (double underscore start ). |
-f FileID | Specifies a file that contains a list of input files to process. FileID
must contain a list of input file names. Each line in FileID is treated as if it
were listed separately on the ld command line. Lines in the file can contain
shell pattern characters * (asterisk), [ (left bracket),
] (right bracket), and ? (question mark), which are expanded by
using the glob subroutine and can designate multiple object files. |
-G | The -G produces a shared object that is enabled for use with the runtime linker. The -G flag is equivalent to specifying the erok, rtl, nortllib, nosymbolic, noautoexp, and M:SRE options with the -b flag. Subsequent options can override these options. |
-H Number | Aligns the text, data, and loader sections of the output file so that each section begins on
a file offset that is a multiple of Number. If the specified number is 1, no
alignment occurs. If the specified number is 0, the loader section is aligned on a word boundary,
and the text and data sections are aligned on a boundary to satisfy the alignment of all CSECTs in
the sections. The default value is 0. If the specified Number causes any CSECTS to be unaligned within the output file, the ld command issues a warning and the output executable file might not load or run. |
-K | Aligns the header, text, data, and loader sections of the output file so that each section begins on a page boundary. This flag is equivalent to specifying -H Number, where Number is the page size of the machine on which ld is running. |
-l Name | Processes the libName.a file. In
dynamic mode, with the rtl option, processes the
libName.a or
libName.so file. In all cases, directories that are
specified by the -L flag or in the standard library directories
(/usr/lib and /lib) are searched to find the file. In
dynamic mode with the rtl option, the first directory that contains either
libName.so or
libName.a satisfies the search. If both files are found in
the same directory, the libName.so file is used. You can
repeat this flag. For more information about dynamic mode, see Run-time Linking.
Note: The first definition of a symbol is kept, even if no reference to the symbol is seen when the
archive is read. In other versions of the ld command, a symbol that is defined in
an archive is ignored if no reference to the symbol is seen when the archive is read.
|
-L Directory | Adds Directory to the list of search directories that are used for finding libraries that are designated by the -l (lowercase letter L) flag. The list of directories, including the standard library directories, is also recorded in the output object file loader section for use by the system loader unless you use the -blibpath, -bnolibpath, or -bsvr4 option. You can repeat this flag. |
-m or -M | Lists to standard output the names of all files and archive members that are processed to create the output file. Shared objects and import files are not listed. |
-o Name | Names the output file Name. By default, the name of the output file is a.out. |
-r | Produces a nonexecutable output file to use as an input file in another ld command call. This file might also contain unresolved symbols. The -r flag is equivalent to specifying the erok, noglink, nox, and nogc options with the -b flag. (Subsequent options can override these options.) |
-R Path | Valid only when the -bsvr4 option is present on the ld command line. It defines a colon-separated list of directories that are used to specify library search directories to the runtime linker. Path, if present and not NULL, is recorded in the output file's loader section. Then it is used when linking an executable file with shared libraries at run time. Multiple instances of this option are concatenated together with each Path separated by a colon. |
-s | Strips the symbol table, line number information, and relocation information when creating
the output file. Stripping saves space but impairs the usefulness of the debuggers. You can also
strip an existing executable file by using the strip command. Note: Nonshared
objects cannot be linked if they are stripped. A shared object can be stripped, but a stripped,
shared object cannot be used when linking statically.
|
-S Number | Sets the maximum size (in bytes) allowed for the user stack when the output executable
program file is run. This value is saved in the auxiliary header and used by the system loader to
set the soft
ulimit. The default value is 0. For more information about large user stacks and 32-bit programs, see Large Program Support under General programming concepts topic. |
-T Number | Sets the starting address of the text section of the output file to
Number. The default value is 0. If both the -T and -bpT flags are specified, the latter flag takes precedence. Note: The system loader relocates the text section at run time, so the specified number affects
addresses that are listed in address maps or printed by utilities such as the nm
or the dump command.
Attention: If Number is
0x1000xxxxxxx and the
program that is linked is a 64-bit program, the system loader loads the executable text into memory
that starts from the segment at the address 0x10000000000 . |
-u Name | This option prevents garbage collection of the external symbol Name. If the specified symbol does not exist, a warning is reported. You can repeat this flag. |
-v | Writes additional information about binder command execution to the loadmap file. |
-V | Writes the version string of ld command to standard error (stderr). |
-z | In the absence of the -b svr4 option, the -z flag functions the same as the -K flag. |
-z defs | This option forces a fatal error if any undefined symbols remain at the end of the link. This option is the default when an executable file is built. It is also useful when building a shared library to assure that the object is self-contained, that is, that all its symbolic references are resolved internally. This option is valid only when the -b svr4 option is specified. It is equivalent to the -b ernotok option. |
-z nodefs | This flag allows undefined symbols. This option is the default when a shared library is built. When used with executable files, the behavior of references to such undefined symbols is unspecified. This option is valid only when the -b svr4 option is specified. It is equivalent to the -b erok option. |
-z multidefs | This option allows multiple symbol definitions. By default, multiple symbol definitions that occur between relocatable objects (.o files) results in a fatal error condition. This option suppresses the error condition and allows the first symbol definition to be taken. This option is valid only when the -b svr4 option is specified. |
-z text | In dynamic mode only, forces a fatal error if any relocations against the .text section remain. This option is valid only when the -b svr4 option is specified. |
-z nowarntext | In dynamic mode only, allows relocations against all mappable sections, including the .text section. This option is the default when building a shared library. This option is valid only when the -b svr4 option is specified. |
-z warntext | In dynamic mode only, warns if any relocations against the .text section remain. This option is the default when building an executable file. This option is valid only when the -b svr4 option is specified. |
-Z String | Prefixes the names of the standard library directories with String when searching for libraries specified by the -l (lowercase letter L) flag. For example, with the -Z test and -lxyz flags, the ld command looks for the /test/usr/lib/libxyz.a and /test/lib/libxyz.a files. When the -Z String flag is used, the standard library directories are not searched. This flag has no effect on the library path information that is saved in the loader section of the output file. This flag is useful when developing a new version of a library. You can repeat this flag. |
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 links the files. Although the binder is 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)
- In the following list of binder options, two option names that are separated by the word or are synonymous.
- The FileID indicates a path name. You can use either a relative or a full path name.
- For a nonrepeatable option that is followed by an argument, you can negate the option by using a null argument. That is, specify only the option and the colon.
- If you specify conflicting options, the last one takes precedence.
Item | Description |
---|---|
32 | Specifies 32-bit linking mode. In this mode, all input object files must be XCOFF32 files, or an error is reported. XCOFF64 archive members are ignored. For import or export files that specify the mode of certain symbols, 64-bit symbols are ignored. If both -b32 and -b64 options are specified, the last specified option is used. If neither option is specified, the mode is determined from the value of the environment variable OBJECT_MODE. |
64 | Specifies 64-bit linking mode. In this mode, all input object files must be XCOFF64 files, or an error is reported. XCOFF32 archive members are ignored. For import or export files that specify the mode of certain symbols, 32-bit symbols are ignored. If both -b32 and -b64 options are specified, the last specified option is used. If neither option is specified, the mode is determined from the value of the environment variable OBJECT_MODE. |
asis | Processes all external symbols in mixed case. This option is the default. To process all external symbols in uppercase, see the caps option that follows. |
aslr or aslr:[tdsmp]* or aslr:- |
Specifies the address space layout randomization for the program. The aslr
option enables all the randomization attributes when only this option is used, and
If the aslr option is followed by a colon, individual attributes can be
enabled. The following attributes denote text, data, stack, mmap, and private-libraries:
t, d, s, m, and
p. For the attributes that are not listed, the randomization settings remain
disabled.
Note: The m and p attributes cannot be specified for
32-bit programs.
Some programs are compiled and linked such that relocatable addresses are mapped into the text section. This option requires the relocation of the addresses when the program is run. These programs fail if randomization is enabled for text or data. As a result, when text-section relocations exist, text and data randomization are not enabled unless the t and d attributes are explicitly specified when by using the aslr option. |
autoexp | Automatically exports some symbols from the output module without having to list them in an
export file. (This option does not export all symbols from the output module. Use the
bexpall option to export all symbols.)This option is the default. Use this
option when linking a main program. The linker assumes that you are linking a main program when you
do not specify a module type (with the M or modtype
option) beginning with S and you do not use the noentry
option. When you use the autoexp option, if any shared object that is listed on the command-line imports a symbol from the special file . (dot), and the module that is linked contains a local definition of the symbol, the symbol is exported automatically. Other symbols are also exported automatically when you link with the rtl option. If a symbol defined in the module that is linked has one or more definitions that are exported from a shared object that are listed on the command-line, and if any of the definitions is a BSS symbol, the symbol is exported automatically. If the definition in the module that is linked is a BSS symbol, the symbol is exported with the nosymbolic attribute. Otherwise, the symbol is exported with the symbolic attribute. If the symbol is listed in an export file with another export attribute, the explicit attribute is used. If the autoexp option would automatically export a symbol, but the symbol is listed in an export file with the list attribute, the symbol is not exported. |
autoimp or so | Imports symbols from any shared objects that are specified as input files. The shared objects are referenced but not included as part of the output object file. This option is the default. |
autoload: path/file(member) | Automatically load the archive member. |
bigtls | Generates extra code if the size of thread-local storage in the output object or program is larger than 64 KB and a compiler was used that generates direct references to local-exec or local-dynamic thread-local variables. Extra code is needed for every direct reference to a thread-local variable that cannot be addressed with a 16-bit offset. Because a program that contains extra code might have poor performance, it is better to reduce the number of thread-local variables that use direct references than to use the option. The default option is the nobigtls option. |
bigtoc | Generates extra code if the size of the table of contents (TOC) is greater than 64 KB. Extra code is needed for every reference to a TOC symbol that cannot be addressed with a 16-bit offset. Because a program that contains generated code might have poor performance, reduce the number of TOC entries that are needed by the program before you use this option. The default is the nobigtoc option. When this option is used, the glink file /usr/lib/glinkl.o is used in 32-bit mode and /usr/lib/glinkl64.o is used in 64-bit mode. |
_ptrgl symbol as the target function and the
definition of the _ptrgl symbol is located at an offset of more than 32 MB from the
calling location. The function call might have been made by using the function pointer or the called
function is defined in a different module than the calling function. This option has no effect if
pointer glue is inlined by the compiler. |
|
bindcmds:FileID | Writes a copy of the binder commands that are generated by the ld command to FileID. You can redirect the resultant file as standard input to the binder program when the binder program is called as a stand-alone program. By default, no file is produced. |
binder:FileID | Uses FileID as the binder called by the ld command. The default binder is the /usr/ccs/bin/bind file. |
bindopts:FileID | Writes a copy of the binder program arguments to FileID. You can use the resultant file to start the binder program as a stand-alone program. By default, no file is produced. |
C:FileID or calls:FileID | Writes an address map of the output object file to FileID. Symbols are sorted by section and then by address. For each symbol listed in the map, references from the symbol to other symbols are listed. By default, no file is produced. To learn more about the calls option, see Address Maps. |
caps | Processes all external symbols in uppercase. The default is the asis option. |
cdtors[:[incl][:[nnn] [:order]]] | The linker gathers information about C++ static constructor or destructor functions and saves
this information in the output file. The incl suboption tells the linker which
archive members to search when creating the saved information. Following are the possible values:
The nnn suboption specifies the priority of the output module. If a program loads multiple modules at the same time, the nnn suboption is used to control the order in which modules are initialized. (The priority is ignored if the output file is a program and not a shared object.) The priority can be in the range from -231 to 231-1. The default priority is 0. Values in the range from -231 to -231+1023 are reserved for C++ runtime initialization. The order suboption specifies the order in which individual constructor or
destructor functions are called, for all functions with the same priority. Following are the
possible values:
You can specify this option multiple times, but the last suboption that you specify is used. An unspecified suboption does not affect the current or default value. For example, -bcdtors:csect:20:s -bcdtors:::r is the same as -bcdtors:csect::20:r. The default is -bnocdtors. If -bcdtors is specified, it is the same as -bcdtors:all:0:s. Note:
|
comprld or crld | Combines multiple relocation entries (RLDs) at the same address into a single RLD when possible. This option is the default. |
cror15 | Uses the cror 15,15,15 (0x4def7b82 ) instruction as the
special no-op instruction that follows a call instruction. The default value is ori 0, 0,
0 (0x60000000 ). See the nop option. Use this option when linking object files on the current level of the system that you intend to relink on AIX® 3.1. |
cror31 | Uses the cror 31,31,31 (0x4ffffb82 ) instruction as the
special no-op instruction that follows a call instruction. The default value is ori 0, 0,
0 (0x60000000 ). See the nop option. Use this option when linking object files on the current level of the system that you intend to relink on AIX 3.2. |
D: Number [/dsa] or maxdata:Number[/dsa] | Sets the maximum size (in bytes) that is allowed for the user data area (or user heap) when
the executable program is run. This value is saved in the auxiliary header and used by the system
loader to increase the soft data limit, if required. The default value is 0. When this option is
used, the specified number of bytes are reserved for the user data area. The program might not
explicitly map objects, by using shmat or mmap functions
to virtual addresses that are reserved for the user data area. For 32-bit programs, the maximum
value that is allowed by the system is For 64-bit programs, the maxdata option provides a guaranteed maximum size
for the programs data heap. Any value can be specified but the data area cannot extend past
|
datapsize:psize | Requests psize page sizes in bytes for data. The value can be specified as
a decimal, hexadecimal, or octal number. The number specifications are the same as in the C
programming language. Also, the page size can be specified as a number followed by a one-character
suffix:
-b datapsize:16k or -b datapsize:0x4000
requests 0x4000 for data and set the F_VARPG bit in the XCOFF
header. |
dbg:Option or debugopt:Option | Sets a special debugging or control option. By default, no debug option is set. The dbg:loadabs or debugopt:loadabs option is used to indicate that the output program is loaded at the same address as the address specified by the -T and -D flags. In this case, a branch-absolute instruction is never changed to a (relative) branch instruction even if its target is a relocatable symbol. Similarly, a branch instruction is never changed to a branch-absolute instruction. |
delcsect | Deletes all symbols in a CSECT if any symbol in the CSECT was defined by a previously read
object file. This option prevents more than one instance of the same function from existing in the
same program. For example, if a.o file defines function a() and
b.o file defines functions a() and b() , linking
a.o and b.o with the -bdelcsect option
deletes symbols a() and b() from b.o . Thus, two
instances of a() do not exist. The default is the nodelcsect
option. |
dynamic or shared | Cause the linker to process subsequent shared objects in dynamic mode. This option is the default. In dynamic mode, shared objects are not statically included in the output file. Instead, the shared objects are listed in the loader section of the output file. When you specify the rtl option and dynamic mode is in effect, files that ends in .so as well as .a satisfy searches for libraries specified with the -l (lowercase L) flag. When both are in effect, preference is given to .so instead of .a when present in the same directory. When you specify the rtl option and static mode is in effect, files that ends in .a are processed. |
E:FileID or export:FileID | Exports the external symbols that are listed in the file FileID. Exported symbols are listed in the loader section of the output file. There is no default export file. When the svr4 option is used, the E:FileID option cancels any expall or expfull options. |
ernotok or f | Reports an error if there are any unresolved external references. This option is the default. |
erok | Produces the output object file without errors even if there are unresolved external references. The default is the ernotok option. |
errmsg | Writes error messages to standard error if the error level of the message is greater than or equal to the value of the halt option and the quiet option is used or standard output is redirected. This option is the default. |
ex1:FileID, ex2:FileID, ex3:FileID, ex4:FileID, and ex5:FileID | Provide user exits in the typical binder subcommand sequence. Each file that
is specified by FileID must contain a list of binder subcommands that runs as
follows:
|
expall | This option exports all global symbols, except imported symbols, unreferenced symbols that
are defined in archive members, and symbols that begin with an underscore (_). You can export more
symbols by listing them in an export file or by using the expfull option. This
option does not affect symbols that are exported by the autoexp option. When you use this option, you might be able to avoid this by using an export file. However, by using an export file provides explicit control over which symbols are exported, and allows the usage of other global symbols within the shared object without worrying about conflicting with names that are exported from other shared objects. The default is noexpall. |
expfull | This option exports all global symbols, except the imported symbols and the symbols that are defined in the archive members when the archive member is not used. Unlike the -bexpall option, the -bexpfull option exports symbols that begin with an underscore (_) and also exports the module entry point of the symbol. The actual behavior of the -bexpfull option might differ depending on the specific use case and the configuration of the runtime linker. The -bexpfull option does not affect symbols that are exported by the autoexp option. The default value is noexpfull unless the svr4 option is used with the -b flag. |
export:FileID | Functions the same as the E:FileID option. |
f | Functions the same as the ernotok option. |
forceimprw | Forces read-only CSECTs that contain references to imported symbols to become read or write. The default is noforceimprw. |
forkpolicy:policy | Sets the _AOUT_FORK_POLICY and _AOUT_FORK_COR flags in the XCOFF auxiliary header, when linking a 64-bit program. If policy is cor, the _AOUT_FORK_COR flag is also set, requesting the use of the copy-on-reference forktree policy when the program is run. If policy is cow, the _AOUT_FORK_COR flag is reset, requesting the use of the copy-on-write forktree policy when the program is run. When linking a 32-bit program, this flag is ignored. The default value is noforkpolicy. |
gc | Performs garbage collection. Use the nogc, gcbypass, or keepfile option to prevent garbage collection for some or all object files. This option is the default. |
gcbypass:Number | Specifies the number of files to bypass when garbage is collected if the gc option is specified. This option is ignored if the nogc option is used. If Number is 0, this option is equivalent to the gc option and garbage collection is performed for all files. The default value is 0. |
glink: FileID or glink=large or glink=small |
Uses the global linkage prototype code that is specified by FileID
Global-linkage interface code is generated for each imported or undefined function. In 32-bit mode,
the default is the /usr/lib/glink.o file, or
/usr/lib/glinkl.o if the bigtoc option is used. In 64-bit
mode, the default is the /usr/lib/glink64.o file, or
/usr/lib/glinkl64.o if the bigtoc option is used. You can
also use glink=large to specify /usr/lib/glinkl.o in 32-bit mode
and /usr/lib/glinkl64.o in 64-bit mode, or glink=small to override
a previous glink option. |
h:Number or halt:Number | Specifies the maximum error level for binder command processing to continue. The default
value is 4. If any binder subcommand has a return value greater than
Number, no additional binder subcommands are processed. If the halt level value
is 8 or greater, the output file might not be an executable file if it is produced at all. Return
values are:
|
I:FileID or import:FileID | (Uppercase i) Imports the symbols that are listed in FileID. There is no default import file. |
initfini:[ Initial] [:Termination] [:Priority] | Specifies a module initialization and termination function for a module, where
Initial is an initialization routine, Termination is a
termination routine, and Priority is a signed integer, with values from
-2,147,483,648 to 2,147,483,647. Specify at least one of Initial and
Termination, and if you omit both Termination and
Priority, you must omit the colon after Initial as well. If
you do not specify Priority, 0 is the default. This option
can be repeated. This option sorts routines by priority, starting with the routine with the smallest (most negative) priority. It invokes initialization routines in order, and termination routines in reverse order. This option invokes routines with the same priority in an unspecified order, but if multiple initfini options specify the same priority and both an initialization and termination routine, it preserves the relative order of the routines. For example, if you specify the options initfini:i1:f1 and initfini:i2:f2, then function i1 and i2 are invoked in an unspecified order, but if i1 is invoked before i2 when the module is loaded, f2 will be invoked before f1 when the module is unloaded. Note:
|
ipath | For shared objects listed on the command-line, rather than specified with the -l flag, use the path component when listing the shared object in the loader section of the output file. This option is the default. |
keepfile:FileID | This option prevents garbage collection of FileID. By default, the binder deletes unreferenced CSECTS in all files. You can repeat this option. |
lazy | This option enables lazy loading of a module's dependent modules. This option adds a
-lrtl option that follows other flags and options. If the
-brtl option is specified, the -blazy option is ignored
and lazy loading is not enabled. When a module is linked, a list of its dependent modules is saved in the module's loader section. The system loader automatically loads the dependent modules after the module is loaded. When lazy loading is enabled, loading is deferred for some dependents until a function is called in the module for the first time. A module is lazy loaded when all references to the module are function calls. If variables in the module are referenced, the module is loaded in the typical way. Note: Be careful while comparing function pointers if you are by using lazy loading. Usually a
function has a unique address to compare two function pointers to determine whether they refer to
the same function. When by using lazy loading to link a module, the address of a function in a lazy
loaded module is not the same address that is computed by other modules. Programs that depend upon
the comparison of function pointers must not use lazy loading.
For more information about lazy loading, see Shared Libraries and Lazy Loading. |
l:FileID or loadmap:FileID | (Lowercase L) Writes each binder subcommand and its results to FileID. By default, no file is produced. |
libpath:Path | Uses Path as the library path when writing the loader section of the
output file. Path is not checked for validity or used when searching for
libraries specified by the -l flag. Path overrides any
library paths that are generated when the -L flag is used. If you do not specify any -L flags, or if you specify the nolibpath option, the default library path information is written in the loader section of the output file. The default library path information is the value of the LIBPATH environment variable if it is defined, and /usr/lib:/lib, otherwise. |
loadmap:FileID | Functions the same as the l:FileID option. |
lpdata | Sets the F_LPDATA bit in the XCOFF header of the executable file. When this
bit is set, the process is going to request large pages for its data. |
Item | Description |
---|---|
M:ModuleType or modtype:ModuleType | Sets the two-character module-type field and the shared object flag in the object file. The
module type is not checked by the binder, but it must be set to one of the following values:
|
map:FileID or R:FileID | Writes an address map of the output object file to FileID. Symbols are sorted by section and then by address. By default, no file is produced. To learn more about the map option, see Address Maps. |
maxdata:Number[/dsa] | Functions the same as the D:Number[/dsa] option. |
maxstack:Number or S:Number | Functions the same as the -S flag. |
modtype:ModuleType | Functions the same as the M:ModuleType option. |
nl or noloadmap | This option does not write the binder subcommands and their results to a load map file. This option is the default. |
noaslr | Cancels the effect of a previous aslr option on the command line. |
noautoexp | Prevents automatic exportation of any symbols. The default is the autoexp option. |
noautoimp or nso | Links any unstripped, shared objects as ordinary object files. When you use this option, the
loader section of shared objects is not used. The default is the autoimp or
so option. Note: By using either of these flags, you can statically link a
shared object file into an application. Any application that is statically linked is not binary
portable from any fix or release level to any other fix or release level.
|
nobigtls | This option generates a severe error message if the compiler generates direct references to thread-local variables and the relocation to one of the variables overflows because the size of the thread-local storage is greater than 64 KB. If an output file is produced, it does not run correctly. The nobigtls option is the default option. |
nobigtoc | This option generates a severe error message if the size of the TOC is greater than 64 KB. If an output file is produced, it does not execute correctly. This option is the default. |
nobind | Omits calling the binder. Instead, the ld command writes the generated list of binder subcommands to standard output. By default, the ld command calls the binder. |
nocdtors | This option does not gather static constructor or destructor functions. This option is the default. |
nocomprld or nocrld | This option does not combine multiple relocation entries (RLDs) at the same address into a single RLD. The default is the comprld or crld option. |
nodelcsect | This option allows all symbols in the CSECT to be considered during symbol resolution, even if some symbol in the CSECT is defined in a previously read object file. For more information, see the delcsect option. The nodelcsect option is the default. |
noexpall | This option does not export symbols unless you list them in an export file or you export them with the autoexp option. This option is the default. |
noexpfull | This option does not export symbols unless you list them in an export file or you export them with the autoexp option. This option is the default, unless the svr4 option is used. |
noentry | This option indicates that the output file has no entry point. To retain any needed symbols, specify them with the -u flag or with an export file. You can also use the -r flag or the nogc or gcbtpass options to keep all external symbols in some or all object files. If neither the noentry nor the nox option is used and the entry point is not found, a warning is issued. This warning is suppressed when the svr4 option is used. |
noerrmsg | This option does not write error messages to standard error. Use this option if you specify the noquiet option and you pipe standard output to a command such as tee or pg. |
noforceimprw | This option allows read-only CSECTs to reference imported symbols. This option is the default. |
noforkpolicy | Clears the _AOUT_FORK_POLICY and _AOUT_FORK_COR flags in the XCOFF auxiliary header, when linking a 64-bit program. The default forktree policy is used, unless a forktree policy is specified with the VMM_CNTRL environment variable. When linking a 32-bit program, this flag is ignored. This option is the default. |
nogc | This option prevents garbage collection. CSECTs in all object files that contain global symbols are kept, whether they are referenced or not. The default is the gc option. |
noglink | Prevents the ld command from inserting global linkage code. By default, the binder inserts the global linkage code. |
noipath | For shared objects listed on the command-line, rather than specified with the
-l flag, use a null path component when listing the shared object in the loader
section of the output file. A null path component is always used for shared objects that are
specified with the -l flag. This option does not affect the specification of a
path component by using a line beginning with #! in an import file. The default is
the ipath option. |
nolibpath | Overrides any previous library path that is generated by the -L flag or specified by the libpath option. Instead, the default library path information is written in the loader section of the output file. The default library path information is the value of the LIBPATH environment variable if it is defined, and /usr/lib:/lib otherwise. |
noloadmap | Functions the same as the nl option. |
nolpdata | Clears the F_LPDATA bit in the XCOFF header of the executable file. When
this bit is not set, the process is going to use small (regular) pages for its data. |
nom | This option does not list the object files that are used to create the output file. This option overrides the -m flag. This option is the default. |
noobjreorder | This option does not use the depth-first CSECT reordering logic. The CSECTs in the output
file are arranged in the same order that the object files and library files were specified on the
command line, except as follows:
If both the noobjreorder and noreorder options are specified, the noreorder option takes precedence. The default is the reorder option. |
noorder_file | This option does not map symbols in a specified order. This flag negates the effect of a previous -border_file flag. This option is the default. |
nop:Nop | Specifies the no-op instruction that is used after branches to local routines.
Nop can be one of the special values cror15,
cror31, ori, or an eight-digit hexadecimal number. The
ori instruction is the default. Specifying the
-bnop:cror15 option is equivalent to specifying the
-bcror15 option; specifying the -bnop:cror31 option is
equivalent to specifying the -bcror31 option. If you specify one of the special
nop options, all previous nop options are overridden. If Nop is an eight-digit hexadecimal number, it specifies an arbitrary machine instruction. This machine instruction overrides any previously specified special value for Nop instruction. When you use this form, you can repeat this option. The last machine instruction that is specified is the instruction that is generated by the binder after intra-module branches. Other specified machine instructions are recognized as no-op instructions, but are converted to the preferred no-op instruction. |
noplugin_opt | Discards any previous plug-in options that are specified with the plugin_opt option. |
noquiet | Writes each binder subcommand and its results to standard output. The default is the quiet option. |
noreorder | This option does not reorder CSECTs, except to combine all XMC_TC (TOC address constant) and XMC_TD (TOC variable) CSECTs and place them in the data section, and combine all BSS symbols and place them in the bss section. All other CSECTs are placed in the text section, so text and data are mixed in the output file. When the noreorder option is used, the text section of the output file might no longer be position-independent, and the system loader will not load a module if the text section is not position-independent. Therefore, avoid by using this option for programs and kernel extensions. If both noobjreorder and noreorder options are specified, the noreorder option takes precedence. The default is the reorder option. |
nortl | Disables runtime linking for the output file. This option implies the nortllib and nosymbolic- options. Furthermore, more actions that are described under the rtl option are not taken. This option is the default unless the svr4 option is used. |
nortllib | This option does not include a reference to the runtime linker. If a main program is linked with this option, no runtime linking takes place in the program, regardless of the way any shared modules are linked that are used by the program. This option is the default unless the svr4 option is used. |
norwexec | Specifies that if the system's sed_config setting is not off, the process' private data areas have nonexecute permission. |
noshrsymtab | Prevents the _AOUT_SHR_SYMTAB flag from being set in the output object. This option is the default state. |
nostabsplit | Prevents the debug section to be written to an alternate output file with the extension .stab. This option is the default setting. |
nostrip | This option does not generate a stripped output file. Thus, the symbol table and relocation information are written in the output file. This option overrides the -s flag. This option is the default. |
nosymbolic | Assigns the nosymbolic attribute to most symbols exported without an explicit attribute. For more information, see Attributes of Exported Symbols. The default is the nosymbolic- option. |
nosymbolic- | Assigns the nosymbolic- attribute to most symbols exported without an explicit attribute. For more information, see Attributes of Exported Symbols. This option is the default. |
notextro or nro | This option does not check to ensure that there are no load-time relocation entries for the text section of the output object file. This option is the default. |
notmprelname | The binder does not check for general instantiations. Note: This option is only needed for
32-bit mode. This option is ignored when you build 64-bit objects.
|
notypchk | This option does not check function-parameter types between external functional calls. The default is the typchk option. |
nov | This option does not write additional information to the load map file. This option is the default and overrides the -v flag. |
noweaklocal | Resolves weak symbols by using normal search order. This option overrides the weaklocal option. It is the default option. |
nox | This option does not make the output file an executable file. Neither the auxiliary header nor the loader section is written. Flags and options that specify values that are written in the auxiliary header or loader section have no effect when this option is used. The default is the x option. |
nro | Functions the same as the notextro option. |
nso | Functions the same as the noautoimp option. |
order_file:FileID | Maps symbols that are listed in FileID in the specified order. The symbols that are listed in the file are mapped before other symbols of the same storage-mapping class. Function names that are specified in the file must start with a dot because a function name without a dot denotes a function descriptor. |
order:Specification | Controls the order in which some symbols are mapped in the output file. The
specifications are as follows:
|
pD:Origin | Specifies Origin as the address of the first byte of the file page that
contains the beginning of the data section. For example, if the data section begins at an offset
0x22A0 in the object file, and pD:0x20000000 is specified, the
first byte of the data section is assigned address 0x200002A0 . This option assumes
a page size of 4096 (0x1000 ) bytes. Note: If both the -bpD and
-D flags are specified, the latter flag takes precedence.
|
plugin:path | Specifies the full path of a compiler plug-in. This option is typically generated by a
compiler, if required. If you want to cancel a previously specified plug-in path, do not specify the path variable that is -bplugin:. If an input file is a bitcode file or an archive that contains a bitcode file, and a plug-in path is not specified, the ld command fails. |
plugin_opt:plugin-option | Specifies an option to be passed to the compiler plug-in. You can specify the
plugin_opt option multiple times. This option is typically generated by a
compiler. |
pT:Origin | Specifies Origin as the address of the first byte of the file page that
contains the beginning of the text section. For example, if the text section begins at an offset
0x264 in the object file, and pT:0x10000000 is specified, the
first byte of the text section is assigned address 0x10000264 . Note: If both the
-bpT and -T flags are specified, the latter flag takes
precedence. For more information, see the -T flag for additional information.
|
quiet | This option does not write binder subcommands and their results to standard output. This option is the default. |
Item | Description |
---|---|
R:FileID | Functions the same as the map:FileID option. |
r or reorder | Reorders CSECTs as part of the save command processing. The reorder process arranges CSECTs of the same storage-mapping class by proximity of reference. This option is the default. |
ras | Sets a flag in the output module's auxiliary header to signify that the module is both storage key safe and recovery safe. For more information about how to make a kernel extension be key safe and recovery safe, see Kernel Extensions and Device Support Programming Concepts . |
rename:Symbol, NewName | Renames the external symbol Symbol to NewName. In effect, it is as if all definitions and references to Symbol in all object files were renamed to NewName before the files were processed. By default, symbols are not renamed. |
reorder | Functions the same as the r option. |
ro or textro | Ensures that there are no load-time relocation entries for the text section of the resultant object file. The default is the nro option. |
rtl | Enables runtime linking for the output file. This option implies the
rtllib and symbolic options. When dynamic mode is in effect (see the dynamic and static options), the rtl option allows input files that are specified with the -l flag to end in .so as well as in .a. All input files that are shared objects are listed as dependents of your program in the output files loader section. The shared objects are listed in the same order as they were specified on the command line. A shared object that is contained in an archive is only listed if the archive specifies automatic loading for the shared object member. You can specify automatic loading for an archive member foo.o by creating an import file with the following lines:
After creating the import file, add the import file as a member to the archive. You might also specify automatic loading for an archive member foo.o by using the -bautoload option:
You might specify more archive members with -bautoloads option. If the first line of an import file begins with |
rtllib | This option includes a reference to the runtime linker. The runtime linker is defined in librtl.a, and an implicit -lrtl flag is added automatically to the command line. This option (implied by the rtl option) must be used when linking a main program or no runtime linking occurs. Shared objects do not have to be linked with this option. The default is the nortllib option unless the svr4 option is used. |
rwexec | Specifies that the execute permissions of the process' private data areas are determined according to the system's sed_config setting. This option is the default. |
rwexec_must | Specifies that the process' private data areas have execute permission, regardless of the system's sed_config setting. |
S:Number | Functions the same as the -S flag. |
scalls:FileID | Writes an address map of the object file to FileID. Symbols are listed alphabetically. For each symbol listed in the map, references from the symbol to the other symbols are listed. By default, no file is produced. To learn more about the scalls option, see Address Maps. |
shared | Functions the same as the dynamic option. |
shmpsize: psize | Requests psize page sizes in bytes for a shared memory. The
value that is specified must be a power of two. If not, the value is rounded down to the nearest
power of two. The value can be specified as a decimal, hexadecimal, or octal number. Also, the page
size can be specified as a number followed by a one-character suffix:
-b shmpsize:64k or -b shmpsize:0x10000
request a page size of 64 KB for shared memory. If the specified value is not 0, the F_VARPG bit of
the XCOFF header’s f_flags member is set. If 0 is specified, F_VARPG is cleared. The program uses
the default page size for shared memory. In 32-bit mode, this flag is ignored and a warning message
is printed. |
shrsymtab | In 64-bit mode, sets the _AOUT_SHR_SYMTAB flag in the XCOFF auxiliary header. If File is a 64-bit program, a shared symbol table is created when the program is run. If File is a 64-bit object but not a 64-bit program, the _AOUT_SHR_SYMTAB flag can be set, but has no effect at run time. In 32-bit mode, this flag is ignored. The default is noshrsymtab. |
smap:FileID | Writes an address map of the object file to FileID. Symbols are listed alphabetically. By default, no file is produced. To learn more about the smap option, see Address Maps that follows. |
so | Functions the same as the autoimp option. |
stabcmpct:Level | Specifies the level of compaction for stabstrings in the debug section. Stabstrings are
strings that are longer than eight characters. Each substring in the symbol table has its own offset
in the debug section. The following values are valid for Level:
|
stabsplit | This option causes the debug section to be written to an alternate output file with the extension .stab. |
stackpsize:psize | Requests psize page sizes in bytes for process main thread stack. The
value can be specified as a decimal, hexadecimal, or octal number. The number specifications are the
same as in the C programming language. Also, the page size can be specified as a number followed by
a one-character suffix:
-b stackpsize:16k or -b stackpsize:0x4000
requests 0x4000 for process main thread stack and set the F_VARPG bit in the XCOFF
header. |
static | This option causes the linker to process subsequent shared objects in static mode. In static mode, shared objects are statically linked in the output file. |
svr4 | This option changes the meaning of some other options on the command line and the standard
behavior of the linker. It has the following effect on the linker:
|
sxref:FileID | Writes an address map of the object file to FileID. Symbols are listed alphabetically. For each symbol listed in the map, references to the symbol from other symbols are listed. By default, no file is produced. To learn more about the sxref option, see Address Maps that follows. |
symbolic | Assigns the symbolic attribute to most symbols exported without an explicit attribute. For more information, see Attributes of Exported Symbols that follows. This option is the default when the svr4 option is used. Otherwise, the default is the symbolic- option. |
textro | Same as the ro option. |
textpsize:psize | Requests psize page sizes in bytes for text. The value can be specified as
a decimal, hexadecimal, or octal number. The number specifications are the same as in the C
programming language. Also, the page size can be specified as a number followed by a one-character
suffix:
-b textpsize:16k or -b textpsize:0x4000
requests 0x4000 for text and set the F_VARPG bit in the XCOFF header. |
tmplrename | Specifies that the binder must check for general instantiations. The binder checks for any
symbol of the form __tfNNxxx_name and renames the symbol to
name. The default is -bnotmplrename. Note: This option is
only needed for 32-bit mode. This option is ignored when building 64-bit objects.
|
typchk | Performs function-parameter type checking between external functional calls. The information
of the Parameter-type checking can be included in object files by compilers and assemblers. This
option is the default. For more information about type checking, see XCOFF Object File Format. |
weaklocal | Specifies that weak symbols are searched for first in the object files where they are referenced. If the symbols are not found there, the normal search order is resumed. |
x | Makes the output file an executable file, if no errors exist. This option is the default option. |
X or xref:FileID | Writes an address map of the object file to FileID. Symbols are sorted by section and then by address. For each symbol listed in the map, references to the symbol from other symbols are listed. By default, no file is produced. To learn more about the xref option, see Address Maps that follows. |
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 runtime linker, allowing some symbols to be rebounded at load-time. To create a program that uses the runtime 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 that are enabled for runtime linking by using the -G flag. You can fully enable runtime linking for existing shared objects by relinking them with the rtl_enable command, unless they are stripped.
Symbol Visibility
Global and weak symbols in an input object file can be marked with a visibility symbol. Four symbol visibilities are defined.
Symbol | Visibility |
---|---|
Internal | The symbol is not exported. The address of the symbol must not be provided to other programs or shared objects, but the linker does not verify this. |
Hidden | The symbol is not exported. |
Protected | The symbol is exported but cannot be rebounded (or preempted), even if runtime linking is being used. |
Exported | The symbol is exported with the global export attribute. |
The visibility of a symbol can be specified in an assembler source file. Some compilers support visibility as well. Consult your compiler documentation for details.
Export files can also be used to specify the visibility for a symbol. Ordinarily, the visibility that is specified in an export file takes precedence over the visibility that is specified in the object file. This linker considers symbol visibility when creating the export list for a program or shared object.
Import and export File Format (-bI: and -bE: Flags)
Each line within an import or export file contains the name of a symbol, optionally followed by an address or a keyword. Primary keywords are svc, svc32, svc3264, svc64, syscall, syscall32, syscall3264, syscall64, symbolic, nosymbolic, nosymbolic-, list, cm, bss, internal, hidden, protected, and export. A few more keywords are weak and required, which can be used along with another keyword.
In an import file, specifying an address allows a symbol to be mapped to a fixed address, such as an address in a shared memory segment. 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, svc32, svc3264, svc64, syscall, syscall32, syscall3264, or syscall64 keyword after a function name to indicate that the function is a system call. This option is needed when linking kernel extensions. If the output file is not a kernel extension, these keywords are equivalent to the symbolic keyword.
You can use the list keyword to cause a symbol to be listed in the loader section of the output file, although it is not marked as an exported symbol. The list keyword 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 runtime linker.
You can use the symbolic, nosymbolic, or nosymbolic- keyword to associate an attribute with an exported symbol. A symbol address in an export file is ignored. In an export file, the keywords cm and bss are equivalent to the nosymbolic keyword. The visibility of a symbol can be specified with the internal, hidden, protected, or export keywords. For more information, see.Attributes of Exported Symbols
The weak keyword can be used to specify a weak symbol binding, and might be used with another attribute.
Use the required keyword to verify that a symbol is defined and not imported. An error is printed for symbols not meeting these criteria.
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 that contains
# 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 must be used for 32-bit links, 64-bit links, or both.32-bit and 64-bit Import File Options
Item Description 32 This option is used in an import or export file to specify that subsequent symbols must 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 must 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:Item Description #! (Nothing after the #!
) Use null path, null file, and null number. This option is treated as a deferred import by the system loader.#! () Use ipath
,ifile
, andimember
. 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 file. 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 that are imported by other modules, or loading fails. This import file name can be used with or without the runtime linker. #! .. (Two dots) Use this name to list symbols that are resolved by the runtime linker. Use this file name to create shared objects that are used by programs that makes use of the runtime linker. If you use a module that imports symbols from .. in a program that was not linked with the rtllib option, the symbols are unresolved, and references to such symbols 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 extra member names on more lines, if appropriate. You do not need to list symbol names in the import file because the symbols imported from shr.so are read from shr.so itself.
For more information about creating a shared library, see create_shared_lib subroutine. For more information about loading and binding, see the load subroutine.
Attributes of Exported Symbols
When you use runtime linking, a reference to a symbol in the same module can be rebounded only if the symbol is exported with the proper attribute. References to symbols with the symbolic attribute cannot be rebounded. References to symbols with the nosymbolic attribute can be rebounded. References to symbols with the nosymbolic- attribute can be rebounded if the symbols are variables. For function symbols, calls by using a function pointer can be rebounded, while direct function calls cannot be rebounded. 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 by using the runtime linker, avoid by using the nosymbolic attribute because intra-module function calls are made indirectly through a function descriptor by using global-linkage code. Otherwise, the attribute of exported symbols has no effect for modules that are used with programs that do not use the runtime linker.
You can specify an explicit export attribute for symbols that are 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.
If a symbol is listed in an export file without a keyword, and the visibility of the symbol is specified in an input file, the symbol’s visibility is preserved. An input symbol’s visibility can be overridden by using the internal, hidden, protected, or export keyword.
The weak export attribute marks the associated symbol's mapping type with L_WEAK in the loader section.
Imported symbols might have only the weak export attribute. If a symbol is imported from another module, all references to the symbol can be rebounded. However, if a symbol is imported at a fixed address, all references are bound to this fixed address and cannot be rebounded by the runtime linker. The system loader must resolve deferred imports. The runtime linker never resolves or rebinds references to deferred imports.
For exports of nonimported 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 runtime linker ignores such symbols.
- If a symbol was exported with an explicit attribute, or with an explicit visibility, the explicit attribute, or visibility 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, 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 symbols with a storage class of C_WEAKEXT, are printed with the characters {
and }
surrounding the symbol name.
The following information is listed about each symbol:
- 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 the storage-mapping class XMC_TC0 is shown as T0.
The input file information depends on the type of input file. For object files, source file names that are 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 that are 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:
Item | Description |
---|---|
LIBPATH | If LIBPATH is defined, its value is used as the default library path information. The default library path is /usr/lib:/lib. If no -L flags are specified and no -blibpath option is specified, the default library path information is written in the loader section of the output file. Regardless of any options specified, LIBPATH is not used when searching for libraries that are specified from the command line. |
TMPDIR | If the output file exists or it is on a remote file system, the ld command generates a temporary output file. The temporary output file is created in the directory that is specified by TMPDIR. If TMPDIR is not defined, the temporary output file is created in the /tmp directory if the output file is remote, or in the same directory as the existing output file. |
OBJECT_MODE | If neither the -b32 nor -b64 option is used, the OBJECT_MODE environment variable is examined to determine the linking mode. If the value of OBJECT_MODE is 32 or 64, 32-bit or 64-bit mode is used. If the value is 32_64 or any other value, the linker prints an error message and exits with a nonzero return code. Otherwise, a 32-bit mode is used. |
Examples
- To link several object files and produce a a.out file to run under the
operating system, enter the following command:
The -lc (lowercase letter L) links the libc.a library. A simpler way to link the libc.a library is to use the cc command (the compiler) to link the files as follows:ld /usr/lib/crt0.o pgm.o subs1.o subs2.o -lc
cc pgm.o subs1.o subs2.o
- To specify the name of the output file, enter the following command:
This creates the output in the file pgm.cc -o pgm pgm.o subs1.o subs2.o
- To relink pgm if only the object file subs1.o changed,
enter the following command:
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.cc -o pgm subs1.o pgm
- To link with library subroutines, enter the following command:
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 that is specified by -l (lowercase letter L) flag (This means the /usr/lib/libtools.a file).cc pgm.o subs1.o subs2.o mylib.a -ltools
- To generate a shared object, enter the following command:
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 that are specified in the file shrsub.exp and stores the linked shared object in the file shrsub.o. The -bM:SRE sets the shared object flag in the linked object file.ld -o shrsub.o subs1.o subs2.o -bE:shrsub.exp -bM:SRE -lc
- To link with the shared object shrsub.o generated previously, enter the
following command:
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 that contains 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`.cc -o pgm pgm.o shrsub.o -L '.'
The list of directories searched by the system loader can be seen by using the dump command.
- To link a program by using the libc.a library as a nonshared library, enter
the following command:
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 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 nonshared library, and the -bI:/lib/syscalls.exp directs the ld command to import the system call functions that are 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.cc -o pgm pgm.o -bnso -bI:/lib/syscalls.exp
Note: Anytime that /usr/lib/libc.a is linked nonshared, the flag -bI:/lib/syscalls.exp must be used. The application must 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. - To enable the randomization attributes, enter the
following command:
-baslr
If text-section relocations exist, do not enable text and data randomization.
- To enable randomization for text and stack only, enter
the following command:
-baslr:ts
Files
Item | Description |
---|---|
/usr/bin/ld | Contains the ld command. |
/usr/lib/lib*.a | Specifies libraries That are used for linking programs. |
a.out | Specifies the default output file name. |