Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ld(1)			     GNU Development Tools			 ld(1)

NAME
       ld - the	GNU linker

SYNOPSIS
       ld     [-o output] objfile...
	      [-Aarchitecture] [-b input-format] [-Bstatic] [-Bdynamic]
	      [-Bsymbolic] [-c commandfile] [--cref] [-d|-dc|-dp]
	      [-defsym symbol =	expression] [-e	entry] [-embedded-relocs] [-E]
	      [-export-dynamic]	[-f name] [--auxiliary name] [-F name]
	      [--filter	name] [-format input-format] [-g] [-G size] [-h	name]
	      [-soname name] [--help] [-i] [-lar] [-Lsearchdir]	[-M] [-Map
	      mapfile] [-m emulation] [-n|-N] [-noinhibit-exec]
	      [-no-keep-memory]	[-no-warn-mismatch] [-oformat output-format]
	      [-R filename] [-relax] [-r|-Ur] [-rpath directory]
	      [-rpath-link directory] [-S] [-s]	[-shared] [-sort-common]
	      [-split-by-reloc count] [-split-by-file] [-T commandfile]
	      [-Ttext textorg] [-Tdata dataorg]	[-Tbss bssorg] [-t] [-u	sym]
	      [-V] [-v]	[--verbose] [--version]	[-warn-common]
	      [-warn-constructors] [-warn-multiple-gp] [-warn-once]
	      [-warn-section-align] [--whole-archive] [--no-whole-archive]
	      [--wrap symbol] [-X] [-x]

