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

FreeBSD Manual Pages

  
 
  

home | help
ld(1)									 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