ld(1) GNU Development Tools ld(1) NNAAMMEE ld - the GNU linker SSYYNNOOPPSSIISS lldd [--oo _o_u_t_p_u_t] _o_b_j_f_i_l_e... [--AA_a_r_c_h_i_t_e_c_t_u_r_e] [--bb _i_n_p_u_t_-_f_o_r_m_a_t] [--BBssttaattiicc] [--cc _c_o_m_m_a_n_d_f_i_l_e] [--dd|--ddcc|--ddpp] [--ddeeffssyymm _s_y_m_b_o_l = _e_x_p_r_e_s_s_i_o_n] [--ee _e_n_t_r_y] [--FF] [--FF _f_o_r_m_a_t] [--ffoorrmmaatt _i_n_p_u_t_-_f_o_r_m_a_t] [--gg] [--GG_s_i_z_e] [----hheellpp] [--ii] [--ll_a_r] [--LL_s_e_a_r_c_h_d_i_r] [--MM] [--MMaapp_m_a_p_f_i_l_e] [--mm_e_m_u_l_a_t_i_o_n] [--nn|--NN] [--nnooiinnhhiibbiitt--eexxeecc] [--ooffoorrmmaatt _o_u_t_p_u_t_-_f_o_r_m_a_t] [--RR _f_i_l_e_n_a_m_e] [--rreellaaxx] [--rr|--UUrr] [--SS] [--ss] [--ssoorrtt--ccoommmmoonn] [--TT _c_o_m_m_a_n_d_f_i_l_e] [--TTtteexxtt _t_e_x_t_o_r_g] [--TTddaattaa _d_a_t_a_o_r_g] [--TTbbssss _b_s_s_o_r_g] [--tt] [--uu _s_y_m] [--VV] [--vv] [----vveerrssiioonn] [--wwaarrnn--ccoommmmoonn] [--XX] [--xx] DDEESSCCRRIIPPTTIIOONN lldd combines a number of object and archive files, relo- cates their data and ties up symbol references. Often the last step in building a new compiled program to run is a call to lldd. lldd accepts Linker Command Language files to provide ex- plicit and total control over the linking process. This man page does not describe the command language; see the `lldd' entry in `iinnffoo', or the manual _l_d_: _t_h_e _G_N_U _l_i_n_k_e_r , for full details on the command language and on other as- pects of the GNU linker. This version of lldd uses the general purpose BFD libraries to operate on object files. This allows lldd to read, com- bine, and write object files in many different formats-- for example, COFF or aa..oouutt. Different formats may be linked together to produce any available kind of object file. You can use `oobbjjdduummpp --ii' to get a list of formats supported on various architectures; see oobbjjdduummpp(11). Aside from its flexibility, the GNU linker is more helpful than other linkers in providing diagnostic information. Many linkers abandon execution immediately upon encounter- ing an error; whenever possible, lldd continues executing, allowing you to identify other errors (or, in some cases, to get an output file in spite of the error). The GNU linker lldd is meant to cover a broad range of situ- ations, and to be as compatible as possible with other linkers. As a result, you have many choices to control its behavior through the command line, and through envi- ronment variables. cygnus support 17 August 1992 1 ld(1) GNU Development Tools ld(1) OOPPTTIIOONNSS The plethora of command-line options may seem intimidat- ing, but in actual practice few of them are used in any particular context. For instance, a frequent use of lldd is to link standard Unix object files on a standard, support- ed Unix system. On such a system, to link a file hheelllloo..oo: $ ld -o output /lib/crt0.o hello.o -lc This tells lldd to produce a file called oouuttppuutt as the re- sult of linking the file //lliibb//ccrrtt00..oo with hheelllloo..oo and the library lliibbcc..aa which will come from the standard search directories. The command-line options to lldd may be specified in any or- der, and may be repeated at will. For the most part, re- peating an option with a different argument will either have no further effect, or override prior occurrences (those further to the left on the command line) of an op- tion. The exceptions--which may meaningfully be used more than once--are --AA, --bb (or its synonym --ffoorrmmaatt), --ddeeffssyymm, --LL, --ll, --RR, and --uu. The list of object files to be linked together, shown as _o_b_j_f_i_l_e, may follow, precede, or be mixed in with command- line options; save that an _o_b_j_f_i_l_e argument may not be placed between an option flag and its argument. Usually the linker is invoked with at least one object file, but other forms of binary input files can also be specified with --ll, --RR, and the script command language. If _n_o binary input files at all are specified, the linker does not produce any output, and issues the message `NNoo iinnppuutt ffiilleess'. Option arguments must either follow the option letter without intervening whitespace, or be given as separate arguments immediately following the option that requires them. --AA_a_r_c_h_i_t_e_c_t_u_r_e In the current release of lldd, this option is use- ful only for the Intel 960 family of architectures. In that lldd configuration, the _a_r_c_h_i_t_e_c_t_u_r_e argument is one of the two-letter names identifying members of the 960 family; the option specifies the desired output target, and warns of any incompatible in- structions in the input files. It also modifies the linker's search strategy for archive libraries, to support the use of libraries specific to each particular architecture, by including in the search cygnus support 17 August 1992 2 ld(1) GNU Development Tools ld(1) loop names suffixed with the string identifying the architecture. For example, if your lldd command line included `--AACCAA' as well as `--llttrryy', the linker would look (in its built-in search paths, and in any paths you specify with --LL) for a library with the names try libtry.a tryca libtryca.a The first two possibilities would be considered in any event; the last two are due to the use of `--AACCAA'. Future releases of lldd may support similar function- ality for other architecture families. You can meaningfully use --AA more than once on a command line, if an architecture family allows com- bination of target architectures; each use will add another pair of name variants to search for when --ll specifies a library. --bb _i_n_p_u_t_-_f_o_r_m_a_t Specify the binary format for input object files that follow this option on the command line. You don't usually need to specify this, as lldd is con- figured to expect as a default input format the most usual format on each machine. _i_n_p_u_t_-_f_o_r_m_a_t is a text string, the name of a particular format sup- ported by the BFD libraries. --ffoorrmmaatt _i_n_p_u_t_-_f_o_r_m_a_t has the same effect, as does the script command TTAARRGGEETT. You may want to use this option if you are linking files with an unusual binary format. You can also use --bb to switch formats explicitly (when linking object files of different formats), by including --bb _i_n_p_u_t_-_f_o_r_m_a_t before each group of object files in a particular format. The default format is taken from the environment variable GGNNUUTTAARRGGEETT. You can also define the input format from a script, using the command TTAARRGGEETT. --BBssttaattiicc This flag is accepted for command-line compatibili- ty with the SunOS linker, but has no effect on lldd. cygnus support 17 August 1992 3 ld(1) GNU Development Tools ld(1) --cc _c_o_m_m_a_n_d_f_i_l_e Directs lldd to read link commands from the file _c_o_m_m_a_n_d_f_i_l_e. These commands will completely over- ride lldd's default link format (rather than adding to it); _c_o_m_m_a_n_d_f_i_l_e must specify everything neces- sary to describe the target format. You may also include a script of link commands di- rectly in the command line by bracketing it between `{{' and `}}' characters. --dd --ddcc --ddpp These three options are equivalent; multiple forms are supported for compatibility with other linkers. Use any of them to make lldd assign space to common symbols even if a relocatable output file is speci- fied (--rr). The script command FFOORRCCEE__CCOOMMMMOONN__AALLLLOOCCAATTIIOONN has the same effect. --ddeeffssyymm _s_y_m_b_o_l = _e_x_p_r_e_s_s_i_o_n Create a global symbol in the output file, containing the absolute address given by _e_x_- _p_r_e_s_s_i_o_n. You may use this option as many times as necessary to define multiple symbols in the command line. A limited form of arithmetic is supported for the _e_x_p_r_e_s_s_i_o_n in this context: you may give a hexadecimal constant or the name of an existing symbol, or use ++ and -- to add or subtract hexadeci- mal constants or symbols. If you need more elabo- rate expressions, consider using the linker command language from a script. --ee _e_n_t_r_y Use _e_n_t_r_y as the explicit symbol for beginning ex- ecution of your program, rather than the default entry point. for a discussion of defaults and oth- er ways of specifying the entry point. --FF --FF_f_o_r_m_a_t Some older linkers used this option throughout a compilation toolchain for specifying object-file format for both input and output object files. lldd's mechanisms (the --bb or --ffoorrmmaatt options for in- put files, the TTAARRGGEETT command in linker scripts for cygnus support 17 August 1992 4 ld(1) GNU Development Tools ld(1) output files, the GGNNUUTTAARRGGEETT environment variable) are more flexible, but but it accepts (and ignores) the --FF option flag for compatibility with scripts written to call the old linker. --ffoorrmmaatt _i_n_p_u_t_-_f_o_r_m_a_t Synonym for --bb _i_n_p_u_t_-_f_o_r_m_a_t. --gg Accepted, but ignored; provided for compatibility with other tools. --GG _s_i_z_e Set the maximum size of objects to be optimized us- ing the GP register to _s_i_z_e under MIPS ECOFF. Ig- nored for other object file formats. ----hheellpp Print a summary of the command-line options on the standard output and exit. This option and ----vveerr-- ssiioonn begin with two dashes instead of one for com- patibility with other GNU programs. The other op- tions start with only one dash for compatibility with other linkers. --ii Perform an incremental link (same as option --rr). --ll_a_r Add an archive file _a_r to the list of files to link. This option may be used any number of times. lldd will search its path-list for occurrences of lliibb_a_r.a for every _a_r specified. --LL_s_e_a_r_c_h_d_i_r This command adds path _s_e_a_r_c_h_d_i_r to the list of paths that lldd will search for archive libraries. You may use this option any number of times. The default set of paths searched (without being specified with --LL) depends on what emulation mode lldd is using, and in some cases also on how it was configured. The paths can also be specified in a link script with the SSEEAARRCCHH__DDIIRR command. --MM Print (to the standard output file) a link map-- diagnostic information about where symbols are mapped by lldd, and information on global common storage allocation. cygnus support 17 August 1992 5 ld(1) GNU Development Tools ld(1) --MMaapp _m_a_p_f_i_l_e Print to the file _m_a_p_f_i_l_e a link map--diagnostic information about where symbols are mapped by lldd, and information on global common storage alloca- tion. --mm _e_m_u_l_a_t_i_o_n Emulate the _e_m_u_l_a_t_i_o_n linker. You can list the available emulations with the _-_V option. This op- tion overrides the compiled-in default, which is the system for which you configured lldd. --NN specifies readable and writable tteexxtt and ddaattaa sec- tions. If the output format supports Unix style magic numbers, the output is marked as OOMMAAGGIICC. When you use the `--NN' option, the linker does not page-align the data segment. --nn sets the text segment to be read only, and NNMMAAGGIICC is written if possible. --nnooiinnhhiibbiitt--eexxeecc Normally, the linker will not produce an output file if it encounters errors during the link pro- cess. With this flag, you can specify that you wish the output file retained even after non-fatal errors. --oo _o_u_t_p_u_t _o_u_t_p_u_t _o_u_t_p_u_t is a name for the program produced by lldd; if this option is not specified, the name `aa..oouutt' is used by default. The script command OOUUTTPPUUTT can also specify the output file name. --ooffoorrmmaatt _o_u_t_p_u_t_-_f_o_r_m_a_t Specify the binary format for the output object file. You don't usually need to specify this, as lldd is configured to produce as a default output format the most usual format on each machine. _o_u_t_- _p_u_t_-_f_o_r_m_a_t is a text string, the name of a particu- lar format supported by the BFD libraries. The script command OOUUTTPPUUTT__FFOORRMMAATT can also specify the output format, but this option overrides it. --RR _f_i_l_e_n_a_m_e _f_i_l_e Read symbol names and their addresses from cygnus support 17 August 1992 6 ld(1) GNU Development Tools ld(1) _f_i_l_e_n_a_m_e, but do not relocate it or include it in the output. This allows your output file to refer symbolically to absolute locations of memory de- fined in other programs. --rreellaaxx An option with machine dependent effects. Current- ly this option is only supported on the H8/300. On some platforms, use this option to perform glob- al optimizations that become possible when the linker resolves addressing in your program, such as relaxing address modes and synthesizing new in- structions in the output object file. On platforms where this is not supported, `--rreellaaxx' is accepted, but has no effect. --rr Generates relocatable output--i.e., generate an output file that can in turn serve as input to lldd. This is often called _p_a_r_t_i_a_l linking. As a side effect, in environments that support standard Unix magic numbers, this option also sets the output file's magic number to OOMMAAGGIICC. If this option is not specified, an absolute file is produced. When linking C++ programs, this option _w_i_l_l _n_o_t resolve references to constructors; --UUrr is an alternative. This option does the same as --ii. --SS Omits debugger symbol information (but not all sym- bols) from the output file. --ss Omits all symbol information from the output file. --ssoorrtt--ccoommmmoonn Normally, when lldd places the global common symbols in the appropriate output sections, it sorts them by size. First come all the one byte symbols, then all the two bytes, then all the four bytes, and then everything else. This is to prevent gaps be- tween symbols due to alignment constraints. This option disables that sorting. --TTbbssss _o_r_g --TTddaattaa _o_r_g cygnus support 17 August 1992 7 ld(1) GNU Development Tools ld(1) --TTtteexxtt _o_r_g Use _o_r_g as the starting address for--respectively-- the bbssss, ddaattaa, or the tteexxtt segment of the output file. _t_e_x_t_o_r_g must be a hexadecimal integer. --TT _c_o_m_m_a_n_d_f_i_l_e --TT_c_o_m_m_a_n_d_f_i_l_e Equivalent to --cc _c_o_m_m_a_n_d_f_i_l_e; supported for compat- ibility with other tools. --tt Prints names of input files as lldd processes them. --uu _s_y_m Forces _s_y_m to be entered in the output file as an undefined symbol. This may, for example, trigger linking of additional modules from standard li- braries. --uu may be repeated with different option arguments to enter additional undefined symbols. --UUrr For anything other than C++ programs, this option is equivalent to --rr: it generates relocatable out- put--i.e., an output file that can in turn serve as input to lldd. When linking C++ programs, --UUrr _w_i_l_l resolve references to constructors, unlike --rr. --VV Display the version number for lldd and list the sup- ported emulations. Display which input files can and can not be opened. --vv Display the version number for lldd. ----vveerrssiioonn Display the version number for lldd and exit. --wwaarrnn--ccoommmmoonn Warn when a common symbol is combined with another common symbol or with a symbol definition. Unix linkers allow this somewhat sloppy practice, but linkers on some other operating systems do not. This option allows you to find potential problems from combining global symbols. --XX If --ss or --SS is also specified, delete only local symbols beginning with `LL'. cygnus support 17 August 1992 8 ld(1) GNU Development Tools ld(1) --xx If --ss or --SS is also specified, delete all local symbols, not just those beginning with `LL'. EENNVVIIRROONNMMEENNTT You can change the behavior of lldd with the environment variable GGNNUUTTAARRGGEETT. GGNNUUTTAARRGGEETT determines the input-file object format if you don't use --bb (or its synonym --ffoorrmmaatt). Its value should be one of the BFD names for an input format. If there is no GGNNUUTTAARRGGEETT in the environment, lldd uses the natural for- mat of the host. If GGNNUUTTAARRGGEETT is set to ddeeffaauulltt then BFD attempts to discover the input format by examining binary input files; this method often succeeds, but there are po- tential ambiguities, since there is no method of ensuring that the magic number used to flag object-file formats is unique. However, the configuration procedure for BFD on each system places the conventional format for that system first in the search-list, so ambiguities are resolved in favor of convention. SSEEEE AALLSSOO oobbjjdduummpp(11) `lldd' and `bbiinnuuttiillss' entries in iinnffoo _l_d_: _t_h_e _G_N_U _l_i_n_k_e_r, Steve Chamberlain and Roland Pesch; _T_h_e _G_N_U _B_i_n_a_r_y _U_t_i_l_i_t_i_e_s, Roland H. Pesch. CCOOPPYYIINNGG Copyright (c) 1991, 1992 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified ver- sions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above con- ditions for modified versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original En- glish. cygnus support 17 August 1992 9 .