s: * -export-all-symbols [This is the default] * -exclude-symbols * -exclude-libs * -exclude-modules-for-implib * -version-script When auto-export is in operation, `ld' will export all the non-local (global and common) symbols it finds in a DLL, with the exception of a few symbols known to belong to the system's runtime and libraries. As it will often not be desirable to export all of a DLL's symbols, which may include private functions that are not part of any public interface, the command-line options listed above may be used to filter symbols out from the list for exporting. The `--output-def' option can be used in order to see the final list of exported symbols with all exclusions taken into effect. If `--export-all-symbols' is not given explicitly on the command line, then the default auto-export behavior will be _disabled_ if either of the following are true: * A DEF file is used. * Any symbol in any object file was marked with the __declspec(dllexport) attribute. _using a DEF file_ Another way of exporting symbols is using a DEF file. A DEF file is an ASCII file containing definitions of symbols which should be exported when a dll is created. Usually it is named `.def' and is added as any other object file to the linker's command line. The file's name must end in `.def' or `.DEF'. gcc -o .def Using a DEF file turns off the normal auto-export behavior, unless the `--export-all-symbols' option is also used. Here is an example of a DEF file for a shared library called `xyz.dll': LIBRARY "xyz.dll" BASE=0x20000000 EXPORTS foo bar _bar = bar another_foo = abc.dll.afoo var1 DATA doo = foo == foo2 eoo DATA == var1 This example defines a DLL with a non-default base address and seven symbols in the export table. The third exported symbol `_bar' is an alias for the second. The fourth symbol, `another_foo' is resolved by "forwarding" to another module and treating it as an alias for `afoo' exported from the DLL `abc.dll'. The final symbol `var1' is declared to be a data object. The `doo' symbol in export library is an alias of `foo', which gets the string name in export table `foo2'. The `eoo' symbol is an data export symbol, which gets in export table the name `var1'. The optional `LIBRARY ' command indicates the _internal_ name of the output DLL. If `' does not include a suffix, the default library suffix, `.DLL' is appended. When the .DEF file is used to build an application, rather than a library, the `NAME ' command should be used instead of `LIBRARY'. If `' does not include a suffix, the default executable suffix, `.EXE' is appended. With either `LIBRARY ' or `NAME ' the optional specification `BASE = ' may be used to specify a non-default base address for the image. If neither `LIBRARY ' nor `NAME ' is specified, or they specify an empty string, the internal name is the same as the filename specified on the command line. The complete specification of an export symbol is: EXPORTS ( ( ( [ = ] ) | ( = . )) [ @ ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== ] ) * Declares `' as an exported symbol from the DLL, or declares `' as an exported alias for `'; or declares `' as a "forward" alias for the symbol `' in the DLL `'. Optionally, the symbol may be exported by the specified ordinal `' alias. The optional `' is the to be used string in import/export table for the symbol. The optional keywords that follow the declaration indicate: `NONAME': Do not put the symbol name in the DLL's export table. It will still be exported by its ordinal alias (either the value specified by the .def specification or, otherwise, the value assigned by the linker). The symbol name, however, does remain visible in the import library (if any), unless `PRIVATE' is also specified. `DATA': The symbol is a variable or object, rather than a function. The import lib will export only an indirect reference to `foo' as the symbol `_imp__foo' (ie, `foo' must be resolved as `*_imp__foo'). `CONSTANT': Like `DATA', but put the undecorated `foo' as well as `_imp__foo' into the import library. Both refer to the read-only import address table's pointer to the variable, not to the variable itself. This can be dangerous. If the user code fails to add the `dllimport' attribute and also fails to explicitly add the extra indirection that the use of the attribute enforces, the application will behave unexpectedly. `PRIVATE': Put the symbol in the DLL's export table, but do not put it into the static import library used to resolve imports at link time. The symbol can still be imported using the `LoadLibrary/GetProcAddress' API at runtime or by by using the GNU ld extension of linking directly to the DLL without an import library. See ld/deffilep.y in the binutils sources for the full specification of other DEF file statements While linking a shared dll, `ld' is able to create a DEF file with the `--output-def ' command line option. _Using decorations_ Another way of marking symbols for export is to modify the source code itself, so that when building the DLL each symbol to be exported is declared as: __declspec(dllexport) int a_variable __declspec(dllexport) void a_function(int with_args) All such symbols will be exported from the DLL. If, however, any of the object files in the DLL contain symbols decorated in this way, then the normal auto-export behavior is disabled, unless the `--export-all-symbols' option is also used. Note that object files that wish to access these symbols must _not_ decorate them with dllexport. Instead, they should use dllimport, instead: __declspec(dllimport) int a_variable __declspec(dllimport) void a_function(int with_args) This complicates the structure of library header files, because when included by the library itself the header must declare the variables and functions as dllexport, but when included by client code the header must declare them as dllimport. There are a number of idioms that are typically used to do this; often client code can omit the __declspec() declaration completely. See `--enable-auto-import' and `automatic data imports' for more information. _automatic data imports_ The standard Windows dll format supports data imports from dlls only by adding special decorations (dllimport/dllexport), which let the compiler produce specific assembler instructions to deal with this issue. This increases the effort necessary to port existing Un*x code to these platforms, especially for large c++ libraries and applications. The auto-import feature, which was initially provided by Paul Sokolovsky, allows one to omit the decorations to achieve a behavior that conforms to that on POSIX/Un*x platforms. This feature is enabled with the `--enable-auto-import' command-line option, although it is enabled by default on cygwin/mingw. The `--enable-auto-import' option itself now serves mainly to suppress any warnings that are ordinarily emitted when linked objects trigger the feature's use. auto-import of variables does not always work flawlessly without additional assistance. Sometimes, you will see this message "variable '' can't be auto-imported. Please read the documentation for ld's `--enable-auto-import' for details." The `--enable-auto-import' documentation explains why this error occurs, and several methods that can be used to overcome this difficulty. One of these methods is the _runtime pseudo-relocs_ feature, described below. For complex variables imported from DLLs (such as structs or classes), object files typically contain a base address for the variable and an offset (_addend_) within the variable-to specify a particular field or public member, for instance. Unfortunately, the runtime loader used in win32 environments is incapable of fixing these references at runtime without the additional information supplied by dllimport/dllexport decorations. The standard auto-import feature described above is unable to resolve these references. The `--enable-runtime-pseudo-relocs' switch allows these references to be resolved without error, while leaving the task of adjusting the references themselves (with their non-zero addends) to specialized code provided by the runtime environment. Recent versions of the cygwin and mingw environments and compilers provide this runtime support; older versions do not. However, the support is only necessary on the developer's platform; the compiled result will run without error on an older system. `--enable-runtime-pseudo-relocs' is not the default; it must be explicitly enabled as needed. _direct linking to a dll_ The cygwin/mingw ports of `ld' support the direct linking, including data symbols, to a dll without the usage of any import libraries. This is much faster and uses much less memory than does the traditional import library method, especially when linking large libraries or applications. When `ld' creates an import lib, each function or variable exported from the dll is stored in its own bfd, even though a single bfd could contain many exports. The overhead involved in storing, loading, and processing so many bfd's is quite large, and explains the tremendous time, memory, and storage needed to link against particularly large or complex libraries when using import libs. Linking directly to a dll uses no extra command-line switches other than `-L' and `-l', because `ld' already searches for a number of names to match each library. All that is needed from the developer's perspective is an understanding of this search, in order to force ld to select the dll instead of an import library. For instance, when ld is called with the argument `-lxxx' it will attempt to find, in the first directory of its search path, libxxx.dll.a xxx.dll.a libxxx.a xxx.lib cygxxx.dll (*) libxxx.dll xxx.dll before moving on to the next directory in the search path. (*) Actually, this is not `cygxxx.dll' but in fact is `xxx.dll', where `' is set by the `ld' option `--dll-search-prefix='. In the case of cygwin, the standard gcc spec file includes `--dll-search-prefix=cyg', so in effect we actually search for `cygxxx.dll'. Other win32-based unix environments, such as mingw or pw32, may use other `'es, although at present only cygwin makes use of this feature. It was originally intended to help avoid name conflicts among dll's built for the various win32/un*x environments, so that (for example) two versions of a zlib dll could coexist on the same machine. The generic cygwin/mingw path layout uses a `bin' directory for applications and dll's and a `lib' directory for the import libraries (using cygwin nomenclature): bin/ cygxxx.dll lib/ libxxx.dll.a (in case of dll's) libxxx.a (in case of static archive) Linking directly to a dll without using the import library can be done two ways: 1. Use the dll directly by adding the `bin' path to the link line gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx However, as the dll's often have version numbers appended to their names (`cygncurses-5.dll') this will often fail, unless one specifies `-L../bin -lncurses-5' to include the version. Import libs are generally not versioned, and do not have this difficulty. 2. Create a symbolic link from the dll to a file in the `lib' directory according to the above mentioned search pattern. This should be used to avoid unwanted changes in the tools needed for making the app/dll. ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] Then you can link without any make environment changes. gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx This technique also avoids the version number problems, because the following is perfectly legal bin/ cygxxx-5.dll lib/ libxxx.dll.a -> ../bin/cygxxx-5.dll Linking directly to a dll without using an import lib will work even when auto-import features are exercised, and even when `--enable-runtime-pseudo-relocs' is used. Given the improvements in speed and memory usage, one might justifiably wonder why import libraries are used at all. There are three reasons: 1. Until recently, the link-directly-to-dll functionality did _not_ work with auto-imported data. 2. Sometimes it is necessary to include pure static objects within the import library (which otherwise contains only bfd's for indirection symbols that point to the exports of a dll). Again, the import lib for the cygwin kernel makes use of this ability, and it is not possible to do this without an import lib. 3. Symbol aliases can only be resolved using an import lib. This is critical when linking against OS-supplied dll's (eg, the win32 API) in which symbols are usually exported as undecorated aliases of their stdcall-decorated assembly names. So, import libs are not going away. But the ability to replace true import libs with a simple symbolic link to (or a copy of) a dll, in many cases, is a useful addition to the suite of tools binutils makes available to the win32 developer. Given the massive improvements in memory requirements during linking, storage requirements, and linking speed, we expect that many developers will soon begin to use this feature whenever possible. _symbol aliasing_ _adding additional names_ Sometimes, it is useful to export symbols with additional names. A symbol `foo' will be exported as `foo', but it can also be exported as `_foo' by using special directives in the DEF file when creating the dll. This will affect also the optional created import library. Consider the following DEF file: LIBRARY "xyz.dll" BASE=0x61000000 EXPORTS foo _foo = foo The line `_foo = foo' maps the symbol `foo' to `_foo'. Another method for creating a symbol alias is to create it in the source code using the "weak" attribute: void foo () { /* Do something. */; } void _foo () __attribute__ ((weak, alias ("foo"))); See the gcc manual for more information about attributes and weak symbols. _renaming symbols_ Sometimes it is useful to rename exports. For instance, the cygwin kernel does this regularly. A symbol `_foo' can be exported as `foo' but not as `_foo' by using special directives in the DEF file. (This will also affect the import library, if it is created). In the following example: LIBRARY "xyz.dll" BASE=0x61000000 EXPORTS _foo = foo The line `_foo = foo' maps the exported symbol `foo' to `_foo'. Note: using a DEF file disables the default auto-export behavior, unless the `--export-all-symbols' command line option is used. If, however, you are trying to rename symbols, then you should list _all_ desired exports in the DEF file, including the symbols that are not being renamed, and do _not_ use the `--export-all-symbols' option. If you list only the renamed symbols in the DEF file, and use `--export-all-symbols' to handle the other symbols, then the both the new names _and_ the original names for the renamed symbols will be exported. In effect, you'd be aliasing those symbols, not renaming them, which is probably not what you wanted. _weak externals_ The Windows object format, PE, specifies a form of weak symbols called weak externals. When a weak symbol is linked and the symbol is not defined, the weak symbol becomes an alias for some other symbol. There are three variants of weak externals: * Definition is searched for in objects and libraries, historically called lazy externals. * Definition is searched for only in other objects, not in libraries. This form is not presently implemented. * No search; the symbol is an alias. This form is not presently implemented. As a GNU extension, weak symbols that do not specify an alternate symbol are supported. If the symbol is undefined when linking, the symbol uses a default value. _aligned common symbols_ As a GNU extension to the PE file format, it is possible to specify the desired alignment for a common symbol. This information is conveyed from the assembler or compiler to the linker by means of GNU-specific commands carried in the object file's `.drectve' section, which are recognized by `ld' and respected when laying out the common symbols. Native tools will be able to process object files employing this GNU extension, but will fail to respect the alignment instructions, and may issue noisy warnings about unknown linker directives.  File: ld.info, Node: Xtensa, Prev: WIN32, Up: Machine Dependent 4.14 `ld' and Xtensa Processors =============================== The default `ld' behavior for Xtensa processors is to interpret `SECTIONS' commands so that lists of explicitly named sections in a specification with a wildcard file will be interleaved when necessary to keep literal pools within the range of PC-relative load offsets. For example, with the command: SECTIONS { .text : { *(.literal .text) } } `ld' may interleave some of the `.literal' and `.text' sections from different object files to ensure that the literal pools are within the range of PC-relative load offsets. A valid interleaving might place the `.literal' sections from an initial group of files followed by the `.text' sections of that group of files. Then, the `.literal' sections from the rest of the files and the `.text' sections from the rest of the files would follow. Relaxation is enabled by default for the Xtensa version of `ld' and provides two important link-time optimizations. The first optimization is to combine identical literal values to reduce code size. A redundant literal will be removed and all the `L32R' instructions that use it will be changed to reference an identical literal, as long as the location of the replacement literal is within the offset range of all the `L32R' instructions. The second optimization is to remove unnecessary overhead from assembler-generated "longcall" sequences of `L32R'/`CALLXN' when the target functions are within range of direct `CALLN' instructions. For each of these cases where an indirect call sequence can be optimized to a direct call, the linker will change the `CALLXN' instruction to a `CALLN' instruction, remove the `L32R' instruction, and remove the literal referenced by the `L32R' instruction if it is not used for anything else. Removing the `L32R' instruction always reduces code size but can potentially hurt performance by changing the alignment of subsequent branch targets. By default, the linker will always preserve alignments, either by switching some instructions between 24-bit encodings and the equivalent density instructions or by inserting a no-op in place of the `L32R' instruction that was removed. If code size is more important than performance, the `--size-opt' option can be used to prevent the linker from widening density instructions or inserting no-ops, except in a few cases where no-ops are required for correctness. The following Xtensa-specific command-line options can be used to control the linker: `--size-opt' When optimizing indirect calls to direct calls, optimize for code size more than performance. With this option, the linker will not insert no-ops or widen density instructions to preserve branch target alignment. There may still be some cases where no-ops are required to preserve the correctness of the code.  File: ld.info, Node: BFD, Next: Reporting Bugs, Prev: Machine Dependent, Up: Top 5 BFD ***** The linker accesses object and archive files using the BFD libraries. These libraries allow the linker to use the same routines to operate on object files whatever the object file format. A different object file format can be supported simply by creating a new BFD back end and adding it to the library. To conserve runtime memory, however, the linker and associated tools are usually configured to support only a subset of the object file formats available. You can use `objdump -i' (*note objdump: (binutils.info)objdump.) to list all the formats available for your configuration. As with most implementations, BFD is a compromise between several conflicting requirements. The major factor influencing BFD design was efficiency: any time used converting between formats is time which would not have been spent had BFD not been involved. This is partly offset by abstraction payback; since BFD simplifies applications and back ends, more time and care may be spent optimizing algorithms for a greater speed. One minor artifact of the BFD solution which you should bear in mind is the potential for information loss. There are two places where useful information can be lost using the BFD mechanism: during conversion and during output. *Note BFD information loss::. * Menu: * BFD outline:: How it works: an outline of BFD  File: ld.info, Node: BFD outline, Up: BFD 5.1 How It Works: An Outline of BFD =================================== When an object file is opened, BFD subroutines automatically determine the format of the input object file. They then build a descriptor in memory with pointers to routines that will be used to access elements of the object file's data structures. As different information from the object files is required, BFD reads from different sections of the file and processes them. For example, a very common operation for the linker is processing symbol tables. Each BFD back end provides a routine for converting between the object file's representation of symbols and an internal canonical format. When the linker asks for the symbol table of an object file, it calls through a memory pointer to the routine from the relevant BFD back end which reads and converts the table into a canonical form. The linker then operates upon the canonical form. When the link is finished and the linker writes the output file's symbol table, another BFD back end routine is called to take the newly created symbol table and convert it into the chosen output format. * Menu: * BFD information loss:: Information Loss * Canonical format:: The BFD canonical object-file format  File: ld.info, Node: BFD information loss, Next: Canonical format, Up: BFD outline 5.1.1 Information Loss ---------------------- _Information can be lost during output._ The output formats supported by BFD do not provide identical facilities, and information which can be described in one form has nowhere to go in another format. One example of this is alignment information in `b.out'. There is nowhere in an `a.out' format file to store alignment information on the contained data, so when a file is linked from `b.out' and an `a.out' image is produced, alignment information will not propagate to the output file. (The linker will still use the alignment information internally, so the link is performed correctly). Another example is COFF section names. COFF files may contain an unlimited number of sections, each one with a textual section name. If the target of the link is a format which does not have many sections (e.g., `a.out') or has sections without names (e.g., the Oasys format), the link cannot be done simply. You can circumvent this problem by describing the desired input-to-output section mapping with the linker command language. _Information can be lost during canonicalization._ The BFD internal canonical form of the external formats is not exhaustive; there are structures in input formats for which there is no direct representation internally. This means that the BFD back ends cannot maintain all possible data richness through the transformation between external to internal and back to external formats. This limitation is only a problem when an application reads one format and writes another. Each BFD back end is responsible for maintaining as much data as possible, and the internal BFD canonical form has structures which are opaque to the BFD core, and exported only to the back ends. When a file is read in one format, the canonical form is generated for BFD and the application. At the same time, the back end saves away any information which may otherwise be lost. If the data is then written back in the same format, the back end routine will be able to use the canonical form provided by the BFD core as well as the information it prepared earlier. Since there is a great deal of commonality between back ends, there is no information lost when linking or copying big endian COFF to little endian COFF, or `a.out' to `b.out'. When a mixture of formats is linked, the information is only lost from the files whose format differs from the destination.  File: ld.info, Node: Canonical format, Prev: BFD information loss, Up: BFD outline 5.1.2 The BFD canonical object-file format ------------------------------------------ The greatest potential for loss of information occurs when there is the least overlap between the information provided by the source format, that stored by the canonical format, and that needed by the destination format. A brief description of the canonical form may help you understand which kinds of data you can count on preserving across conversions. _files_ Information stored on a per-file basis includes target machine architecture, particular implementation format type, a demand pageable bit, and a write protected bit. Information like Unix magic numbers is not stored here--only the magic numbers' meaning, so a `ZMAGIC' file would have both the demand pageable bit and the write protected text bit set. The byte order of the target is stored on a per-file basis, so that big- and little-endian object files may be used with one another. _sections_ Each section in the input file contains the name of the section, the section's original address in the object file, size and alignment information, various flags, and pointers into other BFD data structures. _symbols_ Each symbol contains a pointer to the information for the object file which originally defined it, its name, its value, and various flag bits. When a BFD back end reads in a symbol table, it relocates all symbols to make them relative to the base of the section where they were defined. Doing this ensures that each symbol points to its containing section. Each symbol also has a varying amount of hidden private data for the BFD back end. Since the symbol points to the original file, the private data format for that symbol is accessible. `ld' can operate on a collection of symbols of wildly different formats without problems. Normal global and simple local symbols are maintained on output, so an output file (no matter its format) will retain symbols pointing to functions and to global, static, and common variables. Some symbol information is not worth retaining; in `a.out', type information is stored in the symbol table as long symbol names. This information would be useless to most COFF debuggers; the linker has command line switches to allow users to throw it away. There is one word of type information within the symbol, so if the format supports symbol type information within symbols (for example, COFF, IEEE, Oasys) and the type is simple enough to fit within one word (nearly everything but aggregates), the information will be preserved. _relocation level_ Each canonical BFD relocation record contains a pointer to the symbol to relocate to, the offset of the data to relocate, the section the data is in, and a pointer to a relocation type descriptor. Relocation is performed by passing messages through the relocation type descriptor and the symbol pointer. Therefore, relocations can be performed on output data using a relocation method that is only available in one of the input formats. For instance, Oasys provides a byte relocation format. A relocation record requesting this relocation type would point indirectly to a routine to perform this, so the relocation may be performed on a byte being written to a 68k COFF file, even though 68k COFF has no such relocation type. _line numbers_ Object formats can contain, for debugging purposes, some form of mapping between symbols, source line numbers, and addresses in the output file. These addresses have to be relocated along with the symbol information. Each symbol with an associated list of line number records points to the first record of the list. The head of a line number list consists of a pointer to the symbol, which allows finding out the address of the function whose line number is being described. The rest of the list is made up of pairs: offsets into the section and line numbers. Any format which can simply derive this information can pass it successfully between formats (COFF, IEEE and Oasys).  File: ld.info, Node: Reporting Bugs, Next: MRI, Prev: BFD, Up: Top 6 Reporting Bugs **************** Your bug reports play an essential role in making `ld' reliable. Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the principal function of a bug report is to help the entire community by making the next version of `ld' work better. Bug reports are your contribution to the maintenance of `ld'. In order for a bug report to serve its purpose, you must include the information that enables us to fix the bug. * Menu: * Bug Criteria:: Have you found a bug? * Bug Reporting:: How to report bugs  File: ld.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs 6.1 Have You Found a Bug? ========================= If you are not sure whether you have found a bug, here are some guidelines: * If the linker gets a fatal signal, for any input whatever, that is a `ld' bug. Reliable linkers never crash. * If `ld' produces an error message for valid input, that is a bug. * If `ld' does not produce an error message for invalid input, that may be a bug. In the general case, the linker can not verify that object files are correct. * If you are an experienced user of linkers, your suggestions for improvement of `ld' are welcome in any case.  File: ld.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs 6.2 How to Report Bugs ====================== A number of companies and individuals offer support for GNU products. If you obtained `ld' from a support organization, we recommend you contact that organization first. You can find contact information for many support companies and individuals in the file `etc/SERVICE' in the GNU Emacs distribution. Otherwise, send bug reports for `ld' to `http://www.sourceware.org/bugzilla/'. The fundamental principle of reporting bugs usefully is this: *report all the facts*. If you are not sure whether to state a fact or leave it out, state it! Often people omit facts because they think they know what causes the problem and assume that some details do not matter. Thus, you might assume that the name of a symbol you use in an example does not matter. Well, probably it does not, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that name is stored in memory; perhaps, if the name were different, the contents of that location would fool the linker into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful. Keep in mind that the purpose of a bug report is to enable us to fix the bug if it is new to us. Therefore, always write your bug reports on the assumption that the bug has not been reported previously. Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" This cannot help us fix a bug, so it is basically useless. We respond by asking for enough details to enable us to investigate. You might as well expedite matters by sending them to begin with. To enable us to fix the bug, you should include all these things: * The version of `ld'. `ld' announces it if you start it with the `--version' argument. Without this, we will not know whether there is any point in looking for the bug in the current version of `ld'. * Any patches you may have applied to the `ld' source, including any patches made to the `BFD' library. * The type of machine you are using, and the operating system name and version number. * What compiler (and its version) was used to compile `ld'--e.g. "`gcc-2.7'". * The command arguments you gave the linker to link your example and observe the bug. To guarantee you will not omit something important, list them all. A copy of the Makefile (or the output from make) is sufficient. If we were to try to guess the arguments, we would probably guess wrong and then we might not encounter the bug. * A complete input file, or set of input files, that will reproduce the bug. It is generally most helpful to send the actual object files provided that they are reasonably small. Say no more than 10K. For bigger files you can either make them available by FTP or HTTP or else state that you are willing to send the object file(s) to whomever requests them. (Note - your email will be going to a mailing list, so we do not want to clog it up with large attachments). But small attachments are best. If the source files were assembled using `gas' or compiled using `gcc', then it may be OK to send the source files rather than the object files. In this case, be sure to say exactly what version of `gas' or `gcc' was used to produce the object files. Also say how `gas' or `gcc' were configured. * A description of what behavior you observe that you believe is incorrect. For example, "It gets a fatal signal." Of course, if the bug is that `ld' gets a fatal signal, then we will certainly notice it. But if the bug is incorrect output, we might not notice unless it is glaringly wrong. You might as well not give us a chance to make a mistake. Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of `ld' is out of sync, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations. * If you wish to suggest changes to the `ld' source, send us context diffs, as generated by `diff' with the `-u', `-c', or `-p' option. Always send diffs from the old file to the new file. If you even discuss something in the `ld' source, refer to it by context, not by line number. The line numbers in our development sources will not match those in your sources. Your line numbers would convey no useful information to us. Here are some things that are not necessary: * A description of the envelope of the bug. Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it. This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. We recommend that you save your time for something else. Of course, if you can find a simpler example to report _instead_ of the original one, that is a convenience for us. Errors in the output will be easier to spot, running under the debugger will take '()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ less time, and so on. However, simplification is not vital; if you do not want to do this, report the bug anyway and send us the entire test case you used. * A patch for the bug. A patch for the bug does help us if it is a good one. But do not omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. Sometimes with a program as complicated as `ld' it is very hard to construct an example that will make the program follow a certain path through the code. If you do not send us the example, we will not be able to construct one, so we will not be able to verify that the bug is fixed. And if we cannot understand what bug you are trying to fix, or why your patch should be an improvement, we will not install it. A test case will help us to understand. * A guess about what the bug is or what it depends on. Such guesses are usually wrong. Even we cannot guess right about such things without first using the debugger to find the facts.  File: ld.info, Node: MRI, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top Appendix A MRI Compatible Script Files ************************************** To aid users making the transition to GNU `ld' from the MRI linker, `ld' can use MRI compatible linker scripts as an alternative to the more general-purpose linker scripting language described in *Note Scripts::. MRI compatible linker scripts have a much simpler command set than the scripting language otherwise used with `ld'. GNU `ld' supports the most commonly used MRI linker commands; these commands are described here. In general, MRI scripts aren't of much use with the `a.out' object file format, since it only has three sections and MRI scripts lack some features to make use of them. You can specify a file containing an MRI-compatible script using the `-c' command-line option. Each command in an MRI-compatible script occupies its own line; each command line starts with the keyword that identifies the command (though blank lines are also allowed for punctuation). If a line of an MRI-compatible script begins with an unrecognized keyword, `ld' issues a warning message, but continues processing the script. Lines beginning with `*' are comments. You can write these commands using all upper-case letters, or all lower case; for example, `chip' is the same as `CHIP'. The following list shows only the upper-case form of each command. `ABSOLUTE SECNAME' `ABSOLUTE SECNAME, SECNAME, ... SECNAME' Normally, `ld' includes in the output file all sections from all the input files. However, in an MRI-compatible script, you can use the `ABSOLUTE' command to restrict the sections that will be present in your output program. If the `ABSOLUTE' command is used at all in a script, then only the sections named explicitly in `ABSOLUTE' commands will appear in the linker output. You can still use other input sections (whatever you select on the command line, or using `LOAD') to resolve addresses in the output file. `ALIAS OUT-SECNAME, IN-SECNAME' Use this command to place the data from input section IN-SECNAME in a section called OUT-SECNAME in the linker output file. IN-SECNAME may be an integer. `ALIGN SECNAME = EXPRESSION' Align the section called SECNAME to EXPRESSION. The EXPRESSION should be a power of two. `BASE EXPRESSION' Use the value of EXPRESSION as the lowest address (other than absolute addresses) in the output file. `CHIP EXPRESSION' `CHIP EXPRESSION, EXPRESSION' This command does nothing; it is accepted only for compatibility. `END' This command does nothing whatever; it's only accepted for compatibility. `FORMAT OUTPUT-FORMAT' Similar to the `OUTPUT_FORMAT' command in the more general linker language, but restricted to one of these output formats: 1. S-records, if OUTPUT-FORMAT is `S' 2. IEEE, if OUTPUT-FORMAT is `IEEE' 3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is `COFF' `LIST ANYTHING...' Print (to the standard output file) a link map, as produced by the `ld' command-line option `-M'. The keyword `LIST' may be followed by anything on the same line, with no change in its effect. `LOAD FILENAME' `LOAD FILENAME, FILENAME, ... FILENAME' Include one or more object file FILENAME in the link; this has the same effect as specifying FILENAME directly on the `ld' command line. `NAME OUTPUT-NAME' OUTPUT-NAME is the name for the program produced by `ld'; the MRI-compatible command `NAME' is equivalent to the command-line option `-o' or the general script language command `OUTPUT'. `ORDER SECNAME, SECNAME, ... SECNAME' `ORDER SECNAME SECNAME SECNAME' Normally, `ld' orders the sections in its output file in the order in which they first appear in the input files. In an MRI-compatible script, you can override this ordering with the `ORDER' command. The sections you list with `ORDER' will appear first in your output file, in the order specified. `PUBLIC NAME=EXPRESSION' `PUBLIC NAME,EXPRESSION' `PUBLIC NAME EXPRESSION' Supply a value (EXPRESSION) for external symbol NAME used in the linker input files. `SECT SECNAME, EXPRESSION' `SECT SECNAME=EXPRESSION' `SECT SECNAME EXPRESSION' You can use any of these three forms of the `SECT' command to specify the start address (EXPRESSION) for section SECNAME. If you have more than one `SECT' statement for the same SECNAME, only the _first_ sets the start address.  File: ld.info, Node: GNU Free Documentation License, Next: LD Index, Prev: MRI, Up: Top Appendix B GNU Free Documentation License ***************************************** Version 1.3, 3 November 2008 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. `http://fsf.org/' Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. The "publisher" means any person or entity that distributes copies of the Document to the public. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the t