ld Command Purpose Links object files. Syntax ld [ -eLabel ] [ -DNumber ] [ -HNumber ] [ -K ] [ -M ] [ -m ] [ -oName ] [ -Q ] [ -r ] [ -s ] [ -SNumber ] [ -T Number ] [ -v ] [ -x ] [ -z ] [ -ZString ] [ -LDirectory ... ] [ -fFileID ... ] [ -lKey ... ] [ -b Option ... ] InputFile ... Description The ld command (the linkage editor or binder) combines the desig- nated object files, import lists, and libraries into one object file, resolving external references. It produces an executable object file that can be run, or if specified without the -s flag, can become the InputFile parameter in another call to the ld command. The ld command by default creates and places its output in the a.out file. The linkage editor can rebind without requiring that all input object files be named again. For example, if one object file from a large program has changed, you can relink the program by listing the new object file and the old program on the command line, along with any shared libraries required by the program. The ld command links object files, libraries, and import lists in the order specified on the command line. If a file is specified more than once on the command line, only the first occurrence of the file is processed. At least one input file must be speci- fied, whether with the -bI (uppercase i), -bimport, -f, or -l (lowercase L) flag or as an InputFile parameter. (The -bI or -bimport flag is the -b flag used with the I or import input op- tion.) Libraries are archive files with names that end in .a. A library can be designated by an absolute or relative path name, or by us- ing the -l (the lowercase letter L) flag in the form -lxyz. The last form designates an libxyz.a archive file to be searched for in several directories; first in any directories specified by -L flags, then in the standard library directory /usr/lib. (The standard library directories were previously /lib and /usr/lib.) Members of an archive file can be object files, shared objects, or import lists. If an archive contains another archive or a member whose type is not recognized, the ld command reports a severe error and does not process the archive. The ld command processes all object files and libraries in the same manner. It includes the symbol table of all objects, dis- carding only symbol definitions that duplicate already-defined symbols. Unlike some other versions of the ld command, you do not need to order library objects so references precede defini- tions. You also do not need to list an archive more than once on the command line. Import lists are ASCII files that identify which external symbols are to be resolved during run time, instead of being resolved during the linkage editor process. An import list usually iden- tifies the executable object file containing the definition of the import symbol. The loader finds and resolves that symbol at run time. If the first line of an import list begins with #! (pound sign, exclamation point), the file may be specified on the command line as an ordinary InputFile parameter. Otherwise, the -bI or -bimport flag must be used. The information needed to resolve import references is found in one of two places: * The loader section of shared object files * Import files, specified with the -bI or -bimport flag, con- tained in an archive, or listed as an InputFile parameter on the command line. Export lists are ASCII files that identify external symbols that are to be made available for another executable object file to import. The file format of an export list is the same as the file format of an import list. There are six predefined symbols for the ld command. Five of these symbols are used to provide special address locations and can be declared in C as extern char name[ ]. Redefining these symbols will result in unspecified behavior. The symbol names are: _text First location of the program. _data First location of the data. _etext First location above the program. _edata First location above initialized data. _end and end First location above all data. A sixth symbol, _ptrgl, is used by compilers to implement calls using function pointers. Flags The order of flags does not affect the way they work, except for the flags associated with input object files, archives, and im- ports. These flags are: -L, -f, -l (the lowercase letter L), and -bI (uppercase i), and they are processed in the following order: 1. The -L flag adds a directory to the list of directories to be searched to locate libraries specified by the -l (the lowercase letter L) flag. The directories are searched in the order speci- fied. The -L flags are processed before any object files. 2. Object files, input object files specified by the -f flag, and archive libraries specified by the -l (the lowercase letter L) flag, are all processed in the order specified. 3. Import lists specified by the -bI (uppercase letter i) flag are processed in the order specified, after all other object files and libraries have been processed. An import list can be specified like a regular object file without the -bI (uppercase letter i) flag if it is necessary to process an import list prior to a regular object file. In this case, the first record of the import list must begin with the #! (pound sign and exclamation point) symbols, and the import list is processed with the files in step number two (see above). For compatibility with other versions of the ld command, some flags are recognized, but ignored. Ignored flags produce a mes- sage stating that the flag and its operand were ignored. An ig- nored flag does not cause the ld command to terminate early. Flags that are not valid produce a message stating that the flag is not valid. After all the flags that are not valid are diag- nosed, the ld command terminates without any further processing. If conflicting flags are specified on the command line, the ld command accepts the latest flag and ignores the earlier one. Flags with an operand can be entered with or without a space between the flag and the operand. Numeric values can be speci- fied in decimal, octal (with a leading 0), or hexadecimal (with a leading 0x or 0X) format. -ANumber Prints a message indicating this flag has been ignored. -bOption Sets binder (ld) special control and processing options. See the following information on binder options. This flag can be repeated. -BNumber Prints a message indicating this flag has been ignored. -d Prints a message indicating this flag has been ignored. -DNumber Makes the contents of the Number variable the starting address for the initialized data (the .data section) of the out- put file. If the Number variable is -1, the data section starts immediately after the text section. If not specified, the data section begins at location 0. Note: The system loader relocates the .data section at run time, so the specified number only affects addresses listed in address maps or printed by utilities such as the dump or nm command. -eLabel Makes the contents of the Label variable the entry point of the executable output file (-e __start (double underscore start) is the default). -fFileID Takes the names of the .o and .a files to process from the contents of the file specified by the FileID variable. The file specified by the FileID variable must contain a list of in- put file names, each of which is treated as if it had been listed separately on the ld command line, rather than with the -f flag. Lines in the file can contain shell pattern characters *, [, ], and ?, which are expanded in the usual way and may designate mul- tiple object files. The input object files, archive libraries specified by the -l (lowercase L) flag, and object files speci- fied by the -f flag are processed by the binder in the order specified on the ld command line. This flag can be repeated. For information on generating path names, see the glob subrou- tine in AIX Version 3.2 Technical Reference Volume 1: Base Operating System and Extensions. -HNumber Makes the value of the Number variable the boundary to which the .text, .data, and .loader sections are aligned within the output object file. To perform the specified file boundary alignment, the binder inserts a pad section of an appropriate size prior to the .text, .data, and .loader sections of the out- put object file. If the value of the Number variable is 0, no padding is inserted. To ensure that the system loader can load a program, the .text section must be aligned at least as strictly as is required by a .text CSECT. For example, the XL C Compiler generates code CSECTs with double-word alignment. Thus, -H8, which specifies that the sections be aligned on a double-word boundary, is ordi- narily the minimum value of the Number variable. The xlc.cfg file causes the cc command to use the -H512 option when calling the ld command. The default is not to align the .text, .data, and .loader sec- tions of the output object file. -i Prints a message indicating this flag has been ignored. -j[Key:]Number Prints a message indicating this flag has been ignored. -kKey:Path Prints a message indicating this flag has been ig- nored. -K Pads the header, .text, .data, and .loader segments of the output file to lie on page boundaries. This flag is equivalent to specifying -HNumber, where the Number variable is the page size. -lKey Processes the libKey.a file, which is located in one of the directories specified by the -L flag or the standard library directory (/usr/lib). The files specified with this argument are searched in the order specified, along with the input object files and all the files specified with the -f flag. This flag can be repeated. (l is the lowercase letter L.) In this version of the ld command, the first definition of each symbol in the link always takes precedence and is used even if the first reference follows the definition. -LDirectory Adds the contents of the Directory variable to the list of directories to be searched for libraries designated by the -l (the lowercase letter L) flag. This flag can be repeated. The list of directories, along with the standard library directo- ry, is also recorded in the output object file loader section for use by the dynamic loader. -M or -m Lists to the load map output file the names of all files and archive members processed to create the output file. -n Prints a message indicating this flag has been ignored. -N Prints a message indicating this flag has been ignored. -o Name Names the output file the contents of the Name variable rather than the a.out file. -Q Has no effect in this operating system. -r Permits the output file to be produced even though it contains unresolved symbols. A file produced with this flag is not exe- cutable and is expected to be used as a file parameter in another ld command call. The -r flag is equivalent to specifying the erok, noglink, nox, and nogc options with the -b flag. (Subse- quent options can override these options.) -RNumber Prints a message indicating this flag has been ignored. -s Strips the symbol table, line number information, and reloca- tion information from the output. This saves space but impairs the usefulness of the debug program. Using the strip command has the same effect. -SNumber Makes the value of the Number variable the maximum size the user stack is allowed to grow. This value represents the number of bytes allowed. If the value of the Number variable is 0, the system default limit is used. The default value is 0. For more information on large user stacks, see "Large Program Support Overview" in AIX Version 3.2 General Programming Con- cepts. -TNumber Makes the value of the Number variable the starting ad- dress for the text segment of the output file. The default value is 0. Note: The system loader relocates the .text section at run time, so the specified number affects only addresses listed in address maps or printed by utilities such as the dump or nm command. -uSymbol Prints a message indicating this flag has been ignored. -v Writes additional information to the load map file. -VNumber Prints a message indicating this flag has been ignored. -x Has no effect in this operating system. -YNumber Prints a message indicating this flag has been ignored. -z Same as the -K flag. -ZString Prefixes the standard library directory with the con- tents of the String variable when searching for libraries speci- fied by the -l (the lowercase letter L) flag. For example, with the -Z/test and -lxyz flags, the ld command looks for the /test/usr/lib/libxyz.a file. When the -ZString flag is used, the standard library directory is not searched. This flag is useful when developing a new version of a library. Binder Options (-bOptions) This version of the ld command validates the command-line argu- ments and calls the binder (usually the /usr/lib/bind file), passing a generated list of binder subcommands. The binder pro- gram actually links the files. Two binder options affect the calling of the binder. The binder option specifies which binder to call, and the nobind option prevents any binder from being called. The other binder options affect the behavior of the binder program itself. The following binder option values are possible for the Options variable of the -b flag. Note: In the binder options listed below, two option names separated by the word or are synonymous. Either option name can be used. If conflicting options are specified, the last one takes precedence. The FileID argument indicates an AIX path name. Either a relative or a full path name may be used. asis Processes all external symbols in mixed case. This is a default option. autoimp or so Imports symbols from any shared object files specified in the bind. The shared object file is referenced but is not bound in as part of the output object file. This is a de- fault option. bindcmds:FileID Writes a copy of the binder commands generated by the ld command to the file specified by the contents of the FileID variable. The resultant file can be redirected as stan- dard input to the binder program when run in standalone or in- teractive mode. The default is that no file is produced. binder:FileID Specifies the name of the binder program called by the ld command. The name is specified by the contents of the FileID variable. The default is the /usr/lib/bind file. bindopts:FileID Puts a copy of the binder program arguments into the file specified by the contents of the FileID variable. The resultant file can be used to invoke the binder program in stan- dalone or interactive mode. The default is that no file is pro- duced. calls:FileID or C:FileID Writes a calls-symbol cross-reference of the output object file to FileID. The default is that no file is produced. To learn more about the calls option, see " Address Maps" . caps Processes all external symbols in uppercase. The default is the asis option. comprld or crld Combines multiple relocation entries (RLDs) at the same address into a single RLD. This is a default option. cror15 Uses the cror 15,15,15 (0x4def7b82) instruction as the special nop instruction following a call instruction. This op- tion is provided to prevent the binder from using the new default cror 31,31,31 (0x4ffffb82) instruction as the special nop in- struction. This option should only be used when binding object files on the current level of the system that will need to be rebound on a previous Version 3.1 release level of the operating system. The default value is cror31. cror31 Uses the cror 31,31,31 (0x4ffffb82) instruction as the special nop instruction following a call instruction. This is a default option. D:Number Same as the maxdata option. debugopt:Option or dbg:Option Sets a special debugging option in the binder. By default, no debug option is set. delcsect During the symbol resolve process, causes the binder to delete all symbols within a csect whenever a replacement symbol is encountered. The default is the nodelcsect option. E:FileID Same as export:FileID. ernotok or f Omits accepting external references at the end of the bind. The binder does not produce the output object file if there are unresolved external references. This is a default op- tion. erok Produces the output object file even if there are unresolved external references. The default is the ernotok option. errmsg Writes error messages to the display device if the error code is greater than the halt value. This option overrides the quiet option. This is a default option. ex1:FileID Provides user exits in the normal binder subcommand sequence. Each file specified by the FileID variable must con- tain a list of binder subcommands, which will be executed immedi- ately before reading any values of the InputFile parameter. No default user exits exist. ex2:FileID Provides user exits in the normal binder subcommand sequence. Each file specified by the FileID variable must con- tain a list of binder subcommands, which will be executed immedi- ately before symbol resolution processing. No default user exits exist. ex3:FileID Provides user exits in the normal binder subcommand sequence. Each file specified by the FileID variable must con- tain a list of binder subcommands, which will be executed immedi- ately after symbol resolution processing. No default user exits exist. ex4:FileID Provides user exits in the normal binder subcommand sequence. Each file specified by the FileID variable must con- tain a list of binder subcommands, which will be executed immedi- ately before writing the output file. No default user exits ex- ist. ex5:FileID Provides user exits in the normal binder subcommand sequence. Each file specified by the FileID variable must con- tain a list of binder subcommands, which will be executed after writing the output file. No default user exits exist. export:FileID or E:FileID Exports the external symbols listed in the file specified by the FileID variable. There is no default export file. f Same as ernotok. filelist or fl Uses the filelist command instead of the insert command for reading the object files for processing. The filelist command optimizes the allocation of internal processing tables by pre-scanning the input object files. The default is the insert option. gc Performs garbage collection. Garbage collection is the pro- cess of discarding unreferenced (that is, unneeded) control sec- tions (CSECTs) before writing the output file. This is a default option. A CSECT is a unit of coding, instructions, or data that is itself an entity. A CSECT is the smallest separately relocat- able unit of a program. If a symbol is not referenced but is needed in the output file (such as a routine to be called during a debugging session), the symbol can be exported to keep it from being discarded. This is a default option. gcbypass:Number If the gc option is selected, specifies the number of files to bypass for garbage collection processing. This option is valid only when the gc and filelist options are used. If the value of the Number variable is 0, no object files are bypassed. The default value is 0. glink:FileID Uses the global linkage prototype code specified in the FileID variable. Global-linkage interface code is generated for each imported or undefined function. The default is the /usr/lib/glink.o file. halt:Number or h:Number Specifies the maximum error level for binder command processing to continue. The default value is 2. If any binder subcommand has a return code greater than the value of the Number variable, no additional binder subcommands are pro- cessed. If the halt level is 8 or greater, the output file may not be executable. Return codes are: 0 No error 4 Warning 8 Error 12 Severe error 16 Internal program error i Same as the insert option. import:FileID or I(the uppercase letter i):FileID Imports the external symbols listed in the file specified in the FileID vari- able. There is no default import file. insert or i Uses the insert command instead of the filelist com- mand to read the object files for processing. This is a default option. loadmap:FileID or l(the lowercase letter L):FileID Writes the results of each command to the file specified by the FileID vari- able. The default is that no file is produced. map:FileID or R:FileID Writes a symbol map in address order to the file specified by the FileID variable of the output object file. The default is that no file is produced. To learn more about the map option, see " Address Maps" . maxdata:Number or D:Number Sets the value of the Number variable to the maximum size, in bytes, that the user data area is allowed to increase. If the Number variable is 0, the system default limit is used. The default value is 0. For more information on large user data areas, see "Large Pro- gram Support Overview" in AIX Version 3.2 General Programming Concepts. maxstack:Number Same as the -S flag. modtype:ModuleType or M:ModuleType Sets the two-character module- type field and the shared object flag in the object file. The module type is not checked by the binder, but it should be set to one of the following: 1L Single use. Module requires a private copy of the data sec- tion for each load. This is a default option. RE Reusable. Module requires a private copy of the data area for each process dependent on the module. RO Read only. Module is read-only, and can be used by several processes at once. If an S prefix is used on any of the above options, the shared flag in the object file is set. The system loader ignores the module types field. The system loader will attempt to share a single instance of the .data section of an RO module. Otherwise, the module type is ig- nored by the system loader. The default value is 1L. nl Same as the noloadmap option. noautoimp or nso Binds in as part of the output object file, any unstripped shared object file specified as input to the bind. The default is the autoimp option. nobind Omits calling the binder. Instead, the ld command writes the generated list of binder subcommands to standard output. The default is to have the ld command call the binder. nocomprld or nocrld Omits combining multiple relocation entries (RLDs) at the same address into a single RLD. The default is the comprld option. nodelcsect During the symbol resolve process, the binder deletes only the replaced symbols of a CSECT. If the -s flag is not used, the replaced symbol will be changed to an internal symbol in the output object file symbol table, and will not be visible for symbol resolution during a subsequent bind. This is a de- fault option. noerrmsg Omits writing error messages to the display device if the quiet option is set. The default is the errmsg option. nogc Omits garbage collection. Garbage collection is the process of discarding unreferenced (that is, unneeded) CSECTs from the output object file. The default is the gc option. noglink Omits performing the addgl command to insert global link- age code. The default is to have the binder insert the global linkage code. noloadmap or nl Omits writing the results of each command to a results file. This is a default option. noobjreorder Omits using the depth-first CSECT reordering logic. The resultant CSECTs for an application executable file are ar- ranged in the same order that the object files and library files were specified on the command line, except as follows: * CSECTs are placed in their correct .text, .data, or .bss sec- tion of the object file. This is based on the CSECT storage- class field. * All TC (TOC address constant) CSECTs are grouped together. If both the noobjreorder and noreorder options are specified, the noreorder option takes precedence. The default is the reorder option. noquiet Writes the results of each subcommand to standard output. The default is the quiet option. noreorder Omits reordering CSECTs, except to combine all TC (TOC address constant) CSECTs and place them in the .data section. All other CSECTs are placed in the .text section, so text and data are mixed in the output file. This option should be used only to link the kernel, because the resulting output file cannot be loaded by the system loader. If both noobjreorder and noreorder options are specified, the noreorder option takes pre- cedence. The default is the reorder option. nostrcmpct During final object processing, the binder does not eliminate duplicate occurrences of identical strings in the typchk section and the string table of the output object file. This is a default option. notextro or nro Omits checking to ensure that there are no load time relocation entries for the .text section of the output ob- ject file. This is a default option. notypchk Omits function-parameter type checking between external functional calls. The default is the typchk option. nox Omits making the output file executable. nro Same as the notextro option. quiet Omits writing the results of each command to the standard output. This is a default option. R:FileID Same as the map:FileID option. rename:Symbol, NewName Renames the external symbol specified by the Symbol variable to the name specified by the NewName vari- able. The effect of renaming a symbol is as if all definitions and references to Symbol in all object files had been renamed to NewName before the file were processed. The default is to rename no symbols. reorder or r Reorders CSECTs as part of the save command process- ing. The reorder process arranges CSECTs of the same storage- mapping class by proximity of reference. This is a default op- tion. ro Same as the textro option. S:Number Same as the -S flag. so Same as the autoimp option. strcmpct During final object output processing, eliminates dupli- cate occurrences of identical strings in the typchk section and the string table of the resultant a.out object file. The de- fault is the nostrcmpct option. textro or ro Checks to ensure that there are no load time reloca- tion entries for the .text section of the resultant object file. The default is the nro option. typchk Performs function-parameter type checking between external functional calls. Parameter-type checking information can be in- cluded in object files by compilers and assemblers. This is a default option. For more information on type checking, see Typchk Section in "Special Data Sections for the a.out File" in AIX Version 3.2 Files Reference. x The output file is made executable. X Same as the xref:FileID option. xref:FileID or X:FileID Writes a symbolic and relocation (RLD) cross-reference map to the file specified by the FileID parameter of the output object file. To learn more about maps, see the " Address Maps" information. The default is that no file is pro- duced. Import and Export File Format (-bI: and -bE: Flags) Each line within an import or export file must list a single sym- bol. In an import file, you can specify an address after the symbol, allowing data CSECTs to be mapped to a shared memory seg- ment and eliminating the need to use the assembler. An address is ignored if the file is used as an export file. In an export file, you can use the svc or syscall keyword after a name to indicate that it is a system call. This is needed when linking kernel extensions. The svc or syscall keyword is ignored if the file is used as an import file. The ld command treats import and export files according to the following: * A blank line is ignored. * A line beginning with an * (asterisk) is treated as a comment and is ignored. * A line beginning with a # (pound sign, blank space) provides operands to the setopt binder subcommand (-b dbg:Option). For example, a line containing # verbose causes the binder to list each symbol as it is read from the file. These option settings are active only while processing the file. * When processing an import file, a line beginning with a #! (pound sign, exclamation point) provides the shared library name to be associated with the subsequent import symbols. The line can occur more than once. This file name information is placed in the loader section of the xcoff object file and is used by the system loader to locate the appropriate object file at execution time. If the import file name is: ipath/ifile (imember), the file name placed in the loader section is determined based on the import file name and the contents of the #! line of the import file, as follows: #! (Nothing after the #!) Use null path, null file, and null number. This is treated as a delayed resolve by the system loader. #! () Use ipath, ifile, and imember. This line can be used if the import file is specified as an InputFile parameter, because the file must begin with #! in this case. It can also be used to restore the default name if it was changed by another #! line. #! path/file (member) Use specified path, file, and member. #! path/file Use specified path and file, and a null member. #! file Use a null path, specified file, and a null member. At run time, a list of directories will be searched to find the shared object. #! (member) Use ipath, ifile, and specified member. At run time, a list of directories will be searched to find the shared object. #! file (member) Use a null path and specified file and member. At run time, a list of directories will be searched to find the shared object. #! (member) Use ipath, ifile, and specified member. For more information on creating a shared library, see " How to Create a Shared Library" in AIX Version 3.2 General Programming Concepts. For more information on loading and binding, see the load subroutine in AIX Version 3.2 Technical Reference Volume 1: Base Operating System and Extensions. Address Maps Address maps can be generated, listing the layout of symbols in the output object file. If the map option is used, unresolved symbols and imported symbols are listed first, followed by the symbols in each section, in address order. The calls option is used to list, after each symbol, references from the symbol to other symbols. Finally, the xref option is used to list, after each symbol, references from other symbols to that symbol. The -T and -D flags affect the addresses printed in these address maps. For machine-level debugging, it may be convenient to determine where the text and data sections exist during execu- tion, and use those addresses as arguments to the -T and -D flags. For an executable running on AIX Version 3.2, -T0x10000400 is usually the correct value. The correct value for the -D flag varies, depending on any shared libraries that might be loaded. Examples 1. To link several object files and produce an a.out file to run under the operating system, enter: ld -T512 -e__start /usr/ccs/lib/crt0.o pgm.o subs1.o subs2.o -lc The -lc (lowercase letter L) links the libc.a library. A simpler way to accomplish this is to use the cc command to link the files as follows: cc pgm.o subs1.o subs2.o Since the cc command automatically uses the link options and necessary support libraries, you do not need to specify them on the command line (it gets this information from the /etc/xlc.cfg configuration file). For this reason, you should use the cc com- mand to link files when you are producing programs that run under the operating system. 2. To specify the name of the output file, enter: cc -o pgm pgm.o subs1.o subs2.o This stores the linked output in the file pgm. 3. To relink if only the object file subs1.o has changed, enter: cc -o pgm subs1.o pgm The CSECTs that originally came from object files pgm.o and subs2.o will be read from the file pgm. This technique can speed the linking process if a program consists of a large number of input files, but only a few files change at a time. 4. To link with library subroutines, enter: cc pgm.o subs1.o subs2.o mylib.a -ltools This links the object modules pgm.o, subs1.o, and subs2.o, the subroutines from the mylib.a directory, and the subroutine from the library specified by -l (the lowercase letter L) flag. (This means the /usr/lib/libtools.a file). 5. To generate a shared object file, enter: ld -o shrsub.o subs1.o subs2.o -bE:shrsub.exp -bM:SRE -T512 -H512 -lc This links the object files subs1.o, subs2.o, and the subroutines from the library libc.a specified by -l flag (the lowercase letter L). It exports the symbols specified in the file shrsub.exp and stores the linked shared object in file shrsub.o. The -bM:SRE sets the shared object flag in the linked object file. 6. To link with the shared object file shrsub.o generated above, enter: cc -o pgm pgm.o shrsub.o -L '.' This links the object file pgm.o with the exported symbols of shrsub.o. The linked output is stored in the object file pgm. The -L '.' adds the current directory to the library search path that the system loader uses to locate the shrsub.o shared object file. At run time, this program is loaded only if it is executed from a directory containing an instance of the shrsub.o file or if the shrsub.o file is found in the /usr/lib standard library directory. To allow the program to be run from anywhere, use the option -L `pwd` (single left quotation mark). The list of directories searched by the system loader can be seen using the dump command. 7. To link a program using the libc.a library as a non-shared li- brary, enter: cc -o pgm pgm.o -bnso -bI:/lib/syscalls.exp This links pgm.o with the necessary support libraries and names the output file pgm. For the cc command, the libc.a library is a necessary support library and is normally link-edited to the user's program as a shared library. In this example, the -bnso option directs the ld command to link with the libc.a library as a non-shared library, and the -bI:/lib/syscalls.exp directs the ld command to import the system call functions that are actually contained in the kernel or /usr/lib/boot/unix. Whenever linking with the -bnso option, any symbols that were both imported and exported (that is, passed through) in a shared object file must be explicitly imported, as is done by the -bI:/lib/syscalls.exp option in this example. Note: Any time that /usr/lib/libc.a is linked non-shared, the flag -bI:/lib/syscalls.exp must be used. The application may also have to be linked again whenever an updated release of the operating system is installed. 8. To link with one library non-shared and the remaining li- braries shared, first enter: ld -r shrsub.o -o nonshrsub.o -bnso This use of the ld command generates in nonshrsub.o a non-shared version of shrsub.o. Next enter the following: cc -o pgm pgm.o nonshrsub.o The cc command uses nonshrsub.o instead of shrsub.o. Additional shared libraries remain shared. In this example, the shared ob- jects in the /usr/lib/libc.a implicit library remain shared. Implementation Specifics This command is part of Base Operating System (BOS) Runtime. Files /usr/lib/lib*.a Specifies libraries used for linking programs. a.out Specifies the default output file name. Related Information How to Create a Shared Library in AIX Version 3.2 General Pro- gramming Concepts. The ar command, as command, cc command, dump command, nm command, strip command. The load subroutine, loadquery subroutine, loadbind subrou- tine, unload subroutine. The a.out file format. Shared Library Overview in AIX Version 3.2 General Programming Concepts. ================================================================= ================================================================= Efficient Use of the ld Command The AIX binder (invoked as the final stage of a compile or directly via the ld command) has functions that are not found in the typical UNIX linker. This can result in longer linking times if the additional power of the AIX binder is not exploited. This section describes some techniques for more efficient use of the binder. Rebindable Executables The formal documentation of the binder refers to the ability of the binder to take an executable (a load module) as input. Ex- ploitation of this function can significantly improve the overall performance of the system with software development workloads, as well as improving the response time of individual lds. In most typical UNIX systems, the ld command always takes as in- put a set of files containing object code, either from individual .o files or from archived libraries of .o files. The ld command then resolves the external references among these files and writes an executable with the default name of the a.out file. The a.out file can only be executed. If a bug is found in one of the modules that was included in the a.out file, the defective source code is changed and recompiled, and then the entire ld process must be repeated, starting from the full set of .o files. In the AIX operating system, however, the binder can accept both .o and a.out files as input, because the binder includes resolved External Symbol Dictionary (ESD) and Relocation Dictionary (RLD) information in the executable file. This means that the user has the ability to rebind an existing executable to replace a single modified .o file, rather than building a new executable from the beginning. Since the binding process consumes storage and pro- cessor cycles partly in proportion to the number of different files being accessed and the number of different references to symbols that have to be resolved, rebinding an executable with a new version of one module is much quicker than binding it from scratch. Prebound Subroutine Libraries Equally important in some environments is the ability to bind an entire subroutine library in advance of its use. The system sub- routine libraries such as libc.a are, in effect, shipped in binder-output format, rather than as an archive file of .o file's. This saves the user considerable processing time when binding an application with the required system libraries, since only the references from the application to the library subrou- tines have to be resolved. References among the system library routines themselves have already been resolved during the system build process. Many third-party subroutine libraries, however, are routinely shipped in archive form as raw .o file's. When users bind appli- cations with such libraries, the binder has to do symbol resolu- tion for the entire library each time the application is bound. This results in long bind times in environments where applica- tions are being bound with large libraries on small machines. The performance difference between bound and unbound libraries is dramatic, especially in minimum configurations. One user report- ed ld command execution times on the order of 11 minutes in an 8MB model 320 when binding a small FORTRAN program with an 8+MB subroutine library that had been built in the usual archive form. When the subroutine library was prebound, the time required to bind the FORTRAN program fell to approximately 1.7 minutes. When the resulting a.out file was rebound with a new FORTRAN .o file, simulating the handling of a trivial bug fix, the bind time fell to approximately 4 seconds. Examples 1. To prebind a library, use the following command on the archive file: ld -r libfoo.a -o libfooa.o 2. The compile and bind of the FORTRAN program something.f is as follows: xlf something.f libfooa.o Notice that the prebound library is treated as another ordinary input file, not the usual library identification syntax (-lfoo). 3. To recompile the module and rebind the executable after fixing a bug, the user enters: xlf something.f a.out 4. However, if the bug fix had resulted in a call to a different subroutine in the library, the bind would fail. The following Korn shell script tests for a failure return code and recovers from the error: # !/usr/bin/ksh # Shell script for source file replacement bind # xlf something.f a.out rc=$? if [ "$rc" != 0 ] then echo "New function added ... using libfooa.o" xlf something.o libfooa.o fi Related Information AIX Version 3.2 Performance Monitoring and Tuning Guide: Content List. The XCOFF Object (a.out) File Format. The ld command.