ultrix man page for ld

ld(1)							      General Commands Manual							     ld(1)

Name
       ld, uld - RISC link editor and ucode link editor

Syntax
       ld[ options ] [ filename filename ...  ]
       uld[ options ] [ filename filename ...  ]

Description
       The  invokes the RISC link editor, which links RISC extended coff object files.	The archive format understood by is the one created by the
       archiver

       The editor combines several object files into one, performs relocation, resolves external symbols, and supports	symbol	table  information
       for symbolic debugging.	In the simplest case, you specify the names of several object files as arguments to the command.  The command com-
       bines them, producing an object module that you can execute or use as input to a subsequent command.  (In the latter case, you must specify
       the -r option to preserve the relocation entries.)  The command writes its output to a file named By default, this file is executable if no
       errors occurred during the load.

       The command concatenates object files in the order in which you specify them.  The entry point of the output is the beginning of  the  text
       segment (unless you specify the -e option).

       The  command  combines  several	ucode object files and libraries into one ucode object file. The command hides external symbols for better
       optimizations by subsequent compiler passes.  The command uses the symbol tables of coff object files loaded with  ucode  object  files	to
       determine  what	external symbols not to hide. You can specify that the command not hide external symbols by creating a file that describes
       those symbols.

       The link editors and accept object files targeted for either Big Endian or Little Endian byte ordering  with  their  headers  and  symbolic
       tables in any byte ordering.  However and are faster if the headers and symbolic tables have the byte ordering of the machine that they are
       running on.  The default byte ordering of the headers and symbolic tables is the target byte ordering of the output object file.  For  non-
       relocatable object files, the default byte ordering of the headers and symbolic tables cannot be changed.

       If  you	specify  that  you  want to link a library, the and commands search the library exactly once at the point it is encountered in the
       argument list.  The library (archive) symbol table (see is a hash table that and search to resolve external references.	The commands  load
       only those routines that define unresolved external references.	The order of the routines in the library is unimportant.

       By  default,  the and commands search for libraries in the and directories.  In some cases, the target byte ordering of the object files or
       is loading is the opposite of the byte ordering of the machine on which the link editor is executing. When this case occurs, the link  edi-
       tor  changes  the  default  directories	it searches for libraries. If the object file's byte ordering is Big Endian and the machine's byte
       ordering is Little Endian (Digital products), the link editor searches the and directories, by default. Conversely, if  the  object  file's
       byte ordering is Little Endian and the machine's byte ordering is Big Endian, the editor searches the and directories, by default.

       The  following  symbols	are  reserved; do not define them: etext, edata, end, _ftext, _fdata, _fbss, _gp, _procedure_table, _procedure_ta-
       ble_size, and _procedure_string_table.  These loader defined symbols, if referred to, have their values set as described in

Options
       You can use the following options on both the and command lines.  If you specify an option that the  command  does  not	use,  the  command
       ignores that option.

       You  can specify the options described in this section on the command line. To do so, prepend a k to the option. When you prepend a k , the
       command ignores the option and passes it to the link editor. The link editor ignores the prepended k and  processes  the  option  normally.
       Therefore, the -kA option has the same effect as specifying -A .

       -A file	      Link  to allow incremental loading.  The link editor performs the link process so that the resulting object can be read into
		      an already executing program.

		      The file argument is the name of an object file. The link editor defines additional symbols using the symbol table  in  that
		      file. This argument must appear on the command line before any other object file.

		      During an incremental load, the link editor loads only newly linked material into the text and data portions of a.out.  How-
		      ever, the new symbol table reflects every symbol defined before and after the incremental load.

		      You can use the -T option to cause the link editor to assume that the newly linked segment starts at the specified  address,
		      which  must  be  a correct multiple for the resulting object type.  The default resulting object type is an OMAGIC file. The
		      default starting address of the text is the value of the end symbol rounded to SCNROUND as defined in the  include  file	By
		      default, when the newly linked segment is read into an already executing program the initial value of the break must also be
		      rounded.

		      All objects except the argument to the -A option must be compiled with the -G 0 option. Using the -A option sets	-G  0  for
		      linking.

		      For  jump  instructions  to  operate  correctly,	the beginning and ending points of the instruction must be in the same 256
		      megabyte segment. Thus, it is invalid to use the default address of a ZMAGIC file as the	base  file  and  allow	the  newly
		      linked text to start at the value of the end symbol.

		      To  solve  this  problem, use the -D option when you create the base file.  Using this option ensures that the text and data
		      will be in the same 256 megabyte segment.  Alternatively, use the -N option, which places the data section immediately  fol-
		      lowing the text section.

       -B num	      Set the bss segment origin.  The argument num is a hexadecimal address.  You can use this option only if the final object is
		      an OMAGIC file.

       -Bstring       Append string to the library name created for the -lx or -klx options. When searching for a library, the link  editor  first
		      appends  string to the library name. If the link editor cannot find a library of that name, it searches for the library name
		      without string.

       -b	      Do not merge the symbolic information entries for the same file into one entry for that file.  Use this option when the sym-
		      bolic  information from the same file appears differently in any of the objects to be linked.  This situation can occur when
		      object files are compiled, by means of conditional compilation, with an apparently different version of an include file.

       -bestGnum      Calculate the best number to use as an argument to the -G option. Use this option when you are  compiling  and  linking  the
		      files  that  will  produce  the objects you want to link with -G.  Using too large a number with the -G option may cause the
		      global pointer data area to overflow; using too small a number may reduce your program's execution speed.

       -count

       -countall

       -nocount       Count (or do not count) the specified objects as able to be recompiled when calculating the best number to use as  an  argu-
		      ment  to	the  -G  option.  By default, the -bestGnum option assumes you can recompile everything with the -G option. If you
		      cannot recompile certain object files or libraries (because, for example, you have no sources for them), use  these  options
		      to tell the link editor to take this into account in calculating the best number for the -G option.

		      The  -nocount  option  specifies	that object files appearing after it on the command line cannot be recompiled.	The -count
		      option specifies that object files appearing after it on the command line can be recompiled. You can alternate  the  use	of
		      -nocount	and  -count.   The  -countall option specifies that all object files appearing after it on the command line can be
		      recompiled.  This option overrides any -nocount options that appear after it on the command line.

       -D num	      Set the data segment origin.  The argument num is a hexadecimal address.	See Restrictions for information on  valid  values
		      for the hexadecimal address.

       -d	      Force definition of common storage and define loader defined symbols even if -r is present.

       -EB	      Produce the output object file with Big Endian byte ordered headers and symbolic information tables.

       -EL	      Produce the output object file with Little Endian byte ordered headers and symbolic information tables.

       -e epsym       Set the default entry point address for the output file to be that of the symbol epsym.

       -F	      Load the process on demand from the resulting executable file (413 format) rather than preloading it as a ZMAGIC file.  This
		      behavior is the default. (This option is identical to the -z option.)

       -ffill	      Set the fill pattern for ``holes'' within an output section.  The argument fill is a 4-byte hexadecimal constant.

       -Gnum	      Assume the decimal number num specifies the largest size in bytes of a .comm item or literal that is to be allocated in  the
		      small bss section for reference off the global pointer. The default largest size is 8 bytes.

       -g

       -g[123]	      Disable the -jmpopt option. The -g0 option is accepted, but it has no effect.

       -jmpopt

       -nojmpopt      Fill or do not fill the delay slots of jump instructions with the target of the jump and adjust the jump offset to jump past
		      that instruction.  This feature always is disabled for debugging (when the -g1, -g2 or  -g  flag	is  present).	When  this
		      option  is  enabled  it requires that all of the loaded program's text be in memory and could cause the loader to run out of
		      memory.  The default is -nojmpopt.

       -klx	      Search a ucode object library libx.b, where x is a string.  Because the link editor searches the library when it	encounters
		      the library name, the placement of the -kl option is significant.

       -L	      Ignore the libx.a or libx.b default directories when searching for libraries.  This option is useful when you never want the
		      link editor to search the default directories and want it to only search the directories you specify with the -Ldir option.

       -Ldir	      Search dir before searching the default directories libx.a or libx.b This option is effective only if  it  precedes  the	-l
		      option.

       -lx	      Search  a  library libx.a, where x is a string.  Because the link editor searches the library when it encounters the library
		      name, the placement of the -l option is significant.

       -M	      Produce a primitive load map, listing the names of the files that are loaded. This option displays a map	that  resembles  a
		      UNIX 4.3BSD map.	(See also the -m option.)

       -m	      Display  a  map or listing of the input/output sections on standard output. This option displays a map that resembles a UNIX
		      System V map.  (See also the -M option.)

       -N	      Assign the 0407 magic number to the output file, making it an OMAGIC file. In an OMAGIC file, the data  section  immediately
		      follows  the  text  section. The text section can be read or written, but it is not shareable for users executing the OMAGIC
		      file.

       -n	      Assign 0419 magic number to the output file, making it an NMAGIC file. When users execute the NMAGIC file, the text  section
		      of the executable is read-only and shared among all users executing that file.  This option moves the data section up to the
		      first possible page-size byte boundary following the end of the text.

       -o outfile     Produce an output object file by the name outfile.  The name of the default object file is a.out.

       -p file	      Preserve (do not hide) the symbol names listed in file when loading ucode object files.  You must separate the symbol  names
		      in the file with blanks, tabs, or newline characters.

       -r	      Retain  relocation  entries  in  the output file.  Relocation entries must be saved if the output file is to become an input
		      file in a subsequent run.  This option also prevents final definitions from being given to common symbols and suppresses the
		      undefined symbol diagnostics.

       -S	      Set silent mode and suppress nonfatal errors.

       -s	      Strip the symbolic information from the output object file.

       -T num	      Set  the	text segment origin.  The argument num is a hexadecimal address.  See Restrictions for information on valid values
		      for the hexadecimal address.

       -u symname     Enter symname as an undefined symbol in the symbol table.  This option is useful for loading linked material entirely from a
		      library  because	initially  the	symbol table is empty. An unresolved reference is needed to force the loading of the first
		      routine.

       -V	      Display a message giving information about the version of being used.

       -VS num	      Use num as the decimal version stamp to identify the file that is produced.  The version stamp is stored in the optional and
		      symbolic headers.

       -v	      Set verbose mode, which causes the link editor to display the name of each file as it is processed.

       -x	      Do  not  preserve local (nonglobal) symbols in the output symbol table; enter only external and static symbols.  This option
		      saves space in the output file.

       -ysym	      Display the name of each file in which the specified symbol appears, the symbol's data type, and whether the file defines or
		      references the symbol.  You can specify a number of -y options to trace many symbols.

       -z	      Load the process on demand from the resulting executable file (413 format) rather than preloading it as a ZMAGIC file.  This
		      behavior is the default. (This option is identical to the -F option.)

Restrictions
       The text and data segments must not overlap and all addresses must be less than 0x80000000.  The stack starts below  0x80000000	and  grows
       through lower addresses, so leave space for it.

       For ZMAGIC and NMAGIC files, the default text segment address is 0x00400000 and the default data segment address is 0x10000000.	For OMAGIC
       files, the default text segment address is 0x10000000 with the data segment following the text segment.	The default for all types of files
       is that the bss segment follows the data segment.

       If  you use the -B option when you link an OMAGIC file, the origin you specify for the bss segment must follow the data segment. If the bss
       segment does not follow the data segment, the OMAGIC file will not run.

       The segments must be on 4 megabyte boundaries.  Objects linked at addresses other than the default will not run.

Files
       Library file

       Library file

       Library file

       Output file

See Also
       cc(1), as(1), ar(1), end(3)

								       RISC								     ld(1)