sys/man/1/2l

   1 .TH 2L 1
   2 .SH NAME
   3 0l, 1l, 2l, 5l, 6l, 7l, 8l, kl, ql, vl \- loaders
   4 .SH SYNOPSIS
   5 .B 2l
   6 [
   7 .I option ...
   8 ]
   9 [
  10 .I file ...
  11 ]
  12 .br
  13 etc.
  14 .SH DESCRIPTION
  15 These commands
  16 load the named
  17 .I files
  18 into executable files for the corresponding architectures; see
  19 .IR 2c (1)
  20 for the correspondence between an architecture and the character
  21 .RB ( 1 ,
  22 .RB 2 ,
  23 etc.) that specifies it.
  24 The files should be object files or libraries (archives of object files)
  25 for the appropriate architecture.
  26 Also, a name like
  27 .BI -l ext
  28 represents the library
  29 .BI lib ext .a
  30 in
  31 .BR /$objtype/lib ,
  32 where
  33 .I objtype
  34 is one of
  35 .BR 68000 ,
  36 etc. as listed in
  37 .IR 2c (1).
  38 The libraries must have tables of contents
  39 (see
  40 .IR ar (1)).
  41 .PP
  42 In practice,
  43 .B -l
  44 options are rarely necessary as the header files for
  45 the libraries cause their archives to be included automatically in the load
  46 (see
  47 .IR 2c (1)).
  48 For example, any program that includes header file
  49 .B libc.h
  50 causes the loader
  51 to search the C library
  52 .BR /$objtype/lib/libc.a .
  53 Also, the loader creates an undefined symbol
  54 .B _main
  55 (or
  56 .B _mainp
  57 if profiling is enabled) to force loading of the
  58 startup linkage from the C library.
  59 .PP
  60 The order of search to resolve undefined symbols is to load all files and libraries
  61 mentioned explicitly on the command line, and then to resolve remaining symbols
  62 by searching in topological order
  63 libraries mentioned in header files included by files already loaded.
  64 When scanning such libraries, the algorithm is to scan each library repeatedly until
  65 no new undefined symbols are picked up, then to start on the next library.  Thus if library
  66 .I A
  67 needs
  68 .I B
  69 which needs
  70 .I A
  71 again, it may be necessary to mention
  72 .I A
  73 explicitly so it will be read a second time.
  74 .PP
  75 The loader options are:
  76 .TP 0.75i
  77 .B -l
  78 (As a bare option.)
  79 Suppress the default loading of the startup linkage and libraries
  80 specified by header files.
  81 .TP
  82 .BI -o " out"
  83 Place output in file
  84 .IR out .
  85 Default is
  86 .IB O .out\f1,
  87 where
  88 .I O
  89 is the first letter of the loader name.
  90 .TP
  91 .B -p
  92 Insert profiling code into the executable output; no special action is needed
  93 during compilation or assembly.
  94 .TP
  95 .B -e
  96 Insert (\fLe\fPmbedded) tracing code into the executable output; no special action is needed
  97 during compilation or assembly.
  98 The added code calls
  99 .L _tracein
 100 at function entries
 101 and
 102 .L _traceout
 103 at function exits.
 104 .TP
 105 .B -F
 106 (ARM only) Don't generate VFP hardware floating point instructions.
 107 .TP
 108 .B -s
 109 Strip the symbol tables from the output file.
 110 .TP
 111 .B -a
 112 Print the object code in assembly language, with addresses.
 113 .TP
 114 .B -v
 115 Print debugging output that annotates the activities of the load.
 116 .TP
 117 .BI -M
 118 .RI ( Kl
 119 only) Generate instructions rather than calls to emulation routines
 120 for multiply and divide.
 121 .TP
 122 .BI -E symbol
 123 The entry point for the binary is
 124 .I symbol
 125 (default
 126 .BR _main ;
 127 .B _mainp
 128 under
 129 .BR -p ).
 130 .TP
 131 .BI -x " [ file ]"
 132 Produce an export table in the executable.
 133 The optional
 134 .I file
 135 restricts the exported symbols to those listed in the file.
 136 See
 137 .IR dynld (2).
 138 .TP
 139 .BI -u " [ file ]"
 140 Produce an export table, import table
 141 and a dynamic load section in the executable.
 142 The optional
 143 .I file
 144 restricts the imported symbols to those listed in the file.
 145 See
 146 .IR dynld (2).
 147 .TP
 148 .B -t
 149 (\c
 150 .I 5l
 151 and
 152 .I vl
 153 only)
 154 Move strings into the text segment.
 155 .TP
 156 .BI -H n
 157 Executable header is type
 158 .IR n .
 159 The meaning of the types is architecture-dependent; typically
 160 type 1 is Plan 9 boot format and type 2 is the
 161 regular Plan 9 format, the default.  These are reversed on the MIPS.
 162 The Next boot format is 3.  Type 4 in
 163 .I vl
 164 creates a MIPS executable for an SGI Unix system.
 165 .TP
 166 .BI -T t
 167 The text segment starts at address
 168 .IR t .
 169 .TP
 170 .BI -D d
 171 The data segment starts at address
 172 .IR d .
 173 .TP
 174 .BI -R r
 175 The text segment is rounded to a multiple of
 176 .I r
 177 (if
 178 .I r
 179 is nonzero).
 180 .PP
 181 The numbers in the above options can begin with
 182 .L 0x
 183 or
 184 .L 0
 185 to change the default base from decimal to hexadecimal or octal.
 186 The defaults for the values depend on the compiler and the
 187 header type.
 188 .PP
 189 The loaded image has several symbols inserted by the loader:
 190 .B etext
 191 is the address of the end of the text segment;
 192 .B bdata
 193 is the address of the beginning of the data segment;
 194 .B edata
 195 is the address of the end of the data segment;
 196 and
 197 .B end
 198 is the address of the end of the bss segment, and of the program.
 199 .SH FILES
 200 .TF /$objtype/lib
 201 .TP
 202 .B /$objtype/lib
 203 for
 204 .BI -l lib
 205 arguments.
 206 .SH SOURCE
 207 .B /sys/src/cmd/2l
 208 etc.
 209 .SH "SEE ALSO"
 210 .IR 2c (1),
 211 .IR 2a (1),
 212 .IR ar (1),
 213 .IR nm (1),
 214 .IR db (1),
 215 .IR prof (1)
 216 .PP
 217 Rob Pike,
 218 ``How to Use the Plan 9 C Compiler''
 219 .SH BUGS
 220 The list of loaders given above is only partial,
 221 not all architectures are supported on all systems,
 222 some have been retired and some
 223 are provided by third parties.