ld man page on NeXTSTEP

Man page or keyword search:  
man Server   1419 pages
apropos Keyword Search (all sections)
Output format
NeXTSTEP logo
[printable version]


LD(1)									 LD(1)

NAME
       ld - Mach object file link editor

SYNOPSIS
       ld [ option ...	] [ file ...  ]

DESCRIPTION
       The  ld command combines several Mach-O (Mach object) files into one by
       combining like sections in like segments from  all  the	object	files,
       resolving   external  references,  and  searching  libraries.   In  the
       simplest case several object files are given,  and  ld  combines	 them,
       producing  an  object  file  which can either be executed or become the
       input for a further ld run.  (In the latter case, the -r option must be
       given  to  preserve the relocation information.)	 Unless an output file
       is specified, ld produces a  file  named	 a.out.	  This	file  is  made
       executable only if no errors occurred during the link editing and there
       are no undefined symbols.

FAT FILE SUPPORT
       The link editor accepts ``fat''	(multiple-architecture)	 input	files,
       but  always  creates  a ``thin'' (single-architecture), standard Mach-O
       output file.  The architecture is specified using the -arch   arch_type
       option.	 If  this  option is not used, ld(1) attempts to determine the
       output architecture by examining the first object file  encountered  on
       the  command  line.   If	 it  is	 a  ``thin''  file,  its  architecture
       determines that of the output file.  If	the  first  input  file	 is  a
       ``fat'' file, the ``best'' architecture for the host is used.  (See the
       explanation of the -arch option, below.)

       The compiler driver cc(1) handles creating fat executables  by  calling
       ld(1)  multiple	times  and using lipo(1) to create a ``fat'' file from
       the results of the ld(1) executions.

OUTPUT FILE LAYOUT
       The object files are loaded in the order in which they are specified on
       the command line.  The segments and the sections in those segments will
       appear in the output file in the order  they  are  encountered  in  the
       object  files  being  linked.  All zero fill sections will appear after
       all non-zero fill sections in their segments.

       Sections created from files with the -sectcreate option will appear  in
       the  output  file  last.	 Section names for sections created from files
       are not allowed to overlap with a section name in the same segment as a
       section coming from an object file.  Sections created from files may be
       in a segment which has sections from object files and  if  so  will  be
       loaded at the end of the non-zero fill sections for that segment.

       If  the option -seglinkedit is specified, the segment it creates is the
       last segment in the output file.

       The address of each segment can be specified with -segaddr, which takes
       the  segment's  name  as an argument.  The address of the first segment
       can alternatively be specified using -seg1addr, in which case a segment
       name  is	 not used.  Segments that do not have a specified address will
       be assigned addresses in the order in which they appear in  the	output
       file.  A segment's address will be assigned based on the ending address
       of the previous segment.	 If the address of the first segment  has  not
       been specified by name, its assigned address will be the specified (via
       -seg1addr) or default first segment address.  If neither flag  is  used
       to specify the first segment's address, its default address is zero for
       all formats except the demand-paged executable format (MH_EXECUTE),  in
       which  case  the	 default  first	 address  is  the value of the segment
       alignment.

       For demand-paged executable format (MH_EXECUTE) output files,  if  none
       of the segments' addresses covers address zero through the value of the
       segment alignment, a segment with no access protection will be  created
       to  cover  those	 addresses.   This  segment,  named ``__PAGEZERO'', is
       created so that any attempt to dereference a NULL pointer will cause  a
       memory exception.

       The  entry  point  of  the  output  file	 is the beginning of the first
       section in the first segment (unless the -e option is specified).

STATIC ARCHIVE LIBRARIES
       ld supports two	types  of  libraries:  static  archive	libraries  and
       dynamic	shared	libraries. Searching for undefined symbols is peformed
       differently for dynamic shared libraries than it is for static  archive
       libraries.  The	searching  of  dynamic	shared	libraries is described
       later.

       When a static archive library is specified as an argument to ld, it  is
       searched	 exactly  once, at the point it is encountered in the argument
       list.  Only those members defining an unresolved external reference, as
       defined	by  the static archive libary's table of contents, are loaded.
       To produce the table of contents, all static archive libraries must  be
       processed by ranlib(1).

       Generally, a static archive library does not have multiple members that
       define the same symbol.	For these types of libraries, the order of the
       members	is  not	 important, so the table of contents can be sorted for
       faster link editing using the -s option to ranlib(1).  The first member
       of  the	static archive library is named ``__.SYMDEF SORTED'', which is
       understood to be a sorted table of contents.

       If the static archive library does have multiple	 members  that	define
       the same symbol, the table of contents that ranlib(1) produces can't be
       sorted.	Instead, it follows the order in which the members  appear  in
       the  static  archive  library.	The  link editor searches the table of
       contents iteratively, loading members until no further  references  are
       satisfied.   In	the  unsorted  case,  the  first  member of the static
       archive library is named ``__.SYMDEF'', which is	 understood  to	 be  a
       table of contents in the order of the archive members.

       Static  archive	library	 members can also be loaded in response to the
       -ObjC and -all_load flags. See their descriptions below.