DESCRIPTION
       ld  combines a number of	object and archive files, relocates their data
       and ties	up symbol references. Often the	last step in  building	a  new
       compiled	program	to run is a call to ld.

       ld  accepts Linker Command Language files to provide explicit and total
       control over the	linking	process.  This man page	does not describe  the
       command	language;  see the `ld'	entry in `info', or the	manual ld: the
       GNU linker , for	full details on	the command language and on other  as-
       pects of	the GNU	linker.

       This version of ld uses the general purpose BFD libraries to operate on
       object files. This allows ld to read, combine, and write	 object	 files
       in  many	different formats--for example,	COFF or	a.out.	Different for-
       mats may	be linked together to produce any  available  kind  of	object
       file.   You  can	use `objdump -i' to get	a list of formats supported on
       various architectures; see objdump(1).

       Aside from its flexibility, the GNU linker is more helpful  than	 other
       linkers in providing diagnostic information.  Many linkers abandon exe-
       cution immediately upon encountering an error;  whenever	 possible,  ld
       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 ld is meant to cover a broad range of situations,	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 environment variables.

OPTIONS
       The  plethora of	command-line options may seem intimidating, but	in ac-
       tual practice few of them are used in any particular context.  For  in-
       stance, a frequent use of ld is to link standard	Unix object files on a
       standard, supported Unix	system.	 On such a system, to link a file hel-
       lo.o:

       $ ld -o output /lib/crt0.o hello.o -lc

       This  tells ld to produce a file	called output as the result of linking
       the file	/lib/crt0.o with hello.o and the  library  libc.a  which  will
       come from the standard search directories.

       The  command-line  options to ld	may be specified in any	order, and may
       be repeated at will.  For the most part,	repeating  an  option  with  a
       different argument will either have no further effect, or override pri-
       or occurrences (those further to	the left on the	command	 line)	of  an
       option.

       The  exceptions--which may meaningfully be used more than once--are -A,
       -b (or its synonym -format), -defsym, -L, -l, -R, and -u.

       The list	of object files	to be linked together, shown as	 objfile,  may
       follow, precede,	or be mixed in with command-line options; save that an
       objfile argument	may not	be placed between an option flag and its argu-
       ment.

       Usually	the linker is invoked with at least one	object file, but other
       forms of	binary input files can also be specified with -l, -R, and  the
       script  command	language.   If no binary input files at	all are	speci-
       fied, the linker	does not produce any output, and  issues  the  message
       `No input files'.

       Option arguments	must either follow the option letter without interven-
       ing whitespace, or be given as separate arguments immediately following
       the option that requires	them.

       -Aarchitecture
	      In the current release of	ld, this option	is useful only for the
	      Intel 960	family of architectures.  In  that  ld	configuration,
	      the architecture argument	is one of the two-letter names identi-
	      fying members of the 960 family; the option  specifies  the  de-
	      sired  output target, and	warns of any incompatible instructions
	      in the input files.  It also modifies the	linker's search	strat-
	      egy  for archive libraries, to support the use of	libraries spe-
	      cific to each  particular	 architecture,	by  including  in  the
	      search  loop  names suffixed with	the string identifying the ar-
	      chitecture.

	      For example, if your ld command line included `-ACA' as well  as
	      `-ltry',	the  linker  would look	(in its	built-in search	paths,
	      and in any paths you specify with	-L) 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 `-ACA'.

	      Future releases of ld may	support	similar	functionality for oth-
	      er architecture families.

	      You can meaningfully use -A more than once on a command line, if
	      an architecture family allows combination	 of  target  architec-
	      tures; each use will add another pair of name variants to	search
	      for when -l specifies a library.

       -b input-format
	      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 ld is configured	to expect as a	default	 input
	      format the most usual format on each machine.  input-format is a
	      text string, the name of a particular format  supported  by  the
	      BFD  libraries.	-format	 input-format  has the same effect, as
	      does the script command TARGET.

	      You may want to use this option if you are linking files with an
	      unusual  binary  format.	 You can also use -b to	switch formats
	      explicitly (when linking object files of different formats),  by
	      including	-b input-format	before each group of object files in a
	      particular format.

	      The default format is taken from the environment	variable  GNU-
	      TARGET.  You can also define the input format from a script, us-
	      ing the command TARGET.

       -Bstatic
	      Do not link against shared libraries.  This is  only  meaningful
	      on platforms for which shared libraries are supported.

       -Bdynamic
	      Link  against  dynamic  libraries.   This	 is only meaningful on
	      platforms	for which shared libraries are supported.  This	option
	      is normally the default on such platforms.

       -Bsymbolic
	      When  creating  a	shared library,	bind references	to global sym-
	      bols to the definition within the	shared library,	if any.	  Nor-
	      mally,  it is possible for a program linked against a shared li-
	      brary to override	the  definition	 within	 the  shared  library.
	      This  option  is	only meaningful	on ELF platforms which support
	      shared libraries.

       -c commandfile
	      Directs ld to read link  commands	 from  the  file  commandfile.
	      These commands will completely override ld's default link	format
	      (rather than adding to it); commandfile must specify  everything
	      necessary	to describe the	target format.

	      You  may	also include a script of link commands directly	in the
	      command line by bracketing it between `{'	and `}'	characters.

       --cref Output a cross reference table.  If a linker map file  is	 being
	      generated, the cross reference table is printed to the map file.
	      Otherwise, it is printed on the standard output.

       -d

       -dc

       -dp    These three options are equivalent; multiple forms are supported
	      for  compatibility  with other linkers.  Use any of them to make
	      ld assign	space to common	symbols	even if	a  relocatable	output
	      file is specified	(-r).  The script command FORCE_COMMON_ALLOCA-
	      TION has the same	effect.

       -defsym symbol =	expression
	      Create a global symbol in	the output file, containing the	 abso-
	      lute  address  given  by expression.  You	may use	this option as
	      many times as necessary to define	multiple symbols in  the  com-
	      mand  line.   A  limited form of arithmetic is supported for the
	      expression in this context: you may give a hexadecimal  constant
	      or the name of an	existing symbol, or use	+ and -	to add or sub-
	      tract hexadecimal	constants or symbols.  If you need more	elabo-
	      rate  expressions,  consider  using  the linker command language
	      from a script.

       -e entry
	      Use entry	as the explicit	symbol for beginning execution of your
	      program,	rather than the	default	entry point.  for a discussion
	      of defaults and other ways of specifying the entry point.

       -embedded-relocs
	      This option is only meaningful when linking  MIPS	 embedded  PIC
	      code, generated by the -membedded-pic option to the GNU compiler
	      and assembler.  It causes	the linker to create a table which may
	      be  used	at  runtime  to	relocate any data which	was statically
	      initialized to pointer values.  See the code in testsuite/ld-em-
	      pic for details.

       -E

       -export-dynamic
	      When creating an ELF file, add all symbols to the	dynamic	symbol
	      table.  Normally,	the dynamic symbol table contains only symbols
	      which  are  used by a dynamic object.  This option is needed for
	      some uses	of dlopen.

       -f name

       --auxiliary name
	      When creating an ELF shared object, set the  internal  DT_AUXIL-
	      IARY field to the	specified name.	 This tells the	dynamic	linker
	      that the symbol table of the shared object should	be used	as  an
	      auxiliary	filter on the symbol table of the shared object	name.

       -F name

       --filter	name
	      When  creating  an ELF shared object, set	the internal DT_FILTER
	      field to the specified name.  This tells the dynamic linker that
	      the symbol table of the shared object should be used as a	filter
	      on the symbol table of the shared	object name.

       -format input-format
	      Synonym for -b input-format.

       -g     Accepted,	but ignored; provided  for  compatibility  with	 other
	      tools.

       -G  sizeSet  the	 maximum  size of objects to be	optimized using	the GP
       register
	      to size under MIPS ECOFF.	 Ignored for other  object  file  for-
	      mats.

       -h name

       -soname name
	      When  creating  an ELF shared object, set	the internal DT_SONAME
	      field to the specified name.  When an executable is linked  with
	      a	 shared	object which has a DT_SONAME field, then when the exe-
	      cutable is run the dynamic  linker  will	attempt	 to  load  the
	      shared  object  specified	by the DT_SONAME field rather than the
	      using the	file name given	to the linker.

       --help Print a summary of the command-line options on the standard out-
	      put  and	exit.  This option and --version begin with two	dashes
	      instead of one for compatibility with other GNU  programs.   The
	      other  options  start  with only one dash	for compatibility with
	      other linkers.

       -i     Perform an incremental link (same	as option -r).

       -lar   Add an archive file ar to	the list of files to link.   This  op-
	      tion  may	be used	any number of times.  ld will search its path-
	      list for occurrences of libar.a for every	ar specified.

       -Lsearchdir
	      This command adds	path searchdir to the list of  paths  that  ld
	      will  search for archive libraries.  You may use this option any
	      number of	times.

	      The default set of paths searched	(without being specified  with
	      -L) depends on what emulation mode ld is using, and in some cas-
	      es also on how it	was configured.	   The paths can also be spec-
	      ified in a link script with the SEARCH_DIR command.

       -M     Print  (to  the standard output file) a link map--diagnostic in-
	      formation	about where symbols are	mapped by ld, and  information
	      on global	common storage allocation.

       -Map mapfilePrint to the	file
	      mapfile  a  link map--diagnostic information about where symbols
	      are mapped by ld,	and information	on global common storage allo-
	      cation.

       -m emulationEmulate the
	      emulation	 linker.   You	can list the available emulations with
	      the --verbose or -V options.  This  option  overrides  the  com-
	      piled-in	default,  which	is the system for which	you configured
	      ld.

       -N     specifies	readable and writable text and data sections.  If  the
	      output  format  supports Unix style magic	numbers, the output is
	      marked as	OMAGIC.

	      When you use the `-N' option, the	linker does not	page-align the
	      data segment.

       -n     sets  the	text segment to	be read	only, and NMAGIC is written if
	      possible.

       -noinhibit-exec
	      Normally,	the linker will	not produce an output file if  it  en-
	      counters	errors	during	the link process.  With	this flag, you
	      can specify that you wish	the output file	 retained  even	 after
	      non-fatal	errors.

       -no-keep-memory
	      The  linker  normally  optimizes	for speed over memory usage by
	      caching the symbol tables	of input files in memory.  This	option
	      tells  the  linker  to  instead  optimize	 for  memory usage, by
	      rereading	the symbol tables as necessary.	 This may be  required
	      if the linker runs out of	memory space while linking a large ex-
	      ecutable.

       -no-warn-mismatch
	      Normally the linker will give an error if	you try	 to  link  to-
	      gether  input files that are mismatched for some reason, perhaps
	      because they have	been compiled for different processors or  for
	      different	 endiannesses.	 This  option tells the	linker that it
	      should silently permit such possible errors.  This option	should
	      only  be	used with care,	in cases when you have taken some spe-
	      cial action that ensures that the	linker errors are  inappropri-
	      ate.

       -o output
	      output  is a name	for the	program	produced by ld;	if this	option
	      is not specified,	the name `a.out'  is  used  by	default.   The
	      script command OUTPUT can	also specify the output	file name.

       -oformat	output-format
	      Specify the binary format	for the	output object file.  You don't
	      usually need to specify this, as ld is configured	to produce  as
	      a	 default  output format	the most usual format on each machine.
	      output-format is a text string, the name of a particular	format
	      supported	 by the	BFD libraries.	The script command OUTPUT_FOR-
	      MAT can also specify the output format, but  this	 option	 over-
	      rides it.

       -R filename
	      Read  symbol names and their addresses from filename, but	do not
	      relocate it or include it	in the output.	This allows your  out-
	      put  file	 to refer symbolically to absolute locations of	memory
	      defined in other programs.

       -relax An option	with machine dependent effects.	 Currently this	option
	      is only supported	on the H8/300.

	      On  some	platforms, use this option to perform global optimiza-
	      tions that become	possible when the linker  resolves  addressing
	      in your program, such as relaxing	address	modes and synthesizing
	      new instructions in the output object file.

	      On platforms where this is not supported,	`-relax' is  accepted,
	      but has no effect.

       -r     Generates	relocatable output--i.e., generate an output file that
	      can in turn serve	as input to ld.	 This is often called  partial
	      linking.	 As  a side effect, in environments that support stan-
	      dard Unix	magic numbers, this option also	sets the output	file's
	      magic number to OMAGIC.  If this option is not specified,	an ab-
	      solute file is produced.	When linking C++ programs, this	option
	      will  not	resolve	references to constructors; -Ur	is an alterna-
	      tive.

	      This option does the same	as -i.

       -rpath directory
	      Add a directory to the runtime library  search  path.   This  is
	      used  when  linking  an ELF executable with shared objects.  All
	      -rpath arguments are concatenated	 and  passed  to  the  runtime
	      linker,  which  uses  them  to locate shared objects at runtime.
	      The -rpath option	is also	 used  when  locating  shared  objects
	      which  are  needed  by shared objects explicitly included	in the
	      link; see	the description	of the -rpath-link option.  If	-rpath
	      is  not used when	linking	an ELF executable, the contents	of the
	      environment variable LD_RUN_PATH will be used if it is defined.

	      The -rpath option	may also be used on  SunOS.   By  default,  on
	      SunOS,  the  linker  will	form a runtime search patch out	of all
	      the -L options it	is given.  If a	-rpath	option	is  used,  the
	      runtime  search path will	be formed exclusively using the	-rpath
	      options, ignoring	the -L options.	 This can be useful when using
	      gcc,  which  adds	 many  -L  options which may be	on NFS mounted
	      filesystems.

       -rpath-link directory
	      When using ELF or	SunOS, one shared library may require another.
	      This  happens  when an ld	-shared	link includes a	shared library
	      as one of	the input files.

	      When the linker encounters such a	dependency when	doing  a  non-
	      shared,  non-relocateable	link, it will automatically try	to lo-
	      cate the required	shared library and include it in the link,  if
	      it  is not included explicitly.  In such a case, the -rpath-link
	      option specifies the first set of	directories  to	 search.   The
	      -rpath-link option may specify a sequence	of directory names ei-
	      ther by specifying a list	of names separated by  colons,	or  by
	      appearing	multiple times.

	      If the required shared library is	not found, the linker will is-
	      sue a warning and	continue with the link.

       -S     Omits debugger symbol information	(but not all symbols) from the
	      output file.

       -s     Omits all	symbol information from	the output file.

       -shared
	      Create  a	 shared	 library.  This	is currently only supported on
	      ELF and SunOS platforms (on SunOS	it is  not  required,  as  the
	      linker will automatically	create a shared	library	when there are
	      undefined	symbols	and the	-e option is not used).

       -sort-common
	      Normally,	when ld	places the global common symbols in the	appro-
	      priate  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  dis-
	      ables that sorting.

       -split-by-reloc count
	      Trys  to	creates	 extra	sections in the	output file so that no
	      single output section in the file	contains more than count relo-
	      cations.	 This  is  useful when generating huge relocatable for
	      downloading into certain real time kernels with the COFF	object
	      file format; since COFF cannot represent more than 65535 reloca-
	      tions in a single	section.  Note that this  will	fail  to  work
	      with  object  file  formats  which do not	support	arbitrary sec-
	      tions.  The linker will not split	up individual  input  sections
	      for  redistribution,  so if a single input section contains more
	      than count relocations one output	section	will contain that many
	      relocations.

       -split-by-file
	      Similar  to -split-by-reloc but creates a	new output section for
	      each input file.

       -Tbss org

       -Tdata org

       -Ttext orgUse org as the	starting address for--respectively--the
	      bss, data, or the	text segment of	the output file.  textorg must
	      be a hexadecimal integer.

       -T commandfile
	      Equivalent  to  -c commandfile; supported	for compatibility with
	      other tools.

       -t     Prints names of input files as ld	processes them.

       -u sym Forces sym to be entered in the output file as an	undefined sym-
	      bol.   This may, for example, trigger linking of additional mod-
	      ules from	standard libraries.  -u	may be repeated	with different
	      option arguments to enter	additional undefined symbols.

       -Ur    For  anything other than C++ programs, this option is equivalent
	      to -r: it	generates relocatable  output--i.e.,  an  output  file
	      that  can	 in  turn serve	as input to ld.	 When linking C++ pro-
	      grams, -Ur will resolve references to constructors, unlike -r.

       --verbose
	      Display the version number for ld	and list the supported	emula-
	      tions.  Display which input files	can and	can not	be opened.

       -v, -V Display the version number for ld.  The -V option	also lists the
	      supported	emulations.

       --version
	      Display the version number for ld	and exit.

       -warn-common
	      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.

       -warn-constructors
	      Warn if any global constructors are used.	 This is  only	useful
	      for  a  few  object file formats.	 For formats like COFF or ELF,
	      the linker can not detect	the use	of global constructors.

       -warn-multiple-gp
	      Warn if the output file requires multiple	global-pointer values.
	      This  option  is only meaningful for certain processors, such as
	      the Alpha.

       -warn-once
	      Only warn	once for each undefined	symbol,	rather than  once  per
	      module which refers to it.

       -warn-section-align
	      Warn  if	the address of an output section is changed because of
	      alignment.  Typically, the alignment will	be  set	 by  an	 input
	      section.	 The address will only be changed if it	not explicitly
	      specified; that is, if the SECTIONS command does not  specify  a
	      start address for	the section.

       --whole-archive
	      For  each	 archive  mentioned  on	 the  command  line  after the
	      --whole-archive option, include every object file	in the archive
	      in  the link, rather than	searching the archive for the required
	      object files.  This is normally used to turn an archive file in-
	      to  a shared library, forcing every object to be included	in the
	      resulting	shared library.

       --no-whole-archive
	      Turn off the effect of the --whole-archive option	 for  archives
	      which appear later on the	command	line.

       --wrap symbol
	      Use  a  wrapper function for symbol.  Any	undefined reference to
	      symbol will be resolved to __wrap_symbol.	 Any undefined	refer-
	      ence to __real_symbol will be resolved to	symbol.

       -X     Delete  all  temporary local symbols.  For most targets, this is
	      all local	symbols	whose names begin with `L'.

       -x     Delete all local symbols.

ENVIRONMENT
       You can change the behavior of ld with the environment variable GNUTAR-
       GET.

       GNUTARGET  determines  the input-file object format if you don't	use -b
       (or its synonym -format).  Its value should be one of the BFD names for
       an  input format.  If there is no GNUTARGET in the environment, ld uses
       the natural format of the host. If GNUTARGET is set to default then BFD
       attempts	 to discover the input format by examining binary input	files;
       this method often succeeds, but there are potential ambiguities,	 since
       there  is  no method of ensuring	that the magic number used to flag ob-
       ject-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.

SEE ALSO
       objdump(1)
       `ld' and	`binutils' entries in info
       ld: the GNU linker, Steve Chamberlain and Roland	Pesch; The GNU	Binary
       Utilities, Roland H. Pesch.

COPYING
       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 versions of this
       manual under the	conditions for verbatim	copying, provided that the en-
       tire resulting derived work is distributed under	the terms of a permis-
       sion notice identical to	this one.

       Permission is granted to	copy and distribute translations of this manu-
       al  into	another	language, under	the above conditions for modified ver-
       sions, except that this permission notice may be	included  in  transla-
       tions approved by the Free Software Foundation instead of in the	origi-
       nal English.

cygnus support			17 August 1992				 ld(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | SEE ALSO | COPYING

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ld&sektion=1&manpath=FreeBSD+3.2-RELEASE>

home | help