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

FreeBSD Manual Pages

  
 
  

home | help
ld(1)			    General Commands Manual			 ld(1)

NAME
       ld - link editor

SYNOPSIS
   The link editor.
       search] filename]
	      epsym] symbol] ...  filename] x |	file] ...
	      library] outfile]
	      symbol] ...  symbol] ...	name]
	      bind] ...	 n] offset] dir] ...
	      file] file] offset]
	      path_list] oldpath:newpath] path]
	      file]
	      filename]	symbol]	...  symbol] ...
	      shared_library_path]
	      function]	...
	      size] size] internal_name]
	      percentage]
	      function]	...  filename]
	      filename]
	      shared_library_name] pagesize]
	      pagesize]	size] name] size]
	      flag]
	      type] flag] symbol] ...
	      n]
	      size]

DESCRIPTION
       takes  one or more object files or libraries as input and combines them
       to produce a single (usually executable)	file.  In doing	so it resolves
       references  to  external	symbols, assigns final addresses to procedures
       and variables, revises code  and	 data  to  reflect  new	 addresses  (a
       process	called	"relocation"),	and updates symbolic debug information
       when present in the file.  By default, produces an executable file that
       can  be	run  by	 the  HP-UX  loader (see exec(2)).  Alternatively, the
       linker can generate a relocatable file that  is	suitable  for  further
       processing  by (see below).  It can also	generate a shared library (see
       below).	The linker marks the output file non-executable	if  there  are
       any  duplicate  symbols	or  any	unresolved external references remain.
       may or may not generate an output file (see option) if any other	errors
       occur during its	operation.

       recognizes three	kinds of input files: object files created by the com-
       pilers, assembler, or linker (also known	as  files),  shared  libraries
       created	by  the	 linker,  and archives of object files (called archive
       libraries).  An archive library contains	a table	of all the externally-
       visible symbols from its	component object files.	 (The archiver command
       ar(1) creates and maintains this	index.)	 uses this  table  to  resolve
       references to external symbols.

       processes  files	 in the	same order as they appear on the command line.
       It includes code	and data from an archive library element if  and  only
       if  that	object module provides a definition for	a currently unresolved
       reference within	the user's program (see	It is common practice to  list
       libraries following the names of	all simple object files	on the command
       line.

       Code and	data from shared libraries is never copied into	an  executable
       program.	  For  32-bit mode, crt0.o is found at For 64-bit mode,	crt0.o
       is found	at You should include in a link.  For 32-bit mode, the dynamic
       loader  is found	at For 64-bit mode, the	dynamic	loader is found	at The
       dynamic loader attaches	each  required	library	 to  the  process  and
       resolves	all symbolic references	between	the program and	its libraries.

       The text	segment	of a shared library is shared among all	processes that
       use the library;	each process using the library receives	its  own  copy
       of  the data segment.  If has been run on the executable	that loads the
       library,	the text segment of a shared library is	mapped	privately  for
       each  process  running the executable.  recursively examines the	depen-
       dencies of shared libraries used	by a program that was  created	by  If
       does  not  find a supporting shared library at the path recorded	in the
       dependency list of a shared library,  and  if  the  dependency  is  the
       result of an argument used when the shared library was created, searchs
       all the directories that	it would search	for a library that was	speci-
       fied with (see and

   Options
	      Specify whether shared or	archive	libraries are searched
			     with  the	option.	 The value of search should be
			     one of or This option can appear more than	 once,
			     interspersed   among   options,  to  control  the
			     searching for each	library.  The  default	is  to
			     use  the  shared  version	of a library if	one is
			     available,	or the archive version if not.

			     If	 either	 or  is	 active,  only	the  specified
			     library type is accepted.

			     If	 is active, the	archive	form is	preferred, but
			     the shared	form is	allowed.

			     If	is active, the shared form  is	preferred  but
			     the archive form is allowed.

			     To	 create	 a  statically-bound  program, use the
			     option rather than

	      Create a shared library rather than a normal executable file.
			     Object files processed with this option must con-
			     tain (PIC), generated by default by the compiler.
			     See the discussion	of  position-independent  code
			     in	cc(1), aCC(1), f90(1), as(1), and

	      Read ld options from a file.
			     Each  line	 contains zero or more arguments sepa-
			     rated by white space.  Each  line	in  the	 file,
			     including	the last line, must end	with a newline
			     character.	 A character implies that the rest  of
			     the  line	is  a comment.	To escape a character,
			     use the sequence

	      Force definition of ``common'' symbols; that is, assign
			     addresses and sizes, for output.

	      This option is the default.  Instructs the linker	to  produce  a
	      dynamically
			     linked executable (a program which	can use	shared
			     libraries).  This option is the complement	of

			     If	no shared libraries are	linked in, the	linker
			     builds a dynamically linked executable.  However,
			     in	PA32-bit mode using the	option,	if  no	shared
			     libraries	are  linked  in,  the  linker builds a
			     statically	bound  executable  (or	archive	 bound
			     executable).

			     For  dynamically  linked executables, the dynamic
			     loader is involved	in the process of loading  the
			     executable,  regardless  of whether it was	linked
			     with shared libraries.  For (or statically	bound)
			     programs,	control	 does  not pass	to the dynamic
			     loader.  See dld.so(5) for	more information.

	      Set the default entry point address for the output  file	to  be
	      that of
			     the  symbol  epsym.  (This	option only applies to
			     executable	files.)

	      Prior to writing the symbol table	to the output file,
			     mark this name as ``local''  so  that  it	is  no
			     longer  externally	 visible.   This  ensures that
			     this particular entry will	not clash with a defi-
			     nition  in	 another file during future processing
			     by	If used	when building a	shared library or pro-
			     gram,  this option	prevents the named symbol from
			     being visible to the dynamic loader.

			     You can specify more than one symbol on the  com-
			     mand line with multiple option-symbol pairs, that
			     is, each symbol you specify must be  preceded  by
			     the option.

	      Specify a	mapfile	that describes the output file memory map.

			     Please  refer  to guide and the for more informa-
			     tion.

	      Search a library
			     or	where x	is one or more characters.   The  cur-
			     rent  state  of the option	determines whether the
			     archive or	shared or  version  of	a  library  is
			     searched.	Because	a library is searched when its
			     name is encountered, the placement	of a  is  sig-
			     nificant.	  By  default,	32-bit	libraries  are
			     located in	64-bit libraries are located in	If the
			     environment  variable  is	present	 in the	user's
			     environment, it should contain a  colon-separated
			     list of directories to search.  These directories
			     are searched instead of the default  directories,
			     but options can still be used.  If	a program uses
			     shared libraries, the dynamic loader, for 32-bit,
			     or	for 64-bit, attempts to	load each library from
			     the same directory	in which it was	found at  link
			     time (see the and options).

	      Search the library specified. Similar to the
			     option  except the	current	state of the option is
			     not important. The	library	name can be any	 valid
			     filename.

	      Produce a	load map on the	standard output.

	      This option is ignored.

	      Force the	linker to create a fully archive bound program
			     (also called statically-bound executable).	 Spec-
			     ify or (or	equivalent startup  code)  on  the  ld
			     command  line  when  you  use  this option.  This
			     option is the complement of

			     For dynamically linked executables,  the  dynamic
			     loader  is	involved in the	process	of loading the
			     executable, regardless of whether it  was	linked
			     with  shared  libraries.	For  statically	linked
			     programs, control does not	pass  to  the  dynamic
			     loader.

	      Create  a	 dynamically  linked  program  if shared libraries are
	      linked in.
			     If	no shared libraries are	linked in, the	linker
			     creates  a	 fully	archive	 bound	program.  This
			     option is the default in compatibility mode (with
			     the options.   See	also the and options.

	      Produce an output	object file named
			     outfile if	outfile	is not specified).

	      This option is ignored.

	      Retain  relocation information in	the output file	for subsequent
	      re-linking.
			     The command does not  report  undefined  symbols.
			     This option cannot	be used	when building a	shared
			     library ( ) or in conjunction  with  the  or  the
			     incremental linking options.

	      Strip the	output file of all symbol table, relocation,
			     and  debug	 support  information.	 (The strip(1)
			     command also  removes  this  information.)	  This
			     option  is	 incompatible  with the	option and the
			     option.

			     Note:  Use	of the option might impair or  prevent
			     the  use  of a symbolic debugger on the resulting
			     program.

	      When building a shared library, causes the linker	to resolve all
	      references
			     to	 the specified symbol to the symbol defined in
			     the library.  This	option is similar to but oper-
			     ates on a per symbol basis.

			     You  can specify more than	one symbol on the com-
			     mand line with multiple option-symbol pairs, that
			     is,  each	symbol you specify must	be preceded by
			     the option.

	      Print a trace (to	standard output) of each input file as
			     processes it.

	      Enter	     symbol as an undefined symbol in the  symbol  ta-
			     ble.   The	resulting unresolved reference is use-
			     ful for linking  a	 program  solely  from	object
			     files in a	library.

			     You  can specify more than	one symbol on the com-
			     mand line with multiple option-symbol pairs, that
			     is,  each	symbol you specify must	be preceded by
			     the option.

	      Display verbose messages during linking.
			     This option is equivalent to (see the option  for
			     more information).

	      Strip local symbols from the output file.	 This reduces
			     the size of the output file without impairing the
			     effectiveness of  object  file  utilities.	  This
			     option  is	 incompatible  with the	option and the
			     options.  (The incremental	 linker	 requires  the
			     parts   of	 the  output  load  module  which  are
			     stripped out with the option.)

			     Note:  Use	of the option might impair or  prevent
			     the  use  of a symbolic debugger on the resulting
			     program.

	      Indicate each file in which
			     symbol appears.  You can specify  more  than  one
			     symbol  on	the command line with multiple option-
			     symbol pairs, that	is, each  symbol  you  specify
			     must be preceded by the option.

	      Arrange for run-time dereferencing of null pointers to produce a
			     signal.   (This  is the complement	of the option.
			     is	the default.)

	      This option is ignored and generates a warning message.

	      Select run-time binding  behavior	 of  a	program	 using	shared
	      libraries	or
			     the  binding  preference  in  building  a	shared
			     library.  The most	common values for bind are:

			     Bind addresses on first reference
				    rather than	at program start-up time. This
				    is the default.

			     Bind  addresses  of  all symbols immediately upon
			     loading the library.
				    Commonly followed by  to  allow  procedure
				    calls  that	 cannot	be resolved at program
				    start-up to	be resolved  on	 first	refer-
				    ence.

				    Since suppresses messages about unresolved
				    symbols, also  specify  to	display	 those
				    messages.

				    See	the example below.

			     If	also using
				    for	 code  symbols that could not be bound
				    at program	startup,  defer	 binding  them
				    until  they	 are referenced.  See descrip-
				    tion of above.

				    Since suppresses messages about unresolved
				    symbols,  also  specify  to	 display those
				    messages.

			     Causes the	search for a symbol definition	to  be
			     restricted	to
				    those  symbols  that were visible when the
				    library was	loaded.

			     Used only when building a shared  library.	  This
			     option causes all
				    references	in  a  shared  library	to  be
				    resolved  internally  if  possible.	  Such
				    internally-resolved	  symbols   are	 still
				    externally visible.	 By  default  (without
				    the	 option),  references to a symbol in a
				    shared library are resolved	 to  the  most
				    visible definition.	 The first load	module
				    (a.out or  shared  library)	 that  exports
				    that symbol	contains the most visible def-
				    inition.  More than	one  load  module  can
				    define and export the same symbol.	Refer-
				    ences to a symbol in a shared library  can
				    be	resolved  to  a	 definition in another
				    shared library  even  if  that  symbol  is
				    defined  in	 the  shared library.  You can
				    use	this option to enforce that all	refer-
				    ences  in the shared library use their own
				    definitions,  if  defined  in  the	shared
				    library.   See  the	 and  options for more
				    information	  about	  using	  with	 those
				    options.

			     Display  verbose  messages	 when binding symbols.
			     This is the default except	when
				    is	specified.  In	that  case,  must   be
				    explicitly	specified  to get verbose mes-
				    sages.

			     Use the option or see the manual for more	infor-
			     mation on the uses	of binding modes.

	      This option is ignored and generates a warning message.

	      Set  (in	hexadecimal) the starting address of the data segment.
	      This
			     option is useful with kernel and embedded	appli-
			     cations.	The default address for	64-bit mode is
			     0x6000000000000000	and the	 default  address  for
			     32-bit mode is 0x40000000.

	      Mark all symbols defined by a program for	export
			     to	 shared	libraries.  In a mode link, marks only
			     those symbols that	are actually referenced	 by  a
			     shared library seen at link time.	In a link, all
			     symbols are exported by default, so is not	neces-
			     sary to make symbols visible.  However, it	has an
			     additional	 side  effect	of   identifying   all
			     exported  symbols as necessary, so	that they will
			     not be removed when using dead code elimination

	      Force load the archive library.  Equivalent to

	      This option is ignored and generates a warning.

	      This option is accepted and ignored.

	      Strip all	unloadable data	from the output	file.
			     This option is  typically	used  to  strip	 debug
			     information and is	incompatible with the option.

			     Note:   Use of the	option might impair or prevent
			     the use of	a symbolic debugger on	the  resulting
			     program.

	      Instrument  the  code to collect profile information upon	execu-
	      tion.
			     When an instrumented program is executed, a  pro-
			     file  database  file is output (by	default, named
			     flow.data).  The  profile	data  gathered	during
			     program execution can be used in conjunction with
			     the option.   The	default	 instrumenter  is  the
			     dynamic  instrumenter  but	the option can be used
			     to	invoke the static instrumenter instead.

			     This option  should  not  be  used	 with  the  or
			     options.

			     If	 using	the  recommended  method to instrument
			     your programs is to use your  compiler's  option,
			     rather than the option.  If you invoke the	linker
			     directly, you must	pass the and  options  to  the
			     linker.   If you have both	an instrumented	shared
			     library and  an  instrumented  shared  executable
			     that you want to link with	that library, you must
			     include  the  and	options	 in  addition  to  the
			     options.	If  using the default or no additional
			     linker options are	needed.

	      Search for     or	in dir before looking  in  default  locations.
			     You can specify more than one directory, but each
			     must be preceded by the option.   The  option  is
			     effective	only  if it precedes the option	on the
			     command line.

	      In 32-bit	mode only, cause the data  to  be  placed  immediately
	      following	the
			     text,  and	 make the text writable. Files of this
			     type cannot be shared.

	      Turn on linker optimizations.
			     Currently the optimization	includes  the  removal
			     of	dead procedures.

			     is	passed to the linker by	the compilers when the
			     compiler option is	selected.

			     This option is incompatible with the option.

			     For more details on linker	optimizations use  the
			     option or see the manual.

	      Examine  the  profile  database file produced by an instrumented
	      program
			     (see the option) to perform profile  based	 opti-
			     mizations on the code.  This option should	not be
			     used with the option.

	      Reorder debuggable functions.  Ordinarily
			     does not reorder functions	from files with	debug-
			     ging information, because reordering renders them
			     non-debuggable.  This option overrides  this  and
			     reorders  the  functions.	Reordering is based on
			     link  order  file	produced  from	flow.data   by
			     default.	If  you	specify	the option, the	linker
			     does not  use  flow.data  for  reordering.	  This
			     option is incompatible with

			     Note:   Use of the	option might impair or prevent
			     the use of	a symbolic debugger on	the  resulting
			     program.

	      Save link	order file generated by
			     during  linking  with  option into	user-specified
			     file.   This  option  is  incompatible  with  the
			     option.

	      Indicate	to  the	 linker	to use the specified file for the link
	      order file
			     instead of	generating it  using  This  option  is
			     incompatible with the option.

	      This option is ignored.

	      Set  (in	hexadecimal)  the  starting address of the text	(i.e.,
	      code) segment.
			     This option is useful with	 kernel	 and  embedded
			     applications.   The  default  address  for	64-bit
			     mode is 0x4000000000000000	and 0x04000000.	 If -N
			     option is specified, the default is 0x1000.

	      This option is ignored and generates a warning message.

	      This option is ignored.

	      Output a message giving information about	the version of
			     being used.

	      This is the default. Allow run-time dereferencing	of null	point-
	      ers.
			     See the discussions of  and  pointers  in	cc(1).
			     (This is the complement of	the option.)

	      Control unsatisfied symbol error reporting.
			     does not flag errors if the resulting output file
			     has unsatisfied symbols.  This is the default for
			     relocatable  links	 and  shared  library  builds.
			     flags an error if the resulting output  file  has
			     unsatisfied  symbols.   This  is  the default for
			     program files.

	      The	     option  loads  all	 object	 files	from   archive
			     libraries.	  is  the  default  --	loads only the
			     required object  files  from  archive  libraries.
			     The  mode	that is	selected, either explicitly or
			     by	default, remains on until it is	changed.

	      Specify a	colon-separated	list of	directories
			     to	be searched  at	 program  run-time  to	locate
			     shared  libraries needed by the executable	output
			     file that	were  specified	 with  either  the  or
			     options.	This  list  of directories becomes the
			     embedded path.  If	either is not used or  if  you
			     specify a single colon as the argument, builds an
			     embedded path using all the directories specified
			     by	 the  option(s)	 and  the environment variable
			     (see the option).

	      This option is ignored.

	      Turn on compatibility mode in the	linker -- mimic
			     behavior of PA-RISC 32-bit	links.

	      When you use the
			     linker option to override the effect of the  com-
			     piler  option,  the  linker omits the information
			     from the object files  (in	 addition  to  copying
			     over  the	debug information to the output	file).
			     However, if any object files were the  result  of
			     previous  links, the information from these files
			     is	not omitted.  The option, when	used  in  con-
			     junction  with  the  option, forces the linker to
			     omit information from all object files, including
			     objects   generated  with	the  option.   is  the
			     default.

	      is the default.  Include any paths that are specified with
			     in	the embedded  path,  unless  you  specify  the
			     option.   If you use only the path	list specified
			     by	is in the embedded path.

			     The option	removes	all library  paths  that  were
			     specified with the	option from the	embedded path.
			     The linker	searches the library  paths  specified
			     by	 the  option  at  link time.  At run time, the
			     only library paths	searched are  those  specified
			     by	 the  environment  variables and library paths
			     specified by the linker option, and  finally  the
			     default library paths.

	      Used together with the
			     option, this option specifies that	file should be
			     used as the profile database file.	  The  default
			     value  is	See  the discussion of the environment
			     variable for more information.   This  option  is
			     incompatible with the option.

	      Output  information on procedures	that were eliminated by	proce-
	      lim.
			     Equivalent	to

	      Valid for	executables and	shared library links.	Instructs  the
	      linker to
			     dump all external symbols into the	file specified
			     by	filename.  This	 dumps	all  external  symbols
			     referred  to  within  the	load  module (a.out or
			     shared library) but not defined within  the  load
			     module  into  the	specified  file.  You can pass
			     this file back to your compiler using the option.
			     For  more	information, see the compiler options,
			     and

	      When building a shared library or	program,
			     mark the symbol for export	to the dynamic loader.
			     Only  symbols  explicitly	marked	are  exported.
			     When building a shared library, calls to  symbols
			     that are not exported are resolved	internally.

			     If	 you  use the or option	with references	to the
			     symbol  specified	are  resolved  internally   if
			     defined.	The  runtime behavior may be different
			     from using	alone.

			     You can specify more than one symbol on the  com-
			     mand line with multiple option-symbol pairs, that
			     is, each symbol you specify must be  preceded  by
			     the option.

	      This option is similar to	the
			     option  in	 that  it  exports a symbol.  However,
			     unlike the	option,	the option does	not alter  the
			     visibility	 of any	other symbol in	the file. When
			     building a	mode executable,  by  default  exports
			     only  those  symbols that are actually referenced
			     by	a shared  library  seen	 at  link  time.   The
			     option  when  specified  with  has	 the effect of
			     exporting the specified symbol without hiding any
			     of	 the  symbols  exported	by default.  In	a mode
			     link, all symbols are exported by default,	so +ee
			     is	 not  necessary	to make	a symbol visible. How-
			     ever, it has the additional side effect of	 iden-
			     tifying  the symbol as necessary, so that it will
			     not be removed when using dead  code  elimination
			     The  option  still	retains	its export behavior if
			     an	option such as is also given.

			     You can specify more than one symbol on the  com-
			     mand line with multiple option-symbol pairs, that
			     is, each symbol you specify must be  preceded  by
			     the option.

	      Instruct the linker to run the fastbind tool
			     on	 the  executable  it  has  produced.  The exe-
			     cutable should be linked with  shared  libraries.
			     For  more	details	 about	fastbind(1),  use  the
			     option, or	see the	manual.	 This option is	incom-
			     patible with the option.

	      Pass the	     option  to	 the  fastbind	tool. For more details
			     about fastbind(1),	use the	 option,  or  see  the
			     manual.   This  option  is	 incompatible with the
			     option.

	      Enables the shared library filter	mechanism, which allows	you to
			     divide a large library into a "filter"  and  sev-
			     eral  "implementation"  libraries	for more effi-
			     cient   organization   of	  shared    libraries.
			     shared_library_path specifies the location	of the
			     filter library.  See the for more information.

	      Specify the terminator function to be invoked in forward	order,
	      the order
			     the functions appear left to right	on the command
			     line.

			     You can specify more than one terminator function
			     on	 the  command line with	multiple option-symbol
			     pairs, that is, each function you specify must be
			     preceded by the option.

	      The default is loads  all	 object	 files from archive libraries.
			     loads only	the required object files from archive
			     libraries.	  The selected mode, either explicitly
			     or	 by  default,  remains	in  effect  until  you
			     explicitly	change it.

	      Enable the global	symbol table hash mechanism,
			     used  to  look  up	values of symbol import/export
			     entries.  The and related options provide perfor-
			     mance  enhancements  through use of global	symbol
			     table which improves searching for	exported  sym-
			     bols.   See  dld.so(5)  and the for more informa-
			     tion.

	      This option is ignored.

	      Request a	particular hash	array size using the global symbol
			     table hash	mechanism.  The	default	value is 1103.
			     The value can be overridden at runtime by setting
			     the environment variable to the value prime  num-
			     ber.  You can set the value using size file.

	      When building a shared library, record
			     internal_name  as	the name of the	library.  When
			     the library is used to  link  another  executable
			     file  (program  or	 shared	 library), this	inter-
			     nal_name is recorded in the library list  of  the
			     resulting	output file instead of the pathname of
			     the input shared library.	That  is,  if  is  not
			     used,  the	shared library does not	have an	inter-
			     nal name and when an executable is	built with the
			     shared  library,  the  linker records the library
			     name that it looks	at.

			     If	more than one +h option	is seen	 on  the  link
			     line,  the	 linker	uses the first one and emits a
			     warning message.

	      Start the	help browser utility
			     which comes with the HP-UX	operating system.  For
			     more  information,	 see to	the manual.  See manu-
			     als(5) for	ordering information.

	      Prevent all the symbols from being  exported  unless  explicitly
	      exported
			     with the This option marks	all symbols as "local"
			     in	the symbol table.  See also the	and options.

	      Specify incremental linking.

			     If	the output file	does not exist,	or if  it  was
			     created  without  the option, the linker performs
			     an	initial	incremental  link.   The  output  file
			     produced  is  suitable for	subsequent incremental
			     links.  The incremental link option is valid  for
			     both executable and shared	library	links.

			     The  following  options are incompatible with the
			     option.  If you  specify  one  of	the  following
			     incompatible  ld  option  with the	linker emits a
			     warning message and ignores the option.

			     create a relocatable object file.

			     Strip options:
				    and	strip the output file.

			     Optimization options:
				    file, name,

			     The following options  are	 compatible  with  the
			     option with limitations:

			     Set the origin for	the data and text segments. If
			     you change	the offset
				    after the initial  incremental  link,  the
				    linker  performs  an  initial  incremental
				    link automatically.

			     Provide a non-default mapfile. The	user specified
			     mapfile
				    specifications   are  permitted  with  the
				    option. But	you should not modify the map-
				    file  after	 the initial incremental link.
				    If the mapfile is modified after the  ini-
				    tial  link,	an initial incremental link is
				    performed automatically.

	      Suppress incremental-linking related warnings.  By default,  the
	      linker issues
			     all  incremental-linking  related warnings.  This
			     option is ignored if used without or

	      Control the amount of padding
			     percentage	the incremental	linker allocates, rel-
			     ative  to	sizes  of object file structures being
			     padded. By	default	the linker allocates less than
			     20%  of padding space.  This option is ignored if
			     used without or

	      Perform an initial incremental link, regardless  of  the	output
	      load
			     module.

			     In	certain	situations (for	example, internal pad-
			     ding space	is exhausted) the  incremental	linker
			     is	forced to perform an initial incremental link.
			     The option	allows you to  avoid  such  unexpected
			     initial   incremental   links   by	  periodically
			     rebuilding	the output file.

	      Specify the initializer function to be invoked in	reverse	order,
	      the
			     order  the	 functions appear right	to left	on the
			     command line.

			     You can specify more than one  initializer	 func-
			     tion  on  the  command line with multiple option-
			     symbol pairs, that	is, each initializer  function
			     you specify must be preceded by the option.

	      Specify which instrumenter to use.  Only
			     or	 are  recognized.  Default is If is specified,
			     the linker	 will  invoke  automatically.	If  is
			     specified,	 will  be automatically	invoked	by the
			     dynamic loader when the program is	executed.

	      Change the     path to use the program specified by filename for
			     the  "interpreter"	program	as the dynamic loader.
			     This is useful when  using	 special  versions  of
			     dld.so  for  debugging.   The default path	is for
			     32-bit programs and for 64-bit programs.

	      Direct the linker	to only	create an executable if	there were
			     no	errors encountered during the link.  If	 there
			     were  errors  found  (system errors or unresolved
			     references), the output file will be removed.

	      Sets a flag in the executable which causes the dynamic loader to
	      merge
			     all  data	segments of shared libraries loaded at
			     startup time into one block.  Data	 segments  for
			     each  dynamically	loaded	library	 will  also be
			     merged  with  the	data  segments	of   dependent
			     libraries.	  This	increases run-time performance
			     by	allowing the kernel to use  larger  size  page
			     table entries.

	      Cause the	linker to load all object modules before searching
			     any archive or shared libraries.  The linker then
			     searches the archive and shared libraries	speci-
			     fied  on the command line in left to right	order.
			     It	repeats	 the  left  to	right  search  of  the
			     libraries	on the command line until there	are no
			     more unsatisfied  symbols,	 or  the  last	search
			     added  no new definitions.	 This option is	useful
			     if	two libraries are specified that  have	symbol
			     dependencies on each other.

	      Do not use the default memory map.  You must
			     supply a mapfile through the linker option.

	      Disable the default linker behavior of the
			     option  to	 create	 the .dynhash section for exe-
			     cutables or shared	libraries.  Use	this option to
			     eliminate	generation  of pre-computed hash table
			     information for a library or an  executable  that
			     is	 rarely	 used  with  the  global  symbol table
			     lookup scheme or for which	the overhead of	 stor-
			     ing  pre-computed	hash values is too high.  This
			     option has	no effect when used with the option.

	      Instruct the dynamic loader to ignore the	dynamic	path searching
	      environment
			     variables,	 LD_LIBRARY_PATH  and  SHLIB_PATH,  at
			     runtime.  By  default,  or	 if  you  specify  the
			     option,  the dynamic loader looks at the environ-
			     ment variables, that is,  the  environment	 vari-
			     ables  are	enabled.  If you specify the option or
			     the option,  the  option  takes  effect  and  the
			     dynamic  loader  ignores the variables (the envi-
			     ronment variables	are  disabled).	  See  the  or
			     options.	You  can  display  the	status of this
			     option in an executable or	 shared	 library  from
			     the  'shared  library dynamic path	search'	output
			     of	the command.  See chatr(1) for	more  informa-
			     tion.   Generally,	this option is used for	secure
			     programs.

	      Override the   compiler option, and copy all  debug  information
			     to	 the  executable  file.	 When you use the com-
			     piler option with	any  of	 the  options,	linker
			     leaves  the debug information in the object files
			     instead of	copying	it over	to  the	 output	 file.
			     You  can use the option at	link time to force the
			     linker to copy the	debug information over to  the
			     output file and negate the	effect of the compiler
			     option.  See also

	      With the	     option, allow procedures to be  positioned	 inde-
			     pendently.	  The  default	is to merge all	proce-
			     dures into	a single section.

	      This option is ignored.

	      In IC64 (32-bit and 64-bit), the compiler	option
			     is	the default.  causes the compiler to  generate
			     part  of the debug	information even when the com-
			     piler  option  is	not  specified.	  The  default
			     option  also causes part of the debug information
			     to	be always copied over to the executable	 file,
			     resulting	in  larger  executables.   enables the
			     users to profile programs using  tools  like  and
			     even in the absence of compilation.

			     The  linker  option  can  be used to override the
			     default compiler option, and  strip  these	 debug
			     information  during  link time.  can also be used
			     with to fully enforce the mode (i.e., leaving the
			     debug information in the object files).

	      Ignore debug information from non-objdebug objects or
			     archives  and proceed in mode.  If	you are	debug-
			     ging only files compiled  with  the  option,  can
			     improve  link  time  by instructing the linker to
			     bypass the	processing of debug  information  from
			     files compiled with

	      (Use only	before the
			     option  or	the name of a shared library.)	 Cause
			     the linker	 to  add  $ORIGIN  before  the	shared
			     library  name  in the shared library list and set
			     the DF_ORIGIN flag	for  the  output  module.   At
			     runtime,  the  dynamic loader determines the cur-
			     rent directory of the parent module (object  mod-
			     ule,  shared library, or executable) and replaces
			     for that directory	name.  For example,

			     While the option is  available,  the  recommended
			     way  to  specify is in the	embedded path with the
			     option, fo	example,

			     For more details on use the  option  or  see  the
			     manual.

	      Pads the data segment to a multiple of
			     pagesize with zeros.  This	can improve page allo-
			     cation, thus reduce TLB misses  by	 allowing  the
			     kernel to allocate	fewer, larger data pages.  Use
			     of	this option increases your output file size.

	      Pads the text segment to a multiple of
			     pagesize with zeros.  This	can improve page allo-
			     cation,  thus  reduce  TLB	misses by allowing the
			     kernel to allocate	fewer, larger data pages.  Use
			     of	this option increases your output file size.

	      Request  a  particular  virtual  memory page size	that should be
	      used for data.
			     Sizes of and are supported.  A size of allows the
			     kernel  to	 choose	what page size should be used.
			     A size of results in using	the largest page  size
			     available.	  The actual page size may vary	if the
			     requested size cannot be fulfilled.

	      This option is ignored.

	      With the	     option, specify that name should be used  as  the
			     look-up  name  in the profile database file.  The
			     default is	the basename of	the output file	(spec-
			     ified  by the option.)  This option is incompati-
			     ble with the option.

	      Request a	particular virtual memory page size that
			     should be used for	instructions.  See the	option
			     for additional information.

	      This option is ignored.

	      Specifies	the size of the	profiling sample counter buckets.
			     Valid values are 16 or 32.	 See gprof(1) for more
			     details.

	      This option is the default. Indicate that	at run-time, the
			     dynamic loader can	use the	environment  variables
			     and to locate shared libraries needed by the exe-
			     cutable output file that  allow  dynamic  library
			     searching.	  Shared  libraries that allow dynamic
			     library searching either contain an internal name
			     without  the  "/" (slash) character (for example,
			     the base name of the shared library pathname)  or
			     have  no  internal	 name  and were	specified with
			     either or or just the base	 name  of  the	shared
			     library   pathname.   The	environment  variables
			     should be set to a	colon-separated	list of	direc-
			     tories.

			     In	 compatibility	mode using the option, if both
			     and are used, their relative order	on the command
			     line  indicates which path	list is	searched first
			     (see the option). In standard mode	(default  mode
			     or	 using	the option), the order of and does not
			     affect the	dynamic	loader search  order  and  the
			     environment variables are always searched first.

	      This option will cause the paths specified in
			     (embedded path) to	be used	before the paths spec-
			     ified in or in searching  for  shared  libraries.
			     This  changes  the	 default  search  order	of and
			     (embedded path).

	      This option is the  default.   Turn  on  standard	 mode  of  the
	      linker.
			     This  option  is  the  complement	of the option.
			     Options set on with this option are: Options  set
			     off or ignored when this option is	specified are:

	      Do not output the	unwind table.  This creates smaller executable
	      sizes.
			     Use this option if	you do not need	the unwind ta-
			     ble for debugging or aC++ exception handling.

			     Note:   Use of the	option might impair or prevent
			     the use of	a symbolic debugger on	the  resulting
			     program.

	      This option is ignored.

	      This option is ignored.

	      This option is ignored.

	      Enable [disable] printing	a list of unsatisfied
			     symbols used by shared libraries.	The default is
			     Some unsatisfied symbols reported by  the	linker
			     are  not required at run time because the modules
			     which reference the symbols are not used.

	      Produces verbose output about the	link operation.
			     type can have the following values:

			     Dumps all of the information from the
				    options.  Same as

			     Dump info about each object file loaded.

			     Dump info about the size of the heap  used	 by  a
			     link.

			     Dump info about libraries searched.

			     Dump  info	 about	sections that have been	elimi-
			     nated by the
				    option

			     Dump info about each input	section	added  to  the
			     output file.

			     Dump info about global symbols referenced/defined
			     from/in the input files.

	      Specify how the environment for floating-point
			     operations	 should	 be  initialized  at   program
			     start-up.	 By  default,  all  behaviors are dis-
			     abled.  The following flags are supported	(upper
			     case flag enables;	lower case flag	disables):

			     Enable sudden underflow (flush to zero) of	denor-
			     malized values.

			     Trap on floating-point  operations	 that  produce
			     inexact results.

			     Trap  on Denormal|Unnormal	operand	floating-point
			     operation.

			     Trap on floating-point overflow.

			     Trap on floating-point underflow.

			     Trap on invalid floating-point operations.

			     Trap on divide by zero.

			     To	dynamically change these settings at run-time,
			     see fesettrapenable(3M).

	      Specify  the  name  of  the initializer function when building a
	      shared library.
			     A shared library may have	multiple  initializers
			     specified.	  Initializers	are  executed  in  the
			     order that	they  are  specified  on  the  command
			     line.

			     You  can  specify more than one initializer func-
			     tion on the command line  with  multiple  option-
			     symbol pairs, that	is, each initializer you spec-
			     ify must be preceded by the option.

			     This option is supported for compatibility.   Use
			     of	 the  and  For more details on the initializer
			     function, use the option or see the manual.

	      This option is ignored.

	      Enable [disable] the elimination of procedures that are not ref-
	      erenced by
			     the application.  The default is Procedure	elimi-
			     nation  can  occur	 at  any  optimization	level,
			     including	level  0.   For	 more  details use the
			     option or see the manual.	This option is	incom-
			     patible with the option.

	      This option is ignored and generates a warning message.

	      Instructs	the interprocedural optimizer driver to	pass the first
			     n	percent	 of the	object files to	the high level
			     optimizer for interprocedural optimizations  such
			     as	 inlining.  This option	is designed to work at
			     optimization level	4 (+O4)	 in  the  presence  of
			     dynamic profiling.

	      This option is accepted and ignored.

	      This option is accepted and ignored.

	      This option is ignored and generates a warning message.

   Defaults
       Unless  otherwise  directed, names its output file The option overrides
       this.  The default is to	create a dynamically linked program unless you
       specify the option.  The	default	state of is to search shared libraries
       if available, archive libraries otherwise.  The default	bind  behavior
       is

       The default value of the	option is

   The +objdebug Compiler Option
       The  compiler  option,  when  used  with	any of the options, causes the
       debug information to be left in	the  object  files  instead  of	 being
       placed  in  output file.	This results in	shorter	link times and smaller
       output files.

       To debug	the load modules compiled with option,	the  HP	 WDB  debugger
       must  have  access  to  the  object files.  (Note that for object files
       built with the option, the individual object files must be available to
       the  debugger.)	 If you	move the object	files, use HP WDB's command to
       specify the location of these objects.

       The compiler option causes the debug information	to be copied  over  to
       the output file.	 is the	compile-time default.

       If  the	linker	detects	 any  object files that	were compiled with the
       option, it leaves the debug information	in  those  files.  Any	object
       files  not  compiled  with have their debug information copied into the
       output file.

       You can use the option at link time to  continue	 to  place  the	 debug
       information  into  the  output file, even if some objects were compiled
       with

   Incremental linking
       In the edit-compile-link-debug development cycle, link time is  a  sig-
       nificant	 component.  The incremental linker (available through the and
       can reduce the link time	by taking advantage of the fact	that  you  can
       reuse  most  of	the  previous  version	of  the	 program  and that the
       unchanged object	files do not need to  be  processed.  The  incremental
       linker allows you to insert object code into an output file (executable
       or shared library) that you  created  earlier,  without	relinking  the
       unmodified  object files. The time required to relink after the initial
       incremental link	depends	on the number of modules you modify.

       The linker performs the following different modes of linking:

       o      normal link: the default operation  mode	in  which  the	linker
	      links all	modules.

       o      initial  incremental  link: the mode entered when	you request an
	      incremental link,	but the	output module created by the incremen-
	      tal  linker  does	 not  exist,  or it exists but the incremental
	      linker is	unable to perform an incremental update.

       o      incremental link:	the mode entered when you request an incremen-
	      tal  link,  an  output  module created by	the incremental	linker
	      exists, and the incremental linker does not require  an  initial
	      incremental link.

       Incremental  links  are	usually	much faster than regular links.	On the
       initial link, the incremental linker requires about the same amount  of
       time  that  a  normal link process requires, but	subsequent incremental
       links can be much faster	than a normal link.  A change  in  one	object
       file  in	 a moderate size link (tens of files, several megabytes	total)
       normally	is about 10 times faster than a	regular	link. The  incremental
       linker perform as many incremental links	as allocated padding space and
       other constrains	permit.	 The cost of  the  reduced  link  time	is  an
       increase	in the size of the executable or shared	library.

       The  incremental	 linker	 allocates padding space for all components of
       the output file.	Padding	makes modules larger than those	modules	linked
       by  As  object  files  increase	in  size during	successive incremental
       links, the incremental linker can exhaust  the  available  padding.  If
       this  occurs, it	displays a warning message and does a complete initial
       incremental link	of the module.

       On the initial incremental link,	the linker processes the input	object
       files  and libraries in the same	way as the normal link.	In addition to
       the normal linking process, the incremental  linker  saves  information
       about  object files, global symbols, and	relocations, and pads sections
       in the output file for expansion.  On subsequent	incremental links, the
       linker  uses  timestamps	 to determine which object files have changed,
       and updates those modules.

       Under certain conditions, the incremental linker	cannot perform	incre-
       mental  links.  When  this occurs, the incremental linker automatically
       performs	an initial incremental link to restore the  process.   In  the
       following  situations,  the  linker  automatically  performs an initial
       incremental link	of the output file:

       o      Changed linker command line, where the linker command line  does
	      not match	the command line stored	in the output file.  (With the
	      exceptions of the	verbose	and tracing options)

       o      Any of the padding spaces	have been exhausted.

       o      Modules have been	modified by the	or options or tools (for exam-
	      ple,

       o      Incompatible incremental linker version, when you	run a new ver-
	      sion of the incremental linker on	an executable  created	by  an
	      older version.

       o      New  working directory, where the	incremental linker performs an
	      initial incremental link if current directory changes.

       o      Archive or shared	libraries are added/removed to/from the	linker
	      command line.

       o      Object files are removed from the	linker command line.

       Use the option or see the for more information.

       The  incremental	linker searches	an archive library if there are	unsat-
       isfied symbols. It extracts all archive members satisfying  unsatisfied
       symbols	and processes them as new object files.	 If an archive library
       is modified, the	linker replaces	the modified archive library.

       An object file extracted	from an	archive	library	in the	previous  link
       remains	in  the	 output	 load module even if all references to symbols
       defined in the object file have been removed. The linker	removes	 these
       object files when it performs the next initial incremental link.

       In  an initial incremental link,	the linker scans shared	library	symbol
       tables and resolves unsatisfied symbols the same	way it would in	a reg-
       ular  link.  In	incremental  links, the	linker does not	process	shared
       libraries and their symbol tables at all	and  does  not	report	shared
       library	unsatisfied  symbols.  The detection of	unsatisfied symbols is
       left to the The dynamic loader. If any of the shared libraries  on  the
       command line was	modified, the linker reverts to	an initial incremental
       link.

       Performance of the incremental linker may suffer	greatly	if you	change
       a high percentage of object files.

       The incremental linker may not link small programs much faster, and the
       relative	increase in size of the	executable is greater  than  that  for
       larger programs.

       Do  not	use the	incremental linker to create final production modules.
       Because it reserves additional padding space, modules  created  by  the
       incremental  linker are considerably larger than	those created in regu-
       lar links.

EXTERNAL INFLUENCES
   Environment Variables
       Arguments can be	passed to the linker through the
	      environment variable as well as on the command line.  The	linker
	      gets  the	 value of and places its contents before any arguments
	      on the command line.

       Specifies default directories
	      to search	for library files. See the option.

       Specifies, at runtime,  directories
	      to search	for library files. See the option and the  option  for
	      the for more information.

       The following internationalization variables affect the execution of

       Determines the locale category for native language, local customs and
	      coded  character	set  in	 the  absence of and other environment
	      variables.  If is	not specified or is set	to the empty string, a
	      default of (see lang(5)) is used instead of

       Determines the values for all locale categories and has precedence over
	      and other	environment variables.

       Determines the locale that should be used to affect the format
	      and contents of diagnostic messages written to standard error.

       Determines the locale category for numeric formatting.

       Determines the locale category for character handling functions.

       Determines the location of message catalogs for the processing
	      of

       If  any	internationalization  variable	contains  an  invalid setting,
       behaves as if all internationalization variables	are set	to  See	 envi-
       ron(5).

       In addition, the	following environment variable affects

       Specifies a directory
	      for temporary files (see tmpnam(3S)).

       Specifies the pathname of the browser to	display	the
	      when you use the option.

DIAGNOSTICS
       returns zero when the link is successful.  A non-zero return code indi-
       cates that an error occurred.

EXAMPLES
       Link part of a C	program	for later processing by	(Note the  suffix  for
       the  output  object  file; this is an HP-UX convention for indicating a
       linkable	object file):

       Link a shared bound program in standard mode.  Note that	is not	speci-
       fied because for	shared links, it is no longer necessary.

       Link  a	simple	Fortran	 program  to use with a	symbolic debugger (see
       wdb(1)).	 Because the option is not specified on	the command line,  the
       output file name	is

       Create a	shared library:

       Create  a shared	library	with an	internal name, and this	shared library
       allows dynamic library searching:

		shared library list:
		  libfoo1.so

       If you do not use the shared library does not have  an  internal	 name.
       The  linker  does not check whether is a	symbolic link.	It records the
       library name that it looks at, if it does not have the internal name.

		shared library list:
		  libfoo1.sl

       Add $ORIGIN before the shared library name in the shared	library	list.

		shared library list:
		  $ORIGIN/libc.so

WARNINGS
       recognizes several names	as having special  meanings.   The  symbol  is
       reserved	 by the	linker to refer	to the first address beyond the	end of
       the program's address space.  Similarly,	the symbol refers to the first
       address beyond the initialized data, and	the symbol refers to the first
       address beyond the program text.	 The symbols and are also  defined  by
       the  linker, but	only if	the program contains a reference to these sym-
       bols and	does not define	them (see end(3C) for details).

       The linker treats a user	definition of any of the symbols  listed  here
       as an error.

       Through	its  options,  the linker gives	users great flexibility.  How-
       ever, those who invoke the  linker  directly  must  assume  some	 added
       responsibilities.

       There  is  no guarantee that the	linker will pick up files from archive
       libraries and include them in the final program in  the	same  relative
       order that they occur within the	library.

       The  linker  emits  warnings  where  ever  it detects any compatibility
       issues.	Among other things, these issues include  architectural	 ones,
       as  well	 as  functionality  that  may change over time.	 Some of these
       include:

	      o	     Checking of unsatisfied  symbols  by  the	linker,	 which
		     sometimes	skips  certain	object	files from an archived
		     library.  This warning is only given  if  the  option  is
		     also provided.

       As  noted  in the Options section, this release of the linker no	longer
       supports	certain	options.

       The linker accepts the following	options	and issues a warning message.
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o

       The following  options  are  supported  for  compatibility.   They  are
       accepted	and ignored:
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o
	      o

       The  behavior of	normal executables does	not match the behavior of exe-
       cutables	built with For any setuid or  setgid  programs,	 disables  any
       dynamic	library	 searching  through  environment  variables,  and If a
       library only exists in the directory specified in (or you get the  run-
       time  error  "library  not  found" if the program is a setuid or	setgid
       program (that is, uid not equal to euid or gid not equal	to  egid)  and
       it depends on that library.  uses the dynamic path lookup (with only if
       the following conditions	are satisfied: That is,	if the uid or gid does
       not match its effective counterpart, searches only the recorded library
       path.  As a result, dld does not	check the  which  causes  the  runtime
       error "library not found".

AUTHOR
       was developed by	AT&T, the University of	California, Berkeley, and HP.

FILES
       32-bit system archive and shared	libraries

       64-bit system archive and shared	libraries

       output file

       32-bit dynamic loader

       64-bit dynamic loader

       32-bit run-time startup file

       64-bit run-time startup file

       32-bit millicode	library	automatically searched by

       64-bit millicode	library	automatically searched by

       64-bit millicode	library	automatically searched by ld for embedded sys-
       tems

       message catalog

       temporary files

       file containing profile data generated by running an
					       instrumented executable

       program for creating the	procedure link order from
					       a profile database file created
					       by  an instrumented executable;
					       forked by the option

       static instrumentor to instrument an executable or  a  shared  library.
       It
					       is   invoked  if	 you  use  the
					       option.

SEE ALSO
   Profiling and Debugging Tools:
       adb(1)		 absolute debugger
       gprof(1)		 display call graph profile data
       prof(1)		 display profile data
       wdb(1)		 C, C++, Fortran symbolic debugger

   System Tools:
       aCC(1)		 invoke	the HP-UX aC++ compiler
       ar(1)		 create	archived libraries
       cc(1)		 invoke	the HP-UX C compiler
       chatr(1)		 change	program's internal attributes
       elfdump(1)	 dump information contained in an object file
       exec(2)		 execute a file
       f90(1)		 invoke	the HP-UX Fortran 90 compiler
       fastbind(1)	 invoke	the fastbind tool
       lorder(1)	 find ordering relation	for an object library
       nm(1)		 print name list of object file
       size(1)		 print section sizes of	object files
       strip(1)		 strip symbol and  line	 number	 information  from  an
			 object	file

   Miscellaneous:
       a.out(4)		 assembler, compiler, and linker output
       ar(4)		 archive format
       crt0(3)		 execution startup routine
       dld.so(5)	 dynamic loader
       end(3C)		 symbol	of the last locations in program
       uld.so(5)	 microloader

   Texts and Tutorials:
       (Use the		 option)
       (See		 manuals(5) for	ordering information)

STANDARDS CONFORMANCE
									 ld(1)

NAME | SYNOPSIS | DESCRIPTION | EXTERNAL INFLUENCES | DIAGNOSTICS | EXAMPLES | WARNINGS | AUTHOR | FILES | SEE ALSO | STANDARDS CONFORMANCE

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

home | help