DYNAMIC SHARED LIBRARIES
       When a dynamic shared library or an object file that was linked against
       a  dynamic  shared  library  is	specified  as  an argument to ld, that
       library is placed in the dynamic shared library search list. The	 order
       of  the	search	list  is  always  the  same  order  the libraries were
       encountered on the command line. All dynamic libraries  libraries  that
       the  dynamic  libraries	are dependent upon are added to the end of the
       search list.

       Once the search list is constructed, the static link editor checks  for
       undefined  symbols by simulating the way the dynamic linker will search
       for undefined symbols at runtime. For each undefined symbol, the static
       link  editor  searches each library in the search list until it finds a
       module that defines the symbol.	With each undefined symbol, the search
       starts  with the first library in the list.  This is different than for
       static archive libraries, where each library is searched	 exactly  once
       for all undefined symbols.

       The  static  link  editor  simulates  dynamic  linking  as  if  all the
       undefined symbols are to be bound at program launch time.  The  dynamic
       linker  actually binds undefined symbols as they are encountered during
       execution instead of at program launch. However, the static link editor
       always  produces the same linking as the dynamic linker as long as none
       of the dynamic shared  libraries	 define	 the  same  symbol.  Different
       linking	can  occur  only  when	there is more than one definition of a
       symbol and the library modules that contain the	definitions  for  that
       symbol  do  not define and reference exactly the same symbols.  In this
       case, even  different  executions  of  the  same	 program  can  produce
       different  linking because the dynamic linker binds undefined functions
       as they are called, and this  affects  the  order  in  which  undefined
       symbols	are  bound.  Because it can produce different dynamic linking,
       using dynamic shared libraries that define the same symbols in the same
       program is strongly discouraged.

       If  a  static archive library appears after a dynamic shared library on
       the command line, the static library is placed in the  dynamic  library
       search  list and is searched as a dynamic library.  In this way, when a
       dynamic library has undefined symbols, it will  cause  the  appropriate
       members	of  the	 static	 libraries  to	be  loaded  into  the  output.
       Searching static libraries as dynamic libraries can cause  problems  if
       the  dynamic library later changes to reference symbols from the static
       library that it did not previously reference. In	 this  case  when  the
       program runs, the dynamic linker will report these symbols as undefined
       because the members for these symbols were not loaded into the output.

USING THE DYNAMIC LINK EDITOR AND DYNAMIC SHARED LIBRARIES
       The option -dynamic must be specified in order to  use  dynamic	shared
       libraries  (and	any of the features used to implement them) and/or the
       dynamic link editor.  To make sure that the output  is  not  using  any
       features	 that  would require the dynamic link editor, the flag -static
       can be specified.  Only one of these flags can be specified.

LINK EDITOR DEFINED SYMBOLS
       There is a group of link editor defined	symbols	 for  the  MH_EXECUTE,
       MH_DYLIB	 and  MH_PRELOAD  file	types  (see  the  header  file	<mach-
       o/ldsyms.h>).  Link editor symbols are reserved; it is an error	if  an
       input  object  file  defines  such  a  symbol.	Only those link editor
       symbols that are referenced by the object file  appear  in  the	output
       file's symbol table.

       The     link	editor	   defined     symbol	 `__mh_execute_header'
       (`_mh_execute_header' in C) is reserved when the output file format  is
       MH_EXECUTE.   This symbol is the address of the Mach header in a Mach-O
       executable (a file of type MH_EXECUTE).	It  does  not  appear  in  any
       other  Mach-O  file  type.   It can be used to get to the addresses and
       sizes of all the segments and sections in the executable.  This can  be
       done by parsing the headers and load commands (see Mach-O(5)).

       The  link editor defined symbol `__mh_dylib_header' (`_mh_dylib_header'
       in C) is reserved when the output file format is MH_DYLIB.  This symbol
       is the address of the Mach header in a Mach-O dynamic shared library (a
       file of type MH_DYLIB) and is a private external symbol.	 It  does  not
       appear  in  any	other  Mach-O file type.  It can be used to get to the
       addresses and sizes of all the  segments	 and  sections	in  a  dynamic
       shared	library.    The	  addresses,  however,	must  have  the	 value
       _dyld_get_image_vmaddr_slide(3) added to them.

       The MH_PRELOAD file type	 has  link  editor  defined  symbols  for  the
       beginning  and ending of each segment, and for the beginning and ending
       of each section within a segment.  These names are provided for use  in
       a  Mach-O  preloaded file, since it does not have its headers loaded as
       part of the first segment.  The names of the symbols  for  a  segment's
       beginning  and  end have the form: __SEGNAME__begin and __SEGNAME__end,
       where __SEGNAME is the name of the segment.  Similarly, the symbols for
       a    section    have    the    form:   __SEGNAME__sectname__begin   and
       __SEGNAME__sectname__end, where __sectname is the name of  the  section
       in  the	segment	 __SEGNAME.   These  symbols'  types  are those of the
       section that the names refer to.	 (A symbol that refers to the end of a
       section	actually  has, as its value, the beginning address of the next
       section, but the symbol's type is still that of the  section  mentioned
       in the symbol's name.)

OPTIONS
       Ld  understands	several	 options.  Filenames and options that refer to
       libraries (such as -l and -framework), as well as options  that	create
       symbols	(such  as  -u and -i), are position-dependent: They define the
       load order and affect what gets loaded from libraries.  Some ld options
       overlap with compiler options.  If the compiler driver cc(1) is used to
       invoke ld , it maybe necessary to pass the ld(1) options to cc(1) using
       -Wl,-option,argument1,argument2.

       The most common option is:

       -o name
	      The output file is named name, instead of a.out.

       The following flags are related to architectures:

       -arch arch_type
	      Specifies	 the  architecture,  arch_type,	 for  the output file.
	      ``Fat''  input  files  that  do  not  contain   this   specified
	      architecture  are	 ignored.   Only  one  -arch  arch_type can be
	      specified.  See arch(3) for the currently known arch_types.  If
	      arch_type	 specifies a certain implementation of an architecture
	      (such as -arch m68040 or -arch i486 ), the resulting object file
	      has  that	 specific CPU subtype, and it is an error if any input
	      file has a CPU subtype that will not combine to the CPU  subtype
	      for  arch_type.

	      The  default output file architecture is determined by the first
	      object file to be linked.	 If it is a ``thin'' (standard Mach-O)
	      file, or a ``fat'' file that contains only one architecture, the
	      output file will have the same architecture.  Otherwise,	if  it
	      is  a ``fat'' file containing an architecture that would execute
	      on the host, then the ``best'' architecture is used, as  defined
	      by  what	the  kernel exec(2) would select.  Otherwise, it is an
	      error, and a -arch arch_type must be specified.

       -arch_multiple
	      This flag is used by the cc(1) driver program  when  it  is  run
	      with multiple -arch arch_type flags.  It instructs programs like
	      ld(1) to precede any displayed message with a line  stating  the
	      program  name,  in  this case ld, and the architecture (from the
	      -arch   arch_type	  flag).    This   helps   distinguish	 which
	      architecture the error messages refer to.

       -force_cpusubtype_ALL
	      The  -force_cpusubtype_ALL flag causes the CPU subtype to remain
	      the ALL CPU subtype and not to be	 combined  or  changed.	  This
	      flag has precedence over any -arch arch_type flag for a specific
	      implementation.

       The following flags are related to using the dynamic link editor and/or
       dynamic	shared	libraries  (and	 any of the features used to implement
       them):

       -dynamic
	      Allows use of the features associated with dynamic link  editor.
	      The default is -dynamic.

       -static
	      Causes  those features associated with dynamic link editor to be
	      treated as an error. (The description for the options that  will
	      cause  an	 error if you use them in conjunction with -static are
	      marked with the statement "when -dynamic
	       is used").

       -read_only_relocs treatment
	      Specifies how relocation entries in read-only sections are to be
	      treated  when  -dynamic  is  used.   To  get  the	 best possible
	      sharing, the read-only sections should not have  any  relocation
	      entries.	 If  they  do,	the  dynamic  linker will write on the
	      section.	Having relocation entries appear in read-only sections
	      is  normally avoided by compiling with the option -dynamic.  But
	      in  such	cases  non-converted  assembly	code  or  objects  not
	      compiled	with  -dynamic relocation entries will appear in read-
	      only  sections.	The  treatment	can  be:  error,  warning,  or
	      suppress.	  Which	 cause	the treatment of relocation entries in
	      read-only sections as either, errors,  warnings,	or  suppressed
	      messages.	 The default is to treat these as warnings.

       -prebind
	      Have  the	 static	 linker,  ld(1),  prebind  an  executable's or
	      dynamic shared library's undefined symbols to the	 addresses  of
	      the   dynamic   libraries	  it   is  being  linked  with.	  This
	      optimization can only be done if the libraries don't overlap and
	      no  symbols  are	overridden.  When the resulting program is run
	      and the same libraries are used to run the program as  when  the
	      program  was  linked,  the  dynamic  linker can use the prebound
	      addresses.  If not, the dynamic linker undoes the prebinding and
	      binds normally.

       The following flags are related to libraries:

       -lx    This  option  is	an abbreviation for the library name `libx.a',
	      where x is a string.  If -dynamic is specified the  abbreviation
	      for  the	library	 name is first search as `libx.dylib' and then
	      `libx.a' is searched for.	 ld searches for  libraries  first  in
	      any  directories specified with -L options, then in the standard
	      directories /lib, /usr/lib, and /usr/local/lib.	A  library  is
	      searched	when  its name is encountered, so the placement of the
	      -l flag is significant.  If string x is of the  form  x.o,  then
	      that  file  is  searched	for  in	 the  same places, but without
	      prepending `lib' or appending `.a' or `.dylib' to the filename.

       -Ldir  Add dir to the list  of  directories  in	which  to  search  for
	      libraries.   Directories	specified  with -L are searched before
	      the standard directories.

       -Z     Do not  search  the  standard  directories  when	searching  for
	      libraries.

       -framework name[,suffix]
	      Specifies	 a  framework  to link against. Frameworks are dynamic
	      shared libraries, but they are stored  in	 different  locations,
	      and therefore must be searched for differently. When this option
	      is specified, ld searches	 for  framework	 `name.framework/name'
	      first  in	 any directories specified with the -F option, then in
	      the standard framework directories /LocalLibrary/Frameworks, and
	      /NextLibrary/Frameworks.	The placement of the -framework option
	      is significant, as it determines when and how the	 framework  is
	      searched.	  If the optional suffix is specified the framework is
	      first searched for the name with the suffix and then without.

       -Fdir  Add dir to the list  of  directories  in	which  to  search  for
	      frameworks.   Directories	 specified with -F are searched before
	      the standard framework directories.

       -ObjC  Loads all members of static archive  libraries  that  define  an
	      Objective	 C  class or a category. This option does not apply to
	      dynamic shared libraries.

       -all_load
	      Loads all members of static archive libraries.  This option does
	      not apply to dynamic shared libraries.

       -dylib_file install_name:file_name
	      Specifies	 that  a  dynamic  shared  library  is	in a different
	      location than its standard location. Use this  option  when  you
	      link  with a library that is dependent on a dynamic library, and
	      the dynamic library is in a  location  other  than  its  default
	      location.	  install_name	specifies  the	path where the library
	      normally resides.	 file_name specifies the path of  the  library
	      you  want to use instead.	 For example, if you link to a library
	      that depends upon the dynamic library libsys and you have libsys
	      installed	 in  a nondefault location, you would use this option:
	      -dylib_file /lib/libsys_s.A.dylib:/me/lib/libsys_s.A.dylib.

       The following options specify the output file format (the file type):

       -execute
	      Produce a	 Mach-O	 demand-paged  executable  format  file.   The
	      headers  are  placed  in the first segment, and all segments are
	      padded to the segment  alignment.	  This	has  a	file  type  of
	      MH_EXECUTE.   This  is  the  default.   If no segment address is
	      specified at address zero, a  segment  with  no  protection  (no
	      read,  write, or execute permission) is created at address zero.
	      This segment, whose size is that of the  segment	alignment,  is
	      named  ``__PAGEZERO''.   This option was previously named -Mach,
	      which will continue to be recognized.

       -object
	      Produce a Mach-O file in the relocatable object file format that
	      is  intended  for	 execution.   This  differs  from using the -r
	      option in	 that  it  defines  common  symbols,  does  not	 allow
	      undefined	 symbols  and  does  not  preserve relocation entries.
	      This has a file type of MH_OBJECT.  In this format all  sections
	      are  placed  in  one unnamed segment with all protections (read,
	      write, execute) allowed on that segment.	This is	 intended  for
	      extremely	 small	programs  that would otherwise be large due to
	      segment  padding.	  In  this  format,  and  all	non-MH_EXECUTE
	      formats,	the link editor defined symbol ``__mh_execute_header''
	      is not defined since the headers are not part  of	 the  segment.
	      This format file can't be use with the dynamic linker.

       -preload
	      Produce  a Mach-O preloaded executable format file.  The headers
	      are not placed in any segment.  All sections are placed in their
	      proper  segments	and  they are padded to the segment alignment.
	      This has a file type of MH_PRELOAD.  This option was  previously
	      -p, which will continue to be recognized.

       -dylib Produce  a  Mach-O  dynamicly linked shared library format file.
	      The headers are placed in the first segment.  All	 sections  are
	      placed  in  their	 proper	 segments  and	they are padded to the
	      segment alignment.  This has a  file  type  of  MH_DYLIB.	  This
	      option  is  used	by  libtool(1)	when  its  -dynamic  option is
	      specified.

       -bundle
	      Produce a Mach-O bundle format file.  The headers are placed  in
	      the  first  segment.   All  sections  are placed in their proper
	      segments and they are padded to the segment alignment.  This has
	      a file type of MH_BUNDLE.

       -dylinker
	      Produces	a Mach-O dynamic link editor format file.  The headers
	      are placed in the first segment.	All  sections  are  placed  in
	      their  proper  segments,	and  they  are	padded	to the segment
	      alignment.  This has a file type of MH_DYLINKER.

       -fvmlib
	      Produce a Mach-O fixed  VM  shared  library  format  file.   The
	      headers are placed in the first segment but the first section in
	      that segment will	 be  placed  on	 the  next  segment  alignment
	      boundary	in  that  segment.   All  sections are placed in their
	      proper segments and they are padded to  the  segment  alignment.
	      This has a file type of MH_FVMLIB.

       The following flags affect the contents of the output file:

       -r     Save  the	 relocation  information in the output file so that it
	      can be the subject of another ld run.  The resulting  file  type
	      is  a  Mach-O  relocatable  file	(MH_OBJECT)  if	 not otherwise
	      specified.  This flag also prevents final definitions from being
	      given  to	 common symbols, and suppresses the `undefined symbol'
	      diagnostics.

       -d     Force definition of common storage even  if  the	-r  option  is
	      present.	This option also forces link editor defined symbols to
	      be defined.  This option is assumed when there is a dynamic link
	      editor load command in the input and -r is not specified.

       The following flags support segment specifications:

       -segalign value
	      Specifies	 the segment alignment.	 value is a hexadecimal number
	      that must be an integral power of 2.  The default is the	target
	      pagesize (2000 hex currently).

       -seg1addr addr
	      Specifies	 the  starting	address	 of  the  first segment in the
	      output file.  addr  is  a	 hexadecimal  number  and  must	 be  a
	      multiple of the segment alignment.

       -segaddr name addr
	      Specifies	 the  starting address of the segment named name to be
	      addr.  The address must  be  a  hexadecimal  number  that	 is  a
	      multiple of the segment alignment.

       -segprot name max init
	      Specifies	 the  maximum and initial virtual memory protection of
	      the named segment, name, to be max and init  respectfully.   The
	      values  for  max	and init are any combination of the characters
	      `r' (for read), `w' (for write), `x' (for execute) and  '-'  (no
	      access).	 The  default  is `rwx' for the maximum protection for
	      all segments.  The default for the initial  protection  for  all
	      segments	is  `rw'  unless  the segment contains a section which
	      contains some machine insructions, in which case the default for
	      the  initial  protection	is `rwx'.  The default for the initial
	      protection for the ``__TEXT'' segment is `rx' (not writable).

       -seglinkedit
	      Create the link edit segment, named ``__LINKEDIT'' (this is  the
	      default).	  This	segment contains all the link edit information
	      (relocation information, symbol table, string  table,  etc.)  in
	      the  object file.	 If the segment protection for this segment is
	      not specified, the initial protection is not writable.  This can
	      only be specified when the output file type is not MH_OBJECT and
	      MH_PRELOAD output file types.  To get at the  contents  of  this
	      section,	the  Mach header and load commands must be parsed from
	      the link editor defined symbols like `__mh_execute_header'  (see
	      Mach-O(5)).

       -noseglinkedit
	      Do not create the link edit segment (see -seglinkedit above).

       -pagezero_size value
	      Specifies	 the  segment  size of __PAGEZERO to be of size value,
	      where value is a	hexadecimal  number  rounded  to  the  segment
	      alignment.   The default is the target pagesize (currently, 2000
	      hexadecimal).

       The following flags support section specifications:

       -sectcreate segname sectname file
	      The section sectname in the segment segname is created from  the
	      contents	of file.  The combination of segname and sectname must
	      be unique; there cannot already be a section  (segname,sectname)
	      in  any  input  object  file.  This option was previously called
	      -segcreate, which will continue to be recognized.

       -sectalign segname sectname value
	      The section named sectname in the segment segname will have  its
	      alignment set to value, where value is a hexadecimal number that
	      must be an integral power of 2.  This can be  used  to  set  the
	      alignment	 of  a section created from a file, or to increase the
	      alignment of a section from  an  object  file,  or  to  set  the
	      maximum alignment of the (__DATA,__common) section, where common
	      symbols are defined by the link editor.  Setting	the  alignment
	      of  a  literal  section  causes  the  individual	literals to be
	      aligned on that boundary.	  If  the  section  alignment  is  not
	      specified	 by  a	section	 header	 in  an	 object file or on the
	      command line,  it	 defaults  to  10  (hex),  indicating  16-byte
	      alignment.

       -sectorder segname sectname orderfile
	      The  section  sectname  in the segment segname of the input file
	      will be broken up into blocks associated	with  symbols  in  the
	      section.	 The  output  section  will be created by ordering the
	      blocks as specified by the lines in the orderfile.  These blocks
	      are  aligned  to	the  output  file's section alignment for this
	      section.	Any section can be ordered in the output  file	except
	      symbol pointer and symbol stub sections.

	      For non-literal sections, each line of the orderfile contains an
	      object name and a symbol	name,  separated  by  a	 single	 colon
	      (':').   If  the object file is in an archive, the archive name,
	      followed by a single colon, must precede the object  file	 name.
	      The  object  file	 names and archive names should be exactly the
	      names as seen by the link editor, but if not,  the  link	editor
	      attempts to match up the names the best it can.  For non-literal
	      sections, the easiest way to generate an order file is with  the
	      ``-jonls +segname sectname'' options to nm(1).

	      The  format of the orderfile for literal sections is specific to
	      each type of literal section.  For C  string  literal  sections,
	      each line of the order file contains one literal C string, which
	      may include ANSI C  escape  sequences.   For  four-byte  literal
	      sections,	 the order file format is one 32-bit hex number with a
	      leading 0x per line, with the rest of  the  line	treated	 as  a
	      comment.	 For  eight-byte  literal sections, the order file has
	      two 32-bit hex numbers per line; each number has a  leading  0x,
	      the  two	numbers	 are separated by white space, and the rest of
	      the line is treated as a comment.	 For literal pointer sections,
	      the lines in the order file represent pointers, one per line.  A
	      literal pointer is represented by the name of the	 segment  that
	      contains	the  literal being pointed to, followed by the section
	      name, followed by the literal. These three strings are separated
	      by  colons  with	no  extra  white  space.   For all the literal
	      sections, each line in the the order file is simply entered into
	      the  literal  section  and will appear in the output file in the
	      same order as in the order file.	 There	is  no	check  to  see
	      whether  the  literal  is	 present  in  the loaded objects.  For
	      literal sections, the easiest way to generate an order  file  is
	      with the ``-X -v -s segname sectname'' options to otool(1).

       -sectorder_detail
	      When  using  the	-sectorder  option,   any pairs of object file
	      names and symbol names that are found in the loaded objects, but
	      not  specified  in  the orderfile, are placed last in the output
	      file's section.	These pairs are ordered by object file (as the
	      filenames	 appear	 on  the  command  line),  with	 the different
	      symbols from a given object file	being  ordered	by  increasing
	      symbol address (that is, the order in which the symbols occurred
	      in the object file, not their order in the  symbol  table).   By
	      default,	the  link  editor displays a summary that simply shows
	      the number of symbol names found in the loaded objects  but  not
	      in  the  orderfile, as well as the number of symbol names listed
	      in the orderfile but not found  in  the  loaded  objects.	  (The
	      summary is omitted if both values are zero.)  To instead produce
	      a detailed list of  these	 symbols,  use	the  -sectorder_detail
	      flag.   If  an  object  file-symbol name pair is listed multiple
	      times, a warning is generated, and the first occurrence is used.

       -sectobjectsymbols segname sectname
	      This causes the link editor to generate  local  symbols  in  the
	      section  sectname in the segment segname.	 Each object file that
	      has one of these sections will have a local symbol created whose
	      name  is	that  of  the  object  file,  or  of the member of the
	      archive.	The symbol's value will be  the	 first	address	 where
	      that  object file's section was loaded.  The symbol has the type
	      N_SECT and its section number is the the same  as	 that  of  the
	      section (segname,sectname) in the output file.  This symbol will
	      placed in the symbol table just before all other	local  symbols
	      for  the	object file.  This feature is typically used where the
	      section is (__TEXT,__text), in order to help the debugger	 debug
	      object files produced by old versions of the compiler or by non-
	      NeXT compilers.

       The following flags are related to symbols.  These flags' arguments are
       external	 symbols  whose names have `_' prepended to the C, FORTRAN, or
       Pascal variable name.

       -ysym  Display each file in which sym appears, its  type,  and  whether
	      the file defines or references it.  Any multiply defined symbols
	      are automatically traced.	 Like most of the other symbol-related
	      flags,  -y  takes	 only  one argument; the flag may be specified
	      more than once in the  command  line  to	trace  more  than  one
	      symbol.

       -Y number
	      For  the	first  number undefined symbols, displays each file in
	      which the symbol appears, its type and whether the file  defines
	      or  references it (that is, the same style of output produced by
	      the -y option). To  keep	the  output  manageable,  this	option
	      displays at most number references.

       -keep_private_externs
	      Don't  turn  private  external  symbols into static symbols, but
	      rather leave them as private external in	the  resulting	output
	      file.

       -m     Don't  treat  multiply defined symbols as a hard error; instead,
	      simply print a warning.  The  first  such	 symbol	 is  used  for
	      linking;	its  value is used for the symbol in the symbol table.
	      The other symbols by the same name may be used in the  resulting
	      output  file through local references.  This can still produce a
	      resulting output file that is in	error.	 This  flag's  use  is
	      strongly discouraged!

       -whyload
	      Indicate	why  each  member  of  a  library is loaded.  In other
	      words,  indicate	which  currently  undefined  symbol  is	 being
	      resolved, causing that member to be loaded.  This in combination
	      with the above -ysym flag can help determine exactly why a  link
	      edit is failing due to multiply defined symbols.

       -u sym Enter  the  argument  sym	 into the symbol table as an undefined
	      symbol.  This is useful for loading wholly from a library, since
	      initially	 the symbol table is empty and an unresolved reference
	      is needed to force the loading of the first object file.

       -e sym The argument sym is taken to be the symbol  name	of  the	 entry
	      point of the resulting file.  By default, the entry point is the
	      address of the first section in the first segment.

       -idefinition:indirect
	      Create an indirect symbol for the symbol name  definition	 which
	      is  defined to be the same as the symbol name indirect (which is
	      taken to be undefined).  When a definition of the	 symbol	 named
	      indirect	is  linked, both symbols will take on the defined type
	      and value.

	      This option overlaps with a compiler option.   If	 you  use  the
	      compiler	driver	cc(1) to invoke ld, invoke this option in this
	      way: -Wl,-idefinition:indirect.

       -undefined treatment
	      Specifies how undefined symbols are to  be  treated.   treatment
	      can  be: error, warning, or suppress.  Which cause the treatment
	      of undefined symbols as either, errors, warnings, or  suppresses
	      the  checking  of	 undefined  symbols.   The default is to treat
	      undefined symbols as errors.

       -U sym Allow the symbol sym to be undefined, even if the -r flag is not
	      given.  Produce an executable file if the only undefined symbols
	      are those specified with -U.

	      This option overlaps with a compiler option.   If	 you  use  the
	      compiler	driver	cc(1) to invoke ld, invoke this option in this
	      way: -Wl,-U,sym.

       -bind_at_load
	      Causes the output file to be marked such that the dynamic linker
	      will  bind  all  undefined references when the file is loaded or
	      launched.

       The following flags are related to  stripping  link  edit  information.
       This  information  can also be removed by strip(1), which uses the same
       options.	 (The exception is the -s flag below, but this is the same  as
       strip(1)	 with  no  arguments.)	 The  following	 flags	are  listed in
       decreasing level of stripping.

       -s     Completely strip the output; that is, remove  the	 symbol	 table
	      and relocation information.

       -x     Strips the non-global symbols; only saves external symbols.

	      This  option  overlaps  with  a compiler option.	If you use the
	      compiler driver cc(1) to invoke ld, invoke this option  in  this
	      way: -Wl,-x.

       -S     Strip debugging symbols; only save local and global symbols.

       -X     Strip  local  symbols whose names begin with `L'; save all other
	      symbols.	(The compiler  and  assembler  currently  strip	 these
	      internally-generated labels by default, so they generally do not
	      appear in object files seen by the link editor.)

       -b     Strip the base file's symbols from the output file.   (The  base
	      file is given as the argument to the -A option.)

	      This  option  overlaps  with  a compiler option.	If you use the
	      compiler driver cc(1) to invoke ld, invoke this option  in  this
	      way: -Wl,-b.

       The remaining options are infrequently used:

       -w     Suppresses all warning messages.

       -no_arch_warnings
	      Suppresses  warning  messages  about  files  that have the wrong
	      architecture for the -arch flag.

       -arch_errors_fatal
	      Cause the errors having to do with files	that  have  the	 wrong
	      architecture to be fatal and stop the link editor.

       -M     Produce  a load map, listing all the segments and sections.  The
	      list includes  the  address  where  each	input  file's  section
	      appears in the output file, as well as the section's size.

	      This  option  overlaps  with  a compiler option.	If you use the
	      compiler driver cc(1) to invoke ld, invoke this option  in  this
	      way: -Wl,-M.

       -whatsloaded
	      Display  a  single line listing each object file that is loaded.
	      Names of objects in archives have the form libfoo.a(bar.o).

       -filelist listfile[,dirname]
	      Specifies that the  linker  should  link	the  files  listed  in
	      listfile	.   This is an alternative to listing the files on the
	      command line. The file names are listed one per  line  separated
	      only by newlines. (Spaces and tabs are assumed to be part of the
	      file  name.)   If	 the  optional	directory  name,  dirname   is
	      specified, it is prepended to each name in the list file.

       -headerpad value
	      Specifies	 the minimum amount of space ("padding") following the
	      headers for the  MH_EXECUTE  format.   value  is	a  hexadecimal
	      number.	When  a	 segment's  size  is rounded up to the segment
	      alignment, there is extra	 space	left  over,  which  is	placed
	      between  the headers and the sections, rather than at the end of
	      the segment.  The headerpad option specifies the minimum size of
	      this padding, which can be useful if the headers will be altered
	      later.  The default value is the sizeof(struct section)  so  the
	      program  /bin/objcunique	can  always add a section header.  The
	      actual amount of pad will be as large as the amount of the first
	      segment's round-off.  (That is, take the total size of the first
	      segments' headers and non-zerofill sections, round this size  up
	      to  the  segment	alignment,  and use the difference between the
	      rounded and unrounded sizes as the minimum amount of padding.)

       -t     Trace the progress of the link editor; display the name of  each
	      file  that  is loaded as it is processed in the first and second
	      pass of the link editor.

       -A basefile
	      Incremental loading: linking is to be done in a manner that lets
	      the  resulting object be read into an already executing program,
	      the basefile.  basefile is the name of a file whose symbol table
	      will  be taken as a basis on which to define additional symbols.
	      Only newly linked material will be entered into the a.out	 file,
	      but  the	new  symbol table will reflect every symbol defined in
	      the base file and the newly linked files.	 Option(s) to  specify
	      the  addresses  of  the segments are typically needed, since the
	      default addresses	 tend  to  overlap  with  the  basefile.   The
	      default  format  of  the	object file is MH_OBJECT.  Note: It is
	      strongly recommended that this option NOT be used,  because  the
	      dyld package described in dyld(3) is a much easier alternative.

       -dylib_install_name name
	      For dynamic shared library files, specifies the name of the file
	      the library will be installed in for programs that use  it.   If
	      this  is not specified, the name specified in the -o name option
	      will  be	used.	This  option  is  used	 as   the   libtool(1)
	      -install_name name option when its -dynamic option is specified.

       -dylib_compatibility_version number
	      For   dynamic   shared   library	 files,	  this	specifies  the
	      compatibility version number of the library.  When a library  is
	      used  by	a program, the compatibility version is checked and if
	      the program's version is greater that the library's version,  it
	      is  an error.  The format of number is X[.Y[.Z]] where X must be
	      a positive non-zero number less than or equal to 65535,  and  .Y
	      and  .Z  are optional and if present must be a positive non-zero
	      numbers less than or equal to 255.  If the compatibility version
	      number  is not specified, it has a value of 0 and no checking is
	      done when the library is used.   This  option  is	 used  as  the
	      libtool(1)   -compatibility_version   number   option  when  its
	      -dynamic option is set.

       -dylib_current_version number
	      For dynamic shared library files, specifies the current  version
	      number  of  the library.	The current version of the library can
	      be obtained programmatically by the user of the  library	so  it
	      can  determine exactly which version of the library it is using.
	      The format of number is X[.Y[.Z]] where X	 must  be  a  positive
	      non-zero	number	less than or equal to 65535, and .Y and .Z are
	      optional and if present must be a positive non-zero numbers less
	      than  or	equal to 255.  If the version number is not specified,
	      it has a value of 0.  This option	 is  used  as  the  libtool(1)
	      -current_version number option when its -dynamic option is set.

       -dylinker_install_name name
	      For  dynamic  link  editor files, specifies the name of the file
	      the dynamic link editor will be installed in for	programs  that
	      use it.

       Options	available  in  early versions of the Mach-O link editor may no
       longer be supported.

FILES
       /lib/lib*.{a,dylib}		       libraries
       /usr/lib/lib*.{a,dylib}
       /usr/local/lib/lib*.{a,dylib}
       /LocalLibrary/Frameworks/*.framework/*  framework libraries
       /NextLibrary/Frameworks/*.framework/*
       a.out				       output file

SEE ALSO
       as(1), ar(1), cc(1), libtool(1), ranlib(1),  atom(1),  nm(1),  otool(1)
       lipo(1), arch(3), dyld(3), Mach-O(5), strip(1), redo_prebinding(1)

NeXT Software, Inc.		March 28, 1996				 LD(1)
[top]

List of man pages available for NeXTSTEP

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net