diff options
| author | Paul Brook <paul@codesourcery.com> | 2005-04-29 15:57:20 +0000 |
|---|---|---|
| committer | Paul Brook <paul@codesourcery.com> | 2005-04-29 15:57:20 +0000 |
| commit | 11f31bb97faf2e6f8c3b8cc98c3e44779acd17cc (patch) | |
| tree | 5d823629d6dc3f8606dbcb0e1f9984fef4d2f9a1 | |
| parent | dfd3d2dacc181d6c13c4689cc91b1fc82d3f56a6 (diff) | |
| download | gdb-11f31bb97faf2e6f8c3b8cc98c3e44779acd17cc.tar.gz | |
Remove generated documentation and translation files from CVS.
| -rw-r--r-- | bfd/doc/bfd.info | 89 | ||||
| -rw-r--r-- | bfd/doc/bfd.info-1 | 8006 | ||||
| -rw-r--r-- | bfd/doc/bfd.info-2 | 1702 | ||||
| -rw-r--r-- | bfd/po/da.gmo | bin | 60556 -> 0 bytes | |||
| -rw-r--r-- | bfd/po/es.gmo | bin | 84719 -> 0 bytes | |||
| -rw-r--r-- | bfd/po/fr.gmo | bin | 71749 -> 0 bytes | |||
| -rw-r--r-- | bfd/po/ja.gmo | bin | 38616 -> 0 bytes | |||
| -rw-r--r-- | bfd/po/ro.gmo | bin | 69038 -> 0 bytes | |||
| -rw-r--r-- | bfd/po/sv.gmo | bin | 67266 -> 0 bytes | |||
| -rw-r--r-- | bfd/po/tr.gmo | bin | 69529 -> 0 bytes | |||
| -rw-r--r-- | bfd/po/zh_CN.gmo | bin | 28132 -> 0 bytes | |||
| -rw-r--r-- | etc/configure.info | 2771 | ||||
| -rw-r--r-- | etc/standards.info | 4930 | ||||
| -rw-r--r-- | opcodes/po/da.gmo | bin | 8332 -> 0 bytes | |||
| -rw-r--r-- | opcodes/po/de.gmo | bin | 16919 -> 0 bytes | |||
| -rw-r--r-- | opcodes/po/es.gmo | bin | 16747 -> 0 bytes | |||
| -rw-r--r-- | opcodes/po/fr.gmo | bin | 16408 -> 0 bytes | |||
| -rw-r--r-- | opcodes/po/id.gmo | bin | 8307 -> 0 bytes | |||
| -rw-r--r-- | opcodes/po/nl.gmo | bin | 16097 -> 0 bytes | |||
| -rw-r--r-- | opcodes/po/pt_BR.gmo | bin | 8467 -> 0 bytes | |||
| -rw-r--r-- | opcodes/po/ro.gmo | bin | 15986 -> 0 bytes | |||
| -rw-r--r-- | opcodes/po/sv.gmo | bin | 15872 -> 0 bytes | |||
| -rw-r--r-- | opcodes/po/tr.gmo | bin | 16094 -> 0 bytes |
23 files changed, 0 insertions, 17498 deletions
diff --git a/bfd/doc/bfd.info b/bfd/doc/bfd.info deleted file mode 100644 index 08c14140b08..00000000000 --- a/bfd/doc/bfd.info +++ /dev/null @@ -1,89 +0,0 @@ -This is ../.././bfd/doc/bfd.info, produced by makeinfo version 4.7 from -../.././bfd/doc/bfd.texinfo. - -START-INFO-DIR-ENTRY -* Bfd: (bfd). The Binary File Descriptor library. -END-INFO-DIR-ENTRY - - This file documents the BFD library. - - Copyright (C) 1991, 2000, 2001, 2003 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with no Invariant Sections, with no Front-Cover Texts, and with no - Back-Cover Texts. A copy of the license is included in the -section entitled "GNU Free Documentation License". - - -Indirect: -bfd.info-1: 724 -bfd.info-2: 298309 - -Tag Table: -(Indirect) -Node: Top724 -Node: Overview1056 -Node: History2107 -Node: How It Works3053 -Node: What BFD Version 2 Can Do4595 -Node: BFD information loss5910 -Node: Canonical format8442 -Node: BFD front end12814 -Node: Memory Usage38041 -Node: Initialization39269 -Node: Sections39665 -Node: Section Input40148 -Node: Section Output41513 -Node: typedef asection43999 -Node: section prototypes61598 -Node: Symbols70581 -Node: Reading Symbols72176 -Node: Writing Symbols73283 -Node: Mini Symbols74992 -Node: typedef asymbol75966 -Node: symbol handling functions80884 -Node: Archives86226 -Node: Formats89903 -Node: Relocations92794 -Node: typedef arelent93521 -Node: howto manager109239 -Node: Core Files165412 -Node: Targets166491 -Node: bfd_target168461 -Node: Architectures187781 -Node: Opening and Closing208078 -Node: Internal217791 -Node: File Caching224063 -Node: Linker Functions227370 -Node: Creating a Linker Hash Table229043 -Node: Adding Symbols to the Hash Table230781 -Node: Differing file formats231681 -Node: Adding symbols from an object file233429 -Node: Adding symbols from an archive235580 -Node: Performing the Final Link237994 -Node: Information provided by the linker239236 -Node: Relocating the section contents240386 -Node: Writing the symbol table242137 -Node: Hash Tables245130 -Node: Creating and Freeing a Hash Table246328 -Node: Looking Up or Entering a String247578 -Node: Traversing a Hash Table248831 -Node: Deriving a New Hash Table Type249620 -Node: Define the Derived Structures250686 -Node: Write the Derived Creation Routine251767 -Node: Write Other Derived Routines254461 -Node: BFD back ends255776 -Node: What to Put Where256046 -Node: aout256184 -Node: coff262435 -Node: elf287111 -Node: mmo287965 -Node: File layout288893 -Node: Symbol-table294540 -Node: mmo section mapping298309 -Node: GNU Free Documentation License301961 -Node: Index321681 - -End Tag Table diff --git a/bfd/doc/bfd.info-1 b/bfd/doc/bfd.info-1 deleted file mode 100644 index d6e8ba0f70d..00000000000 --- a/bfd/doc/bfd.info-1 +++ /dev/null @@ -1,8006 +0,0 @@ -This is ../.././bfd/doc/bfd.info, produced by makeinfo version 4.7 from -../.././bfd/doc/bfd.texinfo. - -START-INFO-DIR-ENTRY -* Bfd: (bfd). The Binary File Descriptor library. -END-INFO-DIR-ENTRY - - This file documents the BFD library. - - Copyright (C) 1991, 2000, 2001, 2003 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with no Invariant Sections, with no Front-Cover Texts, and with no - Back-Cover Texts. A copy of the license is included in the -section entitled "GNU Free Documentation License". - - -File: bfd.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) - - This file documents the binary file descriptor library libbfd. - -* Menu: - -* Overview:: Overview of BFD -* BFD front end:: BFD front end -* BFD back ends:: BFD back ends -* GNU Free Documentation License:: GNU Free Documentation License -* Index:: Index - - -File: bfd.info, Node: Overview, Next: BFD front end, Prev: Top, Up: Top - -1 Introduction -************** - -BFD is a package which allows applications to use the same routines to -operate on object files whatever the object file format. A new object -file format can be supported simply by creating a new BFD back end and -adding it to the library. - - BFD is split into two parts: the front end, and the back ends (one -for each object file format). - * The front end of BFD provides the interface to the user. It manages - memory and various canonical data structures. The front end also - decides which back end to use and when to call back end routines. - - * The back ends provide BFD its view of the real world. Each back - end provides a set of calls which the BFD front end can use to - maintain its canonical form. The back ends also may keep around - information for their own use, for greater efficiency. - -* Menu: - -* History:: History -* How It Works:: How It Works -* What BFD Version 2 Can Do:: What BFD Version 2 Can Do - - -File: bfd.info, Node: History, Next: How It Works, Prev: Overview, Up: Overview - -1.1 History -=========== - -One spur behind BFD was the desire, on the part of the GNU 960 team at -Intel Oregon, for interoperability of applications on their COFF and -b.out file formats. Cygnus was providing GNU support for the team, and -was contracted to provide the required functionality. - - The name came from a conversation David Wallace was having with -Richard Stallman about the library: RMS said that it would be quite -hard--David said "BFD". Stallman was right, but the name stuck. - - At the same time, Ready Systems wanted much the same thing, but for -different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k -coff. - - BFD was first implemented by members of Cygnus Support; Steve -Chamberlain (`sac@cygnus.com'), John Gilmore (`gnu@cygnus.com'), K. -Richard Pixley (`rich@cygnus.com') and David Henkel-Wallace -(`gumby@cygnus.com'). - - -File: bfd.info, Node: How It Works, Next: What BFD Version 2 Can Do, Prev: History, Up: Overview - -1.2 How To Use BFD -================== - -To use the library, include `bfd.h' and link with `libbfd.a'. - - BFD provides a common interface to the parts of an object file for a -calling application. - - When an application sucessfully opens a target file (object, -archive, or whatever), a pointer to an internal structure is returned. -This pointer points to a structure called `bfd', described in `bfd.h'. -Our convention is to call this pointer a BFD, and instances of it -within code `abfd'. All operations on the target object file are -applied as methods to the BFD. The mapping is defined within `bfd.h' -in a set of macros, all beginning with `bfd_' to reduce namespace -pollution. - - For example, this sequence does what you would probably expect: -return the number of sections in an object file attached to a BFD -`abfd'. - - #include "bfd.h" - - unsigned int number_of_sections (abfd) - bfd *abfd; - { - return bfd_count_sections (abfd); - } - - The abstraction used within BFD is that an object file has: - - * a header, - - * a number of sections containing raw data (*note Sections::), - - * a set of relocations (*note Relocations::), and - - * some symbol information (*note Symbols::). - Also, BFDs opened for archives have the additional attribute of an -index and contain subordinate BFDs. This approach is fine for a.out and -coff, but loses efficiency when applied to formats such as S-records and -IEEE-695. - - -File: bfd.info, Node: What BFD Version 2 Can Do, Prev: How It Works, Up: Overview - -1.3 What BFD Version 2 Can Do -============================= - -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: bfd.info, Node: BFD information loss, Next: Canonical format, Up: What BFD Version 2 Can Do - -1.3.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: bfd.info, Node: Canonical format, Prev: BFD information loss, Up: What BFD Version 2 Can Do - -1.3.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: bfd.info, Node: BFD front end, Next: BFD back ends, Prev: Overview, Up: Top - -2 BFD Front End -*************** - -2.1 `typedef bfd' -================= - -A BFD has type `bfd'; objects of this type are the cornerstone of any -application using BFD. Using BFD consists of making references though -the BFD and to data in the BFD. - - Here is the structure that defines the type `bfd'. It contains the -major data about the file and pointers to the rest of the data. - - - struct bfd - { - /* A unique identifier of the BFD */ - unsigned int id; - - /* The filename the application opened the BFD with. */ - const char *filename; - - /* A pointer to the target jump table. */ - const struct bfd_target *xvec; - - /* The IOSTREAM, and corresponding IO vector that provide access - to the file backing the BFD. */ - void *iostream; - const struct bfd_iovec *iovec; - - /* Is the file descriptor being cached? That is, can it be closed as - needed, and re-opened when accessed later? */ - bfd_boolean cacheable; - - /* Marks whether there was a default target specified when the - BFD was opened. This is used to select which matching algorithm - to use to choose the back end. */ - bfd_boolean target_defaulted; - - /* The caching routines use these to maintain a - least-recently-used list of BFDs. */ - struct bfd *lru_prev, *lru_next; - - /* When a file is closed by the caching routines, BFD retains - state information on the file here... */ - ufile_ptr where; - - /* ... and here: (``once'' means at least once). */ - bfd_boolean opened_once; - - /* Set if we have a locally maintained mtime value, rather than - getting it from the file each time. */ - bfd_boolean mtime_set; - - /* File modified time, if mtime_set is TRUE. */ - long mtime; - - /* Reserved for an unimplemented file locking extension. */ - int ifd; - - /* The format which belongs to the BFD. (object, core, etc.) */ - bfd_format format; - - /* The direction with which the BFD was opened. */ - enum bfd_direction - { - no_direction = 0, - read_direction = 1, - write_direction = 2, - both_direction = 3 - } - direction; - - /* Format_specific flags. */ - flagword flags; - - /* Currently my_archive is tested before adding origin to - anything. I believe that this can become always an add of - origin, with origin set to 0 for non archive files. */ - ufile_ptr origin; - - /* Remember when output has begun, to stop strange things - from happening. */ - bfd_boolean output_has_begun; - - /* A hash table for section names. */ - struct bfd_hash_table section_htab; - - /* Pointer to linked list of sections. */ - struct bfd_section *sections; - - /* The place where we add to the section list. */ - struct bfd_section **section_tail; - - /* The number of sections. */ - unsigned int section_count; - - /* Stuff only useful for object files: - The start address. */ - bfd_vma start_address; - - /* Used for input and output. */ - unsigned int symcount; - - /* Symbol table for output BFD (with symcount entries). */ - struct bfd_symbol **outsymbols; - - /* Used for slurped dynamic symbol tables. */ - unsigned int dynsymcount; - - /* Pointer to structure which contains architecture information. */ - const struct bfd_arch_info *arch_info; - - /* Flag set if symbols from this BFD should not be exported. */ - bfd_boolean no_export; - - /* Stuff only useful for archives. */ - void *arelt_data; - struct bfd *my_archive; /* The containing archive BFD. */ - struct bfd *next; /* The next BFD in the archive. */ - struct bfd *archive_head; /* The first BFD in the archive. */ - bfd_boolean has_armap; - - /* A chain of BFD structures involved in a link. */ - struct bfd *link_next; - - /* A field used by _bfd_generic_link_add_archive_symbols. This will - be used only for archive elements. */ - int archive_pass; - - /* Used by the back end to hold private data. */ - union - { - struct aout_data_struct *aout_data; - struct artdata *aout_ar_data; - struct _oasys_data *oasys_obj_data; - struct _oasys_ar_data *oasys_ar_data; - struct coff_tdata *coff_obj_data; - struct pe_tdata *pe_obj_data; - struct xcoff_tdata *xcoff_obj_data; - struct ecoff_tdata *ecoff_obj_data; - struct ieee_data_struct *ieee_data; - struct ieee_ar_data_struct *ieee_ar_data; - struct srec_data_struct *srec_data; - struct ihex_data_struct *ihex_data; - struct tekhex_data_struct *tekhex_data; - struct elf_obj_tdata *elf_obj_data; - struct nlm_obj_tdata *nlm_obj_data; - struct bout_data_struct *bout_data; - struct mmo_data_struct *mmo_data; - struct sun_core_struct *sun_core_data; - struct sco5_core_struct *sco5_core_data; - struct trad_core_struct *trad_core_data; - struct som_data_struct *som_data; - struct hpux_core_struct *hpux_core_data; - struct hppabsd_core_struct *hppabsd_core_data; - struct sgi_core_struct *sgi_core_data; - struct lynx_core_struct *lynx_core_data; - struct osf_core_struct *osf_core_data; - struct cisco_core_struct *cisco_core_data; - struct versados_data_struct *versados_data; - struct netbsd_core_struct *netbsd_core_data; - struct mach_o_data_struct *mach_o_data; - struct mach_o_fat_data_struct *mach_o_fat_data; - struct bfd_pef_data_struct *pef_data; - struct bfd_pef_xlib_data_struct *pef_xlib_data; - struct bfd_sym_data_struct *sym_data; - void *any; - } - tdata; - - /* Used by the application to hold private data. */ - void *usrdata; - - /* Where all the allocated stuff under this BFD goes. This is a - struct objalloc *, but we use void * to avoid requiring the inclusion - of objalloc.h. */ - void *memory; - }; - -2.2 Error reporting -=================== - -Most BFD functions return nonzero on success (check their individual -documentation for precise semantics). On an error, they call -`bfd_set_error' to set an error condition that callers can check by -calling `bfd_get_error'. If that returns `bfd_error_system_call', then -check `errno'. - - The easiest way to report a BFD error to the user is to use -`bfd_perror'. - -2.2.1 Type `bfd_error_type' ---------------------------- - -The values returned by `bfd_get_error' are defined by the enumerated -type `bfd_error_type'. - - - typedef enum bfd_error - { - bfd_error_no_error = 0, - bfd_error_system_call, - bfd_error_invalid_target, - bfd_error_wrong_format, - bfd_error_wrong_object_format, - bfd_error_invalid_operation, - bfd_error_no_memory, - bfd_error_no_symbols, - bfd_error_no_armap, - bfd_error_no_more_archived_files, - bfd_error_malformed_archive, - bfd_error_file_not_recognized, - bfd_error_file_ambiguously_recognized, - bfd_error_no_contents, - bfd_error_nonrepresentable_section, - bfd_error_no_debug_section, - bfd_error_bad_value, - bfd_error_file_truncated, - bfd_error_file_too_big, - bfd_error_invalid_error_code - } - bfd_error_type; - -2.2.1.1 `bfd_get_error' -....................... - -*Synopsis* - bfd_error_type bfd_get_error (void); - *Description* -Return the current BFD error condition. - -2.2.1.2 `bfd_set_error' -....................... - -*Synopsis* - void bfd_set_error (bfd_error_type error_tag); - *Description* -Set the BFD error condition to be ERROR_TAG. - -2.2.1.3 `bfd_errmsg' -.................... - -*Synopsis* - const char *bfd_errmsg (bfd_error_type error_tag); - *Description* -Return a string describing the error ERROR_TAG, or the system error if -ERROR_TAG is `bfd_error_system_call'. - -2.2.1.4 `bfd_perror' -.................... - -*Synopsis* - void bfd_perror (const char *message); - *Description* -Print to the standard error stream a string describing the last BFD -error that occurred, or the last system error if the last BFD error was -a system call failure. If MESSAGE is non-NULL and non-empty, the error -string printed is preceded by MESSAGE, a colon, and a space. It is -followed by a newline. - -2.2.2 BFD error handler ------------------------ - -Some BFD functions want to print messages describing the problem. They -call a BFD error handler function. This function may be overridden by -the program. - - The BFD error handler acts like printf. - - - typedef void (*bfd_error_handler_type) (const char *, ...); - -2.2.2.1 `bfd_set_error_handler' -............................... - -*Synopsis* - bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type); - *Description* -Set the BFD error handler function. Returns the previous function. - -2.2.2.2 `bfd_set_error_program_name' -.................................... - -*Synopsis* - void bfd_set_error_program_name (const char *); - *Description* -Set the program name to use when printing a BFD error. This is printed -before the error message followed by a colon and space. The string -must not be changed after it is passed to this function. - -2.2.2.3 `bfd_get_error_handler' -............................... - -*Synopsis* - bfd_error_handler_type bfd_get_error_handler (void); - *Description* -Return the BFD error handler function. - -2.3 Symbols -=========== - -2.3.0.1 `bfd_get_reloc_upper_bound' -................................... - -*Synopsis* - long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect); - *Description* -Return the number of bytes required to store the relocation information -associated with section SECT attached to bfd ABFD. If an error occurs, -return -1. - -2.3.0.2 `bfd_canonicalize_reloc' -................................ - -*Synopsis* - long bfd_canonicalize_reloc - (bfd *abfd, asection *sec, arelent **loc, asymbol **syms); - *Description* -Call the back end associated with the open BFD ABFD and translate the -external form of the relocation information attached to SEC into the -internal canonical form. Place the table into memory at LOC, which has -been preallocated, usually by a call to `bfd_get_reloc_upper_bound'. -Returns the number of relocs, or -1 on error. - - The SYMS table is also needed for horrible internal magic reasons. - -2.3.0.3 `bfd_set_reloc' -....................... - -*Synopsis* - void bfd_set_reloc - (bfd *abfd, asection *sec, arelent **rel, unsigned int count); - *Description* -Set the relocation pointer and count within section SEC to the values -REL and COUNT. The argument ABFD is ignored. - -2.3.0.4 `bfd_set_file_flags' -............................ - -*Synopsis* - bfd_boolean bfd_set_file_flags (bfd *abfd, flagword flags); - *Description* -Set the flag word in the BFD ABFD to the value FLAGS. - - Possible errors are: - * `bfd_error_wrong_format' - The target bfd was not of object format. - - * `bfd_error_invalid_operation' - The target bfd was open for - reading. - - * `bfd_error_invalid_operation' - The flag word contained a bit - which was not applicable to the type of file. E.g., an attempt - was made to set the `D_PAGED' bit on a BFD format which does not - support demand paging. - -2.3.0.5 `bfd_get_arch_size' -........................... - -*Synopsis* - int bfd_get_arch_size (bfd *abfd); - *Description* -Returns the architecture address size, in bits, as determined by the -object file's format. For ELF, this information is included in the -header. - - *Returns* -Returns the arch size in bits if known, `-1' otherwise. - -2.3.0.6 `bfd_get_sign_extend_vma' -................................. - -*Synopsis* - int bfd_get_sign_extend_vma (bfd *abfd); - *Description* -Indicates if the target architecture "naturally" sign extends an -address. Some architectures implicitly sign extend address values when -they are converted to types larger than the size of an address. For -instance, bfd_get_start_address() will return an address sign extended -to fill a bfd_vma when this is the case. - - *Returns* -Returns `1' if the target architecture is known to sign extend -addresses, `0' if the target architecture is known to not sign extend -addresses, and `-1' otherwise. - -2.3.0.7 `bfd_set_start_address' -............................... - -*Synopsis* - bfd_boolean bfd_set_start_address (bfd *abfd, bfd_vma vma); - *Description* -Make VMA the entry point of output BFD ABFD. - - *Returns* -Returns `TRUE' on success, `FALSE' otherwise. - -2.3.0.8 `bfd_get_gp_size' -......................... - -*Synopsis* - unsigned int bfd_get_gp_size (bfd *abfd); - *Description* -Return the maximum size of objects to be optimized using the GP -register under MIPS ECOFF. This is typically set by the `-G' argument -to the compiler, assembler or linker. - -2.3.0.9 `bfd_set_gp_size' -......................... - -*Synopsis* - void bfd_set_gp_size (bfd *abfd, unsigned int i); - *Description* -Set the maximum size of objects to be optimized using the GP register -under ECOFF or MIPS ELF. This is typically set by the `-G' argument to -the compiler, assembler or linker. - -2.3.0.10 `bfd_scan_vma' -....................... - -*Synopsis* - bfd_vma bfd_scan_vma (const char *string, const char **end, int base); - *Description* -Convert, like `strtoul', a numerical expression STRING into a `bfd_vma' -integer, and return that integer. (Though without as many bells and -whistles as `strtoul'.) The expression is assumed to be unsigned -(i.e., positive). If given a BASE, it is used as the base for -conversion. A base of 0 causes the function to interpret the string in -hex if a leading "0x" or "0X" is found, otherwise in octal if a leading -zero is found, otherwise in decimal. - - If the value would overflow, the maximum `bfd_vma' value is returned. - -2.3.0.11 `bfd_copy_private_header_data' -....................................... - -*Synopsis* - bfd_boolean bfd_copy_private_header_data (bfd *ibfd, bfd *obfd); - *Description* -Copy private BFD header information from the BFD IBFD to the the BFD -OBFD. This copies information that may require sections to exist, but -does not require symbol tables. Return `true' on success, `false' on -error. Possible error returns are: - - * `bfd_error_no_memory' - Not enough memory exists to create private - data for OBFD. - - #define bfd_copy_private_header_data(ibfd, obfd) \ - BFD_SEND (obfd, _bfd_copy_private_header_data, \ - (ibfd, obfd)) - -2.3.0.12 `bfd_copy_private_bfd_data' -.................................... - -*Synopsis* - bfd_boolean bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd); - *Description* -Copy private BFD information from the BFD IBFD to the the BFD OBFD. -Return `TRUE' on success, `FALSE' on error. Possible error returns are: - - * `bfd_error_no_memory' - Not enough memory exists to create private - data for OBFD. - - #define bfd_copy_private_bfd_data(ibfd, obfd) \ - BFD_SEND (obfd, _bfd_copy_private_bfd_data, \ - (ibfd, obfd)) - -2.3.0.13 `bfd_merge_private_bfd_data' -..................................... - -*Synopsis* - bfd_boolean bfd_merge_private_bfd_data (bfd *ibfd, bfd *obfd); - *Description* -Merge private BFD information from the BFD IBFD to the the output file -BFD OBFD when linking. Return `TRUE' on success, `FALSE' on error. -Possible error returns are: - - * `bfd_error_no_memory' - Not enough memory exists to create private - data for OBFD. - - #define bfd_merge_private_bfd_data(ibfd, obfd) \ - BFD_SEND (obfd, _bfd_merge_private_bfd_data, \ - (ibfd, obfd)) - -2.3.0.14 `bfd_set_private_flags' -................................ - -*Synopsis* - bfd_boolean bfd_set_private_flags (bfd *abfd, flagword flags); - *Description* -Set private BFD flag information in the BFD ABFD. Return `TRUE' on -success, `FALSE' on error. Possible error returns are: - - * `bfd_error_no_memory' - Not enough memory exists to create private - data for OBFD. - - #define bfd_set_private_flags(abfd, flags) \ - BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags)) - -2.3.0.15 `Other functions' -.......................... - -*Description* -The following functions exist but have not yet been documented. - #define bfd_sizeof_headers(abfd, reloc) \ - BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc)) - - #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \ - BFD_SEND (abfd, _bfd_find_nearest_line, \ - (abfd, sec, syms, off, file, func, line)) - - #define bfd_debug_info_start(abfd) \ - BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) - - #define bfd_debug_info_end(abfd) \ - BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) - - #define bfd_debug_info_accumulate(abfd, section) \ - BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) - - #define bfd_stat_arch_elt(abfd, stat) \ - BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat)) - - #define bfd_update_armap_timestamp(abfd) \ - BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd)) - - #define bfd_set_arch_mach(abfd, arch, mach)\ - BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) - - #define bfd_relax_section(abfd, section, link_info, again) \ - BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again)) - - #define bfd_gc_sections(abfd, link_info) \ - BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info)) - - #define bfd_merge_sections(abfd, link_info) \ - BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info)) - - #define bfd_is_group_section(abfd, sec) \ - BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec)) - - #define bfd_discard_group(abfd, sec) \ - BFD_SEND (abfd, _bfd_discard_group, (abfd, sec)) - - #define bfd_link_hash_table_create(abfd) \ - BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) - - #define bfd_link_hash_table_free(abfd, hash) \ - BFD_SEND (abfd, _bfd_link_hash_table_free, (hash)) - - #define bfd_link_add_symbols(abfd, info) \ - BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) - - #define bfd_link_just_syms(abfd, sec, info) \ - BFD_SEND (abfd, _bfd_link_just_syms, (sec, info)) - - #define bfd_final_link(abfd, info) \ - BFD_SEND (abfd, _bfd_final_link, (abfd, info)) - - #define bfd_free_cached_info(abfd) \ - BFD_SEND (abfd, _bfd_free_cached_info, (abfd)) - - #define bfd_get_dynamic_symtab_upper_bound(abfd) \ - BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd)) - - #define bfd_print_private_bfd_data(abfd, file)\ - BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file)) - - #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \ - BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols)) - - #define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \ - BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \ - dyncount, dynsyms, ret)) - - #define bfd_get_dynamic_reloc_upper_bound(abfd) \ - BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd)) - - #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \ - BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms)) - - extern bfd_byte *bfd_get_relocated_section_contents - (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *, - bfd_boolean, asymbol **); - -2.3.0.16 `bfd_alt_mach_code' -............................ - -*Synopsis* - bfd_boolean bfd_alt_mach_code (bfd *abfd, int alternative); - *Description* -When more than one machine code number is available for the same -machine type, this function can be used to switch between the preferred -one (alternative == 0) and any others. Currently, only ELF supports -this feature, with up to two alternate machine codes. - - struct bfd_preserve - { - void *marker; - void *tdata; - flagword flags; - const struct bfd_arch_info *arch_info; - struct bfd_section *sections; - struct bfd_section **section_tail; - unsigned int section_count; - struct bfd_hash_table section_htab; - }; - -2.3.0.17 `bfd_preserve_save' -............................ - -*Synopsis* - bfd_boolean bfd_preserve_save (bfd *, struct bfd_preserve *); - *Description* -When testing an object for compatibility with a particular target -back-end, the back-end object_p function needs to set up certain fields -in the bfd on successfully recognizing the object. This typically -happens in a piecemeal fashion, with failures possible at many points. -On failure, the bfd is supposed to be restored to its initial state, -which is virtually impossible. However, restoring a subset of the bfd -state works in practice. This function stores the subset and -reinitializes the bfd. - -2.3.0.18 `bfd_preserve_restore' -............................... - -*Synopsis* - void bfd_preserve_restore (bfd *, struct bfd_preserve *); - *Description* -This function restores bfd state saved by bfd_preserve_save. If MARKER -is non-NULL in struct bfd_preserve then that block and all subsequently -bfd_alloc'd memory is freed. - -2.3.0.19 `bfd_preserve_finish' -.............................. - -*Synopsis* - void bfd_preserve_finish (bfd *, struct bfd_preserve *); - *Description* -This function should be called when the bfd state saved by -bfd_preserve_save is no longer needed. ie. when the back-end object_p -function returns with success. - -2.3.0.20 `struct bfd_iovec' -........................... - -*Description* -The `struct bfd_iovec' contains the internal file I/O class. Each -`BFD' has an instance of this class and all file I/O is routed through -it (it is assumed that the instance implements all methods listed -below). - struct bfd_iovec - { - /* To avoid problems with macros, a "b" rather than "f" - prefix is prepended to each method name. */ - /* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching - bytes starting at PTR. Return the number of bytes actually - transfered (a read past end-of-file returns less than NBYTES), - or -1 (setting `bfd_error') if an error occurs. */ - file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes); - file_ptr (*bwrite) (struct bfd *abfd, const void *ptr, - file_ptr nbytes); - /* Return the current IOSTREAM file offset, or -1 (setting `bfd_error' - if an error occurs. */ - file_ptr (*btell) (struct bfd *abfd); - /* For the following, on successful completion a value of 0 is returned. - Otherwise, a value of -1 is returned (and `bfd_error' is set). */ - int (*bseek) (struct bfd *abfd, file_ptr offset, int whence); - int (*bclose) (struct bfd *abfd); - int (*bflush) (struct bfd *abfd); - int (*bstat) (struct bfd *abfd, struct stat *sb); - }; - -2.3.0.21 `bfd_get_mtime' -........................ - -*Synopsis* - long bfd_get_mtime (bfd *abfd); - *Description* -Return the file modification time (as read from the file system, or -from the archive header for archive members). - -2.3.0.22 `bfd_get_size' -....................... - -*Synopsis* - long bfd_get_size (bfd *abfd); - *Description* -Return the file size (as read from file system) for the file associated -with BFD ABFD. - - The initial motivation for, and use of, this routine is not so we -can get the exact size of the object the BFD applies to, since that -might not be generally possible (archive members for example). It -would be ideal if someone could eventually modify it so that such -results were guaranteed. - - Instead, we want to ask questions like "is this NNN byte sized -object I'm about to try read from file offset YYY reasonable?" As as -example of where we might do this, some object formats use string -tables for which the first `sizeof (long)' bytes of the table contain -the size of the table itself, including the size bytes. If an -application tries to read what it thinks is one of these string tables, -without some way to validate the size, and for some reason the size is -wrong (byte swapping error, wrong location for the string table, etc.), -the only clue is likely to be a read error when it tries to read the -table, or a "virtual memory exhausted" error when it tries to allocate -15 bazillon bytes of space for the 15 bazillon byte table it is about -to read. This function at least allows us to answer the question, "is -the size reasonable?". - -* Menu: - -* Memory Usage:: -* Initialization:: -* Sections:: -* Symbols:: -* Archives:: -* Formats:: -* Relocations:: -* Core Files:: -* Targets:: -* Architectures:: -* Opening and Closing:: -* Internal:: -* File Caching:: -* Linker Functions:: -* Hash Tables:: - - -File: bfd.info, Node: Memory Usage, Next: Initialization, Prev: BFD front end, Up: BFD front end - -2.4 Memory Usage -================ - -BFD keeps all of its internal structures in obstacks. There is one -obstack per open BFD file, into which the current state is stored. When -a BFD is closed, the obstack is deleted, and so everything which has -been allocated by BFD for the closing file is thrown away. - - BFD does not free anything created by an application, but pointers -into `bfd' structures become invalid on a `bfd_close'; for example, -after a `bfd_close' the vector passed to `bfd_canonicalize_symtab' is -still around, since it has been allocated by the application, but the -data that it pointed to are lost. - - The general rule is to not close a BFD until all operations dependent -upon data from the BFD have been completed, or all the data from within -the file has been copied. To help with the management of memory, there -is a function (`bfd_alloc_size') which returns the number of bytes in -obstacks associated with the supplied BFD. This could be used to select -the greediest open BFD, close it to reclaim the memory, perform some -operation and reopen the BFD again, to get a fresh copy of the data -structures. - - -File: bfd.info, Node: Initialization, Next: Sections, Prev: Memory Usage, Up: BFD front end - -2.5 Initialization -================== - -These are the functions that handle initializing a BFD. - -2.5.0.1 `bfd_init' -.................. - -*Synopsis* - void bfd_init (void); - *Description* -This routine must be called before any other BFD function to initialize -magical internal data structures. - - -File: bfd.info, Node: Sections, Next: Symbols, Prev: Initialization, Up: BFD front end - -2.6 Sections -============ - -The raw data contained within a BFD is maintained through the section -abstraction. A single BFD may have any number of sections. It keeps -hold of them by pointing to the first; each one points to the next in -the list. - - Sections are supported in BFD in `section.c'. - -* Menu: - -* Section Input:: -* Section Output:: -* typedef asection:: -* section prototypes:: - - -File: bfd.info, Node: Section Input, Next: Section Output, Prev: Sections, Up: Sections - -2.6.1 Section input -------------------- - -When a BFD is opened for reading, the section structures are created -and attached to the BFD. - - Each section has a name which describes the section in the outside -world--for example, `a.out' would contain at least three sections, -called `.text', `.data' and `.bss'. - - Names need not be unique; for example a COFF file may have several -sections named `.data'. - - Sometimes a BFD will contain more than the "natural" number of -sections. A back end may attach other sections containing constructor -data, or an application may add a section (using `bfd_make_section') to -the sections attached to an already open BFD. For example, the linker -creates an extra section `COMMON' for each input file's BFD to hold -information about common storage. - - The raw data is not necessarily read in when the section descriptor -is created. Some targets may leave the data in place until a -`bfd_get_section_contents' call is made. Other back ends may read in -all the data at once. For example, an S-record file has to be read -once to determine the size of the data. An IEEE-695 file doesn't -contain raw data in sections, but data and relocation expressions -intermixed, so the data area has to be parsed to get out the data and -relocations. - - -File: bfd.info, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections - -2.6.2 Section output --------------------- - -To write a new object style BFD, the various sections to be written -have to be created. They are attached to the BFD in the same way as -input sections; data is written to the sections using -`bfd_set_section_contents'. - - Any program that creates or combines sections (e.g., the assembler -and linker) must use the `asection' fields `output_section' and -`output_offset' to indicate the file sections to which each section -must be written. (If the section is being created from scratch, -`output_section' should probably point to the section itself and -`output_offset' should probably be zero.) - - The data to be written comes from input sections attached (via -`output_section' pointers) to the output sections. The output section -structure can be considered a filter for the input section: the output -section determines the vma of the output data and the name, but the -input section determines the offset into the output section of the data -to be written. - - E.g., to create a section "O", starting at 0x100, 0x123 long, -containing two subsections, "A" at offset 0x0 (i.e., at vma 0x100) and -"B" at offset 0x20 (i.e., at vma 0x120) the `asection' structures would -look like: - - section name "A" - output_offset 0x00 - size 0x20 - output_section -----------> section name "O" - | vma 0x100 - section name "B" | size 0x123 - output_offset 0x20 | - size 0x103 | - output_section --------| - -2.6.3 Link orders ------------------ - -The data within a section is stored in a "link_order". These are much -like the fixups in `gas'. The link_order abstraction allows a section -to grow and shrink within itself. - - A link_order knows how big it is, and which is the next link_order -and where the raw data for it is; it also points to a list of -relocations which apply to it. - - The link_order is used by the linker to perform relaxing on final -code. The compiler creates code which is as big as necessary to make -it work without relaxing, and the user can select whether to relax. -Sometimes relaxing takes a lot of time. The linker runs around the -relocations to see if any are attached to data which can be shrunk, if -so it does it on a link_order by link_order basis. - - -File: bfd.info, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections - -2.6.4 typedef asection ----------------------- - -Here is the section structure: - - - typedef struct bfd_section - { - /* The name of the section; the name isn't a copy, the pointer is - the same as that passed to bfd_make_section. */ - const char *name; - - /* A unique sequence number. */ - int id; - - /* Which section in the bfd; 0..n-1 as sections are created in a bfd. */ - int index; - - /* The next section in the list belonging to the BFD, or NULL. */ - struct bfd_section *next; - - /* The field flags contains attributes of the section. Some - flags are read in from the object file, and some are - synthesized from other information. */ - flagword flags; - - #define SEC_NO_FLAGS 0x000 - - /* Tells the OS to allocate space for this section when loading. - This is clear for a section containing debug information only. */ - #define SEC_ALLOC 0x001 - - /* Tells the OS to load the section from the file when loading. - This is clear for a .bss section. */ - #define SEC_LOAD 0x002 - - /* The section contains data still to be relocated, so there is - some relocation information too. */ - #define SEC_RELOC 0x004 - - /* A signal to the OS that the section contains read only data. */ - #define SEC_READONLY 0x008 - - /* The section contains code only. */ - #define SEC_CODE 0x010 - - /* The section contains data only. */ - #define SEC_DATA 0x020 - - /* The section will reside in ROM. */ - #define SEC_ROM 0x040 - - /* The section contains constructor information. This section - type is used by the linker to create lists of constructors and - destructors used by `g++'. When a back end sees a symbol - which should be used in a constructor list, it creates a new - section for the type of name (e.g., `__CTOR_LIST__'), attaches - the symbol to it, and builds a relocation. To build the lists - of constructors, all the linker has to do is catenate all the - sections called `__CTOR_LIST__' and relocate the data - contained within - exactly the operations it would peform on - standard data. */ - #define SEC_CONSTRUCTOR 0x080 - - /* The section has contents - a data section could be - `SEC_ALLOC' | `SEC_HAS_CONTENTS'; a debug section could be - `SEC_HAS_CONTENTS' */ - #define SEC_HAS_CONTENTS 0x100 - - /* An instruction to the linker to not output the section - even if it has information which would normally be written. */ - #define SEC_NEVER_LOAD 0x200 - - /* The section contains thread local data. */ - #define SEC_THREAD_LOCAL 0x400 - - /* The section has GOT references. This flag is only for the - linker, and is currently only used by the elf32-hppa back end. - It will be set if global offset table references were detected - in this section, which indicate to the linker that the section - contains PIC code, and must be handled specially when doing a - static link. */ - #define SEC_HAS_GOT_REF 0x800 - - /* The section contains common symbols (symbols may be defined - multiple times, the value of a symbol is the amount of - space it requires, and the largest symbol value is the one - used). Most targets have exactly one of these (which we - translate to bfd_com_section_ptr), but ECOFF has two. */ - #define SEC_IS_COMMON 0x1000 - - /* The section contains only debugging information. For - example, this is set for ELF .debug and .stab sections. - strip tests this flag to see if a section can be - discarded. */ - #define SEC_DEBUGGING 0x2000 - - /* The contents of this section are held in memory pointed to - by the contents field. This is checked by bfd_get_section_contents, - and the data is retrieved from memory if appropriate. */ - #define SEC_IN_MEMORY 0x4000 - - /* The contents of this section are to be excluded by the - linker for executable and shared objects unless those - objects are to be further relocated. */ - #define SEC_EXCLUDE 0x8000 - - /* The contents of this section are to be sorted based on the sum of - the symbol and addend values specified by the associated relocation - entries. Entries without associated relocation entries will be - appended to the end of the section in an unspecified order. */ - #define SEC_SORT_ENTRIES 0x10000 - - /* When linking, duplicate sections of the same name should be - discarded, rather than being combined into a single section as - is usually done. This is similar to how common symbols are - handled. See SEC_LINK_DUPLICATES below. */ - #define SEC_LINK_ONCE 0x20000 - - /* If SEC_LINK_ONCE is set, this bitfield describes how the linker - should handle duplicate sections. */ - #define SEC_LINK_DUPLICATES 0x40000 - - /* This value for SEC_LINK_DUPLICATES means that duplicate - sections with the same name should simply be discarded. */ - #define SEC_LINK_DUPLICATES_DISCARD 0x0 - - /* This value for SEC_LINK_DUPLICATES means that the linker - should warn if there are any duplicate sections, although - it should still only link one copy. */ - #define SEC_LINK_DUPLICATES_ONE_ONLY 0x80000 - - /* This value for SEC_LINK_DUPLICATES means that the linker - should warn if any duplicate sections are a different size. */ - #define SEC_LINK_DUPLICATES_SAME_SIZE 0x100000 - - /* This value for SEC_LINK_DUPLICATES means that the linker - should warn if any duplicate sections contain different - contents. */ - #define SEC_LINK_DUPLICATES_SAME_CONTENTS \ - (SEC_LINK_DUPLICATES_ONE_ONLY | SEC_LINK_DUPLICATES_SAME_SIZE) - - /* This section was created by the linker as part of dynamic - relocation or other arcane processing. It is skipped when - going through the first-pass output, trusting that someone - else up the line will take care of it later. */ - #define SEC_LINKER_CREATED 0x200000 - - /* This section should not be subject to garbage collection. */ - #define SEC_KEEP 0x400000 - - /* This section contains "short" data, and should be placed - "near" the GP. */ - #define SEC_SMALL_DATA 0x800000 - - /* Attempt to merge identical entities in the section. - Entity size is given in the entsize field. */ - #define SEC_MERGE 0x1000000 - - /* If given with SEC_MERGE, entities to merge are zero terminated - strings where entsize specifies character size instead of fixed - size entries. */ - #define SEC_STRINGS 0x2000000 - - /* This section contains data about section groups. */ - #define SEC_GROUP 0x4000000 - - /* The section is a COFF shared library section. This flag is - only for the linker. If this type of section appears in - the input file, the linker must copy it to the output file - without changing the vma or size. FIXME: Although this - was originally intended to be general, it really is COFF - specific (and the flag was renamed to indicate this). It - might be cleaner to have some more general mechanism to - allow the back end to control what the linker does with - sections. */ - #define SEC_COFF_SHARED_LIBRARY 0x10000000 - - /* This section contains data which may be shared with other - executables or shared objects. This is for COFF only. */ - #define SEC_COFF_SHARED 0x20000000 - - /* When a section with this flag is being linked, then if the size of - the input section is less than a page, it should not cross a page - boundary. If the size of the input section is one page or more, - it should be aligned on a page boundary. This is for TI - TMS320C54X only. */ - #define SEC_TIC54X_BLOCK 0x40000000 - - /* Conditionally link this section; do not link if there are no - references found to any symbol in the section. This is for TI - TMS320C54X only. */ - #define SEC_TIC54X_CLINK 0x80000000 - - /* End of section flags. */ - - /* Some internal packed boolean fields. */ - - /* See the vma field. */ - unsigned int user_set_vma : 1; - - /* A mark flag used by some of the linker backends. */ - unsigned int linker_mark : 1; - - /* Another mark flag used by some of the linker backends. Set for - output sections that have an input section. */ - unsigned int linker_has_input : 1; - - /* A mark flag used by some linker backends for garbage collection. */ - unsigned int gc_mark : 1; - - /* The following flags are used by the ELF linker. */ - - /* Mark sections which have been allocated to segments. */ - unsigned int segment_mark : 1; - - /* Type of sec_info information. */ - unsigned int sec_info_type:3; - #define ELF_INFO_TYPE_NONE 0 - #define ELF_INFO_TYPE_STABS 1 - #define ELF_INFO_TYPE_MERGE 2 - #define ELF_INFO_TYPE_EH_FRAME 3 - #define ELF_INFO_TYPE_JUST_SYMS 4 - - /* Nonzero if this section uses RELA relocations, rather than REL. */ - unsigned int use_rela_p:1; - - /* Bits used by various backends. The generic code doesn't touch - these fields. */ - - /* Nonzero if this section has TLS related relocations. */ - unsigned int has_tls_reloc:1; - - /* Nonzero if this section has a gp reloc. */ - unsigned int has_gp_reloc:1; - - /* Nonzero if this section needs the relax finalize pass. */ - unsigned int need_finalize_relax:1; - - /* Whether relocations have been processed. */ - unsigned int reloc_done : 1; - - /* End of internal packed boolean fields. */ - - /* The virtual memory address of the section - where it will be - at run time. The symbols are relocated against this. The - user_set_vma flag is maintained by bfd; if it's not set, the - backend can assign addresses (for example, in `a.out', where - the default address for `.data' is dependent on the specific - target and various flags). */ - bfd_vma vma; - - /* The load address of the section - where it would be in a - rom image; really only used for writing section header - information. */ - bfd_vma lma; - - /* The size of the section in octets, as it will be output. - Contains a value even if the section has no contents (e.g., the - size of `.bss'). */ - bfd_size_type size; - - /* For input sections, the original size on disk of the section, in - octets. This field is used by the linker relaxation code. It is - currently only set for sections where the linker relaxation scheme - doesn't cache altered section and reloc contents (stabs, eh_frame, - SEC_MERGE, some coff relaxing targets), and thus the original size - needs to be kept to read the section multiple times. - For output sections, rawsize holds the section size calculated on - a previous linker relaxation pass. */ - bfd_size_type rawsize; - - /* If this section is going to be output, then this value is the - offset in *bytes* into the output section of the first byte in the - input section (byte ==> smallest addressable unit on the - target). In most cases, if this was going to start at the - 100th octet (8-bit quantity) in the output section, this value - would be 100. However, if the target byte size is 16 bits - (bfd_octets_per_byte is "2"), this value would be 50. */ - bfd_vma output_offset; - - /* The output section through which to map on output. */ - struct bfd_section *output_section; - - /* The alignment requirement of the section, as an exponent of 2 - - e.g., 3 aligns to 2^3 (or 8). */ - unsigned int alignment_power; - - /* If an input section, a pointer to a vector of relocation - records for the data in this section. */ - struct reloc_cache_entry *relocation; - - /* If an output section, a pointer to a vector of pointers to - relocation records for the data in this section. */ - struct reloc_cache_entry **orelocation; - - /* The number of relocation records in one of the above. */ - unsigned reloc_count; - - /* Information below is back end specific - and not always used - or updated. */ - - /* File position of section data. */ - file_ptr filepos; - - /* File position of relocation info. */ - file_ptr rel_filepos; - - /* File position of line data. */ - file_ptr line_filepos; - - /* Pointer to data for applications. */ - void *userdata; - - /* If the SEC_IN_MEMORY flag is set, this points to the actual - contents. */ - unsigned char *contents; - - /* Attached line number information. */ - alent *lineno; - - /* Number of line number records. */ - unsigned int lineno_count; - - /* Entity size for merging purposes. */ - unsigned int entsize; - - /* Points to the kept section if this section is a link-once section, - and is discarded. */ - struct bfd_section *kept_section; - - /* When a section is being output, this value changes as more - linenumbers are written out. */ - file_ptr moving_line_filepos; - - /* What the section number is in the target world. */ - int target_index; - - void *used_by_bfd; - - /* If this is a constructor section then here is a list of the - relocations created to relocate items within it. */ - struct relent_chain *constructor_chain; - - /* The BFD which owns the section. */ - bfd *owner; - - /* A symbol which points at this section only. */ - struct bfd_symbol *symbol; - struct bfd_symbol **symbol_ptr_ptr; - - struct bfd_link_order *link_order_head; - struct bfd_link_order *link_order_tail; - } asection; - - /* These sections are global, and are managed by BFD. The application - and target back end are not permitted to change the values in - these sections. New code should use the section_ptr macros rather - than referring directly to the const sections. The const sections - may eventually vanish. */ - #define BFD_ABS_SECTION_NAME "*ABS*" - #define BFD_UND_SECTION_NAME "*UND*" - #define BFD_COM_SECTION_NAME "*COM*" - #define BFD_IND_SECTION_NAME "*IND*" - - /* The absolute section. */ - extern asection bfd_abs_section; - #define bfd_abs_section_ptr ((asection *) &bfd_abs_section) - #define bfd_is_abs_section(sec) ((sec) == bfd_abs_section_ptr) - /* Pointer to the undefined section. */ - extern asection bfd_und_section; - #define bfd_und_section_ptr ((asection *) &bfd_und_section) - #define bfd_is_und_section(sec) ((sec) == bfd_und_section_ptr) - /* Pointer to the common section. */ - extern asection bfd_com_section; - #define bfd_com_section_ptr ((asection *) &bfd_com_section) - /* Pointer to the indirect section. */ - extern asection bfd_ind_section; - #define bfd_ind_section_ptr ((asection *) &bfd_ind_section) - #define bfd_is_ind_section(sec) ((sec) == bfd_ind_section_ptr) - - #define bfd_is_const_section(SEC) \ - ( ((SEC) == bfd_abs_section_ptr) \ - || ((SEC) == bfd_und_section_ptr) \ - || ((SEC) == bfd_com_section_ptr) \ - || ((SEC) == bfd_ind_section_ptr)) - - extern const struct bfd_symbol * const bfd_abs_symbol; - extern const struct bfd_symbol * const bfd_com_symbol; - extern const struct bfd_symbol * const bfd_und_symbol; - extern const struct bfd_symbol * const bfd_ind_symbol; - - /* Macros to handle insertion and deletion of a bfd's sections. These - only handle the list pointers, ie. do not adjust section_count, - target_index etc. */ - #define bfd_section_list_remove(ABFD, PS) \ - do \ - { \ - asection **_ps = PS; \ - asection *_s = *_ps; \ - *_ps = _s->next; \ - if (_s->next == NULL) \ - (ABFD)->section_tail = _ps; \ - } \ - while (0) - #define bfd_section_list_insert(ABFD, PS, S) \ - do \ - { \ - asection **_ps = PS; \ - asection *_s = S; \ - _s->next = *_ps; \ - *_ps = _s; \ - if (_s->next == NULL) \ - (ABFD)->section_tail = &_s->next; \ - } \ - while (0) - - -File: bfd.info, Node: section prototypes, Prev: typedef asection, Up: Sections - -2.6.5 Section prototypes ------------------------- - -These are the functions exported by the section handling part of BFD. - -2.6.5.1 `bfd_section_list_clear' -................................ - -*Synopsis* - void bfd_section_list_clear (bfd *); - *Description* -Clears the section list, and also resets the section count and hash -table entries. - -2.6.5.2 `bfd_get_section_by_name' -................................. - -*Synopsis* - asection *bfd_get_section_by_name (bfd *abfd, const char *name); - *Description* -Run through ABFD and return the one of the `asection's whose name -matches NAME, otherwise `NULL'. *Note Sections::, for more information. - - This should only be used in special cases; the normal way to process -all sections of a given name is to use `bfd_map_over_sections' and -`strcmp' on the name (or better yet, base it on the section flags or -something else) for each section. - -2.6.5.3 `bfd_get_section_by_name_if' -.................................... - -*Synopsis* - asection *bfd_get_section_by_name_if - (bfd *abfd, - const char *name, - bfd_boolean (*func) (bfd *abfd, asection *sect, void *obj), - void *obj); - *Description* -Call the provided function FUNC for each section attached to the BFD -ABFD whose name matches NAME, passing OBJ as an argument. The function -will be called as if by - - func (abfd, the_section, obj); - - It returns the first section for which FUNC returns true, otherwise -`NULL'. - -2.6.5.4 `bfd_get_unique_section_name' -..................................... - -*Synopsis* - char *bfd_get_unique_section_name - (bfd *abfd, const char *templat, int *count); - *Description* -Invent a section name that is unique in ABFD by tacking a dot and a -digit suffix onto the original TEMPLAT. If COUNT is non-NULL, then it -specifies the first number tried as a suffix to generate a unique name. -The value pointed to by COUNT will be incremented in this case. - -2.6.5.5 `bfd_make_section_old_way' -.................................. - -*Synopsis* - asection *bfd_make_section_old_way (bfd *abfd, const char *name); - *Description* -Create a new empty section called NAME and attach it to the end of the -chain of sections for the BFD ABFD. An attempt to create a section with -a name which is already in use returns its pointer without changing the -section chain. - - It has the funny name since this is the way it used to be before it -was rewritten.... - - Possible errors are: - * `bfd_error_invalid_operation' - If output has already started for - this BFD. - - * `bfd_error_no_memory' - If memory allocation fails. - -2.6.5.6 `bfd_make_section_anyway' -................................. - -*Synopsis* - asection *bfd_make_section_anyway (bfd *abfd, const char *name); - *Description* -Create a new empty section called NAME and attach it to the end of the -chain of sections for ABFD. Create a new section even if there is -already a section with that name. - - Return `NULL' and set `bfd_error' on error; possible errors are: - * `bfd_error_invalid_operation' - If output has already started for - ABFD. - - * `bfd_error_no_memory' - If memory allocation fails. - -2.6.5.7 `bfd_make_section' -.......................... - -*Synopsis* - asection *bfd_make_section (bfd *, const char *name); - *Description* -Like `bfd_make_section_anyway', but return `NULL' (without calling -bfd_set_error ()) without changing the section chain if there is -already a section named NAME. If there is an error, return `NULL' and -set `bfd_error'. - -2.6.5.8 `bfd_set_section_flags' -............................... - -*Synopsis* - bfd_boolean bfd_set_section_flags - (bfd *abfd, asection *sec, flagword flags); - *Description* -Set the attributes of the section SEC in the BFD ABFD to the value -FLAGS. Return `TRUE' on success, `FALSE' on error. Possible error -returns are: - - * `bfd_error_invalid_operation' - The section cannot have one or - more of the attributes requested. For example, a .bss section in - `a.out' may not have the `SEC_HAS_CONTENTS' field set. - -2.6.5.9 `bfd_map_over_sections' -............................... - -*Synopsis* - void bfd_map_over_sections - (bfd *abfd, - void (*func) (bfd *abfd, asection *sect, void *obj), - void *obj); - *Description* -Call the provided function FUNC for each section attached to the BFD -ABFD, passing OBJ as an argument. The function will be called as if by - - func (abfd, the_section, obj); - - This is the preferred method for iterating over sections; an -alternative would be to use a loop: - - section *p; - for (p = abfd->sections; p != NULL; p = p->next) - func (abfd, p, ...) - -2.6.5.10 `bfd_sections_find_if' -............................... - -*Synopsis* - asection *bfd_sections_find_if - (bfd *abfd, - bfd_boolean (*operation) (bfd *abfd, asection *sect, void *obj), - void *obj); - *Description* -Call the provided function OPERATION for each section attached to the -BFD ABFD, passing OBJ as an argument. The function will be called as if -by - - operation (abfd, the_section, obj); - - It returns the first section for which OPERATION returns true. - -2.6.5.11 `bfd_set_section_size' -............................... - -*Synopsis* - bfd_boolean bfd_set_section_size - (bfd *abfd, asection *sec, bfd_size_type val); - *Description* -Set SEC to the size VAL. If the operation is ok, then `TRUE' is -returned, else `FALSE'. - - Possible error returns: - * `bfd_error_invalid_operation' - Writing has started to the BFD, so - setting the size is invalid. - -2.6.5.12 `bfd_set_section_contents' -................................... - -*Synopsis* - bfd_boolean bfd_set_section_contents - (bfd *abfd, asection *section, const void *data, - file_ptr offset, bfd_size_type count); - *Description* -Sets the contents of the section SECTION in BFD ABFD to the data -starting in memory at DATA. The data is written to the output section -starting at offset OFFSET for COUNT octets. - - Normally `TRUE' is returned, else `FALSE'. Possible error returns -are: - * `bfd_error_no_contents' - The output section does not have the - `SEC_HAS_CONTENTS' attribute, so nothing can be written to it. - - * and some more too - This routine is front end to the back end function -`_bfd_set_section_contents'. - -2.6.5.13 `bfd_get_section_contents' -................................... - -*Synopsis* - bfd_boolean bfd_get_section_contents - (bfd *abfd, asection *section, void *location, file_ptr offset, - bfd_size_type count); - *Description* -Read data from SECTION in BFD ABFD into memory starting at LOCATION. -The data is read at an offset of OFFSET from the start of the input -section, and is read for COUNT bytes. - - If the contents of a constructor with the `SEC_CONSTRUCTOR' flag set -are requested or if the section does not have the `SEC_HAS_CONTENTS' -flag set, then the LOCATION is filled with zeroes. If no errors occur, -`TRUE' is returned, else `FALSE'. - -2.6.5.14 `bfd_malloc_and_get_section' -..................................... - -*Synopsis* - bfd_boolean bfd_malloc_and_get_section - (bfd *abfd, asection *section, bfd_byte **buf); - *Description* -Read all data from SECTION in BFD ABFD into a buffer, *BUF, malloc'd by -this function. - -2.6.5.15 `bfd_copy_private_section_data' -........................................ - -*Synopsis* - bfd_boolean bfd_copy_private_section_data - (bfd *ibfd, asection *isec, bfd *obfd, asection *osec); - *Description* -Copy private section information from ISEC in the BFD IBFD to the -section OSEC in the BFD OBFD. Return `TRUE' on success, `FALSE' on -error. Possible error returns are: - - * `bfd_error_no_memory' - Not enough memory exists to create private - data for OSEC. - - #define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \ - BFD_SEND (obfd, _bfd_copy_private_section_data, \ - (ibfd, isection, obfd, osection)) - -2.6.5.16 `_bfd_strip_section_from_output' -......................................... - -*Synopsis* - void _bfd_strip_section_from_output - (struct bfd_link_info *info, asection *section); - *Description* -Remove SECTION from the output. If the output section becomes empty, -remove it from the output bfd. - - This function won't actually do anything except twiddle flags if -called too late in the linking process, when it's not safe to remove -sections. - -2.6.5.17 `bfd_generic_is_group_section' -....................................... - -*Synopsis* - bfd_boolean bfd_generic_is_group_section (bfd *, const asection *sec); - *Description* -Returns TRUE if SEC is a member of a group. - -2.6.5.18 `bfd_generic_discard_group' -.................................... - -*Synopsis* - bfd_boolean bfd_generic_discard_group (bfd *abfd, asection *group); - *Description* -Remove all members of GROUP from the output. - - -File: bfd.info, Node: Symbols, Next: Archives, Prev: Sections, Up: BFD front end - -2.7 Symbols -=========== - -BFD tries to maintain as much symbol information as it can when it -moves information from file to file. BFD passes information to -applications though the `asymbol' structure. When the application -requests the symbol table, BFD reads the table in the native form and -translates parts of it into the internal format. To maintain more than -the information passed to applications, some targets keep some -information "behind the scenes" in a structure only the particular back -end knows about. For example, the coff back end keeps the original -symbol table structure as well as the canonical structure when a BFD is -read in. On output, the coff back end can reconstruct the output symbol -table so that no information is lost, even information unique to coff -which BFD doesn't know or understand. If a coff symbol table were read, -but were written through an a.out back end, all the coff specific -information would be lost. The symbol table of a BFD is not necessarily -read in until a canonicalize request is made. Then the BFD back end -fills in a table provided by the application with pointers to the -canonical information. To output symbols, the application provides BFD -with a table of pointers to pointers to `asymbol's. This allows -applications like the linker to output a symbol as it was read, since -the "behind the scenes" information will be still available. - -* Menu: - -* Reading Symbols:: -* Writing Symbols:: -* Mini Symbols:: -* typedef asymbol:: -* symbol handling functions:: - - -File: bfd.info, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols - -2.7.1 Reading symbols ---------------------- - -There are two stages to reading a symbol table from a BFD: allocating -storage, and the actual reading process. This is an excerpt from an -application which reads the symbol table: - - long storage_needed; - asymbol **symbol_table; - long number_of_symbols; - long i; - - storage_needed = bfd_get_symtab_upper_bound (abfd); - - if (storage_needed < 0) - FAIL - - if (storage_needed == 0) - return; - - symbol_table = xmalloc (storage_needed); - ... - number_of_symbols = - bfd_canonicalize_symtab (abfd, symbol_table); - - if (number_of_symbols < 0) - FAIL - - for (i = 0; i < number_of_symbols; i++) - process_symbol (symbol_table[i]); - - All storage for the symbols themselves is in an objalloc connected -to the BFD; it is freed when the BFD is closed. - - -File: bfd.info, Node: Writing Symbols, Next: Mini Symbols, Prev: Reading Symbols, Up: Symbols - -2.7.2 Writing symbols ---------------------- - -Writing of a symbol table is automatic when a BFD open for writing is -closed. The application attaches a vector of pointers to pointers to -symbols to the BFD being written, and fills in the symbol count. The -close and cleanup code reads through the table provided and performs -all the necessary operations. The BFD output code must always be -provided with an "owned" symbol: one which has come from another BFD, -or one which has been created using `bfd_make_empty_symbol'. Here is an -example showing the creation of a symbol table with only one element: - - #include "bfd.h" - int main (void) - { - bfd *abfd; - asymbol *ptrs[2]; - asymbol *new; - - abfd = bfd_openw ("foo","a.out-sunos-big"); - bfd_set_format (abfd, bfd_object); - new = bfd_make_empty_symbol (abfd); - new->name = "dummy_symbol"; - new->section = bfd_make_section_old_way (abfd, ".text"); - new->flags = BSF_GLOBAL; - new->value = 0x12345; - - ptrs[0] = new; - ptrs[1] = 0; - - bfd_set_symtab (abfd, ptrs, 1); - bfd_close (abfd); - return 0; - } - - ./makesym - nm foo - 00012345 A dummy_symbol - - Many formats cannot represent arbitrary symbol information; for -instance, the `a.out' object format does not allow an arbitrary number -of sections. A symbol pointing to a section which is not one of -`.text', `.data' or `.bss' cannot be described. - - -File: bfd.info, Node: Mini Symbols, Next: typedef asymbol, Prev: Writing Symbols, Up: Symbols - -2.7.3 Mini Symbols ------------------- - -Mini symbols provide read-only access to the symbol table. They use -less memory space, but require more time to access. They can be useful -for tools like nm or objdump, which may have to handle symbol tables of -extremely large executables. - - The `bfd_read_minisymbols' function will read the symbols into -memory in an internal form. It will return a `void *' pointer to a -block of memory, a symbol count, and the size of each symbol. The -pointer is allocated using `malloc', and should be freed by the caller -when it is no longer needed. - - The function `bfd_minisymbol_to_symbol' will take a pointer to a -minisymbol, and a pointer to a structure returned by -`bfd_make_empty_symbol', and return a `asymbol' structure. The return -value may or may not be the same as the value from -`bfd_make_empty_symbol' which was passed in. - - -File: bfd.info, Node: typedef asymbol, Next: symbol handling functions, Prev: Mini Symbols, Up: Symbols - -2.7.4 typedef asymbol ---------------------- - -An `asymbol' has the form: - - - typedef struct bfd_symbol - { - /* A pointer to the BFD which owns the symbol. This information - is necessary so that a back end can work out what additional - information (invisible to the application writer) is carried - with the symbol. - - This field is *almost* redundant, since you can use section->owner - instead, except that some symbols point to the global sections - bfd_{abs,com,und}_section. This could be fixed by making - these globals be per-bfd (or per-target-flavor). FIXME. */ - struct bfd *the_bfd; /* Use bfd_asymbol_bfd(sym) to access this field. */ - - /* The text of the symbol. The name is left alone, and not copied; the - application may not alter it. */ - const char *name; - - /* The value of the symbol. This really should be a union of a - numeric value with a pointer, since some flags indicate that - a pointer to another symbol is stored here. */ - symvalue value; - - /* Attributes of a symbol. */ - #define BSF_NO_FLAGS 0x00 - - /* The symbol has local scope; `static' in `C'. The value - is the offset into the section of the data. */ - #define BSF_LOCAL 0x01 - - /* The symbol has global scope; initialized data in `C'. The - value is the offset into the section of the data. */ - #define BSF_GLOBAL 0x02 - - /* The symbol has global scope and is exported. The value is - the offset into the section of the data. */ - #define BSF_EXPORT BSF_GLOBAL /* No real difference. */ - - /* A normal C symbol would be one of: - `BSF_LOCAL', `BSF_FORT_COMM', `BSF_UNDEFINED' or - `BSF_GLOBAL'. */ - - /* The symbol is a debugging record. The value has an arbitrary - meaning, unless BSF_DEBUGGING_RELOC is also set. */ - #define BSF_DEBUGGING 0x08 - - /* The symbol denotes a function entry point. Used in ELF, - perhaps others someday. */ - #define BSF_FUNCTION 0x10 - - /* Used by the linker. */ - #define BSF_KEEP 0x20 - #define BSF_KEEP_G 0x40 - - /* A weak global symbol, overridable without warnings by - a regular global symbol of the same name. */ - #define BSF_WEAK 0x80 - - /* This symbol was created to point to a section, e.g. ELF's - STT_SECTION symbols. */ - #define BSF_SECTION_SYM 0x100 - - /* The symbol used to be a common symbol, but now it is - allocated. */ - #define BSF_OLD_COMMON 0x200 - - /* The default value for common data. */ - #define BFD_FORT_COMM_DEFAULT_VALUE 0 - - /* In some files the type of a symbol sometimes alters its - location in an output file - ie in coff a `ISFCN' symbol - which is also `C_EXT' symbol appears where it was - declared and not at the end of a section. This bit is set - by the target BFD part to convey this information. */ - #define BSF_NOT_AT_END 0x400 - - /* Signal that the symbol is the label of constructor section. */ - #define BSF_CONSTRUCTOR 0x800 - - /* Signal that the symbol is a warning symbol. The name is a - warning. The name of the next symbol is the one to warn about; - if a reference is made to a symbol with the same name as the next - symbol, a warning is issued by the linker. */ - #define BSF_WARNING 0x1000 - - /* Signal that the symbol is indirect. This symbol is an indirect - pointer to the symbol with the same name as the next symbol. */ - #define BSF_INDIRECT 0x2000 - - /* BSF_FILE marks symbols that contain a file name. This is used - for ELF STT_FILE symbols. */ - #define BSF_FILE 0x4000 - - /* Symbol is from dynamic linking information. */ - #define BSF_DYNAMIC 0x8000 - - /* The symbol denotes a data object. Used in ELF, and perhaps - others someday. */ - #define BSF_OBJECT 0x10000 - - /* This symbol is a debugging symbol. The value is the offset - into the section of the data. BSF_DEBUGGING should be set - as well. */ - #define BSF_DEBUGGING_RELOC 0x20000 - - /* This symbol is thread local. Used in ELF. */ - #define BSF_THREAD_LOCAL 0x40000 - - flagword flags; - - /* A pointer to the section to which this symbol is - relative. This will always be non NULL, there are special - sections for undefined and absolute symbols. */ - struct bfd_section *section; - - /* Back end special data. */ - union - { - void *p; - bfd_vma i; - } - udata; - } - asymbol; - - -File: bfd.info, Node: symbol handling functions, Prev: typedef asymbol, Up: Symbols - -2.7.5 Symbol handling functions -------------------------------- - -2.7.5.1 `bfd_get_symtab_upper_bound' -.................................... - -*Description* -Return the number of bytes required to store a vector of pointers to -`asymbols' for all the symbols in the BFD ABFD, including a terminal -NULL pointer. If there are no symbols in the BFD, then return 0. If an -error occurs, return -1. - #define bfd_get_symtab_upper_bound(abfd) \ - BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd)) - -2.7.5.2 `bfd_is_local_label' -............................ - -*Synopsis* - bfd_boolean bfd_is_local_label (bfd *abfd, asymbol *sym); - *Description* -Return TRUE if the given symbol SYM in the BFD ABFD is a compiler -generated local label, else return FALSE. - -2.7.5.3 `bfd_is_local_label_name' -................................. - -*Synopsis* - bfd_boolean bfd_is_local_label_name (bfd *abfd, const char *name); - *Description* -Return TRUE if a symbol with the name NAME in the BFD ABFD is a -compiler generated local label, else return FALSE. This just checks -whether the name has the form of a local label. - #define bfd_is_local_label_name(abfd, name) \ - BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name)) - -2.7.5.4 `bfd_is_target_special_symbol' -...................................... - -*Synopsis* - bfd_boolean bfd_is_target_special_symbol (bfd *abfd, asymbol *sym); - *Description* -Return TRUE iff a symbol SYM in the BFD ABFD is something special to -the particular target represented by the BFD. Such symbols should -normally not be mentioned to the user. - #define bfd_is_target_special_symbol(abfd, sym) \ - BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym)) - -2.7.5.5 `bfd_canonicalize_symtab' -................................. - -*Description* -Read the symbols from the BFD ABFD, and fills in the vector LOCATION -with pointers to the symbols and a trailing NULL. Return the actual -number of symbol pointers, not including the NULL. - #define bfd_canonicalize_symtab(abfd, location) \ - BFD_SEND (abfd, _bfd_canonicalize_symtab, (abfd, location)) - -2.7.5.6 `bfd_set_symtab' -........................ - -*Synopsis* - bfd_boolean bfd_set_symtab - (bfd *abfd, asymbol **location, unsigned int count); - *Description* -Arrange that when the output BFD ABFD is closed, the table LOCATION of -COUNT pointers to symbols will be written. - -2.7.5.7 `bfd_print_symbol_vandf' -................................ - -*Synopsis* - void bfd_print_symbol_vandf (bfd *abfd, void *file, asymbol *symbol); - *Description* -Print the value and flags of the SYMBOL supplied to the stream FILE. - -2.7.5.8 `bfd_make_empty_symbol' -............................... - -*Description* -Create a new `asymbol' structure for the BFD ABFD and return a pointer -to it. - - This routine is necessary because each back end has private -information surrounding the `asymbol'. Building your own `asymbol' and -pointing to it will not create the private information, and will cause -problems later on. - #define bfd_make_empty_symbol(abfd) \ - BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd)) - -2.7.5.9 `_bfd_generic_make_empty_symbol' -........................................ - -*Synopsis* - asymbol *_bfd_generic_make_empty_symbol (bfd *); - *Description* -Create a new `asymbol' structure for the BFD ABFD and return a pointer -to it. Used by core file routines, binary back-end and anywhere else -where no private info is needed. - -2.7.5.10 `bfd_make_debug_symbol' -................................ - -*Description* -Create a new `asymbol' structure for the BFD ABFD, to be used as a -debugging symbol. Further details of its use have yet to be worked out. - #define bfd_make_debug_symbol(abfd,ptr,size) \ - BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd, ptr, size)) - -2.7.5.11 `bfd_decode_symclass' -.............................. - -*Description* -Return a character corresponding to the symbol class of SYMBOL, or '?' -for an unknown class. - - *Synopsis* - int bfd_decode_symclass (asymbol *symbol); - -2.7.5.12 `bfd_is_undefined_symclass' -.................................... - -*Description* -Returns non-zero if the class symbol returned by bfd_decode_symclass -represents an undefined symbol. Returns zero otherwise. - - *Synopsis* - bfd_boolean bfd_is_undefined_symclass (int symclass); - -2.7.5.13 `bfd_symbol_info' -.......................... - -*Description* -Fill in the basic info about symbol that nm needs. Additional info may -be added by the back-ends after calling this function. - - *Synopsis* - void bfd_symbol_info (asymbol *symbol, symbol_info *ret); - -2.7.5.14 `bfd_copy_private_symbol_data' -....................................... - -*Synopsis* - bfd_boolean bfd_copy_private_symbol_data - (bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym); - *Description* -Copy private symbol information from ISYM in the BFD IBFD to the symbol -OSYM in the BFD OBFD. Return `TRUE' on success, `FALSE' on error. -Possible error returns are: - - * `bfd_error_no_memory' - Not enough memory exists to create private - data for OSEC. - - #define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \ - BFD_SEND (obfd, _bfd_copy_private_symbol_data, \ - (ibfd, isymbol, obfd, osymbol)) - - -File: bfd.info, Node: Archives, Next: Formats, Prev: Symbols, Up: BFD front end - -2.8 Archives -============ - -*Description* -An archive (or library) is just another BFD. It has a symbol table, -although there's not much a user program will do with it. - - The big difference between an archive BFD and an ordinary BFD is -that the archive doesn't have sections. Instead it has a chain of BFDs -that are considered its contents. These BFDs can be manipulated like -any other. The BFDs contained in an archive opened for reading will -all be opened for reading. You may put either input or output BFDs -into an archive opened for output; they will be handled correctly when -the archive is closed. - - Use `bfd_openr_next_archived_file' to step through the contents of -an archive opened for input. You don't have to read the entire archive -if you don't want to! Read it until you find what you want. - - Archive contents of output BFDs are chained through the `next' -pointer in a BFD. The first one is findable through the `archive_head' -slot of the archive. Set it with `bfd_set_archive_head' (q.v.). A -given BFD may be in only one open output archive at a time. - - As expected, the BFD archive code is more general than the archive -code of any given environment. BFD archives may contain files of -different formats (e.g., a.out and coff) and even different -architectures. You may even place archives recursively into archives! - - This can cause unexpected confusion, since some archive formats are -more expressive than others. For instance, Intel COFF archives can -preserve long filenames; SunOS a.out archives cannot. If you move a -file from the first to the second format and back again, the filename -may be truncated. Likewise, different a.out environments have different -conventions as to how they truncate filenames, whether they preserve -directory names in filenames, etc. When interoperating with native -tools, be sure your files are homogeneous. - - Beware: most of these formats do not react well to the presence of -spaces in filenames. We do the best we can, but can't always handle -this case due to restrictions in the format of archives. Many Unix -utilities are braindead in regards to spaces and such in filenames -anyway, so this shouldn't be much of a restriction. - - Archives are supported in BFD in `archive.c'. - -2.8.0.1 `bfd_get_next_mapent' -............................. - -*Synopsis* - symindex bfd_get_next_mapent - (bfd *abfd, symindex previous, carsym **sym); - *Description* -Step through archive ABFD's symbol table (if it has one). Successively -update SYM with the next symbol's information, returning that symbol's -(internal) index into the symbol table. - - Supply `BFD_NO_MORE_SYMBOLS' as the PREVIOUS entry to get the first -one; returns `BFD_NO_MORE_SYMBOLS' when you've already got the last one. - - A `carsym' is a canonical archive symbol. The only user-visible -element is its name, a null-terminated string. - -2.8.0.2 `bfd_set_archive_head' -.............................. - -*Synopsis* - bfd_boolean bfd_set_archive_head (bfd *output, bfd *new_head); - *Description* -Set the head of the chain of BFDs contained in the archive OUTPUT to -NEW_HEAD. - -2.8.0.3 `bfd_openr_next_archived_file' -...................................... - -*Synopsis* - bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous); - *Description* -Provided a BFD, ARCHIVE, containing an archive and NULL, open an input -BFD on the first contained element and returns that. Subsequent calls -should pass the archive and the previous return value to return a -created BFD to the next contained element. NULL is returned when there -are no more. - - -File: bfd.info, Node: Formats, Next: Relocations, Prev: Archives, Up: BFD front end - -2.9 File formats -================ - -A format is a BFD concept of high level file contents type. The formats -supported by BFD are: - - * `bfd_object' - The BFD may contain data, symbols, relocations and debug info. - - * `bfd_archive' - The BFD contains other BFDs and an optional index. - - * `bfd_core' - The BFD contains the result of an executable core dump. - -2.9.0.1 `bfd_check_format' -.......................... - -*Synopsis* - bfd_boolean bfd_check_format (bfd *abfd, bfd_format format); - *Description* -Verify if the file attached to the BFD ABFD is compatible with the -format FORMAT (i.e., one of `bfd_object', `bfd_archive' or `bfd_core'). - - If the BFD has been set to a specific target before the call, only -the named target and format combination is checked. If the target has -not been set, or has been set to `default', then all the known target -backends is interrogated to determine a match. If the default target -matches, it is used. If not, exactly one target must recognize the -file, or an error results. - - The function returns `TRUE' on success, otherwise `FALSE' with one -of the following error codes: - - * `bfd_error_invalid_operation' - if `format' is not one of - `bfd_object', `bfd_archive' or `bfd_core'. - - * `bfd_error_system_call' - if an error occured during a read - even - some file mismatches can cause bfd_error_system_calls. - - * `file_not_recognised' - none of the backends recognised the file - format. - - * `bfd_error_file_ambiguously_recognized' - more than one backend - recognised the file format. - -2.9.0.2 `bfd_check_format_matches' -.................................. - -*Synopsis* - bfd_boolean bfd_check_format_matches - (bfd *abfd, bfd_format format, char ***matching); - *Description* -Like `bfd_check_format', except when it returns FALSE with `bfd_errno' -set to `bfd_error_file_ambiguously_recognized'. In that case, if -MATCHING is not NULL, it will be filled in with a NULL-terminated list -of the names of the formats that matched, allocated with `malloc'. -Then the user may choose a format and try again. - - When done with the list that MATCHING points to, the caller should -free it. - -2.9.0.3 `bfd_set_format' -........................ - -*Synopsis* - bfd_boolean bfd_set_format (bfd *abfd, bfd_format format); - *Description* -This function sets the file format of the BFD ABFD to the format -FORMAT. If the target set in the BFD does not support the format -requested, the format is invalid, or the BFD is not open for writing, -then an error occurs. - -2.9.0.4 `bfd_format_string' -........................... - -*Synopsis* - const char *bfd_format_string (bfd_format format); - *Description* -Return a pointer to a const string `invalid', `object', `archive', -`core', or `unknown', depending upon the value of FORMAT. - - -File: bfd.info, Node: Relocations, Next: Core Files, Prev: Formats, Up: BFD front end - -2.10 Relocations -================ - -BFD maintains relocations in much the same way it maintains symbols: -they are left alone until required, then read in en-masse and -translated into an internal form. A common routine -`bfd_perform_relocation' acts upon the canonical form to do the fixup. - - Relocations are maintained on a per section basis, while symbols are -maintained on a per BFD basis. - - All that a back end has to do to fit the BFD interface is to create -a `struct reloc_cache_entry' for each relocation in a particular -section, and fill in the right bits of the structures. - -* Menu: - -* typedef arelent:: -* howto manager:: - - -File: bfd.info, Node: typedef arelent, Next: howto manager, Prev: Relocations, Up: Relocations - -2.10.1 typedef arelent ----------------------- - -This is the structure of a relocation entry: - - - typedef enum bfd_reloc_status - { - /* No errors detected. */ - bfd_reloc_ok, - - /* The relocation was performed, but there was an overflow. */ - bfd_reloc_overflow, - - /* The address to relocate was not within the section supplied. */ - bfd_reloc_outofrange, - - /* Used by special functions. */ - bfd_reloc_continue, - - /* Unsupported relocation size requested. */ - bfd_reloc_notsupported, - - /* Unused. */ - bfd_reloc_other, - - /* The symbol to relocate against was undefined. */ - bfd_reloc_undefined, - - /* The relocation was performed, but may not be ok - presently - generated only when linking i960 coff files with i960 b.out - symbols. If this type is returned, the error_message argument - to bfd_perform_relocation will be set. */ - bfd_reloc_dangerous - } - bfd_reloc_status_type; - - - typedef struct reloc_cache_entry - { - /* A pointer into the canonical table of pointers. */ - struct bfd_symbol **sym_ptr_ptr; - - /* offset in section. */ - bfd_size_type address; - - /* addend for relocation value. */ - bfd_vma addend; - - /* Pointer to how to perform the required relocation. */ - reloc_howto_type *howto; - - } - arelent; - *Description* -Here is a description of each of the fields within an `arelent': - - * `sym_ptr_ptr' - The symbol table pointer points to a pointer to the symbol -associated with the relocation request. It is the pointer into the -table returned by the back end's `canonicalize_symtab' action. *Note -Symbols::. The symbol is referenced through a pointer to a pointer so -that tools like the linker can fix up all the symbols of the same name -by modifying only one pointer. The relocation routine looks in the -symbol and uses the base of the section the symbol is attached to and -the value of the symbol as the initial relocation offset. If the symbol -pointer is zero, then the section provided is looked up. - - * `address' - The `address' field gives the offset in bytes from the base of the -section data which owns the relocation record to the first byte of -relocatable information. The actual data relocated will be relative to -this point; for example, a relocation type which modifies the bottom -two bytes of a four byte word would not touch the first byte pointed to -in a big endian world. - - * `addend' - The `addend' is a value provided by the back end to be added (!) to -the relocation offset. Its interpretation is dependent upon the howto. -For example, on the 68k the code: - - char foo[]; - main() - { - return foo[0x12345678]; - } - - Could be compiled into: - - linkw fp,#-4 - moveb @#12345678,d0 - extbl d0 - unlk fp - rts - - This could create a reloc pointing to `foo', but leave the offset in -the data, something like: - - RELOCATION RECORDS FOR [.text]: - offset type value - 00000006 32 _foo - - 00000000 4e56 fffc ; linkw fp,#-4 - 00000004 1039 1234 5678 ; moveb @#12345678,d0 - 0000000a 49c0 ; extbl d0 - 0000000c 4e5e ; unlk fp - 0000000e 4e75 ; rts - - Using coff and an 88k, some instructions don't have enough space in -them to represent the full address range, and pointers have to be -loaded in two parts. So you'd get something like: - - or.u r13,r0,hi16(_foo+0x12345678) - ld.b r2,r13,lo16(_foo+0x12345678) - jmp r1 - - This should create two relocs, both pointing to `_foo', and with -0x12340000 in their addend field. The data would consist of: - - RELOCATION RECORDS FOR [.text]: - offset type value - 00000002 HVRT16 _foo+0x12340000 - 00000006 LVRT16 _foo+0x12340000 - - 00000000 5da05678 ; or.u r13,r0,0x5678 - 00000004 1c4d5678 ; ld.b r2,r13,0x5678 - 00000008 f400c001 ; jmp r1 - - The relocation routine digs out the value from the data, adds it to -the addend to get the original offset, and then adds the value of -`_foo'. Note that all 32 bits have to be kept around somewhere, to cope -with carry from bit 15 to bit 16. - - One further example is the sparc and the a.out format. The sparc has -a similar problem to the 88k, in that some instructions don't have room -for an entire offset, but on the sparc the parts are created in odd -sized lumps. The designers of the a.out format chose to not use the -data within the section for storing part of the offset; all the offset -is kept within the reloc. Anything in the data should be ignored. - - save %sp,-112,%sp - sethi %hi(_foo+0x12345678),%g2 - ldsb [%g2+%lo(_foo+0x12345678)],%i0 - ret - restore - - Both relocs contain a pointer to `foo', and the offsets contain junk. - - RELOCATION RECORDS FOR [.text]: - offset type value - 00000004 HI22 _foo+0x12345678 - 00000008 LO10 _foo+0x12345678 - - 00000000 9de3bf90 ; save %sp,-112,%sp - 00000004 05000000 ; sethi %hi(_foo+0),%g2 - 00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0 - 0000000c 81c7e008 ; ret - 00000010 81e80000 ; restore - - * `howto' - The `howto' field can be imagined as a relocation instruction. It is -a pointer to a structure which contains information on what to do with -all of the other information in the reloc record and data section. A -back end would normally have a relocation instruction set and turn -relocations into pointers to the correct structure on input - but it -would be possible to create each howto field on demand. - -2.10.1.1 `enum complain_overflow' -................................. - -Indicates what sort of overflow checking should be done when performing -a relocation. - - - enum complain_overflow - { - /* Do not complain on overflow. */ - complain_overflow_dont, - - /* Complain if the bitfield overflows, whether it is considered - as signed or unsigned. */ - complain_overflow_bitfield, - - /* Complain if the value overflows when considered as signed - number. */ - complain_overflow_signed, - - /* Complain if the value overflows when considered as an - unsigned number. */ - complain_overflow_unsigned - }; - -2.10.1.2 `reloc_howto_type' -........................... - -The `reloc_howto_type' is a structure which contains all the -information that libbfd needs to know to tie up a back end's data. - - struct bfd_symbol; /* Forward declaration. */ - - struct reloc_howto_struct - { - /* The type field has mainly a documentary use - the back end can - do what it wants with it, though normally the back end's - external idea of what a reloc number is stored - in this field. For example, a PC relative word relocation - in a coff environment has the type 023 - because that's - what the outside world calls a R_PCRWORD reloc. */ - unsigned int type; - - /* The value the final relocation is shifted right by. This drops - unwanted data from the relocation. */ - unsigned int rightshift; - - /* The size of the item to be relocated. This is *not* a - power-of-two measure. To get the number of bytes operated - on by a type of relocation, use bfd_get_reloc_size. */ - int size; - - /* The number of bits in the item to be relocated. This is used - when doing overflow checking. */ - unsigned int bitsize; - - /* Notes that the relocation is relative to the location in the - data section of the addend. The relocation function will - subtract from the relocation value the address of the location - being relocated. */ - bfd_boolean pc_relative; - - /* The bit position of the reloc value in the destination. - The relocated value is left shifted by this amount. */ - unsigned int bitpos; - - /* What type of overflow error should be checked for when - relocating. */ - enum complain_overflow complain_on_overflow; - - /* If this field is non null, then the supplied function is - called rather than the normal function. This allows really - strange relocation methods to be accommodated (e.g., i960 callj - instructions). */ - bfd_reloc_status_type (*special_function) - (bfd *, arelent *, struct bfd_symbol *, void *, asection *, - bfd *, char **); - - /* The textual name of the relocation type. */ - char *name; - - /* Some formats record a relocation addend in the section contents - rather than with the relocation. For ELF formats this is the - distinction between USE_REL and USE_RELA (though the code checks - for USE_REL == 1/0). The value of this field is TRUE if the - addend is recorded with the section contents; when performing a - partial link (ld -r) the section contents (the data) will be - modified. The value of this field is FALSE if addends are - recorded with the relocation (in arelent.addend); when performing - a partial link the relocation will be modified. - All relocations for all ELF USE_RELA targets should set this field - to FALSE (values of TRUE should be looked on with suspicion). - However, the converse is not true: not all relocations of all ELF - USE_REL targets set this field to TRUE. Why this is so is peculiar - to each particular target. For relocs that aren't used in partial - links (e.g. GOT stuff) it doesn't matter what this is set to. */ - bfd_boolean partial_inplace; - - /* src_mask selects the part of the instruction (or data) to be used - in the relocation sum. If the target relocations don't have an - addend in the reloc, eg. ELF USE_REL, src_mask will normally equal - dst_mask to extract the addend from the section contents. If - relocations do have an addend in the reloc, eg. ELF USE_RELA, this - field should be zero. Non-zero values for ELF USE_RELA targets are - bogus as in those cases the value in the dst_mask part of the - section contents should be treated as garbage. */ - bfd_vma src_mask; - - /* dst_mask selects which parts of the instruction (or data) are - replaced with a relocated value. */ - bfd_vma dst_mask; - - /* When some formats create PC relative instructions, they leave - the value of the pc of the place being relocated in the offset - slot of the instruction, so that a PC relative relocation can - be made just by adding in an ordinary offset (e.g., sun3 a.out). - Some formats leave the displacement part of an instruction - empty (e.g., m88k bcs); this flag signals the fact. */ - bfd_boolean pcrel_offset; - }; - -2.10.1.3 `The HOWTO Macro' -.......................... - -*Description* -The HOWTO define is horrible and will go away. - #define HOWTO(C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \ - { (unsigned) C, R, S, B, P, BI, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC } - - *Description* -And will be replaced with the totally magic way. But for the moment, we -are compatible, so do it this way. - #define NEWHOWTO(FUNCTION, NAME, SIZE, REL, IN) \ - HOWTO (0, 0, SIZE, 0, REL, 0, complain_overflow_dont, FUNCTION, \ - NAME, FALSE, 0, 0, IN) - - *Description* -This is used to fill in an empty howto entry in an array. - #define EMPTY_HOWTO(C) \ - HOWTO ((C), 0, 0, 0, FALSE, 0, complain_overflow_dont, NULL, \ - NULL, FALSE, 0, 0, FALSE) - - *Description* -Helper routine to turn a symbol into a relocation value. - #define HOWTO_PREPARE(relocation, symbol) \ - { \ - if (symbol != NULL) \ - { \ - if (bfd_is_com_section (symbol->section)) \ - { \ - relocation = 0; \ - } \ - else \ - { \ - relocation = symbol->value; \ - } \ - } \ - } - -2.10.1.4 `bfd_get_reloc_size' -............................. - -*Synopsis* - unsigned int bfd_get_reloc_size (reloc_howto_type *); - *Description* -For a reloc_howto_type that operates on a fixed number of bytes, this -returns the number of bytes operated on. - -2.10.1.5 `arelent_chain' -........................ - -*Description* -How relocs are tied together in an `asection': - typedef struct relent_chain - { - arelent relent; - struct relent_chain *next; - } - arelent_chain; - -2.10.1.6 `bfd_check_overflow' -............................. - -*Synopsis* - bfd_reloc_status_type bfd_check_overflow - (enum complain_overflow how, - unsigned int bitsize, - unsigned int rightshift, - unsigned int addrsize, - bfd_vma relocation); - *Description* -Perform overflow checking on RELOCATION which has BITSIZE significant -bits and will be shifted right by RIGHTSHIFT bits, on a machine with -addresses containing ADDRSIZE significant bits. The result is either of -`bfd_reloc_ok' or `bfd_reloc_overflow'. - -2.10.1.7 `bfd_perform_relocation' -................................. - -*Synopsis* - bfd_reloc_status_type bfd_perform_relocation - (bfd *abfd, - arelent *reloc_entry, - void *data, - asection *input_section, - bfd *output_bfd, - char **error_message); - *Description* -If OUTPUT_BFD is supplied to this function, the generated image will be -relocatable; the relocations are copied to the output file after they -have been changed to reflect the new state of the world. There are two -ways of reflecting the results of partial linkage in an output file: by -modifying the output data in place, and by modifying the relocation -record. Some native formats (e.g., basic a.out and basic coff) have no -way of specifying an addend in the relocation type, so the addend has -to go in the output data. This is no big deal since in these formats -the output data slot will always be big enough for the addend. Complex -reloc types with addends were invented to solve just this problem. The -ERROR_MESSAGE argument is set to an error message if this return -`bfd_reloc_dangerous'. - -2.10.1.8 `bfd_install_relocation' -................................. - -*Synopsis* - bfd_reloc_status_type bfd_install_relocation - (bfd *abfd, - arelent *reloc_entry, - void *data, bfd_vma data_start, - asection *input_section, - char **error_message); - *Description* -This looks remarkably like `bfd_perform_relocation', except it does not -expect that the section contents have been filled in. I.e., it's -suitable for use when creating, rather than applying a relocation. - - For now, this function should be considered reserved for the -assembler. - - -File: bfd.info, Node: howto manager, Prev: typedef arelent, Up: Relocations - -2.11 The howto manager -====================== - -When an application wants to create a relocation, but doesn't know what -the target machine might call it, it can find out by using this bit of -code. - -2.11.0.1 `bfd_reloc_code_type' -.............................. - -*Description* -The insides of a reloc code. The idea is that, eventually, there will -be one enumerator for every type of relocation we ever do. Pass one of -these values to `bfd_reloc_type_lookup', and it'll return a howto -pointer. - - This does mean that the application must determine the correct -enumerator value; you can't get a howto pointer from a random set of -attributes. - - Here are the possible values for `enum bfd_reloc_code_real': - - -- : BFD_RELOC_64 - -- : BFD_RELOC_32 - -- : BFD_RELOC_26 - -- : BFD_RELOC_24 - -- : BFD_RELOC_16 - -- : BFD_RELOC_14 - -- : BFD_RELOC_8 - Basic absolute relocations of N bits. - - -- : BFD_RELOC_64_PCREL - -- : BFD_RELOC_32_PCREL - -- : BFD_RELOC_24_PCREL - -- : BFD_RELOC_16_PCREL - -- : BFD_RELOC_12_PCREL - -- : BFD_RELOC_8_PCREL - PC-relative relocations. Sometimes these are relative to the - address of the relocation itself; sometimes they are relative to - the start of the section containing the relocation. It depends on - the specific target. - - The 24-bit relocation is used in some Intel 960 configurations. - - -- : BFD_RELOC_32_SECREL - Section relative relocations. Some targets need this for DWARF2. - - -- : BFD_RELOC_32_GOT_PCREL - -- : BFD_RELOC_16_GOT_PCREL - -- : BFD_RELOC_8_GOT_PCREL - -- : BFD_RELOC_32_GOTOFF - -- : BFD_RELOC_16_GOTOFF - -- : BFD_RELOC_LO16_GOTOFF - -- : BFD_RELOC_HI16_GOTOFF - -- : BFD_RELOC_HI16_S_GOTOFF - -- : BFD_RELOC_8_GOTOFF - -- : BFD_RELOC_64_PLT_PCREL - -- : BFD_RELOC_32_PLT_PCREL - -- : BFD_RELOC_24_PLT_PCREL - -- : BFD_RELOC_16_PLT_PCREL - -- : BFD_RELOC_8_PLT_PCREL - -- : BFD_RELOC_64_PLTOFF - -- : BFD_RELOC_32_PLTOFF - -- : BFD_RELOC_16_PLTOFF - -- : BFD_RELOC_LO16_PLTOFF - -- : BFD_RELOC_HI16_PLTOFF - -- : BFD_RELOC_HI16_S_PLTOFF - -- : BFD_RELOC_8_PLTOFF - For ELF. - - -- : BFD_RELOC_68K_GLOB_DAT - -- : BFD_RELOC_68K_JMP_SLOT - -- : BFD_RELOC_68K_RELATIVE - Relocations used by 68K ELF. - - -- : BFD_RELOC_32_BASEREL - -- : BFD_RELOC_16_BASEREL - -- : BFD_RELOC_LO16_BASEREL - -- : BFD_RELOC_HI16_BASEREL - -- : BFD_RELOC_HI16_S_BASEREL - -- : BFD_RELOC_8_BASEREL - -- : BFD_RELOC_RVA - Linkage-table relative. - - -- : BFD_RELOC_8_FFnn - Absolute 8-bit relocation, but used to form an address like 0xFFnn. - - -- : BFD_RELOC_32_PCREL_S2 - -- : BFD_RELOC_16_PCREL_S2 - -- : BFD_RELOC_23_PCREL_S2 - These PC-relative relocations are stored as word displacements - - i.e., byte displacements shifted right two bits. The 30-bit word - displacement (<<32_PCREL_S2>> - 32 bits, shifted 2) is used on the - SPARC. (SPARC tools generally refer to this as <<WDISP30>>.) The - signed 16-bit displacement is used on the MIPS, and the 23-bit - displacement is used on the Alpha. - - -- : BFD_RELOC_HI22 - -- : BFD_RELOC_LO10 - High 22 bits and low 10 bits of 32-bit value, placed into lower - bits of the target word. These are used on the SPARC. - - -- : BFD_RELOC_GPREL16 - -- : BFD_RELOC_GPREL32 - For systems that allocate a Global Pointer register, these are - displacements off that register. These relocation types are - handled specially, because the value the register will have is - decided relatively late. - - -- : BFD_RELOC_I960_CALLJ - Reloc types used for i960/b.out. - - -- : BFD_RELOC_NONE - -- : BFD_RELOC_SPARC_WDISP22 - -- : BFD_RELOC_SPARC22 - -- : BFD_RELOC_SPARC13 - -- : BFD_RELOC_SPARC_GOT10 - -- : BFD_RELOC_SPARC_GOT13 - -- : BFD_RELOC_SPARC_GOT22 - -- : BFD_RELOC_SPARC_PC10 - -- : BFD_RELOC_SPARC_PC22 - -- : BFD_RELOC_SPARC_WPLT30 - -- : BFD_RELOC_SPARC_COPY - -- : BFD_RELOC_SPARC_GLOB_DAT - -- : BFD_RELOC_SPARC_JMP_SLOT - -- : BFD_RELOC_SPARC_RELATIVE - -- : BFD_RELOC_SPARC_UA16 - -- : BFD_RELOC_SPARC_UA32 - -- : BFD_RELOC_SPARC_UA64 - SPARC ELF relocations. There is probably some overlap with other - relocation types already defined. - - -- : BFD_RELOC_SPARC_BASE13 - -- : BFD_RELOC_SPARC_BASE22 - I think these are specific to SPARC a.out (e.g., Sun 4). - - -- : BFD_RELOC_SPARC_64 - -- : BFD_RELOC_SPARC_10 - -- : BFD_RELOC_SPARC_11 - -- : BFD_RELOC_SPARC_OLO10 - -- : BFD_RELOC_SPARC_HH22 - -- : BFD_RELOC_SPARC_HM10 - -- : BFD_RELOC_SPARC_LM22 - -- : BFD_RELOC_SPARC_PC_HH22 - -- : BFD_RELOC_SPARC_PC_HM10 - -- : BFD_RELOC_SPARC_PC_LM22 - -- : BFD_RELOC_SPARC_WDISP16 - -- : BFD_RELOC_SPARC_WDISP19 - -- : BFD_RELOC_SPARC_7 - -- : BFD_RELOC_SPARC_6 - -- : BFD_RELOC_SPARC_5 - -- : BFD_RELOC_SPARC_DISP64 - -- : BFD_RELOC_SPARC_PLT32 - -- : BFD_RELOC_SPARC_PLT64 - -- : BFD_RELOC_SPARC_HIX22 - -- : BFD_RELOC_SPARC_LOX10 - -- : BFD_RELOC_SPARC_H44 - -- : BFD_RELOC_SPARC_M44 - -- : BFD_RELOC_SPARC_L44 - -- : BFD_RELOC_SPARC_REGISTER - SPARC64 relocations - - -- : BFD_RELOC_SPARC_REV32 - SPARC little endian relocation - - -- : BFD_RELOC_SPARC_TLS_GD_HI22 - -- : BFD_RELOC_SPARC_TLS_GD_LO10 - -- : BFD_RELOC_SPARC_TLS_GD_ADD - -- : BFD_RELOC_SPARC_TLS_GD_CALL - -- : BFD_RELOC_SPARC_TLS_LDM_HI22 - -- : BFD_RELOC_SPARC_TLS_LDM_LO10 - -- : BFD_RELOC_SPARC_TLS_LDM_ADD - -- : BFD_RELOC_SPARC_TLS_LDM_CALL - -- : BFD_RELOC_SPARC_TLS_LDO_HIX22 - -- : BFD_RELOC_SPARC_TLS_LDO_LOX10 - -- : BFD_RELOC_SPARC_TLS_LDO_ADD - -- : BFD_RELOC_SPARC_TLS_IE_HI22 - -- : BFD_RELOC_SPARC_TLS_IE_LO10 - -- : BFD_RELOC_SPARC_TLS_IE_LD - -- : BFD_RELOC_SPARC_TLS_IE_LDX - -- : BFD_RELOC_SPARC_TLS_IE_ADD - -- : BFD_RELOC_SPARC_TLS_LE_HIX22 - -- : BFD_RELOC_SPARC_TLS_LE_LOX10 - -- : BFD_RELOC_SPARC_TLS_DTPMOD32 - -- : BFD_RELOC_SPARC_TLS_DTPMOD64 - -- : BFD_RELOC_SPARC_TLS_DTPOFF32 - -- : BFD_RELOC_SPARC_TLS_DTPOFF64 - -- : BFD_RELOC_SPARC_TLS_TPOFF32 - -- : BFD_RELOC_SPARC_TLS_TPOFF64 - SPARC TLS relocations - - -- : BFD_RELOC_ALPHA_GPDISP_HI16 - Alpha ECOFF and ELF relocations. Some of these treat the symbol or - "addend" in some special way. For GPDISP_HI16 ("gpdisp") - relocations, the symbol is ignored when writing; when reading, it - will be the absolute section symbol. The addend is the - displacement in bytes of the "lda" instruction from the "ldah" - instruction (which is at the address of this reloc). - - -- : BFD_RELOC_ALPHA_GPDISP_LO16 - For GPDISP_LO16 ("ignore") relocations, the symbol is handled as - with GPDISP_HI16 relocs. The addend is ignored when writing the - relocations out, and is filled in with the file's GP value on - reading, for convenience. - - -- : BFD_RELOC_ALPHA_GPDISP - The ELF GPDISP relocation is exactly the same as the GPDISP_HI16 - relocation except that there is no accompanying GPDISP_LO16 - relocation. - - -- : BFD_RELOC_ALPHA_LITERAL - -- : BFD_RELOC_ALPHA_ELF_LITERAL - -- : BFD_RELOC_ALPHA_LITUSE - The Alpha LITERAL/LITUSE relocs are produced by a symbol reference; - the assembler turns it into a LDQ instruction to load the address - of the symbol, and then fills in a register in the real - instruction. - - The LITERAL reloc, at the LDQ instruction, refers to the .lita - section symbol. The addend is ignored when writing, but is filled - in with the file's GP value on reading, for convenience, as with - the GPDISP_LO16 reloc. - - The ELF_LITERAL reloc is somewhere between 16_GOTOFF and - GPDISP_LO16. It should refer to the symbol to be referenced, as - with 16_GOTOFF, but it generates output not based on the position - within the .got section, but relative to the GP value chosen for - the file during the final link stage. - - The LITUSE reloc, on the instruction using the loaded address, - gives information to the linker that it might be able to use to - optimize away some literal section references. The symbol is - ignored (read as the absolute section symbol), and the "addend" - indicates the type of instruction using the register: 1 - "memory" - fmt insn 2 - byte-manipulation (byte offset reg) 3 - jsr (target - of branch) - - -- : BFD_RELOC_ALPHA_HINT - The HINT relocation indicates a value that should be filled into - the "hint" field of a jmp/jsr/ret instruction, for possible branch- - prediction logic which may be provided on some processors. - - -- : BFD_RELOC_ALPHA_LINKAGE - The LINKAGE relocation outputs a linkage pair in the object file, - which is filled by the linker. - - -- : BFD_RELOC_ALPHA_CODEADDR - The CODEADDR relocation outputs a STO_CA in the object file, which - is filled by the linker. - - -- : BFD_RELOC_ALPHA_GPREL_HI16 - -- : BFD_RELOC_ALPHA_GPREL_LO16 - The GPREL_HI/LO relocations together form a 32-bit offset from the - GP register. - - -- : BFD_RELOC_ALPHA_BRSGP - Like BFD_RELOC_23_PCREL_S2, except that the source and target must - share a common GP, and the target address is adjusted for - STO_ALPHA_STD_GPLOAD. - - -- : BFD_RELOC_ALPHA_TLSGD - -- : BFD_RELOC_ALPHA_TLSLDM - -- : BFD_RELOC_ALPHA_DTPMOD64 - -- : BFD_RELOC_ALPHA_GOTDTPREL16 - -- : BFD_RELOC_ALPHA_DTPREL64 - -- : BFD_RELOC_ALPHA_DTPREL_HI16 - -- : BFD_RELOC_ALPHA_DTPREL_LO16 - -- : BFD_RELOC_ALPHA_DTPREL16 - -- : BFD_RELOC_ALPHA_GOTTPREL16 - -- : BFD_RELOC_ALPHA_TPREL64 - -- : BFD_RELOC_ALPHA_TPREL_HI16 - -- : BFD_RELOC_ALPHA_TPREL_LO16 - -- : BFD_RELOC_ALPHA_TPREL16 - Alpha thread-local storage relocations. - - -- : BFD_RELOC_MIPS_JMP - Bits 27..2 of the relocation address shifted right 2 bits; simple - reloc otherwise. - - -- : BFD_RELOC_MIPS16_JMP - The MIPS16 jump instruction. - - -- : BFD_RELOC_MIPS16_GPREL - MIPS16 GP relative reloc. - - -- : BFD_RELOC_HI16 - High 16 bits of 32-bit value; simple reloc. - - -- : BFD_RELOC_HI16_S - High 16 bits of 32-bit value but the low 16 bits will be sign - extended and added to form the final result. If the low 16 bits - form a negative number, we need to add one to the high value to - compensate for the borrow when the low bits are added. - - -- : BFD_RELOC_LO16 - Low 16 bits. - - -- : BFD_RELOC_MIPS16_HI16 - MIPS16 high 16 bits of 32-bit value. - - -- : BFD_RELOC_MIPS16_HI16_S - MIPS16 high 16 bits of 32-bit value but the low 16 bits will be - sign extended and added to form the final result. If the low 16 - bits form a negative number, we need to add one to the high value - to compensate for the borrow when the low bits are added. - - -- : BFD_RELOC_MIPS16_LO16 - MIPS16 low 16 bits. - - -- : BFD_RELOC_MIPS_LITERAL - Relocation against a MIPS literal section. - - -- : BFD_RELOC_MIPS_GOT16 - -- : BFD_RELOC_MIPS_CALL16 - -- : BFD_RELOC_MIPS_GOT_HI16 - -- : BFD_RELOC_MIPS_GOT_LO16 - -- : BFD_RELOC_MIPS_CALL_HI16 - -- : BFD_RELOC_MIPS_CALL_LO16 - -- : BFD_RELOC_MIPS_SUB - -- : BFD_RELOC_MIPS_GOT_PAGE - -- : BFD_RELOC_MIPS_GOT_OFST - -- : BFD_RELOC_MIPS_GOT_DISP - -- : BFD_RELOC_MIPS_SHIFT5 - -- : BFD_RELOC_MIPS_SHIFT6 - -- : BFD_RELOC_MIPS_INSERT_A - -- : BFD_RELOC_MIPS_INSERT_B - -- : BFD_RELOC_MIPS_DELETE - -- : BFD_RELOC_MIPS_HIGHEST - -- : BFD_RELOC_MIPS_HIGHER - -- : BFD_RELOC_MIPS_SCN_DISP - -- : BFD_RELOC_MIPS_REL16 - -- : BFD_RELOC_MIPS_RELGOT - -- : BFD_RELOC_MIPS_JALR - -- : BFD_RELOC_MIPS_TLS_DTPMOD32 - -- : BFD_RELOC_MIPS_TLS_DTPREL32 - -- : BFD_RELOC_MIPS_TLS_DTPMOD64 - -- : BFD_RELOC_MIPS_TLS_DTPREL64 - -- : BFD_RELOC_MIPS_TLS_GD - -- : BFD_RELOC_MIPS_TLS_LDM - -- : BFD_RELOC_MIPS_TLS_DTPREL_HI16 - -- : BFD_RELOC_MIPS_TLS_DTPREL_LO16 - -- : BFD_RELOC_MIPS_TLS_GOTTPREL - -- : BFD_RELOC_MIPS_TLS_TPREL32 - -- : BFD_RELOC_MIPS_TLS_TPREL64 - -- : BFD_RELOC_MIPS_TLS_TPREL_HI16 - -- : BFD_RELOC_MIPS_TLS_TPREL_LO16 - MIPS ELF relocations. - - -- : BFD_RELOC_FRV_LABEL16 - -- : BFD_RELOC_FRV_LABEL24 - -- : BFD_RELOC_FRV_LO16 - -- : BFD_RELOC_FRV_HI16 - -- : BFD_RELOC_FRV_GPREL12 - -- : BFD_RELOC_FRV_GPRELU12 - -- : BFD_RELOC_FRV_GPREL32 - -- : BFD_RELOC_FRV_GPRELHI - -- : BFD_RELOC_FRV_GPRELLO - -- : BFD_RELOC_FRV_GOT12 - -- : BFD_RELOC_FRV_GOTHI - -- : BFD_RELOC_FRV_GOTLO - -- : BFD_RELOC_FRV_FUNCDESC - -- : BFD_RELOC_FRV_FUNCDESC_GOT12 - -- : BFD_RELOC_FRV_FUNCDESC_GOTHI - -- : BFD_RELOC_FRV_FUNCDESC_GOTLO - -- : BFD_RELOC_FRV_FUNCDESC_VALUE - -- : BFD_RELOC_FRV_FUNCDESC_GOTOFF12 - -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFHI - -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFLO - -- : BFD_RELOC_FRV_GOTOFF12 - -- : BFD_RELOC_FRV_GOTOFFHI - -- : BFD_RELOC_FRV_GOTOFFLO - -- : BFD_RELOC_FRV_GETTLSOFF - -- : BFD_RELOC_FRV_TLSDESC_VALUE - -- : BFD_RELOC_FRV_GOTTLSDESC12 - -- : BFD_RELOC_FRV_GOTTLSDESCHI - -- : BFD_RELOC_FRV_GOTTLSDESCLO - -- : BFD_RELOC_FRV_TLSMOFF12 - -- : BFD_RELOC_FRV_TLSMOFFHI - -- : BFD_RELOC_FRV_TLSMOFFLO - -- : BFD_RELOC_FRV_GOTTLSOFF12 - -- : BFD_RELOC_FRV_GOTTLSOFFHI - -- : BFD_RELOC_FRV_GOTTLSOFFLO - -- : BFD_RELOC_FRV_TLSOFF - -- : BFD_RELOC_FRV_TLSDESC_RELAX - -- : BFD_RELOC_FRV_GETTLSOFF_RELAX - -- : BFD_RELOC_FRV_TLSOFF_RELAX - -- : BFD_RELOC_FRV_TLSMOFF - Fujitsu Frv Relocations. - - -- : BFD_RELOC_MN10300_GOTOFF24 - This is a 24bit GOT-relative reloc for the mn10300. - - -- : BFD_RELOC_MN10300_GOT32 - This is a 32bit GOT-relative reloc for the mn10300, offset by two - bytes in the instruction. - - -- : BFD_RELOC_MN10300_GOT24 - This is a 24bit GOT-relative reloc for the mn10300, offset by two - bytes in the instruction. - - -- : BFD_RELOC_MN10300_GOT16 - This is a 16bit GOT-relative reloc for the mn10300, offset by two - bytes in the instruction. - - -- : BFD_RELOC_MN10300_COPY - Copy symbol at runtime. - - -- : BFD_RELOC_MN10300_GLOB_DAT - Create GOT entry. - - -- : BFD_RELOC_MN10300_JMP_SLOT - Create PLT entry. - - -- : BFD_RELOC_MN10300_RELATIVE - Adjust by program base. - - -- : BFD_RELOC_386_GOT32 - -- : BFD_RELOC_386_PLT32 - -- : BFD_RELOC_386_COPY - -- : BFD_RELOC_386_GLOB_DAT - -- : BFD_RELOC_386_JUMP_SLOT - -- : BFD_RELOC_386_RELATIVE - -- : BFD_RELOC_386_GOTOFF - -- : BFD_RELOC_386_GOTPC - -- : BFD_RELOC_386_TLS_TPOFF - -- : BFD_RELOC_386_TLS_IE - -- : BFD_RELOC_386_TLS_GOTIE - -- : BFD_RELOC_386_TLS_LE - -- : BFD_RELOC_386_TLS_GD - -- : BFD_RELOC_386_TLS_LDM - -- : BFD_RELOC_386_TLS_LDO_32 - -- : BFD_RELOC_386_TLS_IE_32 - -- : BFD_RELOC_386_TLS_LE_32 - -- : BFD_RELOC_386_TLS_DTPMOD32 - -- : BFD_RELOC_386_TLS_DTPOFF32 - -- : BFD_RELOC_386_TLS_TPOFF32 - i386/elf relocations - - -- : BFD_RELOC_X86_64_GOT32 - -- : BFD_RELOC_X86_64_PLT32 - -- : BFD_RELOC_X86_64_COPY - -- : BFD_RELOC_X86_64_GLOB_DAT - -- : BFD_RELOC_X86_64_JUMP_SLOT - -- : BFD_RELOC_X86_64_RELATIVE - -- : BFD_RELOC_X86_64_GOTPCREL - -- : BFD_RELOC_X86_64_32S - -- : BFD_RELOC_X86_64_DTPMOD64 - -- : BFD_RELOC_X86_64_DTPOFF64 - -- : BFD_RELOC_X86_64_TPOFF64 - -- : BFD_RELOC_X86_64_TLSGD - -- : BFD_RELOC_X86_64_TLSLD - -- : BFD_RELOC_X86_64_DTPOFF32 - -- : BFD_RELOC_X86_64_GOTTPOFF - -- : BFD_RELOC_X86_64_TPOFF32 - x86-64/elf relocations - - -- : BFD_RELOC_NS32K_IMM_8 - -- : BFD_RELOC_NS32K_IMM_16 - -- : BFD_RELOC_NS32K_IMM_32 - -- : BFD_RELOC_NS32K_IMM_8_PCREL - -- : BFD_RELOC_NS32K_IMM_16_PCREL - -- : BFD_RELOC_NS32K_IMM_32_PCREL - -- : BFD_RELOC_NS32K_DISP_8 - -- : BFD_RELOC_NS32K_DISP_16 - -- : BFD_RELOC_NS32K_DISP_32 - -- : BFD_RELOC_NS32K_DISP_8_PCREL - -- : BFD_RELOC_NS32K_DISP_16_PCREL - -- : BFD_RELOC_NS32K_DISP_32_PCREL - ns32k relocations - - -- : BFD_RELOC_PDP11_DISP_8_PCREL - -- : BFD_RELOC_PDP11_DISP_6_PCREL - PDP11 relocations - - -- : BFD_RELOC_PJ_CODE_HI16 - -- : BFD_RELOC_PJ_CODE_LO16 - -- : BFD_RELOC_PJ_CODE_DIR16 - -- : BFD_RELOC_PJ_CODE_DIR32 - -- : BFD_RELOC_PJ_CODE_REL16 - -- : BFD_RELOC_PJ_CODE_REL32 - Picojava relocs. Not all of these appear in object files. - - -- : BFD_RELOC_PPC_B26 - -- : BFD_RELOC_PPC_BA26 - -- : BFD_RELOC_PPC_TOC16 - -- : BFD_RELOC_PPC_B16 - -- : BFD_RELOC_PPC_B16_BRTAKEN - -- : BFD_RELOC_PPC_B16_BRNTAKEN - -- : BFD_RELOC_PPC_BA16 - -- : BFD_RELOC_PPC_BA16_BRTAKEN - -- : BFD_RELOC_PPC_BA16_BRNTAKEN - -- : BFD_RELOC_PPC_COPY - -- : BFD_RELOC_PPC_GLOB_DAT - -- : BFD_RELOC_PPC_JMP_SLOT - -- : BFD_RELOC_PPC_RELATIVE - -- : BFD_RELOC_PPC_LOCAL24PC - -- : BFD_RELOC_PPC_EMB_NADDR32 - -- : BFD_RELOC_PPC_EMB_NADDR16 - -- : BFD_RELOC_PPC_EMB_NADDR16_LO - -- : BFD_RELOC_PPC_EMB_NADDR16_HI - -- : BFD_RELOC_PPC_EMB_NADDR16_HA - -- : BFD_RELOC_PPC_EMB_SDAI16 - -- : BFD_RELOC_PPC_EMB_SDA2I16 - -- : BFD_RELOC_PPC_EMB_SDA2REL - -- : BFD_RELOC_PPC_EMB_SDA21 - -- : BFD_RELOC_PPC_EMB_MRKREF - -- : BFD_RELOC_PPC_EMB_RELSEC16 - -- : BFD_RELOC_PPC_EMB_RELST_LO - -- : BFD_RELOC_PPC_EMB_RELST_HI - -- : BFD_RELOC_PPC_EMB_RELST_HA - -- : BFD_RELOC_PPC_EMB_BIT_FLD - -- : BFD_RELOC_PPC_EMB_RELSDA - -- : BFD_RELOC_PPC64_HIGHER - -- : BFD_RELOC_PPC64_HIGHER_S - -- : BFD_RELOC_PPC64_HIGHEST - -- : BFD_RELOC_PPC64_HIGHEST_S - -- : BFD_RELOC_PPC64_TOC16_LO - -- : BFD_RELOC_PPC64_TOC16_HI - -- : BFD_RELOC_PPC64_TOC16_HA - -- : BFD_RELOC_PPC64_TOC - -- : BFD_RELOC_PPC64_PLTGOT16 - -- : BFD_RELOC_PPC64_PLTGOT16_LO - -- : BFD_RELOC_PPC64_PLTGOT16_HI - -- : BFD_RELOC_PPC64_PLTGOT16_HA - -- : BFD_RELOC_PPC64_ADDR16_DS - -- : BFD_RELOC_PPC64_ADDR16_LO_DS - -- : BFD_RELOC_PPC64_GOT16_DS - -- : BFD_RELOC_PPC64_GOT16_LO_DS - -- : BFD_RELOC_PPC64_PLT16_LO_DS - -- : BFD_RELOC_PPC64_SECTOFF_DS - -- : BFD_RELOC_PPC64_SECTOFF_LO_DS - -- : BFD_RELOC_PPC64_TOC16_DS - -- : BFD_RELOC_PPC64_TOC16_LO_DS - -- : BFD_RELOC_PPC64_PLTGOT16_DS - -- : BFD_RELOC_PPC64_PLTGOT16_LO_DS - Power(rs6000) and PowerPC relocations. - - -- : BFD_RELOC_PPC_TLS - -- : BFD_RELOC_PPC_DTPMOD - -- : BFD_RELOC_PPC_TPREL16 - -- : BFD_RELOC_PPC_TPREL16_LO - -- : BFD_RELOC_PPC_TPREL16_HI - -- : BFD_RELOC_PPC_TPREL16_HA - -- : BFD_RELOC_PPC_TPREL - -- : BFD_RELOC_PPC_DTPREL16 - -- : BFD_RELOC_PPC_DTPREL16_LO - -- : BFD_RELOC_PPC_DTPREL16_HI - -- : BFD_RELOC_PPC_DTPREL16_HA - -- : BFD_RELOC_PPC_DTPREL - -- : BFD_RELOC_PPC_GOT_TLSGD16 - -- : BFD_RELOC_PPC_GOT_TLSGD16_LO - -- : BFD_RELOC_PPC_GOT_TLSGD16_HI - -- : BFD_RELOC_PPC_GOT_TLSGD16_HA - -- : BFD_RELOC_PPC_GOT_TLSLD16 - -- : BFD_RELOC_PPC_GOT_TLSLD16_LO - -- : BFD_RELOC_PPC_GOT_TLSLD16_HI - -- : BFD_RELOC_PPC_GOT_TLSLD16_HA - -- : BFD_RELOC_PPC_GOT_TPREL16 - -- : BFD_RELOC_PPC_GOT_TPREL16_LO - -- : BFD_RELOC_PPC_GOT_TPREL16_HI - -- : BFD_RELOC_PPC_GOT_TPREL16_HA - -- : BFD_RELOC_PPC_GOT_DTPREL16 - -- : BFD_RELOC_PPC_GOT_DTPREL16_LO - -- : BFD_RELOC_PPC_GOT_DTPREL16_HI - -- : BFD_RELOC_PPC_GOT_DTPREL16_HA - -- : BFD_RELOC_PPC64_TPREL16_DS - -- : BFD_RELOC_PPC64_TPREL16_LO_DS - -- : BFD_RELOC_PPC64_TPREL16_HIGHER - -- : BFD_RELOC_PPC64_TPREL16_HIGHERA - -- : BFD_RELOC_PPC64_TPREL16_HIGHEST - -- : BFD_RELOC_PPC64_TPREL16_HIGHESTA - -- : BFD_RELOC_PPC64_DTPREL16_DS - -- : BFD_RELOC_PPC64_DTPREL16_LO_DS - -- : BFD_RELOC_PPC64_DTPREL16_HIGHER - -- : BFD_RELOC_PPC64_DTPREL16_HIGHERA - -- : BFD_RELOC_PPC64_DTPREL16_HIGHEST - -- : BFD_RELOC_PPC64_DTPREL16_HIGHESTA - PowerPC and PowerPC64 thread-local storage relocations. - - -- : BFD_RELOC_I370_D12 - IBM 370/390 relocations - - -- : BFD_RELOC_CTOR - The type of reloc used to build a constructor table - at the moment - probably a 32 bit wide absolute relocation, but the target can - choose. It generally does map to one of the other relocation - types. - - -- : BFD_RELOC_ARM_PCREL_BRANCH - ARM 26 bit pc-relative branch. The lowest two bits must be zero - and are not stored in the instruction. - - -- : BFD_RELOC_ARM_PCREL_BLX - ARM 26 bit pc-relative branch. The lowest bit must be zero and is - not stored in the instruction. The 2nd lowest bit comes from a 1 - bit field in the instruction. - - -- : BFD_RELOC_THUMB_PCREL_BLX - Thumb 22 bit pc-relative branch. The lowest bit must be zero and - is not stored in the instruction. The 2nd lowest bit comes from a - 1 bit field in the instruction. - - -- : BFD_RELOC_ARM_IMMEDIATE - -- : BFD_RELOC_ARM_ADRL_IMMEDIATE - -- : BFD_RELOC_ARM_OFFSET_IMM - -- : BFD_RELOC_ARM_SHIFT_IMM - -- : BFD_RELOC_ARM_SMI - -- : BFD_RELOC_ARM_SWI - -- : BFD_RELOC_ARM_MULTI - -- : BFD_RELOC_ARM_CP_OFF_IMM - -- : BFD_RELOC_ARM_CP_OFF_IMM_S2 - -- : BFD_RELOC_ARM_ADR_IMM - -- : BFD_RELOC_ARM_LDR_IMM - -- : BFD_RELOC_ARM_LITERAL - -- : BFD_RELOC_ARM_IN_POOL - -- : BFD_RELOC_ARM_OFFSET_IMM8 - -- : BFD_RELOC_ARM_HWLITERAL - -- : BFD_RELOC_ARM_THUMB_ADD - -- : BFD_RELOC_ARM_THUMB_IMM - -- : BFD_RELOC_ARM_THUMB_SHIFT - -- : BFD_RELOC_ARM_THUMB_OFFSET - -- : BFD_RELOC_ARM_GOT12 - -- : BFD_RELOC_ARM_GOT32 - -- : BFD_RELOC_ARM_JUMP_SLOT - -- : BFD_RELOC_ARM_COPY - -- : BFD_RELOC_ARM_GLOB_DAT - -- : BFD_RELOC_ARM_PLT32 - -- : BFD_RELOC_ARM_RELATIVE - -- : BFD_RELOC_ARM_GOTOFF - -- : BFD_RELOC_ARM_GOTPC - These relocs are only used within the ARM assembler. They are not - (at present) written to any object files. - - -- : BFD_RELOC_ARM_TARGET1 - Pc-relative or absolute relocation depending on target. Used for - entries in .init_array sections. - - -- : BFD_RELOC_ARM_ROSEGREL32 - Read-only segment base relative address. - - -- : BFD_RELOC_ARM_SBREL32 - Data segment base relative address. - - -- : BFD_RELOC_ARM_TARGET2 - This reloc is used for References to RTTI dta from exception - handling tables. The actual definition depends on the target. It - may be a pc-relative or some form of GOT-indirect relocation. - - -- : BFD_RELOC_ARM_PREL31 - 31-bit PC relative address. - - -- : BFD_RELOC_SH_PCDISP8BY2 - -- : BFD_RELOC_SH_PCDISP12BY2 - -- : BFD_RELOC_SH_IMM3 - -- : BFD_RELOC_SH_IMM3U - -- : BFD_RELOC_SH_DISP12 - -- : BFD_RELOC_SH_DISP12BY2 - -- : BFD_RELOC_SH_DISP12BY4 - -- : BFD_RELOC_SH_DISP12BY8 - -- : BFD_RELOC_SH_DISP20 - -- : BFD_RELOC_SH_DISP20BY8 - -- : BFD_RELOC_SH_IMM4 - -- : BFD_RELOC_SH_IMM4BY2 - -- : BFD_RELOC_SH_IMM4BY4 - -- : BFD_RELOC_SH_IMM8 - -- : BFD_RELOC_SH_IMM8BY2 - -- : BFD_RELOC_SH_IMM8BY4 - -- : BFD_RELOC_SH_PCRELIMM8BY2 - -- : BFD_RELOC_SH_PCRELIMM8BY4 - -- : BFD_RELOC_SH_SWITCH16 - -- : BFD_RELOC_SH_SWITCH32 - -- : BFD_RELOC_SH_USES - -- : BFD_RELOC_SH_COUNT - -- : BFD_RELOC_SH_ALIGN - -- : BFD_RELOC_SH_CODE - -- : BFD_RELOC_SH_DATA - -- : BFD_RELOC_SH_LABEL - -- : BFD_RELOC_SH_LOOP_START - -- : BFD_RELOC_SH_LOOP_END - -- : BFD_RELOC_SH_COPY - -- : BFD_RELOC_SH_GLOB_DAT - -- : BFD_RELOC_SH_JMP_SLOT - -- : BFD_RELOC_SH_RELATIVE - -- : BFD_RELOC_SH_GOTPC - -- : BFD_RELOC_SH_GOT_LOW16 - -- : BFD_RELOC_SH_GOT_MEDLOW16 - -- : BFD_RELOC_SH_GOT_MEDHI16 - -- : BFD_RELOC_SH_GOT_HI16 - -- : BFD_RELOC_SH_GOTPLT_LOW16 - -- : BFD_RELOC_SH_GOTPLT_MEDLOW16 - -- : BFD_RELOC_SH_GOTPLT_MEDHI16 - -- : BFD_RELOC_SH_GOTPLT_HI16 - -- : BFD_RELOC_SH_PLT_LOW16 - -- : BFD_RELOC_SH_PLT_MEDLOW16 - -- : BFD_RELOC_SH_PLT_MEDHI16 - -- : BFD_RELOC_SH_PLT_HI16 - -- : BFD_RELOC_SH_GOTOFF_LOW16 - -- : BFD_RELOC_SH_GOTOFF_MEDLOW16 - -- : BFD_RELOC_SH_GOTOFF_MEDHI16 - -- : BFD_RELOC_SH_GOTOFF_HI16 - -- : BFD_RELOC_SH_GOTPC_LOW16 - -- : BFD_RELOC_SH_GOTPC_MEDLOW16 - -- : BFD_RELOC_SH_GOTPC_MEDHI16 - -- : BFD_RELOC_SH_GOTPC_HI16 - -- : BFD_RELOC_SH_COPY64 - -- : BFD_RELOC_SH_GLOB_DAT64 - -- : BFD_RELOC_SH_JMP_SLOT64 - -- : BFD_RELOC_SH_RELATIVE64 - -- : BFD_RELOC_SH_GOT10BY4 - -- : BFD_RELOC_SH_GOT10BY8 - -- : BFD_RELOC_SH_GOTPLT10BY4 - -- : BFD_RELOC_SH_GOTPLT10BY8 - -- : BFD_RELOC_SH_GOTPLT32 - -- : BFD_RELOC_SH_SHMEDIA_CODE - -- : BFD_RELOC_SH_IMMU5 - -- : BFD_RELOC_SH_IMMS6 - -- : BFD_RELOC_SH_IMMS6BY32 - -- : BFD_RELOC_SH_IMMU6 - -- : BFD_RELOC_SH_IMMS10 - -- : BFD_RELOC_SH_IMMS10BY2 - -- : BFD_RELOC_SH_IMMS10BY4 - -- : BFD_RELOC_SH_IMMS10BY8 - -- : BFD_RELOC_SH_IMMS16 - -- : BFD_RELOC_SH_IMMU16 - -- : BFD_RELOC_SH_IMM_LOW16 - -- : BFD_RELOC_SH_IMM_LOW16_PCREL - -- : BFD_RELOC_SH_IMM_MEDLOW16 - -- : BFD_RELOC_SH_IMM_MEDLOW16_PCREL - -- : BFD_RELOC_SH_IMM_MEDHI16 - -- : BFD_RELOC_SH_IMM_MEDHI16_PCREL - -- : BFD_RELOC_SH_IMM_HI16 - -- : BFD_RELOC_SH_IMM_HI16_PCREL - -- : BFD_RELOC_SH_PT_16 - -- : BFD_RELOC_SH_TLS_GD_32 - -- : BFD_RELOC_SH_TLS_LD_32 - -- : BFD_RELOC_SH_TLS_LDO_32 - -- : BFD_RELOC_SH_TLS_IE_32 - -- : BFD_RELOC_SH_TLS_LE_32 - -- : BFD_RELOC_SH_TLS_DTPMOD32 - -- : BFD_RELOC_SH_TLS_DTPOFF32 - -- : BFD_RELOC_SH_TLS_TPOFF32 - Renesas / SuperH SH relocs. Not all of these appear in object - files. - - -- : BFD_RELOC_THUMB_PCREL_BRANCH9 - -- : BFD_RELOC_THUMB_PCREL_BRANCH12 - -- : BFD_RELOC_THUMB_PCREL_BRANCH23 - Thumb 23-, 12- and 9-bit pc-relative branches. The lowest bit must - be zero and is not stored in the instruction. - - -- : BFD_RELOC_ARC_B22_PCREL - ARC Cores relocs. ARC 22 bit pc-relative branch. The lowest two - bits must be zero and are not stored in the instruction. The high - 20 bits are installed in bits 26 through 7 of the instruction. - - -- : BFD_RELOC_ARC_B26 - ARC 26 bit absolute branch. The lowest two bits must be zero and - are not stored in the instruction. The high 24 bits are installed - in bits 23 through 0. - - -- : BFD_RELOC_D10V_10_PCREL_R - Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2 - bits assumed to be 0. - - -- : BFD_RELOC_D10V_10_PCREL_L - Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2 - bits assumed to be 0. This is the same as the previous reloc - except it is in the left container, i.e., shifted left 15 bits. - - -- : BFD_RELOC_D10V_18 - This is an 18-bit reloc with the right 2 bits assumed to be 0. - - -- : BFD_RELOC_D10V_18_PCREL - This is an 18-bit reloc with the right 2 bits assumed to be 0. - - -- : BFD_RELOC_D30V_6 - Mitsubishi D30V relocs. This is a 6-bit absolute reloc. - - -- : BFD_RELOC_D30V_9_PCREL - This is a 6-bit pc-relative reloc with the right 3 bits assumed to - be 0. - - -- : BFD_RELOC_D30V_9_PCREL_R - This is a 6-bit pc-relative reloc with the right 3 bits assumed to - be 0. Same as the previous reloc but on the right side of the - container. - - -- : BFD_RELOC_D30V_15 - This is a 12-bit absolute reloc with the right 3 bitsassumed to be - 0. - - -- : BFD_RELOC_D30V_15_PCREL - This is a 12-bit pc-relative reloc with the right 3 bits assumed - to be 0. - - -- : BFD_RELOC_D30V_15_PCREL_R - This is a 12-bit pc-relative reloc with the right 3 bits assumed - to be 0. Same as the previous reloc but on the right side of the - container. - - -- : BFD_RELOC_D30V_21 - This is an 18-bit absolute reloc with the right 3 bits assumed to - be 0. - - -- : BFD_RELOC_D30V_21_PCREL - This is an 18-bit pc-relative reloc with the right 3 bits assumed - to be 0. - - -- : BFD_RELOC_D30V_21_PCREL_R - This is an 18-bit pc-relative reloc with the right 3 bits assumed - to be 0. Same as the previous reloc but on the right side of the - container. - - -- : BFD_RELOC_D30V_32 - This is a 32-bit absolute reloc. - - -- : BFD_RELOC_D30V_32_PCREL - This is a 32-bit pc-relative reloc. - - -- : BFD_RELOC_DLX_HI16_S - DLX relocs - - -- : BFD_RELOC_DLX_LO16 - DLX relocs - - -- : BFD_RELOC_DLX_JMP26 - DLX relocs - - -- : BFD_RELOC_M32R_24 - Renesas M32R (formerly Mitsubishi M32R) relocs. This is a 24 bit - absolute address. - - -- : BFD_RELOC_M32R_10_PCREL - This is a 10-bit pc-relative reloc with the right 2 bits assumed - to be 0. - - -- : BFD_RELOC_M32R_18_PCREL - This is an 18-bit reloc with the right 2 bits assumed to be 0. - - -- : BFD_RELOC_M32R_26_PCREL - This is a 26-bit reloc with the right 2 bits assumed to be 0. - - -- : BFD_RELOC_M32R_HI16_ULO - This is a 16-bit reloc containing the high 16 bits of an address - used when the lower 16 bits are treated as unsigned. - - -- : BFD_RELOC_M32R_HI16_SLO - This is a 16-bit reloc containing the high 16 bits of an address - used when the lower 16 bits are treated as signed. - - -- : BFD_RELOC_M32R_LO16 - This is a 16-bit reloc containing the lower 16 bits of an address. - - -- : BFD_RELOC_M32R_SDA16 - This is a 16-bit reloc containing the small data area offset for - use in add3, load, and store instructions. - - -- : BFD_RELOC_M32R_GOT24 - -- : BFD_RELOC_M32R_26_PLTREL - -- : BFD_RELOC_M32R_COPY - -- : BFD_RELOC_M32R_GLOB_DAT - -- : BFD_RELOC_M32R_JMP_SLOT - -- : BFD_RELOC_M32R_RELATIVE - -- : BFD_RELOC_M32R_GOTOFF - -- : BFD_RELOC_M32R_GOTOFF_HI_ULO - -- : BFD_RELOC_M32R_GOTOFF_HI_SLO - -- : BFD_RELOC_M32R_GOTOFF_LO - -- : BFD_RELOC_M32R_GOTPC24 - -- : BFD_RELOC_M32R_GOT16_HI_ULO - -- : BFD_RELOC_M32R_GOT16_HI_SLO - -- : BFD_RELOC_M32R_GOT16_LO - -- : BFD_RELOC_M32R_GOTPC_HI_ULO - -- : BFD_RELOC_M32R_GOTPC_HI_SLO - -- : BFD_RELOC_M32R_GOTPC_LO - For PIC. - - -- : BFD_RELOC_V850_9_PCREL - This is a 9-bit reloc - - -- : BFD_RELOC_V850_22_PCREL - This is a 22-bit reloc - - -- : BFD_RELOC_V850_SDA_16_16_OFFSET - This is a 16 bit offset from the short data area pointer. - - -- : BFD_RELOC_V850_SDA_15_16_OFFSET - This is a 16 bit offset (of which only 15 bits are used) from the - short data area pointer. - - -- : BFD_RELOC_V850_ZDA_16_16_OFFSET - This is a 16 bit offset from the zero data area pointer. - - -- : BFD_RELOC_V850_ZDA_15_16_OFFSET - This is a 16 bit offset (of which only 15 bits are used) from the - zero data area pointer. - - -- : BFD_RELOC_V850_TDA_6_8_OFFSET - This is an 8 bit offset (of which only 6 bits are used) from the - tiny data area pointer. - - -- : BFD_RELOC_V850_TDA_7_8_OFFSET - This is an 8bit offset (of which only 7 bits are used) from the - tiny data area pointer. - - -- : BFD_RELOC_V850_TDA_7_7_OFFSET - This is a 7 bit offset from the tiny data area pointer. - - -- : BFD_RELOC_V850_TDA_16_16_OFFSET - This is a 16 bit offset from the tiny data area pointer. - - -- : BFD_RELOC_V850_TDA_4_5_OFFSET - This is a 5 bit offset (of which only 4 bits are used) from the - tiny data area pointer. - - -- : BFD_RELOC_V850_TDA_4_4_OFFSET - This is a 4 bit offset from the tiny data area pointer. - - -- : BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET - This is a 16 bit offset from the short data area pointer, with the - bits placed non-contiguously in the instruction. - - -- : BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET - This is a 16 bit offset from the zero data area pointer, with the - bits placed non-contiguously in the instruction. - - -- : BFD_RELOC_V850_CALLT_6_7_OFFSET - This is a 6 bit offset from the call table base pointer. - - -- : BFD_RELOC_V850_CALLT_16_16_OFFSET - This is a 16 bit offset from the call table base pointer. - - -- : BFD_RELOC_V850_LONGCALL - Used for relaxing indirect function calls. - - -- : BFD_RELOC_V850_LONGJUMP - Used for relaxing indirect jumps. - - -- : BFD_RELOC_V850_ALIGN - Used to maintain alignment whilst relaxing. - - -- : BFD_RELOC_V850_LO16_SPLIT_OFFSET - This is a variation of BFD_RELOC_LO16 that can be used in v850e - ld.bu instructions. - - -- : BFD_RELOC_MN10300_32_PCREL - This is a 32bit pcrel reloc for the mn10300, offset by two bytes - in the instruction. - - -- : BFD_RELOC_MN10300_16_PCREL - This is a 16bit pcrel reloc for the mn10300, offset by two bytes - in the instruction. - - -- : BFD_RELOC_TIC30_LDP - This is a 8bit DP reloc for the tms320c30, where the most - significant 8 bits of a 24 bit word are placed into the least - significant 8 bits of the opcode. - - -- : BFD_RELOC_TIC54X_PARTLS7 - This is a 7bit reloc for the tms320c54x, where the least - significant 7 bits of a 16 bit word are placed into the least - significant 7 bits of the opcode. - - -- : BFD_RELOC_TIC54X_PARTMS9 - This is a 9bit DP reloc for the tms320c54x, where the most - significant 9 bits of a 16 bit word are placed into the least - significant 9 bits of the opcode. - - -- : BFD_RELOC_TIC54X_23 - This is an extended address 23-bit reloc for the tms320c54x. - - -- : BFD_RELOC_TIC54X_16_OF_23 - This is a 16-bit reloc for the tms320c54x, where the least - significant 16 bits of a 23-bit extended address are placed into - the opcode. - - -- : BFD_RELOC_TIC54X_MS7_OF_23 - This is a reloc for the tms320c54x, where the most significant 7 - bits of a 23-bit extended address are placed into the opcode. - - -- : BFD_RELOC_FR30_48 - This is a 48 bit reloc for the FR30 that stores 32 bits. - - -- : BFD_RELOC_FR30_20 - This is a 32 bit reloc for the FR30 that stores 20 bits split up - into two sections. - - -- : BFD_RELOC_FR30_6_IN_4 - This is a 16 bit reloc for the FR30 that stores a 6 bit word - offset in 4 bits. - - -- : BFD_RELOC_FR30_8_IN_8 - This is a 16 bit reloc for the FR30 that stores an 8 bit byte - offset into 8 bits. - - -- : BFD_RELOC_FR30_9_IN_8 - This is a 16 bit reloc for the FR30 that stores a 9 bit short - offset into 8 bits. - - -- : BFD_RELOC_FR30_10_IN_8 - This is a 16 bit reloc for the FR30 that stores a 10 bit word - offset into 8 bits. - - -- : BFD_RELOC_FR30_9_PCREL - This is a 16 bit reloc for the FR30 that stores a 9 bit pc relative - short offset into 8 bits. - - -- : BFD_RELOC_FR30_12_PCREL - This is a 16 bit reloc for the FR30 that stores a 12 bit pc - relative short offset into 11 bits. - - -- : BFD_RELOC_MCORE_PCREL_IMM8BY4 - -- : BFD_RELOC_MCORE_PCREL_IMM11BY2 - -- : BFD_RELOC_MCORE_PCREL_IMM4BY2 - -- : BFD_RELOC_MCORE_PCREL_32 - -- : BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2 - -- : BFD_RELOC_MCORE_RVA - Motorola Mcore relocations. - - -- : BFD_RELOC_MMIX_GETA - -- : BFD_RELOC_MMIX_GETA_1 - -- : BFD_RELOC_MMIX_GETA_2 - -- : BFD_RELOC_MMIX_GETA_3 - These are relocations for the GETA instruction. - - -- : BFD_RELOC_MMIX_CBRANCH - -- : BFD_RELOC_MMIX_CBRANCH_J - -- : BFD_RELOC_MMIX_CBRANCH_1 - -- : BFD_RELOC_MMIX_CBRANCH_2 - -- : BFD_RELOC_MMIX_CBRANCH_3 - These are relocations for a conditional branch instruction. - - -- : BFD_RELOC_MMIX_PUSHJ - -- : BFD_RELOC_MMIX_PUSHJ_1 - -- : BFD_RELOC_MMIX_PUSHJ_2 - -- : BFD_RELOC_MMIX_PUSHJ_3 - -- : BFD_RELOC_MMIX_PUSHJ_STUBBABLE - These are relocations for the PUSHJ instruction. - - -- : BFD_RELOC_MMIX_JMP - -- : BFD_RELOC_MMIX_JMP_1 - -- : BFD_RELOC_MMIX_JMP_2 - -- : BFD_RELOC_MMIX_JMP_3 - These are relocations for the JMP instruction. - - -- : BFD_RELOC_MMIX_ADDR19 - This is a relocation for a relative address as in a GETA - instruction or a branch. - - -- : BFD_RELOC_MMIX_ADDR27 - This is a relocation for a relative address as in a JMP - instruction. - - -- : BFD_RELOC_MMIX_REG_OR_BYTE - This is a relocation for an instruction field that may be a general - register or a value 0..255. - - -- : BFD_RELOC_MMIX_REG - This is a relocation for an instruction field that may be a general - register. - - -- : BFD_RELOC_MMIX_BASE_PLUS_OFFSET - This is a relocation for two instruction fields holding a register - and an offset, the equivalent of the relocation. - - -- : BFD_RELOC_MMIX_LOCAL - This relocation is an assertion that the expression is not - allocated as a global register. It does not modify contents. - - -- : BFD_RELOC_AVR_7_PCREL - This is a 16 bit reloc for the AVR that stores 8 bit pc relative - short offset into 7 bits. - - -- : BFD_RELOC_AVR_13_PCREL - This is a 16 bit reloc for the AVR that stores 13 bit pc relative - short offset into 12 bits. - - -- : BFD_RELOC_AVR_16_PM - This is a 16 bit reloc for the AVR that stores 17 bit value - (usually program memory address) into 16 bits. - - -- : BFD_RELOC_AVR_LO8_LDI - This is a 16 bit reloc for the AVR that stores 8 bit value (usually - data memory address) into 8 bit immediate value of LDI insn. - - -- : BFD_RELOC_AVR_HI8_LDI - This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 - bit of data memory address) into 8 bit immediate value of LDI insn. - - -- : BFD_RELOC_AVR_HH8_LDI - This is a 16 bit reloc for the AVR that stores 8 bit value (most - high 8 bit of program memory address) into 8 bit immediate value - of LDI insn. - - -- : BFD_RELOC_AVR_LO8_LDI_NEG - This is a 16 bit reloc for the AVR that stores negated 8 bit value - (usually data memory address) into 8 bit immediate value of SUBI - insn. - - -- : BFD_RELOC_AVR_HI8_LDI_NEG - This is a 16 bit reloc for the AVR that stores negated 8 bit value - (high 8 bit of data memory address) into 8 bit immediate value of - SUBI insn. - - -- : BFD_RELOC_AVR_HH8_LDI_NEG - This is a 16 bit reloc for the AVR that stores negated 8 bit value - (most high 8 bit of program memory address) into 8 bit immediate - value of LDI or SUBI insn. - - -- : BFD_RELOC_AVR_LO8_LDI_PM - This is a 16 bit reloc for the AVR that stores 8 bit value (usually - command address) into 8 bit immediate value of LDI insn. - - -- : BFD_RELOC_AVR_HI8_LDI_PM - This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 - bit of command address) into 8 bit immediate value of LDI insn. - - -- : BFD_RELOC_AVR_HH8_LDI_PM - This is a 16 bit reloc for the AVR that stores 8 bit value (most - high 8 bit of command address) into 8 bit immediate value of LDI - insn. - - -- : BFD_RELOC_AVR_LO8_LDI_PM_NEG - This is a 16 bit reloc for the AVR that stores negated 8 bit value - (usually command address) into 8 bit immediate value of SUBI insn. - - -- : BFD_RELOC_AVR_HI8_LDI_PM_NEG - This is a 16 bit reloc for the AVR that stores negated 8 bit value - (high 8 bit of 16 bit command address) into 8 bit immediate value - of SUBI insn. - - -- : BFD_RELOC_AVR_HH8_LDI_PM_NEG - This is a 16 bit reloc for the AVR that stores negated 8 bit value - (high 6 bit of 22 bit command address) into 8 bit immediate value - of SUBI insn. - - -- : BFD_RELOC_AVR_CALL - This is a 32 bit reloc for the AVR that stores 23 bit value into - 22 bits. - - -- : BFD_RELOC_AVR_LDI - This is a 16 bit reloc for the AVR that stores all needed bits for - absolute addressing with ldi with overflow check to linktime - - -- : BFD_RELOC_AVR_6 - This is a 6 bit reloc for the AVR that stores offset for ldd/std - instructions - - -- : BFD_RELOC_AVR_6_ADIW - This is a 6 bit reloc for the AVR that stores offset for adiw/sbiw - instructions - - -- : BFD_RELOC_390_12 - Direct 12 bit. - - -- : BFD_RELOC_390_GOT12 - 12 bit GOT offset. - - -- : BFD_RELOC_390_PLT32 - 32 bit PC relative PLT address. - - -- : BFD_RELOC_390_COPY - Copy symbol at runtime. - - -- : BFD_RELOC_390_GLOB_DAT - Create GOT entry. - - -- : BFD_RELOC_390_JMP_SLOT - Create PLT entry. - - -- : BFD_RELOC_390_RELATIVE - Adjust by program base. - - -- : BFD_RELOC_390_GOTPC - 32 bit PC relative offset to GOT. - - -- : BFD_RELOC_390_GOT16 - 16 bit GOT offset. - - -- : BFD_RELOC_390_PC16DBL - PC relative 16 bit shifted by 1. - - -- : BFD_RELOC_390_PLT16DBL - 16 bit PC rel. PLT shifted by 1. - - -- : BFD_RELOC_390_PC32DBL - PC relative 32 bit shifted by 1. - - -- : BFD_RELOC_390_PLT32DBL - 32 bit PC rel. PLT shifted by 1. - - -- : BFD_RELOC_390_GOTPCDBL - 32 bit PC rel. GOT shifted by 1. - - -- : BFD_RELOC_390_GOT64 - 64 bit GOT offset. - - -- : BFD_RELOC_390_PLT64 - 64 bit PC relative PLT address. - - -- : BFD_RELOC_390_GOTENT - 32 bit rel. offset to GOT entry. - - -- : BFD_RELOC_390_GOTOFF64 - 64 bit offset to GOT. - - -- : BFD_RELOC_390_GOTPLT12 - 12-bit offset to symbol-entry within GOT, with PLT handling. - - -- : BFD_RELOC_390_GOTPLT16 - 16-bit offset to symbol-entry within GOT, with PLT handling. - - -- : BFD_RELOC_390_GOTPLT32 - 32-bit offset to symbol-entry within GOT, with PLT handling. - - -- : BFD_RELOC_390_GOTPLT64 - 64-bit offset to symbol-entry within GOT, with PLT handling. - - -- : BFD_RELOC_390_GOTPLTENT - 32-bit rel. offset to symbol-entry within GOT, with PLT handling. - - -- : BFD_RELOC_390_PLTOFF16 - 16-bit rel. offset from the GOT to a PLT entry. - - -- : BFD_RELOC_390_PLTOFF32 - 32-bit rel. offset from the GOT to a PLT entry. - - -- : BFD_RELOC_390_PLTOFF64 - 64-bit rel. offset from the GOT to a PLT entry. - - -- : BFD_RELOC_390_TLS_LOAD - -- : BFD_RELOC_390_TLS_GDCALL - -- : BFD_RELOC_390_TLS_LDCALL - -- : BFD_RELOC_390_TLS_GD32 - -- : BFD_RELOC_390_TLS_GD64 - -- : BFD_RELOC_390_TLS_GOTIE12 - -- : BFD_RELOC_390_TLS_GOTIE32 - -- : BFD_RELOC_390_TLS_GOTIE64 - -- : BFD_RELOC_390_TLS_LDM32 - -- : BFD_RELOC_390_TLS_LDM64 - -- : BFD_RELOC_390_TLS_IE32 - -- : BFD_RELOC_390_TLS_IE64 - -- : BFD_RELOC_390_TLS_IEENT - -- : BFD_RELOC_390_TLS_LE32 - -- : BFD_RELOC_390_TLS_LE64 - -- : BFD_RELOC_390_TLS_LDO32 - -- : BFD_RELOC_390_TLS_LDO64 - -- : BFD_RELOC_390_TLS_DTPMOD - -- : BFD_RELOC_390_TLS_DTPOFF - -- : BFD_RELOC_390_TLS_TPOFF - s390 tls relocations. - - -- : BFD_RELOC_390_20 - -- : BFD_RELOC_390_GOT20 - -- : BFD_RELOC_390_GOTPLT20 - -- : BFD_RELOC_390_TLS_GOTIE20 - Long displacement extension. - - -- : BFD_RELOC_IP2K_FR9 - Scenix IP2K - 9-bit register number / data address - - -- : BFD_RELOC_IP2K_BANK - Scenix IP2K - 4-bit register/data bank number - - -- : BFD_RELOC_IP2K_ADDR16CJP - Scenix IP2K - low 13 bits of instruction word address - - -- : BFD_RELOC_IP2K_PAGE3 - Scenix IP2K - high 3 bits of instruction word address - - -- : BFD_RELOC_IP2K_LO8DATA - -- : BFD_RELOC_IP2K_HI8DATA - -- : BFD_RELOC_IP2K_EX8DATA - Scenix IP2K - ext/low/high 8 bits of data address - - -- : BFD_RELOC_IP2K_LO8INSN - -- : BFD_RELOC_IP2K_HI8INSN - Scenix IP2K - low/high 8 bits of instruction word address - - -- : BFD_RELOC_IP2K_PC_SKIP - Scenix IP2K - even/odd PC modifier to modify snb pcl.0 - - -- : BFD_RELOC_IP2K_TEXT - Scenix IP2K - 16 bit word address in text section. - - -- : BFD_RELOC_IP2K_FR_OFFSET - Scenix IP2K - 7-bit sp or dp offset - - -- : BFD_RELOC_VPE4KMATH_DATA - -- : BFD_RELOC_VPE4KMATH_INSN - Scenix VPE4K coprocessor - data/insn-space addressing - - -- : BFD_RELOC_VTABLE_INHERIT - -- : BFD_RELOC_VTABLE_ENTRY - These two relocations are used by the linker to determine which of - the entries in a C++ virtual function table are actually used. - When the -gc-sections option is given, the linker will zero out - the entries that are not used, so that the code for those - functions need not be included in the output. - - VTABLE_INHERIT is a zero-space relocation used to describe to the - linker the inheritance tree of a C++ virtual function table. The - relocation's symbol should be the parent class' vtable, and the - relocation should be located at the child vtable. - - VTABLE_ENTRY is a zero-space relocation that describes the use of a - virtual function table entry. The reloc's symbol should refer to - the table of the class mentioned in the code. Off of that base, - an offset describes the entry that is being used. For Rela hosts, - this offset is stored in the reloc's addend. For Rel hosts, we - are forced to put this offset in the reloc's section offset. - - -- : BFD_RELOC_IA64_IMM14 - -- : BFD_RELOC_IA64_IMM22 - -- : BFD_RELOC_IA64_IMM64 - -- : BFD_RELOC_IA64_DIR32MSB - -- : BFD_RELOC_IA64_DIR32LSB - -- : BFD_RELOC_IA64_DIR64MSB - -- : BFD_RELOC_IA64_DIR64LSB - -- : BFD_RELOC_IA64_GPREL22 - -- : BFD_RELOC_IA64_GPREL64I - -- : BFD_RELOC_IA64_GPREL32MSB - -- : BFD_RELOC_IA64_GPREL32LSB - -- : BFD_RELOC_IA64_GPREL64MSB - -- : BFD_RELOC_IA64_GPREL64LSB - -- : BFD_RELOC_IA64_LTOFF22 - -- : BFD_RELOC_IA64_LTOFF64I - -- : BFD_RELOC_IA64_PLTOFF22 - -- : BFD_RELOC_IA64_PLTOFF64I - -- : BFD_RELOC_IA64_PLTOFF64MSB - -- : BFD_RELOC_IA64_PLTOFF64LSB - -- : BFD_RELOC_IA64_FPTR64I - -- : BFD_RELOC_IA64_FPTR32MSB - -- : BFD_RELOC_IA64_FPTR32LSB - -- : BFD_RELOC_IA64_FPTR64MSB - -- : BFD_RELOC_IA64_FPTR64LSB - -- : BFD_RELOC_IA64_PCREL21B - -- : BFD_RELOC_IA64_PCREL21BI - -- : BFD_RELOC_IA64_PCREL21M - -- : BFD_RELOC_IA64_PCREL21F - -- : BFD_RELOC_IA64_PCREL22 - -- : BFD_RELOC_IA64_PCREL60B - -- : BFD_RELOC_IA64_PCREL64I - -- : BFD_RELOC_IA64_PCREL32MSB - -- : BFD_RELOC_IA64_PCREL32LSB - -- : BFD_RELOC_IA64_PCREL64MSB - -- : BFD_RELOC_IA64_PCREL64LSB - -- : BFD_RELOC_IA64_LTOFF_FPTR22 - -- : BFD_RELOC_IA64_LTOFF_FPTR64I - -- : BFD_RELOC_IA64_LTOFF_FPTR32MSB - -- : BFD_RELOC_IA64_LTOFF_FPTR32LSB - -- : BFD_RELOC_IA64_LTOFF_FPTR64MSB - -- : BFD_RELOC_IA64_LTOFF_FPTR64LSB - -- : BFD_RELOC_IA64_SEGREL32MSB - -- : BFD_RELOC_IA64_SEGREL32LSB - -- : BFD_RELOC_IA64_SEGREL64MSB - -- : BFD_RELOC_IA64_SEGREL64LSB - -- : BFD_RELOC_IA64_SECREL32MSB - -- : BFD_RELOC_IA64_SECREL32LSB - -- : BFD_RELOC_IA64_SECREL64MSB - -- : BFD_RELOC_IA64_SECREL64LSB - -- : BFD_RELOC_IA64_REL32MSB - -- : BFD_RELOC_IA64_REL32LSB - -- : BFD_RELOC_IA64_REL64MSB - -- : BFD_RELOC_IA64_REL64LSB - -- : BFD_RELOC_IA64_LTV32MSB - -- : BFD_RELOC_IA64_LTV32LSB - -- : BFD_RELOC_IA64_LTV64MSB - -- : BFD_RELOC_IA64_LTV64LSB - -- : BFD_RELOC_IA64_IPLTMSB - -- : BFD_RELOC_IA64_IPLTLSB - -- : BFD_RELOC_IA64_COPY - -- : BFD_RELOC_IA64_LTOFF22X - -- : BFD_RELOC_IA64_LDXMOV - -- : BFD_RELOC_IA64_TPREL14 - -- : BFD_RELOC_IA64_TPREL22 - -- : BFD_RELOC_IA64_TPREL64I - -- : BFD_RELOC_IA64_TPREL64MSB - -- : BFD_RELOC_IA64_TPREL64LSB - -- : BFD_RELOC_IA64_LTOFF_TPREL22 - -- : BFD_RELOC_IA64_DTPMOD64MSB - -- : BFD_RELOC_IA64_DTPMOD64LSB - -- : BFD_RELOC_IA64_LTOFF_DTPMOD22 - -- : BFD_RELOC_IA64_DTPREL14 - -- : BFD_RELOC_IA64_DTPREL22 - -- : BFD_RELOC_IA64_DTPREL64I - -- : BFD_RELOC_IA64_DTPREL32MSB - -- : BFD_RELOC_IA64_DTPREL32LSB - -- : BFD_RELOC_IA64_DTPREL64MSB - -- : BFD_RELOC_IA64_DTPREL64LSB - -- : BFD_RELOC_IA64_LTOFF_DTPREL22 - Intel IA64 Relocations. - - -- : BFD_RELOC_M68HC11_HI8 - Motorola 68HC11 reloc. This is the 8 bit high part of an absolute - address. - - -- : BFD_RELOC_M68HC11_LO8 - Motorola 68HC11 reloc. This is the 8 bit low part of an absolute - address. - - -- : BFD_RELOC_M68HC11_3B - Motorola 68HC11 reloc. This is the 3 bit of a value. - - -- : BFD_RELOC_M68HC11_RL_JUMP - Motorola 68HC11 reloc. This reloc marks the beginning of a - jump/call instruction. It is used for linker relaxation to - correctly identify beginning of instruction and change some - branches to use PC-relative addressing mode. - - -- : BFD_RELOC_M68HC11_RL_GROUP - Motorola 68HC11 reloc. This reloc marks a group of several - instructions that gcc generates and for which the linker - relaxation pass can modify and/or remove some of them. - - -- : BFD_RELOC_M68HC11_LO16 - Motorola 68HC11 reloc. This is the 16-bit lower part of an - address. It is used for 'call' instruction to specify the symbol - address without any special transformation (due to memory bank - window). - - -- : BFD_RELOC_M68HC11_PAGE - Motorola 68HC11 reloc. This is a 8-bit reloc that specifies the - page number of an address. It is used by 'call' instruction to - specify the page number of the symbol. - - -- : BFD_RELOC_M68HC11_24 - Motorola 68HC11 reloc. This is a 24-bit reloc that represents the - address with a 16-bit value and a 8-bit page number. The symbol - address is transformed to follow the 16K memory bank of 68HC12 - (seen as mapped in the window). - - -- : BFD_RELOC_M68HC12_5B - Motorola 68HC12 reloc. This is the 5 bits of a value. - - -- : BFD_RELOC_16C_NUM08 - -- : BFD_RELOC_16C_NUM08_C - -- : BFD_RELOC_16C_NUM16 - -- : BFD_RELOC_16C_NUM16_C - -- : BFD_RELOC_16C_NUM32 - -- : BFD_RELOC_16C_NUM32_C - -- : BFD_RELOC_16C_DISP04 - -- : BFD_RELOC_16C_DISP04_C - -- : BFD_RELOC_16C_DISP08 - -- : BFD_RELOC_16C_DISP08_C - -- : BFD_RELOC_16C_DISP16 - -- : BFD_RELOC_16C_DISP16_C - -- : BFD_RELOC_16C_DISP24 - -- : BFD_RELOC_16C_DISP24_C - -- : BFD_RELOC_16C_DISP24a - -- : BFD_RELOC_16C_DISP24a_C - -- : BFD_RELOC_16C_REG04 - -- : BFD_RELOC_16C_REG04_C - -- : BFD_RELOC_16C_REG04a - -- : BFD_RELOC_16C_REG04a_C - -- : BFD_RELOC_16C_REG14 - -- : BFD_RELOC_16C_REG14_C - -- : BFD_RELOC_16C_REG16 - -- : BFD_RELOC_16C_REG16_C - -- : BFD_RELOC_16C_REG20 - -- : BFD_RELOC_16C_REG20_C - -- : BFD_RELOC_16C_ABS20 - -- : BFD_RELOC_16C_ABS20_C - -- : BFD_RELOC_16C_ABS24 - -- : BFD_RELOC_16C_ABS24_C - -- : BFD_RELOC_16C_IMM04 - -- : BFD_RELOC_16C_IMM04_C - -- : BFD_RELOC_16C_IMM16 - -- : BFD_RELOC_16C_IMM16_C - -- : BFD_RELOC_16C_IMM20 - -- : BFD_RELOC_16C_IMM20_C - -- : BFD_RELOC_16C_IMM24 - -- : BFD_RELOC_16C_IMM24_C - -- : BFD_RELOC_16C_IMM32 - -- : BFD_RELOC_16C_IMM32_C - NS CR16C Relocations. - - -- : BFD_RELOC_CRX_REL4 - -- : BFD_RELOC_CRX_REL8 - -- : BFD_RELOC_CRX_REL8_CMP - -- : BFD_RELOC_CRX_REL16 - -- : BFD_RELOC_CRX_REL24 - -- : BFD_RELOC_CRX_REL32 - -- : BFD_RELOC_CRX_REGREL12 - -- : BFD_RELOC_CRX_REGREL22 - -- : BFD_RELOC_CRX_REGREL28 - -- : BFD_RELOC_CRX_REGREL32 - -- : BFD_RELOC_CRX_ABS16 - -- : BFD_RELOC_CRX_ABS32 - -- : BFD_RELOC_CRX_NUM8 - -- : BFD_RELOC_CRX_NUM16 - -- : BFD_RELOC_CRX_NUM32 - -- : BFD_RELOC_CRX_IMM16 - -- : BFD_RELOC_CRX_IMM32 - -- : BFD_RELOC_CRX_SWITCH8 - -- : BFD_RELOC_CRX_SWITCH16 - -- : BFD_RELOC_CRX_SWITCH32 - NS CRX Relocations. - - -- : BFD_RELOC_CRIS_BDISP8 - -- : BFD_RELOC_CRIS_UNSIGNED_5 - -- : BFD_RELOC_CRIS_SIGNED_6 - -- : BFD_RELOC_CRIS_UNSIGNED_6 - -- : BFD_RELOC_CRIS_SIGNED_8 - -- : BFD_RELOC_CRIS_UNSIGNED_8 - -- : BFD_RELOC_CRIS_SIGNED_16 - -- : BFD_RELOC_CRIS_UNSIGNED_16 - -- : BFD_RELOC_CRIS_LAPCQ_OFFSET - -- : BFD_RELOC_CRIS_UNSIGNED_4 - These relocs are only used within the CRIS assembler. They are not - (at present) written to any object files. - - -- : BFD_RELOC_CRIS_COPY - -- : BFD_RELOC_CRIS_GLOB_DAT - -- : BFD_RELOC_CRIS_JUMP_SLOT - -- : BFD_RELOC_CRIS_RELATIVE - Relocs used in ELF shared libraries for CRIS. - - -- : BFD_RELOC_CRIS_32_GOT - 32-bit offset to symbol-entry within GOT. - - -- : BFD_RELOC_CRIS_16_GOT - 16-bit offset to symbol-entry within GOT. - - -- : BFD_RELOC_CRIS_32_GOTPLT - 32-bit offset to symbol-entry within GOT, with PLT handling. - - -- : BFD_RELOC_CRIS_16_GOTPLT - 16-bit offset to symbol-entry within GOT, with PLT handling. - - -- : BFD_RELOC_CRIS_32_GOTREL - 32-bit offset to symbol, relative to GOT. - - -- : BFD_RELOC_CRIS_32_PLT_GOTREL - 32-bit offset to symbol with PLT entry, relative to GOT. - - -- : BFD_RELOC_CRIS_32_PLT_PCREL - 32-bit offset to symbol with PLT entry, relative to this - relocation. - - -- : BFD_RELOC_860_COPY - -- : BFD_RELOC_860_GLOB_DAT - -- : BFD_RELOC_860_JUMP_SLOT - -- : BFD_RELOC_860_RELATIVE - -- : BFD_RELOC_860_PC26 - -- : BFD_RELOC_860_PLT26 - -- : BFD_RELOC_860_PC16 - -- : BFD_RELOC_860_LOW0 - -- : BFD_RELOC_860_SPLIT0 - -- : BFD_RELOC_860_LOW1 - -- : BFD_RELOC_860_SPLIT1 - -- : BFD_RELOC_860_LOW2 - -- : BFD_RELOC_860_SPLIT2 - -- : BFD_RELOC_860_LOW3 - -- : BFD_RELOC_860_LOGOT0 - -- : BFD_RELOC_860_SPGOT0 - -- : BFD_RELOC_860_LOGOT1 - -- : BFD_RELOC_860_SPGOT1 - -- : BFD_RELOC_860_LOGOTOFF0 - -- : BFD_RELOC_860_SPGOTOFF0 - -- : BFD_RELOC_860_LOGOTOFF1 - -- : BFD_RELOC_860_SPGOTOFF1 - -- : BFD_RELOC_860_LOGOTOFF2 - -- : BFD_RELOC_860_LOGOTOFF3 - -- : BFD_RELOC_860_LOPC - -- : BFD_RELOC_860_HIGHADJ - -- : BFD_RELOC_860_HAGOT - -- : BFD_RELOC_860_HAGOTOFF - -- : BFD_RELOC_860_HAPC - -- : BFD_RELOC_860_HIGH - -- : BFD_RELOC_860_HIGOT - -- : BFD_RELOC_860_HIGOTOFF - Intel i860 Relocations. - - -- : BFD_RELOC_OPENRISC_ABS_26 - -- : BFD_RELOC_OPENRISC_REL_26 - OpenRISC Relocations. - - -- : BFD_RELOC_H8_DIR16A8 - -- : BFD_RELOC_H8_DIR16R8 - -- : BFD_RELOC_H8_DIR24A8 - -- : BFD_RELOC_H8_DIR24R8 - -- : BFD_RELOC_H8_DIR32A16 - H8 elf Relocations. - - -- : BFD_RELOC_XSTORMY16_REL_12 - -- : BFD_RELOC_XSTORMY16_12 - -- : BFD_RELOC_XSTORMY16_24 - -- : BFD_RELOC_XSTORMY16_FPTR16 - Sony Xstormy16 Relocations. - - -- : BFD_RELOC_VAX_GLOB_DAT - -- : BFD_RELOC_VAX_JMP_SLOT - -- : BFD_RELOC_VAX_RELATIVE - Relocations used by VAX ELF. - - -- : BFD_RELOC_MSP430_10_PCREL - -- : BFD_RELOC_MSP430_16_PCREL - -- : BFD_RELOC_MSP430_16 - -- : BFD_RELOC_MSP430_16_PCREL_BYTE - -- : BFD_RELOC_MSP430_16_BYTE - -- : BFD_RELOC_MSP430_2X_PCREL - -- : BFD_RELOC_MSP430_RL_PCREL - msp430 specific relocation codes - - -- : BFD_RELOC_IQ2000_OFFSET_16 - -- : BFD_RELOC_IQ2000_OFFSET_21 - -- : BFD_RELOC_IQ2000_UHI16 - IQ2000 Relocations. - - -- : BFD_RELOC_XTENSA_RTLD - Special Xtensa relocation used only by PLT entries in ELF shared - objects to indicate that the runtime linker should set the value - to one of its own internal functions or data structures. - - -- : BFD_RELOC_XTENSA_GLOB_DAT - -- : BFD_RELOC_XTENSA_JMP_SLOT - -- : BFD_RELOC_XTENSA_RELATIVE - Xtensa relocations for ELF shared objects. - - -- : BFD_RELOC_XTENSA_PLT - Xtensa relocation used in ELF object files for symbols that may - require PLT entries. Otherwise, this is just a generic 32-bit - relocation. - - -- : BFD_RELOC_XTENSA_DIFF8 - -- : BFD_RELOC_XTENSA_DIFF16 - -- : BFD_RELOC_XTENSA_DIFF32 - Xtensa relocations to mark the difference of two local symbols. - These are only needed to support linker relaxation and can be - ignored when not relaxing. The field is set to the value of the - difference assuming no relaxation. The relocation encodes the - position of the first symbol so the linker can determine whether - to adjust the field value. - - -- : BFD_RELOC_XTENSA_SLOT0_OP - -- : BFD_RELOC_XTENSA_SLOT1_OP - -- : BFD_RELOC_XTENSA_SLOT2_OP - -- : BFD_RELOC_XTENSA_SLOT3_OP - -- : BFD_RELOC_XTENSA_SLOT4_OP - -- : BFD_RELOC_XTENSA_SLOT5_OP - -- : BFD_RELOC_XTENSA_SLOT6_OP - -- : BFD_RELOC_XTENSA_SLOT7_OP - -- : BFD_RELOC_XTENSA_SLOT8_OP - -- : BFD_RELOC_XTENSA_SLOT9_OP - -- : BFD_RELOC_XTENSA_SLOT10_OP - -- : BFD_RELOC_XTENSA_SLOT11_OP - -- : BFD_RELOC_XTENSA_SLOT12_OP - -- : BFD_RELOC_XTENSA_SLOT13_OP - -- : BFD_RELOC_XTENSA_SLOT14_OP - Generic Xtensa relocations for instruction operands. Only the slot - number is encoded in the relocation. The relocation applies to the - last PC-relative immediate operand, or if there are no PC-relative - immediates, to the last immediate operand. - - -- : BFD_RELOC_XTENSA_SLOT0_ALT - -- : BFD_RELOC_XTENSA_SLOT1_ALT - -- : BFD_RELOC_XTENSA_SLOT2_ALT - -- : BFD_RELOC_XTENSA_SLOT3_ALT - -- : BFD_RELOC_XTENSA_SLOT4_ALT - -- : BFD_RELOC_XTENSA_SLOT5_ALT - -- : BFD_RELOC_XTENSA_SLOT6_ALT - -- : BFD_RELOC_XTENSA_SLOT7_ALT - -- : BFD_RELOC_XTENSA_SLOT8_ALT - -- : BFD_RELOC_XTENSA_SLOT9_ALT - -- : BFD_RELOC_XTENSA_SLOT10_ALT - -- : BFD_RELOC_XTENSA_SLOT11_ALT - -- : BFD_RELOC_XTENSA_SLOT12_ALT - -- : BFD_RELOC_XTENSA_SLOT13_ALT - -- : BFD_RELOC_XTENSA_SLOT14_ALT - Alternate Xtensa relocations. Only the slot is encoded in the - relocation. The meaning of these relocations is opcode-specific. - - -- : BFD_RELOC_XTENSA_OP0 - -- : BFD_RELOC_XTENSA_OP1 - -- : BFD_RELOC_XTENSA_OP2 - Xtensa relocations for backward compatibility. These have all been - replaced by BFD_RELOC_XTENSA_SLOT0_OP. - - -- : BFD_RELOC_XTENSA_ASM_EXPAND - Xtensa relocation to mark that the assembler expanded the - instructions from an original target. The expansion size is - encoded in the reloc size. - - -- : BFD_RELOC_XTENSA_ASM_SIMPLIFY - Xtensa relocation to mark that the linker should simplify - assembler-expanded instructions. This is commonly used internally - by the linker after analysis of a BFD_RELOC_XTENSA_ASM_EXPAND. - - - typedef enum bfd_reloc_code_real bfd_reloc_code_real_type; - -2.11.0.2 `bfd_reloc_type_lookup' -................................ - -*Synopsis* - reloc_howto_type *bfd_reloc_type_lookup - (bfd *abfd, bfd_reloc_code_real_type code); - *Description* -Return a pointer to a howto structure which, when invoked, will perform -the relocation CODE on data from the architecture noted. - -2.11.0.3 `bfd_default_reloc_type_lookup' -........................................ - -*Synopsis* - reloc_howto_type *bfd_default_reloc_type_lookup - (bfd *abfd, bfd_reloc_code_real_type code); - *Description* -Provides a default relocation lookup routine for any architecture. - -2.11.0.4 `bfd_get_reloc_code_name' -.................................. - -*Synopsis* - const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code); - *Description* -Provides a printable name for the supplied relocation code. Useful -mainly for printing error messages. - -2.11.0.5 `bfd_generic_relax_section' -.................................... - -*Synopsis* - bfd_boolean bfd_generic_relax_section - (bfd *abfd, - asection *section, - struct bfd_link_info *, - bfd_boolean *); - *Description* -Provides default handling for relaxing for back ends which don't do -relaxing. - -2.11.0.6 `bfd_generic_gc_sections' -.................................. - -*Synopsis* - bfd_boolean bfd_generic_gc_sections - (bfd *, struct bfd_link_info *); - *Description* -Provides default handling for relaxing for back ends which don't do -section gc - i.e., does nothing. - -2.11.0.7 `bfd_generic_merge_sections' -..................................... - -*Synopsis* - bfd_boolean bfd_generic_merge_sections - (bfd *, struct bfd_link_info *); - *Description* -Provides default handling for SEC_MERGE section merging for back ends -which don't have SEC_MERGE support - i.e., does nothing. - -2.11.0.8 `bfd_generic_get_relocated_section_contents' -..................................................... - -*Synopsis* - bfd_byte *bfd_generic_get_relocated_section_contents - (bfd *abfd, - struct bfd_link_info *link_info, - struct bfd_link_order *link_order, - bfd_byte *data, - bfd_boolean relocatable, - asymbol **symbols); - *Description* -Provides default handling of relocation effort for back ends which -can't be bothered to do it efficiently. - - -File: bfd.info, Node: Core Files, Next: Targets, Prev: Relocations, Up: BFD front end - -2.12 Core files -=============== - -*Description* -These are functions pertaining to core files. - -2.12.0.1 `bfd_core_file_failing_command' -........................................ - -*Synopsis* - const char *bfd_core_file_failing_command (bfd *abfd); - *Description* -Return a read-only string explaining which program was running when it -failed and produced the core file ABFD. - -2.12.0.2 `bfd_core_file_failing_signal' -....................................... - -*Synopsis* - int bfd_core_file_failing_signal (bfd *abfd); - *Description* -Returns the signal number which caused the core dump which generated -the file the BFD ABFD is attached to. - -2.12.0.3 `core_file_matches_executable_p' -......................................... - -*Synopsis* - bfd_boolean core_file_matches_executable_p - (bfd *core_bfd, bfd *exec_bfd); - *Description* -Return `TRUE' if the core file attached to CORE_BFD was generated by a -run of the executable file attached to EXEC_BFD, `FALSE' otherwise. - - -File: bfd.info, Node: Targets, Next: Architectures, Prev: Core Files, Up: BFD front end - -2.13 Targets -============ - -*Description* -Each port of BFD to a different machine requires the creation of a -target back end. All the back end provides to the root part of BFD is a -structure containing pointers to functions which perform certain low -level operations on files. BFD translates the applications's requests -through a pointer into calls to the back end routines. - - When a file is opened with `bfd_openr', its format and target are -unknown. BFD uses various mechanisms to determine how to interpret the -file. The operations performed are: - - * Create a BFD by calling the internal routine `_bfd_new_bfd', then - call `bfd_find_target' with the target string supplied to - `bfd_openr' and the new BFD pointer. - - * If a null target string was provided to `bfd_find_target', look up - the environment variable `GNUTARGET' and use that as the target - string. - - * If the target string is still `NULL', or the target string is - `default', then use the first item in the target vector as the - target type, and set `target_defaulted' in the BFD to cause - `bfd_check_format' to loop through all the targets. *Note - bfd_target::. *Note Formats::. - - * Otherwise, inspect the elements in the target vector one by one, - until a match on target name is found. When found, use it. - - * Otherwise return the error `bfd_error_invalid_target' to - `bfd_openr'. - - * `bfd_openr' attempts to open the file using `bfd_open_file', and - returns the BFD. - Once the BFD has been opened and the target selected, the file -format may be determined. This is done by calling `bfd_check_format' on -the BFD with a suggested format. If `target_defaulted' has been set, -each possible target type is tried to see if it recognizes the -specified format. `bfd_check_format' returns `TRUE' when the caller -guesses right. - -* Menu: - -* bfd_target:: - - -File: bfd.info, Node: bfd_target, Prev: Targets, Up: Targets - -2.13.1 bfd_target ------------------ - -*Description* -This structure contains everything that BFD knows about a target. It -includes things like its byte order, name, and which routines to call -to do various operations. - - Every BFD points to a target structure with its `xvec' member. - - The macros below are used to dispatch to functions through the -`bfd_target' vector. They are used in a number of macros further down -in `bfd.h', and are also used when calling various routines by hand -inside the BFD implementation. The ARGLIST argument must be -parenthesized; it contains all the arguments to the called function. - - They make the documentation (more) unpleasant to read, so if someone -wants to fix this and not break the above, please do. - #define BFD_SEND(bfd, message, arglist) \ - ((*((bfd)->xvec->message)) arglist) - - #ifdef DEBUG_BFD_SEND - #undef BFD_SEND - #define BFD_SEND(bfd, message, arglist) \ - (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ - ((*((bfd)->xvec->message)) arglist) : \ - (bfd_assert (__FILE__,__LINE__), NULL)) - #endif - For operations which index on the BFD format: - #define BFD_SEND_FMT(bfd, message, arglist) \ - (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) - - #ifdef DEBUG_BFD_SEND - #undef BFD_SEND_FMT - #define BFD_SEND_FMT(bfd, message, arglist) \ - (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ - (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \ - (bfd_assert (__FILE__,__LINE__), NULL)) - #endif - This is the structure which defines the type of BFD this is. The -`xvec' member of the struct `bfd' itself points here. Each module that -implements access to a different target under BFD, defines one of these. - - FIXME, these names should be rationalised with the names of the -entry points which call them. Too bad we can't have one macro to define -them both! - enum bfd_flavour - { - bfd_target_unknown_flavour, - bfd_target_aout_flavour, - bfd_target_coff_flavour, - bfd_target_ecoff_flavour, - bfd_target_xcoff_flavour, - bfd_target_elf_flavour, - bfd_target_ieee_flavour, - bfd_target_nlm_flavour, - bfd_target_oasys_flavour, - bfd_target_tekhex_flavour, - bfd_target_srec_flavour, - bfd_target_ihex_flavour, - bfd_target_som_flavour, - bfd_target_os9k_flavour, - bfd_target_versados_flavour, - bfd_target_msdos_flavour, - bfd_target_ovax_flavour, - bfd_target_evax_flavour, - bfd_target_mmo_flavour, - bfd_target_mach_o_flavour, - bfd_target_pef_flavour, - bfd_target_pef_xlib_flavour, - bfd_target_sym_flavour - }; - - enum bfd_endian { BFD_ENDIAN_BIG, BFD_ENDIAN_LITTLE, BFD_ENDIAN_UNKNOWN }; - - /* Forward declaration. */ - typedef struct bfd_link_info _bfd_link_info; - - typedef struct bfd_target - { - /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */ - char *name; - - /* The "flavour" of a back end is a general indication about - the contents of a file. */ - enum bfd_flavour flavour; - - /* The order of bytes within the data area of a file. */ - enum bfd_endian byteorder; - - /* The order of bytes within the header parts of a file. */ - enum bfd_endian header_byteorder; - - /* A mask of all the flags which an executable may have set - - from the set `BFD_NO_FLAGS', `HAS_RELOC', ...`D_PAGED'. */ - flagword object_flags; - - /* A mask of all the flags which a section may have set - from - the set `SEC_NO_FLAGS', `SEC_ALLOC', ...`SET_NEVER_LOAD'. */ - flagword section_flags; - - /* The character normally found at the front of a symbol. - (if any), perhaps `_'. */ - char symbol_leading_char; - - /* The pad character for file names within an archive header. */ - char ar_pad_char; - - /* The maximum number of characters in an archive header. */ - unsigned short ar_max_namelen; - - /* Entries for byte swapping for data. These are different from the - other entry points, since they don't take a BFD as the first argument. - Certain other handlers could do the same. */ - bfd_uint64_t (*bfd_getx64) (const void *); - bfd_int64_t (*bfd_getx_signed_64) (const void *); - void (*bfd_putx64) (bfd_uint64_t, void *); - bfd_vma (*bfd_getx32) (const void *); - bfd_signed_vma (*bfd_getx_signed_32) (const void *); - void (*bfd_putx32) (bfd_vma, void *); - bfd_vma (*bfd_getx16) (const void *); - bfd_signed_vma (*bfd_getx_signed_16) (const void *); - void (*bfd_putx16) (bfd_vma, void *); - - /* Byte swapping for the headers. */ - bfd_uint64_t (*bfd_h_getx64) (const void *); - bfd_int64_t (*bfd_h_getx_signed_64) (const void *); - void (*bfd_h_putx64) (bfd_uint64_t, void *); - bfd_vma (*bfd_h_getx32) (const void *); - bfd_signed_vma (*bfd_h_getx_signed_32) (const void *); - void (*bfd_h_putx32) (bfd_vma, void *); - bfd_vma (*bfd_h_getx16) (const void *); - bfd_signed_vma (*bfd_h_getx_signed_16) (const void *); - void (*bfd_h_putx16) (bfd_vma, void *); - - /* Format dependent routines: these are vectors of entry points - within the target vector structure, one for each format to check. */ - - /* Check the format of a file being read. Return a `bfd_target *' or zero. */ - const struct bfd_target *(*_bfd_check_format[bfd_type_end]) (bfd *); - - /* Set the format of a file being written. */ - bfd_boolean (*_bfd_set_format[bfd_type_end]) (bfd *); - - /* Write cached information into a file being written, at `bfd_close'. */ - bfd_boolean (*_bfd_write_contents[bfd_type_end]) (bfd *); - The general target vector. These vectors are initialized using the -BFD_JUMP_TABLE macros. - - /* Generic entry points. */ - #define BFD_JUMP_TABLE_GENERIC(NAME) \ - NAME##_close_and_cleanup, \ - NAME##_bfd_free_cached_info, \ - NAME##_new_section_hook, \ - NAME##_get_section_contents, \ - NAME##_get_section_contents_in_window - - /* Called when the BFD is being closed to do any necessary cleanup. */ - bfd_boolean (*_close_and_cleanup) (bfd *); - /* Ask the BFD to free all cached information. */ - bfd_boolean (*_bfd_free_cached_info) (bfd *); - /* Called when a new section is created. */ - bfd_boolean (*_new_section_hook) (bfd *, sec_ptr); - /* Read the contents of a section. */ - bfd_boolean (*_bfd_get_section_contents) - (bfd *, sec_ptr, void *, file_ptr, bfd_size_type); - bfd_boolean (*_bfd_get_section_contents_in_window) - (bfd *, sec_ptr, bfd_window *, file_ptr, bfd_size_type); - - /* Entry points to copy private data. */ - #define BFD_JUMP_TABLE_COPY(NAME) \ - NAME##_bfd_copy_private_bfd_data, \ - NAME##_bfd_merge_private_bfd_data, \ - NAME##_bfd_copy_private_section_data, \ - NAME##_bfd_copy_private_symbol_data, \ - NAME##_bfd_copy_private_header_data, \ - NAME##_bfd_set_private_flags, \ - NAME##_bfd_print_private_bfd_data - - /* Called to copy BFD general private data from one object file - to another. */ - bfd_boolean (*_bfd_copy_private_bfd_data) (bfd *, bfd *); - /* Called to merge BFD general private data from one object file - to a common output file when linking. */ - bfd_boolean (*_bfd_merge_private_bfd_data) (bfd *, bfd *); - /* Called to copy BFD private section data from one object file - to another. */ - bfd_boolean (*_bfd_copy_private_section_data) - (bfd *, sec_ptr, bfd *, sec_ptr); - /* Called to copy BFD private symbol data from one symbol - to another. */ - bfd_boolean (*_bfd_copy_private_symbol_data) - (bfd *, asymbol *, bfd *, asymbol *); - /* Called to copy BFD private header data from one object file - to another. */ - bfd_boolean (*_bfd_copy_private_header_data) - (bfd *, bfd *); - /* Called to set private backend flags. */ - bfd_boolean (*_bfd_set_private_flags) (bfd *, flagword); - - /* Called to print private BFD data. */ - bfd_boolean (*_bfd_print_private_bfd_data) (bfd *, void *); - - /* Core file entry points. */ - #define BFD_JUMP_TABLE_CORE(NAME) \ - NAME##_core_file_failing_command, \ - NAME##_core_file_failing_signal, \ - NAME##_core_file_matches_executable_p - - char * (*_core_file_failing_command) (bfd *); - int (*_core_file_failing_signal) (bfd *); - bfd_boolean (*_core_file_matches_executable_p) (bfd *, bfd *); - - /* Archive entry points. */ - #define BFD_JUMP_TABLE_ARCHIVE(NAME) \ - NAME##_slurp_armap, \ - NAME##_slurp_extended_name_table, \ - NAME##_construct_extended_name_table, \ - NAME##_truncate_arname, \ - NAME##_write_armap, \ - NAME##_read_ar_hdr, \ - NAME##_openr_next_archived_file, \ - NAME##_get_elt_at_index, \ - NAME##_generic_stat_arch_elt, \ - NAME##_update_armap_timestamp - - bfd_boolean (*_bfd_slurp_armap) (bfd *); - bfd_boolean (*_bfd_slurp_extended_name_table) (bfd *); - bfd_boolean (*_bfd_construct_extended_name_table) - (bfd *, char **, bfd_size_type *, const char **); - void (*_bfd_truncate_arname) (bfd *, const char *, char *); - bfd_boolean (*write_armap) - (bfd *, unsigned int, struct orl *, unsigned int, int); - void * (*_bfd_read_ar_hdr_fn) (bfd *); - bfd * (*openr_next_archived_file) (bfd *, bfd *); - #define bfd_get_elt_at_index(b,i) BFD_SEND (b, _bfd_get_elt_at_index, (b,i)) - bfd * (*_bfd_get_elt_at_index) (bfd *, symindex); - int (*_bfd_stat_arch_elt) (bfd *, struct stat *); - bfd_boolean (*_bfd_update_armap_timestamp) (bfd *); - - /* Entry points used for symbols. */ - #define BFD_JUMP_TABLE_SYMBOLS(NAME) \ - NAME##_get_symtab_upper_bound, \ - NAME##_canonicalize_symtab, \ - NAME##_make_empty_symbol, \ - NAME##_print_symbol, \ - NAME##_get_symbol_info, \ - NAME##_bfd_is_local_label_name, \ - NAME##_bfd_is_target_special_symbol, \ - NAME##_get_lineno, \ - NAME##_find_nearest_line, \ - NAME##_bfd_make_debug_symbol, \ - NAME##_read_minisymbols, \ - NAME##_minisymbol_to_symbol - - long (*_bfd_get_symtab_upper_bound) (bfd *); - long (*_bfd_canonicalize_symtab) - (bfd *, struct bfd_symbol **); - struct bfd_symbol * - (*_bfd_make_empty_symbol) (bfd *); - void (*_bfd_print_symbol) - (bfd *, void *, struct bfd_symbol *, bfd_print_symbol_type); - #define bfd_print_symbol(b,p,s,e) BFD_SEND (b, _bfd_print_symbol, (b,p,s,e)) - void (*_bfd_get_symbol_info) - (bfd *, struct bfd_symbol *, symbol_info *); - #define bfd_get_symbol_info(b,p,e) BFD_SEND (b, _bfd_get_symbol_info, (b,p,e)) - bfd_boolean (*_bfd_is_local_label_name) (bfd *, const char *); - bfd_boolean (*_bfd_is_target_special_symbol) (bfd *, asymbol *); - alent * (*_get_lineno) (bfd *, struct bfd_symbol *); - bfd_boolean (*_bfd_find_nearest_line) - (bfd *, struct bfd_section *, struct bfd_symbol **, bfd_vma, - const char **, const char **, unsigned int *); - /* Back-door to allow format-aware applications to create debug symbols - while using BFD for everything else. Currently used by the assembler - when creating COFF files. */ - asymbol * (*_bfd_make_debug_symbol) - (bfd *, void *, unsigned long size); - #define bfd_read_minisymbols(b, d, m, s) \ - BFD_SEND (b, _read_minisymbols, (b, d, m, s)) - long (*_read_minisymbols) - (bfd *, bfd_boolean, void **, unsigned int *); - #define bfd_minisymbol_to_symbol(b, d, m, f) \ - BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f)) - asymbol * (*_minisymbol_to_symbol) - (bfd *, bfd_boolean, const void *, asymbol *); - - /* Routines for relocs. */ - #define BFD_JUMP_TABLE_RELOCS(NAME) \ - NAME##_get_reloc_upper_bound, \ - NAME##_canonicalize_reloc, \ - NAME##_bfd_reloc_type_lookup - - long (*_get_reloc_upper_bound) (bfd *, sec_ptr); - long (*_bfd_canonicalize_reloc) - (bfd *, sec_ptr, arelent **, struct bfd_symbol **); - /* See documentation on reloc types. */ - reloc_howto_type * - (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type); - - /* Routines used when writing an object file. */ - #define BFD_JUMP_TABLE_WRITE(NAME) \ - NAME##_set_arch_mach, \ - NAME##_set_section_contents - - bfd_boolean (*_bfd_set_arch_mach) - (bfd *, enum bfd_architecture, unsigned long); - bfd_boolean (*_bfd_set_section_contents) - (bfd *, sec_ptr, const void *, file_ptr, bfd_size_type); - - /* Routines used by the linker. */ - #define BFD_JUMP_TABLE_LINK(NAME) \ - NAME##_sizeof_headers, \ - NAME##_bfd_get_relocated_section_contents, \ - NAME##_bfd_relax_section, \ - NAME##_bfd_link_hash_table_create, \ - NAME##_bfd_link_hash_table_free, \ - NAME##_bfd_link_add_symbols, \ - NAME##_bfd_link_just_syms, \ - NAME##_bfd_final_link, \ - NAME##_bfd_link_split_section, \ - NAME##_bfd_gc_sections, \ - NAME##_bfd_merge_sections, \ - NAME##_bfd_is_group_section, \ - NAME##_bfd_discard_group, \ - NAME##_section_already_linked \ - - int (*_bfd_sizeof_headers) (bfd *, bfd_boolean); - bfd_byte * (*_bfd_get_relocated_section_contents) - (bfd *, struct bfd_link_info *, struct bfd_link_order *, - bfd_byte *, bfd_boolean, struct bfd_symbol **); - - bfd_boolean (*_bfd_relax_section) - (bfd *, struct bfd_section *, struct bfd_link_info *, bfd_boolean *); - - /* Create a hash table for the linker. Different backends store - different information in this table. */ - struct bfd_link_hash_table * - (*_bfd_link_hash_table_create) (bfd *); - - /* Release the memory associated with the linker hash table. */ - void (*_bfd_link_hash_table_free) (struct bfd_link_hash_table *); - - /* Add symbols from this object file into the hash table. */ - bfd_boolean (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *); - - /* Indicate that we are only retrieving symbol values from this section. */ - void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *); - - /* Do a link based on the link_order structures attached to each - section of the BFD. */ - bfd_boolean (*_bfd_final_link) (bfd *, struct bfd_link_info *); - - /* Should this section be split up into smaller pieces during linking. */ - bfd_boolean (*_bfd_link_split_section) (bfd *, struct bfd_section *); - - /* Remove sections that are not referenced from the output. */ - bfd_boolean (*_bfd_gc_sections) (bfd *, struct bfd_link_info *); - - /* Attempt to merge SEC_MERGE sections. */ - bfd_boolean (*_bfd_merge_sections) (bfd *, struct bfd_link_info *); - - /* Is this section a member of a group? */ - bfd_boolean (*_bfd_is_group_section) (bfd *, const struct bfd_section *); - - /* Discard members of a group. */ - bfd_boolean (*_bfd_discard_group) (bfd *, struct bfd_section *); - - /* Check if SEC has been already linked during a reloceatable or - final link. */ - void (*_section_already_linked) (bfd *, struct bfd_section *); - - /* Routines to handle dynamic symbols and relocs. */ - #define BFD_JUMP_TABLE_DYNAMIC(NAME) \ - NAME##_get_dynamic_symtab_upper_bound, \ - NAME##_canonicalize_dynamic_symtab, \ - NAME##_get_synthetic_symtab, \ - NAME##_get_dynamic_reloc_upper_bound, \ - NAME##_canonicalize_dynamic_reloc - - /* Get the amount of memory required to hold the dynamic symbols. */ - long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *); - /* Read in the dynamic symbols. */ - long (*_bfd_canonicalize_dynamic_symtab) - (bfd *, struct bfd_symbol **); - /* Create synthetized symbols. */ - long (*_bfd_get_synthetic_symtab) - (bfd *, long, struct bfd_symbol **, long, struct bfd_symbol **, - struct bfd_symbol **); - /* Get the amount of memory required to hold the dynamic relocs. */ - long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *); - /* Read in the dynamic relocs. */ - long (*_bfd_canonicalize_dynamic_reloc) - (bfd *, arelent **, struct bfd_symbol **); - A pointer to an alternative bfd_target in case the current one is not -satisfactory. This can happen when the target cpu supports both big -and little endian code, and target chosen by the linker has the wrong -endianness. The function open_output() in ld/ldlang.c uses this field -to find an alternative output format that is suitable. - /* Opposite endian version of this target. */ - const struct bfd_target * alternative_target; - - /* Data for use by back-end routines, which isn't - generic enough to belong in this structure. */ - const void *backend_data; - - } bfd_target; - -2.13.1.1 `bfd_set_default_target' -................................. - -*Synopsis* - bfd_boolean bfd_set_default_target (const char *name); - *Description* -Set the default target vector to use when recognizing a BFD. This -takes the name of the target, which may be a BFD target name or a -configuration triplet. - -2.13.1.2 `bfd_find_target' -.......................... - -*Synopsis* - const bfd_target *bfd_find_target (const char *target_name, bfd *abfd); - *Description* -Return a pointer to the transfer vector for the object target named -TARGET_NAME. If TARGET_NAME is `NULL', choose the one in the -environment variable `GNUTARGET'; if that is null or not defined, then -choose the first entry in the target list. Passing in the string -"default" or setting the environment variable to "default" will cause -the first entry in the target list to be returned, and -"target_defaulted" will be set in the BFD. This causes -`bfd_check_format' to loop over all the targets to find the one that -matches the file being read. - -2.13.1.3 `bfd_target_list' -.......................... - -*Synopsis* - const char ** bfd_target_list (void); - *Description* -Return a freshly malloced NULL-terminated vector of the names of all -the valid BFD targets. Do not modify the names. - -2.13.1.4 `bfd_seach_for_target' -............................... - -*Synopsis* - const bfd_target *bfd_search_for_target - (int (*search_func) (const bfd_target *, void *), - void *); - *Description* -Return a pointer to the first transfer vector in the list of transfer -vectors maintained by BFD that produces a non-zero result when passed -to the function SEARCH_FUNC. The parameter DATA is passed, unexamined, -to the search function. - - -File: bfd.info, Node: Architectures, Next: Opening and Closing, Prev: Targets, Up: BFD front end - -2.14 Architectures -================== - -BFD keeps one atom in a BFD describing the architecture of the data -attached to the BFD: a pointer to a `bfd_arch_info_type'. - - Pointers to structures can be requested independently of a BFD so -that an architecture's information can be interrogated without access -to an open BFD. - - The architecture information is provided by each architecture -package. The set of default architectures is selected by the macro -`SELECT_ARCHITECTURES'. This is normally set up in the -`config/TARGET.mt' file of your choice. If the name is not defined, -then all the architectures supported are included. - - When BFD starts up, all the architectures are called with an -initialize method. It is up to the architecture back end to insert as -many items into the list of architectures as it wants to; generally -this would be one for each machine and one for the default case (an -item with a machine field of 0). - - BFD's idea of an architecture is implemented in `archures.c'. - -2.14.1 bfd_architecture ------------------------ - -*Description* -This enum gives the object file's CPU architecture, in a global -sense--i.e., what processor family does it belong to? Another field -indicates which processor within the family is in use. The machine -gives a number which distinguishes different versions of the -architecture, containing, for example, 2 and 3 for Intel i960 KA and -i960 KB, and 68020 and 68030 for Motorola 68020 and 68030. - enum bfd_architecture - { - bfd_arch_unknown, /* File arch not known. */ - bfd_arch_obscure, /* Arch known, not one of these. */ - bfd_arch_m68k, /* Motorola 68xxx */ - #define bfd_mach_m68000 1 - #define bfd_mach_m68008 2 - #define bfd_mach_m68010 3 - #define bfd_mach_m68020 4 - #define bfd_mach_m68030 5 - #define bfd_mach_m68040 6 - #define bfd_mach_m68060 7 - #define bfd_mach_cpu32 8 - #define bfd_mach_mcf5200 9 - #define bfd_mach_mcf5206e 10 - #define bfd_mach_mcf5307 11 - #define bfd_mach_mcf5407 12 - #define bfd_mach_mcf528x 13 - #define bfd_mach_mcfv4e 14 - #define bfd_mach_mcf521x 15 - #define bfd_mach_mcf5249 16 - #define bfd_mach_mcf547x 17 - #define bfd_mach_mcf548x 18 - bfd_arch_vax, /* DEC Vax */ - bfd_arch_i960, /* Intel 960 */ - /* The order of the following is important. - lower number indicates a machine type that - only accepts a subset of the instructions - available to machines with higher numbers. - The exception is the "ca", which is - incompatible with all other machines except - "core". */ - - #define bfd_mach_i960_core 1 - #define bfd_mach_i960_ka_sa 2 - #define bfd_mach_i960_kb_sb 3 - #define bfd_mach_i960_mc 4 - #define bfd_mach_i960_xa 5 - #define bfd_mach_i960_ca 6 - #define bfd_mach_i960_jx 7 - #define bfd_mach_i960_hx 8 - - bfd_arch_or32, /* OpenRISC 32 */ - - bfd_arch_a29k, /* AMD 29000 */ - bfd_arch_sparc, /* SPARC */ - #define bfd_mach_sparc 1 - /* The difference between v8plus and v9 is that v9 is a true 64 bit env. */ - #define bfd_mach_sparc_sparclet 2 - #define bfd_mach_sparc_sparclite 3 - #define bfd_mach_sparc_v8plus 4 - #define bfd_mach_sparc_v8plusa 5 /* with ultrasparc add'ns. */ - #define bfd_mach_sparc_sparclite_le 6 - #define bfd_mach_sparc_v9 7 - #define bfd_mach_sparc_v9a 8 /* with ultrasparc add'ns. */ - #define bfd_mach_sparc_v8plusb 9 /* with cheetah add'ns. */ - #define bfd_mach_sparc_v9b 10 /* with cheetah add'ns. */ - /* Nonzero if MACH has the v9 instruction set. */ - #define bfd_mach_sparc_v9_p(mach) \ - ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9b \ - && (mach) != bfd_mach_sparc_sparclite_le) - /* Nonzero if MACH is a 64 bit sparc architecture. */ - #define bfd_mach_sparc_64bit_p(mach) \ - ((mach) >= bfd_mach_sparc_v9 && (mach) != bfd_mach_sparc_v8plusb) - bfd_arch_mips, /* MIPS Rxxxx */ - #define bfd_mach_mips3000 3000 - #define bfd_mach_mips3900 3900 - #define bfd_mach_mips4000 4000 - #define bfd_mach_mips4010 4010 - #define bfd_mach_mips4100 4100 - #define bfd_mach_mips4111 4111 - #define bfd_mach_mips4120 4120 - #define bfd_mach_mips4300 4300 - #define bfd_mach_mips4400 4400 - #define bfd_mach_mips4600 4600 - #define bfd_mach_mips4650 4650 - #define bfd_mach_mips5000 5000 - #define bfd_mach_mips5400 5400 - #define bfd_mach_mips5500 5500 - #define bfd_mach_mips6000 6000 - #define bfd_mach_mips7000 7000 - #define bfd_mach_mips8000 8000 - #define bfd_mach_mips9000 9000 - #define bfd_mach_mips10000 10000 - #define bfd_mach_mips12000 12000 - #define bfd_mach_mips16 16 - #define bfd_mach_mips5 5 - #define bfd_mach_mips_sb1 12310201 /* octal 'SB', 01 */ - #define bfd_mach_mipsisa32 32 - #define bfd_mach_mipsisa32r2 33 - #define bfd_mach_mipsisa64 64 - #define bfd_mach_mipsisa64r2 65 - bfd_arch_i386, /* Intel 386 */ - #define bfd_mach_i386_i386 1 - #define bfd_mach_i386_i8086 2 - #define bfd_mach_i386_i386_intel_syntax 3 - #define bfd_mach_x86_64 64 - #define bfd_mach_x86_64_intel_syntax 65 - bfd_arch_we32k, /* AT&T WE32xxx */ - bfd_arch_tahoe, /* CCI/Harris Tahoe */ - bfd_arch_i860, /* Intel 860 */ - bfd_arch_i370, /* IBM 360/370 Mainframes */ - bfd_arch_romp, /* IBM ROMP PC/RT */ - bfd_arch_alliant, /* Alliant */ - bfd_arch_convex, /* Convex */ - bfd_arch_m88k, /* Motorola 88xxx */ - bfd_arch_m98k, /* Motorola 98xxx */ - bfd_arch_pyramid, /* Pyramid Technology */ - bfd_arch_h8300, /* Renesas H8/300 (formerly Hitachi H8/300) */ - #define bfd_mach_h8300 1 - #define bfd_mach_h8300h 2 - #define bfd_mach_h8300s 3 - #define bfd_mach_h8300hn 4 - #define bfd_mach_h8300sn 5 - #define bfd_mach_h8300sx 6 - #define bfd_mach_h8300sxn 7 - bfd_arch_pdp11, /* DEC PDP-11 */ - bfd_arch_powerpc, /* PowerPC */ - #define bfd_mach_ppc 32 - #define bfd_mach_ppc64 64 - #define bfd_mach_ppc_403 403 - #define bfd_mach_ppc_403gc 4030 - #define bfd_mach_ppc_505 505 - #define bfd_mach_ppc_601 601 - #define bfd_mach_ppc_602 602 - #define bfd_mach_ppc_603 603 - #define bfd_mach_ppc_ec603e 6031 - #define bfd_mach_ppc_604 604 - #define bfd_mach_ppc_620 620 - #define bfd_mach_ppc_630 630 - #define bfd_mach_ppc_750 750 - #define bfd_mach_ppc_860 860 - #define bfd_mach_ppc_a35 35 - #define bfd_mach_ppc_rs64ii 642 - #define bfd_mach_ppc_rs64iii 643 - #define bfd_mach_ppc_7400 7400 - #define bfd_mach_ppc_e500 500 - bfd_arch_rs6000, /* IBM RS/6000 */ - #define bfd_mach_rs6k 6000 - #define bfd_mach_rs6k_rs1 6001 - #define bfd_mach_rs6k_rsc 6003 - #define bfd_mach_rs6k_rs2 6002 - bfd_arch_hppa, /* HP PA RISC */ - #define bfd_mach_hppa10 10 - #define bfd_mach_hppa11 11 - #define bfd_mach_hppa20 20 - #define bfd_mach_hppa20w 25 - bfd_arch_d10v, /* Mitsubishi D10V */ - #define bfd_mach_d10v 1 - #define bfd_mach_d10v_ts2 2 - #define bfd_mach_d10v_ts3 3 - bfd_arch_d30v, /* Mitsubishi D30V */ - bfd_arch_dlx, /* DLX */ - bfd_arch_m68hc11, /* Motorola 68HC11 */ - bfd_arch_m68hc12, /* Motorola 68HC12 */ - #define bfd_mach_m6812_default 0 - #define bfd_mach_m6812 1 - #define bfd_mach_m6812s 2 - bfd_arch_z8k, /* Zilog Z8000 */ - #define bfd_mach_z8001 1 - #define bfd_mach_z8002 2 - bfd_arch_h8500, /* Renesas H8/500 (formerly Hitachi H8/500) */ - bfd_arch_sh, /* Renesas / SuperH SH (formerly Hitachi SH) */ - #define bfd_mach_sh 1 - #define bfd_mach_sh2 0x20 - #define bfd_mach_sh_dsp 0x2d - #define bfd_mach_sh2a 0x2a - #define bfd_mach_sh2a_nofpu 0x2b - #define bfd_mach_sh2a_nofpu_or_sh4_nommu_nofpu 0x2a1 - #define bfd_mach_sh2a_nofpu_or_sh3_nommu 0x2a2 - #define bfd_mach_sh2a_or_sh4 0x2a3 - #define bfd_mach_sh2a_or_sh3e 0x2a4 - #define bfd_mach_sh2e 0x2e - #define bfd_mach_sh3 0x30 - #define bfd_mach_sh3_nommu 0x31 - #define bfd_mach_sh3_dsp 0x3d - #define bfd_mach_sh3e 0x3e - #define bfd_mach_sh4 0x40 - #define bfd_mach_sh4_nofpu 0x41 - #define bfd_mach_sh4_nommu_nofpu 0x42 - #define bfd_mach_sh4a 0x4a - #define bfd_mach_sh4a_nofpu 0x4b - #define bfd_mach_sh4al_dsp 0x4d - #define bfd_mach_sh5 0x50 - bfd_arch_alpha, /* Dec Alpha */ - #define bfd_mach_alpha_ev4 0x10 - #define bfd_mach_alpha_ev5 0x20 - #define bfd_mach_alpha_ev6 0x30 - bfd_arch_arm, /* Advanced Risc Machines ARM. */ - #define bfd_mach_arm_unknown 0 - #define bfd_mach_arm_2 1 - #define bfd_mach_arm_2a 2 - #define bfd_mach_arm_3 3 - #define bfd_mach_arm_3M 4 - #define bfd_mach_arm_4 5 - #define bfd_mach_arm_4T 6 - #define bfd_mach_arm_5 7 - #define bfd_mach_arm_5T 8 - #define bfd_mach_arm_5TE 9 - #define bfd_mach_arm_XScale 10 - #define bfd_mach_arm_ep9312 11 - #define bfd_mach_arm_iWMMXt 12 - bfd_arch_ns32k, /* National Semiconductors ns32000 */ - bfd_arch_w65, /* WDC 65816 */ - bfd_arch_tic30, /* Texas Instruments TMS320C30 */ - bfd_arch_tic4x, /* Texas Instruments TMS320C3X/4X */ - #define bfd_mach_tic3x 30 - #define bfd_mach_tic4x 40 - bfd_arch_tic54x, /* Texas Instruments TMS320C54X */ - bfd_arch_tic80, /* TI TMS320c80 (MVP) */ - bfd_arch_v850, /* NEC V850 */ - #define bfd_mach_v850 1 - #define bfd_mach_v850e 'E' - #define bfd_mach_v850e1 '1' - bfd_arch_arc, /* ARC Cores */ - #define bfd_mach_arc_5 5 - #define bfd_mach_arc_6 6 - #define bfd_mach_arc_7 7 - #define bfd_mach_arc_8 8 - bfd_arch_m32r, /* Renesas M32R (formerly Mitsubishi M32R/D) */ - #define bfd_mach_m32r 1 /* For backwards compatibility. */ - #define bfd_mach_m32rx 'x' - #define bfd_mach_m32r2 '2' - bfd_arch_mn10200, /* Matsushita MN10200 */ - bfd_arch_mn10300, /* Matsushita MN10300 */ - #define bfd_mach_mn10300 300 - #define bfd_mach_am33 330 - #define bfd_mach_am33_2 332 - bfd_arch_fr30, - #define bfd_mach_fr30 0x46523330 - bfd_arch_frv, - #define bfd_mach_frv 1 - #define bfd_mach_frvsimple 2 - #define bfd_mach_fr300 300 - #define bfd_mach_fr400 400 - #define bfd_mach_fr450 450 - #define bfd_mach_frvtomcat 499 /* fr500 prototype */ - #define bfd_mach_fr500 500 - #define bfd_mach_fr550 550 - bfd_arch_mcore, - bfd_arch_ia64, /* HP/Intel ia64 */ - #define bfd_mach_ia64_elf64 64 - #define bfd_mach_ia64_elf32 32 - bfd_arch_ip2k, /* Ubicom IP2K microcontrollers. */ - #define bfd_mach_ip2022 1 - #define bfd_mach_ip2022ext 2 - bfd_arch_iq2000, /* Vitesse IQ2000. */ - #define bfd_mach_iq2000 1 - #define bfd_mach_iq10 2 - bfd_arch_pj, - bfd_arch_avr, /* Atmel AVR microcontrollers. */ - #define bfd_mach_avr1 1 - #define bfd_mach_avr2 2 - #define bfd_mach_avr3 3 - #define bfd_mach_avr4 4 - #define bfd_mach_avr5 5 - bfd_arch_cr16c, /* National Semiconductor CompactRISC. */ - #define bfd_mach_cr16c 1 - bfd_arch_crx, /* National Semiconductor CRX. */ - #define bfd_mach_crx 1 - bfd_arch_cris, /* Axis CRIS */ - #define bfd_mach_cris_v0_v10 255 - #define bfd_mach_cris_v32 32 - #define bfd_mach_cris_v10_v32 1032 - bfd_arch_s390, /* IBM s390 */ - #define bfd_mach_s390_31 31 - #define bfd_mach_s390_64 64 - bfd_arch_openrisc, /* OpenRISC */ - bfd_arch_mmix, /* Donald Knuth's educational processor. */ - bfd_arch_xstormy16, - #define bfd_mach_xstormy16 1 - bfd_arch_msp430, /* Texas Instruments MSP430 architecture. */ - #define bfd_mach_msp11 11 - #define bfd_mach_msp110 110 - #define bfd_mach_msp12 12 - #define bfd_mach_msp13 13 - #define bfd_mach_msp14 14 - #define bfd_mach_msp15 15 - #define bfd_mach_msp16 16 - #define bfd_mach_msp31 31 - #define bfd_mach_msp32 32 - #define bfd_mach_msp33 33 - #define bfd_mach_msp41 41 - #define bfd_mach_msp42 42 - #define bfd_mach_msp43 43 - #define bfd_mach_msp44 44 - bfd_arch_xtensa, /* Tensilica's Xtensa cores. */ - #define bfd_mach_xtensa 1 - bfd_arch_maxq, /* Dallas MAXQ 10/20 */ - #define bfd_mach_maxq10 10 - #define bfd_mach_maxq20 20 - bfd_arch_last - }; - -2.14.2 bfd_arch_info --------------------- - -*Description* -This structure contains information on architectures for use within BFD. - - typedef struct bfd_arch_info - { - int bits_per_word; - int bits_per_address; - int bits_per_byte; - enum bfd_architecture arch; - unsigned long mach; - const char *arch_name; - const char *printable_name; - unsigned int section_align_power; - /* TRUE if this is the default machine for the architecture. - The default arch should be the first entry for an arch so that - all the entries for that arch can be accessed via `next'. */ - bfd_boolean the_default; - const struct bfd_arch_info * (*compatible) - (const struct bfd_arch_info *a, const struct bfd_arch_info *b); - - bfd_boolean (*scan) (const struct bfd_arch_info *, const char *); - - const struct bfd_arch_info *next; - } - bfd_arch_info_type; - -2.14.2.1 `bfd_printable_name' -............................. - -*Synopsis* - const char *bfd_printable_name (bfd *abfd); - *Description* -Return a printable string representing the architecture and machine -from the pointer to the architecture info structure. - -2.14.2.2 `bfd_scan_arch' -........................ - -*Synopsis* - const bfd_arch_info_type *bfd_scan_arch (const char *string); - *Description* -Figure out if BFD supports any cpu which could be described with the -name STRING. Return a pointer to an `arch_info' structure if a machine -is found, otherwise NULL. - -2.14.2.3 `bfd_arch_list' -........................ - -*Synopsis* - const char **bfd_arch_list (void); - *Description* -Return a freshly malloced NULL-terminated vector of the names of all -the valid BFD architectures. Do not modify the names. - -2.14.2.4 `bfd_arch_get_compatible' -.................................. - -*Synopsis* - const bfd_arch_info_type *bfd_arch_get_compatible - (const bfd *abfd, const bfd *bbfd, bfd_boolean accept_unknowns); - *Description* -Determine whether two BFDs' architectures and machine types are -compatible. Calculates the lowest common denominator between the two -architectures and machine types implied by the BFDs and returns a -pointer to an `arch_info' structure describing the compatible machine. - -2.14.2.5 `bfd_default_arch_struct' -.................................. - -*Description* -The `bfd_default_arch_struct' is an item of `bfd_arch_info_type' which -has been initialized to a fairly generic state. A BFD starts life by -pointing to this structure, until the correct back end has determined -the real architecture of the file. - extern const bfd_arch_info_type bfd_default_arch_struct; - -2.14.2.6 `bfd_set_arch_info' -............................ - -*Synopsis* - void bfd_set_arch_info (bfd *abfd, const bfd_arch_info_type *arg); - *Description* -Set the architecture info of ABFD to ARG. - -2.14.2.7 `bfd_default_set_arch_mach' -.................................... - -*Synopsis* - bfd_boolean bfd_default_set_arch_mach - (bfd *abfd, enum bfd_architecture arch, unsigned long mach); - *Description* -Set the architecture and machine type in BFD ABFD to ARCH and MACH. -Find the correct pointer to a structure and insert it into the -`arch_info' pointer. - -2.14.2.8 `bfd_get_arch' -....................... - -*Synopsis* - enum bfd_architecture bfd_get_arch (bfd *abfd); - *Description* -Return the enumerated type which describes the BFD ABFD's architecture. - -2.14.2.9 `bfd_get_mach' -....................... - -*Synopsis* - unsigned long bfd_get_mach (bfd *abfd); - *Description* -Return the long type which describes the BFD ABFD's machine. - -2.14.2.10 `bfd_arch_bits_per_byte' -.................................. - -*Synopsis* - unsigned int bfd_arch_bits_per_byte (bfd *abfd); - *Description* -Return the number of bits in one of the BFD ABFD's architecture's bytes. - -2.14.2.11 `bfd_arch_bits_per_address' -..................................... - -*Synopsis* - unsigned int bfd_arch_bits_per_address (bfd *abfd); - *Description* -Return the number of bits in one of the BFD ABFD's architecture's -addresses. - -2.14.2.12 `bfd_default_compatible' -.................................. - -*Synopsis* - const bfd_arch_info_type *bfd_default_compatible - (const bfd_arch_info_type *a, const bfd_arch_info_type *b); - *Description* -The default function for testing for compatibility. - -2.14.2.13 `bfd_default_scan' -............................ - -*Synopsis* - bfd_boolean bfd_default_scan - (const struct bfd_arch_info *info, const char *string); - *Description* -The default function for working out whether this is an architecture -hit and a machine hit. - -2.14.2.14 `bfd_get_arch_info' -............................. - -*Synopsis* - const bfd_arch_info_type *bfd_get_arch_info (bfd *abfd); - *Description* -Return the architecture info struct in ABFD. - -2.14.2.15 `bfd_lookup_arch' -........................... - -*Synopsis* - const bfd_arch_info_type *bfd_lookup_arch - (enum bfd_architecture arch, unsigned long machine); - *Description* -Look for the architecture info structure which matches the arguments -ARCH and MACHINE. A machine of 0 matches the machine/architecture -structure which marks itself as the default. - -2.14.2.16 `bfd_printable_arch_mach' -................................... - -*Synopsis* - const char *bfd_printable_arch_mach - (enum bfd_architecture arch, unsigned long machine); - *Description* -Return a printable string representing the architecture and machine -type. - - This routine is depreciated. - -2.14.2.17 `bfd_octets_per_byte' -............................... - -*Synopsis* - unsigned int bfd_octets_per_byte (bfd *abfd); - *Description* -Return the number of octets (8-bit quantities) per target byte (minimum -addressable unit). In most cases, this will be one, but some DSP -targets have 16, 32, or even 48 bits per byte. - -2.14.2.18 `bfd_arch_mach_octets_per_byte' -......................................... - -*Synopsis* - unsigned int bfd_arch_mach_octets_per_byte - (enum bfd_architecture arch, unsigned long machine); - *Description* -See bfd_octets_per_byte. - - This routine is provided for those cases where a bfd * is not -available - - -File: bfd.info, Node: Opening and Closing, Next: Internal, Prev: Architectures, Up: BFD front end - -2.15 Opening and closing BFDs -============================= - -2.15.0.1 `bfd_openr' -.................... - -*Synopsis* - bfd *bfd_openr (const char *filename, const char *target); - *Description* -Open the file FILENAME (using `fopen') with the target TARGET. Return -a pointer to the created BFD. - - Calls `bfd_find_target', so TARGET is interpreted as by that -function. - - If `NULL' is returned then an error has occured. Possible errors -are `bfd_error_no_memory', `bfd_error_invalid_target' or `system_call' -error. - -2.15.0.2 `bfd_fdopenr' -...................... - -*Synopsis* - bfd *bfd_fdopenr (const char *filename, const char *target, int fd); - *Description* -`bfd_fdopenr' is to `bfd_fopenr' much like `fdopen' is to `fopen'. It -opens a BFD on a file already described by the FD supplied. - - When the file is later `bfd_close'd, the file descriptor will be -closed. If the caller desires that this file descriptor be cached by -BFD (opened as needed, closed as needed to free descriptors for other -opens), with the supplied FD used as an initial file descriptor (but -subject to closure at any time), call bfd_set_cacheable(bfd, 1) on the -returned BFD. The default is to assume no caching; the file descriptor -will remain open until `bfd_close', and will not be affected by BFD -operations on other files. - - Possible errors are `bfd_error_no_memory', -`bfd_error_invalid_target' and `bfd_error_system_call'. - -2.15.0.3 `bfd_openstreamr' -.......................... - -*Synopsis* - bfd *bfd_openstreamr (const char *, const char *, void *); - *Description* -Open a BFD for read access on an existing stdio stream. When the BFD -is passed to `bfd_close', the stream will be closed. - -2.15.0.4 `bfd_openr_iovec' -.......................... - -*Synopsis* - bfd *bfd_openr_iovec (const char *filename, const char *target, - void *(*open) (struct bfd *nbfd, - void *open_closure), - void *open_closure, - file_ptr (*pread) (struct bfd *nbfd, - void *stream, - void *buf, - file_ptr nbytes, - file_ptr offset), - int (*close) (struct bfd *nbfd, - void *stream)); - *Description* -Create and return a BFD backed by a read-only STREAM. The STREAM is -created using OPEN, accessed using PREAD and destroyed using CLOSE. - - Calls `bfd_find_target', so TARGET is interpreted as by that -function. - - Calls OPEN (which can call `bfd_zalloc' and `bfd_get_filename') to -obtain the read-only stream backing the BFD. OPEN either succeeds -returning the non-`NULL' STREAM, or fails returning `NULL' (setting -`bfd_error'). - - Calls PREAD to request NBYTES of data from STREAM starting at OFFSET -(e.g., via a call to `bfd_read'). PREAD either succeeds returning the -number of bytes read (which can be less than NBYTES when end-of-file), -or fails returning -1 (setting `bfd_error'). - - Calls CLOSE when the BFD is later closed using `bfd_close'. CLOSE -either succeeds returning 0, or fails returning -1 (setting -`bfd_error'). - - If `bfd_openr_iovec' returns `NULL' then an error has occurred. -Possible errors are `bfd_error_no_memory', `bfd_error_invalid_target' -and `bfd_error_system_call'. - -2.15.0.5 `bfd_openw' -.................... - -*Synopsis* - bfd *bfd_openw (const char *filename, const char *target); - *Description* -Create a BFD, associated with file FILENAME, using the file format -TARGET, and return a pointer to it. - - Possible errors are `bfd_error_system_call', `bfd_error_no_memory', -`bfd_error_invalid_target'. - -2.15.0.6 `bfd_close' -.................... - -*Synopsis* - bfd_boolean bfd_close (bfd *abfd); - *Description* -Close a BFD. If the BFD was open for writing, then pending operations -are completed and the file written out and closed. If the created file -is executable, then `chmod' is called to mark it as such. - - All memory attached to the BFD is released. - - The file descriptor associated with the BFD is closed (even if it -was passed in to BFD by `bfd_fdopenr'). - - *Returns* -`TRUE' is returned if all is ok, otherwise `FALSE'. - -2.15.0.7 `bfd_close_all_done' -............................. - -*Synopsis* - bfd_boolean bfd_close_all_done (bfd *); - *Description* -Close a BFD. Differs from `bfd_close' since it does not complete any -pending operations. This routine would be used if the application had -just used BFD for swapping and didn't want to use any of the writing -code. - - If the created file is executable, then `chmod' is called to mark it -as such. - - All memory attached to the BFD is released. - - *Returns* -`TRUE' is returned if all is ok, otherwise `FALSE'. - -2.15.0.8 `bfd_create' -..................... - -*Synopsis* - bfd *bfd_create (const char *filename, bfd *templ); - *Description* -Create a new BFD in the manner of `bfd_openw', but without opening a -file. The new BFD takes the target from the target used by TEMPLATE. -The format is always set to `bfd_object'. - -2.15.0.9 `bfd_make_writable' -............................ - -*Synopsis* - bfd_boolean bfd_make_writable (bfd *abfd); - *Description* -Takes a BFD as created by `bfd_create' and converts it into one like as -returned by `bfd_openw'. It does this by converting the BFD to -BFD_IN_MEMORY. It's assumed that you will call `bfd_make_readable' on -this bfd later. - - *Returns* -`TRUE' is returned if all is ok, otherwise `FALSE'. - -2.15.0.10 `bfd_make_readable' -............................. - -*Synopsis* - bfd_boolean bfd_make_readable (bfd *abfd); - *Description* -Takes a BFD as created by `bfd_create' and `bfd_make_writable' and -converts it into one like as returned by `bfd_openr'. It does this by -writing the contents out to the memory buffer, then reversing the -direction. - - *Returns* -`TRUE' is returned if all is ok, otherwise `FALSE'. - -2.15.0.11 `bfd_alloc' -..................... - -*Synopsis* - void *bfd_alloc (bfd *abfd, bfd_size_type wanted); - *Description* -Allocate a block of WANTED bytes of memory attached to `abfd' and -return a pointer to it. - -2.15.0.12 `bfd_zalloc' -...................... - -*Synopsis* - void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); - *Description* -Allocate a block of WANTED bytes of zeroed memory attached to `abfd' -and return a pointer to it. - -2.15.0.13 `bfd_calc_gnu_debuglink_crc32' -........................................ - -*Synopsis* - unsigned long bfd_calc_gnu_debuglink_crc32 - (unsigned long crc, const unsigned char *buf, bfd_size_type len); - *Description* -Computes a CRC value as used in the .gnu_debuglink section. Advances -the previously computed CRC value by computing and adding in the crc32 -for LEN bytes of BUF. - - *Returns* -Return the updated CRC32 value. - -2.15.0.14 `get_debug_link_info' -............................... - -*Synopsis* - char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out); - *Description* -fetch the filename and CRC32 value for any separate debuginfo -associated with ABFD. Return NULL if no such info found, otherwise -return filename and update CRC32_OUT. - -2.15.0.15 `separate_debug_file_exists' -...................................... - -*Synopsis* - bfd_boolean separate_debug_file_exists - (char *name, unsigned long crc32); - *Description* -Checks to see if NAME is a file and if its contents match CRC32. - -2.15.0.16 `find_separate_debug_file' -.................................... - -*Synopsis* - char *find_separate_debug_file (bfd *abfd); - *Description* -Searches ABFD for a reference to separate debugging information, scans -various locations in the filesystem, including the file tree rooted at -DEBUG_FILE_DIRECTORY, and returns a filename of such debugging -information if the file is found and has matching CRC32. Returns NULL -if no reference to debugging file exists, or file cannot be found. - -2.15.0.17 `bfd_follow_gnu_debuglink' -.................................... - -*Synopsis* - char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); - *Description* -Takes a BFD and searches it for a .gnu_debuglink section. If this -section is found, it examines the section for the name and checksum of -a '.debug' file containing auxiliary debugging information. It then -searches the filesystem for this .debug file in some standard -locations, including the directory tree rooted at DIR, and if found -returns the full filename. - - If DIR is NULL, it will search a default path configured into libbfd -at build time. [XXX this feature is not currently implemented]. - - *Returns* -`NULL' on any errors or failure to locate the .debug file, otherwise a -pointer to a heap-allocated string containing the filename. The caller -is responsible for freeing this string. - -2.15.0.18 `bfd_create_gnu_debuglink_section' -............................................ - -*Synopsis* - struct bfd_section *bfd_create_gnu_debuglink_section - (bfd *abfd, const char *filename); - *Description* -Takes a BFD and adds a .gnu_debuglink section to it. The section is -sized to be big enough to contain a link to the specified FILENAME. - - *Returns* -A pointer to the new section is returned if all is ok. Otherwise -`NULL' is returned and bfd_error is set. - -2.15.0.19 `bfd_fill_in_gnu_debuglink_section' -............................................. - -*Synopsis* - bfd_boolean bfd_fill_in_gnu_debuglink_section - (bfd *abfd, struct bfd_section *sect, const char *filename); - *Description* -Takes a BFD and containing a .gnu_debuglink section SECT and fills in -the contents of the section to contain a link to the specified -FILENAME. The filename should be relative to the current directory. - - *Returns* -`TRUE' is returned if all is ok. Otherwise `FALSE' is returned and -bfd_error is set. - - -File: bfd.info, Node: Internal, Next: File Caching, Prev: Opening and Closing, Up: BFD front end - -2.16 Internal functions -======================= - -*Description* -These routines are used within BFD. They are not intended for export, -but are documented here for completeness. - -2.16.0.1 `bfd_write_bigendian_4byte_int' -........................................ - -*Synopsis* - bfd_boolean bfd_write_bigendian_4byte_int (bfd *, unsigned int); - *Description* -Write a 4 byte integer I to the output BFD ABFD, in big endian order -regardless of what else is going on. This is useful in archives. - -2.16.0.2 `bfd_put_size' -....................... - -2.16.0.3 `bfd_get_size' -....................... - -*Description* -These macros as used for reading and writing raw data in sections; each -access (except for bytes) is vectored through the target format of the -BFD and mangled accordingly. The mangling performs any necessary endian -translations and removes alignment restrictions. Note that types -accepted and returned by these macros are identical so they can be -swapped around in macros--for example, `libaout.h' defines `GET_WORD' -to either `bfd_get_32' or `bfd_get_64'. - - In the put routines, VAL must be a `bfd_vma'. If we are on a system -without prototypes, the caller is responsible for making sure that is -true, with a cast if necessary. We don't cast them in the macro -definitions because that would prevent `lint' or `gcc -Wall' from -detecting sins such as passing a pointer. To detect calling these with -less than a `bfd_vma', use `gcc -Wconversion' on a host with 64 bit -`bfd_vma''s. - - /* Byte swapping macros for user section data. */ - - #define bfd_put_8(abfd, val, ptr) \ - ((void) (*((unsigned char *) (ptr)) = (val) & 0xff)) - #define bfd_put_signed_8 \ - bfd_put_8 - #define bfd_get_8(abfd, ptr) \ - (*(unsigned char *) (ptr) & 0xff) - #define bfd_get_signed_8(abfd, ptr) \ - (((*(unsigned char *) (ptr) & 0xff) ^ 0x80) - 0x80) - - #define bfd_put_16(abfd, val, ptr) \ - BFD_SEND (abfd, bfd_putx16, ((val),(ptr))) - #define bfd_put_signed_16 \ - bfd_put_16 - #define bfd_get_16(abfd, ptr) \ - BFD_SEND (abfd, bfd_getx16, (ptr)) - #define bfd_get_signed_16(abfd, ptr) \ - BFD_SEND (abfd, bfd_getx_signed_16, (ptr)) - - #define bfd_put_32(abfd, val, ptr) \ - BFD_SEND (abfd, bfd_putx32, ((val),(ptr))) - #define bfd_put_signed_32 \ - bfd_put_32 - #define bfd_get_32(abfd, ptr) \ - BFD_SEND (abfd, bfd_getx32, (ptr)) - #define bfd_get_signed_32(abfd, ptr) \ - BFD_SEND (abfd, bfd_getx_signed_32, (ptr)) - - #define bfd_put_64(abfd, val, ptr) \ - BFD_SEND (abfd, bfd_putx64, ((val), (ptr))) - #define bfd_put_signed_64 \ - bfd_put_64 - #define bfd_get_64(abfd, ptr) \ - BFD_SEND (abfd, bfd_getx64, (ptr)) - #define bfd_get_signed_64(abfd, ptr) \ - BFD_SEND (abfd, bfd_getx_signed_64, (ptr)) - - #define bfd_get(bits, abfd, ptr) \ - ((bits) == 8 ? (bfd_vma) bfd_get_8 (abfd, ptr) \ - : (bits) == 16 ? bfd_get_16 (abfd, ptr) \ - : (bits) == 32 ? bfd_get_32 (abfd, ptr) \ - : (bits) == 64 ? bfd_get_64 (abfd, ptr) \ - : (abort (), (bfd_vma) - 1)) - - #define bfd_put(bits, abfd, val, ptr) \ - ((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \ - : (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \ - : (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \ - : (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \ - : (abort (), (void) 0)) - -2.16.0.4 `bfd_h_put_size' -......................... - -*Description* -These macros have the same function as their `bfd_get_x' brethren, -except that they are used for removing information for the header -records of object files. Believe it or not, some object files keep -their header records in big endian order and their data in little -endian order. - - /* Byte swapping macros for file header data. */ - - #define bfd_h_put_8(abfd, val, ptr) \ - bfd_put_8 (abfd, val, ptr) - #define bfd_h_put_signed_8(abfd, val, ptr) \ - bfd_put_8 (abfd, val, ptr) - #define bfd_h_get_8(abfd, ptr) \ - bfd_get_8 (abfd, ptr) - #define bfd_h_get_signed_8(abfd, ptr) \ - bfd_get_signed_8 (abfd, ptr) - - #define bfd_h_put_16(abfd, val, ptr) \ - BFD_SEND (abfd, bfd_h_putx16, (val, ptr)) - #define bfd_h_put_signed_16 \ - bfd_h_put_16 - #define bfd_h_get_16(abfd, ptr) \ - BFD_SEND (abfd, bfd_h_getx16, (ptr)) - #define bfd_h_get_signed_16(abfd, ptr) \ - BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr)) - - #define bfd_h_put_32(abfd, val, ptr) \ - BFD_SEND (abfd, bfd_h_putx32, (val, ptr)) - #define bfd_h_put_signed_32 \ - bfd_h_put_32 - #define bfd_h_get_32(abfd, ptr) \ - BFD_SEND (abfd, bfd_h_getx32, (ptr)) - #define bfd_h_get_signed_32(abfd, ptr) \ - BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr)) - - #define bfd_h_put_64(abfd, val, ptr) \ - BFD_SEND (abfd, bfd_h_putx64, (val, ptr)) - #define bfd_h_put_signed_64 \ - bfd_h_put_64 - #define bfd_h_get_64(abfd, ptr) \ - BFD_SEND (abfd, bfd_h_getx64, (ptr)) - #define bfd_h_get_signed_64(abfd, ptr) \ - BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr)) - - /* Aliases for the above, which should eventually go away. */ - - #define H_PUT_64 bfd_h_put_64 - #define H_PUT_32 bfd_h_put_32 - #define H_PUT_16 bfd_h_put_16 - #define H_PUT_8 bfd_h_put_8 - #define H_PUT_S64 bfd_h_put_signed_64 - #define H_PUT_S32 bfd_h_put_signed_32 - #define H_PUT_S16 bfd_h_put_signed_16 - #define H_PUT_S8 bfd_h_put_signed_8 - #define H_GET_64 bfd_h_get_64 - #define H_GET_32 bfd_h_get_32 - #define H_GET_16 bfd_h_get_16 - #define H_GET_8 bfd_h_get_8 - #define H_GET_S64 bfd_h_get_signed_64 - #define H_GET_S32 bfd_h_get_signed_32 - #define H_GET_S16 bfd_h_get_signed_16 - #define H_GET_S8 bfd_h_get_signed_8 - -2.16.0.5 `bfd_log2' -................... - -*Synopsis* - unsigned int bfd_log2 (bfd_vma x); - *Description* -Return the log base 2 of the value supplied, rounded up. E.g., an X of -1025 returns 11. A X of 0 returns 0. - - -File: bfd.info, Node: File Caching, Next: Linker Functions, Prev: Internal, Up: BFD front end - -2.17 File caching -================= - -The file caching mechanism is embedded within BFD and allows the -application to open as many BFDs as it wants without regard to the -underlying operating system's file descriptor limit (often as low as 20 -open files). The module in `cache.c' maintains a least recently used -list of `BFD_CACHE_MAX_OPEN' files, and exports the name -`bfd_cache_lookup', which runs around and makes sure that the required -BFD is open. If not, then it chooses a file to close, closes it and -opens the one wanted, returning its file handle. - -2.17.0.1 `BFD_CACHE_MAX_OPEN macro' -................................... - -*Description* -The maximum number of files which the cache will keep open at one time. - #define BFD_CACHE_MAX_OPEN 10 - -2.17.0.2 `bfd_last_cache' -......................... - -*Synopsis* - extern bfd *bfd_last_cache; - *Description* -Zero, or a pointer to the topmost BFD on the chain. This is used by -the `bfd_cache_lookup' macro in `libbfd.h' to determine when it can -avoid a function call. - -2.17.0.3 `bfd_cache_lookup' -........................... - -*Description* -Check to see if the required BFD is the same as the last one looked up. -If so, then it can use the stream in the BFD with impunity, since it -can't have changed since the last lookup; otherwise, it has to perform -the complicated lookup function. - #define bfd_cache_lookup(x) \ - ((x) == bfd_last_cache ? \ - (FILE *) (bfd_last_cache->iostream): \ - bfd_cache_lookup_worker (x)) - -2.17.0.4 `bfd_cache_init' -......................... - -*Synopsis* - bfd_boolean bfd_cache_init (bfd *abfd); - *Description* -Add a newly opened BFD to the cache. - -2.17.0.5 `bfd_cache_close' -.......................... - -*Synopsis* - bfd_boolean bfd_cache_close (bfd *abfd); - *Description* -Remove the BFD ABFD from the cache. If the attached file is open, then -close it too. - - *Returns* -`FALSE' is returned if closing the file fails, `TRUE' is returned if -all is well. - -2.17.0.6 `bfd_cache_close_all' -.............................. - -*Synopsis* - bfd_boolean bfd_cache_close_all (void); - *Description* -Remove all BFDs from the cache. If the attached file is open, then -close it too. - - *Returns* -`FALSE' is returned if closing one of the file fails, `TRUE' is -returned if all is well. - -2.17.0.7 `bfd_open_file' -........................ - -*Synopsis* - FILE* bfd_open_file (bfd *abfd); - *Description* -Call the OS to open a file for ABFD. Return the `FILE *' (possibly -`NULL') that results from this operation. Set up the BFD so that -future accesses know the file is open. If the `FILE *' returned is -`NULL', then it won't have been put in the cache, so it won't have to -be removed from it. - -2.17.0.8 `bfd_cache_lookup_worker' -.................................. - -*Synopsis* - FILE *bfd_cache_lookup_worker (bfd *abfd); - *Description* -Called when the macro `bfd_cache_lookup' fails to find a quick answer. -Find a file descriptor for ABFD. If necessary, it open it. If there -are already more than `BFD_CACHE_MAX_OPEN' files open, it tries to -close one first, to avoid running out of file descriptors. It will -abort rather than returning NULL if it is unable to (re)open the ABFD. - - -File: bfd.info, Node: Linker Functions, Next: Hash Tables, Prev: File Caching, Up: BFD front end - -2.18 Linker Functions -===================== - -The linker uses three special entry points in the BFD target vector. -It is not necessary to write special routines for these entry points -when creating a new BFD back end, since generic versions are provided. -However, writing them can speed up linking and make it use -significantly less runtime memory. - - The first routine creates a hash table used by the other routines. -The second routine adds the symbols from an object file to the hash -table. The third routine takes all the object files and links them -together to create the output file. These routines are designed so -that the linker proper does not need to know anything about the symbols -in the object files that it is linking. The linker merely arranges the -sections as directed by the linker script and lets BFD handle the -details of symbols and relocs. - - The second routine and third routines are passed a pointer to a -`struct bfd_link_info' structure (defined in `bfdlink.h') which holds -information relevant to the link, including the linker hash table -(which was created by the first routine) and a set of callback -functions to the linker proper. - - The generic linker routines are in `linker.c', and use the header -file `genlink.h'. As of this writing, the only back ends which have -implemented versions of these routines are a.out (in `aoutx.h') and -ECOFF (in `ecoff.c'). The a.out routines are used as examples -throughout this section. - -* Menu: - -* Creating a Linker Hash Table:: -* Adding Symbols to the Hash Table:: -* Performing the Final Link:: - - -File: bfd.info, Node: Creating a Linker Hash Table, Next: Adding Symbols to the Hash Table, Prev: Linker Functions, Up: Linker Functions - -2.18.1 Creating a linker hash table ------------------------------------ - -The linker routines must create a hash table, which must be derived -from `struct bfd_link_hash_table' described in `bfdlink.c'. *Note Hash -Tables::, for information on how to create a derived hash table. This -entry point is called using the target vector of the linker output file. - - The `_bfd_link_hash_table_create' entry point must allocate and -initialize an instance of the desired hash table. If the back end does -not require any additional information to be stored with the entries in -the hash table, the entry point may simply create a `struct -bfd_link_hash_table'. Most likely, however, some additional -information will be needed. - - For example, with each entry in the hash table the a.out linker -keeps the index the symbol has in the final output file (this index -number is used so that when doing a relocatable link the symbol index -used in the output file can be quickly filled in when copying over a -reloc). The a.out linker code defines the required structures and -functions for a hash table derived from `struct bfd_link_hash_table'. -The a.out linker hash table is created by the function -`NAME(aout,link_hash_table_create)'; it simply allocates space for the -hash table, initializes it, and returns a pointer to it. - - When writing the linker routines for a new back end, you will -generally not know exactly which fields will be required until you have -finished. You should simply create a new hash table which defines no -additional fields, and then simply add fields as they become necessary. - - -File: bfd.info, Node: Adding Symbols to the Hash Table, Next: Performing the Final Link, Prev: Creating a Linker Hash Table, Up: Linker Functions - -2.18.2 Adding symbols to the hash table ---------------------------------------- - -The linker proper will call the `_bfd_link_add_symbols' entry point for -each object file or archive which is to be linked (typically these are -the files named on the command line, but some may also come from the -linker script). The entry point is responsible for examining the file. -For an object file, BFD must add any relevant symbol information to -the hash table. For an archive, BFD must determine which elements of -the archive should be used and adding them to the link. - - The a.out version of this entry point is -`NAME(aout,link_add_symbols)'. - -* Menu: - -* Differing file formats:: -* Adding symbols from an object file:: -* Adding symbols from an archive:: - - -File: bfd.info, Node: Differing file formats, Next: Adding symbols from an object file, Prev: Adding Symbols to the Hash Table, Up: Adding Symbols to the Hash Table - -2.18.2.1 Differing file formats -............................... - -Normally all the files involved in a link will be of the same format, -but it is also possible to link together different format object files, -and the back end must support that. The `_bfd_link_add_symbols' entry -point is called via the target vector of the file to be added. This -has an important consequence: the function may not assume that the hash -table is the type created by the corresponding -`_bfd_link_hash_table_create' vector. All the `_bfd_link_add_symbols' -function can assume about the hash table is that it is derived from -`struct bfd_link_hash_table'. - - Sometimes the `_bfd_link_add_symbols' function must store some -information in the hash table entry to be used by the `_bfd_final_link' -function. In such a case the `creator' field of the hash table must be -checked to make sure that the hash table was created by an object file -of the same format. - - The `_bfd_final_link' routine must be prepared to handle a hash -entry without any extra information added by the -`_bfd_link_add_symbols' function. A hash entry without extra -information will also occur when the linker script directs the linker -to create a symbol. Note that, regardless of how a hash table entry is -added, all the fields will be initialized to some sort of null value by -the hash table entry initialization function. - - See `ecoff_link_add_externals' for an example of how to check the -`creator' field before saving information (in this case, the ECOFF -external symbol debugging information) in a hash table entry. - - -File: bfd.info, Node: Adding symbols from an object file, Next: Adding symbols from an archive, Prev: Differing file formats, Up: Adding Symbols to the Hash Table - -2.18.2.2 Adding symbols from an object file -........................................... - -When the `_bfd_link_add_symbols' routine is passed an object file, it -must add all externally visible symbols in that object file to the hash -table. The actual work of adding the symbol to the hash table is -normally handled by the function `_bfd_generic_link_add_one_symbol'. -The `_bfd_link_add_symbols' routine is responsible for reading all the -symbols from the object file and passing the correct information to -`_bfd_generic_link_add_one_symbol'. - - The `_bfd_link_add_symbols' routine should not use -`bfd_canonicalize_symtab' to read the symbols. The point of providing -this routine is to avoid the overhead of converting the symbols into -generic `asymbol' structures. - - `_bfd_generic_link_add_one_symbol' handles the details of combining -common symbols, warning about multiple definitions, and so forth. It -takes arguments which describe the symbol to add, notably symbol flags, -a section, and an offset. The symbol flags include such things as -`BSF_WEAK' or `BSF_INDIRECT'. The section is a section in the object -file, or something like `bfd_und_section_ptr' for an undefined symbol -or `bfd_com_section_ptr' for a common symbol. - - If the `_bfd_final_link' routine is also going to need to read the -symbol information, the `_bfd_link_add_symbols' routine should save it -somewhere attached to the object file BFD. However, the information -should only be saved if the `keep_memory' field of the `info' argument -is TRUE, so that the `-no-keep-memory' linker switch is effective. - - The a.out function which adds symbols from an object file is -`aout_link_add_object_symbols', and most of the interesting work is in -`aout_link_add_symbols'. The latter saves pointers to the hash tables -entries created by `_bfd_generic_link_add_one_symbol' indexed by symbol -number, so that the `_bfd_final_link' routine does not have to call the -hash table lookup routine to locate the entry. - - -File: bfd.info, Node: Adding symbols from an archive, Prev: Adding symbols from an object file, Up: Adding Symbols to the Hash Table - -2.18.2.3 Adding symbols from an archive -....................................... - -When the `_bfd_link_add_symbols' routine is passed an archive, it must -look through the symbols defined by the archive and decide which -elements of the archive should be included in the link. For each such -element it must call the `add_archive_element' linker callback, and it -must add the symbols from the object file to the linker hash table. - - In most cases the work of looking through the symbols in the archive -should be done by the `_bfd_generic_link_add_archive_symbols' function. -This function builds a hash table from the archive symbol table and -looks through the list of undefined symbols to see which elements -should be included. `_bfd_generic_link_add_archive_symbols' is passed -a function to call to make the final decision about adding an archive -element to the link and to do the actual work of adding the symbols to -the linker hash table. - - The function passed to `_bfd_generic_link_add_archive_symbols' must -read the symbols of the archive element and decide whether the archive -element should be included in the link. If the element is to be -included, the `add_archive_element' linker callback routine must be -called with the element as an argument, and the elements symbols must -be added to the linker hash table just as though the element had itself -been passed to the `_bfd_link_add_symbols' function. - - When the a.out `_bfd_link_add_symbols' function receives an archive, -it calls `_bfd_generic_link_add_archive_symbols' passing -`aout_link_check_archive_element' as the function argument. -`aout_link_check_archive_element' calls `aout_link_check_ar_symbols'. -If the latter decides to add the element (an element is only added if -it provides a real, non-common, definition for a previously undefined -or common symbol) it calls the `add_archive_element' callback and then -`aout_link_check_archive_element' calls `aout_link_add_symbols' to -actually add the symbols to the linker hash table. - - The ECOFF back end is unusual in that it does not normally call -`_bfd_generic_link_add_archive_symbols', because ECOFF archives already -contain a hash table of symbols. The ECOFF back end searches the -archive itself to avoid the overhead of creating a new hash table. - - -File: bfd.info, Node: Performing the Final Link, Prev: Adding Symbols to the Hash Table, Up: Linker Functions - -2.18.3 Performing the final link --------------------------------- - -When all the input files have been processed, the linker calls the -`_bfd_final_link' entry point of the output BFD. This routine is -responsible for producing the final output file, which has several -aspects. It must relocate the contents of the input sections and copy -the data into the output sections. It must build an output symbol -table including any local symbols from the input files and the global -symbols from the hash table. When producing relocatable output, it must -modify the input relocs and write them into the output file. There may -also be object format dependent work to be done. - - The linker will also call the `write_object_contents' entry point -when the BFD is closed. The two entry points must work together in -order to produce the correct output file. - - The details of how this works are inevitably dependent upon the -specific object file format. The a.out `_bfd_final_link' routine is -`NAME(aout,final_link)'. - -* Menu: - -* Information provided by the linker:: -* Relocating the section contents:: -* Writing the symbol table:: - - -File: bfd.info, Node: Information provided by the linker, Next: Relocating the section contents, Prev: Performing the Final Link, Up: Performing the Final Link - -2.18.3.1 Information provided by the linker -........................................... - -Before the linker calls the `_bfd_final_link' entry point, it sets up -some data structures for the function to use. - - The `input_bfds' field of the `bfd_link_info' structure will point -to a list of all the input files included in the link. These files are -linked through the `link_next' field of the `bfd' structure. - - Each section in the output file will have a list of `link_order' -structures attached to the `link_order_head' field (the `link_order' -structure is defined in `bfdlink.h'). These structures describe how to -create the contents of the output section in terms of the contents of -various input sections, fill constants, and, eventually, other types of -information. They also describe relocs that must be created by the BFD -backend, but do not correspond to any input file; this is used to -support -Ur, which builds constructors while generating a relocatable -object file. - - -File: bfd.info, Node: Relocating the section contents, Next: Writing the symbol table, Prev: Information provided by the linker, Up: Performing the Final Link - -2.18.3.2 Relocating the section contents -........................................ - -The `_bfd_final_link' function should look through the `link_order' -structures attached to each section of the output file. Each -`link_order' structure should either be handled specially, or it should -be passed to the function `_bfd_default_link_order' which will do the -right thing (`_bfd_default_link_order' is defined in `linker.c'). - - For efficiency, a `link_order' of type `bfd_indirect_link_order' -whose associated section belongs to a BFD of the same format as the -output BFD must be handled specially. This type of `link_order' -describes part of an output section in terms of a section belonging to -one of the input files. The `_bfd_final_link' function should read the -contents of the section and any associated relocs, apply the relocs to -the section contents, and write out the modified section contents. If -performing a relocatable link, the relocs themselves must also be -modified and written out. - - The functions `_bfd_relocate_contents' and -`_bfd_final_link_relocate' provide some general support for performing -the actual relocations, notably overflow checking. Their arguments -include information about the symbol the relocation is against and a -`reloc_howto_type' argument which describes the relocation to perform. -These functions are defined in `reloc.c'. - - The a.out function which handles reading, relocating, and writing -section contents is `aout_link_input_section'. The actual relocation -is done in `aout_link_input_section_std' and -`aout_link_input_section_ext'. - - -File: bfd.info, Node: Writing the symbol table, Prev: Relocating the section contents, Up: Performing the Final Link - -2.18.3.3 Writing the symbol table -................................. - -The `_bfd_final_link' function must gather all the symbols in the input -files and write them out. It must also write out all the symbols in -the global hash table. This must be controlled by the `strip' and -`discard' fields of the `bfd_link_info' structure. - - The local symbols of the input files will not have been entered into -the linker hash table. The `_bfd_final_link' routine must consider -each input file and include the symbols in the output file. It may be -convenient to do this when looking through the `link_order' structures, -or it may be done by stepping through the `input_bfds' list. - - The `_bfd_final_link' routine must also traverse the global hash -table to gather all the externally visible symbols. It is possible -that most of the externally visible symbols may be written out when -considering the symbols of each input file, but it is still necessary -to traverse the hash table since the linker script may have defined -some symbols that are not in any of the input files. - - The `strip' field of the `bfd_link_info' structure controls which -symbols are written out. The possible values are listed in -`bfdlink.h'. If the value is `strip_some', then the `keep_hash' field -of the `bfd_link_info' structure is a hash table of symbols to keep; -each symbol should be looked up in this hash table, and only symbols -which are present should be included in the output file. - - If the `strip' field of the `bfd_link_info' structure permits local -symbols to be written out, the `discard' field is used to further -controls which local symbols are included in the output file. If the -value is `discard_l', then all local symbols which begin with a certain -prefix are discarded; this is controlled by the -`bfd_is_local_label_name' entry point. - - The a.out backend handles symbols by calling -`aout_link_write_symbols' on each input BFD and then traversing the -global hash table with the function `aout_link_write_other_symbol'. It -builds a string table while writing out the symbols, which is written -to the output file at the end of `NAME(aout,final_link)'. - -2.18.3.4 `bfd_link_split_section' -................................. - -*Synopsis* - bfd_boolean bfd_link_split_section (bfd *abfd, asection *sec); - *Description* -Return nonzero if SEC should be split during a reloceatable or final -link. - #define bfd_link_split_section(abfd, sec) \ - BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) - -2.18.3.5 `bfd_section_already_linked' -..................................... - -*Synopsis* - void bfd_section_already_linked (bfd *abfd, asection *sec); - *Description* -Check if SEC has been already linked during a reloceatable or final -link. - #define bfd_section_already_linked(abfd, sec) \ - BFD_SEND (abfd, _section_already_linked, (abfd, sec)) - - -File: bfd.info, Node: Hash Tables, Prev: Linker Functions, Up: BFD front end - -2.19 Hash Tables -================ - -BFD provides a simple set of hash table functions. Routines are -provided to initialize a hash table, to free a hash table, to look up a -string in a hash table and optionally create an entry for it, and to -traverse a hash table. There is currently no routine to delete an -string from a hash table. - - The basic hash table does not permit any data to be stored with a -string. However, a hash table is designed to present a base class from -which other types of hash tables may be derived. These derived types -may store additional information with the string. Hash tables were -implemented in this way, rather than simply providing a data pointer in -a hash table entry, because they were designed for use by the linker -back ends. The linker may create thousands of hash table entries, and -the overhead of allocating private data and storing and following -pointers becomes noticeable. - - The basic hash table code is in `hash.c'. - -* Menu: - -* Creating and Freeing a Hash Table:: -* Looking Up or Entering a String:: -* Traversing a Hash Table:: -* Deriving a New Hash Table Type:: - - -File: bfd.info, Node: Creating and Freeing a Hash Table, Next: Looking Up or Entering a String, Prev: Hash Tables, Up: Hash Tables - -2.19.1 Creating and freeing a hash table ----------------------------------------- - -To create a hash table, create an instance of a `struct bfd_hash_table' -(defined in `bfd.h') and call `bfd_hash_table_init' (if you know -approximately how many entries you will need, the function -`bfd_hash_table_init_n', which takes a SIZE argument, may be used). -`bfd_hash_table_init' returns `FALSE' if some sort of error occurs. - - The function `bfd_hash_table_init' take as an argument a function to -use to create new entries. For a basic hash table, use the function -`bfd_hash_newfunc'. *Note Deriving a New Hash Table Type::, for why -you would want to use a different value for this argument. - - `bfd_hash_table_init' will create an objalloc which will be used to -allocate new entries. You may allocate memory on this objalloc using -`bfd_hash_allocate'. - - Use `bfd_hash_table_free' to free up all the memory that has been -allocated for a hash table. This will not free up the `struct -bfd_hash_table' itself, which you must provide. - - Use `bfd_hash_set_default_size' to set the default size of hash -table to use. - - -File: bfd.info, Node: Looking Up or Entering a String, Next: Traversing a Hash Table, Prev: Creating and Freeing a Hash Table, Up: Hash Tables - -2.19.2 Looking up or entering a string --------------------------------------- - -The function `bfd_hash_lookup' is used both to look up a string in the -hash table and to create a new entry. - - If the CREATE argument is `FALSE', `bfd_hash_lookup' will look up a -string. If the string is found, it will returns a pointer to a `struct -bfd_hash_entry'. If the string is not found in the table -`bfd_hash_lookup' will return `NULL'. You should not modify any of the -fields in the returns `struct bfd_hash_entry'. - - If the CREATE argument is `TRUE', the string will be entered into -the hash table if it is not already there. Either way a pointer to a -`struct bfd_hash_entry' will be returned, either to the existing -structure or to a newly created one. In this case, a `NULL' return -means that an error occurred. - - If the CREATE argument is `TRUE', and a new entry is created, the -COPY argument is used to decide whether to copy the string onto the -hash table objalloc or not. If COPY is passed as `FALSE', you must be -careful not to deallocate or modify the string as long as the hash table -exists. - - -File: bfd.info, Node: Traversing a Hash Table, Next: Deriving a New Hash Table Type, Prev: Looking Up or Entering a String, Up: Hash Tables - -2.19.3 Traversing a hash table ------------------------------- - -The function `bfd_hash_traverse' may be used to traverse a hash table, -calling a function on each element. The traversal is done in a random -order. - - `bfd_hash_traverse' takes as arguments a function and a generic -`void *' pointer. The function is called with a hash table entry (a -`struct bfd_hash_entry *') and the generic pointer passed to -`bfd_hash_traverse'. The function must return a `boolean' value, which -indicates whether to continue traversing the hash table. If the -function returns `FALSE', `bfd_hash_traverse' will stop the traversal -and return immediately. - - -File: bfd.info, Node: Deriving a New Hash Table Type, Prev: Traversing a Hash Table, Up: Hash Tables - -2.19.4 Deriving a new hash table type -------------------------------------- - -Many uses of hash tables want to store additional information which -each entry in the hash table. Some also find it convenient to store -additional information with the hash table itself. This may be done -using a derived hash table. - - Since C is not an object oriented language, creating a derived hash -table requires sticking together some boilerplate routines with a few -differences specific to the type of hash table you want to create. - - An example of a derived hash table is the linker hash table. The -structures for this are defined in `bfdlink.h'. The functions are in -`linker.c'. - - You may also derive a hash table from an already derived hash table. -For example, the a.out linker backend code uses a hash table derived -from the linker hash table. - -* Menu: - -* Define the Derived Structures:: -* Write the Derived Creation Routine:: -* Write Other Derived Routines:: - - -File: bfd.info, Node: Define the Derived Structures, Next: Write the Derived Creation Routine, Prev: Deriving a New Hash Table Type, Up: Deriving a New Hash Table Type - -2.19.4.1 Define the derived structures -...................................... - -You must define a structure for an entry in the hash table, and a -structure for the hash table itself. - - The first field in the structure for an entry in the hash table must -be of the type used for an entry in the hash table you are deriving -from. If you are deriving from a basic hash table this is `struct -bfd_hash_entry', which is defined in `bfd.h'. The first field in the -structure for the hash table itself must be of the type of the hash -table you are deriving from itself. If you are deriving from a basic -hash table, this is `struct bfd_hash_table'. - - For example, the linker hash table defines `struct -bfd_link_hash_entry' (in `bfdlink.h'). The first field, `root', is of -type `struct bfd_hash_entry'. Similarly, the first field in `struct -bfd_link_hash_table', `table', is of type `struct bfd_hash_table'. - - -File: bfd.info, Node: Write the Derived Creation Routine, Next: Write Other Derived Routines, Prev: Define the Derived Structures, Up: Deriving a New Hash Table Type - -2.19.4.2 Write the derived creation routine -........................................... - -You must write a routine which will create and initialize an entry in -the hash table. This routine is passed as the function argument to -`bfd_hash_table_init'. - - In order to permit other hash tables to be derived from the hash -table you are creating, this routine must be written in a standard way. - - The first argument to the creation routine is a pointer to a hash -table entry. This may be `NULL', in which case the routine should -allocate the right amount of space. Otherwise the space has already -been allocated by a hash table type derived from this one. - - After allocating space, the creation routine must call the creation -routine of the hash table type it is derived from, passing in a pointer -to the space it just allocated. This will initialize any fields used -by the base hash table. - - Finally the creation routine must initialize any local fields for -the new hash table type. - - Here is a boilerplate example of a creation routine. FUNCTION_NAME -is the name of the routine. ENTRY_TYPE is the type of an entry in the -hash table you are creating. BASE_NEWFUNC is the name of the creation -routine of the hash table type your hash table is derived from. - - struct bfd_hash_entry * - FUNCTION_NAME (entry, table, string) - struct bfd_hash_entry *entry; - struct bfd_hash_table *table; - const char *string; - { - struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry; - - /* Allocate the structure if it has not already been allocated by a - derived class. */ - if (ret == (ENTRY_TYPE *) NULL) - { - ret = ((ENTRY_TYPE *) - bfd_hash_allocate (table, sizeof (ENTRY_TYPE))); - if (ret == (ENTRY_TYPE *) NULL) - return NULL; - } - - /* Call the allocation method of the base class. */ - ret = ((ENTRY_TYPE *) - BASE_NEWFUNC ((struct bfd_hash_entry *) ret, table, string)); - - /* Initialize the local fields here. */ - - return (struct bfd_hash_entry *) ret; - } - *Description* -The creation routine for the linker hash table, which is in `linker.c', -looks just like this example. FUNCTION_NAME is -`_bfd_link_hash_newfunc'. ENTRY_TYPE is `struct bfd_link_hash_entry'. -BASE_NEWFUNC is `bfd_hash_newfunc', the creation routine for a basic -hash table. - - `_bfd_link_hash_newfunc' also initializes the local fields in a -linker hash table entry: `type', `written' and `next'. - - -File: bfd.info, Node: Write Other Derived Routines, Prev: Write the Derived Creation Routine, Up: Deriving a New Hash Table Type - -2.19.4.3 Write other derived routines -..................................... - -You will want to write other routines for your new hash table, as well. - - You will want an initialization routine which calls the -initialization routine of the hash table you are deriving from and -initializes any other local fields. For the linker hash table, this is -`_bfd_link_hash_table_init' in `linker.c'. - - You will want a lookup routine which calls the lookup routine of the -hash table you are deriving from and casts the result. The linker hash -table uses `bfd_link_hash_lookup' in `linker.c' (this actually takes an -additional argument which it uses to decide how to return the looked up -value). - - You may want a traversal routine. This should just call the -traversal routine of the hash table you are deriving from with -appropriate casts. The linker hash table uses `bfd_link_hash_traverse' -in `linker.c'. - - These routines may simply be defined as macros. For example, the -a.out backend linker hash table, which is derived from the linker hash -table, uses macros for the lookup and traversal routines. These are -`aout_link_hash_lookup' and `aout_link_hash_traverse' in aoutx.h. - - -File: bfd.info, Node: BFD back ends, Next: GNU Free Documentation License, Prev: BFD front end, Up: Top - -3 BFD back ends -*************** - -* Menu: - -* What to Put Where:: -* aout :: a.out backends -* coff :: coff backends -* elf :: elf backends -* mmo :: mmo backend - - -File: bfd.info, Node: What to Put Where, Next: aout, Prev: BFD back ends, Up: BFD back ends - - All of BFD lives in one directory. - - -File: bfd.info, Node: aout, Next: coff, Prev: What to Put Where, Up: BFD back ends - -3.1 a.out backends -================== - -*Description* -BFD supports a number of different flavours of a.out format, though the -major differences are only the sizes of the structures on disk, and the -shape of the relocation information. - - The support is split into a basic support file `aoutx.h' and other -files which derive functions from the base. One derivation file is -`aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions -support for sun3, sun4, 386 and 29k a.out files, to create a target -jump vector for a specific target. - - This information is further split out into more specific files for -each machine, including `sunos.c' for sun3 and sun4, `newsos3.c' for -the Sony NEWS, and `demo64.c' for a demonstration of a 64 bit a.out -format. - - The base file `aoutx.h' defines general mechanisms for reading and -writing records to and from disk and various other methods which BFD -requires. It is included by `aout32.c' and `aout64.c' to form the names -`aout_32_swap_exec_header_in', `aout_64_swap_exec_header_in', etc. - - As an example, this is what goes on to make the back end for a sun4, -from `aout32.c': - - #define ARCH_SIZE 32 - #include "aoutx.h" - - Which exports names: - - ... - aout_32_canonicalize_reloc - aout_32_find_nearest_line - aout_32_get_lineno - aout_32_get_reloc_upper_bound - ... - - from `sunos.c': - - #define TARGET_NAME "a.out-sunos-big" - #define VECNAME sunos_big_vec - #include "aoutf1.h" - - requires all the names from `aout32.c', and produces the jump vector - - sunos_big_vec - - The file `host-aout.c' is a special case. It is for a large set of -hosts that use "more or less standard" a.out files, and for which -cross-debugging is not interesting. It uses the standard 32-bit a.out -support routines, but determines the file offsets and addresses of the -text, data, and BSS sections, the machine architecture and machine -type, and the entry point address, in a host-dependent manner. Once -these values have been determined, generic code is used to handle the -object file. - - When porting it to run on a new system, you must supply: - - HOST_PAGE_SIZE - HOST_SEGMENT_SIZE - HOST_MACHINE_ARCH (optional) - HOST_MACHINE_MACHINE (optional) - HOST_TEXT_START_ADDR - HOST_STACK_END_ADDR - - in the file `../include/sys/h-XXX.h' (for your host). These values, -plus the structures and macros defined in `a.out.h' on your host -system, will produce a BFD target that will access ordinary a.out files -on your host. To configure a new machine to use `host-aout.c', specify: - - TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec - TDEPFILES= host-aout.o trad-core.o - - in the `config/XXX.mt' file, and modify `configure.in' to use the -`XXX.mt' file (by setting "`bfd_target=XXX'") when your configuration -is selected. - -3.1.1 Relocations ------------------ - -*Description* -The file `aoutx.h' provides for both the _standard_ and _extended_ -forms of a.out relocation records. - - The standard records contain only an address, a symbol index, and a -type field. The extended records (used on 29ks and sparcs) also have a -full integer for an addend. - -3.1.2 Internal entry points ---------------------------- - -*Description* -`aoutx.h' exports several routines for accessing the contents of an -a.out file, which are gathered and exported in turn by various format -specific files (eg sunos.c). - -3.1.2.1 `aout_SIZE_swap_exec_header_in' -....................................... - -*Synopsis* - void aout_SIZE_swap_exec_header_in, - (bfd *abfd, - struct external_exec *raw_bytes, - struct internal_exec *execp); - *Description* -Swap the information in an executable header RAW_BYTES taken from a raw -byte stream memory image into the internal exec header structure EXECP. - -3.1.2.2 `aout_SIZE_swap_exec_header_out' -........................................ - -*Synopsis* - void aout_SIZE_swap_exec_header_out - (bfd *abfd, - struct internal_exec *execp, - struct external_exec *raw_bytes); - *Description* -Swap the information in an internal exec header structure EXECP into -the buffer RAW_BYTES ready for writing to disk. - -3.1.2.3 `aout_SIZE_some_aout_object_p' -...................................... - -*Synopsis* - const bfd_target *aout_SIZE_some_aout_object_p - (bfd *abfd, - const bfd_target *(*callback_to_real_object_p) ()); - *Description* -Some a.out variant thinks that the file open in ABFD checking is an -a.out file. Do some more checking, and set up for access if it really -is. Call back to the calling environment's "finish up" function just -before returning, to handle any last-minute setup. - -3.1.2.4 `aout_SIZE_mkobject' -............................ - -*Synopsis* - bfd_boolean aout_SIZE_mkobject, (bfd *abfd); - *Description* -Initialize BFD ABFD for use with a.out files. - -3.1.2.5 `aout_SIZE_machine_type' -................................ - -*Synopsis* - enum machine_type aout_SIZE_machine_type - (enum bfd_architecture arch, - unsigned long machine)); - *Description* -Keep track of machine architecture and machine type for a.out's. Return -the `machine_type' for a particular architecture and machine, or -`M_UNKNOWN' if that exact architecture and machine can't be represented -in a.out format. - - If the architecture is understood, machine type 0 (default) is -always understood. - -3.1.2.6 `aout_SIZE_set_arch_mach' -................................. - -*Synopsis* - bfd_boolean aout_SIZE_set_arch_mach, - (bfd *, - enum bfd_architecture arch, - unsigned long machine)); - *Description* -Set the architecture and the machine of the BFD ABFD to the values ARCH -and MACHINE. Verify that ABFD's format can support the architecture -required. - -3.1.2.7 `aout_SIZE_new_section_hook' -.................................... - -*Synopsis* - bfd_boolean aout_SIZE_new_section_hook, - (bfd *abfd, - asection *newsect)); - *Description* -Called by the BFD in response to a `bfd_make_section' request. - - -File: bfd.info, Node: coff, Next: elf, Prev: aout, Up: BFD back ends - -3.2 coff backends -================= - -BFD supports a number of different flavours of coff format. The major -differences between formats are the sizes and alignments of fields in -structures on disk, and the occasional extra field. - - Coff in all its varieties is implemented with a few common files and -a number of implementation specific files. For example, The 88k bcs -coff format is implemented in the file `coff-m88k.c'. This file -`#include's `coff/m88k.h' which defines the external structure of the -coff format for the 88k, and `coff/internal.h' which defines the -internal structure. `coff-m88k.c' also defines the relocations used by -the 88k format *Note Relocations::. - - The Intel i960 processor version of coff is implemented in -`coff-i960.c'. This file has the same structure as `coff-m88k.c', -except that it includes `coff/i960.h' rather than `coff-m88k.h'. - -3.2.1 Porting to a new version of coff --------------------------------------- - -The recommended method is to select from the existing implementations -the version of coff which is most like the one you want to use. For -example, we'll say that i386 coff is the one you select, and that your -coff flavour is called foo. Copy `i386coff.c' to `foocoff.c', copy -`../include/coff/i386.h' to `../include/coff/foo.h', and add the lines -to `targets.c' and `Makefile.in' so that your new back end is used. -Alter the shapes of the structures in `../include/coff/foo.h' so that -they match what you need. You will probably also have to add `#ifdef's -to the code in `coff/internal.h' and `coffcode.h' if your version of -coff is too wild. - - You can verify that your new BFD backend works quite simply by -building `objdump' from the `binutils' directory, and making sure that -its version of what's going on and your host system's idea (assuming it -has the pretty standard coff dump utility, usually called `att-dump' or -just `dump') are the same. Then clean up your code, and send what -you've done to Cygnus. Then your stuff will be in the next release, and -you won't have to keep integrating it. - -3.2.2 How the coff backend works --------------------------------- - -3.2.2.1 File layout -................... - -The Coff backend is split into generic routines that are applicable to -any Coff target and routines that are specific to a particular target. -The target-specific routines are further split into ones which are -basically the same for all Coff targets except that they use the -external symbol format or use different values for certain constants. - - The generic routines are in `coffgen.c'. These routines work for -any Coff target. They use some hooks into the target specific code; -the hooks are in a `bfd_coff_backend_data' structure, one of which -exists for each target. - - The essentially similar target-specific routines are in -`coffcode.h'. This header file includes executable C code. The -various Coff targets first include the appropriate Coff header file, -make any special defines that are needed, and then include `coffcode.h'. - - Some of the Coff targets then also have additional routines in the -target source file itself. - - For example, `coff-i960.c' includes `coff/internal.h' and -`coff/i960.h'. It then defines a few constants, such as `I960', and -includes `coffcode.h'. Since the i960 has complex relocation types, -`coff-i960.c' also includes some code to manipulate the i960 relocs. -This code is not in `coffcode.h' because it would not be used by any -other target. - -3.2.2.2 Bit twiddling -..................... - -Each flavour of coff supported in BFD has its own header file -describing the external layout of the structures. There is also an -internal description of the coff layout, in `coff/internal.h'. A major -function of the coff backend is swapping the bytes and twiddling the -bits to translate the external form of the structures into the normal -internal form. This is all performed in the `bfd_swap'_thing_direction -routines. Some elements are different sizes between different versions -of coff; it is the duty of the coff version specific include file to -override the definitions of various packing routines in `coffcode.h'. -E.g., the size of line number entry in coff is sometimes 16 bits, and -sometimes 32 bits. `#define'ing `PUT_LNSZ_LNNO' and `GET_LNSZ_LNNO' -will select the correct one. No doubt, some day someone will find a -version of coff which has a varying field size not catered to at the -moment. To port BFD, that person will have to add more `#defines'. -Three of the bit twiddling routines are exported to `gdb'; -`coff_swap_aux_in', `coff_swap_sym_in' and `coff_swap_lineno_in'. `GDB' -reads the symbol table on its own, but uses BFD to fix things up. More -of the bit twiddlers are exported for `gas'; `coff_swap_aux_out', -`coff_swap_sym_out', `coff_swap_lineno_out', `coff_swap_reloc_out', -`coff_swap_filehdr_out', `coff_swap_aouthdr_out', -`coff_swap_scnhdr_out'. `Gas' currently keeps track of all the symbol -table and reloc drudgery itself, thereby saving the internal BFD -overhead, but uses BFD to swap things on the way out, making cross -ports much safer. Doing so also allows BFD (and thus the linker) to -use the same header files as `gas', which makes one avenue to disaster -disappear. - -3.2.2.3 Symbol reading -...................... - -The simple canonical form for symbols used by BFD is not rich enough to -keep all the information available in a coff symbol table. The back end -gets around this problem by keeping the original symbol table around, -"behind the scenes". - - When a symbol table is requested (through a call to -`bfd_canonicalize_symtab'), a request gets through to -`coff_get_normalized_symtab'. This reads the symbol table from the coff -file and swaps all the structures inside into the internal form. It -also fixes up all the pointers in the table (represented in the file by -offsets from the first symbol in the table) into physical pointers to -elements in the new internal table. This involves some work since the -meanings of fields change depending upon context: a field that is a -pointer to another structure in the symbol table at one moment may be -the size in bytes of a structure at the next. Another pass is made -over the table. All symbols which mark file names (`C_FILE' symbols) -are modified so that the internal string points to the value in the -auxent (the real filename) rather than the normal text associated with -the symbol (`".file"'). - - At this time the symbol names are moved around. Coff stores all -symbols less than nine characters long physically within the symbol -table; longer strings are kept at the end of the file in the string -table. This pass moves all strings into memory and replaces them with -pointers to the strings. - - The symbol table is massaged once again, this time to create the -canonical table used by the BFD application. Each symbol is inspected -in turn, and a decision made (using the `sclass' field) about the -various flags to set in the `asymbol'. *Note Symbols::. The generated -canonical table shares strings with the hidden internal symbol table. - - Any linenumbers are read from the coff file too, and attached to the -symbols which own the functions the linenumbers belong to. - -3.2.2.4 Symbol writing -...................... - -Writing a symbol to a coff file which didn't come from a coff file will -lose any debugging information. The `asymbol' structure remembers the -BFD from which the symbol was taken, and on output the back end makes -sure that the same destination target as source target is present. - - When the symbols have come from a coff file then all the debugging -information is preserved. - - Symbol tables are provided for writing to the back end in a vector -of pointers to pointers. This allows applications like the linker to -accumulate and output large symbol tables without having to do too much -byte copying. - - This function runs through the provided symbol table and patches -each symbol marked as a file place holder (`C_FILE') to point to the -next file place holder in the list. It also marks each `offset' field -in the list with the offset from the first symbol of the current symbol. - - Another function of this procedure is to turn the canonical value -form of BFD into the form used by coff. Internally, BFD expects symbol -values to be offsets from a section base; so a symbol physically at -0x120, but in a section starting at 0x100, would have the value 0x20. -Coff expects symbols to contain their final value, so symbols have -their values changed at this point to reflect their sum with their -owning section. This transformation uses the `output_section' field of -the `asymbol''s `asection' *Note Sections::. - - * `coff_mangle_symbols' - This routine runs though the provided symbol table and uses the -offsets generated by the previous pass and the pointers generated when -the symbol table was read in to create the structured hierarchy -required by coff. It changes each pointer to a symbol into the index -into the symbol table of the asymbol. - - * `coff_write_symbols' - This routine runs through the symbol table and patches up the -symbols from their internal form into the coff way, calls the bit -twiddlers, and writes out the table to the file. - -3.2.2.5 `coff_symbol_type' -.......................... - -*Description* -The hidden information for an `asymbol' is described in a -`combined_entry_type': - - - typedef struct coff_ptr_struct - { - /* Remembers the offset from the first symbol in the file for - this symbol. Generated by coff_renumber_symbols. */ - unsigned int offset; - - /* Should the value of this symbol be renumbered. Used for - XCOFF C_BSTAT symbols. Set by coff_slurp_symbol_table. */ - unsigned int fix_value : 1; - - /* Should the tag field of this symbol be renumbered. - Created by coff_pointerize_aux. */ - unsigned int fix_tag : 1; - - /* Should the endidx field of this symbol be renumbered. - Created by coff_pointerize_aux. */ - unsigned int fix_end : 1; - - /* Should the x_csect.x_scnlen field be renumbered. - Created by coff_pointerize_aux. */ - unsigned int fix_scnlen : 1; - - /* Fix up an XCOFF C_BINCL/C_EINCL symbol. The value is the - index into the line number entries. Set by coff_slurp_symbol_table. */ - unsigned int fix_line : 1; - - /* The container for the symbol structure as read and translated - from the file. */ - union - { - union internal_auxent auxent; - struct internal_syment syment; - } u; - } combined_entry_type; - - - /* Each canonical asymbol really looks like this: */ - - typedef struct coff_symbol_struct - { - /* The actual symbol which the rest of BFD works with */ - asymbol symbol; - - /* A pointer to the hidden information for this symbol */ - combined_entry_type *native; - - /* A pointer to the linenumber information for this symbol */ - struct lineno_cache_entry *lineno; - - /* Have the line numbers been relocated yet ? */ - bfd_boolean done_lineno; - } coff_symbol_type; - -3.2.2.6 `bfd_coff_backend_data' -............................... - - /* COFF symbol classifications. */ - - enum coff_symbol_classification - { - /* Global symbol. */ - COFF_SYMBOL_GLOBAL, - /* Common symbol. */ - COFF_SYMBOL_COMMON, - /* Undefined symbol. */ - COFF_SYMBOL_UNDEFINED, - /* Local symbol. */ - COFF_SYMBOL_LOCAL, - /* PE section symbol. */ - COFF_SYMBOL_PE_SECTION - }; -Special entry points for gdb to swap in coff symbol table parts: - typedef struct - { - void (*_bfd_coff_swap_aux_in) - PARAMS ((bfd *, PTR, int, int, int, int, PTR)); - - void (*_bfd_coff_swap_sym_in) - PARAMS ((bfd *, PTR, PTR)); - - void (*_bfd_coff_swap_lineno_in) - PARAMS ((bfd *, PTR, PTR)); - - unsigned int (*_bfd_coff_swap_aux_out) - PARAMS ((bfd *, PTR, int, int, int, int, PTR)); - - unsigned int (*_bfd_coff_swap_sym_out) - PARAMS ((bfd *, PTR, PTR)); - - unsigned int (*_bfd_coff_swap_lineno_out) - PARAMS ((bfd *, PTR, PTR)); - - unsigned int (*_bfd_coff_swap_reloc_out) - PARAMS ((bfd *, PTR, PTR)); - - unsigned int (*_bfd_coff_swap_filehdr_out) - PARAMS ((bfd *, PTR, PTR)); - - unsigned int (*_bfd_coff_swap_aouthdr_out) - PARAMS ((bfd *, PTR, PTR)); - - unsigned int (*_bfd_coff_swap_scnhdr_out) - PARAMS ((bfd *, PTR, PTR)); - - unsigned int _bfd_filhsz; - unsigned int _bfd_aoutsz; - unsigned int _bfd_scnhsz; - unsigned int _bfd_symesz; - unsigned int _bfd_auxesz; - unsigned int _bfd_relsz; - unsigned int _bfd_linesz; - unsigned int _bfd_filnmlen; - bfd_boolean _bfd_coff_long_filenames; - bfd_boolean _bfd_coff_long_section_names; - unsigned int _bfd_coff_default_section_alignment_power; - bfd_boolean _bfd_coff_force_symnames_in_strings; - unsigned int _bfd_coff_debug_string_prefix_length; - - void (*_bfd_coff_swap_filehdr_in) - PARAMS ((bfd *, PTR, PTR)); - - void (*_bfd_coff_swap_aouthdr_in) - PARAMS ((bfd *, PTR, PTR)); - - void (*_bfd_coff_swap_scnhdr_in) - PARAMS ((bfd *, PTR, PTR)); - - void (*_bfd_coff_swap_reloc_in) - PARAMS ((bfd *abfd, PTR, PTR)); - - bfd_boolean (*_bfd_coff_bad_format_hook) - PARAMS ((bfd *, PTR)); - - bfd_boolean (*_bfd_coff_set_arch_mach_hook) - PARAMS ((bfd *, PTR)); - - PTR (*_bfd_coff_mkobject_hook) - PARAMS ((bfd *, PTR, PTR)); - - bfd_boolean (*_bfd_styp_to_sec_flags_hook) - PARAMS ((bfd *, PTR, const char *, asection *, flagword *)); - - void (*_bfd_set_alignment_hook) - PARAMS ((bfd *, asection *, PTR)); - - bfd_boolean (*_bfd_coff_slurp_symbol_table) - PARAMS ((bfd *)); - - bfd_boolean (*_bfd_coff_symname_in_debug) - PARAMS ((bfd *, struct internal_syment *)); - - bfd_boolean (*_bfd_coff_pointerize_aux_hook) - PARAMS ((bfd *, combined_entry_type *, combined_entry_type *, - unsigned int, combined_entry_type *)); - - bfd_boolean (*_bfd_coff_print_aux) - PARAMS ((bfd *, FILE *, combined_entry_type *, combined_entry_type *, - combined_entry_type *, unsigned int)); - - void (*_bfd_coff_reloc16_extra_cases) - PARAMS ((bfd *, struct bfd_link_info *, struct bfd_link_order *, arelent *, - bfd_byte *, unsigned int *, unsigned int *)); - - int (*_bfd_coff_reloc16_estimate) - PARAMS ((bfd *, asection *, arelent *, unsigned int, - struct bfd_link_info *)); - - enum coff_symbol_classification (*_bfd_coff_classify_symbol) - PARAMS ((bfd *, struct internal_syment *)); - - bfd_boolean (*_bfd_coff_compute_section_file_positions) - PARAMS ((bfd *)); - - bfd_boolean (*_bfd_coff_start_final_link) - PARAMS ((bfd *, struct bfd_link_info *)); - - bfd_boolean (*_bfd_coff_relocate_section) - PARAMS ((bfd *, struct bfd_link_info *, bfd *, asection *, bfd_byte *, - struct internal_reloc *, struct internal_syment *, asection **)); - - reloc_howto_type *(*_bfd_coff_rtype_to_howto) - PARAMS ((bfd *, asection *, struct internal_reloc *, - struct coff_link_hash_entry *, struct internal_syment *, - bfd_vma *)); - - bfd_boolean (*_bfd_coff_adjust_symndx) - PARAMS ((bfd *, struct bfd_link_info *, bfd *, asection *, - struct internal_reloc *, bfd_boolean *)); - - bfd_boolean (*_bfd_coff_link_add_one_symbol) - PARAMS ((struct bfd_link_info *, bfd *, const char *, flagword, - asection *, bfd_vma, const char *, bfd_boolean, bfd_boolean, - struct bfd_link_hash_entry **)); - - bfd_boolean (*_bfd_coff_link_output_has_begun) - PARAMS ((bfd *, struct coff_final_link_info *)); - - bfd_boolean (*_bfd_coff_final_link_postscript) - PARAMS ((bfd *, struct coff_final_link_info *)); - - } bfd_coff_backend_data; - - #define coff_backend_info(abfd) \ - ((bfd_coff_backend_data *) (abfd)->xvec->backend_data) - - #define bfd_coff_swap_aux_in(a,e,t,c,ind,num,i) \ - ((coff_backend_info (a)->_bfd_coff_swap_aux_in) (a,e,t,c,ind,num,i)) - - #define bfd_coff_swap_sym_in(a,e,i) \ - ((coff_backend_info (a)->_bfd_coff_swap_sym_in) (a,e,i)) - - #define bfd_coff_swap_lineno_in(a,e,i) \ - ((coff_backend_info ( a)->_bfd_coff_swap_lineno_in) (a,e,i)) - - #define bfd_coff_swap_reloc_out(abfd, i, o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_out) (abfd, i, o)) - - #define bfd_coff_swap_lineno_out(abfd, i, o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_lineno_out) (abfd, i, o)) - - #define bfd_coff_swap_aux_out(a,i,t,c,ind,num,o) \ - ((coff_backend_info (a)->_bfd_coff_swap_aux_out) (a,i,t,c,ind,num,o)) - - #define bfd_coff_swap_sym_out(abfd, i,o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_sym_out) (abfd, i, o)) - - #define bfd_coff_swap_scnhdr_out(abfd, i,o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_out) (abfd, i, o)) - - #define bfd_coff_swap_filehdr_out(abfd, i,o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_out) (abfd, i, o)) - - #define bfd_coff_swap_aouthdr_out(abfd, i,o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_out) (abfd, i, o)) - - #define bfd_coff_filhsz(abfd) (coff_backend_info (abfd)->_bfd_filhsz) - #define bfd_coff_aoutsz(abfd) (coff_backend_info (abfd)->_bfd_aoutsz) - #define bfd_coff_scnhsz(abfd) (coff_backend_info (abfd)->_bfd_scnhsz) - #define bfd_coff_symesz(abfd) (coff_backend_info (abfd)->_bfd_symesz) - #define bfd_coff_auxesz(abfd) (coff_backend_info (abfd)->_bfd_auxesz) - #define bfd_coff_relsz(abfd) (coff_backend_info (abfd)->_bfd_relsz) - #define bfd_coff_linesz(abfd) (coff_backend_info (abfd)->_bfd_linesz) - #define bfd_coff_filnmlen(abfd) (coff_backend_info (abfd)->_bfd_filnmlen) - #define bfd_coff_long_filenames(abfd) \ - (coff_backend_info (abfd)->_bfd_coff_long_filenames) - #define bfd_coff_long_section_names(abfd) \ - (coff_backend_info (abfd)->_bfd_coff_long_section_names) - #define bfd_coff_default_section_alignment_power(abfd) \ - (coff_backend_info (abfd)->_bfd_coff_default_section_alignment_power) - #define bfd_coff_swap_filehdr_in(abfd, i,o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_filehdr_in) (abfd, i, o)) - - #define bfd_coff_swap_aouthdr_in(abfd, i,o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_aouthdr_in) (abfd, i, o)) - - #define bfd_coff_swap_scnhdr_in(abfd, i,o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_scnhdr_in) (abfd, i, o)) - - #define bfd_coff_swap_reloc_in(abfd, i, o) \ - ((coff_backend_info (abfd)->_bfd_coff_swap_reloc_in) (abfd, i, o)) - - #define bfd_coff_bad_format_hook(abfd, filehdr) \ - ((coff_backend_info (abfd)->_bfd_coff_bad_format_hook) (abfd, filehdr)) - - #define bfd_coff_set_arch_mach_hook(abfd, filehdr)\ - ((coff_backend_info (abfd)->_bfd_coff_set_arch_mach_hook) (abfd, filehdr)) - #define bfd_coff_mkobject_hook(abfd, filehdr, aouthdr)\ - ((coff_backend_info (abfd)->_bfd_coff_mkobject_hook)\ - (abfd, filehdr, aouthdr)) - - #define bfd_coff_styp_to_sec_flags_hook(abfd, scnhdr, name, section, flags_ptr)\ - ((coff_backend_info (abfd)->_bfd_styp_to_sec_flags_hook)\ - (abfd, scnhdr, name, section, flags_ptr)) - - #define bfd_coff_set_alignment_hook(abfd, sec, scnhdr)\ - ((coff_backend_info (abfd)->_bfd_set_alignment_hook) (abfd, sec, scnhdr)) - - #define bfd_coff_slurp_symbol_table(abfd)\ - ((coff_backend_info (abfd)->_bfd_coff_slurp_symbol_table) (abfd)) - - #define bfd_coff_symname_in_debug(abfd, sym)\ - ((coff_backend_info (abfd)->_bfd_coff_symname_in_debug) (abfd, sym)) - - #define bfd_coff_force_symnames_in_strings(abfd)\ - (coff_backend_info (abfd)->_bfd_coff_force_symnames_in_strings) - - #define bfd_coff_debug_string_prefix_length(abfd)\ - (coff_backend_info (abfd)->_bfd_coff_debug_string_prefix_length) - - #define bfd_coff_print_aux(abfd, file, base, symbol, aux, indaux)\ - ((coff_backend_info (abfd)->_bfd_coff_print_aux)\ - (abfd, file, base, symbol, aux, indaux)) - - #define bfd_coff_reloc16_extra_cases(abfd, link_info, link_order,\ - reloc, data, src_ptr, dst_ptr)\ - ((coff_backend_info (abfd)->_bfd_coff_reloc16_extra_cases)\ - (abfd, link_info, link_order, reloc, data, src_ptr, dst_ptr)) - - #define bfd_coff_reloc16_estimate(abfd, section, reloc, shrink, link_info)\ - ((coff_backend_info (abfd)->_bfd_coff_reloc16_estimate)\ - (abfd, section, reloc, shrink, link_info)) - - #define bfd_coff_classify_symbol(abfd, sym)\ - ((coff_backend_info (abfd)->_bfd_coff_classify_symbol)\ - (abfd, sym)) - - #define bfd_coff_compute_section_file_positions(abfd)\ - ((coff_backend_info (abfd)->_bfd_coff_compute_section_file_positions)\ - (abfd)) - - #define bfd_coff_start_final_link(obfd, info)\ - ((coff_backend_info (obfd)->_bfd_coff_start_final_link)\ - (obfd, info)) - #define bfd_coff_relocate_section(obfd,info,ibfd,o,con,rel,isyms,secs)\ - ((coff_backend_info (ibfd)->_bfd_coff_relocate_section)\ - (obfd, info, ibfd, o, con, rel, isyms, secs)) - #define bfd_coff_rtype_to_howto(abfd, sec, rel, h, sym, addendp)\ - ((coff_backend_info (abfd)->_bfd_coff_rtype_to_howto)\ - (abfd, sec, rel, h, sym, addendp)) - #define bfd_coff_adjust_symndx(obfd, info, ibfd, sec, rel, adjustedp)\ - ((coff_backend_info (abfd)->_bfd_coff_adjust_symndx)\ - (obfd, info, ibfd, sec, rel, adjustedp)) - #define bfd_coff_link_add_one_symbol(info, abfd, name, flags, section,\ - value, string, cp, coll, hashp)\ - ((coff_backend_info (abfd)->_bfd_coff_link_add_one_symbol)\ - (info, abfd, name, flags, section, value, string, cp, coll, hashp)) - - #define bfd_coff_link_output_has_begun(a,p) \ - ((coff_backend_info (a)->_bfd_coff_link_output_has_begun) (a,p)) - #define bfd_coff_final_link_postscript(a,p) \ - ((coff_backend_info (a)->_bfd_coff_final_link_postscript) (a,p)) - -3.2.2.7 Writing relocations -........................... - -To write relocations, the back end steps though the canonical -relocation table and create an `internal_reloc'. The symbol index to -use is removed from the `offset' field in the symbol table supplied. -The address comes directly from the sum of the section base address and -the relocation offset; the type is dug directly from the howto field. -Then the `internal_reloc' is swapped into the shape of an -`external_reloc' and written out to disk. - -3.2.2.8 Reading linenumbers -........................... - -Creating the linenumber table is done by reading in the entire coff -linenumber table, and creating another table for internal use. - - A coff linenumber table is structured so that each function is -marked as having a line number of 0. Each line within the function is -an offset from the first line in the function. The base of the line -number information for the table is stored in the symbol associated -with the function. - - Note: The PE format uses line number 0 for a flag indicating a new -source file. - - The information is copied from the external to the internal table, -and each symbol which marks a function is marked by pointing its... - - How does this work ? - -3.2.2.9 Reading relocations -........................... - -Coff relocations are easily transformed into the internal BFD form -(`arelent'). - - Reading a coff relocation table is done in the following stages: - - * Read the entire coff relocation table into memory. - - * Process each relocation in turn; first swap it from the external - to the internal form. - - * Turn the symbol referenced in the relocation's symbol index into a - pointer into the canonical symbol table. This table is the same - as the one returned by a call to `bfd_canonicalize_symtab'. The - back end will call that routine and save the result if a - canonicalization hasn't been done. - - * The reloc index is turned into a pointer to a howto structure, in - a back end specific way. For instance, the 386 and 960 use the - `r_type' to directly produce an index into a howto table vector; - the 88k subtracts a number from the `r_type' field and creates an - addend field. - - -File: bfd.info, Node: elf, Next: mmo, Prev: coff, Up: BFD back ends - -3.3 -=== - -ELF backends - - BFD support for ELF formats is being worked on. Currently, the best -supported back ends are for sparc and i386 (running svr4 or Solaris 2). - - Documentation of the internals of the support code still needs to be -written. The code is changing quickly enough that we haven't bothered -yet. - -3.3.0.1 `bfd_elf_find_section' -.............................. - -*Synopsis* - struct elf_internal_shdr *bfd_elf_find_section (bfd *abfd, char *name); - *Description* -Helper functions for GDB to locate the string tables. Since BFD hides -string tables from callers, GDB needs to use an internal hook to find -them. Sun's .stabstr, in particular, isn't even pointed to by the -.stab section, so ordinary mechanisms wouldn't work to find it, even if -we had some. - - -File: bfd.info, Node: mmo, Prev: elf, Up: BFD back ends - -3.4 mmo backend -=============== - -The mmo object format is used exclusively together with Professor -Donald E. Knuth's educational 64-bit processor MMIX. The simulator -`mmix' which is available at -`http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz' -understands this format. That package also includes a combined -assembler and linker called `mmixal'. The mmo format has no advantages -feature-wise compared to e.g. ELF. It is a simple non-relocatable -object format with no support for archives or debugging information, -except for symbol value information and line numbers (which is not yet -implemented in BFD). See -`http://www-cs-faculty.stanford.edu/~knuth/mmix.html' for more -information about MMIX. The ELF format is used for intermediate object -files in the BFD implementation. - -* Menu: - -* File layout:: -* Symbol-table:: -* mmo section mapping:: - - -File: bfd.info, Node: File layout, Next: Symbol-table, Prev: mmo, Up: mmo - -3.4.1 File layout ------------------ - -The mmo file contents is not partitioned into named sections as with -e.g. ELF. Memory areas is formed by specifying the location of the -data that follows. Only the memory area `0x0000...00' to `0x01ff...ff' -is executable, so it is used for code (and constants) and the area -`0x2000...00' to `0x20ff...ff' is used for writable data. *Note mmo -section mapping::. - - There is provision for specifying "special data" of 65536 different -types. We use type 80 (decimal), arbitrarily chosen the same as the -ELF `e_machine' number for MMIX, filling it with section information -normally found in ELF objects. *Note mmo section mapping::. - - Contents is entered as 32-bit words, xor:ed over previous contents, -always zero-initialized. A word that starts with the byte `0x98' forms -a command called a `lopcode', where the next byte distinguished between -the thirteen lopcodes. The two remaining bytes, called the `Y' and `Z' -fields, or the `YZ' field (a 16-bit big-endian number), are used for -various purposes different for each lopcode. As documented in -`http://www-cs-faculty.stanford.edu/~knuth/mmixal-intro.ps.gz', the -lopcodes are: - -`lop_quote' - 0x98000001. The next word is contents, regardless of whether it - starts with 0x98 or not. - -`lop_loc' - 0x9801YYZZ, where `Z' is 1 or 2. This is a location directive, - setting the location for the next data to the next 32-bit word - (for Z = 1) or 64-bit word (for Z = 2), plus Y * 2^56. Normally - `Y' is 0 for the text segment and 2 for the data segment. - -`lop_skip' - 0x9802YYZZ. Increase the current location by `YZ' bytes. - -`lop_fixo' - 0x9803YYZZ, where `Z' is 1 or 2. Store the current location as 64 - bits into the location pointed to by the next 32-bit (Z = 1) or - 64-bit (Z = 2) word, plus Y * 2^56. - -`lop_fixr' - 0x9804YYZZ. `YZ' is stored into the current location plus 2 - 4 * - YZ. - -`lop_fixrx' - 0x980500ZZ. `Z' is 16 or 24. A value `L' derived from the - following 32-bit word are used in a manner similar to `YZ' in - lop_fixr: it is xor:ed into the current location minus 4 * L. The - first byte of the word is 0 or 1. If it is 1, then L = (LOWEST 24 - BITS OF WORD) - 2^Z, if 0, then L = (LOWEST 24 BITS OF WORD). - -`lop_file' - 0x9806YYZZ. `Y' is the file number, `Z' is count of 32-bit words. - Set the file number to `Y' and the line counter to 0. The next Z - * 4 bytes contain the file name, padded with zeros if the count is - not a multiple of four. The same `Y' may occur multiple times, - but `Z' must be 0 for all but the first occurrence. - -`lop_line' - 0x9807YYZZ. `YZ' is the line number. Together with lop_file, it - forms the source location for the next 32-bit word. Note that for - each non-lopcode 32-bit word, line numbers are assumed incremented - by one. - -`lop_spec' - 0x9808YYZZ. `YZ' is the type number. Data until the next lopcode - other than lop_quote forms special data of type `YZ'. *Note mmo - section mapping::. - - Other types than 80, (or type 80 with a content that does not - parse) is stored in sections named `.MMIX.spec_data.N' where N is - the `YZ'-type. The flags for such a sections say not to allocate - or load the data. The vma is 0. Contents of multiple occurrences - of special data N is concatenated to the data of the previous - lop_spec Ns. The location in data or code at which the lop_spec - occurred is lost. - -`lop_pre' - 0x980901ZZ. The first lopcode in a file. The `Z' field forms the - length of header information in 32-bit words, where the first word - tells the time in seconds since `00:00:00 GMT Jan 1 1970'. - -`lop_post' - 0x980a00ZZ. Z > 32. This lopcode follows after all - content-generating lopcodes in a program. The `Z' field denotes - the value of `rG' at the beginning of the program. The following - 256 - Z big-endian 64-bit words are loaded into global registers - `$G' ... `$255'. - -`lop_stab' - 0x980b0000. The next-to-last lopcode in a program. Must follow - immediately after the lop_post lopcode and its data. After this - lopcode follows all symbols in a compressed format (*note - Symbol-table::). - -`lop_end' - 0x980cYYZZ. The last lopcode in a program. It must follow the - lop_stab lopcode and its data. The `YZ' field contains the number - of 32-bit words of symbol table information after the preceding - lop_stab lopcode. - - Note that the lopcode "fixups"; `lop_fixr', `lop_fixrx' and -`lop_fixo' are not generated by BFD, but are handled. They are -generated by `mmixal'. - - This trivial one-label, one-instruction file: - - :Main TRAP 1,2,3 - - can be represented this way in mmo: - - 0x98090101 - lop_pre, one 32-bit word with timestamp. - <timestamp> - 0x98010002 - lop_loc, text segment, using a 64-bit address. - Note that mmixal does not emit this for the file above. - 0x00000000 - Address, high 32 bits. - 0x00000000 - Address, low 32 bits. - 0x98060002 - lop_file, 2 32-bit words for file-name. - 0x74657374 - "test" - 0x2e730000 - ".s\0\0" - 0x98070001 - lop_line, line 1. - 0x00010203 - TRAP 1,2,3 - 0x980a00ff - lop_post, setting $255 to 0. - 0x00000000 - 0x00000000 - 0x980b0000 - lop_stab for ":Main" = 0, serial 1. - 0x203a4040 *Note Symbol-table::. - 0x10404020 - 0x4d206120 - 0x69016e00 - 0x81000000 - 0x980c0005 - lop_end; symbol table contained five 32-bit words. - - -File: bfd.info, Node: Symbol-table, Next: mmo section mapping, Prev: File layout, Up: mmo - -3.4.2 Symbol table format -------------------------- - -From mmixal.w (or really, the generated mmixal.tex) in -`http://www-cs-faculty.stanford.edu/~knuth/programs/mmix.tar.gz'): -"Symbols are stored and retrieved by means of a `ternary search trie', -following ideas of Bentley and Sedgewick. (See ACM-SIAM Symp. on -Discrete Algorithms `8' (1997), 360-369; R.Sedgewick, `Algorithms in C' -(Reading, Mass. Addison-Wesley, 1998), `15.4'.) Each trie node stores -a character, and there are branches to subtries for the cases where a -given character is less than, equal to, or greater than the character -in the trie. There also is a pointer to a symbol table entry if a -symbol ends at the current node." - - So it's a tree encoded as a stream of bytes. The stream of bytes -acts on a single virtual global symbol, adding and removing characters -and signalling complete symbol points. Here, we read the stream and -create symbols at the completion points. - - First, there's a control byte `m'. If any of the listed bits in `m' -is nonzero, we execute what stands at the right, in the listed order: - - (MMO3_LEFT) - 0x40 - Traverse left trie. - (Read a new command byte and recurse.) - - (MMO3_SYMBITS) - 0x2f - Read the next byte as a character and store it in the - current character position; increment character position. - Test the bits of `m': - - (MMO3_WCHAR) - 0x80 - The character is 16-bit (so read another byte, - merge into current character. - - (MMO3_TYPEBITS) - 0xf - We have a complete symbol; parse the type, value - and serial number and do what should be done - with a symbol. The type and length information - is in j = (m & 0xf). - - (MMO3_REGQUAL_BITS) - j == 0xf: A register variable. The following - byte tells which register. - j <= 8: An absolute symbol. Read j bytes as the - big-endian number the symbol equals. - A j = 2 with two zero bytes denotes an - unknown symbol. - j > 8: As with j <= 8, but add (0x20 << 56) - to the value in the following j - 8 - bytes. - - Then comes the serial number, as a variant of - uleb128, but better named ubeb128: - Read bytes and shift the previous value left 7 - (multiply by 128). Add in the new byte, repeat - until a byte has bit 7 set. The serial number - is the computed value minus 128. - - (MMO3_MIDDLE) - 0x20 - Traverse middle trie. (Read a new command byte - and recurse.) Decrement character position. - - (MMO3_RIGHT) - 0x10 - Traverse right trie. (Read a new command byte and - recurse.) - - Let's look again at the `lop_stab' for the trivial file (*note File -layout::). - - 0x980b0000 - lop_stab for ":Main" = 0, serial 1. - 0x203a4040 - 0x10404020 - 0x4d206120 - 0x69016e00 - 0x81000000 - - This forms the trivial trie (note that the path between ":" and "M" -is redundant): - - 203a ":" - 40 / - 40 / - 10 \ - 40 / - 40 / - 204d "M" - 2061 "a" - 2069 "i" - 016e "n" is the last character in a full symbol, and - with a value represented in one byte. - 00 The value is 0. - 81 The serial number is 1. - diff --git a/bfd/doc/bfd.info-2 b/bfd/doc/bfd.info-2 deleted file mode 100644 index 0485aed5b79..00000000000 --- a/bfd/doc/bfd.info-2 +++ /dev/null @@ -1,1702 +0,0 @@ -This is ../.././bfd/doc/bfd.info, produced by makeinfo version 4.7 from -../.././bfd/doc/bfd.texinfo. - -START-INFO-DIR-ENTRY -* Bfd: (bfd). The Binary File Descriptor library. -END-INFO-DIR-ENTRY - - This file documents the BFD library. - - Copyright (C) 1991, 2000, 2001, 2003 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with no Invariant Sections, with no Front-Cover Texts, and with no - Back-Cover Texts. A copy of the license is included in the -section entitled "GNU Free Documentation License". - - -File: bfd.info, Node: mmo section mapping, Prev: Symbol-table, Up: mmo - -3.4.3 mmo section mapping -------------------------- - -The implementation in BFD uses special data type 80 (decimal) to -encapsulate and describe named sections, containing e.g. debug -information. If needed, any datum in the encapsulation will be quoted -using lop_quote. First comes a 32-bit word holding the number of -32-bit words containing the zero-terminated zero-padded segment name. -After the name there's a 32-bit word holding flags describing the -section type. Then comes a 64-bit big-endian word with the section -length (in bytes), then another with the section start address. -Depending on the type of section, the contents might follow, -zero-padded to 32-bit boundary. For a loadable section (such as data -or code), the contents might follow at some later point, not -necessarily immediately, as a lop_loc with the same start address as in -the section description, followed by the contents. This in effect -forms a descriptor that must be emitted before the actual contents. -Sections described this way must not overlap. - - For areas that don't have such descriptors, synthetic sections are -formed by BFD. Consecutive contents in the two memory areas -`0x0000...00' to `0x01ff...ff' and `0x2000...00' to `0x20ff...ff' are -entered in sections named `.text' and `.data' respectively. If an area -is not otherwise described, but would together with a neighboring lower -area be less than `0x40000000' bytes long, it is joined with the lower -area and the gap is zero-filled. For other cases, a new section is -formed, named `.MMIX.sec.N'. Here, N is a number, a running count -through the mmo file, starting at 0. - - A loadable section specified as: - - .section secname,"ax" - TETRA 1,2,3,4,-1,-2009 - BYTE 80 - - and linked to address `0x4', is represented by the sequence: - - 0x98080050 - lop_spec 80 - 0x00000002 - two 32-bit words for the section name - 0x7365636e - "secn" - 0x616d6500 - "ame\0" - 0x00000033 - flags CODE, READONLY, LOAD, ALLOC - 0x00000000 - high 32 bits of section length - 0x0000001c - section length is 28 bytes; 6 * 4 + 1 + alignment to 32 bits - 0x00000000 - high 32 bits of section address - 0x00000004 - section address is 4 - 0x98010002 - 64 bits with address of following data - 0x00000000 - high 32 bits of address - 0x00000004 - low 32 bits: data starts at address 4 - 0x00000001 - 1 - 0x00000002 - 2 - 0x00000003 - 3 - 0x00000004 - 4 - 0xffffffff - -1 - 0xfffff827 - -2009 - 0x50000000 - 80 as a byte, padded with zeros. - - Note that the lop_spec wrapping does not include the section -contents. Compare this to a non-loaded section specified as: - - .section thirdsec - TETRA 200001,100002 - BYTE 38,40 - - This, when linked to address `0x200000000000001c', is represented by: - - 0x98080050 - lop_spec 80 - 0x00000002 - two 32-bit words for the section name - 0x7365636e - "thir" - 0x616d6500 - "dsec" - 0x00000010 - flag READONLY - 0x00000000 - high 32 bits of section length - 0x0000000c - section length is 12 bytes; 2 * 4 + 2 + alignment to 32 bits - 0x20000000 - high 32 bits of address - 0x0000001c - low 32 bits of address 0x200000000000001c - 0x00030d41 - 200001 - 0x000186a2 - 100002 - 0x26280000 - 38, 40 as bytes, padded with zeros - - For the latter example, the section contents must not be loaded in -memory, and is therefore specified as part of the special data. The -address is usually unimportant but might provide information for e.g. -the DWARF 2 debugging format. - - -File: bfd.info, Node: GNU Free Documentation License, Next: Index, Prev: BFD back ends, Up: Top - -Appendix A GNU Free Documentation License -***************************************** - - Version 1.1, March 2000 - - Copyright (C) 2000, 2003 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - - 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 - written 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 that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you." - - 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. - (For example, 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. - - 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 "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and 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 has been designed - to thwart or discourage subsequent modification by readers is not - Transparent. 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 designed for human modification. - Opaque formats include PostScript, PDF, 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 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. - - 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 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 publicly-accessible - computer-network location containing a complete Transparent copy - of the Document, free of added material, which the general - network-using public has access to download anonymously at no - charge using public-standard network protocols. 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 less than five). - 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", and 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. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, 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 as "Endorsements" or to - conflict in title with any Invariant Section. - - 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. - - 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, does not as a whole count as a - Modified Version of the Document, provided no compilation - copyright is claimed for the compilation. Such a compilation is - called an "aggregate", and this License does not apply to the - other self-contained works thus compiled with the Document, on - account of their being thus compiled, if they 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 - quarter of the entire aggregate, the Document's Cover Texts may be - placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License provided that you also include the - original English version of this License. In case of a - disagreement between the translation and the original English - version of this License, the original English version will prevail. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - http://www.gnu.org/copyleft/. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled "GNU - Free Documentation License." - - If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no Front-Cover -Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being -LIST"; likewise for Back-Cover Texts. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, to -permit their use in free software. - - -File: bfd.info, Node: Index, Prev: GNU Free Documentation License, Up: Top - -Index -***** - - -* Menu: - -* _bfd_final_link_relocate: Relocating the section contents. - (line 22) -* _bfd_generic_link_add_archive_symbols: Adding symbols from an archive. - (line 12) -* _bfd_generic_link_add_one_symbol: Adding symbols from an object file. - (line 19) -* _bfd_generic_make_empty_symbol: symbol handling functions. - (line 92) -* _bfd_link_add_symbols in target vector: Adding Symbols to the Hash Table. - (line 6) -* _bfd_link_final_link in target vector: Performing the Final Link. - (line 6) -* _bfd_link_hash_table_create in target vector: Creating a Linker Hash Table. - (line 6) -* _bfd_relocate_contents: Relocating the section contents. - (line 22) -* _bfd_strip_section_from_output: section prototypes. (line 242) -* aout_SIZE_machine_type: aout. (line 146) -* aout_SIZE_mkobject: aout. (line 138) -* aout_SIZE_new_section_hook: aout. (line 175) -* aout_SIZE_set_arch_mach: aout. (line 162) -* aout_SIZE_some_aout_object_p: aout. (line 125) -* aout_SIZE_swap_exec_header_in: aout. (line 101) -* aout_SIZE_swap_exec_header_out: aout. (line 113) -* arelent_chain: typedef arelent. (line 338) -* BFD: Overview. (line 6) -* BFD canonical format: Canonical format. (line 11) -* bfd_alloc: Opening and Closing. - (line 179) -* bfd_alt_mach_code: BFD front end. (line 588) -* bfd_arch_bits_per_address: Architectures. (line 453) -* bfd_arch_bits_per_byte: Architectures. (line 445) -* bfd_arch_get_compatible: Architectures. (line 388) -* bfd_arch_list: Architectures. (line 379) -* bfd_arch_mach_octets_per_byte: Architectures. (line 522) -* bfd_cache_close: File Caching. (line 53) -* bfd_cache_close_all: File Caching. (line 66) -* bfd_cache_init: File Caching. (line 45) -* bfd_cache_lookup: File Caching. (line 32) -* bfd_cache_lookup_worker: File Caching. (line 91) -* BFD_CACHE_MAX_OPEN macro: File Caching. (line 15) -* bfd_calc_gnu_debuglink_crc32: Opening and Closing. - (line 197) -* bfd_canonicalize_reloc: BFD front end. (line 315) -* bfd_canonicalize_symtab: symbol handling functions. - (line 50) -* bfd_check_format: Formats. (line 18) -* bfd_check_format_matches: Formats. (line 49) -* bfd_check_overflow: typedef arelent. (line 350) -* bfd_close: Opening and Closing. - (line 104) -* bfd_close_all_done: Opening and Closing. - (line 122) -* bfd_coff_backend_data: coff. (line 246) -* bfd_copy_private_bfd_data: BFD front end. (line 454) -* bfd_copy_private_header_data: BFD front end. (line 436) -* bfd_copy_private_section_data: section prototypes. (line 224) -* bfd_copy_private_symbol_data: symbol handling functions. - (line 140) -* bfd_core_file_failing_command: Core Files. (line 9) -* bfd_core_file_failing_signal: Core Files. (line 18) -* bfd_create: Opening and Closing. - (line 141) -* bfd_create_gnu_debuglink_section: Opening and Closing. - (line 263) -* bfd_decode_symclass: symbol handling functions. - (line 111) -* bfd_default_arch_struct: Architectures. (line 400) -* bfd_default_compatible: Architectures. (line 462) -* bfd_default_reloc_type_lookup: howto manager. (line 1704) -* bfd_default_scan: Architectures. (line 471) -* bfd_default_set_arch_mach: Architectures. (line 418) -* bfd_elf_find_section: elf. (line 15) -* bfd_errmsg: BFD front end. (line 243) -* bfd_fdopenr: Opening and Closing. - (line 22) -* bfd_fill_in_gnu_debuglink_section: Opening and Closing. - (line 277) -* bfd_find_target: bfd_target. (line 420) -* bfd_follow_gnu_debuglink: Opening and Closing. - (line 242) -* bfd_format_string: Formats. (line 76) -* bfd_generic_discard_group: section prototypes. (line 264) -* bfd_generic_gc_sections: howto manager. (line 1735) -* bfd_generic_get_relocated_section_contents: howto manager. (line 1755) -* bfd_generic_is_group_section: section prototypes. (line 256) -* bfd_generic_merge_sections: howto manager. (line 1745) -* bfd_generic_relax_section: howto manager. (line 1722) -* bfd_get_arch: Architectures. (line 429) -* bfd_get_arch_info: Architectures. (line 481) -* bfd_get_arch_size: BFD front end. (line 359) -* bfd_get_error: BFD front end. (line 226) -* bfd_get_error_handler: BFD front end. (line 294) -* bfd_get_gp_size: BFD front end. (line 400) -* bfd_get_mach: Architectures. (line 437) -* bfd_get_mtime: BFD front end. (line 676) -* bfd_get_next_mapent: Archives. (line 49) -* bfd_get_reloc_code_name: howto manager. (line 1713) -* bfd_get_reloc_size: typedef arelent. (line 329) -* bfd_get_reloc_upper_bound: BFD front end. (line 305) -* bfd_get_section_by_name: section prototypes. (line 17) -* bfd_get_section_by_name_if: section prototypes. (line 31) -* bfd_get_section_contents: section prototypes. (line 197) -* bfd_get_sign_extend_vma: BFD front end. (line 372) -* bfd_get_size <1>: Internal. (line 22) -* bfd_get_size: BFD front end. (line 685) -* bfd_get_symtab_upper_bound: symbol handling functions. - (line 6) -* bfd_get_unique_section_name: section prototypes. (line 50) -* bfd_h_put_size: Internal. (line 94) -* bfd_hash_allocate: Creating and Freeing a Hash Table. - (line 17) -* bfd_hash_lookup: Looking Up or Entering a String. - (line 6) -* bfd_hash_newfunc: Creating and Freeing a Hash Table. - (line 12) -* bfd_hash_set_default_size: Creating and Freeing a Hash Table. - (line 25) -* bfd_hash_table_free: Creating and Freeing a Hash Table. - (line 21) -* bfd_hash_table_init: Creating and Freeing a Hash Table. - (line 6) -* bfd_hash_table_init_n: Creating and Freeing a Hash Table. - (line 6) -* bfd_hash_traverse: Traversing a Hash Table. - (line 6) -* bfd_init: Initialization. (line 8) -* bfd_install_relocation: typedef arelent. (line 391) -* bfd_is_local_label: symbol handling functions. - (line 17) -* bfd_is_local_label_name: symbol handling functions. - (line 26) -* bfd_is_target_special_symbol: symbol handling functions. - (line 38) -* bfd_is_undefined_symclass: symbol handling functions. - (line 120) -* bfd_last_cache: File Caching. (line 22) -* bfd_link_split_section: Writing the symbol table. - (line 44) -* bfd_log2: Internal. (line 161) -* bfd_lookup_arch: Architectures. (line 489) -* bfd_make_debug_symbol: symbol handling functions. - (line 102) -* bfd_make_empty_symbol: symbol handling functions. - (line 78) -* bfd_make_readable: Opening and Closing. - (line 165) -* bfd_make_section: section prototypes. (line 98) -* bfd_make_section_anyway: section prototypes. (line 82) -* bfd_make_section_old_way: section prototypes. (line 62) -* bfd_make_writable: Opening and Closing. - (line 151) -* bfd_malloc_and_get_section: section prototypes. (line 214) -* bfd_map_over_sections: section prototypes. (line 124) -* bfd_merge_private_bfd_data: BFD front end. (line 470) -* bfd_octets_per_byte: Architectures. (line 512) -* bfd_open_file: File Caching. (line 79) -* bfd_openr: Opening and Closing. - (line 6) -* bfd_openr_iovec: Opening and Closing. - (line 52) -* bfd_openr_next_archived_file: Archives. (line 75) -* bfd_openstreamr: Opening and Closing. - (line 43) -* bfd_openw: Opening and Closing. - (line 92) -* bfd_perform_relocation: typedef arelent. (line 366) -* bfd_perror: BFD front end. (line 252) -* bfd_preserve_finish: BFD front end. (line 636) -* bfd_preserve_restore: BFD front end. (line 626) -* bfd_preserve_save: BFD front end. (line 610) -* bfd_print_symbol_vandf: symbol handling functions. - (line 70) -* bfd_printable_arch_mach: Architectures. (line 500) -* bfd_printable_name: Architectures. (line 360) -* bfd_put_size: Internal. (line 19) -* BFD_RELOC_12_PCREL: howto manager. (line 39) -* BFD_RELOC_14: howto manager. (line 31) -* BFD_RELOC_16: howto manager. (line 30) -* BFD_RELOC_16_BASEREL: howto manager. (line 80) -* BFD_RELOC_16_GOT_PCREL: howto manager. (line 52) -* BFD_RELOC_16_GOTOFF: howto manager. (line 55) -* BFD_RELOC_16_PCREL: howto manager. (line 38) -* BFD_RELOC_16_PCREL_S2: howto manager. (line 92) -* BFD_RELOC_16_PLT_PCREL: howto manager. (line 63) -* BFD_RELOC_16_PLTOFF: howto manager. (line 67) -* BFD_RELOC_16C_ABS20: howto manager. (line 1464) -* BFD_RELOC_16C_ABS20_C: howto manager. (line 1465) -* BFD_RELOC_16C_ABS24: howto manager. (line 1466) -* BFD_RELOC_16C_ABS24_C: howto manager. (line 1467) -* BFD_RELOC_16C_DISP04: howto manager. (line 1444) -* BFD_RELOC_16C_DISP04_C: howto manager. (line 1445) -* BFD_RELOC_16C_DISP08: howto manager. (line 1446) -* BFD_RELOC_16C_DISP08_C: howto manager. (line 1447) -* BFD_RELOC_16C_DISP16: howto manager. (line 1448) -* BFD_RELOC_16C_DISP16_C: howto manager. (line 1449) -* BFD_RELOC_16C_DISP24: howto manager. (line 1450) -* BFD_RELOC_16C_DISP24_C: howto manager. (line 1451) -* BFD_RELOC_16C_DISP24a: howto manager. (line 1452) -* BFD_RELOC_16C_DISP24a_C: howto manager. (line 1453) -* BFD_RELOC_16C_IMM04: howto manager. (line 1468) -* BFD_RELOC_16C_IMM04_C: howto manager. (line 1469) -* BFD_RELOC_16C_IMM16: howto manager. (line 1470) -* BFD_RELOC_16C_IMM16_C: howto manager. (line 1471) -* BFD_RELOC_16C_IMM20: howto manager. (line 1472) -* BFD_RELOC_16C_IMM20_C: howto manager. (line 1473) -* BFD_RELOC_16C_IMM24: howto manager. (line 1474) -* BFD_RELOC_16C_IMM24_C: howto manager. (line 1475) -* BFD_RELOC_16C_IMM32: howto manager. (line 1476) -* BFD_RELOC_16C_IMM32_C: howto manager. (line 1477) -* BFD_RELOC_16C_NUM08: howto manager. (line 1438) -* BFD_RELOC_16C_NUM08_C: howto manager. (line 1439) -* BFD_RELOC_16C_NUM16: howto manager. (line 1440) -* BFD_RELOC_16C_NUM16_C: howto manager. (line 1441) -* BFD_RELOC_16C_NUM32: howto manager. (line 1442) -* BFD_RELOC_16C_NUM32_C: howto manager. (line 1443) -* BFD_RELOC_16C_REG04: howto manager. (line 1454) -* BFD_RELOC_16C_REG04_C: howto manager. (line 1455) -* BFD_RELOC_16C_REG04a: howto manager. (line 1456) -* BFD_RELOC_16C_REG04a_C: howto manager. (line 1457) -* BFD_RELOC_16C_REG14: howto manager. (line 1458) -* BFD_RELOC_16C_REG14_C: howto manager. (line 1459) -* BFD_RELOC_16C_REG16: howto manager. (line 1460) -* BFD_RELOC_16C_REG16_C: howto manager. (line 1461) -* BFD_RELOC_16C_REG20: howto manager. (line 1462) -* BFD_RELOC_16C_REG20_C: howto manager. (line 1463) -* BFD_RELOC_23_PCREL_S2: howto manager. (line 93) -* BFD_RELOC_24: howto manager. (line 29) -* BFD_RELOC_24_PCREL: howto manager. (line 37) -* BFD_RELOC_24_PLT_PCREL: howto manager. (line 62) -* BFD_RELOC_26: howto manager. (line 28) -* BFD_RELOC_32: howto manager. (line 27) -* BFD_RELOC_32_BASEREL: howto manager. (line 79) -* BFD_RELOC_32_GOT_PCREL: howto manager. (line 51) -* BFD_RELOC_32_GOTOFF: howto manager. (line 54) -* BFD_RELOC_32_PCREL: howto manager. (line 36) -* BFD_RELOC_32_PCREL_S2: howto manager. (line 91) -* BFD_RELOC_32_PLT_PCREL: howto manager. (line 61) -* BFD_RELOC_32_PLTOFF: howto manager. (line 66) -* BFD_RELOC_32_SECREL: howto manager. (line 48) -* BFD_RELOC_386_COPY: howto manager. (line 422) -* BFD_RELOC_386_GLOB_DAT: howto manager. (line 423) -* BFD_RELOC_386_GOT32: howto manager. (line 420) -* BFD_RELOC_386_GOTOFF: howto manager. (line 426) -* BFD_RELOC_386_GOTPC: howto manager. (line 427) -* BFD_RELOC_386_JUMP_SLOT: howto manager. (line 424) -* BFD_RELOC_386_PLT32: howto manager. (line 421) -* BFD_RELOC_386_RELATIVE: howto manager. (line 425) -* BFD_RELOC_386_TLS_DTPMOD32: howto manager. (line 437) -* BFD_RELOC_386_TLS_DTPOFF32: howto manager. (line 438) -* BFD_RELOC_386_TLS_GD: howto manager. (line 432) -* BFD_RELOC_386_TLS_GOTIE: howto manager. (line 430) -* BFD_RELOC_386_TLS_IE: howto manager. (line 429) -* BFD_RELOC_386_TLS_IE_32: howto manager. (line 435) -* BFD_RELOC_386_TLS_LDM: howto manager. (line 433) -* BFD_RELOC_386_TLS_LDO_32: howto manager. (line 434) -* BFD_RELOC_386_TLS_LE: howto manager. (line 431) -* BFD_RELOC_386_TLS_LE_32: howto manager. (line 436) -* BFD_RELOC_386_TLS_TPOFF: howto manager. (line 428) -* BFD_RELOC_386_TLS_TPOFF32: howto manager. (line 439) -* BFD_RELOC_390_12: howto manager. (line 1155) -* BFD_RELOC_390_20: howto manager. (line 1255) -* BFD_RELOC_390_COPY: howto manager. (line 1164) -* BFD_RELOC_390_GLOB_DAT: howto manager. (line 1167) -* BFD_RELOC_390_GOT12: howto manager. (line 1158) -* BFD_RELOC_390_GOT16: howto manager. (line 1179) -* BFD_RELOC_390_GOT20: howto manager. (line 1256) -* BFD_RELOC_390_GOT64: howto manager. (line 1197) -* BFD_RELOC_390_GOTENT: howto manager. (line 1203) -* BFD_RELOC_390_GOTOFF64: howto manager. (line 1206) -* BFD_RELOC_390_GOTPC: howto manager. (line 1176) -* BFD_RELOC_390_GOTPCDBL: howto manager. (line 1194) -* BFD_RELOC_390_GOTPLT12: howto manager. (line 1209) -* BFD_RELOC_390_GOTPLT16: howto manager. (line 1212) -* BFD_RELOC_390_GOTPLT20: howto manager. (line 1257) -* BFD_RELOC_390_GOTPLT32: howto manager. (line 1215) -* BFD_RELOC_390_GOTPLT64: howto manager. (line 1218) -* BFD_RELOC_390_GOTPLTENT: howto manager. (line 1221) -* BFD_RELOC_390_JMP_SLOT: howto manager. (line 1170) -* BFD_RELOC_390_PC16DBL: howto manager. (line 1182) -* BFD_RELOC_390_PC32DBL: howto manager. (line 1188) -* BFD_RELOC_390_PLT16DBL: howto manager. (line 1185) -* BFD_RELOC_390_PLT32: howto manager. (line 1161) -* BFD_RELOC_390_PLT32DBL: howto manager. (line 1191) -* BFD_RELOC_390_PLT64: howto manager. (line 1200) -* BFD_RELOC_390_PLTOFF16: howto manager. (line 1224) -* BFD_RELOC_390_PLTOFF32: howto manager. (line 1227) -* BFD_RELOC_390_PLTOFF64: howto manager. (line 1230) -* BFD_RELOC_390_RELATIVE: howto manager. (line 1173) -* BFD_RELOC_390_TLS_DTPMOD: howto manager. (line 1250) -* BFD_RELOC_390_TLS_DTPOFF: howto manager. (line 1251) -* BFD_RELOC_390_TLS_GD32: howto manager. (line 1236) -* BFD_RELOC_390_TLS_GD64: howto manager. (line 1237) -* BFD_RELOC_390_TLS_GDCALL: howto manager. (line 1234) -* BFD_RELOC_390_TLS_GOTIE12: howto manager. (line 1238) -* BFD_RELOC_390_TLS_GOTIE20: howto manager. (line 1258) -* BFD_RELOC_390_TLS_GOTIE32: howto manager. (line 1239) -* BFD_RELOC_390_TLS_GOTIE64: howto manager. (line 1240) -* BFD_RELOC_390_TLS_IE32: howto manager. (line 1243) -* BFD_RELOC_390_TLS_IE64: howto manager. (line 1244) -* BFD_RELOC_390_TLS_IEENT: howto manager. (line 1245) -* BFD_RELOC_390_TLS_LDCALL: howto manager. (line 1235) -* BFD_RELOC_390_TLS_LDM32: howto manager. (line 1241) -* BFD_RELOC_390_TLS_LDM64: howto manager. (line 1242) -* BFD_RELOC_390_TLS_LDO32: howto manager. (line 1248) -* BFD_RELOC_390_TLS_LDO64: howto manager. (line 1249) -* BFD_RELOC_390_TLS_LE32: howto manager. (line 1246) -* BFD_RELOC_390_TLS_LE64: howto manager. (line 1247) -* BFD_RELOC_390_TLS_LOAD: howto manager. (line 1233) -* BFD_RELOC_390_TLS_TPOFF: howto manager. (line 1252) -* BFD_RELOC_64: howto manager. (line 26) -* BFD_RELOC_64_PCREL: howto manager. (line 35) -* BFD_RELOC_64_PLT_PCREL: howto manager. (line 60) -* BFD_RELOC_64_PLTOFF: howto manager. (line 65) -* BFD_RELOC_68K_GLOB_DAT: howto manager. (line 74) -* BFD_RELOC_68K_JMP_SLOT: howto manager. (line 75) -* BFD_RELOC_68K_RELATIVE: howto manager. (line 76) -* BFD_RELOC_8: howto manager. (line 32) -* BFD_RELOC_860_COPY: howto manager. (line 1543) -* BFD_RELOC_860_GLOB_DAT: howto manager. (line 1544) -* BFD_RELOC_860_HAGOT: howto manager. (line 1569) -* BFD_RELOC_860_HAGOTOFF: howto manager. (line 1570) -* BFD_RELOC_860_HAPC: howto manager. (line 1571) -* BFD_RELOC_860_HIGH: howto manager. (line 1572) -* BFD_RELOC_860_HIGHADJ: howto manager. (line 1568) -* BFD_RELOC_860_HIGOT: howto manager. (line 1573) -* BFD_RELOC_860_HIGOTOFF: howto manager. (line 1574) -* BFD_RELOC_860_JUMP_SLOT: howto manager. (line 1545) -* BFD_RELOC_860_LOGOT0: howto manager. (line 1557) -* BFD_RELOC_860_LOGOT1: howto manager. (line 1559) -* BFD_RELOC_860_LOGOTOFF0: howto manager. (line 1561) -* BFD_RELOC_860_LOGOTOFF1: howto manager. (line 1563) -* BFD_RELOC_860_LOGOTOFF2: howto manager. (line 1565) -* BFD_RELOC_860_LOGOTOFF3: howto manager. (line 1566) -* BFD_RELOC_860_LOPC: howto manager. (line 1567) -* BFD_RELOC_860_LOW0: howto manager. (line 1550) -* BFD_RELOC_860_LOW1: howto manager. (line 1552) -* BFD_RELOC_860_LOW2: howto manager. (line 1554) -* BFD_RELOC_860_LOW3: howto manager. (line 1556) -* BFD_RELOC_860_PC16: howto manager. (line 1549) -* BFD_RELOC_860_PC26: howto manager. (line 1547) -* BFD_RELOC_860_PLT26: howto manager. (line 1548) -* BFD_RELOC_860_RELATIVE: howto manager. (line 1546) -* BFD_RELOC_860_SPGOT0: howto manager. (line 1558) -* BFD_RELOC_860_SPGOT1: howto manager. (line 1560) -* BFD_RELOC_860_SPGOTOFF0: howto manager. (line 1562) -* BFD_RELOC_860_SPGOTOFF1: howto manager. (line 1564) -* BFD_RELOC_860_SPLIT0: howto manager. (line 1551) -* BFD_RELOC_860_SPLIT1: howto manager. (line 1553) -* BFD_RELOC_860_SPLIT2: howto manager. (line 1555) -* BFD_RELOC_8_BASEREL: howto manager. (line 84) -* BFD_RELOC_8_FFnn: howto manager. (line 88) -* BFD_RELOC_8_GOT_PCREL: howto manager. (line 53) -* BFD_RELOC_8_GOTOFF: howto manager. (line 59) -* BFD_RELOC_8_PCREL: howto manager. (line 40) -* BFD_RELOC_8_PLT_PCREL: howto manager. (line 64) -* BFD_RELOC_8_PLTOFF: howto manager. (line 71) -* BFD_RELOC_ALPHA_BRSGP: howto manager. (line 259) -* BFD_RELOC_ALPHA_CODEADDR: howto manager. (line 250) -* BFD_RELOC_ALPHA_DTPMOD64: howto manager. (line 266) -* BFD_RELOC_ALPHA_DTPREL16: howto manager. (line 271) -* BFD_RELOC_ALPHA_DTPREL64: howto manager. (line 268) -* BFD_RELOC_ALPHA_DTPREL_HI16: howto manager. (line 269) -* BFD_RELOC_ALPHA_DTPREL_LO16: howto manager. (line 270) -* BFD_RELOC_ALPHA_ELF_LITERAL: howto manager. (line 215) -* BFD_RELOC_ALPHA_GOTDTPREL16: howto manager. (line 267) -* BFD_RELOC_ALPHA_GOTTPREL16: howto manager. (line 272) -* BFD_RELOC_ALPHA_GPDISP: howto manager. (line 209) -* BFD_RELOC_ALPHA_GPDISP_HI16: howto manager. (line 195) -* BFD_RELOC_ALPHA_GPDISP_LO16: howto manager. (line 203) -* BFD_RELOC_ALPHA_GPREL_HI16: howto manager. (line 254) -* BFD_RELOC_ALPHA_GPREL_LO16: howto manager. (line 255) -* BFD_RELOC_ALPHA_HINT: howto manager. (line 241) -* BFD_RELOC_ALPHA_LINKAGE: howto manager. (line 246) -* BFD_RELOC_ALPHA_LITERAL: howto manager. (line 214) -* BFD_RELOC_ALPHA_LITUSE: howto manager. (line 216) -* BFD_RELOC_ALPHA_TLSGD: howto manager. (line 264) -* BFD_RELOC_ALPHA_TLSLDM: howto manager. (line 265) -* BFD_RELOC_ALPHA_TPREL16: howto manager. (line 276) -* BFD_RELOC_ALPHA_TPREL64: howto manager. (line 273) -* BFD_RELOC_ALPHA_TPREL_HI16: howto manager. (line 274) -* BFD_RELOC_ALPHA_TPREL_LO16: howto manager. (line 275) -* BFD_RELOC_ARC_B22_PCREL: howto manager. (line 754) -* BFD_RELOC_ARC_B26: howto manager. (line 759) -* BFD_RELOC_ARM_ADR_IMM: howto manager. (line 615) -* BFD_RELOC_ARM_ADRL_IMMEDIATE: howto manager. (line 607) -* BFD_RELOC_ARM_COPY: howto manager. (line 628) -* BFD_RELOC_ARM_CP_OFF_IMM: howto manager. (line 613) -* BFD_RELOC_ARM_CP_OFF_IMM_S2: howto manager. (line 614) -* BFD_RELOC_ARM_GLOB_DAT: howto manager. (line 629) -* BFD_RELOC_ARM_GOT12: howto manager. (line 625) -* BFD_RELOC_ARM_GOT32: howto manager. (line 626) -* BFD_RELOC_ARM_GOTOFF: howto manager. (line 632) -* BFD_RELOC_ARM_GOTPC: howto manager. (line 633) -* BFD_RELOC_ARM_HWLITERAL: howto manager. (line 620) -* BFD_RELOC_ARM_IMMEDIATE: howto manager. (line 606) -* BFD_RELOC_ARM_IN_POOL: howto manager. (line 618) -* BFD_RELOC_ARM_JUMP_SLOT: howto manager. (line 627) -* BFD_RELOC_ARM_LDR_IMM: howto manager. (line 616) -* BFD_RELOC_ARM_LITERAL: howto manager. (line 617) -* BFD_RELOC_ARM_MULTI: howto manager. (line 612) -* BFD_RELOC_ARM_OFFSET_IMM: howto manager. (line 608) -* BFD_RELOC_ARM_OFFSET_IMM8: howto manager. (line 619) -* BFD_RELOC_ARM_PCREL_BLX: howto manager. (line 596) -* BFD_RELOC_ARM_PCREL_BRANCH: howto manager. (line 592) -* BFD_RELOC_ARM_PLT32: howto manager. (line 630) -* BFD_RELOC_ARM_PREL31: howto manager. (line 652) -* BFD_RELOC_ARM_RELATIVE: howto manager. (line 631) -* BFD_RELOC_ARM_ROSEGREL32: howto manager. (line 641) -* BFD_RELOC_ARM_SBREL32: howto manager. (line 644) -* BFD_RELOC_ARM_SHIFT_IMM: howto manager. (line 609) -* BFD_RELOC_ARM_SMI: howto manager. (line 610) -* BFD_RELOC_ARM_SWI: howto manager. (line 611) -* BFD_RELOC_ARM_TARGET1: howto manager. (line 637) -* BFD_RELOC_ARM_TARGET2: howto manager. (line 647) -* BFD_RELOC_ARM_THUMB_ADD: howto manager. (line 621) -* BFD_RELOC_ARM_THUMB_IMM: howto manager. (line 622) -* BFD_RELOC_ARM_THUMB_OFFSET: howto manager. (line 624) -* BFD_RELOC_ARM_THUMB_SHIFT: howto manager. (line 623) -* BFD_RELOC_AVR_13_PCREL: howto manager. (line 1076) -* BFD_RELOC_AVR_16_PM: howto manager. (line 1080) -* BFD_RELOC_AVR_6: howto manager. (line 1147) -* BFD_RELOC_AVR_6_ADIW: howto manager. (line 1151) -* BFD_RELOC_AVR_7_PCREL: howto manager. (line 1072) -* BFD_RELOC_AVR_CALL: howto manager. (line 1139) -* BFD_RELOC_AVR_HH8_LDI: howto manager. (line 1092) -* BFD_RELOC_AVR_HH8_LDI_NEG: howto manager. (line 1107) -* BFD_RELOC_AVR_HH8_LDI_PM: howto manager. (line 1120) -* BFD_RELOC_AVR_HH8_LDI_PM_NEG: howto manager. (line 1134) -* BFD_RELOC_AVR_HI8_LDI: howto manager. (line 1088) -* BFD_RELOC_AVR_HI8_LDI_NEG: howto manager. (line 1102) -* BFD_RELOC_AVR_HI8_LDI_PM: howto manager. (line 1116) -* BFD_RELOC_AVR_HI8_LDI_PM_NEG: howto manager. (line 1129) -* BFD_RELOC_AVR_LDI: howto manager. (line 1143) -* BFD_RELOC_AVR_LO8_LDI: howto manager. (line 1084) -* BFD_RELOC_AVR_LO8_LDI_NEG: howto manager. (line 1097) -* BFD_RELOC_AVR_LO8_LDI_PM: howto manager. (line 1112) -* BFD_RELOC_AVR_LO8_LDI_PM_NEG: howto manager. (line 1125) -* bfd_reloc_code_type: howto manager. (line 10) -* BFD_RELOC_CRIS_16_GOT: howto manager. (line 1524) -* BFD_RELOC_CRIS_16_GOTPLT: howto manager. (line 1530) -* BFD_RELOC_CRIS_32_GOT: howto manager. (line 1521) -* BFD_RELOC_CRIS_32_GOTPLT: howto manager. (line 1527) -* BFD_RELOC_CRIS_32_GOTREL: howto manager. (line 1533) -* BFD_RELOC_CRIS_32_PLT_GOTREL: howto manager. (line 1536) -* BFD_RELOC_CRIS_32_PLT_PCREL: howto manager. (line 1539) -* BFD_RELOC_CRIS_BDISP8: howto manager. (line 1502) -* BFD_RELOC_CRIS_COPY: howto manager. (line 1515) -* BFD_RELOC_CRIS_GLOB_DAT: howto manager. (line 1516) -* BFD_RELOC_CRIS_JUMP_SLOT: howto manager. (line 1517) -* BFD_RELOC_CRIS_LAPCQ_OFFSET: howto manager. (line 1510) -* BFD_RELOC_CRIS_RELATIVE: howto manager. (line 1518) -* BFD_RELOC_CRIS_SIGNED_16: howto manager. (line 1508) -* BFD_RELOC_CRIS_SIGNED_6: howto manager. (line 1504) -* BFD_RELOC_CRIS_SIGNED_8: howto manager. (line 1506) -* BFD_RELOC_CRIS_UNSIGNED_16: howto manager. (line 1509) -* BFD_RELOC_CRIS_UNSIGNED_4: howto manager. (line 1511) -* BFD_RELOC_CRIS_UNSIGNED_5: howto manager. (line 1503) -* BFD_RELOC_CRIS_UNSIGNED_6: howto manager. (line 1505) -* BFD_RELOC_CRIS_UNSIGNED_8: howto manager. (line 1507) -* BFD_RELOC_CRX_ABS16: howto manager. (line 1490) -* BFD_RELOC_CRX_ABS32: howto manager. (line 1491) -* BFD_RELOC_CRX_IMM16: howto manager. (line 1495) -* BFD_RELOC_CRX_IMM32: howto manager. (line 1496) -* BFD_RELOC_CRX_NUM16: howto manager. (line 1493) -* BFD_RELOC_CRX_NUM32: howto manager. (line 1494) -* BFD_RELOC_CRX_NUM8: howto manager. (line 1492) -* BFD_RELOC_CRX_REGREL12: howto manager. (line 1486) -* BFD_RELOC_CRX_REGREL22: howto manager. (line 1487) -* BFD_RELOC_CRX_REGREL28: howto manager. (line 1488) -* BFD_RELOC_CRX_REGREL32: howto manager. (line 1489) -* BFD_RELOC_CRX_REL16: howto manager. (line 1483) -* BFD_RELOC_CRX_REL24: howto manager. (line 1484) -* BFD_RELOC_CRX_REL32: howto manager. (line 1485) -* BFD_RELOC_CRX_REL4: howto manager. (line 1480) -* BFD_RELOC_CRX_REL8: howto manager. (line 1481) -* BFD_RELOC_CRX_REL8_CMP: howto manager. (line 1482) -* BFD_RELOC_CRX_SWITCH16: howto manager. (line 1498) -* BFD_RELOC_CRX_SWITCH32: howto manager. (line 1499) -* BFD_RELOC_CRX_SWITCH8: howto manager. (line 1497) -* BFD_RELOC_CTOR: howto manager. (line 586) -* BFD_RELOC_D10V_10_PCREL_L: howto manager. (line 768) -* BFD_RELOC_D10V_10_PCREL_R: howto manager. (line 764) -* BFD_RELOC_D10V_18: howto manager. (line 773) -* BFD_RELOC_D10V_18_PCREL: howto manager. (line 776) -* BFD_RELOC_D30V_15: howto manager. (line 791) -* BFD_RELOC_D30V_15_PCREL: howto manager. (line 795) -* BFD_RELOC_D30V_15_PCREL_R: howto manager. (line 799) -* BFD_RELOC_D30V_21: howto manager. (line 804) -* BFD_RELOC_D30V_21_PCREL: howto manager. (line 808) -* BFD_RELOC_D30V_21_PCREL_R: howto manager. (line 812) -* BFD_RELOC_D30V_32: howto manager. (line 817) -* BFD_RELOC_D30V_32_PCREL: howto manager. (line 820) -* BFD_RELOC_D30V_6: howto manager. (line 779) -* BFD_RELOC_D30V_9_PCREL: howto manager. (line 782) -* BFD_RELOC_D30V_9_PCREL_R: howto manager. (line 786) -* BFD_RELOC_DLX_HI16_S: howto manager. (line 823) -* BFD_RELOC_DLX_JMP26: howto manager. (line 829) -* BFD_RELOC_DLX_LO16: howto manager. (line 826) -* BFD_RELOC_FR30_10_IN_8: howto manager. (line 1002) -* BFD_RELOC_FR30_12_PCREL: howto manager. (line 1010) -* BFD_RELOC_FR30_20: howto manager. (line 986) -* BFD_RELOC_FR30_48: howto manager. (line 983) -* BFD_RELOC_FR30_6_IN_4: howto manager. (line 990) -* BFD_RELOC_FR30_8_IN_8: howto manager. (line 994) -* BFD_RELOC_FR30_9_IN_8: howto manager. (line 998) -* BFD_RELOC_FR30_9_PCREL: howto manager. (line 1006) -* BFD_RELOC_FRV_FUNCDESC: howto manager. (line 364) -* BFD_RELOC_FRV_FUNCDESC_GOT12: howto manager. (line 365) -* BFD_RELOC_FRV_FUNCDESC_GOTHI: howto manager. (line 366) -* BFD_RELOC_FRV_FUNCDESC_GOTLO: howto manager. (line 367) -* BFD_RELOC_FRV_FUNCDESC_GOTOFF12: howto manager. (line 369) -* BFD_RELOC_FRV_FUNCDESC_GOTOFFHI: howto manager. (line 370) -* BFD_RELOC_FRV_FUNCDESC_GOTOFFLO: howto manager. (line 371) -* BFD_RELOC_FRV_FUNCDESC_VALUE: howto manager. (line 368) -* BFD_RELOC_FRV_GETTLSOFF: howto manager. (line 375) -* BFD_RELOC_FRV_GETTLSOFF_RELAX: howto manager. (line 388) -* BFD_RELOC_FRV_GOT12: howto manager. (line 361) -* BFD_RELOC_FRV_GOTHI: howto manager. (line 362) -* BFD_RELOC_FRV_GOTLO: howto manager. (line 363) -* BFD_RELOC_FRV_GOTOFF12: howto manager. (line 372) -* BFD_RELOC_FRV_GOTOFFHI: howto manager. (line 373) -* BFD_RELOC_FRV_GOTOFFLO: howto manager. (line 374) -* BFD_RELOC_FRV_GOTTLSDESC12: howto manager. (line 377) -* BFD_RELOC_FRV_GOTTLSDESCHI: howto manager. (line 378) -* BFD_RELOC_FRV_GOTTLSDESCLO: howto manager. (line 379) -* BFD_RELOC_FRV_GOTTLSOFF12: howto manager. (line 383) -* BFD_RELOC_FRV_GOTTLSOFFHI: howto manager. (line 384) -* BFD_RELOC_FRV_GOTTLSOFFLO: howto manager. (line 385) -* BFD_RELOC_FRV_GPREL12: howto manager. (line 356) -* BFD_RELOC_FRV_GPREL32: howto manager. (line 358) -* BFD_RELOC_FRV_GPRELHI: howto manager. (line 359) -* BFD_RELOC_FRV_GPRELLO: howto manager. (line 360) -* BFD_RELOC_FRV_GPRELU12: howto manager. (line 357) -* BFD_RELOC_FRV_HI16: howto manager. (line 355) -* BFD_RELOC_FRV_LABEL16: howto manager. (line 352) -* BFD_RELOC_FRV_LABEL24: howto manager. (line 353) -* BFD_RELOC_FRV_LO16: howto manager. (line 354) -* BFD_RELOC_FRV_TLSDESC_RELAX: howto manager. (line 387) -* BFD_RELOC_FRV_TLSDESC_VALUE: howto manager. (line 376) -* BFD_RELOC_FRV_TLSMOFF: howto manager. (line 390) -* BFD_RELOC_FRV_TLSMOFF12: howto manager. (line 380) -* BFD_RELOC_FRV_TLSMOFFHI: howto manager. (line 381) -* BFD_RELOC_FRV_TLSMOFFLO: howto manager. (line 382) -* BFD_RELOC_FRV_TLSOFF: howto manager. (line 386) -* BFD_RELOC_FRV_TLSOFF_RELAX: howto manager. (line 389) -* BFD_RELOC_GPREL16: howto manager. (line 106) -* BFD_RELOC_GPREL32: howto manager. (line 107) -* BFD_RELOC_H8_DIR16A8: howto manager. (line 1581) -* BFD_RELOC_H8_DIR16R8: howto manager. (line 1582) -* BFD_RELOC_H8_DIR24A8: howto manager. (line 1583) -* BFD_RELOC_H8_DIR24R8: howto manager. (line 1584) -* BFD_RELOC_H8_DIR32A16: howto manager. (line 1585) -* BFD_RELOC_HI16: howto manager. (line 289) -* BFD_RELOC_HI16_BASEREL: howto manager. (line 82) -* BFD_RELOC_HI16_GOTOFF: howto manager. (line 57) -* BFD_RELOC_HI16_PLTOFF: howto manager. (line 69) -* BFD_RELOC_HI16_S: howto manager. (line 292) -* BFD_RELOC_HI16_S_BASEREL: howto manager. (line 83) -* BFD_RELOC_HI16_S_GOTOFF: howto manager. (line 58) -* BFD_RELOC_HI16_S_PLTOFF: howto manager. (line 70) -* BFD_RELOC_HI22: howto manager. (line 101) -* BFD_RELOC_I370_D12: howto manager. (line 583) -* BFD_RELOC_I960_CALLJ: howto manager. (line 113) -* BFD_RELOC_IA64_COPY: howto manager. (line 1374) -* BFD_RELOC_IA64_DIR32LSB: howto manager. (line 1319) -* BFD_RELOC_IA64_DIR32MSB: howto manager. (line 1318) -* BFD_RELOC_IA64_DIR64LSB: howto manager. (line 1321) -* BFD_RELOC_IA64_DIR64MSB: howto manager. (line 1320) -* BFD_RELOC_IA64_DTPMOD64LSB: howto manager. (line 1384) -* BFD_RELOC_IA64_DTPMOD64MSB: howto manager. (line 1383) -* BFD_RELOC_IA64_DTPREL14: howto manager. (line 1386) -* BFD_RELOC_IA64_DTPREL22: howto manager. (line 1387) -* BFD_RELOC_IA64_DTPREL32LSB: howto manager. (line 1390) -* BFD_RELOC_IA64_DTPREL32MSB: howto manager. (line 1389) -* BFD_RELOC_IA64_DTPREL64I: howto manager. (line 1388) -* BFD_RELOC_IA64_DTPREL64LSB: howto manager. (line 1392) -* BFD_RELOC_IA64_DTPREL64MSB: howto manager. (line 1391) -* BFD_RELOC_IA64_FPTR32LSB: howto manager. (line 1336) -* BFD_RELOC_IA64_FPTR32MSB: howto manager. (line 1335) -* BFD_RELOC_IA64_FPTR64I: howto manager. (line 1334) -* BFD_RELOC_IA64_FPTR64LSB: howto manager. (line 1338) -* BFD_RELOC_IA64_FPTR64MSB: howto manager. (line 1337) -* BFD_RELOC_IA64_GPREL22: howto manager. (line 1322) -* BFD_RELOC_IA64_GPREL32LSB: howto manager. (line 1325) -* BFD_RELOC_IA64_GPREL32MSB: howto manager. (line 1324) -* BFD_RELOC_IA64_GPREL64I: howto manager. (line 1323) -* BFD_RELOC_IA64_GPREL64LSB: howto manager. (line 1327) -* BFD_RELOC_IA64_GPREL64MSB: howto manager. (line 1326) -* BFD_RELOC_IA64_IMM14: howto manager. (line 1315) -* BFD_RELOC_IA64_IMM22: howto manager. (line 1316) -* BFD_RELOC_IA64_IMM64: howto manager. (line 1317) -* BFD_RELOC_IA64_IPLTLSB: howto manager. (line 1373) -* BFD_RELOC_IA64_IPLTMSB: howto manager. (line 1372) -* BFD_RELOC_IA64_LDXMOV: howto manager. (line 1376) -* BFD_RELOC_IA64_LTOFF22: howto manager. (line 1328) -* BFD_RELOC_IA64_LTOFF22X: howto manager. (line 1375) -* BFD_RELOC_IA64_LTOFF64I: howto manager. (line 1329) -* BFD_RELOC_IA64_LTOFF_DTPMOD22: howto manager. (line 1385) -* BFD_RELOC_IA64_LTOFF_DTPREL22: howto manager. (line 1393) -* BFD_RELOC_IA64_LTOFF_FPTR22: howto manager. (line 1350) -* BFD_RELOC_IA64_LTOFF_FPTR32LSB: howto manager. (line 1353) -* BFD_RELOC_IA64_LTOFF_FPTR32MSB: howto manager. (line 1352) -* BFD_RELOC_IA64_LTOFF_FPTR64I: howto manager. (line 1351) -* BFD_RELOC_IA64_LTOFF_FPTR64LSB: howto manager. (line 1355) -* BFD_RELOC_IA64_LTOFF_FPTR64MSB: howto manager. (line 1354) -* BFD_RELOC_IA64_LTOFF_TPREL22: howto manager. (line 1382) -* BFD_RELOC_IA64_LTV32LSB: howto manager. (line 1369) -* BFD_RELOC_IA64_LTV32MSB: howto manager. (line 1368) -* BFD_RELOC_IA64_LTV64LSB: howto manager. (line 1371) -* BFD_RELOC_IA64_LTV64MSB: howto manager. (line 1370) -* BFD_RELOC_IA64_PCREL21B: howto manager. (line 1339) -* BFD_RELOC_IA64_PCREL21BI: howto manager. (line 1340) -* BFD_RELOC_IA64_PCREL21F: howto manager. (line 1342) -* BFD_RELOC_IA64_PCREL21M: howto manager. (line 1341) -* BFD_RELOC_IA64_PCREL22: howto manager. (line 1343) -* BFD_RELOC_IA64_PCREL32LSB: howto manager. (line 1347) -* BFD_RELOC_IA64_PCREL32MSB: howto manager. (line 1346) -* BFD_RELOC_IA64_PCREL60B: howto manager. (line 1344) -* BFD_RELOC_IA64_PCREL64I: howto manager. (line 1345) -* BFD_RELOC_IA64_PCREL64LSB: howto manager. (line 1349) -* BFD_RELOC_IA64_PCREL64MSB: howto manager. (line 1348) -* BFD_RELOC_IA64_PLTOFF22: howto manager. (line 1330) -* BFD_RELOC_IA64_PLTOFF64I: howto manager. (line 1331) -* BFD_RELOC_IA64_PLTOFF64LSB: howto manager. (line 1333) -* BFD_RELOC_IA64_PLTOFF64MSB: howto manager. (line 1332) -* BFD_RELOC_IA64_REL32LSB: howto manager. (line 1365) -* BFD_RELOC_IA64_REL32MSB: howto manager. (line 1364) -* BFD_RELOC_IA64_REL64LSB: howto manager. (line 1367) -* BFD_RELOC_IA64_REL64MSB: howto manager. (line 1366) -* BFD_RELOC_IA64_SECREL32LSB: howto manager. (line 1361) -* BFD_RELOC_IA64_SECREL32MSB: howto manager. (line 1360) -* BFD_RELOC_IA64_SECREL64LSB: howto manager. (line 1363) -* BFD_RELOC_IA64_SECREL64MSB: howto manager. (line 1362) -* BFD_RELOC_IA64_SEGREL32LSB: howto manager. (line 1357) -* BFD_RELOC_IA64_SEGREL32MSB: howto manager. (line 1356) -* BFD_RELOC_IA64_SEGREL64LSB: howto manager. (line 1359) -* BFD_RELOC_IA64_SEGREL64MSB: howto manager. (line 1358) -* BFD_RELOC_IA64_TPREL14: howto manager. (line 1377) -* BFD_RELOC_IA64_TPREL22: howto manager. (line 1378) -* BFD_RELOC_IA64_TPREL64I: howto manager. (line 1379) -* BFD_RELOC_IA64_TPREL64LSB: howto manager. (line 1381) -* BFD_RELOC_IA64_TPREL64MSB: howto manager. (line 1380) -* BFD_RELOC_IP2K_ADDR16CJP: howto manager. (line 1267) -* BFD_RELOC_IP2K_BANK: howto manager. (line 1264) -* BFD_RELOC_IP2K_EX8DATA: howto manager. (line 1275) -* BFD_RELOC_IP2K_FR9: howto manager. (line 1261) -* BFD_RELOC_IP2K_FR_OFFSET: howto manager. (line 1288) -* BFD_RELOC_IP2K_HI8DATA: howto manager. (line 1274) -* BFD_RELOC_IP2K_HI8INSN: howto manager. (line 1279) -* BFD_RELOC_IP2K_LO8DATA: howto manager. (line 1273) -* BFD_RELOC_IP2K_LO8INSN: howto manager. (line 1278) -* BFD_RELOC_IP2K_PAGE3: howto manager. (line 1270) -* BFD_RELOC_IP2K_PC_SKIP: howto manager. (line 1282) -* BFD_RELOC_IP2K_TEXT: howto manager. (line 1285) -* BFD_RELOC_IQ2000_OFFSET_16: howto manager. (line 1608) -* BFD_RELOC_IQ2000_OFFSET_21: howto manager. (line 1609) -* BFD_RELOC_IQ2000_UHI16: howto manager. (line 1610) -* BFD_RELOC_LO10: howto manager. (line 102) -* BFD_RELOC_LO16: howto manager. (line 298) -* BFD_RELOC_LO16_BASEREL: howto manager. (line 81) -* BFD_RELOC_LO16_GOTOFF: howto manager. (line 56) -* BFD_RELOC_LO16_PLTOFF: howto manager. (line 68) -* BFD_RELOC_M32R_10_PCREL: howto manager. (line 836) -* BFD_RELOC_M32R_18_PCREL: howto manager. (line 840) -* BFD_RELOC_M32R_24: howto manager. (line 832) -* BFD_RELOC_M32R_26_PCREL: howto manager. (line 843) -* BFD_RELOC_M32R_26_PLTREL: howto manager. (line 862) -* BFD_RELOC_M32R_COPY: howto manager. (line 863) -* BFD_RELOC_M32R_GLOB_DAT: howto manager. (line 864) -* BFD_RELOC_M32R_GOT16_HI_SLO: howto manager. (line 873) -* BFD_RELOC_M32R_GOT16_HI_ULO: howto manager. (line 872) -* BFD_RELOC_M32R_GOT16_LO: howto manager. (line 874) -* BFD_RELOC_M32R_GOT24: howto manager. (line 861) -* BFD_RELOC_M32R_GOTOFF: howto manager. (line 867) -* BFD_RELOC_M32R_GOTOFF_HI_SLO: howto manager. (line 869) -* BFD_RELOC_M32R_GOTOFF_HI_ULO: howto manager. (line 868) -* BFD_RELOC_M32R_GOTOFF_LO: howto manager. (line 870) -* BFD_RELOC_M32R_GOTPC24: howto manager. (line 871) -* BFD_RELOC_M32R_GOTPC_HI_SLO: howto manager. (line 876) -* BFD_RELOC_M32R_GOTPC_HI_ULO: howto manager. (line 875) -* BFD_RELOC_M32R_GOTPC_LO: howto manager. (line 877) -* BFD_RELOC_M32R_HI16_SLO: howto manager. (line 850) -* BFD_RELOC_M32R_HI16_ULO: howto manager. (line 846) -* BFD_RELOC_M32R_JMP_SLOT: howto manager. (line 865) -* BFD_RELOC_M32R_LO16: howto manager. (line 854) -* BFD_RELOC_M32R_RELATIVE: howto manager. (line 866) -* BFD_RELOC_M32R_SDA16: howto manager. (line 857) -* BFD_RELOC_M68HC11_24: howto manager. (line 1429) -* BFD_RELOC_M68HC11_3B: howto manager. (line 1404) -* BFD_RELOC_M68HC11_HI8: howto manager. (line 1396) -* BFD_RELOC_M68HC11_LO16: howto manager. (line 1418) -* BFD_RELOC_M68HC11_LO8: howto manager. (line 1400) -* BFD_RELOC_M68HC11_PAGE: howto manager. (line 1424) -* BFD_RELOC_M68HC11_RL_GROUP: howto manager. (line 1413) -* BFD_RELOC_M68HC11_RL_JUMP: howto manager. (line 1407) -* BFD_RELOC_M68HC12_5B: howto manager. (line 1435) -* BFD_RELOC_MCORE_PCREL_32: howto manager. (line 1017) -* BFD_RELOC_MCORE_PCREL_IMM11BY2: howto manager. (line 1015) -* BFD_RELOC_MCORE_PCREL_IMM4BY2: howto manager. (line 1016) -* BFD_RELOC_MCORE_PCREL_IMM8BY4: howto manager. (line 1014) -* BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2: howto manager. (line 1018) -* BFD_RELOC_MCORE_RVA: howto manager. (line 1019) -* BFD_RELOC_MIPS16_GPREL: howto manager. (line 286) -* BFD_RELOC_MIPS16_HI16: howto manager. (line 301) -* BFD_RELOC_MIPS16_HI16_S: howto manager. (line 304) -* BFD_RELOC_MIPS16_JMP: howto manager. (line 283) -* BFD_RELOC_MIPS16_LO16: howto manager. (line 310) -* BFD_RELOC_MIPS_CALL16: howto manager. (line 317) -* BFD_RELOC_MIPS_CALL_HI16: howto manager. (line 320) -* BFD_RELOC_MIPS_CALL_LO16: howto manager. (line 321) -* BFD_RELOC_MIPS_DELETE: howto manager. (line 330) -* BFD_RELOC_MIPS_GOT16: howto manager. (line 316) -* BFD_RELOC_MIPS_GOT_DISP: howto manager. (line 325) -* BFD_RELOC_MIPS_GOT_HI16: howto manager. (line 318) -* BFD_RELOC_MIPS_GOT_LO16: howto manager. (line 319) -* BFD_RELOC_MIPS_GOT_OFST: howto manager. (line 324) -* BFD_RELOC_MIPS_GOT_PAGE: howto manager. (line 323) -* BFD_RELOC_MIPS_HIGHER: howto manager. (line 332) -* BFD_RELOC_MIPS_HIGHEST: howto manager. (line 331) -* BFD_RELOC_MIPS_INSERT_A: howto manager. (line 328) -* BFD_RELOC_MIPS_INSERT_B: howto manager. (line 329) -* BFD_RELOC_MIPS_JALR: howto manager. (line 336) -* BFD_RELOC_MIPS_JMP: howto manager. (line 279) -* BFD_RELOC_MIPS_LITERAL: howto manager. (line 313) -* BFD_RELOC_MIPS_REL16: howto manager. (line 334) -* BFD_RELOC_MIPS_RELGOT: howto manager. (line 335) -* BFD_RELOC_MIPS_SCN_DISP: howto manager. (line 333) -* BFD_RELOC_MIPS_SHIFT5: howto manager. (line 326) -* BFD_RELOC_MIPS_SHIFT6: howto manager. (line 327) -* BFD_RELOC_MIPS_SUB: howto manager. (line 322) -* BFD_RELOC_MIPS_TLS_DTPMOD32: howto manager. (line 337) -* BFD_RELOC_MIPS_TLS_DTPMOD64: howto manager. (line 339) -* BFD_RELOC_MIPS_TLS_DTPREL32: howto manager. (line 338) -* BFD_RELOC_MIPS_TLS_DTPREL64: howto manager. (line 340) -* BFD_RELOC_MIPS_TLS_DTPREL_HI16: howto manager. (line 343) -* BFD_RELOC_MIPS_TLS_DTPREL_LO16: howto manager. (line 344) -* BFD_RELOC_MIPS_TLS_GD: howto manager. (line 341) -* BFD_RELOC_MIPS_TLS_GOTTPREL: howto manager. (line 345) -* BFD_RELOC_MIPS_TLS_LDM: howto manager. (line 342) -* BFD_RELOC_MIPS_TLS_TPREL32: howto manager. (line 346) -* BFD_RELOC_MIPS_TLS_TPREL64: howto manager. (line 347) -* BFD_RELOC_MIPS_TLS_TPREL_HI16: howto manager. (line 348) -* BFD_RELOC_MIPS_TLS_TPREL_LO16: howto manager. (line 349) -* BFD_RELOC_MMIX_ADDR19: howto manager. (line 1048) -* BFD_RELOC_MMIX_ADDR27: howto manager. (line 1052) -* BFD_RELOC_MMIX_BASE_PLUS_OFFSET: howto manager. (line 1064) -* BFD_RELOC_MMIX_CBRANCH: howto manager. (line 1028) -* BFD_RELOC_MMIX_CBRANCH_1: howto manager. (line 1030) -* BFD_RELOC_MMIX_CBRANCH_2: howto manager. (line 1031) -* BFD_RELOC_MMIX_CBRANCH_3: howto manager. (line 1032) -* BFD_RELOC_MMIX_CBRANCH_J: howto manager. (line 1029) -* BFD_RELOC_MMIX_GETA: howto manager. (line 1022) -* BFD_RELOC_MMIX_GETA_1: howto manager. (line 1023) -* BFD_RELOC_MMIX_GETA_2: howto manager. (line 1024) -* BFD_RELOC_MMIX_GETA_3: howto manager. (line 1025) -* BFD_RELOC_MMIX_JMP: howto manager. (line 1042) -* BFD_RELOC_MMIX_JMP_1: howto manager. (line 1043) -* BFD_RELOC_MMIX_JMP_2: howto manager. (line 1044) -* BFD_RELOC_MMIX_JMP_3: howto manager. (line 1045) -* BFD_RELOC_MMIX_LOCAL: howto manager. (line 1068) -* BFD_RELOC_MMIX_PUSHJ: howto manager. (line 1035) -* BFD_RELOC_MMIX_PUSHJ_1: howto manager. (line 1036) -* BFD_RELOC_MMIX_PUSHJ_2: howto manager. (line 1037) -* BFD_RELOC_MMIX_PUSHJ_3: howto manager. (line 1038) -* BFD_RELOC_MMIX_PUSHJ_STUBBABLE: howto manager. (line 1039) -* BFD_RELOC_MMIX_REG: howto manager. (line 1060) -* BFD_RELOC_MMIX_REG_OR_BYTE: howto manager. (line 1056) -* BFD_RELOC_MN10300_16_PCREL: howto manager. (line 952) -* BFD_RELOC_MN10300_32_PCREL: howto manager. (line 948) -* BFD_RELOC_MN10300_COPY: howto manager. (line 408) -* BFD_RELOC_MN10300_GLOB_DAT: howto manager. (line 411) -* BFD_RELOC_MN10300_GOT16: howto manager. (line 404) -* BFD_RELOC_MN10300_GOT24: howto manager. (line 400) -* BFD_RELOC_MN10300_GOT32: howto manager. (line 396) -* BFD_RELOC_MN10300_GOTOFF24: howto manager. (line 393) -* BFD_RELOC_MN10300_JMP_SLOT: howto manager. (line 414) -* BFD_RELOC_MN10300_RELATIVE: howto manager. (line 417) -* BFD_RELOC_MSP430_10_PCREL: howto manager. (line 1599) -* BFD_RELOC_MSP430_16: howto manager. (line 1601) -* BFD_RELOC_MSP430_16_BYTE: howto manager. (line 1603) -* BFD_RELOC_MSP430_16_PCREL: howto manager. (line 1600) -* BFD_RELOC_MSP430_16_PCREL_BYTE: howto manager. (line 1602) -* BFD_RELOC_MSP430_2X_PCREL: howto manager. (line 1604) -* BFD_RELOC_MSP430_RL_PCREL: howto manager. (line 1605) -* BFD_RELOC_NONE: howto manager. (line 116) -* BFD_RELOC_NS32K_DISP_16: howto manager. (line 467) -* BFD_RELOC_NS32K_DISP_16_PCREL: howto manager. (line 470) -* BFD_RELOC_NS32K_DISP_32: howto manager. (line 468) -* BFD_RELOC_NS32K_DISP_32_PCREL: howto manager. (line 471) -* BFD_RELOC_NS32K_DISP_8: howto manager. (line 466) -* BFD_RELOC_NS32K_DISP_8_PCREL: howto manager. (line 469) -* BFD_RELOC_NS32K_IMM_16: howto manager. (line 461) -* BFD_RELOC_NS32K_IMM_16_PCREL: howto manager. (line 464) -* BFD_RELOC_NS32K_IMM_32: howto manager. (line 462) -* BFD_RELOC_NS32K_IMM_32_PCREL: howto manager. (line 465) -* BFD_RELOC_NS32K_IMM_8: howto manager. (line 460) -* BFD_RELOC_NS32K_IMM_8_PCREL: howto manager. (line 463) -* BFD_RELOC_OPENRISC_ABS_26: howto manager. (line 1577) -* BFD_RELOC_OPENRISC_REL_26: howto manager. (line 1578) -* BFD_RELOC_PDP11_DISP_6_PCREL: howto manager. (line 475) -* BFD_RELOC_PDP11_DISP_8_PCREL: howto manager. (line 474) -* BFD_RELOC_PJ_CODE_DIR16: howto manager. (line 480) -* BFD_RELOC_PJ_CODE_DIR32: howto manager. (line 481) -* BFD_RELOC_PJ_CODE_HI16: howto manager. (line 478) -* BFD_RELOC_PJ_CODE_LO16: howto manager. (line 479) -* BFD_RELOC_PJ_CODE_REL16: howto manager. (line 482) -* BFD_RELOC_PJ_CODE_REL32: howto manager. (line 483) -* BFD_RELOC_PPC64_ADDR16_DS: howto manager. (line 528) -* BFD_RELOC_PPC64_ADDR16_LO_DS: howto manager. (line 529) -* BFD_RELOC_PPC64_DTPREL16_DS: howto manager. (line 575) -* BFD_RELOC_PPC64_DTPREL16_HIGHER: howto manager. (line 577) -* BFD_RELOC_PPC64_DTPREL16_HIGHERA: howto manager. (line 578) -* BFD_RELOC_PPC64_DTPREL16_HIGHEST: howto manager. (line 579) -* BFD_RELOC_PPC64_DTPREL16_HIGHESTA: howto manager. (line 580) -* BFD_RELOC_PPC64_DTPREL16_LO_DS: howto manager. (line 576) -* BFD_RELOC_PPC64_GOT16_DS: howto manager. (line 530) -* BFD_RELOC_PPC64_GOT16_LO_DS: howto manager. (line 531) -* BFD_RELOC_PPC64_HIGHER: howto manager. (line 516) -* BFD_RELOC_PPC64_HIGHER_S: howto manager. (line 517) -* BFD_RELOC_PPC64_HIGHEST: howto manager. (line 518) -* BFD_RELOC_PPC64_HIGHEST_S: howto manager. (line 519) -* BFD_RELOC_PPC64_PLT16_LO_DS: howto manager. (line 532) -* BFD_RELOC_PPC64_PLTGOT16: howto manager. (line 524) -* BFD_RELOC_PPC64_PLTGOT16_DS: howto manager. (line 537) -* BFD_RELOC_PPC64_PLTGOT16_HA: howto manager. (line 527) -* BFD_RELOC_PPC64_PLTGOT16_HI: howto manager. (line 526) -* BFD_RELOC_PPC64_PLTGOT16_LO: howto manager. (line 525) -* BFD_RELOC_PPC64_PLTGOT16_LO_DS: howto manager. (line 538) -* BFD_RELOC_PPC64_SECTOFF_DS: howto manager. (line 533) -* BFD_RELOC_PPC64_SECTOFF_LO_DS: howto manager. (line 534) -* BFD_RELOC_PPC64_TOC: howto manager. (line 523) -* BFD_RELOC_PPC64_TOC16_DS: howto manager. (line 535) -* BFD_RELOC_PPC64_TOC16_HA: howto manager. (line 522) -* BFD_RELOC_PPC64_TOC16_HI: howto manager. (line 521) -* BFD_RELOC_PPC64_TOC16_LO: howto manager. (line 520) -* BFD_RELOC_PPC64_TOC16_LO_DS: howto manager. (line 536) -* BFD_RELOC_PPC64_TPREL16_DS: howto manager. (line 569) -* BFD_RELOC_PPC64_TPREL16_HIGHER: howto manager. (line 571) -* BFD_RELOC_PPC64_TPREL16_HIGHERA: howto manager. (line 572) -* BFD_RELOC_PPC64_TPREL16_HIGHEST: howto manager. (line 573) -* BFD_RELOC_PPC64_TPREL16_HIGHESTA: howto manager. (line 574) -* BFD_RELOC_PPC64_TPREL16_LO_DS: howto manager. (line 570) -* BFD_RELOC_PPC_B16: howto manager. (line 489) -* BFD_RELOC_PPC_B16_BRNTAKEN: howto manager. (line 491) -* BFD_RELOC_PPC_B16_BRTAKEN: howto manager. (line 490) -* BFD_RELOC_PPC_B26: howto manager. (line 486) -* BFD_RELOC_PPC_BA16: howto manager. (line 492) -* BFD_RELOC_PPC_BA16_BRNTAKEN: howto manager. (line 494) -* BFD_RELOC_PPC_BA16_BRTAKEN: howto manager. (line 493) -* BFD_RELOC_PPC_BA26: howto manager. (line 487) -* BFD_RELOC_PPC_COPY: howto manager. (line 495) -* BFD_RELOC_PPC_DTPMOD: howto manager. (line 542) -* BFD_RELOC_PPC_DTPREL: howto manager. (line 552) -* BFD_RELOC_PPC_DTPREL16: howto manager. (line 548) -* BFD_RELOC_PPC_DTPREL16_HA: howto manager. (line 551) -* BFD_RELOC_PPC_DTPREL16_HI: howto manager. (line 550) -* BFD_RELOC_PPC_DTPREL16_LO: howto manager. (line 549) -* BFD_RELOC_PPC_EMB_BIT_FLD: howto manager. (line 514) -* BFD_RELOC_PPC_EMB_MRKREF: howto manager. (line 509) -* BFD_RELOC_PPC_EMB_NADDR16: howto manager. (line 501) -* BFD_RELOC_PPC_EMB_NADDR16_HA: howto manager. (line 504) -* BFD_RELOC_PPC_EMB_NADDR16_HI: howto manager. (line 503) -* BFD_RELOC_PPC_EMB_NADDR16_LO: howto manager. (line 502) -* BFD_RELOC_PPC_EMB_NADDR32: howto manager. (line 500) -* BFD_RELOC_PPC_EMB_RELSDA: howto manager. (line 515) -* BFD_RELOC_PPC_EMB_RELSEC16: howto manager. (line 510) -* BFD_RELOC_PPC_EMB_RELST_HA: howto manager. (line 513) -* BFD_RELOC_PPC_EMB_RELST_HI: howto manager. (line 512) -* BFD_RELOC_PPC_EMB_RELST_LO: howto manager. (line 511) -* BFD_RELOC_PPC_EMB_SDA21: howto manager. (line 508) -* BFD_RELOC_PPC_EMB_SDA2I16: howto manager. (line 506) -* BFD_RELOC_PPC_EMB_SDA2REL: howto manager. (line 507) -* BFD_RELOC_PPC_EMB_SDAI16: howto manager. (line 505) -* BFD_RELOC_PPC_GLOB_DAT: howto manager. (line 496) -* BFD_RELOC_PPC_GOT_DTPREL16: howto manager. (line 565) -* BFD_RELOC_PPC_GOT_DTPREL16_HA: howto manager. (line 568) -* BFD_RELOC_PPC_GOT_DTPREL16_HI: howto manager. (line 567) -* BFD_RELOC_PPC_GOT_DTPREL16_LO: howto manager. (line 566) -* BFD_RELOC_PPC_GOT_TLSGD16: howto manager. (line 553) -* BFD_RELOC_PPC_GOT_TLSGD16_HA: howto manager. (line 556) -* BFD_RELOC_PPC_GOT_TLSGD16_HI: howto manager. (line 555) -* BFD_RELOC_PPC_GOT_TLSGD16_LO: howto manager. (line 554) -* BFD_RELOC_PPC_GOT_TLSLD16: howto manager. (line 557) -* BFD_RELOC_PPC_GOT_TLSLD16_HA: howto manager. (line 560) -* BFD_RELOC_PPC_GOT_TLSLD16_HI: howto manager. (line 559) -* BFD_RELOC_PPC_GOT_TLSLD16_LO: howto manager. (line 558) -* BFD_RELOC_PPC_GOT_TPREL16: howto manager. (line 561) -* BFD_RELOC_PPC_GOT_TPREL16_HA: howto manager. (line 564) -* BFD_RELOC_PPC_GOT_TPREL16_HI: howto manager. (line 563) -* BFD_RELOC_PPC_GOT_TPREL16_LO: howto manager. (line 562) -* BFD_RELOC_PPC_JMP_SLOT: howto manager. (line 497) -* BFD_RELOC_PPC_LOCAL24PC: howto manager. (line 499) -* BFD_RELOC_PPC_RELATIVE: howto manager. (line 498) -* BFD_RELOC_PPC_TLS: howto manager. (line 541) -* BFD_RELOC_PPC_TOC16: howto manager. (line 488) -* BFD_RELOC_PPC_TPREL: howto manager. (line 547) -* BFD_RELOC_PPC_TPREL16: howto manager. (line 543) -* BFD_RELOC_PPC_TPREL16_HA: howto manager. (line 546) -* BFD_RELOC_PPC_TPREL16_HI: howto manager. (line 545) -* BFD_RELOC_PPC_TPREL16_LO: howto manager. (line 544) -* BFD_RELOC_RVA: howto manager. (line 85) -* BFD_RELOC_SH_ALIGN: howto manager. (line 677) -* BFD_RELOC_SH_CODE: howto manager. (line 678) -* BFD_RELOC_SH_COPY: howto manager. (line 683) -* BFD_RELOC_SH_COPY64: howto manager. (line 708) -* BFD_RELOC_SH_COUNT: howto manager. (line 676) -* BFD_RELOC_SH_DATA: howto manager. (line 679) -* BFD_RELOC_SH_DISP12: howto manager. (line 659) -* BFD_RELOC_SH_DISP12BY2: howto manager. (line 660) -* BFD_RELOC_SH_DISP12BY4: howto manager. (line 661) -* BFD_RELOC_SH_DISP12BY8: howto manager. (line 662) -* BFD_RELOC_SH_DISP20: howto manager. (line 663) -* BFD_RELOC_SH_DISP20BY8: howto manager. (line 664) -* BFD_RELOC_SH_GLOB_DAT: howto manager. (line 684) -* BFD_RELOC_SH_GLOB_DAT64: howto manager. (line 709) -* BFD_RELOC_SH_GOT10BY4: howto manager. (line 712) -* BFD_RELOC_SH_GOT10BY8: howto manager. (line 713) -* BFD_RELOC_SH_GOT_HI16: howto manager. (line 691) -* BFD_RELOC_SH_GOT_LOW16: howto manager. (line 688) -* BFD_RELOC_SH_GOT_MEDHI16: howto manager. (line 690) -* BFD_RELOC_SH_GOT_MEDLOW16: howto manager. (line 689) -* BFD_RELOC_SH_GOTOFF_HI16: howto manager. (line 703) -* BFD_RELOC_SH_GOTOFF_LOW16: howto manager. (line 700) -* BFD_RELOC_SH_GOTOFF_MEDHI16: howto manager. (line 702) -* BFD_RELOC_SH_GOTOFF_MEDLOW16: howto manager. (line 701) -* BFD_RELOC_SH_GOTPC: howto manager. (line 687) -* BFD_RELOC_SH_GOTPC_HI16: howto manager. (line 707) -* BFD_RELOC_SH_GOTPC_LOW16: howto manager. (line 704) -* BFD_RELOC_SH_GOTPC_MEDHI16: howto manager. (line 706) -* BFD_RELOC_SH_GOTPC_MEDLOW16: howto manager. (line 705) -* BFD_RELOC_SH_GOTPLT10BY4: howto manager. (line 714) -* BFD_RELOC_SH_GOTPLT10BY8: howto manager. (line 715) -* BFD_RELOC_SH_GOTPLT32: howto manager. (line 716) -* BFD_RELOC_SH_GOTPLT_HI16: howto manager. (line 695) -* BFD_RELOC_SH_GOTPLT_LOW16: howto manager. (line 692) -* BFD_RELOC_SH_GOTPLT_MEDHI16: howto manager. (line 694) -* BFD_RELOC_SH_GOTPLT_MEDLOW16: howto manager. (line 693) -* BFD_RELOC_SH_IMM3: howto manager. (line 657) -* BFD_RELOC_SH_IMM3U: howto manager. (line 658) -* BFD_RELOC_SH_IMM4: howto manager. (line 665) -* BFD_RELOC_SH_IMM4BY2: howto manager. (line 666) -* BFD_RELOC_SH_IMM4BY4: howto manager. (line 667) -* BFD_RELOC_SH_IMM8: howto manager. (line 668) -* BFD_RELOC_SH_IMM8BY2: howto manager. (line 669) -* BFD_RELOC_SH_IMM8BY4: howto manager. (line 670) -* BFD_RELOC_SH_IMM_HI16: howto manager. (line 734) -* BFD_RELOC_SH_IMM_HI16_PCREL: howto manager. (line 735) -* BFD_RELOC_SH_IMM_LOW16: howto manager. (line 728) -* BFD_RELOC_SH_IMM_LOW16_PCREL: howto manager. (line 729) -* BFD_RELOC_SH_IMM_MEDHI16: howto manager. (line 732) -* BFD_RELOC_SH_IMM_MEDHI16_PCREL: howto manager. (line 733) -* BFD_RELOC_SH_IMM_MEDLOW16: howto manager. (line 730) -* BFD_RELOC_SH_IMM_MEDLOW16_PCREL: howto manager. (line 731) -* BFD_RELOC_SH_IMMS10: howto manager. (line 722) -* BFD_RELOC_SH_IMMS10BY2: howto manager. (line 723) -* BFD_RELOC_SH_IMMS10BY4: howto manager. (line 724) -* BFD_RELOC_SH_IMMS10BY8: howto manager. (line 725) -* BFD_RELOC_SH_IMMS16: howto manager. (line 726) -* BFD_RELOC_SH_IMMS6: howto manager. (line 719) -* BFD_RELOC_SH_IMMS6BY32: howto manager. (line 720) -* BFD_RELOC_SH_IMMU16: howto manager. (line 727) -* BFD_RELOC_SH_IMMU5: howto manager. (line 718) -* BFD_RELOC_SH_IMMU6: howto manager. (line 721) -* BFD_RELOC_SH_JMP_SLOT: howto manager. (line 685) -* BFD_RELOC_SH_JMP_SLOT64: howto manager. (line 710) -* BFD_RELOC_SH_LABEL: howto manager. (line 680) -* BFD_RELOC_SH_LOOP_END: howto manager. (line 682) -* BFD_RELOC_SH_LOOP_START: howto manager. (line 681) -* BFD_RELOC_SH_PCDISP12BY2: howto manager. (line 656) -* BFD_RELOC_SH_PCDISP8BY2: howto manager. (line 655) -* BFD_RELOC_SH_PCRELIMM8BY2: howto manager. (line 671) -* BFD_RELOC_SH_PCRELIMM8BY4: howto manager. (line 672) -* BFD_RELOC_SH_PLT_HI16: howto manager. (line 699) -* BFD_RELOC_SH_PLT_LOW16: howto manager. (line 696) -* BFD_RELOC_SH_PLT_MEDHI16: howto manager. (line 698) -* BFD_RELOC_SH_PLT_MEDLOW16: howto manager. (line 697) -* BFD_RELOC_SH_PT_16: howto manager. (line 736) -* BFD_RELOC_SH_RELATIVE: howto manager. (line 686) -* BFD_RELOC_SH_RELATIVE64: howto manager. (line 711) -* BFD_RELOC_SH_SHMEDIA_CODE: howto manager. (line 717) -* BFD_RELOC_SH_SWITCH16: howto manager. (line 673) -* BFD_RELOC_SH_SWITCH32: howto manager. (line 674) -* BFD_RELOC_SH_TLS_DTPMOD32: howto manager. (line 742) -* BFD_RELOC_SH_TLS_DTPOFF32: howto manager. (line 743) -* BFD_RELOC_SH_TLS_GD_32: howto manager. (line 737) -* BFD_RELOC_SH_TLS_IE_32: howto manager. (line 740) -* BFD_RELOC_SH_TLS_LD_32: howto manager. (line 738) -* BFD_RELOC_SH_TLS_LDO_32: howto manager. (line 739) -* BFD_RELOC_SH_TLS_LE_32: howto manager. (line 741) -* BFD_RELOC_SH_TLS_TPOFF32: howto manager. (line 744) -* BFD_RELOC_SH_USES: howto manager. (line 675) -* BFD_RELOC_SPARC13: howto manager. (line 119) -* BFD_RELOC_SPARC22: howto manager. (line 118) -* BFD_RELOC_SPARC_10: howto manager. (line 141) -* BFD_RELOC_SPARC_11: howto manager. (line 142) -* BFD_RELOC_SPARC_5: howto manager. (line 154) -* BFD_RELOC_SPARC_6: howto manager. (line 153) -* BFD_RELOC_SPARC_64: howto manager. (line 140) -* BFD_RELOC_SPARC_7: howto manager. (line 152) -* BFD_RELOC_SPARC_BASE13: howto manager. (line 136) -* BFD_RELOC_SPARC_BASE22: howto manager. (line 137) -* BFD_RELOC_SPARC_COPY: howto manager. (line 126) -* BFD_RELOC_SPARC_DISP64: howto manager. (line 155) -* BFD_RELOC_SPARC_GLOB_DAT: howto manager. (line 127) -* BFD_RELOC_SPARC_GOT10: howto manager. (line 120) -* BFD_RELOC_SPARC_GOT13: howto manager. (line 121) -* BFD_RELOC_SPARC_GOT22: howto manager. (line 122) -* BFD_RELOC_SPARC_H44: howto manager. (line 160) -* BFD_RELOC_SPARC_HH22: howto manager. (line 144) -* BFD_RELOC_SPARC_HIX22: howto manager. (line 158) -* BFD_RELOC_SPARC_HM10: howto manager. (line 145) -* BFD_RELOC_SPARC_JMP_SLOT: howto manager. (line 128) -* BFD_RELOC_SPARC_L44: howto manager. (line 162) -* BFD_RELOC_SPARC_LM22: howto manager. (line 146) -* BFD_RELOC_SPARC_LOX10: howto manager. (line 159) -* BFD_RELOC_SPARC_M44: howto manager. (line 161) -* BFD_RELOC_SPARC_OLO10: howto manager. (line 143) -* BFD_RELOC_SPARC_PC10: howto manager. (line 123) -* BFD_RELOC_SPARC_PC22: howto manager. (line 124) -* BFD_RELOC_SPARC_PC_HH22: howto manager. (line 147) -* BFD_RELOC_SPARC_PC_HM10: howto manager. (line 148) -* BFD_RELOC_SPARC_PC_LM22: howto manager. (line 149) -* BFD_RELOC_SPARC_PLT32: howto manager. (line 156) -* BFD_RELOC_SPARC_PLT64: howto manager. (line 157) -* BFD_RELOC_SPARC_REGISTER: howto manager. (line 163) -* BFD_RELOC_SPARC_RELATIVE: howto manager. (line 129) -* BFD_RELOC_SPARC_REV32: howto manager. (line 166) -* BFD_RELOC_SPARC_TLS_DTPMOD32: howto manager. (line 187) -* BFD_RELOC_SPARC_TLS_DTPMOD64: howto manager. (line 188) -* BFD_RELOC_SPARC_TLS_DTPOFF32: howto manager. (line 189) -* BFD_RELOC_SPARC_TLS_DTPOFF64: howto manager. (line 190) -* BFD_RELOC_SPARC_TLS_GD_ADD: howto manager. (line 171) -* BFD_RELOC_SPARC_TLS_GD_CALL: howto manager. (line 172) -* BFD_RELOC_SPARC_TLS_GD_HI22: howto manager. (line 169) -* BFD_RELOC_SPARC_TLS_GD_LO10: howto manager. (line 170) -* BFD_RELOC_SPARC_TLS_IE_ADD: howto manager. (line 184) -* BFD_RELOC_SPARC_TLS_IE_HI22: howto manager. (line 180) -* BFD_RELOC_SPARC_TLS_IE_LD: howto manager. (line 182) -* BFD_RELOC_SPARC_TLS_IE_LDX: howto manager. (line 183) -* BFD_RELOC_SPARC_TLS_IE_LO10: howto manager. (line 181) -* BFD_RELOC_SPARC_TLS_LDM_ADD: howto manager. (line 175) -* BFD_RELOC_SPARC_TLS_LDM_CALL: howto manager. (line 176) -* BFD_RELOC_SPARC_TLS_LDM_HI22: howto manager. (line 173) -* BFD_RELOC_SPARC_TLS_LDM_LO10: howto manager. (line 174) -* BFD_RELOC_SPARC_TLS_LDO_ADD: howto manager. (line 179) -* BFD_RELOC_SPARC_TLS_LDO_HIX22: howto manager. (line 177) -* BFD_RELOC_SPARC_TLS_LDO_LOX10: howto manager. (line 178) -* BFD_RELOC_SPARC_TLS_LE_HIX22: howto manager. (line 185) -* BFD_RELOC_SPARC_TLS_LE_LOX10: howto manager. (line 186) -* BFD_RELOC_SPARC_TLS_TPOFF32: howto manager. (line 191) -* BFD_RELOC_SPARC_TLS_TPOFF64: howto manager. (line 192) -* BFD_RELOC_SPARC_UA16: howto manager. (line 130) -* BFD_RELOC_SPARC_UA32: howto manager. (line 131) -* BFD_RELOC_SPARC_UA64: howto manager. (line 132) -* BFD_RELOC_SPARC_WDISP16: howto manager. (line 150) -* BFD_RELOC_SPARC_WDISP19: howto manager. (line 151) -* BFD_RELOC_SPARC_WDISP22: howto manager. (line 117) -* BFD_RELOC_SPARC_WPLT30: howto manager. (line 125) -* BFD_RELOC_THUMB_PCREL_BLX: howto manager. (line 601) -* BFD_RELOC_THUMB_PCREL_BRANCH12: howto manager. (line 749) -* BFD_RELOC_THUMB_PCREL_BRANCH23: howto manager. (line 750) -* BFD_RELOC_THUMB_PCREL_BRANCH9: howto manager. (line 748) -* BFD_RELOC_TIC30_LDP: howto manager. (line 956) -* BFD_RELOC_TIC54X_16_OF_23: howto manager. (line 974) -* BFD_RELOC_TIC54X_23: howto manager. (line 971) -* BFD_RELOC_TIC54X_MS7_OF_23: howto manager. (line 979) -* BFD_RELOC_TIC54X_PARTLS7: howto manager. (line 961) -* BFD_RELOC_TIC54X_PARTMS9: howto manager. (line 966) -* bfd_reloc_type_lookup: howto manager. (line 1693) -* BFD_RELOC_V850_22_PCREL: howto manager. (line 883) -* BFD_RELOC_V850_9_PCREL: howto manager. (line 880) -* BFD_RELOC_V850_ALIGN: howto manager. (line 941) -* BFD_RELOC_V850_CALLT_16_16_OFFSET: howto manager. (line 932) -* BFD_RELOC_V850_CALLT_6_7_OFFSET: howto manager. (line 929) -* BFD_RELOC_V850_LO16_SPLIT_OFFSET: howto manager. (line 944) -* BFD_RELOC_V850_LONGCALL: howto manager. (line 935) -* BFD_RELOC_V850_LONGJUMP: howto manager. (line 938) -* BFD_RELOC_V850_SDA_15_16_OFFSET: howto manager. (line 889) -* BFD_RELOC_V850_SDA_16_16_OFFSET: howto manager. (line 886) -* BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET: howto manager. (line 921) -* BFD_RELOC_V850_TDA_16_16_OFFSET: howto manager. (line 911) -* BFD_RELOC_V850_TDA_4_4_OFFSET: howto manager. (line 918) -* BFD_RELOC_V850_TDA_4_5_OFFSET: howto manager. (line 914) -* BFD_RELOC_V850_TDA_6_8_OFFSET: howto manager. (line 900) -* BFD_RELOC_V850_TDA_7_7_OFFSET: howto manager. (line 908) -* BFD_RELOC_V850_TDA_7_8_OFFSET: howto manager. (line 904) -* BFD_RELOC_V850_ZDA_15_16_OFFSET: howto manager. (line 896) -* BFD_RELOC_V850_ZDA_16_16_OFFSET: howto manager. (line 893) -* BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET: howto manager. (line 925) -* BFD_RELOC_VAX_GLOB_DAT: howto manager. (line 1594) -* BFD_RELOC_VAX_JMP_SLOT: howto manager. (line 1595) -* BFD_RELOC_VAX_RELATIVE: howto manager. (line 1596) -* BFD_RELOC_VPE4KMATH_DATA: howto manager. (line 1291) -* BFD_RELOC_VPE4KMATH_INSN: howto manager. (line 1292) -* BFD_RELOC_VTABLE_ENTRY: howto manager. (line 1296) -* BFD_RELOC_VTABLE_INHERIT: howto manager. (line 1295) -* BFD_RELOC_X86_64_32S: howto manager. (line 449) -* BFD_RELOC_X86_64_COPY: howto manager. (line 444) -* BFD_RELOC_X86_64_DTPMOD64: howto manager. (line 450) -* BFD_RELOC_X86_64_DTPOFF32: howto manager. (line 455) -* BFD_RELOC_X86_64_DTPOFF64: howto manager. (line 451) -* BFD_RELOC_X86_64_GLOB_DAT: howto manager. (line 445) -* BFD_RELOC_X86_64_GOT32: howto manager. (line 442) -* BFD_RELOC_X86_64_GOTPCREL: howto manager. (line 448) -* BFD_RELOC_X86_64_GOTTPOFF: howto manager. (line 456) -* BFD_RELOC_X86_64_JUMP_SLOT: howto manager. (line 446) -* BFD_RELOC_X86_64_PLT32: howto manager. (line 443) -* BFD_RELOC_X86_64_RELATIVE: howto manager. (line 447) -* BFD_RELOC_X86_64_TLSGD: howto manager. (line 453) -* BFD_RELOC_X86_64_TLSLD: howto manager. (line 454) -* BFD_RELOC_X86_64_TPOFF32: howto manager. (line 457) -* BFD_RELOC_X86_64_TPOFF64: howto manager. (line 452) -* BFD_RELOC_XSTORMY16_12: howto manager. (line 1589) -* BFD_RELOC_XSTORMY16_24: howto manager. (line 1590) -* BFD_RELOC_XSTORMY16_FPTR16: howto manager. (line 1591) -* BFD_RELOC_XSTORMY16_REL_12: howto manager. (line 1588) -* BFD_RELOC_XTENSA_ASM_EXPAND: howto manager. (line 1682) -* BFD_RELOC_XTENSA_ASM_SIMPLIFY: howto manager. (line 1687) -* BFD_RELOC_XTENSA_DIFF16: howto manager. (line 1629) -* BFD_RELOC_XTENSA_DIFF32: howto manager. (line 1630) -* BFD_RELOC_XTENSA_DIFF8: howto manager. (line 1628) -* BFD_RELOC_XTENSA_GLOB_DAT: howto manager. (line 1618) -* BFD_RELOC_XTENSA_JMP_SLOT: howto manager. (line 1619) -* BFD_RELOC_XTENSA_OP0: howto manager. (line 1676) -* BFD_RELOC_XTENSA_OP1: howto manager. (line 1677) -* BFD_RELOC_XTENSA_OP2: howto manager. (line 1678) -* BFD_RELOC_XTENSA_PLT: howto manager. (line 1623) -* BFD_RELOC_XTENSA_RELATIVE: howto manager. (line 1620) -* BFD_RELOC_XTENSA_RTLD: howto manager. (line 1613) -* BFD_RELOC_XTENSA_SLOT0_ALT: howto manager. (line 1658) -* BFD_RELOC_XTENSA_SLOT0_OP: howto manager. (line 1638) -* BFD_RELOC_XTENSA_SLOT10_ALT: howto manager. (line 1668) -* BFD_RELOC_XTENSA_SLOT10_OP: howto manager. (line 1648) -* BFD_RELOC_XTENSA_SLOT11_ALT: howto manager. (line 1669) -* BFD_RELOC_XTENSA_SLOT11_OP: howto manager. (line 1649) -* BFD_RELOC_XTENSA_SLOT12_ALT: howto manager. (line 1670) -* BFD_RELOC_XTENSA_SLOT12_OP: howto manager. (line 1650) -* BFD_RELOC_XTENSA_SLOT13_ALT: howto manager. (line 1671) -* BFD_RELOC_XTENSA_SLOT13_OP: howto manager. (line 1651) -* BFD_RELOC_XTENSA_SLOT14_ALT: howto manager. (line 1672) -* BFD_RELOC_XTENSA_SLOT14_OP: howto manager. (line 1652) -* BFD_RELOC_XTENSA_SLOT1_ALT: howto manager. (line 1659) -* BFD_RELOC_XTENSA_SLOT1_OP: howto manager. (line 1639) -* BFD_RELOC_XTENSA_SLOT2_ALT: howto manager. (line 1660) -* BFD_RELOC_XTENSA_SLOT2_OP: howto manager. (line 1640) -* BFD_RELOC_XTENSA_SLOT3_ALT: howto manager. (line 1661) -* BFD_RELOC_XTENSA_SLOT3_OP: howto manager. (line 1641) -* BFD_RELOC_XTENSA_SLOT4_ALT: howto manager. (line 1662) -* BFD_RELOC_XTENSA_SLOT4_OP: howto manager. (line 1642) -* BFD_RELOC_XTENSA_SLOT5_ALT: howto manager. (line 1663) -* BFD_RELOC_XTENSA_SLOT5_OP: howto manager. (line 1643) -* BFD_RELOC_XTENSA_SLOT6_ALT: howto manager. (line 1664) -* BFD_RELOC_XTENSA_SLOT6_OP: howto manager. (line 1644) -* BFD_RELOC_XTENSA_SLOT7_ALT: howto manager. (line 1665) -* BFD_RELOC_XTENSA_SLOT7_OP: howto manager. (line 1645) -* BFD_RELOC_XTENSA_SLOT8_ALT: howto manager. (line 1666) -* BFD_RELOC_XTENSA_SLOT8_OP: howto manager. (line 1646) -* BFD_RELOC_XTENSA_SLOT9_ALT: howto manager. (line 1667) -* BFD_RELOC_XTENSA_SLOT9_OP: howto manager. (line 1647) -* bfd_scan_arch: Architectures. (line 369) -* bfd_scan_vma: BFD front end. (line 420) -* bfd_seach_for_target: bfd_target. (line 445) -* bfd_section_already_linked: Writing the symbol table. - (line 55) -* bfd_section_list_clear: section prototypes. (line 8) -* bfd_sections_find_if: section prototypes. (line 145) -* bfd_set_arch_info: Architectures. (line 410) -* bfd_set_archive_head: Archives. (line 66) -* bfd_set_default_target: bfd_target. (line 410) -* bfd_set_error: BFD front end. (line 235) -* bfd_set_error_handler: BFD front end. (line 275) -* bfd_set_error_program_name: BFD front end. (line 284) -* bfd_set_file_flags: BFD front end. (line 340) -* bfd_set_format: Formats. (line 65) -* bfd_set_gp_size: BFD front end. (line 410) -* bfd_set_private_flags: BFD front end. (line 487) -* bfd_set_reloc: BFD front end. (line 330) -* bfd_set_section_contents: section prototypes. (line 176) -* bfd_set_section_flags: section prototypes. (line 109) -* bfd_set_section_size: section prototypes. (line 162) -* bfd_set_start_address: BFD front end. (line 389) -* bfd_set_symtab: symbol handling functions. - (line 60) -* bfd_symbol_info: symbol handling functions. - (line 130) -* bfd_target_list: bfd_target. (line 436) -* bfd_write_bigendian_4byte_int: Internal. (line 10) -* bfd_zalloc: Opening and Closing. - (line 188) -* coff_symbol_type: coff. (line 186) -* core_file_matches_executable_p: Core Files. (line 27) -* find_separate_debug_file: Opening and Closing. - (line 230) -* get_debug_link_info: Opening and Closing. - (line 211) -* Hash tables: Hash Tables. (line 6) -* internal object-file format: Canonical format. (line 11) -* Linker: Linker Functions. (line 6) -* Other functions: BFD front end. (line 502) -* separate_debug_file_exists: Opening and Closing. - (line 221) -* struct bfd_iovec: BFD front end. (line 646) -* target vector (_bfd_final_link): Performing the Final Link. - (line 6) -* target vector (_bfd_link_add_symbols): Adding Symbols to the Hash Table. - (line 6) -* target vector (_bfd_link_hash_table_create): Creating a Linker Hash Table. - (line 6) -* The HOWTO Macro: typedef arelent. (line 290) -* what is it?: Overview. (line 6) - - diff --git a/bfd/po/da.gmo b/bfd/po/da.gmo Binary files differdeleted file mode 100644 index 944a11c1610..00000000000 --- a/bfd/po/da.gmo +++ /dev/null diff --git a/bfd/po/es.gmo b/bfd/po/es.gmo Binary files differdeleted file mode 100644 index cff702a204f..00000000000 --- a/bfd/po/es.gmo +++ /dev/null diff --git a/bfd/po/fr.gmo b/bfd/po/fr.gmo Binary files differdeleted file mode 100644 index 1a6948d5b93..00000000000 --- a/bfd/po/fr.gmo +++ /dev/null diff --git a/bfd/po/ja.gmo b/bfd/po/ja.gmo Binary files differdeleted file mode 100644 index f8142480577..00000000000 --- a/bfd/po/ja.gmo +++ /dev/null diff --git a/bfd/po/ro.gmo b/bfd/po/ro.gmo Binary files differdeleted file mode 100644 index 8621928313f..00000000000 --- a/bfd/po/ro.gmo +++ /dev/null diff --git a/bfd/po/sv.gmo b/bfd/po/sv.gmo Binary files differdeleted file mode 100644 index e746ec02e75..00000000000 --- a/bfd/po/sv.gmo +++ /dev/null diff --git a/bfd/po/tr.gmo b/bfd/po/tr.gmo Binary files differdeleted file mode 100644 index 74c0ea8fc2d..00000000000 --- a/bfd/po/tr.gmo +++ /dev/null diff --git a/bfd/po/zh_CN.gmo b/bfd/po/zh_CN.gmo Binary files differdeleted file mode 100644 index 501f89d427f..00000000000 --- a/bfd/po/zh_CN.gmo +++ /dev/null diff --git a/etc/configure.info b/etc/configure.info deleted file mode 100644 index 589b25c415b..00000000000 --- a/etc/configure.info +++ /dev/null @@ -1,2771 +0,0 @@ -This is configure.info, produced by makeinfo version 4.7 from -.././etc/configure.texi. - -INFO-DIR-SECTION GNU admin -START-INFO-DIR-ENTRY -* configure: (configure). The GNU configure and build system -END-INFO-DIR-ENTRY - - This file documents the GNU configure and build system. - - Copyright (C) 1998 Cygnus Solutions. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Foundation. - - -File: configure.info, Node: Top, Next: Introduction, Up: (dir) - -GNU configure and build system -****************************** - -The GNU configure and build system. - -* Menu: - -* Introduction:: Introduction. -* Getting Started:: Getting Started. -* Files:: Files. -* Configuration Names:: Configuration Names. -* Cross Compilation Tools:: Cross Compilation Tools. -* Canadian Cross:: Canadian Cross. -* Cygnus Configure:: Cygnus Configure. -* Multilibs:: Multilibs. -* FAQ:: Frequently Asked Questions. -* Index:: Index. - - -File: configure.info, Node: Introduction, Next: Getting Started, Prev: Top, Up: Top - -1 Introduction -************** - -This document describes the GNU configure and build systems. It -describes how autoconf, automake, libtool, and make fit together. It -also includes a discussion of the older Cygnus configure system. - - This document does not describe in detail how to use each of the -tools; see the respective manuals for that. Instead, it describes -which files the developer must write, which files are machine generated -and how they are generated, and where certain common problems should be -addressed. - - This document draws on several sources, including the autoconf -manual by David MacKenzie (*note autoconf overview: (autoconf)Top.), -the automake manual by David MacKenzie and Tom Tromey (*note automake -overview: (automake)Top.), the libtool manual by Gordon Matzigkeit -(*note libtool overview: (libtool)Top.), and the Cygnus configure -manual by K. Richard Pixley. - -* Menu: - -* Goals:: Goals. -* Tools:: The tools. -* History:: History. -* Building:: Building. - - -File: configure.info, Node: Goals, Next: Tools, Up: Introduction - -1.1 Goals -========= - -The GNU configure and build system has two main goals. - - The first is to simplify the development of portable programs. The -system permits the developer to concentrate on writing the program, -simplifying many details of portability across Unix and even Windows -systems, and permitting the developer to describe how to build the -program using simple rules rather than complex Makefiles. - - The second is to simplify the building of programs distributed as -source code. All programs are built using a simple, standardized, two -step process. The program builder need not install any special tools in -order to build the program. - - -File: configure.info, Node: Tools, Next: History, Prev: Goals, Up: Introduction - -1.2 Tools -========= - -The GNU configure and build system is comprised of several different -tools. Program developers must build and install all of these tools. - - People who just want to build programs from distributed sources -normally do not need any special tools beyond a Unix shell, a make -program, and a C compiler. - -autoconf - provides a general portability framework, based on testing the - features of the host system at build time. - -automake - a system for describing how to build a program, permitting the - developer to write a simplified `Makefile'. - -libtool - a standardized approach to building shared libraries. - -gettext - provides a framework for translation of text messages into other - languages; not really discussed in this document. - -m4 - autoconf requires the GNU version of m4; the standard Unix m4 does - not suffice. - -perl - automake requires perl. - - -File: configure.info, Node: History, Next: Building, Prev: Tools, Up: Introduction - -1.3 History -=========== - -This is a very brief and probably inaccurate history. - - As the number of Unix variants increased during the 1980s, it became -harder to write programs which could run on all variants. While it was -often possible to use `#ifdef' to identify particular systems, -developers frequently did not have access to every system, and the -characteristics of some systems changed from version to version. - - By 1992, at least three different approaches had been developed: - * The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael - Manfredi. - - * The Cygnus configure script, by K. Richard Pixley, and the gcc - configure script, by Richard Stallman. These use essentially the - same approach, and the developers communicated regularly. - - * The autoconf program, by David MacKenzie. - - The Metaconfig program is still used for Perl and a few other -programs. It is part of the Dist package. I do not know if it is -being developed. - - In 1994, David MacKenzie and others modified autoconf to incorporate -all the features of Cygnus configure. Since then, there has been a -slow but steady conversion of GNU programs from Cygnus configure to -autoconf. gcc has been converted, eliminating the gcc configure script. - - GNU autoconf was regularly maintained until late 1996. As of this -writing in June, 1998, it has no public maintainer. - - Most programs are built using the make program, which requires the -developer to write Makefiles describing how to build the programs. -Since most programs are built in pretty much the same way, this led to a -lot of duplication. - - The X Window system is built using the imake tool, which uses a -database of rules to eliminate the duplication. However, building a -tool which was developed using imake requires that the builder have -imake installed, violating one of the goals of the GNU system. - - The new BSD make provides a standard library of Makefile fragments, -which permits developers to write very simple Makefiles. However, this -requires that the builder install the new BSD make program. - - In 1994, David MacKenzie wrote the first version of automake, which -permitted writing a simple build description which was converted into a -Makefile which could be used by the standard make program. In 1995, Tom -Tromey completely rewrote automake in Perl, and he continues to enhance -it. - - Various free packages built libraries, and by around 1995 several -included support to build shared libraries on various platforms. -However, there was no consistent approach. In early 1996, Gordon -Matzigkeit began working on libtool, which provided a standardized -approach to building shared libraries. This was integrated into -automake from the start. - - The development of automake and libtool was driven by the GNITS -project, a group of GNU maintainers who designed standardized tools to -help meet the GNU coding standards. - - -File: configure.info, Node: Building, Prev: History, Up: Introduction - -1.4 Building -============ - -Most readers of this document should already know how to build a tool by -running `configure' and `make'. This section may serve as a quick -introduction or reminder. - - Building a tool is normally as simple as running `configure' -followed by `make'. You should normally run `configure' from an empty -directory, using some path to refer to the `configure' script in the -source directory. The directory in which you run `configure' is called -the "object directory". - - In order to use a object directory which is different from the source -directory, you must be using the GNU version of `make', which has the -required `VPATH' support. Despite this restriction, using a different -object directory is highly recommended: - * It keeps the files generated during the build from cluttering up - your sources. - - * It permits you to remove the built files by simply removing the - entire build directory. - - * It permits you to build from the same sources with several sets of - configure options simultaneously. - - If you don't have GNU `make', you will have to run `configure' in -the source directory. All GNU packages should support this; in -particular, GNU packages should not assume the presence of GNU `make'. - - After running `configure', you can build the tools by running `make'. - - To install the tools, run `make install'. Installing the tools will -copy the programs and any required support files to the "installation -directory". The location of the installation directory is controlled -by `configure' options, as described below. - - In the Cygnus tree at present, the info files are built and -installed as a separate step. To build them, run `make info'. To -install them, run `make install-info'. - - All `configure' scripts support a wide variety of options. The most -interesting ones are `--with' and `--enable' options which are -generally specific to particular tools. You can usually use the -`--help' option to get a list of interesting options for a particular -configure script. - - The only generic options you are likely to use are the `--prefix' -and `--exec-prefix' options. These options are used to specify the -installation directory. - - The directory named by the `--prefix' option will hold machine -independent files such as info files. - - The directory named by the `--exec-prefix' option, which is normally -a subdirectory of the `--prefix' directory, will hold machine dependent -files such as executables. - - The default for `--prefix' is `/usr/local'. The default for -`--exec-prefix' is the value used for `--prefix'. - - The convention used in Cygnus releases is to use a `--prefix' option -of `/usr/cygnus/RELEASE', where RELEASE is the name of the release, and -to use a `--exec-prefix' option of `/usr/cygnus/RELEASE/H-HOST', where -HOST is the configuration name of the host system (*note Configuration -Names::). - - Do not use either the source or the object directory as the -installation directory. That will just lead to confusion. - - -File: configure.info, Node: Getting Started, Next: Files, Prev: Introduction, Up: Top - -2 Getting Started -***************** - -To start using the GNU configure and build system with your software -package, you must write three files, and you must run some tools to -manually generate additional files. - -* Menu: - -* Write configure.in:: Write configure.in. -* Write Makefile.am:: Write Makefile.am. -* Write acconfig.h:: Write acconfig.h. -* Generate files:: Generate files. -* Getting Started Example:: Example. - - -File: configure.info, Node: Write configure.in, Next: Write Makefile.am, Up: Getting Started - -2.1 Write configure.in -====================== - -You must first write the file `configure.in'. This is an autoconf -input file, and the autoconf manual describes in detail what this file -should look like. - - You will write tests in your `configure.in' file to check for -conditions that may change from one system to another, such as the -presence of particular header files or functions. - - For example, not all systems support the `gettimeofday' function. -If you want to use the `gettimeofday' function when it is available, -and to use some other function when it is not, you would check for this -by putting `AC_CHECK_FUNCS(gettimeofday)' in `configure.in'. - - When the configure script is run at build time, this will arrange to -define the preprocessor macro `HAVE_GETTIMEOFDAY' to the value 1 if the -`gettimeofday' function is available, and to not define the macro at -all if the function is not available. Your code can then use `#ifdef' -to test whether it is safe to call `gettimeofday'. - - If you have an existing body of code, the `autoscan' program may -help identify potential portability problems, and hence configure tests -that you will want to use. *Note Invoking autoscan: (autoconf)Invoking -autoscan. - - Another handy tool for an existing body of code is `ifnames'. This -will show you all the preprocessor conditionals that the code already -uses. *Note Invoking ifnames: (autoconf)Invoking ifnames. - - Besides the portability tests which are specific to your particular -package, every `configure.in' file should contain the following macros. - -`AC_INIT' - This macro takes a single argument, which is the name of a file in - your package. For example, `AC_INIT(foo.c)'. - -`AC_PREREQ(VERSION)' - This macro is optional. It may be used to indicate the version of - `autoconf' that you are using. This will prevent users from - running an earlier version of `autoconf' and perhaps getting an - invalid `configure' script. For example, `AC_PREREQ(2.12)'. - -`AM_INIT_AUTOMAKE' - This macro takes two arguments: the name of the package, and a - version number. For example, `AM_INIT_AUTOMAKE(foo, 1.0)'. (This - macro is not needed if you are not using automake). - -`AM_CONFIG_HEADER' - This macro names the header file which will hold the preprocessor - macro definitions at run time. Normally this should be - `config.h'. Your sources would then use `#include "config.h"' to - include it. - - This macro may optionally name the input file for that header - file; by default, this is `config.h.in', but that file name works - poorly on DOS filesystems. Therefore, it is often better to name - it explicitly as `config.in'. - - This is what you should normally put in `configure.in': - AM_CONFIG_HEADER(config.h:config.in) - - (If you are not using automake, use `AC_CONFIG_HEADER' rather than - `AM_CONFIG_HEADER'). - -`AM_MAINTAINER_MODE' - This macro always appears in Cygnus configure scripts. Other - programs may or may not use it. - - If this macro is used, the `--enable-maintainer-mode' option is - required to enable automatic rebuilding of generated files used by - the configure system. This of course requires that developers be - aware of, and use, that option. - - If this macro is not used, then the generated files will always be - rebuilt automatically. This will cause problems if the wrong - versions of autoconf, automake, or others are in the builder's - `PATH'. - - (If you are not using automake, you do not need to use this macro). - -`AC_EXEEXT' - Either this macro or `AM_EXEEXT' always appears in Cygnus configure - files. Other programs may or may not use one of them. - - This macro looks for the executable suffix used on the host - system. On Unix systems, this is the empty string. On Windows - systems, this is `.exe'. This macro directs automake to use the - executable suffix as appropriate when creating programs. This - macro does not take any arguments. - - The `AC_EXEEXT' form is new, and is part of a Cygnus patch to - autoconf to support compiling with Visual C++. Older programs use - `AM_EXEEXT' instead. - - (Programs which do not use automake use neither `AC_EXEEXT' nor - `AM_EXEEXT'). - -`AC_PROG_CC' - If you are writing C code, you will normally want to use this - macro. It locates the C compiler to use. It does not take any - arguments. - - However, if this `configure.in' file is for a library which is to - be compiled by a cross compiler which may not fully work, then you - will not want to use `AC_PROG_CC'. Instead, you will want to use a - variant which does not call the macro `AC_PROG_CC_WORKS'. Examples - can be found in various `configure.in' files for libraries that are - compiled with cross compilers, such as libiberty or libgloss. - This is essentially a bug in autoconf, and there will probably be - a better workaround at some point. - -`AC_PROG_CXX' - If you are writing C++ code, you will want to use this macro. It - locates the C++ compiler to use. It does not take any arguments. - The same cross compiler comments apply as for `AC_PROG_CC'. - -`AM_PROG_LIBTOOL' - If you want to build libraries, and you want to permit them to be - shared, or you want to link against libraries which were built - using libtool, then you will need this macro. This macro is - required in order to use libtool. - - By default, this will cause all libraries to be built as shared - libraries. To prevent this-to change the default-use - `AM_DISABLE_SHARED' before `AM_PROG_LIBTOOL'. The configure - options `--enable-shared' and `--disable-shared' may be used to - override the default at build time. - -`AC_DEFINE(_GNU_SOURCE)' - GNU packages should normally include this line before any other - feature tests. This defines the macro `_GNU_SOURCE' when - compiling, which directs the libc header files to provide the - standard GNU system interfaces including all GNU extensions. If - this macro is not defined, certain GNU extensions may not be - available. - -`AC_OUTPUT' - This macro takes a list of file names which the configure process - should produce. This is normally a list of one or more `Makefile' - files in different directories. If your package lives entirely in - a single directory, you would use simply `AC_OUTPUT(Makefile)'. - If you also have, for example, a `lib' subdirectory, you would use - `AC_OUTPUT(Makefile lib/Makefile)'. - - If you want to use locally defined macros in your `configure.in' -file, then you will need to write a `acinclude.m4' file which defines -them (if not using automake, this file is called `aclocal.m4'). -Alternatively, you can put separate macros in an `m4' subdirectory, and -put `ACLOCAL_AMFLAGS = -I m4' in your `Makefile.am' file so that the -`aclocal' program will be able to find them. - - The different macro prefixes indicate which tool defines the macro. -Macros which start with `AC_' are part of autoconf. Macros which start -with `AM_' are provided by automake or libtool. - - -File: configure.info, Node: Write Makefile.am, Next: Write acconfig.h, Prev: Write configure.in, Up: Getting Started - -2.2 Write Makefile.am -===================== - -You must write the file `Makefile.am'. This is an automake input file, -and the automake manual describes in detail what this file should look -like. - - The automake commands in `Makefile.am' mostly look like variable -assignments in a `Makefile'. automake recognizes special variable -names, and automatically add make rules to the output as needed. - - There will be one `Makefile.am' file for each directory in your -package. For each directory with subdirectories, the `Makefile.am' -file should contain the line - SUBDIRS = DIR DIR ... - where each DIR is the name of a subdirectory. - - For each `Makefile.am', there should be a corresponding `Makefile' -in the `AC_OUTPUT' macro in `configure.in'. - - Every `Makefile.am' written at Cygnus should contain the line - AUTOMAKE_OPTIONS = cygnus - This puts automake into Cygnus mode. See the automake manual for -details. - - You may to include the version number of `automake' that you are -using on the `AUTOMAKE_OPTIONS' line. For example, - AUTOMAKE_OPTIONS = cygnus 1.3 - This will prevent users from running an earlier version of -`automake' and perhaps getting an invalid `Makefile.in'. - - If your package builds a program, then in the directory where that -program is built you will normally want a line like - bin_PROGRAMS = PROGRAM - where PROGRAM is the name of the program. You will then want a line -like - PROGRAM_SOURCES = FILE FILE ... - where each FILE is the name of a source file to link into the -program (e.g., `foo.c'). - - If your package builds a library, and you do not want the library to -ever be built as a shared library, then in the directory where that -library is built you will normally want a line like - lib_LIBRARIES = libNAME.a - where `libNAME.a' is the name of the library. You will then want a -line like - libNAME_a_SOURCES = FILE FILE ... - where each FILE is the name of a source file to add to the library. - - If your package builds a library, and you want to permit building the -library as a shared library, then in the directory where that library is -built you will normally want a line like - lib_LTLIBRARIES = libNAME.la - The use of `LTLIBRARIES', and the `.la' extension, indicate a -library to be built using libtool. As usual, you will then want a line -like - libNAME_la_SOURCES = FILE FILE ... - - The strings `bin' and `lib' that appear above in `bin_PROGRAMS' and -`lib_LIBRARIES' are not arbitrary. They refer to particular -directories, which may be set by the `--bindir' and `--libdir' options -to `configure'. If those options are not used, the default values are -based on the `--prefix' or `--exec-prefix' options to `configure'. It -is possible to use other names if the program or library should be -installed in some other directory. - - The `Makefile.am' file may also contain almost anything that may -appear in a normal `Makefile'. automake also supports many other -special variables, as well as conditionals. - - See the automake manual for more information. - - -File: configure.info, Node: Write acconfig.h, Next: Generate files, Prev: Write Makefile.am, Up: Getting Started - -2.3 Write acconfig.h -==================== - -If you are generating a portability header file, (i.e., you are using -`AM_CONFIG_HEADER' in `configure.in'), then you will have to write a -`acconfig.h' file. It will have to contain the following lines. - - /* Name of package. */ - #undef PACKAGE - - /* Version of package. */ - #undef VERSION - - This requirement is really a bug in the system, and the requirement -may be eliminated at some later date. - - The `acconfig.h' file will also similar comment and `#undef' lines -for any unusual macros in the `configure.in' file, including any macro -which appears in a `AC_DEFINE' macro. - - In particular, if you are writing a GNU package and therefore include -`AC_DEFINE(_GNU_SOURCE)' in `configure.in' as suggested above, you will -need lines like this in `acconfig.h': - /* Enable GNU extensions. */ - #undef _GNU_SOURCE - - Normally the `autoheader' program will inform you of any such -requirements by printing an error message when it is run. However, if -you do anything particular odd in your `configure.in' file, you will -have to make sure that the right entries appear in `acconfig.h', since -otherwise the results of the tests may not be available in the -`config.h' file which your code will use. - - (Thee `PACKAGE' and `VERSION' lines are not required if you are not -using automake, and in that case you may not need a `acconfig.h' file -at all). - - -File: configure.info, Node: Generate files, Next: Getting Started Example, Prev: Write acconfig.h, Up: Getting Started - -2.4 Generate files -================== - -Once you have written `configure.in', `Makefile.am', `acconfig.h', and -possibly `acinclude.m4', you must use autoconf and automake programs to -produce the first versions of the generated files. This is done by -executing the following sequence of commands. - - aclocal - autoconf - autoheader - automake - - The `aclocal' and `automake' commands are part of the automake -package, and the `autoconf' and `autoheader' commands are part of the -autoconf package. - - If you are using a `m4' subdirectory for your macros, you will need -to use the `-I m4' option when you run `aclocal'. - - If you are not using the Cygnus tree, use the `-a' option when -running `automake' command in order to copy the required support files -into your source directory. - - If you are using libtool, you must build and install the libtool -package with the same `--prefix' and `--exec-prefix' options as you -used with the autoconf and automake packages. You must do this before -running any of the above commands. If you are not using the Cygnus -tree, you will need to run the `libtoolize' program to copy the libtool -support files into your directory. - - Once you have managed to run these commands without getting any -errors, you should create a new empty directory, and run the `configure' -script which will have been created by `autoconf' with the -`--enable-maintainer-mode' option. This will give you a set of -Makefiles which will include rules to automatically rebuild all the -generated files. - - After doing that, whenever you have changed some of the input files -and want to regenerated the other files, go to your object directory -and run `make'. Doing this is more reliable than trying to rebuild the -files manually, because there are complex order dependencies and it is -easy to forget something. - - -File: configure.info, Node: Getting Started Example, Prev: Generate files, Up: Getting Started - -2.5 Example -=========== - -Let's consider a trivial example. - - Suppose we want to write a simple version of `touch'. Our program, -which we will call `poke', will take a single file name argument, and -use the `utime' system call to set the modification and access times of -the file to the current time. We want this program to be highly -portable. - - We'll first see what this looks like without using autoconf and -automake, and then see what it looks like with them. - -* Menu: - -* Getting Started Example 1:: First Try. -* Getting Started Example 2:: Second Try. -* Getting Started Example 3:: Third Try. -* Generate Files in Example:: Generate Files. - - -File: configure.info, Node: Getting Started Example 1, Next: Getting Started Example 2, Up: Getting Started Example - -2.5.1 First Try ---------------- - -Here is our first try at `poke.c'. Note that we've written it without -ANSI/ISO C prototypes, since we want it to be highly portable. - - #include <stdio.h> - #include <stdlib.h> - #include <sys/types.h> - #include <utime.h> - - int - main (argc, argv) - int argc; - char **argv; - { - if (argc != 2) - { - fprintf (stderr, "Usage: poke file\n"); - exit (1); - } - - if (utime (argv[1], NULL) < 0) - { - perror ("utime"); - exit (1); - } - - exit (0); - } - - We also write a simple `Makefile'. - - CC = gcc - CFLAGS = -g -O2 - - all: poke - - poke: poke.o - $(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o - - So far, so good. - - Unfortunately, there are a few problems. - - On older Unix systems derived from BSD 4.3, the `utime' system call -does not accept a second argument of `NULL'. On those systems, we need -to pass a pointer to `struct utimbuf' structure. Unfortunately, even -older systems don't define that structure; on those systems, we need to -pass an array of two `long' values. - - The header file `stdlib.h' was invented by ANSI C, and older systems -don't have a copy. We included it above to get a declaration of `exit'. - - We can find some of these portability problems by running -`autoscan', which will create a `configure.scan' file which we can use -as a prototype for our `configure.in' file. I won't show the output, -but it will notice the potential problems with `utime' and `stdlib.h'. - - In our `Makefile', we don't provide any way to install the program. -This doesn't matter much for such a simple example, but a real program -will need an `install' target. For that matter, we will also want a -`clean' target. - - -File: configure.info, Node: Getting Started Example 2, Next: Getting Started Example 3, Prev: Getting Started Example 1, Up: Getting Started Example - -2.5.2 Second Try ----------------- - -Here is our second try at this program. - - We modify `poke.c' to use preprocessor macros to control what -features are available. (I've cheated a bit by using the same macro -names which autoconf will use). - - #include <stdio.h> - - #ifdef STDC_HEADERS - #include <stdlib.h> - #endif - - #include <sys/types.h> - - #ifdef HAVE_UTIME_H - #include <utime.h> - #endif - - #ifndef HAVE_UTIME_NULL - - #include <time.h> - - #ifndef HAVE_STRUCT_UTIMBUF - - struct utimbuf - { - long actime; - long modtime; - }; - - #endif - - static int - utime_now (file) - char *file; - { - struct utimbuf now; - - now.actime = now.modtime = time (NULL); - return utime (file, &now); - } - - #define utime(f, p) utime_now (f) - - #endif /* HAVE_UTIME_NULL */ - - int - main (argc, argv) - int argc; - char **argv; - { - if (argc != 2) - { - fprintf (stderr, "Usage: poke file\n"); - exit (1); - } - - if (utime (argv[1], NULL) < 0) - { - perror ("utime"); - exit (1); - } - - exit (0); - } - - Here is the associated `Makefile'. We've added support for the -preprocessor flags we use. We've also added `install' and `clean' -targets. - - # Set this to your installation directory. - bindir = /usr/local/bin - - # Uncomment this if you have the standard ANSI/ISO C header files. - # STDC_HDRS = -DSTDC_HEADERS - - # Uncomment this if you have utime.h. - # UTIME_H = -DHAVE_UTIME_H - - # Uncomment this if utime (FILE, NULL) works on your system. - # UTIME_NULL = -DHAVE_UTIME_NULL - - # Uncomment this if struct utimbuf is defined in utime.h. - # UTIMBUF = -DHAVE_STRUCT_UTIMBUF - - CC = gcc - CFLAGS = -g -O2 - - ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS) - - all: poke - - poke: poke.o - $(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o - - .c.o: - $(CC) -c $(ALL_CFLAGS) poke.c - - install: poke - cp poke $(bindir)/poke - - clean: - rm poke poke.o - - Some problems with this approach should be clear. - - Users who want to compile poke will have to know how `utime' works -on their systems, so that they can uncomment the `Makefile' correctly. - - The installation is done using `cp', but many systems have an -`install' program which may be used, and which supports optional -features such as stripping debugging information out of the installed -binary. - - The use of `Makefile' variables like `CC', `CFLAGS' and `LDFLAGS' -follows the requirements of the GNU standards. This is convenient for -all packages, since it reduces surprises for users. However, it is -easy to get the details wrong, and wind up with a slightly nonstandard -distribution. - - -File: configure.info, Node: Getting Started Example 3, Next: Generate Files in Example, Prev: Getting Started Example 2, Up: Getting Started Example - -2.5.3 Third Try ---------------- - -For our third try at this program, we will write a `configure.in' -script to discover the configuration features on the host system, rather -than requiring the user to edit the `Makefile'. We will also write a -`Makefile.am' rather than a `Makefile'. - - The only change to `poke.c' is to add a line at the start of the -file: - #include "config.h" - - The new `configure.in' file is as follows. - - AC_INIT(poke.c) - AM_INIT_AUTOMAKE(poke, 1.0) - AM_CONFIG_HEADER(config.h:config.in) - AC_PROG_CC - AC_HEADER_STDC - AC_CHECK_HEADERS(utime.h) - AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF)) - AC_FUNC_UTIME_NULL - AC_OUTPUT(Makefile) - - The first four macros in this file, and the last one, were described -above; see *Note Write configure.in::. If we omit these macros, then -when we run `automake' we will get a reminder that we need them. - - The other macros are standard autoconf macros. - -`AC_HEADER_STDC' - Check for standard C headers. - -`AC_CHECK_HEADERS' - Check whether a particular header file exists. - -`AC_EGREP_HEADER' - Check for a particular string in a particular header file, in this - case checking for `utimbuf' in `utime.h'. - -`AC_FUNC_UTIME_NULL' - Check whether `utime' accepts a NULL second argument to set the - file change time to the current time. - - See the autoconf manual for a more complete description. - - The new `Makefile.am' file is as follows. Note how simple this is -compared to our earlier `Makefile'. - - bin_PROGRAMS = poke - - poke_SOURCES = poke.c - - This means that we should build a single program name `poke'. It -should be installed in the binary directory, which we called `bindir' -earlier. The program `poke' is built from the source file `poke.c'. - - We must also write a `acconfig.h' file. Besides `PACKAGE' and -`VERSION', which must be mentioned for all packages which use automake, -we must include `HAVE_STRUCT_UTIMBUF', since we mentioned it in an -`AC_DEFINE'. - - /* Name of package. */ - #undef PACKAGE - - /* Version of package. */ - #undef VERSION - - /* Whether utime.h defines struct utimbuf. */ - #undef HAVE_STRUCT_UTIMBUF - - -File: configure.info, Node: Generate Files in Example, Prev: Getting Started Example 3, Up: Getting Started Example - -2.5.4 Generate Files --------------------- - -We must now generate the other files, using the following commands. - - aclocal - autoconf - autoheader - automake - - When we run `autoheader', it will remind us of any macros we forgot -to add to `acconfig.h'. - - When we run `automake', it will want to add some files to our -distribution. It will add them automatically if we use the -`--add-missing' option. - - By default, `automake' will run in GNU mode, which means that it -will want us to create certain additional files; as of this writing, it -will want `NEWS', `README', `AUTHORS', and `ChangeLog', all of which -are files which should appear in a standard GNU distribution. We can -either add those files, or run `automake' with the `--foreign' option. - - Running these tools will generate the following files, all of which -are described in the next chapter. - - * `aclocal.m4' - - * `configure' - - * `config.in' - - * `Makefile.in' - - * `stamp-h.in' - - -File: configure.info, Node: Files, Next: Configuration Names, Prev: Getting Started, Up: Top - -3 Files -******* - -As was seen in the previous chapter, the GNU configure and build system -uses a number of different files. The developer must write a few files. -The others are generated by various tools. - - The system is rather flexible, and can be used in many different -ways. In describing the files that it uses, I will describe the common -case, and mention some other cases that may arise. - -* Menu: - -* Developer Files:: Developer Files. -* Build Files:: Build Files. -* Support Files:: Support Files. - - -File: configure.info, Node: Developer Files, Next: Build Files, Up: Files - -3.1 Developer Files -=================== - -This section describes the files written or generated by the developer -of a package. - -* Menu: - -* Developer Files Picture:: Developer Files Picture. -* Written Developer Files:: Written Developer Files. -* Generated Developer Files:: Generated Developer Files. - - -File: configure.info, Node: Developer Files Picture, Next: Written Developer Files, Up: Developer Files - -3.1.1 Developer Files Picture ------------------------------ - -Here is a picture of the files which are written by the developer, the -generated files which would be included with a complete source -distribution, and the tools which create those files. The file names -are plain text and the tool names are enclosed by `*' characters (e.g., -`autoheader' is the name of a tool, not the name of a file). - - acconfig.h configure.in Makefile.am - | | | - | --------------+---------------------- | - | | | | | - v v | acinclude.m4 | | - *autoheader* | | v v - | | v --->*automake* - v |--->*aclocal* | | - config.in | | | v - | v | Makefile.in - | aclocal.m4--- - | | - v v - *autoconf* - | - v - configure - - -File: configure.info, Node: Written Developer Files, Next: Generated Developer Files, Prev: Developer Files Picture, Up: Developer Files - -3.1.2 Written Developer Files ------------------------------ - -The following files would be written by the developer. - -`configure.in' - This is the configuration script. This script contains - invocations of autoconf macros. It may also contain ordinary - shell script code. This file will contain feature tests for - portability issues. The last thing in the file will normally be - an `AC_OUTPUT' macro listing which files to create when the - builder runs the configure script. This file is always required - when using the GNU configure system. *Note Write configure.in::. - -`Makefile.am' - This is the automake input file. It describes how the code should - be built. It consists of definitions of automake variables. It - may also contain ordinary Makefile targets. This file is only - needed when using automake (newer tools normally use automake, but - there are still older tools which have not been converted, in - which the developer writes `Makefile.in' directly). *Note Write - Makefile.am::. - -`acconfig.h' - When the configure script creates a portability header file, by - using `AM_CONFIG_HEADER' (or, if not using automake, - `AC_CONFIG_HEADER'), this file is used to describe macros which are - not recognized by the `autoheader' command. This is normally a - fairly uninteresting file, consisting of a collection of `#undef' - lines with comments. Normally any call to `AC_DEFINE' in - `configure.in' will require a line in this file. *Note Write - acconfig.h::. - -`acinclude.m4' - This file is not always required. It defines local autoconf - macros. These macros may then be used in `configure.in'. If you - don't need any local autoconf macros, then you don't need this - file at all. In fact, in general, you never need local autoconf - macros, since you can put everything in `configure.in', but - sometimes a local macro is convenient. - - Newer tools may omit `acinclude.m4', and instead use a - subdirectory, typically named `m4', and define `ACLOCAL_AMFLAGS = - -I m4' in `Makefile.am' to force `aclocal' to look there for macro - definitions. The macro definitions are then placed in separate - files in that directory. - - The `acinclude.m4' file is only used when using automake; in older - tools, the developer writes `aclocal.m4' directly, if it is needed. - - -File: configure.info, Node: Generated Developer Files, Prev: Written Developer Files, Up: Developer Files - -3.1.3 Generated Developer Files -------------------------------- - -The following files would be generated by the developer. - - When using automake, these files are normally not generated manually -after the first time. Instead, the generated `Makefile' contains rules -to automatically rebuild the files as required. When -`AM_MAINTAINER_MODE' is used in `configure.in' (the normal case in -Cygnus code), the automatic rebuilding rules will only be defined if -you configure using the `--enable-maintainer-mode' option. - - When using automatic rebuilding, it is important to ensure that all -the various tools have been built and installed on your `PATH'. Using -automatic rebuilding is highly recommended, so much so that I'm not -going to explain what you have to do if you don't use it. - -`configure' - This is the configure script which will be run when building the - package. This is generated by `autoconf' from `configure.in' and - `aclocal.m4'. This is a shell script. - -`Makefile.in' - This is the file which the configure script will turn into the - `Makefile' at build time. This file is generated by `automake' - from `Makefile.am'. If you aren't using automake, you must write - this file yourself. This file is pretty much a normal `Makefile', - with some configure substitutions for certain variables. - -`aclocal.m4' - This file is created by the `aclocal' program, based on the - contents of `configure.in' and `acinclude.m4' (or, as noted in the - description of `acinclude.m4' above, on the contents of an `m4' - subdirectory). This file contains definitions of autoconf macros - which `autoconf' will use when generating the file `configure'. - These autoconf macros may be defined by you in `acinclude.m4' or - they may be defined by other packages such as automake, libtool or - gettext. If you aren't using automake, you will normally write - this file yourself; in that case, if `configure.in' uses only - standard autoconf macros, this file will not be needed at all. - -`config.in' - This file is created by `autoheader' based on `acconfig.h' and - `configure.in'. At build time, the configure script will define - some of the macros in it to create `config.h', which may then be - included by your program. This permits your C code to use - preprocessor conditionals to change its behaviour based on the - characteristics of the host system. This file may also be called - `config.h.in'. - -`stamp.h-in' - This rather uninteresting file, which I omitted from the picture, - is generated by `automake'. It always contains the string - `timestamp'. It is used as a timestamp file indicating whether - `config.in' is up to date. Using a timestamp file means that - `config.in' can be marked as up to date without actually changing - its modification time. This is useful since `config.in' depends - upon `configure.in', but it is easy to change `configure.in' in a - way which does not affect `config.in'. - - -File: configure.info, Node: Build Files, Next: Support Files, Prev: Developer Files, Up: Files - -3.2 Build Files -=============== - -This section describes the files which are created at configure and -build time. These are the files which somebody who builds the package -will see. - - Of course, the developer will also build the package. The -distinction between developer files and build files is not that the -developer does not see the build files, but that somebody who only -builds the package does not have to worry about the developer files. - -* Menu: - -* Build Files Picture:: Build Files Picture. -* Build Files Description:: Build Files Description. - - -File: configure.info, Node: Build Files Picture, Next: Build Files Description, Up: Build Files - -3.2.1 Build Files Picture -------------------------- - -Here is a picture of the files which will be created at build time. -`config.status' is both a created file and a shell script which is run -to create other files, and the picture attempts to show that. - - config.in *configure* Makefile.in - | | | - | v | - | config.status | - | | | - *config.status*<======+==========>*config.status* - | | - v v - config.h Makefile - - -File: configure.info, Node: Build Files Description, Prev: Build Files Picture, Up: Build Files - -3.2.2 Build Files Description ------------------------------ - -This is a description of the files which are created at build time. - -`config.status' - The first step in building a package is to run the `configure' - script. The `configure' script will create the file - `config.status', which is itself a shell script. When you first - run `configure', it will automatically run `config.status'. An - `Makefile' derived from an automake generated `Makefile.in' will - contain rules to automatically run `config.status' again when - necessary to recreate certain files if their inputs change. - -`Makefile' - This is the file which make will read to build the program. The - `config.status' script will transform `Makefile.in' into - `Makefile'. - -`config.h' - This file defines C preprocessor macros which C code can use to - adjust its behaviour on different systems. The `config.status' - script will transform `config.in' into `config.h'. - -`config.cache' - This file did not fit neatly into the picture, and I omitted it. - It is used by the `configure' script to cache results between - runs. This can be an important speedup. If you modify - `configure.in' in such a way that the results of old tests should - change (perhaps you have added a new library to `LDFLAGS'), then - you will have to remove `config.cache' to force the tests to be - rerun. - - The autoconf manual explains how to set up a site specific cache - file. This can speed up running `configure' scripts on your - system. - -`stamp.h' - This file, which I omitted from the picture, is similar to - `stamp-h.in'. It is used as a timestamp file indicating whether - `config.h' is up to date. This is useful since `config.h' depends - upon `config.status', but it is easy for `config.status' to change - in a way which does not affect `config.h'. - - -File: configure.info, Node: Support Files, Prev: Build Files, Up: Files - -3.3 Support Files -================= - -The GNU configure and build system requires several support files to be -included with your distribution. You do not normally need to concern -yourself with these. If you are using the Cygnus tree, most are already -present. Otherwise, they will be installed with your source by -`automake' (with the `--add-missing' option) and `libtoolize'. - - You don't have to put the support files in the top level directory. -You can put them in a subdirectory, and use the `AC_CONFIG_AUX_DIR' -macro in `configure.in' to tell `automake' and the `configure' script -where they are. - - In this section, I describe the support files, so that you can know -what they are and why they are there. - -`ABOUT-NLS' - Added by automake if you are using gettext. This is a - documentation file about the gettext project. - -`ansi2knr.c' - Used by an automake generated `Makefile' if you put `ansi2knr' in - `AUTOMAKE_OPTIONS' in `Makefile.am'. This permits compiling ANSI - C code with a K&R C compiler. - -`ansi2knr.1' - The man page which goes with `ansi2knr.c'. - -`config.guess' - A shell script which determines the configuration name for the - system on which it is run. - -`config.sub' - A shell script which canonicalizes a configuration name entered by - a user. - -`elisp-comp' - Used to compile Emacs LISP files. - -`install-sh' - A shell script which installs a program. This is used if the - configure script can not find an install binary. - -`ltconfig' - Used by libtool. This is a shell script which configures libtool - for the particular system on which it is used. - -`ltmain.sh' - Used by libtool. This is the actual libtool script which is used, - after it is configured by `ltconfig' to build a library. - -`mdate-sh' - A shell script used by an automake generated `Makefile' to pretty - print the modification time of a file. This is used to maintain - version numbers for texinfo files. - -`missing' - A shell script used if some tool is missing entirely. This is - used by an automake generated `Makefile' to avoid certain sorts of - timestamp problems. - -`mkinstalldirs' - A shell script which creates a directory, including all parent - directories. This is used by an automake generated `Makefile' - during installation. - -`texinfo.tex' - Required if you have any texinfo files. This is used when - converting Texinfo files into DVI using `texi2dvi' and TeX. - -`ylwrap' - A shell script used by an automake generated `Makefile' to run - programs like `bison', `yacc', `flex', and `lex'. These programs - default to producing output files with a fixed name, and the - `ylwrap' script runs them in a subdirectory to avoid file name - conflicts when using a parallel make program. - - -File: configure.info, Node: Configuration Names, Next: Cross Compilation Tools, Prev: Files, Up: Top - -4 Configuration Names -********************* - -The GNU configure system names all systems using a "configuration -name". All such names used to be triplets (they may now contain four -parts in certain cases), and the term "configuration triplet" is still -seen. - -* Menu: - -* Configuration Name Definition:: Configuration Name Definition. -* Using Configuration Names:: Using Configuration Names. - - -File: configure.info, Node: Configuration Name Definition, Next: Using Configuration Names, Up: Configuration Names - -4.1 Configuration Name Definition -================================= - -This is a string of the form CPU-MANUFACTURER-OPERATING_SYSTEM. In -some cases, this is extended to a four part form: -CPU-MANUFACTURER-KERNEL-OPERATING_SYSTEM. - - When using a configuration name in a configure option, it is normally -not necessary to specify an entire name. In particular, the -MANUFACTURER field is often omitted, leading to strings such as -`i386-linux' or `sparc-sunos'. The shell script `config.sub' will -translate these shortened strings into the canonical form. autoconf -will arrange for `config.sub' to be run automatically when it is needed. - - The fields of a configuration name are as follows: - -CPU - The type of processor. This is typically something like `i386' or - `sparc'. More specific variants are used as well, such as - `mipsel' to indicate a little endian MIPS processor. - -MANUFACTURER - A somewhat freeform field which indicates the manufacturer of the - system. This is often simply `unknown'. Other common strings are - `pc' for an IBM PC compatible system, or the name of a workstation - vendor, such as `sun'. - -OPERATING_SYSTEM - The name of the operating system which is run on the system. This - will be something like `solaris2.5' or `irix6.3'. There is no - particular restriction on the version number, and strings like - `aix4.1.4.0' are seen. For an embedded system, which has no - operating system, this field normally indicates the type of object - file format, such as `elf' or `coff'. - -KERNEL - This is used mainly for GNU/Linux. A typical GNU/Linux - configuration name is `i586-pc-linux-gnulibc1'. In this case the - kernel, `linux', is separated from the operating system, - `gnulibc1'. - - The shell script `config.guess' will normally print the correct -configuration name for the system on which it is run. It does by -running `uname' and by examining other characteristics of the system. - - Because `config.guess' can normally determine the configuration name -for a machine, it is normally only necessary to specify a configuration -name when building a cross-compiler or when building using a -cross-compiler. - - -File: configure.info, Node: Using Configuration Names, Prev: Configuration Name Definition, Up: Configuration Names - -4.2 Using Configuration Names -============================= - -A configure script will sometimes have to make a decision based on a -configuration name. You will need to do this if you have to compile -code differently based on something which can not be tested using a -standard autoconf feature test. - - It is normally better to test for particular features, rather than to -test for a particular system. This is because as Unix evolves, -different systems copy features from one another. Even if you need to -determine whether the feature is supported based on a configuration -name, you should define a macro which describes the feature, rather than -defining a macro which describes the particular system you are on. - - Testing for a particular system is normally done using a case -statement in `configure.in'. The case statement might look something -like the following, assuming that `host' is a shell variable holding a -canonical configuration name (which will be the case if `configure.in' -uses the `AC_CANONICAL_HOST' or `AC_CANONICAL_SYSTEM' macro). - - case "${host}" in - i[3-7]86-*-linux-gnu*) do something ;; - sparc*-sun-solaris2.[56789]*) do something ;; - sparc*-sun-solaris*) do something ;; - mips*-*-elf*) do something ;; - esac - - It is particularly important to use `*' after the operating system -field, in order to match the version number which will be generated by -`config.guess'. - - In most cases you must be careful to match a range of processor -types. For most processor families, a trailing `*' suffices, as in -`mips*' above. For the i386 family, something along the lines of -`i[3-7]86' suffices at present. For the m68k family, you will need -something like `m68*'. Of course, if you do not need to match on the -processor, it is simpler to just replace the entire field by a `*', as -in `*-*-irix*'. - - -File: configure.info, Node: Cross Compilation Tools, Next: Canadian Cross, Prev: Configuration Names, Up: Top - -5 Cross Compilation Tools -************************* - -The GNU configure and build system can be used to build "cross -compilation" tools. A cross compilation tool is a tool which runs on -one system and produces code which runs on another system. - -* Menu: - -* Cross Compilation Concepts:: Cross Compilation Concepts. -* Host and Target:: Host and Target. -* Using the Host Type:: Using the Host Type. -* Specifying the Target:: Specifying the Target. -* Using the Target Type:: Using the Target Type. -* Cross Tools in the Cygnus Tree:: Cross Tools in the Cygnus Tree - - -File: configure.info, Node: Cross Compilation Concepts, Next: Host and Target, Up: Cross Compilation Tools - -5.1 Cross Compilation Concepts -============================== - -A compiler which produces programs which run on a different system is a -cross compilation compiler, or simply a "cross compiler". Similarly, -we speak of cross assemblers, cross linkers, etc. - - In the normal case, a compiler produces code which runs on the same -system as the one on which the compiler runs. When it is necessary to -distinguish this case from the cross compilation case, such a compiler -is called a "native compiler". Similarly, we speak of native -assemblers, etc. - - Although the debugger is not strictly speaking a compilation tool, -it is nevertheless meaningful to speak of a cross debugger: a debugger -which is used to debug code which runs on another system. Everything -that is said below about configuring cross compilation tools applies to -the debugger as well. - - -File: configure.info, Node: Host and Target, Next: Using the Host Type, Prev: Cross Compilation Concepts, Up: Cross Compilation Tools - -5.2 Host and Target -=================== - -When building cross compilation tools, there are two different systems -involved: the system on which the tools will run, and the system for -which the tools generate code. - - The system on which the tools will run is called the "host" system. - - The system for which the tools generate code is called the "target" -system. - - For example, suppose you have a compiler which runs on a GNU/Linux -system and generates ELF programs for a MIPS embedded system. In this -case the GNU/Linux system is the host, and the MIPS ELF system is the -target. Such a compiler could be called a GNU/Linux cross MIPS ELF -compiler, or, equivalently, a `i386-linux-gnu' cross `mips-elf' -compiler. - - Naturally, most programs are not cross compilation tools. For those -programs, it does not make sense to speak of a target. It only makes -sense to speak of a target for tools like `gcc' or the `binutils' which -actually produce running code. For example, it does not make sense to -speak of the target of a tool like `bison' or `make'. - - Most cross compilation tools can also serve as native tools. For a -native compilation tool, it is still meaningful to speak of a target. -For a native tool, the target is the same as the host. For example, for -a GNU/Linux native compiler, the host is GNU/Linux, and the target is -also GNU/Linux. - - -File: configure.info, Node: Using the Host Type, Next: Specifying the Target, Prev: Host and Target, Up: Cross Compilation Tools - -5.3 Using the Host Type -======================= - -In almost all cases the host system is the system on which you run the -`configure' script, and on which you build the tools (for the case when -they differ, *note Canadian Cross::). - - If your configure script needs to know the configuration name of the -host system, and the package is not a cross compilation tool and -therefore does not have a target, put `AC_CANONICAL_HOST' in -`configure.in'. This macro will arrange to define a few shell -variables when the `configure' script is run. - -`host' - The canonical configuration name of the host. This will normally - be determined by running the `config.guess' shell script, although - the user is permitted to override this by using an explicit - `--host' option. - -`host_alias' - In the unusual case that the user used an explicit `--host' option, - this will be the argument to `--host'. In the normal case, this - will be the same as the `host' variable. - -`host_cpu' -`host_vendor' -`host_os' - The first three parts of the canonical configuration name. - - The shell variables may be used by putting shell code in -`configure.in'. For an example, see *Note Using Configuration Names::. - - -File: configure.info, Node: Specifying the Target, Next: Using the Target Type, Prev: Using the Host Type, Up: Cross Compilation Tools - -5.4 Specifying the Target -========================= - -By default, the `configure' script will assume that the target is the -same as the host. This is the more common case; for example, it leads -to a native compiler rather than a cross compiler. - - If you want to build a cross compilation tool, you must specify the -target explicitly by using the `--target' option when you run -`configure'. The argument to `--target' is the configuration name of -the system for which you wish to generate code. *Note Configuration -Names::. - - For example, to build tools which generate code for a MIPS ELF -embedded system, you would use `--target mips-elf'. - - -File: configure.info, Node: Using the Target Type, Next: Cross Tools in the Cygnus Tree, Prev: Specifying the Target, Up: Cross Compilation Tools - -5.5 Using the Target Type -========================= - -When writing `configure.in' for a cross compilation tool, you will need -to use information about the target. To do this, put -`AC_CANONICAL_SYSTEM' in `configure.in'. - - `AC_CANONICAL_SYSTEM' will look for a `--target' option and -canonicalize it using the `config.sub' shell script. It will also run -`AC_CANONICAL_HOST' (*note Using the Host Type::). - - The target type will be recorded in the following shell variables. -Note that the host versions of these variables will also be defined by -`AC_CANONICAL_HOST'. - -`target' - The canonical configuration name of the target. - -`target_alias' - The argument to the `--target' option. If the user did not specify - a `--target' option, this will be the same as `host_alias'. - -`target_cpu' -`target_vendor' -`target_os' - The first three parts of the canonical target configuration name. - - Note that if `host' and `target' are the same string, you can assume -a native configuration. If they are different, you can assume a cross -configuration. - - It is arguably possible for `host' and `target' to represent the -same system, but for the strings to not be identical. For example, if -`config.guess' returns `sparc-sun-sunos4.1.4', and somebody configures -with `--target sparc-sun-sunos4.1', then the slight differences between -the two versions of SunOS may be unimportant for your tool. However, -in the general case it can be quite difficult to determine whether the -differences between two configuration names are significant or not. -Therefore, by convention, if the user specifies a `--target' option -without specifying a `--host' option, it is assumed that the user wants -to configure a cross compilation tool. - - The variables `target' and `target_alias' should be handled -differently. - - In general, whenever the user may actually see a string, -`target_alias' should be used. This includes anything which may appear -in the file system, such as a directory name or part of a tool name. -It also includes any tool output, unless it is clearly labelled as the -canonical target configuration name. This permits the user to use the -`--target' option to specify how the tool will appear to the outside -world. - - On the other hand, when checking for characteristics of the target -system, `target' should be used. This is because a wide variety of -`--target' options may map into the same canonical configuration name. -You should not attempt to duplicate the canonicalization done by -`config.sub' in your own code. - - By convention, cross tools are installed with a prefix of the -argument used with the `--target' option, also known as `target_alias' -(*note Using the Target Type::). If the user does not use the -`--target' option, and thus is building a native tool, no prefix is -used. - - For example, if gcc is configured with `--target mips-elf', then the -installed binary will be named `mips-elf-gcc'. If gcc is configured -without a `--target' option, then the installed binary will be named -`gcc'. - - The autoconf macro `AC_ARG_PROGRAM' will handle this for you. If -you are using automake, no more need be done; the programs will -automatically be installed with the correct prefixes. Otherwise, see -the autoconf documentation for `AC_ARG_PROGRAM'. - - -File: configure.info, Node: Cross Tools in the Cygnus Tree, Prev: Using the Target Type, Up: Cross Compilation Tools - -5.6 Cross Tools in the Cygnus Tree -================================== - -The Cygnus tree is used for various packages including gdb, the GNU -binutils, and egcs. It is also, of course, used for Cygnus releases. - - In the Cygnus tree, the top level `configure' script uses the old -Cygnus configure system, not autoconf. The top level `Makefile.in' is -written to build packages based on what is in the source tree, and -supports building a large number of tools in a single -`configure'/`make' step. - - The Cygnus tree may be configured with a `--target' option. The -`--target' option applies recursively to every subdirectory, and -permits building an entire set of cross tools at once. - -* Menu: - -* Host and Target Libraries:: Host and Target Libraries. -* Target Library Configure Scripts:: Target Library Configure Scripts. -* Make Targets in Cygnus Tree:: Make Targets in Cygnus Tree. -* Target libiberty:: Target libiberty - - -File: configure.info, Node: Host and Target Libraries, Next: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree - -5.6.1 Host and Target Libraries -------------------------------- - -The Cygnus tree distinguishes host libraries from target libraries. - - Host libraries are built with the compiler used to build the programs -which run on the host, which is called the host compiler. This includes -libraries such as `bfd' and `tcl'. These libraries are built with the -host compiler, and are linked into programs like the binutils or gcc -which run on the host. - - Target libraries are built with the target compiler. If gcc is -present in the source tree, then the target compiler is the gcc that is -built using the host compiler. Target libraries are libraries such as -`newlib' and `libstdc++'. These libraries are not linked into the host -programs, but are instead made available for use with programs built -with the target compiler. - - For the rest of this section, assume that gcc is present in the -source tree, so that it will be used to build the target libraries. - - There is a complication here. The configure process needs to know -which compiler you are going to use to build a tool; otherwise, the -feature tests will not work correctly. The Cygnus tree handles this by -not configuring the target libraries until the target compiler is -built. In order to permit everything to build using a single -`configure'/`make', the configuration of the target libraries is -actually triggered during the make step. - - When the target libraries are configured, the `--target' option is -not used. Instead, the `--host' option is used with the argument of -the `--target' option for the overall configuration. If no `--target' -option was used for the overall configuration, the `--host' option will -be passed with the output of the `config.guess' shell script. Any -`--build' option is passed down unchanged. - - This translation of configuration options is done because since the -target libraries are compiled with the target compiler, they are being -built in order to run on the target of the overall configuration. By -the definition of host, this means that their host system is the same as -the target system of the overall configuration. - - The same process is used for both a native configuration and a cross -configuration. Even when using a native configuration, the target -libraries will be configured and built using the newly built compiler. -This is particularly important for the C++ libraries, since there is no -reason to assume that the C++ compiler used to build the host tools (if -there even is one) uses the same ABI as the g++ compiler which will be -used to build the target libraries. - - There is one difference between a native configuration and a cross -configuration. In a native configuration, the target libraries are -normally configured and built as siblings of the host tools. In a cross -configuration, the target libraries are normally built in a subdirectory -whose name is the argument to `--target'. This is mainly for -historical reasons. - - To summarize, running `configure' in the Cygnus tree configures all -the host libraries and tools, but does not configure any of the target -libraries. Running `make' then does the following steps: - - * Build the host libraries. - - * Build the host programs, including gcc. Note that we call gcc - both a host program (since it runs on the host) and a target - compiler (since it generates code for the target). - - * Using the newly built target compiler, configure the target - libraries. - - * Build the target libraries. - - The steps need not be done in precisely this order, since they are -actually controlled by `Makefile' targets. - - -File: configure.info, Node: Target Library Configure Scripts, Next: Make Targets in Cygnus Tree, Prev: Host and Target Libraries, Up: Cross Tools in the Cygnus Tree - -5.6.2 Target Library Configure Scripts --------------------------------------- - -There are a few things you must know in order to write a configure -script for a target library. This is just a quick sketch, and beginners -shouldn't worry if they don't follow everything here. - - The target libraries are configured and built using a newly built -target compiler. There may not be any startup files or libraries for -this target compiler. In fact, those files will probably be built as -part of some target library, which naturally means that they will not -exist when your target library is configured. - - This means that the configure script for a target library may not use -any test which requires doing a link. This unfortunately includes many -useful autoconf macros, such as `AC_CHECK_FUNCS'. autoconf macros -which do a compile but not a link, such as `AC_CHECK_HEADERS', may be -used. - - This is a severe restriction, but normally not a fatal one, as target -libraries can often assume the presence of other target libraries, and -thus know which functions will be available. - - As of this writing, the autoconf macro `AC_PROG_CC' does a link to -make sure that the compiler works. This may fail in a target library, -so target libraries must use a different set of macros to locate the -compiler. See the `configure.in' file in a directory like `libiberty' -or `libgloss' for an example. - - As noted in the previous section, target libraries are sometimes -built in directories which are siblings to the host tools, and are -sometimes built in a subdirectory. The `--with-target-subdir' configure -option will be passed when the library is configured. Its value will be -an empty string if the target library is a sibling. Its value will be -the name of the subdirectory if the target library is in a subdirectory. - - If the overall build is not a native build (i.e., the overall -configure used the `--target' option), then the library will be -configured with the `--with-cross-host' option. The value of this -option will be the host system of the overall build. Recall that the -host system of the library will be the target of the overall build. If -the overall build is a native build, the `--with-cross-host' option -will not be used. - - A library which can be built both standalone and as a target library -may want to install itself into different directories depending upon the -case. When built standalone, or when built native, the library should -be installed in `$(libdir)'. When built as a target library which is -not native, the library should be installed in `$(tooldir)/lib'. The -`--with-cross-host' option may be used to distinguish these cases. - - This same test of `--with-cross-host' may be used to see whether it -is OK to use link tests in the configure script. If the -`--with-cross-host' option is not used, then the library is being built -either standalone or native, and a link should work. - - -File: configure.info, Node: Make Targets in Cygnus Tree, Next: Target libiberty, Prev: Target Library Configure Scripts, Up: Cross Tools in the Cygnus Tree - -5.6.3 Make Targets in Cygnus Tree ---------------------------------- - -The top level `Makefile' in the Cygnus tree defines targets for every -known subdirectory. - - For every subdirectory DIR which holds a host library or program, -the `Makefile' target `all-DIR' will build that library or program. - - There are dependencies among host tools. For example, building gcc -requires first building gas, because the gcc build process invokes the -target assembler. These dependencies are reflected in the top level -`Makefile'. - - For every subdirectory DIR which holds a target library, the -`Makefile' target `configure-target-DIR' will configure that library. -The `Makefile' target `all-target-DIR' will build that library. - - Every `configure-target-DIR' target depends upon `all-gcc', since -gcc, the target compiler, is required to configure the tool. Every -`all-target-DIR' target depends upon the corresponding -`configure-target-DIR' target. - - There are several other targets which may be of interest for each -directory: `install-DIR', `clean-DIR', and `check-DIR'. There are also -corresponding `target' versions of these for the target libraries , -such as `install-target-DIR'. - - -File: configure.info, Node: Target libiberty, Prev: Make Targets in Cygnus Tree, Up: Cross Tools in the Cygnus Tree - -5.6.4 Target libiberty ----------------------- - -The `libiberty' subdirectory is currently a special case, in that it is -the only directory which is built both using the host compiler and -using the target compiler. - - This is because the files in `libiberty' are used when building the -host tools, and they are also incorporated into the `libstdc++' target -library as support code. - - This duality does not pose any particular difficulties. It means -that there are targets for both `all-libiberty' and -`all-target-libiberty'. - - In a native configuration, when target libraries are not built in a -subdirectory, the same objects are normally used as both the host build -and the target build. This is normally OK, since libiberty contains -only C code, and in a native configuration the results of the host -compiler and the target compiler are normally interoperable. - - Irix 6 is again an exception here, since the SGI native compiler -defaults to using the `O32' ABI, and gcc defaults to using the `N32' -ABI. On Irix 6, the target libraries are built in a subdirectory even -for a native configuration, avoiding this problem. - - There are currently no other libraries built for both the host and -the target, but there is no conceptual problem with adding more. - - -File: configure.info, Node: Canadian Cross, Next: Cygnus Configure, Prev: Cross Compilation Tools, Up: Top - -6 Canadian Cross -**************** - -It is possible to use the GNU configure and build system to build a -program which will run on a system which is different from the system on -which the tools are built. In other words, it is possible to build -programs using a cross compiler. - - This is referred to as a "Canadian Cross". - -* Menu: - -* Canadian Cross Example:: Canadian Cross Example. -* Canadian Cross Concepts:: Canadian Cross Concepts. -* Build Cross Host Tools:: Build Cross Host Tools. -* Build and Host Options:: Build and Host Options. -* CCross not in Cygnus Tree:: Canadian Cross not in Cygnus Tree. -* CCross in Cygnus Tree:: Canadian Cross in Cygnus Tree. -* Supporting Canadian Cross:: Supporting Canadian Cross. - - -File: configure.info, Node: Canadian Cross Example, Next: Canadian Cross Concepts, Up: Canadian Cross - -6.1 Canadian Cross Example -========================== - -Here is an example of a Canadian Cross. - - While running on a GNU/Linux, you can build a program which will run -on a Solaris system. You would use a GNU/Linux cross Solaris compiler -to build the program. - - Of course, you could not run the resulting program on your GNU/Linux -system. You would have to copy it over to a Solaris system before you -would run it. - - Of course, you could also simply build the programs on the Solaris -system in the first place. However, perhaps the Solaris system is not -available for some reason; perhaps you actually don't have one, but you -want to build the tools for somebody else to use. Or perhaps your -GNU/Linux system is much faster than your Solaris system. - - A Canadian Cross build is most frequently used when building -programs to run on a non-Unix system, such as DOS or Windows. It may -be simpler to configure and build on a Unix system than to support the -configuration machinery on a non-Unix system. - - -File: configure.info, Node: Canadian Cross Concepts, Next: Build Cross Host Tools, Prev: Canadian Cross Example, Up: Canadian Cross - -6.2 Canadian Cross Concepts -=========================== - -When building a Canadian Cross, there are at least two different systems -involved: the system on which the tools are being built, and the system -on which the tools will run. - - The system on which the tools are being built is called the "build" -system. - - The system on which the tools will run is called the host system. - - For example, if you are building a Solaris program on a GNU/Linux -system, as in the previous section, the build system would be GNU/Linux, -and the host system would be Solaris. - - It is, of course, possible to build a cross compiler using a Canadian -Cross (i.e., build a cross compiler using a cross compiler). In this -case, the system for which the resulting cross compiler generates code -is called the target system. (For a more complete discussion of host -and target systems, *note Host and Target::). - - An example of building a cross compiler using a Canadian Cross would -be building a Windows cross MIPS ELF compiler on a GNU/Linux system. In -this case the build system would be GNU/Linux, the host system would be -Windows, and the target system would be MIPS ELF. - - The name Canadian Cross comes from the case when the build, host, and -target systems are all different. At the time that these issues were -all being hashed out, Canada had three national political parties. - - -File: configure.info, Node: Build Cross Host Tools, Next: Build and Host Options, Prev: Canadian Cross Concepts, Up: Canadian Cross - -6.3 Build Cross Host Tools -========================== - -In order to configure a program for a Canadian Cross build, you must -first build and install the set of cross tools you will use to build the -program. - - These tools will be build cross host tools. That is, they will run -on the build system, and will produce code that runs on the host system. - - It is easy to confuse the meaning of build and host here. Always -remember that the build system is where you are doing the build, and the -host system is where the resulting program will run. Therefore, you -need a build cross host compiler. - - In general, you must have a complete cross environment in order to do -the build. This normally means a cross compiler, cross assembler, and -so forth, as well as libraries and include files for the host system. - - -File: configure.info, Node: Build and Host Options, Next: CCross not in Cygnus Tree, Prev: Build Cross Host Tools, Up: Canadian Cross - -6.4 Build and Host Options -========================== - -When you run `configure', you must use both the `--build' and `--host' -options. - - The `--build' option is used to specify the configuration name of -the build system. This can normally be the result of running the -`config.guess' shell script, and it is reasonable to use -`--build=`config.guess`'. - - The `--host' option is used to specify the configuration name of the -host system. - - As we explained earlier, `config.guess' is used to set the default -value for the `--host' option (*note Using the Host Type::). We can -now see that since `config.guess' returns the type of system on which -it is run, it really identifies the build system. Since the host -system is normally the same as the build system (i.e., people do not -normally build using a cross compiler), it is reasonable to use the -result of `config.guess' as the default for the host system when the -`--host' option is not used. - - It might seem that if the `--host' option were used without the -`--build' option that the configure script could run `config.guess' to -determine the build system, and presume a Canadian Cross if the result -of `config.guess' differed from the `--host' option. However, for -historical reasons, some configure scripts are routinely run using an -explicit `--host' option, rather than using the default from -`config.guess'. As noted earlier, it is difficult or impossible to -reliably compare configuration names (*note Using the Target Type::). -Therefore, by convention, if the `--host' option is used, but the -`--build' option is not used, then the build system defaults to the -host system. - - -File: configure.info, Node: CCross not in Cygnus Tree, Next: CCross in Cygnus Tree, Prev: Build and Host Options, Up: Canadian Cross - -6.5 Canadian Cross not in Cygnus Tree. -====================================== - -If you are not using the Cygnus tree, you must explicitly specify the -cross tools which you want to use to build the program. This is done by -setting environment variables before running the `configure' script. - - You must normally set at least the environment variables `CC', `AR', -and `RANLIB' to the cross tools which you want to use to build. - - For some programs, you must set additional cross tools as well, such -as `AS', `LD', or `NM'. - - You would set these environment variables to the build cross tools -which you are going to use. - - For example, if you are building a Solaris program on a GNU/Linux -system, and your GNU/Linux cross Solaris compiler were named -`solaris-gcc', then you would set the environment variable `CC' to -`solaris-gcc'. - - -File: configure.info, Node: CCross in Cygnus Tree, Next: Supporting Canadian Cross, Prev: CCross not in Cygnus Tree, Up: Canadian Cross - -6.6 Canadian Cross in Cygnus Tree -================================= - -This section describes configuring and building a Canadian Cross when -using the Cygnus tree. - -* Menu: - -* Standard Cygnus CCross:: Building a Normal Program. -* Cross Cygnus CCross:: Building a Cross Program. - - -File: configure.info, Node: Standard Cygnus CCross, Next: Cross Cygnus CCross, Up: CCross in Cygnus Tree - -6.6.1 Building a Normal Program -------------------------------- - -When configuring a Canadian Cross in the Cygnus tree, all the -appropriate environment variables are automatically set to `HOST-TOOL', -where HOST is the value used for the `--host' option, and TOOL is the -name of the tool (e.g., `gcc', `as', etc.). These tools must be on -your `PATH'. - - Adding a prefix of HOST will give the usual name for the build cross -host tools. To see this, consider that when these cross tools were -built, they were configured to run on the build system and to produce -code for the host system. That is, they were configured with a -`--target' option that is the same as the system which we are now -calling the host. Recall that the default name for installed cross -tools uses the target system as a prefix (*note Using the Target -Type::). Since that is the system which we are now calling the host, -HOST is the right prefix to use. - - For example, if you configure with `--build=i386-linux-gnu' and -`--host=solaris', then the Cygnus tree will automatically default to -using the compiler `solaris-gcc'. You must have previously built and -installed this compiler, probably by doing a build with no `--host' -option and with a `--target' option of `solaris'. - - -File: configure.info, Node: Cross Cygnus CCross, Prev: Standard Cygnus CCross, Up: CCross in Cygnus Tree - -6.6.2 Building a Cross Program ------------------------------- - -There are additional considerations if you want to build a cross -compiler, rather than a native compiler, in the Cygnus tree using a -Canadian Cross. - - When you build a cross compiler using the Cygnus tree, then the -target libraries will normally be built with the newly built target -compiler (*note Host and Target Libraries::). However, this will not -work when building with a Canadian Cross. This is because the newly -built target compiler will be a program which runs on the host system, -and therefore will not be able to run on the build system. - - Therefore, when building a cross compiler with the Cygnus tree, you -must first install a set of build cross target tools. These tools will -be used when building the target libraries. - - Note that this is not a requirement of a Canadian Cross in general. -For example, it would be possible to build just the host cross target -tools on the build system, to copy the tools to the host system, and to -build the target libraries on the host system. The requirement for -build cross target tools is imposed by the Cygnus tree, which expects -to be able to build both host programs and target libraries in a single -`configure'/`make' step. Because it builds these in a single step, it -expects to be able to build the target libraries on the build system, -which means that it must use a build cross target toolchain. - - For example, suppose you want to build a Windows cross MIPS ELF -compiler on a GNU/Linux system. You must have previously installed -both a GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF -compiler. - - In order to build the Windows (configuration name `i386-cygwin32') -cross MIPS ELF (configure name `mips-elf') compiler, you might execute -the following commands (long command lines are broken across lines with -a trailing backslash as a continuation character). - - mkdir linux-x-cygwin32 - cd linux-x-cygwin32 - SRCDIR/configure --target i386-cygwin32 --prefix=INSTALLDIR \ - --exec-prefix=INSTALLDIR/H-i386-linux - make - make install - cd .. - mkdir linux-x-mips-elf - cd linux-x-mips-elf - SRCDIR/configure --target mips-elf --prefix=INSTALLDIR \ - --exec-prefix=INSTALLDIR/H-i386-linux - make - make install - cd .. - mkdir cygwin32-x-mips-elf - cd cygwin32-x-mips-elf - SRCDIR/configure --build=i386-linux-gnu --host=i386-cygwin32 \ - --target=mips-elf --prefix=WININSTALLDIR \ - --exec-prefix=WININSTALLDIR/H-i386-cygwin32 - make - make install - - You would then copy the contents of WININSTALLDIR over to the -Windows machine, and run the resulting programs. - - -File: configure.info, Node: Supporting Canadian Cross, Prev: CCross in Cygnus Tree, Up: Canadian Cross - -6.7 Supporting Canadian Cross -============================= - -If you want to make it possible to build a program you are developing -using a Canadian Cross, you must take some care when writing your -configure and make rules. Simple cases will normally work correctly. -However, it is not hard to write configure and make tests which will -fail in a Canadian Cross. - -* Menu: - -* CCross in Configure:: Supporting Canadian Cross in Configure Scripts. -* CCross in Make:: Supporting Canadian Cross in Makefiles. - - -File: configure.info, Node: CCross in Configure, Next: CCross in Make, Up: Supporting Canadian Cross - -6.7.1 Supporting Canadian Cross in Configure Scripts ----------------------------------------------------- - -In a `configure.in' file, after calling `AC_PROG_CC', you can find out -whether this is a Canadian Cross configure by examining the shell -variable `cross_compiling'. In a Canadian Cross, which means that the -compiler is a cross compiler, `cross_compiling' will be `yes'. In a -normal configuration, `cross_compiling' will be `no'. - - You ordinarily do not need to know the type of the build system in a -configure script. However, if you do need that information, you can get -it by using the macro `AC_CANONICAL_SYSTEM', the same macro that is -used to determine the target system. This macro will set the variables -`build', `build_alias', `build_cpu', `build_vendor', and `build_os', -which correspond to the similar `target' and `host' variables, except -that they describe the build system. - - When writing tests in `configure.in', you must remember that you -want to test the host environment, not the build environment. - - Macros like `AC_CHECK_FUNCS' which use the compiler will test the -host environment. That is because the tests will be done by running the -compiler, which is actually a build cross host compiler. If the -compiler can find the function, that means that the function is present -in the host environment. - - Tests like `test -f /dev/ptyp0', on the other hand, will test the -build environment. Remember that the configure script is running on the -build system, not the host system. If your configure scripts examines -files, those files will be on the build system. Whatever you determine -based on those files may or may not be the case on the host system. - - Most autoconf macros will work correctly for a Canadian Cross. The -main exception is `AC_TRY_RUN'. This macro tries to compile and run a -test program. This will fail in a Canadian Cross, because the program -will be compiled for the host system, which means that it will not run -on the build system. - - The `AC_TRY_RUN' macro provides an optional argument to tell the -configure script what to do in a Canadian Cross. If that argument is -not present, you will get a warning when you run `autoconf': - warning: AC_TRY_RUN called without default to allow cross compiling - This tells you that the resulting `configure' script will not work -with a Canadian Cross. - - In some cases while it may better to perform a test at configure -time, it is also possible to perform the test at run time. In such a -case you can use the cross compiling argument to `AC_TRY_RUN' to tell -your program that the test could not be performed at configure time. - - There are a few other autoconf macros which will not work correctly -with a Canadian Cross: a partial list is `AC_FUNC_GETPGRP', -`AC_FUNC_SETPGRP', `AC_FUNC_SETVBUF_REVERSED', and -`AC_SYS_RESTARTABLE_SYSCALLS'. The `AC_CHECK_SIZEOF' macro is -generally not very useful with a Canadian Cross; it permits an optional -argument indicating the default size, but there is no way to know what -the correct default should be. - - -File: configure.info, Node: CCross in Make, Prev: CCross in Configure, Up: Supporting Canadian Cross - -6.7.2 Supporting Canadian Cross in Makefiles. ---------------------------------------------- - -The main Canadian Cross issue in a `Makefile' arises when you want to -use a subsidiary program to generate code or data which you will then -include in your real program. - - If you compile this subsidiary program using `$(CC)' in the usual -way, you will not be able to run it. This is because `$(CC)' will -build a program for the host system, but the program is being built on -the build system. - - You must instead use a compiler for the build system, rather than the -host system. In the Cygnus tree, this make variable `$(CC_FOR_BUILD)' -will hold a compiler for the build system. - - Note that you should not include `config.h' in a file you are -compiling with `$(CC_FOR_BUILD)'. The `configure' script will build -`config.h' with information for the host system. However, you are -compiling the file using a compiler for the build system (a native -compiler). Subsidiary programs are normally simple filters which do no -user interaction, and it is normally possible to write them in a highly -portable fashion so that the absence of `config.h' is not crucial. - - The gcc `Makefile.in' shows a complex situation in which certain -files, such as `rtl.c', must be compiled into both subsidiary programs -run on the build system and into the final program. This approach may -be of interest for advanced build system hackers. Note that the build -system compiler is rather confusingly called `HOST_CC'. - - -File: configure.info, Node: Cygnus Configure, Next: Multilibs, Prev: Canadian Cross, Up: Top - -7 Cygnus Configure -****************** - -The Cygnus configure script predates autoconf. All of its interesting -features have been incorporated into autoconf. No new programs should -be written to use the Cygnus configure script. - - However, the Cygnus configure script is still used in a few places: -at the top of the Cygnus tree and in a few target libraries in the -Cygnus tree. Until those uses have been replaced with autoconf, some -brief notes are appropriate here. This is not complete documentation, -but it should be possible to use this as a guide while examining the -scripts themselves. - -* Menu: - -* Cygnus Configure Basics:: Cygnus Configure Basics. -* Cygnus Configure in C++ Libraries:: Cygnus Configure in C++ Libraries. - - -File: configure.info, Node: Cygnus Configure Basics, Next: Cygnus Configure in C++ Libraries, Up: Cygnus Configure - -7.1 Cygnus Configure Basics -=========================== - -Cygnus configure does not use any generated files; there is no program -corresponding to `autoconf'. Instead, there is a single shell script -named `configure' which may be found at the top of the Cygnus tree. -This shell script was written by hand; it was not generated by -autoconf, and it is incorrect, and indeed harmful, to run `autoconf' in -the top level of a Cygnus tree. - - Cygnus configure works in a particular directory by examining the -file `configure.in' in that directory. That file is broken into four -separate shell scripts. - - The first is the contents of `configure.in' up to a line that starts -with `# per-host:'. This is the common part. - - The second is the rest of `configure.in' up to a line that starts -with `# per-target:'. This is the per host part. - - The third is the rest of `configure.in' up to a line that starts -with `# post-target:'. This is the per target part. - - The fourth is the remainder of `configure.in'. This is the post -target part. - - If any of these comment lines are missing, the corresponding shell -script is empty. - - Cygnus configure will first execute the common part. This must set -the shell variable `srctrigger' to the name of a source file, to -confirm that Cygnus configure is looking at the right directory. This -may set the shell variables `package_makefile_frag' and -`package_makefile_rules_frag'. - - Cygnus configure will next set the `build' and `host' shell -variables, and execute the per host part. This may set the shell -variable `host_makefile_frag'. - - Cygnus configure will next set the `target' variable, and execute -the per target part. This may set the shell variable -`target_makefile_frag'. - - Any of these scripts may set the `subdirs' shell variable. This -variable is a list of subdirectories where a `Makefile.in' file may be -found. Cygnus configure will automatically look for a `Makefile.in' -file in the current directory. The `subdirs' shell variable is not -normally used, and I believe that the only directory which uses it at -present is `newlib'. - - For each `Makefile.in', Cygnus configure will automatically create a -`Makefile' by adding definitions for `make' variables such as `host' -and `target', and automatically editing the values of `make' variables -such as `prefix' if they are present. - - Also, if any of the `makefile_frag' shell variables are set, Cygnus -configure will interpret them as file names relative to either the -working directory or the source directory, and will read the contents of -the file into the generated `Makefile'. The file contents will be read -in after the first line in `Makefile.in' which starts with `####'. - - These `Makefile' fragments are used to customize behaviour for a -particular host or target. They serve to select particular files to -compile, and to define particular preprocessor macros by providing -values for `make' variables which are then used during compilation. -Cygnus configure, unlike autoconf, normally does not do feature tests, -and normally requires support to be added manually for each new host. - - The `Makefile' fragment support is similar to the autoconf -`AC_SUBST_FILE' macro. - - After creating each `Makefile', the post target script will be run -(i.e., it may be run several times). This script may further customize -the `Makefile'. When it is run, the shell variable `Makefile' will -hold the name of the `Makefile', including the appropriate directory -component. - - Like an autoconf generated `configure' script, Cygnus configure will -create a file named `config.status' which, when run, will automatically -recreate the configuration. The `config.status' file will simply -execute the Cygnus configure script again with the appropriate -arguments. - - Any of the parts of `configure.in' may set the shell variables -`files' and `links'. Cygnus configure will set up symlinks from the -names in `links' to the files named in `files'. This is similar to the -autoconf `AC_LINK_FILES' macro. - - Finally, any of the parts of `configure.in' may set the shell -variable `configdirs' to a set of subdirectories. If it is set, Cygnus -configure will recursively run the configure process in each -subdirectory. If the subdirectory uses Cygnus configure, it will -contain a `configure.in' file but no `configure' file, in which case -Cygnus configure will invoke itself recursively. If the subdirectory -has a `configure' file, Cygnus configure assumes that it is an autoconf -generated `configure' script, and simply invokes it directly. - - -File: configure.info, Node: Cygnus Configure in C++ Libraries, Prev: Cygnus Configure Basics, Up: Cygnus Configure - -7.2 Cygnus Configure in C++ Libraries -===================================== - -The C++ library configure system, written by Per Bothner, deserves -special mention. It uses Cygnus configure, but it does feature testing -like that done by autoconf generated `configure' scripts. This -approach is used in the libraries `libio', `libstdc++', and `libg++'. - - Most of the `Makefile' information is written out by the shell -script `libio/config.shared'. Each `configure.in' file sets certain -shell variables, and then invokes `config.shared' to create two package -`Makefile' fragments. These fragments are then incorporated into the -resulting `Makefile' by the Cygnus configure script. - - The file `_G_config.h' is created in the `libio' object directory by -running the shell script `libio/gen-params'. This shell script uses -feature tests to define macros and typedefs in `_G_config.h'. - - -File: configure.info, Node: Multilibs, Next: FAQ, Prev: Cygnus Configure, Up: Top - -8 Multilibs -*********** - -For some targets gcc may have different processor requirements depending -upon command line options. An obvious example is the `-msoft-float' -option supported on several processors. This option means that the -floating point registers are not available, which means that floating -point operations must be done by calling an emulation subroutine rather -than by using machine instructions. - - For such options, gcc is often configured to compile target libraries -twice: once with `-msoft-float' and once without. When gcc compiles -target libraries more than once, the resulting libraries are called -"multilibs". - - Multilibs are not really part of the GNU configure and build system, -but we discuss them here since they require support in the `configure' -scripts and `Makefile's used for target libraries. - -* Menu: - -* Multilibs in gcc:: Multilibs in gcc. -* Multilibs in Target Libraries:: Multilibs in Target Libraries. - - -File: configure.info, Node: Multilibs in gcc, Next: Multilibs in Target Libraries, Up: Multilibs - -8.1 Multilibs in gcc -==================== - -In gcc, multilibs are defined by setting the variable -`MULTILIB_OPTIONS' in the target `Makefile' fragment. Several other -`MULTILIB' variables may also be defined there. *Note The Target -Makefile Fragment: (gcc)Target Fragment. - - If you have built gcc, you can see what multilibs it uses by running -it with the `-print-multi-lib' option. The output `.;' means that no -multilibs are used. In general, the output is a sequence of lines, one -per multilib. The first part of each line, up to the `;', is the name -of the multilib directory. The second part is a list of compiler -options separated by `@' characters. - - Multilibs are built in a tree of directories. The top of the tree, -represented by `.' in the list of multilib directories, is the default -library to use when no special compiler options are used. The -subdirectories of the tree hold versions of the library to use when -particular compiler options are used. - - -File: configure.info, Node: Multilibs in Target Libraries, Prev: Multilibs in gcc, Up: Multilibs - -8.2 Multilibs in Target Libraries -================================= - -The target libraries in the Cygnus tree are automatically built with -multilibs. That means that each library is built multiple times. - - This default is set in the top level `configure.in' file, by adding -`--enable-multilib' to the list of arguments passed to configure when -it is run for the target libraries (*note Host and Target Libraries::). - - Each target library uses the shell script `config-ml.in', written by -Doug Evans, to prepare to build target libraries. This shell script is -invoked after the `Makefile' has been created by the `configure' -script. If multilibs are not enabled, it does nothing, otherwise it -modifies the `Makefile' to support multilibs. - - The `config-ml.in' script makes one copy of the `Makefile' for each -multilib in the appropriate subdirectory. When configuring in the -source directory (which is not recommended), it will build a symlink -tree of the sources in each subdirectory. - - The `config-ml.in' script sets several variables in the various -`Makefile's. The `Makefile.in' must have definitions for these -variables already; `config-ml.in' simply changes the existing values. -The `Makefile' should use default values for these variables which will -do the right thing in the subdirectories. - -`MULTISRCTOP' - `config-ml.in' will set this to a sequence of `../' strings, where - the number of strings is the number of multilib levels in the - source tree. The default value should be the empty string. - -`MULTIBUILDTOP' - `config-ml.in' will set this to a sequence of `../' strings, where - the number of strings is number of multilib levels in the object - directory. The default value should be the empty string. This - will differ from `MULTISRCTOP' when configuring in the source tree - (which is not recommended). - -`MULTIDIRS' - In the top level `Makefile' only, `config-ml.in' will set this to - the list of multilib subdirectories. The default value should be - the empty string. - -`MULTISUBDIR' - `config-ml.in' will set this to the installed subdirectory name to - use for this subdirectory, with a leading `/'. The default value - shold be the empty string. - -`MULTIDO' -`MULTICLEAN' - In the top level `Makefile' only, `config-ml.in' will set these - variables to commands to use when doing a recursive make. These - variables should both default to the string `true', so that by - default nothing happens. - - All references to the parent of the source directory should use the -variable `MULTISRCTOP'. Instead of writing `$(srcdir)/..', you must -write `$(srcdir)/$(MULTISRCTOP)..'. - - Similarly, references to the parent of the object directory should -use the variable `MULTIBUILDTOP'. - - In the installation target, the libraries should be installed in the -subdirectory `MULTISUBDIR'. Instead of installing -`$(libdir)/libfoo.a', install `$(libdir)$(MULTISUBDIR)/libfoo.a'. - - The `config-ml.in' script also modifies the top level `Makefile' to -add `multi-do' and `multi-clean' targets which are used when building -multilibs. - - The default target of the `Makefile' should include the following -command: - @$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do - This assumes that `$(FLAGS_TO_PASS)' is defined as a set of -variables to pass to a recursive invocation of `make'. This will build -all the multilibs. Note that the default value of `MULTIDO' is `true', -so by default this command will do nothing. It will only do something -in the top level `Makefile' if multilibs were enabled. - - The `install' target of the `Makefile' should include the following -command: - @$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do - - In general, any operation, other than clean, which should be -performed on all the multilibs should use a `$(MULTIDO)' line, setting -the variable `DO' to the target of each recursive call to `make'. - - The `clean' targets (`clean', `mostlyclean', etc.) should use -`$(MULTICLEAN)'. For example, the `clean' target should do this: - @$(MULTICLEAN) DO=clean multi-clean - - -File: configure.info, Node: FAQ, Next: Index, Prev: Multilibs, Up: Top - -9 Frequently Asked Questions -**************************** - -Which do I run first, `autoconf' or `automake'? - Except when you first add autoconf or automake support to a - package, you shouldn't run either by hand. Instead, configure - with the `--enable-maintainer-mode' option, and let `make' take - care of it. - -`autoconf' says something about undefined macros. - This means that you have macros in your `configure.in' which are - not defined by `autoconf'. You may be using an old version of - `autoconf'; try building and installing a newer one. Make sure the - newly installled `autoconf' is first on your `PATH'. Also, see - the next question. - -My `configure' script has stuff like `CY_GNU_GETTEXT' in it. - This means that you have macros in your `configure.in' which should - be defined in your `aclocal.m4' file, but aren't. This usually - means that `aclocal' was not able to appropriate definitions of the - macros. Make sure that you have installed all the packages you - need. In particular, make sure that you have installed libtool - (this is where `AM_PROG_LIBTOOL' is defined) and gettext (this is - where `CY_GNU_GETTEXT' is defined, at least in the Cygnus version - of gettext). - -My `Makefile' has `@' characters in it. - This may mean that you tried to use an autoconf substitution in - your `Makefile.in' without adding the appropriate `AC_SUBST' call - to your `configure' script. Or it may just mean that you need to - rebuild `Makefile' in your build directory. To rebuild `Makefile' - from `Makefile.in', run the shell script `config.status' with no - arguments. If you need to force `configure' to run again, first - run `config.status --recheck'. These runs are normally done - automatically by `Makefile' targets, but if your `Makefile' has - gotten messed up you'll need to help them along. - -Why do I have to run both `config.status --recheck' and `config.status'? - Normally, you don't; they will be run automatically by `Makefile' - targets. If you do need to run them, use `config.status --recheck' - to run the `configure' script again with the same arguments as the - first time you ran it. Use `config.status' (with no arguments) to - regenerate all files (`Makefile', `config.h', etc.) based on the - results of the configure script. The two cases are separate - because it isn't always necessary to regenerate all the files - after running `config.status --recheck'. The `Makefile' targets - generated by automake will use the environment variables - `CONFIG_FILES' and `CONFIG_HEADERS' to only regenerate files as - they are needed. - -What is the Cygnus tree? - The Cygnus tree is used for various packages including gdb, the GNU - binutils, and egcs. It is also, of course, used for Cygnus - releases. It is the build system which was developed at Cygnus, - using the Cygnus configure script. It permits building many - different packages with a single configure and make. The - configure scripts in the tree are being converted to autoconf, but - the general build structure remains intact. - -Why do I have to keep rebuilding and reinstalling the tools? - I know, it's a pain. Unfortunately, there are bugs in the tools - themselves which need to be fixed, and each time that happens - everybody who uses the tools need to reinstall new versions of - them. I don't know if there is going to be a clever fix until the - tools stabilize. - -Why not just have a Cygnus tree `make' target to update the tools? - The tools unfortunately need to be installed before they can be - used. That means that they must be built using an appropriate - prefix, and it seems unwise to assume that every configuration - uses an appropriate prefix. It might be possible to make them - work in place, or it might be possible to install them in some - subdirectory; so far these approaches have not been implemented. - - -File: configure.info, Node: Index, Prev: FAQ, Up: Top - -Index -***** - - -* Menu: - -* --build option: Build and Host Options. - (line 9) -* --host option: Build and Host Options. - (line 14) -* --target option: Specifying the Target. - (line 10) -* _GNU_SOURCE: Write configure.in. (line 134) -* AC_CANONICAL_HOST: Using the Host Type. (line 10) -* AC_CANONICAL_SYSTEM: Using the Target Type. - (line 6) -* AC_CONFIG_HEADER: Write configure.in. (line 66) -* AC_EXEEXT: Write configure.in. (line 86) -* AC_INIT: Write configure.in. (line 38) -* AC_OUTPUT: Write configure.in. (line 142) -* AC_PREREQ: Write configure.in. (line 42) -* AC_PROG_CC: Write configure.in. (line 103) -* AC_PROG_CXX: Write configure.in. (line 117) -* acconfig.h: Written Developer Files. - (line 27) -* acconfig.h, writing: Write acconfig.h. (line 6) -* acinclude.m4: Written Developer Files. - (line 37) -* aclocal.m4: Generated Developer Files. - (line 33) -* AM_CONFIG_HEADER: Write configure.in. (line 53) -* AM_DISABLE_SHARED: Write configure.in. (line 127) -* AM_EXEEXT: Write configure.in. (line 86) -* AM_INIT_AUTOMAKE: Write configure.in. (line 48) -* AM_MAINTAINER_MODE: Write configure.in. (line 70) -* AM_PROG_LIBTOOL: Write configure.in. (line 122) -* AM_PROG_LIBTOOL in configure: FAQ. (line 19) -* build option: Build and Host Options. - (line 9) -* building with a cross compiler: Canadian Cross. (line 6) -* canadian cross: Canadian Cross. (line 6) -* canadian cross in configure: CCross in Configure. (line 6) -* canadian cross in cygnus tree: CCross in Cygnus Tree. - (line 6) -* canadian cross in makefile: CCross in Make. (line 6) -* canadian cross, configuring: Build and Host Options. - (line 6) -* canonical system names: Configuration Names. (line 6) -* config.cache: Build Files Description. - (line 28) -* config.h: Build Files Description. - (line 23) -* config.h.in: Generated Developer Files. - (line 45) -* config.in: Generated Developer Files. - (line 45) -* config.status: Build Files Description. - (line 9) -* config.status --recheck: FAQ. (line 40) -* configuration names: Configuration Names. (line 6) -* configuration triplets: Configuration Names. (line 6) -* configure: Generated Developer Files. - (line 21) -* configure build system: Build and Host Options. - (line 9) -* configure host: Build and Host Options. - (line 14) -* configure target: Specifying the Target. - (line 10) -* configure.in: Written Developer Files. - (line 9) -* configure.in, writing: Write configure.in. (line 6) -* configuring a canadian cross: Build and Host Options. - (line 6) -* cross compiler: Cross Compilation Concepts. - (line 6) -* cross compiler, building with: Canadian Cross. (line 6) -* cross tools: Cross Compilation Tools. - (line 6) -* CY_GNU_GETTEXT in configure: FAQ. (line 19) -* cygnus configure: Cygnus Configure. (line 6) -* goals: Goals. (line 6) -* history: History. (line 6) -* host names: Configuration Names. (line 6) -* host option: Build and Host Options. - (line 14) -* host system: Host and Target. (line 6) -* host triplets: Configuration Names. (line 6) -* HOST_CC: CCross in Make. (line 27) -* libg++ configure: Cygnus Configure in C++ Libraries. - (line 6) -* libio configure: Cygnus Configure in C++ Libraries. - (line 6) -* libstdc++ configure: Cygnus Configure in C++ Libraries. - (line 6) -* Makefile: Build Files Description. - (line 18) -* Makefile, garbage characters: FAQ. (line 29) -* Makefile.am: Written Developer Files. - (line 18) -* Makefile.am, writing: Write Makefile.am. (line 6) -* Makefile.in: Generated Developer Files. - (line 26) -* multilibs: Multilibs. (line 6) -* stamp-h: Build Files Description. - (line 41) -* stamp-h.in: Generated Developer Files. - (line 54) -* system names: Configuration Names. (line 6) -* system types: Configuration Names. (line 6) -* target option: Specifying the Target. - (line 10) -* target system: Host and Target. (line 6) -* triplets: Configuration Names. (line 6) -* undefined macros: FAQ. (line 12) - - - -Tag Table: -Node: Top978 -Node: Introduction1506 -Node: Goals2588 -Node: Tools3312 -Node: History4306 -Node: Building7304 -Node: Getting Started10399 -Node: Write configure.in10912 -Node: Write Makefile.am18163 -Node: Write acconfig.h21340 -Node: Generate files22877 -Node: Getting Started Example24843 -Node: Getting Started Example 125598 -Node: Getting Started Example 227519 -Node: Getting Started Example 330514 -Node: Generate Files in Example32878 -Node: Files33968 -Node: Developer Files34579 -Node: Developer Files Picture34959 -Node: Written Developer Files36247 -Node: Generated Developer Files38799 -Node: Build Files41943 -Node: Build Files Picture42604 -Node: Build Files Description43368 -Node: Support Files45374 -Node: Configuration Names48256 -Node: Configuration Name Definition48756 -Node: Using Configuration Names51079 -Node: Cross Compilation Tools53049 -Node: Cross Compilation Concepts53740 -Node: Host and Target54708 -Node: Using the Host Type56209 -Node: Specifying the Target57558 -Node: Using the Target Type58347 -Node: Cross Tools in the Cygnus Tree61778 -Node: Host and Target Libraries62835 -Node: Target Library Configure Scripts66584 -Node: Make Targets in Cygnus Tree69676 -Node: Target libiberty71024 -Node: Canadian Cross72411 -Node: Canadian Cross Example73252 -Node: Canadian Cross Concepts74371 -Node: Build Cross Host Tools75883 -Node: Build and Host Options76835 -Node: CCross not in Cygnus Tree78621 -Node: CCross in Cygnus Tree79599 -Node: Standard Cygnus CCross80020 -Node: Cross Cygnus CCross81384 -Node: Supporting Canadian Cross84184 -Node: CCross in Configure84799 -Node: CCross in Make87967 -Node: Cygnus Configure89570 -Node: Cygnus Configure Basics90405 -Node: Cygnus Configure in C++ Libraries95083 -Node: Multilibs96090 -Node: Multilibs in gcc97135 -Node: Multilibs in Target Libraries98213 -Node: FAQ102404 -Node: Index106504 - -End Tag Table diff --git a/etc/standards.info b/etc/standards.info deleted file mode 100644 index 50ee69bdd09..00000000000 --- a/etc/standards.info +++ /dev/null @@ -1,4930 +0,0 @@ -This is standards.info, produced by makeinfo version 4.7 from -.././etc/standards.texi. - -START-INFO-DIR-ENTRY -* Standards: (standards). GNU coding standards. -END-INFO-DIR-ENTRY - - GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996, -1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. - - Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled "GNU -Free Documentation License". - - -File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir) - -Version -******* - -Last updated February 14, 2002. - -* Menu: - -* Preface:: About the GNU Coding Standards -* Legal Issues:: Keeping Free Software Free -* Design Advice:: General Program Design -* Program Behavior:: Program Behavior for All Programs -* Writing C:: Making The Best Use of C -* Documentation:: Documenting Programs -* Managing Releases:: The Release Process -* References:: References to Non-Free Software or Documentation -* Copying This Manual:: How to Make Copies of This Manual -* Index:: - - -File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top - -1 About the GNU Coding Standards -******************************** - -The GNU Coding Standards were written by Richard Stallman and other GNU -Project volunteers. Their purpose is to make the GNU system clean, -consistent, and easy to install. This document can also be read as a -guide to writing portable, robust and reliable programs. It focuses on -programs written in C, but many of the rules and principles are useful -even if you write in another programming language. The rules often -state reasons for writing in a certain way. - - This release of the GNU Coding Standards was last updated February -14, 2002. - - If you did not obtain this file directly from the GNU project and -recently, please check for a newer version. You can ftp the GNU Coding -Standards from any GNU FTP host in the directory `/pub/gnu/standards/'. -The GNU Coding Standards are available there in several different -formats: `standards.text', `standards.info', and `standards.dvi', as -well as the Texinfo "source" which is divided in two files: -`standards.texi' and `make-stds.texi'. The GNU Coding Standards are -also available on the GNU World Wide Web server: -`http://www.gnu.org/prep/standards_toc.html'. - - Corrections or suggestions for this document should be sent to -<bug-standards@gnu.org>. If you make a suggestion, please include a -suggested new wording for it; our time is limited. We prefer a context -diff to the `standards.texi' or `make-stds.texi' files, but if you -don't have those files, please mail your suggestion anyway. - - These standards cover the minimum of what is important when writing a -GNU package. Likely, the needs for additional standards will come up. -Sometimes, you might suggest that such standards be added to this -document. If you think your standards would be generally useful, please -do suggest them. - - You should also set standards for your package on many questions not -addressed or not firmly specified here. The most important point is to -be self-consistent--try to stick to the conventions you pick, and try -to document them as much as possible. That way, your program will be -more maintainable by others. - - -File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top - -2 Keeping Free Software Free -**************************** - -This node discusses how you can make sure that GNU software avoids -legal difficulties, and other related issues. - -* Menu: - -* Reading Non-Free Code:: Referring to Proprietary Programs -* Contributions:: Accepting Contributions -* Trademarks:: How We Deal with Trademark Issues - - -File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues - -2.1 Referring to Proprietary Programs -===================================== - -Don't in any circumstances refer to Unix source code for or during your -work on GNU! (Or to any other proprietary programs.) - - If you have a vague recollection of the internals of a Unix program, -this does not absolutely mean you can't write an imitation of it, but -do try to organize the imitation internally along different lines, -because this is likely to make the details of the Unix version -irrelevant and dissimilar to your results. - - For example, Unix utilities were generally optimized to minimize -memory use; if you go for speed instead, your program will be very -different. You could keep the entire input file in core and scan it -there instead of using stdio. Use a smarter algorithm discovered more -recently than the Unix program. Eliminate use of temporary files. Do -it in one pass instead of two (we did this in the assembler). - - Or, on the contrary, emphasize simplicity instead of speed. For some -applications, the speed of today's computers makes simpler algorithms -adequate. - - Or go for generality. For example, Unix programs often have static -tables or fixed-size strings, which make for arbitrary limits; use -dynamic allocation instead. Make sure your program handles NULs and -other funny characters in the input files. Add a programming language -for extensibility and write part of the program in that language. - - Or turn some parts of the program into independently usable -libraries. Or use a simple garbage collector instead of tracking -precisely when to free memory, or use a new GNU facility such as -obstacks. - - -File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues - -2.2 Accepting Contributions -=========================== - -If the program you are working on is copyrighted by the Free Software -Foundation, then when someone else sends you a piece of code to add to -the program, we need legal papers to use it--just as we asked you to -sign papers initially. _Each_ person who makes a nontrivial -contribution to a program must sign some sort of legal papers in order -for us to have clear title to the program; the main author alone is not -enough. - - So, before adding in any contributions from other people, please tell -us, so we can arrange to get the papers. Then wait until we tell you -that we have received the signed papers, before you actually use the -contribution. - - This applies both before you release the program and afterward. If -you receive diffs to fix a bug, and they make significant changes, we -need legal papers for that change. - - This also applies to comments and documentation files. For copyright -law, comments and code are just text. Copyright applies to all kinds of -text, so we need legal papers for all kinds. - - We know it is frustrating to ask for legal papers; it's frustrating -for us as well. But if you don't wait, you are going out on a limb--for -example, what if the contributor's employer won't sign a disclaimer? -You might have to take that code out again! - - You don't need papers for changes of a few lines here or there, since -they are not significant for copyright purposes. Also, you don't need -papers if all you get from the suggestion is some ideas, not actual code -which you use. For example, if someone send you one implementation, but -you write a different implementation of the same idea, you don't need to -get papers. - - The very worst thing is if you forget to tell us about the other -contributor. We could be very embarrassed in court some day as a -result. - - We have more detailed advice for maintainers of programs; if you have -reached the stage of actually maintaining a program for GNU (whether -released or not), please ask us for a copy. - - -File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues - -2.3 Trademarks -============== - -Please do not include any trademark acknowledgements in GNU software -packages or documentation. - - Trademark acknowledgements are the statements that such-and-such is a -trademark of so-and-so. The GNU Project has no objection to the basic -idea of trademarks, but these acknowledgements feel like kowtowing, so -we don't use them. There is no legal requirement for them. - - What is legally required, as regards other people's trademarks, is to -avoid using them in ways which a reader might read as naming or labeling -our own programs or activities. For example, since "Objective C" is -(or at least was) a trademark, we made sure to say that we provide a -"compiler for the Objective C language" rather than an "Objective C -compiler". The latter is meant to be short for the former, but it does -not explicitly state the relationship, so it could be misinterpreted as -using "Objective C" as a label for the compiler rather than for the -language. - - -File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top - -3 General Program Design -************************ - -This node discusses some of the issues you should take into account -when designing your program. - -* Menu: - -* Source Language:: Which languges to use. -* Compatibility:: Compatibility with other implementations -* Using Extensions:: Using non-standard features -* Standard C:: Using Standard C features -* Conditional Compilation:: Compiling Code Only If A Conditional is True - - -File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice - -3.1 Which Languages to Use -========================== - -When you want to use a language that gets compiled and runs at high -speed, the best language to use is C. Using another language is like -using a non-standard feature: it will cause trouble for users. Even if -GCC supports the other language, users may find it inconvenient to have -to install the compiler for that other language in order to build your -program. For example, if you write your program in C++, people will -have to install the GNU C++ compiler in order to compile your program. - - C has one other advantage over C++ and other compiled languages: more -people know C, so more people will find it easy to read and modify the -program if it is written in C. - - So in general it is much better to use C, rather than the comparable -alternatives. - - But there are two exceptions to that conclusion: - - * It is no problem to use another language to write a tool - specifically intended for use with that language. That is because - the only people who want to build the tool will be those who have - installed the other language anyway. - - * If an application is of interest only to a narrow part of the - community, then the question of which language it is written in - has less effect on other people, so you may as well please - yourself. - - Many programs are designed to be extensible: they include an -interpreter for a language that is higher level than C. Often much of -the program is written in that language, too. The Emacs editor -pioneered this technique. - - The standard extensibility interpreter for GNU software is GUILE, -which implements the language Scheme (an especially clean and simple -dialect of Lisp). `http://www.gnu.org/software/guile/'. We don't -reject programs written in other "scripting languages" such as Perl and -Python, but using GUILE is very important for the overall consistency of -the GNU system. - - -File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice - -3.2 Compatibility with Other Implementations -============================================ - -With occasional exceptions, utility programs and libraries for GNU -should be upward compatible with those in Berkeley Unix, and upward -compatible with Standard C if Standard C specifies their behavior, and -upward compatible with POSIX if POSIX specifies their behavior. - - When these standards conflict, it is useful to offer compatibility -modes for each of them. - - Standard C and POSIX prohibit many kinds of extensions. Feel free -to make the extensions anyway, and include a `--ansi', `--posix', or -`--compatible' option to turn them off. However, if the extension has -a significant chance of breaking any real programs or scripts, then it -is not really upward compatible. So you should try to redesign its -interface to make it upward compatible. - - Many GNU programs suppress extensions that conflict with POSIX if the -environment variable `POSIXLY_CORRECT' is defined (even if it is -defined with a null value). Please make your program recognize this -variable if appropriate. - - When a feature is used only by users (not by programs or command -files), and it is done poorly in Unix, feel free to replace it -completely with something totally different and better. (For example, -`vi' is replaced with Emacs.) But it is nice to offer a compatible -feature as well. (There is a free `vi' clone, so we offer it.) - - Additional useful features are welcome regardless of whether there -is any precedent for them. - - -File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice - -3.3 Using Non-standard Features -=============================== - -Many GNU facilities that already exist support a number of convenient -extensions over the comparable Unix facilities. Whether to use these -extensions in implementing your program is a difficult question. - - On the one hand, using the extensions can make a cleaner program. -On the other hand, people will not be able to build the program unless -the other GNU tools are available. This might cause the program to -work on fewer kinds of machines. - - With some extensions, it might be easy to provide both alternatives. -For example, you can define functions with a "keyword" `INLINE' and -define that as a macro to expand into either `inline' or nothing, -depending on the compiler. - - In general, perhaps it is best not to use the extensions if you can -straightforwardly do without them, but to use the extensions if they -are a big improvement. - - An exception to this rule are the large, established programs (such -as Emacs) which run on a great variety of systems. Using GNU -extensions in such programs would make many users unhappy, so we don't -do that. - - Another exception is for programs that are used as part of -compilation: anything that must be compiled with other compilers in -order to bootstrap the GNU compilation facilities. If these require -the GNU compiler, then no one can compile them without having them -installed already. That would be extremely troublesome in certain -cases. - - -File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice - -3.4 Standard C and Pre-Standard C -================================= - -1989 Standard C is widespread enough now that it is ok to use its -features in new programs. There is one exception: do not ever use the -"trigraph" feature of Standard C. - - 1999 Standard C is not widespread yet, so please do not require its -features in programs. It is ok to use its features if they are present. - - However, it is easy to support pre-standard compilers in most -programs, so if you know how to do that, feel free. If a program you -are maintaining has such support, you should try to keep it working. - - To support pre-standard C, instead of writing function definitions in -standard prototype form, - - int - foo (int x, int y) - ... - -write the definition in pre-standard style like this, - - int - foo (x, y) - int x, y; - ... - -and use a separate declaration to specify the argument prototype: - - int foo (int, int); - - You need such a declaration anyway, in a header file, to get the -benefit of prototypes in all the files where the function is called. -And once you have the declaration, you normally lose nothing by writing -the function definition in the pre-standard style. - - This technique does not work for integer types narrower than `int'. -If you think of an argument as being of a type narrower than `int', -declare it as `int' instead. - - There are a few special cases where this technique is hard to use. -For example, if a function argument needs to hold the system type -`dev_t', you run into trouble, because `dev_t' is shorter than `int' on -some machines; but you cannot use `int' instead, because `dev_t' is -wider than `int' on some machines. There is no type you can safely use -on all machines in a non-standard definition. The only way to support -non-standard C and pass such an argument is to check the width of -`dev_t' using Autoconf and choose the argument type accordingly. This -may not be worth the trouble. - - In order to support pre-standard compilers that do not recognize -prototypes, you may want to use a preprocessor macro like this: - - /* Declare the prototype for a general external function. */ - #if defined (__STDC__) || defined (WINDOWSNT) - #define P_(proto) proto - #else - #define P_(proto) () - #endif - - -File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice - -3.5 Conditional Compilation -=========================== - -When supporting configuration options already known when building your -program we prefer using `if (... )' over conditional compilation, as in -the former case the compiler is able to perform more extensive checking -of all possible code paths. - - For example, please write - - if (HAS_FOO) - ... - else - ... - - instead of: - - #ifdef HAS_FOO - ... - #else - ... - #endif - - A modern compiler such as GCC will generate exactly the same code in -both cases, and we have been using similar techniques with good success -in several projects. - - While this is not a silver bullet solving all portability problems, -following this policy would have saved the GCC project alone many person -hours if not days per year. - - In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC -which cannot be simply used in `if( ...)' statements, there is an easy -workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as -in the following example: - - #ifdef REVERSIBLE_CC_MODE - #define HAS_REVERSIBLE_CC_MODE 1 - #else - #define HAS_REVERSIBLE_CC_MODE 0 - #endif - - -File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top - -4 Program Behavior for All Programs -*********************************** - -This node describes conventions for writing robust software. It also -describes general standards for error messages, the command line -interface, and how libraries should behave. - -* Menu: - -* Semantics:: Writing robust programs -* Libraries:: Library behavior -* Errors:: Formatting error messages -* User Interfaces:: Standards about interfaces generally -* Graphical Interfaces:: Standards for graphical interfaces -* Command-Line Interfaces:: Standards for command line interfaces -* Option Table:: Table of long options -* Memory Usage:: When and how to care about memory needs -* File Usage:: Which files to use, and where - - -File: standards.info, Node: Semantics, Next: Libraries, Up: Program Behavior - -4.1 Writing Robust Programs -=========================== - -Avoid arbitrary limits on the length or number of _any_ data structure, -including file names, lines, files, and symbols, by allocating all data -structures dynamically. In most Unix utilities, "long lines are -silently truncated". This is not acceptable in a GNU utility. - - Utilities reading files should not drop NUL characters, or any other -nonprinting characters _including those with codes above 0177_. The -only sensible exceptions would be utilities specifically intended for -interface to certain types of terminals or printers that can't handle -those characters. Whenever possible, try to make programs work -properly with sequences of bytes that represent multibyte characters, -using encodings such as UTF-8 and others. - - Check every system call for an error return, unless you know you -wish to ignore errors. Include the system error text (from `perror' or -equivalent) in _every_ error message resulting from a failing system -call, as well as the name of the file if any and the name of the -utility. Just "cannot open foo.c" or "stat failed" is not sufficient. - - Check every call to `malloc' or `realloc' to see if it returned -zero. Check `realloc' even if you are making the block smaller; in a -system that rounds block sizes to a power of 2, `realloc' may get a -different block if you ask for less space. - - In Unix, `realloc' can destroy the storage block if it returns zero. -GNU `realloc' does not have this bug: if it fails, the original block -is unchanged. Feel free to assume the bug is fixed. If you wish to -run your program on Unix, and wish to avoid lossage in this case, you -can use the GNU `malloc'. - - You must expect `free' to alter the contents of the block that was -freed. Anything you want to fetch from the block, you must fetch before -calling `free'. - - If `malloc' fails in a noninteractive program, make that a fatal -error. In an interactive program (one that reads commands from the -user), it is better to abort the command and return to the command -reader loop. This allows the user to kill other processes to free up -virtual memory, and then try the command again. - - Use `getopt_long' to decode arguments, unless the argument syntax -makes this unreasonable. - - When static storage is to be written in during program execution, use -explicit C code to initialize it. Reserve C initialized declarations -for data that will not be changed. - - Try to avoid low-level interfaces to obscure Unix data structures -(such as file directories, utmp, or the layout of kernel memory), since -these are less likely to work compatibly. If you need to find all the -files in a directory, use `readdir' or some other high-level interface. -These are supported compatibly by GNU. - - The preferred signal handling facilities are the BSD variant of -`signal', and the POSIX `sigaction' function; the alternative USG -`signal' interface is an inferior design. - - Nowadays, using the POSIX signal functions may be the easiest way to -make a program portable. If you use `signal', then on GNU/Linux -systems running GNU libc version 1, you should include `bsd/signal.h' -instead of `signal.h', so as to get BSD behavior. It is up to you -whether to support systems where `signal' has only the USG behavior, or -give up on them. - - In error checks that detect "impossible" conditions, just abort. -There is usually no point in printing any message. These checks -indicate the existence of bugs. Whoever wants to fix the bugs will have -to read the source code and run a debugger. So explain the problem with -comments in the source. The relevant data will be in variables, which -are easy to examine with the debugger, so there is no point moving them -elsewhere. - - Do not use a count of errors as the exit status for a program. -_That does not work_, because exit status values are limited to 8 bits -(0 through 255). A single run of the program might have 256 errors; if -you try to return 256 as the exit status, the parent process will see 0 -as the status, and it will appear that the program succeeded. - - If you make temporary files, check the `TMPDIR' environment -variable; if that variable is defined, use the specified directory -instead of `/tmp'. - - In addition, be aware that there is a possible security problem when -creating temporary files in world-writable directories. In C, you can -avoid this problem by creating temporary files in this manner: - - fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600); - -or by using the `mkstemps' function from libiberty. - - In bash, use `set -C' to avoid this problem. - - -File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior - -4.2 Library Behavior -==================== - -Try to make library functions reentrant. If they need to do dynamic -storage allocation, at least try to avoid any nonreentrancy aside from -that of `malloc' itself. - - Here are certain name conventions for libraries, to avoid name -conflicts. - - Choose a name prefix for the library, more than two characters long. -All external function and variable names should start with this prefix. -In addition, there should only be one of these in any given library -member. This usually means putting each one in a separate source file. - - An exception can be made when two external symbols are always used -together, so that no reasonable program could use one without the -other; then they can both go in the same file. - - External symbols that are not documented entry points for the user -should have names beginning with `_'. The `_' should be followed by -the chosen name prefix for the library, to prevent collisions with -other libraries. These can go in the same files with user entry points -if you like. - - Static functions and variables can be used as you like and need not -fit any naming convention. - - -File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior - -4.3 Formatting Error Messages -============================= - -Error messages from compilers should look like this: - - SOURCE-FILE-NAME:LINENO: MESSAGE - -If you want to mention the column number, use this format: - - SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE - -Line numbers should start from 1 at the beginning of the file, and -column numbers should start from 1 at the beginning of the line. (Both -of these conventions are chosen for compatibility.) Calculate column -numbers assuming that space and all ASCII printing characters have -equal width, and assuming tab stops every 8 columns. - - Error messages from other noninteractive programs should look like -this: - - PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE - -when there is an appropriate source file, or like this: - - PROGRAM: MESSAGE - -when there is no relevant source file. - - If you want to mention the column number, use this format: - - PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE - - In an interactive program (one that is reading commands from a -terminal), it is better not to include the program name in an error -message. The place to indicate which program is running is in the -prompt or with the screen layout. (When the same program runs with -input from a source other than a terminal, it is not interactive and -would do best to print error messages using the noninteractive style.) - - The string MESSAGE should not begin with a capital letter when it -follows a program name and/or file name. Also, it should not end with -a period. - - Error messages from interactive programs, and other messages such as -usage messages, should start with a capital letter. But they should not -end with a period. - - -File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior - -4.4 Standards for Interfaces Generally -====================================== - -Please don't make the behavior of a utility depend on the name used to -invoke it. It is useful sometimes to make a link to a utility with a -different name, and that should not change what it does. - - Instead, use a run time option or a compilation switch or both to -select among the alternate behaviors. - - Likewise, please don't make the behavior of the program depend on the -type of output device it is used with. Device independence is an -important principle of the system's design; do not compromise it merely -to save someone from typing an option now and then. (Variation in error -message syntax when using a terminal is ok, because that is a side issue -that people do not depend on.) - - If you think one behavior is most useful when the output is to a -terminal, and another is most useful when the output is a file or a -pipe, then it is usually best to make the default behavior the one that -is useful with output to a terminal, and have an option for the other -behavior. - - Compatibility requires certain programs to depend on the type of -output device. It would be disastrous if `ls' or `sh' did not do so in -the way all users expect. In some of these cases, we supplement the -program with a preferred alternate version that does not depend on the -output device type. For example, we provide a `dir' program much like -`ls' except that its default output format is always multi-column -format. - - -File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior - -4.5 Standards for Graphical Interfaces -====================================== - -When you write a program that provides a graphical user interface, -please make it work with X Windows and the GTK toolkit unless the -functionality specifically requires some alternative (for example, -"displaying jpeg images while in console mode"). - - In addition, please provide a command-line interface to control the -functionality. (In many cases, the graphical user interface can be a -separate program which invokes the command-line program.) This is so -that the same jobs can be done from scripts. - - Please also consider providing a CORBA interface (for use from -GNOME), a library interface (for use from C), and perhaps a -keyboard-driven console interface (for use by users from console mode). -Once you are doing the work to provide the functionality and the -graphical interface, these won't be much extra work. - - -File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior - -4.6 Standards for Command Line Interfaces -========================================= - -It is a good idea to follow the POSIX guidelines for the command-line -options of a program. The easiest way to do this is to use `getopt' to -parse them. Note that the GNU version of `getopt' will normally permit -options anywhere among the arguments unless the special argument `--' -is used. This is not what POSIX specifies; it is a GNU extension. - - Please define long-named options that are equivalent to the -single-letter Unix-style options. We hope to make GNU more user -friendly this way. This is easy to do with the GNU function -`getopt_long'. - - One of the advantages of long-named options is that they can be -consistent from program to program. For example, users should be able -to expect the "verbose" option of any GNU program which has one, to be -spelled precisely `--verbose'. To achieve this uniformity, look at the -table of common long-option names when you choose the option names for -your program (*note Option Table::). - - It is usually a good idea for file names given as ordinary arguments -to be input files only; any output files would be specified using -options (preferably `-o' or `--output'). Even if you allow an output -file name as an ordinary argument for compatibility, try to provide an -option as another way to specify it. This will lead to more consistency -among GNU utilities, and fewer idiosyncracies for users to remember. - - All programs should support two standard options: `--version' and -`--help'. - -`--version' - This option should direct the program to print information about - its name, version, origin and legal status, all on standard - output, and then exit successfully. Other options and arguments - should be ignored once this is seen, and the program should not - perform its normal function. - - The first line is meant to be easy for a program to parse; the - version number proper starts after the last space. In addition, - it contains the canonical name for this program, in this format: - - GNU Emacs 19.30 - - The program's name should be a constant string; _don't_ compute it - from `argv[0]'. The idea is to state the standard or canonical - name for the program, not its file name. There are other ways to - find out the precise file name where a command is found in `PATH'. - - If the program is a subsidiary part of a larger package, mention - the package name in parentheses, like this: - - emacsserver (GNU Emacs) 19.30 - - If the package has a version number which is different from this - program's version number, you can mention the package version - number just before the close-parenthesis. - - If you *need* to mention the version numbers of libraries which - are distributed separately from the package which contains this - program, you can do so by printing an additional line of version - info for each library you want to mention. Use the same format - for these lines as for the first line. - - Please do not mention all of the libraries that the program uses - "just for completeness"--that would produce a lot of unhelpful - clutter. Please mention library version numbers only if you find - in practice that they are very important to you in debugging. - - The following line, after the version number line or lines, should - be a copyright notice. If more than one copyright notice is - called for, put each on a separate line. - - Next should follow a brief statement that the program is free - software, and that users are free to copy and change it on certain - conditions. If the program is covered by the GNU GPL, say so - here. Also mention that there is no warranty, to the extent - permitted by law. - - It is ok to finish the output with a list of the major authors of - the program, as a way of giving credit. - - Here's an example of output that follows these rules: - - GNU Emacs 19.34.5 - Copyright (C) 1996 Free Software Foundation, Inc. - GNU Emacs comes with NO WARRANTY, - to the extent permitted by law. - You may redistribute copies of GNU Emacs - under the terms of the GNU General Public License. - For more information about these matters, - see the files named COPYING. - - You should adapt this to your program, of course, filling in the - proper year, copyright holder, name of program, and the references - to distribution terms, and changing the rest of the wording as - necessary. - - This copyright notice only needs to mention the most recent year in - which changes were made--there's no need to list the years for - previous versions' changes. You don't have to mention the name of - the program in these notices, if that is inconvenient, since it - appeared in the first line. - - Translations of the above lines must preserve the validity of the - copyright notices (*note Internationalization::). If the - translation's character set supports it, the `(C)' should be - replaced with the copyright symbol, as follows: - - (the official copyright symbol, which is the letter C in a circle); - - Write the word "Copyright" exactly like that, in English. Do not - translate it into another language. International treaties - recognize the English word "Copyright"; translations into other - languages do not have legal significance. - -`--help' - This option should output brief documentation for how to invoke the - program, on standard output, then exit successfully. Other - options and arguments should be ignored once this is seen, and the - program should not perform its normal function. - - Near the end of the `--help' option's output there should be a line - that says where to mail bug reports. It should have this format: - - Report bugs to MAILING-ADDRESS. - - -File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior - -4.7 Table of Long Options -========================= - -Here is a table of long options used by GNU programs. It is surely -incomplete, but we aim to list all the options that a new program might -want to be compatible with. If you use names not already in the table, -please send <bug-standards@gnu.org> a list of them, with their -meanings, so we can update the table. - -`after-date' - `-N' in `tar'. - -`all' - `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'. - -`all-text' - `-a' in `diff'. - -`almost-all' - `-A' in `ls'. - -`append' - `-a' in `etags', `tee', `time'; `-r' in `tar'. - -`archive' - `-a' in `cp'. - -`archive-name' - `-n' in `shar'. - -`arglength' - `-l' in `m4'. - -`ascii' - `-a' in `diff'. - -`assign' - `-v' in `gawk'. - -`assume-new' - `-W' in Make. - -`assume-old' - `-o' in Make. - -`auto-check' - `-a' in `recode'. - -`auto-pager' - `-a' in `wdiff'. - -`auto-reference' - `-A' in `ptx'. - -`avoid-wraps' - `-n' in `wdiff'. - -`background' - For server programs, run in the background. - -`backward-search' - `-B' in `ctags'. - -`basename' - `-f' in `shar'. - -`batch' - Used in GDB. - -`baud' - Used in GDB. - -`before' - `-b' in `tac'. - -`binary' - `-b' in `cpio' and `diff'. - -`bits-per-code' - `-b' in `shar'. - -`block-size' - Used in `cpio' and `tar'. - -`blocks' - `-b' in `head' and `tail'. - -`break-file' - `-b' in `ptx'. - -`brief' - Used in various programs to make output shorter. - -`bytes' - `-c' in `head', `split', and `tail'. - -`c++' - `-C' in `etags'. - -`catenate' - `-A' in `tar'. - -`cd' - Used in various programs to specify the directory to use. - -`changes' - `-c' in `chgrp' and `chown'. - -`classify' - `-F' in `ls'. - -`colons' - `-c' in `recode'. - -`command' - `-c' in `su'; `-x' in GDB. - -`compare' - `-d' in `tar'. - -`compat' - Used in `gawk'. - -`compress' - `-Z' in `tar' and `shar'. - -`concatenate' - `-A' in `tar'. - -`confirmation' - `-w' in `tar'. - -`context' - Used in `diff'. - -`copyleft' - `-W copyleft' in `gawk'. - -`copyright' - `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'. - -`core' - Used in GDB. - -`count' - `-q' in `who'. - -`count-links' - `-l' in `du'. - -`create' - Used in `tar' and `cpio'. - -`cut-mark' - `-c' in `shar'. - -`cxref' - `-x' in `ctags'. - -`date' - `-d' in `touch'. - -`debug' - `-d' in Make and `m4'; `-t' in Bison. - -`define' - `-D' in `m4'. - -`defines' - `-d' in Bison and `ctags'. - -`delete' - `-D' in `tar'. - -`dereference' - `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'. - -`dereference-args' - `-D' in `du'. - -`device' - Specify an I/O device (special file name). - -`diacritics' - `-d' in `recode'. - -`dictionary-order' - `-d' in `look'. - -`diff' - `-d' in `tar'. - -`digits' - `-n' in `csplit'. - -`directory' - Specify the directory to use, in various programs. In `ls', it - means to show directories themselves rather than their contents. - In `rm' and `ln', it means to not treat links to directories - specially. - -`discard-all' - `-x' in `strip'. - -`discard-locals' - `-X' in `strip'. - -`dry-run' - `-n' in Make. - -`ed' - `-e' in `diff'. - -`elide-empty-files' - `-z' in `csplit'. - -`end-delete' - `-x' in `wdiff'. - -`end-insert' - `-z' in `wdiff'. - -`entire-new-file' - `-N' in `diff'. - -`environment-overrides' - `-e' in Make. - -`eof' - `-e' in `xargs'. - -`epoch' - Used in GDB. - -`error-limit' - Used in `makeinfo'. - -`error-output' - `-o' in `m4'. - -`escape' - `-b' in `ls'. - -`exclude-from' - `-X' in `tar'. - -`exec' - Used in GDB. - -`exit' - `-x' in `xargs'. - -`exit-0' - `-e' in `unshar'. - -`expand-tabs' - `-t' in `diff'. - -`expression' - `-e' in `sed'. - -`extern-only' - `-g' in `nm'. - -`extract' - `-i' in `cpio'; `-x' in `tar'. - -`faces' - `-f' in `finger'. - -`fast' - `-f' in `su'. - -`fatal-warnings' - `-E' in `m4'. - -`file' - `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r' - in `touch'. - -`field-separator' - `-F' in `gawk'. - -`file-prefix' - `-b' in Bison. - -`file-type' - `-F' in `ls'. - -`files-from' - `-T' in `tar'. - -`fill-column' - Used in `makeinfo'. - -`flag-truncation' - `-F' in `ptx'. - -`fixed-output-files' - `-y' in Bison. - -`follow' - `-f' in `tail'. - -`footnote-style' - Used in `makeinfo'. - -`force' - `-f' in `cp', `ln', `mv', and `rm'. - -`force-prefix' - `-F' in `shar'. - -`foreground' - For server programs, run in the foreground; in other words, don't - do anything special to run the server in the background. - -`format' - Used in `ls', `time', and `ptx'. - -`freeze-state' - `-F' in `m4'. - -`fullname' - Used in GDB. - -`gap-size' - `-g' in `ptx'. - -`get' - `-x' in `tar'. - -`graphic' - `-i' in `ul'. - -`graphics' - `-g' in `recode'. - -`group' - `-g' in `install'. - -`gzip' - `-z' in `tar' and `shar'. - -`hashsize' - `-H' in `m4'. - -`header' - `-h' in `objdump' and `recode' - -`heading' - `-H' in `who'. - -`help' - Used to ask for brief usage information. - -`here-delimiter' - `-d' in `shar'. - -`hide-control-chars' - `-q' in `ls'. - -`html' - In `makeinfo', output HTML. - -`idle' - `-u' in `who'. - -`ifdef' - `-D' in `diff'. - -`ignore' - `-I' in `ls'; `-x' in `recode'. - -`ignore-all-space' - `-w' in `diff'. - -`ignore-backups' - `-B' in `ls'. - -`ignore-blank-lines' - `-B' in `diff'. - -`ignore-case' - `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'. - -`ignore-errors' - `-i' in Make. - -`ignore-file' - `-i' in `ptx'. - -`ignore-indentation' - `-I' in `etags'. - -`ignore-init-file' - `-f' in Oleo. - -`ignore-interrupts' - `-i' in `tee'. - -`ignore-matching-lines' - `-I' in `diff'. - -`ignore-space-change' - `-b' in `diff'. - -`ignore-zeros' - `-i' in `tar'. - -`include' - `-i' in `etags'; `-I' in `m4'. - -`include-dir' - `-I' in Make. - -`incremental' - `-G' in `tar'. - -`info' - `-i', `-l', and `-m' in Finger. - -`init-file' - In some programs, specify the name of the file to read as the - user's init file. - -`initial' - `-i' in `expand'. - -`initial-tab' - `-T' in `diff'. - -`inode' - `-i' in `ls'. - -`interactive' - `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs'; - `-w' in `tar'. - -`intermix-type' - `-p' in `shar'. - -`iso-8601' - Used in `date' - -`jobs' - `-j' in Make. - -`just-print' - `-n' in Make. - -`keep-going' - `-k' in Make. - -`keep-files' - `-k' in `csplit'. - -`kilobytes' - `-k' in `du' and `ls'. - -`language' - `-l' in `etags'. - -`less-mode' - `-l' in `wdiff'. - -`level-for-gzip' - `-g' in `shar'. - -`line-bytes' - `-C' in `split'. - -`lines' - Used in `split', `head', and `tail'. - -`link' - `-l' in `cpio'. - -`lint' -`lint-old' - Used in `gawk'. - -`list' - `-t' in `cpio'; `-l' in `recode'. - -`list' - `-t' in `tar'. - -`literal' - `-N' in `ls'. - -`load-average' - `-l' in Make. - -`login' - Used in `su'. - -`machine' - No listing of which programs already use this; someone should - check to see if any actually do, and tell <gnu@gnu.org>. - -`macro-name' - `-M' in `ptx'. - -`mail' - `-m' in `hello' and `uname'. - -`make-directories' - `-d' in `cpio'. - -`makefile' - `-f' in Make. - -`mapped' - Used in GDB. - -`max-args' - `-n' in `xargs'. - -`max-chars' - `-n' in `xargs'. - -`max-lines' - `-l' in `xargs'. - -`max-load' - `-l' in Make. - -`max-procs' - `-P' in `xargs'. - -`mesg' - `-T' in `who'. - -`message' - `-T' in `who'. - -`minimal' - `-d' in `diff'. - -`mixed-uuencode' - `-M' in `shar'. - -`mode' - `-m' in `install', `mkdir', and `mkfifo'. - -`modification-time' - `-m' in `tar'. - -`multi-volume' - `-M' in `tar'. - -`name-prefix' - `-a' in Bison. - -`nesting-limit' - `-L' in `m4'. - -`net-headers' - `-a' in `shar'. - -`new-file' - `-W' in Make. - -`no-builtin-rules' - `-r' in Make. - -`no-character-count' - `-w' in `shar'. - -`no-check-existing' - `-x' in `shar'. - -`no-common' - `-3' in `wdiff'. - -`no-create' - `-c' in `touch'. - -`no-defines' - `-D' in `etags'. - -`no-deleted' - `-1' in `wdiff'. - -`no-dereference' - `-d' in `cp'. - -`no-inserted' - `-2' in `wdiff'. - -`no-keep-going' - `-S' in Make. - -`no-lines' - `-l' in Bison. - -`no-piping' - `-P' in `shar'. - -`no-prof' - `-e' in `gprof'. - -`no-regex' - `-R' in `etags'. - -`no-sort' - `-p' in `nm'. - -`no-split' - Used in `makeinfo'. - -`no-static' - `-a' in `gprof'. - -`no-time' - `-E' in `gprof'. - -`no-timestamp' - `-m' in `shar'. - -`no-validate' - Used in `makeinfo'. - -`no-wait' - Used in `emacsclient'. - -`no-warn' - Used in various programs to inhibit warnings. - -`node' - `-n' in `info'. - -`nodename' - `-n' in `uname'. - -`nonmatching' - `-f' in `cpio'. - -`nstuff' - `-n' in `objdump'. - -`null' - `-0' in `xargs'. - -`number' - `-n' in `cat'. - -`number-nonblank' - `-b' in `cat'. - -`numeric-sort' - `-n' in `nm'. - -`numeric-uid-gid' - `-n' in `cpio' and `ls'. - -`nx' - Used in GDB. - -`old-archive' - `-o' in `tar'. - -`old-file' - `-o' in Make. - -`one-file-system' - `-l' in `tar', `cp', and `du'. - -`only-file' - `-o' in `ptx'. - -`only-prof' - `-f' in `gprof'. - -`only-time' - `-F' in `gprof'. - -`options' - `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'. - -`output' - In various programs, specify the output file name. - -`output-prefix' - `-o' in `shar'. - -`override' - `-o' in `rm'. - -`overwrite' - `-c' in `unshar'. - -`owner' - `-o' in `install'. - -`paginate' - `-l' in `diff'. - -`paragraph-indent' - Used in `makeinfo'. - -`parents' - `-p' in `mkdir' and `rmdir'. - -`pass-all' - `-p' in `ul'. - -`pass-through' - `-p' in `cpio'. - -`port' - `-P' in `finger'. - -`portability' - `-c' in `cpio' and `tar'. - -`posix' - Used in `gawk'. - -`prefix-builtins' - `-P' in `m4'. - -`prefix' - `-f' in `csplit'. - -`preserve' - Used in `tar' and `cp'. - -`preserve-environment' - `-p' in `su'. - -`preserve-modification-time' - `-m' in `cpio'. - -`preserve-order' - `-s' in `tar'. - -`preserve-permissions' - `-p' in `tar'. - -`print' - `-l' in `diff'. - -`print-chars' - `-L' in `cmp'. - -`print-data-base' - `-p' in Make. - -`print-directory' - `-w' in Make. - -`print-file-name' - `-o' in `nm'. - -`print-symdefs' - `-s' in `nm'. - -`printer' - `-p' in `wdiff'. - -`prompt' - `-p' in `ed'. - -`proxy' - Specify an HTTP proxy. - -`query-user' - `-X' in `shar'. - -`question' - `-q' in Make. - -`quiet' - Used in many programs to inhibit the usual output. *Note:* every - program accepting `--quiet' should accept `--silent' as a synonym. - -`quiet-unshar' - `-Q' in `shar' - -`quote-name' - `-Q' in `ls'. - -`rcs' - `-n' in `diff'. - -`re-interval' - Used in `gawk'. - -`read-full-blocks' - `-B' in `tar'. - -`readnow' - Used in GDB. - -`recon' - `-n' in Make. - -`record-number' - `-R' in `tar'. - -`recursive' - Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'. - -`reference-limit' - Used in `makeinfo'. - -`references' - `-r' in `ptx'. - -`regex' - `-r' in `tac' and `etags'. - -`release' - `-r' in `uname'. - -`reload-state' - `-R' in `m4'. - -`relocation' - `-r' in `objdump'. - -`rename' - `-r' in `cpio'. - -`replace' - `-i' in `xargs'. - -`report-identical-files' - `-s' in `diff'. - -`reset-access-time' - `-a' in `cpio'. - -`reverse' - `-r' in `ls' and `nm'. - -`reversed-ed' - `-f' in `diff'. - -`right-side-defs' - `-R' in `ptx'. - -`same-order' - `-s' in `tar'. - -`same-permissions' - `-p' in `tar'. - -`save' - `-g' in `stty'. - -`se' - Used in GDB. - -`sentence-regexp' - `-S' in `ptx'. - -`separate-dirs' - `-S' in `du'. - -`separator' - `-s' in `tac'. - -`sequence' - Used by `recode' to chose files or pipes for sequencing passes. - -`shell' - `-s' in `su'. - -`show-all' - `-A' in `cat'. - -`show-c-function' - `-p' in `diff'. - -`show-ends' - `-E' in `cat'. - -`show-function-line' - `-F' in `diff'. - -`show-tabs' - `-T' in `cat'. - -`silent' - Used in many programs to inhibit the usual output. *Note:* every - program accepting `--silent' should accept `--quiet' as a synonym. - -`size' - `-s' in `ls'. - -`socket' - Specify a file descriptor for a network server to use for its - socket, instead of opening and binding a new socket. This - provides a way to run, in a nonpriveledged process, a server that - normally needs a reserved port number. - -`sort' - Used in `ls'. - -`source' - `-W source' in `gawk'. - -`sparse' - `-S' in `tar'. - -`speed-large-files' - `-H' in `diff'. - -`split-at' - `-E' in `unshar'. - -`split-size-limit' - `-L' in `shar'. - -`squeeze-blank' - `-s' in `cat'. - -`start-delete' - `-w' in `wdiff'. - -`start-insert' - `-y' in `wdiff'. - -`starting-file' - Used in `tar' and `diff' to specify which file within a directory - to start processing with. - -`statistics' - `-s' in `wdiff'. - -`stdin-file-list' - `-S' in `shar'. - -`stop' - `-S' in Make. - -`strict' - `-s' in `recode'. - -`strip' - `-s' in `install'. - -`strip-all' - `-s' in `strip'. - -`strip-debug' - `-S' in `strip'. - -`submitter' - `-s' in `shar'. - -`suffix' - `-S' in `cp', `ln', `mv'. - -`suffix-format' - `-b' in `csplit'. - -`sum' - `-s' in `gprof'. - -`summarize' - `-s' in `du'. - -`symbolic' - `-s' in `ln'. - -`symbols' - Used in GDB and `objdump'. - -`synclines' - `-s' in `m4'. - -`sysname' - `-s' in `uname'. - -`tabs' - `-t' in `expand' and `unexpand'. - -`tabsize' - `-T' in `ls'. - -`terminal' - `-T' in `tput' and `ul'. `-t' in `wdiff'. - -`text' - `-a' in `diff'. - -`text-files' - `-T' in `shar'. - -`time' - Used in `ls' and `touch'. - -`timeout' - Specify how long to wait before giving up on some operation. - -`to-stdout' - `-O' in `tar'. - -`total' - `-c' in `du'. - -`touch' - `-t' in Make, `ranlib', and `recode'. - -`trace' - `-t' in `m4'. - -`traditional' - `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4', - and `ptx'. - -`tty' - Used in GDB. - -`typedefs' - `-t' in `ctags'. - -`typedefs-and-c++' - `-T' in `ctags'. - -`typeset-mode' - `-t' in `ptx'. - -`uncompress' - `-z' in `tar'. - -`unconditional' - `-u' in `cpio'. - -`undefine' - `-U' in `m4'. - -`undefined-only' - `-u' in `nm'. - -`update' - `-u' in `cp', `ctags', `mv', `tar'. - -`usage' - Used in `gawk'; same as `--help'. - -`uuencode' - `-B' in `shar'. - -`vanilla-operation' - `-V' in `shar'. - -`verbose' - Print more information about progress. Many programs support this. - -`verify' - `-W' in `tar'. - -`version' - Print the version number. - -`version-control' - `-V' in `cp', `ln', `mv'. - -`vgrind' - `-v' in `ctags'. - -`volume' - `-V' in `tar'. - -`what-if' - `-W' in Make. - -`whole-size-limit' - `-l' in `shar'. - -`width' - `-w' in `ls' and `ptx'. - -`word-regexp' - `-W' in `ptx'. - -`writable' - `-T' in `who'. - -`zeros' - `-z' in `gprof'. - - -File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior - -4.8 Memory Usage -================ - -If a program typically uses just a few meg of memory, don't bother -making any effort to reduce memory usage. For example, if it is -impractical for other reasons to operate on files more than a few meg -long, it is reasonable to read entire input files into core to operate -on them. - - However, for programs such as `cat' or `tail', that can usefully -operate on very large files, it is important to avoid using a technique -that would artificially limit the size of files it can handle. If a -program works by lines and could be applied to arbitrary user-supplied -input files, it should keep only a line in memory, because this is not -very hard and users will want to be able to operate on input files that -are bigger than will fit in core all at once. - - If your program creates complicated data structures, just make them -in core and give a fatal error if `malloc' returns zero. - - -File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior - -4.9 File Usage -============== - -Programs should be prepared to operate when `/usr' and `/etc' are -read-only file systems. Thus, if the program manages log files, lock -files, backup files, score files, or any other files which are modified -for internal purposes, these files should not be stored in `/usr' or -`/etc'. - - There are two exceptions. `/etc' is used to store system -configuration information; it is reasonable for a program to modify -files in `/etc' when its job is to update the system configuration. -Also, if the user explicitly asks to modify one file in a directory, it -is reasonable for the program to store other files in the same -directory. - - -File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top - -5 Making The Best Use of C -************************** - -This node provides advice on how best to use the C language when -writing GNU software. - -* Menu: - -* Formatting:: Formatting Your Source Code -* Comments:: Commenting Your Work -* Syntactic Conventions:: Clean Use of C Constructs -* Names:: Naming Variables, Functions, and Files -* System Portability:: Portability between different operating systems -* CPU Portability:: Supporting the range of CPU types -* System Functions:: Portability and ``standard'' library functions -* Internationalization:: Techniques for internationalization -* Mmap:: How you can safely use `mmap'. - - -File: standards.info, Node: Formatting, Next: Comments, Up: Writing C - -5.1 Formatting Your Source Code -=============================== - -It is important to put the open-brace that starts the body of a C -function in column zero, and avoid putting any other open-brace or -open-parenthesis or open-bracket in column zero. Several tools look -for open-braces in column zero to find the beginnings of C functions. -These tools will not work on code not formatted that way. - - It is also important for function definitions to start the name of -the function in column zero. This helps people to search for function -definitions, and may also help certain tools recognize them. Thus, the -proper format is this: - - static char * - concat (s1, s2) /* Name starts in column zero here */ - char *s1, *s2; - { /* Open brace in column zero here */ - ... - } - -or, if you want to use Standard C syntax, format the definition like -this: - - static char * - concat (char *s1, char *s2) - { - ... - } - - In Standard C, if the arguments don't fit nicely on one line, split -it like this: - - int - lots_of_args (int an_integer, long a_long, short a_short, - double a_double, float a_float) - ... - - The rest of this section gives our recommendations for other aspects -of C formatting style, which is also the default style of the `indent' -program in version 1.2 and newer. It corresponds to the options - - -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 - -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob - - We don't think of these recommendations as requirements, because it -causes no problems for users if two different programs have different -formatting styles. - - But whatever style you use, please use it consistently, since a -mixture of styles within one program tends to look ugly. If you are -contributing changes to an existing program, please follow the style of -that program. - - For the body of the function, our recommended style looks like this: - - if (x < foo (y, z)) - haha = bar[4] + 5; - else - { - while (z) - { - haha += foo (z, z); - z--; - } - return ++x + bar (); - } - - We find it easier to read a program when it has spaces before the -open-parentheses and after the commas. Especially after the commas. - - When you split an expression into multiple lines, split it before an -operator, not after one. Here is the right way: - - if (foo_this_is_long && bar > win (x, y, z) - && remaining_condition) - - Try to avoid having two operators of different precedence at the same -level of indentation. For example, don't write this: - - mode = (inmode[j] == VOIDmode - || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) - ? outmode[j] : inmode[j]); - - Instead, use extra parentheses so that the indentation shows the -nesting: - - mode = ((inmode[j] == VOIDmode - || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) - ? outmode[j] : inmode[j]); - - Insert extra parentheses so that Emacs will indent the code properly. -For example, the following indentation looks nice if you do it by hand, - - v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 - + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; - -but Emacs would alter it. Adding a set of parentheses produces -something that looks equally nice, and which Emacs will preserve: - - v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 - + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); - - Format do-while statements like this: - - do - { - a = foo (a); - } - while (a > 0); - - Please use formfeed characters (control-L) to divide the program into -pages at logical places (but not within a function). It does not matter -just how long the pages are, since they do not have to fit on a printed -page. The formfeeds should appear alone on lines by themselves. - - -File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C - -5.2 Commenting Your Work -======================== - -Every program should start with a comment saying briefly what it is for. -Example: `fmt - filter for simple filling of text'. - - Please write the comments in a GNU program in English, because -English is the one language that nearly all programmers in all -countries can read. If you do not write English well, please write -comments in English as well as you can, then ask other people to help -rewrite them. If you can't write comments in English, please find -someone to work with you and translate your comments into English. - - Please put a comment on each function saying what the function does, -what sorts of arguments it gets, and what the possible values of -arguments mean and are used for. It is not necessary to duplicate in -words the meaning of the C argument declarations, if a C type is being -used in its customary fashion. If there is anything nonstandard about -its use (such as an argument of type `char *' which is really the -address of the second character of a string, not the first), or any -possible values that would not work the way one would expect (such as, -that strings containing newlines are not guaranteed to work), be sure -to say so. - - Also explain the significance of the return value, if there is one. - - Please put two spaces after the end of a sentence in your comments, -so that the Emacs sentence commands will work. Also, please write -complete sentences and capitalize the first word. If a lower-case -identifier comes at the beginning of a sentence, don't capitalize it! -Changing the spelling makes it a different identifier. If you don't -like starting a sentence with a lower case letter, write the sentence -differently (e.g., "The identifier lower-case is ..."). - - The comment on a function is much clearer if you use the argument -names to speak about the argument values. The variable name itself -should be lower case, but write it in upper case when you are speaking -about the value rather than the variable itself. Thus, "the inode -number NODE_NUM" rather than "an inode". - - There is usually no purpose in restating the name of the function in -the comment before it, because the reader can see that for himself. -There might be an exception when the comment is so long that the -function itself would be off the bottom of the screen. - - There should be a comment on each static variable as well, like this: - - /* Nonzero means truncate lines in the display; - zero means continue them. */ - int truncate_lines; - - Every `#endif' should have a comment, except in the case of short -conditionals (just a few lines) that are not nested. The comment should -state the condition of the conditional that is ending, _including its -sense_. `#else' should have a comment describing the condition _and -sense_ of the code that follows. For example: - - #ifdef foo - ... - #else /* not foo */ - ... - #endif /* not foo */ - #ifdef foo - ... - #endif /* foo */ - -but, by contrast, write the comments this way for a `#ifndef': - - #ifndef foo - ... - #else /* foo */ - ... - #endif /* foo */ - #ifndef foo - ... - #endif /* not foo */ - - -File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C - -5.3 Clean Use of C Constructs -============================= - -Please explicitly declare the types of all objects. For example, you -should explicitly declare all arguments to functions, and you should -declare functions to return `int' rather than omitting the `int'. - - Some programmers like to use the GCC `-Wall' option, and change the -code whenever it issues a warning. If you want to do this, then do. -Other programmers prefer not to use `-Wall', because it gives warnings -for valid and legitimate code which they do not want to change. If you -want to do this, then do. The compiler should be your servant, not -your master. - - Declarations of external functions and functions to appear later in -the source file should all go in one place near the beginning of the -file (somewhere before the first function definition in the file), or -else should go in a header file. Don't put `extern' declarations inside -functions. - - It used to be common practice to use the same local variables (with -names like `tem') over and over for different values within one -function. Instead of doing this, it is better declare a separate local -variable for each distinct purpose, and give it a name which is -meaningful. This not only makes programs easier to understand, it also -facilitates optimization by good compilers. You can also move the -declaration of each local variable into the smallest scope that includes -all its uses. This makes the program even cleaner. - - Don't use local variables or parameters that shadow global -identifiers. - - Don't declare multiple variables in one declaration that spans lines. -Start a new declaration on each line, instead. For example, instead of -this: - - int foo, - bar; - -write either this: - - int foo, bar; - -or this: - - int foo; - int bar; - -(If they are global variables, each should have a comment preceding it -anyway.) - - When you have an `if'-`else' statement nested in another `if' -statement, always put braces around the `if'-`else'. Thus, never write -like this: - - if (foo) - if (bar) - win (); - else - lose (); - -always like this: - - if (foo) - { - if (bar) - win (); - else - lose (); - } - - If you have an `if' statement nested inside of an `else' statement, -either write `else if' on one line, like this, - - if (foo) - ... - else if (bar) - ... - -with its `then'-part indented like the preceding `then'-part, or write -the nested `if' within braces like this: - - if (foo) - ... - else - { - if (bar) - ... - } - - Don't declare both a structure tag and variables or typedefs in the -same declaration. Instead, declare the structure tag separately and -then use it to declare the variables or typedefs. - - Try to avoid assignments inside `if'-conditions. For example, don't -write this: - - if ((foo = (char *) malloc (sizeof *foo)) == 0) - fatal ("virtual memory exhausted"); - -instead, write this: - - foo = (char *) malloc (sizeof *foo); - if (foo == 0) - fatal ("virtual memory exhausted"); - - Don't make the program ugly to placate `lint'. Please don't insert -any casts to `void'. Zero without a cast is perfectly fine as a null -pointer constant, except when calling a varargs function. - - -File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C - -5.4 Naming Variables, Functions, and Files -========================================== - -The names of global variables and functions in a program serve as -comments of a sort. So don't choose terse names--instead, look for -names that give useful information about the meaning of the variable or -function. In a GNU program, names should be English, like other -comments. - - Local variable names can be shorter, because they are used only -within one context, where (presumably) comments explain their purpose. - - Try to limit your use of abbreviations in symbol names. It is ok to -make a few abbreviations, explain what they mean, and then use them -frequently, but don't use lots of obscure abbreviations. - - Please use underscores to separate words in a name, so that the Emacs -word commands can be useful within them. Stick to lower case; reserve -upper case for macros and `enum' constants, and for name-prefixes that -follow a uniform convention. - - For example, you should use names like `ignore_space_change_flag'; -don't use names like `iCantReadThis'. - - Variables that indicate whether command-line options have been -specified should be named after the meaning of the option, not after -the option-letter. A comment should state both the exact meaning of -the option and its letter. For example, - - /* Ignore changes in horizontal whitespace (-b). */ - int ignore_space_change_flag; - - When you want to define names with constant integer values, use -`enum' rather than `#define'. GDB knows about enumeration constants. - - You might want to make sure that none of the file names would -conflict the files were loaded onto an MS-DOS file system which -shortens the names. You can use the program `doschk' to test for this. - - Some GNU programs were designed to limit themselves to file names of -14 characters or less, to avoid file name conflicts if they are read -into older System V systems. Please preserve this feature in the -existing GNU programs that have it, but there is no need to do this in -new GNU programs. `doschk' also reports file names longer than 14 -characters. - - -File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C - -5.5 Portability between System Types -==================================== - -In the Unix world, "portability" refers to porting to different Unix -versions. For a GNU program, this kind of portability is desirable, but -not paramount. - - The primary purpose of GNU software is to run on top of the GNU -kernel, compiled with the GNU C compiler, on various types of CPU. So -the kinds of portability that are absolutely necessary are quite -limited. But it is important to support Linux-based GNU systems, since -they are the form of GNU that is popular. - - Beyond that, it is good to support the other free operating systems -(*BSD), and it is nice to support other Unix-like systems if you want -to. Supporting a variety of Unix-like systems is desirable, although -not paramount. It is usually not too hard, so you may as well do it. -But you don't have to consider it an obligation, if it does turn out to -be hard. - - The easiest way to achieve portability to most Unix-like systems is -to use Autoconf. It's unlikely that your program needs to know more -information about the host platform than Autoconf can provide, simply -because most of the programs that need such knowledge have already been -written. - - Avoid using the format of semi-internal data bases (e.g., -directories) when there is a higher-level alternative (`readdir'). - - As for systems that are not like Unix, such as MSDOS, Windows, the -Macintosh, VMS, and MVS, supporting them is often a lot of work. When -that is the case, it is better to spend your time adding features that -will be useful on GNU and GNU/Linux, rather than on supporting other -incompatible systems. - - It is a good idea to define the "feature test macro" `_GNU_SOURCE' -when compiling your C files. When you compile on GNU or GNU/Linux, -this will enable the declarations of GNU library extension functions, -and that will usually give you a compiler error message if you define -the same function names in some other way in your program. (You don't -have to actually _use_ these functions, if you prefer to make the -program more portable to other systems.) - - But whether or not you use these GNU extensions, you should avoid -using their names for any other meanings. Doing so would make it hard -to move your code into other GNU programs. - - -File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C - -5.6 Portability between CPUs -============================ - -Even GNU systems will differ because of differences among CPU -types--for example, difference in byte ordering and alignment -requirements. It is absolutely essential to handle these differences. -However, don't make any effort to cater to the possibility that an -`int' will be less than 32 bits. We don't support 16-bit machines in -GNU. - - Similarly, don't make any effort to cater to the possibility that -`long' will be smaller than predefined types like `size_t'. For -example, the following code is ok: - - printf ("size = %lu\n", (unsigned long) sizeof array); - printf ("diff = %ld\n", (long) (pointer2 - pointer1)); - - 1989 Standard C requires this to work, and we know of only one -counterexample: 64-bit programs on Microsoft Windows IA-64. We will -leave it to those who want to port GNU programs to that environment to -figure out how to do it. - - Predefined file-size types like `off_t' are an exception: they are -longer than `long' on many platforms, so code like the above won't work -with them. One way to print an `off_t' value portably is to print its -digits yourself, one by one. - - Don't assume that the address of an `int' object is also the address -of its least-significant byte. This is false on big-endian machines. -Thus, don't make the following mistake: - - int c; - ... - while ((c = getchar()) != EOF) - write(file_descriptor, &c, 1); - - When calling functions, you need not worry about the difference -between pointers of various types, or between pointers and integers. -On most machines, there's no difference anyway. As for the few -machines where there is a difference, all of them support Standard C -prototypes, so you can use prototypes (perhaps conditionalized to be -active only in Standard C) to make the code work on those systems. - - In certain cases, it is ok to pass integer and pointer arguments -indiscriminately to the same function, and use no prototype on any -system. For example, many GNU programs have error-reporting functions -that pass their arguments along to `printf' and friends: - - error (s, a1, a2, a3) - char *s; - char *a1, *a2, *a3; - { - fprintf (stderr, "error: "); - fprintf (stderr, s, a1, a2, a3); - } - -In practice, this works on all machines, since a pointer is generally -the widest possible kind of argument; it is much simpler than any -"correct" alternative. Be sure _not_ to use a prototype for such -functions. - - If you have decided to use Standard C, then you can instead define -`error' using `stdarg.h', and pass the arguments along to `vfprintf'. - - Avoid casting pointers to integers if you can. Such casts greatly -reduce portability, and in most programs they are easy to avoid. In the -cases where casting pointers to integers is essential--such as, a Lisp -interpreter which stores type information as well as an address in one -word--you'll have to make explicit provisions to handle different word -sizes. You will also need to make provision for systems in which the -normal range of addresses you can get from `malloc' starts far away -from zero. - - -File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C - -5.7 Calling System Functions -============================ - -C implementations differ substantially. Standard C reduces but does -not eliminate the incompatibilities; meanwhile, many GNU packages still -support pre-standard compilers because this is not hard to do. This -chapter gives recommendations for how to use the more-or-less standard C -library functions to avoid unnecessary loss of portability. - - * Don't use the return value of `sprintf'. It returns the number of - characters written on some systems, but not on all systems. - - * Be aware that `vfprintf' is not always available. - - * `main' should be declared to return type `int'. It should - terminate either by calling `exit' or by returning the integer - status code; make sure it cannot ever return an undefined value. - - * Don't declare system functions explicitly. - - Almost any declaration for a system function is wrong on some - system. To minimize conflicts, leave it to the system header - files to declare system functions. If the headers don't declare a - function, let it remain undeclared. - - While it may seem unclean to use a function without declaring it, - in practice this works fine for most system library functions on - the systems where this really happens; thus, the disadvantage is - only theoretical. By contrast, actual declarations have - frequently caused actual conflicts. - - * If you must declare a system function, don't specify the argument - types. Use an old-style declaration, not a Standard C prototype. - The more you specify about the function, the more likely a - conflict. - - * In particular, don't unconditionally declare `malloc' or `realloc'. - - Most GNU programs use those functions just once, in functions - conventionally named `xmalloc' and `xrealloc'. These functions - call `malloc' and `realloc', respectively, and check the results. - - Because `xmalloc' and `xrealloc' are defined in your program, you - can declare them in other files without any risk of type conflict. - - On most systems, `int' is the same length as a pointer; thus, the - calls to `malloc' and `realloc' work fine. For the few - exceptional systems (mostly 64-bit machines), you can use - *conditionalized* declarations of `malloc' and `realloc'--or put - these declarations in configuration files specific to those - systems. - - * The string functions require special treatment. Some Unix systems - have a header file `string.h'; others have `strings.h'. Neither - file name is portable. There are two things you can do: use - Autoconf to figure out which file to include, or don't include - either file. - - * If you don't include either strings file, you can't get - declarations for the string functions from the header file in the - usual way. - - That causes less of a problem than you might think. The newer - standard string functions should be avoided anyway because many - systems still don't support them. The string functions you can - use are these: - - strcpy strncpy strcat strncat - strlen strcmp strncmp - strchr strrchr - - The copy and concatenate functions work fine without a declaration - as long as you don't use their values. Using their values without - a declaration fails on systems where the width of a pointer - differs from the width of `int', and perhaps in other cases. It - is trivial to avoid using their values, so do that. - - The compare functions and `strlen' work fine without a declaration - on most systems, possibly all the ones that GNU software runs on. - You may find it necessary to declare them *conditionally* on a few - systems. - - The search functions must be declared to return `char *'. Luckily, - there is no variation in the data type they return. But there is - variation in their names. Some systems give these functions the - names `index' and `rindex'; other systems use the names `strchr' - and `strrchr'. Some systems support both pairs of names, but - neither pair works on all systems. - - You should pick a single pair of names and use it throughout your - program. (Nowadays, it is better to choose `strchr' and `strrchr' - for new programs, since those are the standard names.) Declare - both of those names as functions returning `char *'. On systems - which don't support those names, define them as macros in terms of - the other pair. For example, here is what to put at the beginning - of your file (or in a header) if you want to use the names - `strchr' and `strrchr' throughout: - - #ifndef HAVE_STRCHR - #define strchr index - #endif - #ifndef HAVE_STRRCHR - #define strrchr rindex - #endif - - char *strchr (); - char *strrchr (); - - Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros -defined in systems where the corresponding functions exist. One way to -get them properly defined is to use Autoconf. - - -File: standards.info, Node: Internationalization, Next: Mmap, Prev: System Functions, Up: Writing C - -5.8 Internationalization -======================== - -GNU has a library called GNU gettext that makes it easy to translate the -messages in a program into various languages. You should use this -library in every program. Use English for the messages as they appear -in the program, and let gettext provide the way to translate them into -other languages. - - Using GNU gettext involves putting a call to the `gettext' macro -around each string that might need translation--like this: - - printf (gettext ("Processing file `%s'...")); - -This permits GNU gettext to replace the string `"Processing file -`%s'..."' with a translated version. - - Once a program uses gettext, please make a point of writing calls to -`gettext' when you add new strings that call for translation. - - Using GNU gettext in a package involves specifying a "text domain -name" for the package. The text domain name is used to separate the -translations for this package from the translations for other packages. -Normally, the text domain name should be the same as the name of the -package--for example, `fileutils' for the GNU file utilities. - - To enable gettext to work well, avoid writing code that makes -assumptions about the structure of words or sentences. When you want -the precise text of a sentence to vary depending on the data, use two or -more alternative string constants each containing a complete sentences, -rather than inserting conditionalized words or phrases into a single -sentence framework. - - Here is an example of what not to do: - - printf ("%d file%s processed", nfiles, - nfiles != 1 ? "s" : ""); - -The problem with that example is that it assumes that plurals are made -by adding `s'. If you apply gettext to the format string, like this, - - printf (gettext ("%d file%s processed"), nfiles, - nfiles != 1 ? "s" : ""); - -the message can use different words, but it will still be forced to use -`s' for the plural. Here is a better way: - - printf ((nfiles != 1 ? "%d files processed" - : "%d file processed"), - nfiles); - -This way, you can apply gettext to each of the two strings -independently: - - printf ((nfiles != 1 ? gettext ("%d files processed") - : gettext ("%d file processed")), - nfiles); - -This can be any method of forming the plural of the word for "file", and -also handles languages that require agreement in the word for -"processed". - - A similar problem appears at the level of sentence structure with -this code: - - printf ("# Implicit rule search has%s been done.\n", - f->tried_implicit ? "" : " not"); - -Adding `gettext' calls to this code cannot give correct results for all -languages, because negation in some languages requires adding words at -more than one place in the sentence. By contrast, adding `gettext' -calls does the job straightfowardly if the code starts out like this: - - printf (f->tried_implicit - ? "# Implicit rule search has been done.\n", - : "# Implicit rule search has not been done.\n"); - - -File: standards.info, Node: Mmap, Prev: Internationalization, Up: Writing C - -5.9 Mmap -======== - -Don't assume that `mmap' either works on all files or fails for all -files. It may work on some files and fail on others. - - The proper way to use `mmap' is to try it on the specific file for -which you want to use it--and if `mmap' doesn't work, fall back on -doing the job in another way using `read' and `write'. - - The reason this precaution is needed is that the GNU kernel (the -HURD) provides a user-extensible file system, in which there can be many -different kinds of "ordinary files." Many of them support `mmap', but -some do not. It is important to make programs handle all these kinds -of files. - - -File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top - -6 Documenting Programs -********************** - -A GNU program should ideally come with full free documentation, adequate -for both reference and tutorial purposes. If the package can be -programmed or extended, the documentation should cover programming or -extending it, as well as just using it. - -* Menu: - -* GNU Manuals:: Writing proper manuals. -* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual. -* Manual Structure Details:: Specific structure conventions. -* License for Manuals:: Writing the distribution terms for a manual. -* Manual Credits:: Giving credit to documentation contributors. -* Printed Manuals:: Mentioning the printed manual. -* NEWS File:: NEWS files supplement manuals. -* Change Logs:: Recording Changes -* Man Pages:: Man pages are secondary. -* Reading other Manuals:: How far you can go in learning - from other manuals. - - -File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation - -6.1 GNU Manuals -=============== - -The preferred document format for the GNU system is the Texinfo -formatting language. Every GNU package should (ideally) have -documentation in Texinfo both for reference and for learners. Texinfo -makes it possible to produce a good quality formatted book, using TeX, -and to generate an Info file. It is also possible to generate HTML -output from Texinfo source. See the Texinfo manual, either the -hardcopy, or the on-line version available through `info' or the Emacs -Info subsystem (`C-h i'). - - Nowadays some other formats such as Docbook and Sgmltexi can be -converted automatically into Texinfo. It is ok to produce the Texinfo -documentation by conversion this way, as long as it gives good results. - - Programmers often find it most natural to structure the documentation -following the structure of the implementation, which they know. But -this structure is not necessarily good for explaining how to use the -program; it may be irrelevant and confusing for a user. - - At every level, from the sentences in a paragraph to the grouping of -topics into separate manuals, the right way to structure documentation -is according to the concepts and questions that a user will have in mind -when reading it. Sometimes this structure of ideas matches the -structure of the implementation of the software being documented--but -often they are different. Often the most important part of learning to -write good documentation is learning to notice when you are structuring -the documentation like the implementation, and think about better -alternatives. - - For example, each program in the GNU system probably ought to be -documented in one manual; but this does not mean each program should -have its own manual. That would be following the structure of the -implementation, rather than the structure that helps the user -understand. - - Instead, each manual should cover a coherent _topic_. For example, -instead of a manual for `diff' and a manual for `diff3', we have one -manual for "comparison of files" which covers both of those programs, -as well as `cmp'. By documenting these programs together, we can make -the whole subject clearer. - - The manual which discusses a program should certainly document all of -the program's command-line options and all of its commands. It should -give examples of their use. But don't organize the manual as a list of -features. Instead, organize it logically, by subtopics. Address the -questions that a user will ask when thinking about the job that the -program does. - - In general, a GNU manual should serve both as tutorial and reference. -It should be set up for convenient access to each topic through Info, -and for reading straight through (appendixes aside). A GNU manual -should give a good introduction to a beginner reading through from the -start, and should also provide all the details that hackers want. The -Bison manual is a good example of this--please take a look at it to see -what we mean. - - That is not as hard as it first sounds. Arrange each chapter as a -logical breakdown of its topic, but order the sections, and write their -text, so that reading the chapter straight through makes sense. Do -likewise when structuring the book into chapters, and when structuring a -section into paragraphs. The watchword is, _at each point, address the -most fundamental and important issue raised by the preceding text._ - - If necessary, add extra chapters at the beginning of the manual which -are purely tutorial and cover the basics of the subject. These provide -the framework for a beginner to understand the rest of the manual. The -Bison manual provides a good example of how to do this. - - To serve as a reference, a manual should have an Index that list all -the functions, variables, options, and important concepts that are part -of the program. One combined Index should do for a short manual, but -sometimes for a complex package it is better to use multiple indices. -The Texinfo manual includes advice on preparing good index entries, see -*Note Making Index Entries: (texinfo)Index Entries, and see *Note -Defining the Entries of an Index: (texinfo)Indexing Commands. - - Don't use Unix man pages as a model for how to write GNU -documentation; most of them are terse, badly structured, and give -inadequate explanation of the underlying concepts. (There are, of -course, some exceptions.) Also, Unix man pages use a particular format -which is different from what we use in GNU manuals. - - Please include an email address in the manual for where to report -bugs _in the manual_. - - Please do not use the term "pathname" that is used in Unix -documentation; use "file name" (two words) instead. We use the term -"path" only for search paths, which are lists of directory names. - - Please do not use the term "illegal" to refer to erroneous input to a -computer program. Please use "invalid" for this, and reserve the term -"illegal" for activities punishable by law. - - -File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation - -6.2 Doc Strings and Manuals -=========================== - -Some programming systems, such as Emacs, provide a documentation string -for each function, command or variable. You may be tempted to write a -reference manual by compiling the documentation strings and writing a -little additional text to go around them--but you must not do it. That -approach is a fundamental mistake. The text of well-written -documentation strings will be entirely wrong for a manual. - - A documentation string needs to stand alone--when it appears on the -screen, there will be no other text to introduce or explain it. -Meanwhile, it can be rather informal in style. - - The text describing a function or variable in a manual must not stand -alone; it appears in the context of a section or subsection. Other text -at the beginning of the section should explain some of the concepts, and -should often make some general points that apply to several functions or -variables. The previous descriptions of functions and variables in the -section will also have given information about the topic. A description -written to stand alone would repeat some of that information; this -redundance looks bad. Meanwhile, the informality that is acceptable in -a documentation string is totally unacceptable in a manual. - - The only good way to use documentation strings in writing a good -manual is to use them as a source of information for writing good text. - - -File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation - -6.3 Manual Structure Details -============================ - -The title page of the manual should state the version of the programs or -packages documented in the manual. The Top node of the manual should -also contain this information. If the manual is changing more -frequently than or independent of the program, also state a version -number for the manual in both of these places. - - Each program documented in the manual should have a node named -`PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with -its subnodes, if any) should describe the program's command line -arguments and how to run it (the sort of information people would look -in a man page for). Start with an `@example' containing a template for -all the options and arguments that the program uses. - - Alternatively, put a menu item in some menu whose item name fits one -of the above patterns. This identifies the node which that item points -to as the node for this purpose, regardless of the node's actual name. - - The `--usage' feature of the Info reader looks for such a node or -menu item in order to find the relevant text, so it is essential for -every Texinfo file to have one. - - If one manual describes several programs, it should have such a node -for each program described in the manual. - - -File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation - -6.4 License for Manuals -======================= - -Please use the GNU Free Documentation License for all GNU manuals that -are more than a few pages long. Likewise for a collection of short -documents--you only need one copy of the GNU FDL for the whole -collection. For a single short document, you can use a very permissive -non-copyleft license, to avoid taking up space with a long license. - - See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation -of how to employ the GFDL. - - Note that it is not obligatory to include a copy of the GNU GPL or -GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It -can be a good idea to include the program's license in a large manual; -in a short manual, whose size would be increased considerably by -including the program's license, it is probably better not to include -it. - - -File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation - -6.5 Manual Credits -================== - -Please credit the principal human writers of the manual as the authors, -on the title page of the manual. If a company sponsored the work, thank -the company in a suitable place in the manual, but do not cite the -company as an author. - - -File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation - -6.6 Printed Manuals -=================== - -The FSF publishes some GNU manuals in printed form. To encourage sales -of these manuals, the on-line versions of the manual should mention at -the very start that the printed manual is available and should point at -information for getting it--for instance, with a link to the page -`http://www.gnu.org/order/order.html'. This should not be included in -the printed manual, though, because there it is redundant. - - It is also useful to explain in the on-line forms of the manual how -the user can print out the manual from the sources. - - -File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation - -6.7 The NEWS File -================= - -In addition to its manual, the package should have a file named `NEWS' -which contains a list of user-visible changes worth mentioning. In -each new release, add items to the front of the file and identify the -version they pertain to. Don't discard old items; leave them in the -file after the newer items. This way, a user upgrading from any -previous version can see what is new. - - If the `NEWS' file gets very long, move some of the older items into -a file named `ONEWS' and put a note at the end referring the user to -that file. - - -File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation - -6.8 Change Logs -=============== - -Keep a change log to describe all the changes made to program source -files. The purpose of this is so that people investigating bugs in the -future will know about the changes that might have introduced the bug. -Often a new bug can be found by looking at what was recently changed. -More importantly, change logs can help you eliminate conceptual -inconsistencies between different parts of a program, by giving you a -history of how the conflicting concepts arose and who they came from. - -* Menu: - -* Change Log Concepts:: -* Style of Change Logs:: -* Simple Changes:: -* Conditional Changes:: -* Indicating the Part Changed:: - - -File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs - -6.8.1 Change Log Concepts -------------------------- - -You can think of the change log as a conceptual "undo list" which -explains how earlier versions were different from the current version. -People can see the current version; they don't need the change log to -tell them what is in it. What they want from a change log is a clear -explanation of how the earlier version differed. - - The change log file is normally called `ChangeLog' and covers an -entire directory. Each directory can have its own change log, or a -directory can use the change log of its parent directory-it's up to you. - - Another alternative is to record change log information with a -version control system such as RCS or CVS. This can be converted -automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the -command `C-x v a' (`vc-update-change-log') does the job. - - There's no need to describe the full purpose of the changes or how -they work together. If you think that a change calls for explanation, -you're probably right. Please do explain it--but please put the -explanation in comments in the code, where people will see it whenever -they see the code. For example, "New function" is enough for the -change log when you add a function, because there should be a comment -before the function definition to explain what it does. - - However, sometimes it is useful to write one line to describe the -overall purpose of a batch of changes. - - The easiest way to add an entry to `ChangeLog' is with the Emacs -command `M-x add-change-log-entry'. An entry should have an asterisk, -the name of the changed file, and then in parentheses the name of the -changed functions, variables or whatever, followed by a colon. Then -describe the changes you made to that function or variable. - - -File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs - -6.8.2 Style of Change Logs --------------------------- - -Here are some simple examples of change log entries, starting with the -header line that says who made the change and when, followed by -descriptions of specific changes. (These examples are drawn from Emacs -and GCC.) - - 1998-08-17 Richard Stallman <rms@gnu.org> - - * register.el (insert-register): Return nil. - (jump-to-register): Likewise. - - * sort.el (sort-subr): Return nil. - - * tex-mode.el (tex-bibtex-file, tex-file, tex-region): - Restart the tex shell if process is gone or stopped. - (tex-shell-running): New function. - - * expr.c (store_one_arg): Round size up for move_block_to_reg. - (expand_call): Round up when emitting USE insns. - * stmt.c (assign_parms): Round size up for move_block_from_reg. - - It's important to name the changed function or variable in full. -Don't abbreviate function or variable names, and don't combine them. -Subsequent maintainers will often search for a function name to find all -the change log entries that pertain to it; if you abbreviate the name, -they won't find it when they search. - - For example, some people are tempted to abbreviate groups of function -names by writing `* register.el ({insert,jump-to}-register)'; this is -not a good idea, since searching for `jump-to-register' or -`insert-register' would not find that entry. - - Separate unrelated change log entries with blank lines. When two -entries represent parts of the same change, so that they work together, -then don't put blank lines between them. Then you can omit the file -name and the asterisk when successive entries are in the same file. - - Break long lists of function names by closing continued lines with -`)', rather than `,', and opening the continuation with `(' as in this -example: - - * keyboard.c (menu_bar_items, tool_bar_items) - (Fexecute_extended_command): Deal with `keymap' property. - - -File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs - -6.8.3 Simple Changes --------------------- - -Certain simple kinds of changes don't need much detail in the change -log. - - When you change the calling sequence of a function in a simple -fashion, and you change all the callers of the function to use the new -calling sequence, there is no need to make individual entries for all -the callers that you changed. Just write in the entry for the function -being called, "All callers changed"--like this: - - * keyboard.c (Fcommand_execute): New arg SPECIAL. - All callers changed. - - When you change just comments or doc strings, it is enough to write -an entry for the file, without mentioning the functions. Just "Doc -fixes" is enough for the change log. - - There's no need to make change log entries for documentation files. -This is because documentation is not susceptible to bugs that are hard -to fix. Documentation does not consist of parts that must interact in a -precisely engineered fashion. To correct an error, you need not know -the history of the erroneous passage; it is enough to compare what the -documentation says with the way the program actually works. - - -File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs - -6.8.4 Conditional Changes -------------------------- - -C programs often contain compile-time `#if' conditionals. Many changes -are conditional; sometimes you add a new definition which is entirely -contained in a conditional. It is very useful to indicate in the -change log the conditions for which the change applies. - - Our convention for indicating conditional changes is to use square -brackets around the name of the condition. - - Here is a simple example, describing a change which is conditional -but does not have a function or entity name associated with it: - - * xterm.c [SOLARIS2]: Include string.h. - - Here is an entry describing a new definition which is entirely -conditional. This new definition for the macro `FRAME_WINDOW_P' is -used only when `HAVE_X_WINDOWS' is defined: - - * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. - - Here is an entry for a change within the function `init_display', -whose definition as a whole is unconditional, but the changes themselves -are contained in a `#ifdef HAVE_LIBNCURSES' conditional: - - * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. - - Here is an entry for a change that takes affect only when a certain -macro is _not_ defined: - - (gethostname) [!HAVE_SOCKETS]: Replace with winsock version. - - -File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs - -6.8.5 Indicating the Part Changed ---------------------------------- - -Indicate the part of a function which changed by using angle brackets -enclosing an indication of what the changed part does. Here is an entry -for a change in the part of the function `sh-while-getopts' that deals -with `sh' commands: - - * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that - user-specified option string is empty. - - -File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation - -6.9 Man Pages -============= - -In the GNU project, man pages are secondary. It is not necessary or -expected for every GNU program to have a man page, but some of them do. -It's your choice whether to include a man page in your program. - - When you make this decision, consider that supporting a man page -requires continual effort each time the program is changed. The time -you spend on the man page is time taken away from more useful work. - - For a simple program which changes little, updating the man page may -be a small job. Then there is little reason not to include a man page, -if you have one. - - For a large program that changes a great deal, updating a man page -may be a substantial burden. If a user offers to donate a man page, -you may find this gift costly to accept. It may be better to refuse -the man page unless the same person agrees to take full responsibility -for maintaining it--so that you can wash your hands of it entirely. If -this volunteer later ceases to do the job, then don't feel obliged to -pick it up yourself; it may be better to withdraw the man page from the -distribution until someone else agrees to update it. - - When a program changes only a little, you may feel that the -discrepancies are small enough that the man page remains useful without -updating. If so, put a prominent note near the beginning of the man -page explaining that you don't maintain it and that the Texinfo manual -is more authoritative. The note should say how to access the Texinfo -documentation. - - -File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation - -6.10 Reading other Manuals -========================== - -There may be non-free books or documentation files that describe the -program you are documenting. - - It is ok to use these documents for reference, just as the author of -a new algebra textbook can read other books on algebra. A large portion -of any non-fiction book consists of facts, in this case facts about how -a certain program works, and these facts are necessarily the same for -everyone who writes about the subject. But be careful not to copy your -outline structure, wording, tables or examples from preexisting non-free -documentation. Copying from free documentation may be ok; please check -with the FSF about the individual case. - - -File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top - -7 The Release Process -********************* - -Making a release is more than just bundling up your source files in a -tar file and putting it up for FTP. You should set up your software so -that it can be configured to run on a variety of systems. Your Makefile -should conform to the GNU standards described below, and your directory -layout should also conform to the standards discussed below. Doing so -makes it easy to include your package into the larger framework of all -GNU software. - -* Menu: - -* Configuration:: How Configuration Should Work -* Makefile Conventions:: Makefile Conventions -* Releases:: Making Releases - - -File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases - -7.1 How Configuration Should Work -================================= - -Each GNU distribution should come with a shell script named -`configure'. This script is given arguments which describe the kind of -machine and system you want to compile the program for. - - The `configure' script must record the configuration options so that -they affect compilation. - - One way to do this is to make a link from a standard name such as -`config.h' to the proper configuration file for the chosen system. If -you use this technique, the distribution should _not_ contain a file -named `config.h'. This is so that people won't be able to build the -program without configuring it first. - - Another thing that `configure' can do is to edit the Makefile. If -you do this, the distribution should _not_ contain a file named -`Makefile'. Instead, it should include a file `Makefile.in' which -contains the input used for editing. Once again, this is so that people -won't be able to build the program without configuring it first. - - If `configure' does write the `Makefile', then `Makefile' should -have a target named `Makefile' which causes `configure' to be rerun, -setting up the same configuration that was set up last time. The files -that `configure' reads should be listed as dependencies of `Makefile'. - - All the files which are output from the `configure' script should -have comments at the beginning explaining that they were generated -automatically using `configure'. This is so that users won't think of -trying to edit them by hand. - - The `configure' script should write a file named `config.status' -which describes which configuration options were specified when the -program was last configured. This file should be a shell script which, -if run, will recreate the same configuration. - - The `configure' script should accept an option of the form -`--srcdir=DIRNAME' to specify the directory where sources are found (if -it is not the current directory). This makes it possible to build the -program in a separate directory, so that the actual source directory is -not modified. - - If the user does not specify `--srcdir', then `configure' should -check both `.' and `..' to see if it can find the sources. If it finds -the sources in one of these places, it should use them from there. -Otherwise, it should report that it cannot find the sources, and should -exit with nonzero status. - - Usually the easy way to support `--srcdir' is by editing a -definition of `VPATH' into the Makefile. Some rules may need to refer -explicitly to the specified source directory. To make this possible, -`configure' can add to the Makefile a variable named `srcdir' whose -value is precisely the specified directory. - - The `configure' script should also take an argument which specifies -the type of system to build the program for. This argument should look -like this: - - CPU-COMPANY-SYSTEM - - For example, a Sun 3 might be `m68k-sun-sunos4.1'. - - The `configure' script needs to be able to decode all plausible -alternatives for how to describe a machine. Thus, `sun3-sunos4.1' -would be a valid alias. For many programs, `vax-dec-ultrix' would be -an alias for `vax-dec-bsd', simply because the differences between -Ultrix and BSD are rarely noticeable, but a few programs might need to -distinguish them. - - There is a shell script called `config.sub' that you can use as a -subroutine to validate system types and canonicalize aliases. - - Other options are permitted to specify in more detail the software -or hardware present on the machine, and include or exclude optional -parts of the package: - -`--enable-FEATURE[=PARAMETER]' - Configure the package to build and install an optional user-level - facility called FEATURE. This allows users to choose which - optional features to include. Giving an optional PARAMETER of - `no' should omit FEATURE, if it is built by default. - - No `--enable' option should *ever* cause one feature to replace - another. No `--enable' option should ever substitute one useful - behavior for another useful behavior. The only proper use for - `--enable' is for questions of whether to build part of the program - or exclude it. - -`--with-PACKAGE' - The package PACKAGE will be installed, so configure this package - to work with PACKAGE. - - Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld', - `gnu-libc', `gdb', `x', and `x-toolkit'. - - Do not use a `--with' option to specify the file name to use to - find certain files. That is outside the scope of what `--with' - options are for. - - All `configure' scripts should accept all of these "detail" options, -whether or not they make any difference to the particular package at -hand. In particular, they should accept any option that starts with -`--with-' or `--enable-'. This is so users will be able to configure -an entire GNU source tree at once with a single set of options. - - You will note that the categories `--with-' and `--enable-' are -narrow: they *do not* provide a place for any sort of option you might -think of. That is deliberate. We want to limit the possible -configuration options in GNU software. We do not want GNU programs to -have idiosyncratic configuration options. - - Packages that perform part of the compilation process may support -cross-compilation. In such a case, the host and target machines for the -program may be different. - - The `configure' script should normally treat the specified type of -system as both the host and the target, thus producing a program which -works for the same type of machine that it runs on. - - To configure a cross-compiler, cross-assembler, or what have you, you -should specify a target different from the host, using the configure -option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as -for the host type. So the command would look like this: - - ./configure HOSTTYPE --target=TARGETTYPE - - Programs for which cross-operation is not meaningful need not accept -the `--target' option, because configuring an entire operating system -for cross-operation is not a meaningful operation. - - Bootstrapping a cross-compiler requires compiling it on a machine -other than the host it will run on. Compilation packages accept a -configuration option `--build=BUILDTYPE' for specifying the -configuration on which you will compile them, but the configure script -should normally guess the build machine type (using `config.guess'), so -this option is probably not necessary. The host and target types -normally default from the build type, so in bootstrapping a -cross-compiler you must specify them both explicitly. - - Some programs have ways of configuring themselves automatically. If -your program is set up to do this, your `configure' script can simply -ignore most of its arguments. - - -File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases - -7.2 Makefile Conventions -======================== - -This node describes conventions for writing the Makefiles for GNU -programs. Using Automake will help you write a Makefile that follows -these conventions. - -* Menu: - -* Makefile Basics:: General Conventions for Makefiles -* Utilities in Makefiles:: Utilities in Makefiles -* Command Variables:: Variables for Specifying Commands -* Directory Variables:: Variables for Installation Directories -* Standard Targets:: Standard Targets for Users -* Install Command Categories:: Three categories of commands in the `install' - rule: normal, pre-install and post-install. - - -File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions - -7.2.1 General Conventions for Makefiles ---------------------------------------- - -Every Makefile should contain this line: - - SHELL = /bin/sh - -to avoid trouble on systems where the `SHELL' variable might be -inherited from the environment. (This is never a problem with GNU -`make'.) - - Different `make' programs have incompatible suffix lists and -implicit rules, and this sometimes creates confusion or misbehavior. So -it is a good idea to set the suffix list explicitly using only the -suffixes you need in the particular Makefile, like this: - - .SUFFIXES: - .SUFFIXES: .c .o - -The first line clears out the suffix list, the second introduces all -suffixes which may be subject to implicit rules in this Makefile. - - Don't assume that `.' is in the path for command execution. When -you need to run programs that are a part of your package during the -make, please make sure that it uses `./' if the program is built as -part of the make or `$(srcdir)/' if the file is an unchanging part of -the source code. Without one of these prefixes, the current search -path is used. - - The distinction between `./' (the "build directory") and -`$(srcdir)/' (the "source directory") is important because users can -build in a separate directory using the `--srcdir' option to -`configure'. A rule of the form: - - foo.1 : foo.man sedscript - sed -e sedscript foo.man > foo.1 - -will fail when the build directory is not the source directory, because -`foo.man' and `sedscript' are in the source directory. - - When using GNU `make', relying on `VPATH' to find the source file -will work in the case where there is a single dependency file, since -the `make' automatic variable `$<' will represent the source file -wherever it is. (Many versions of `make' set `$<' only in implicit -rules.) A Makefile target like - - foo.o : bar.c - $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o - -should instead be written as - - foo.o : bar.c - $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@ - -in order to allow `VPATH' to work correctly. When the target has -multiple dependencies, using an explicit `$(srcdir)' is the easiest way -to make the rule work well. For example, the target above for `foo.1' -is best written as: - - foo.1 : foo.man sedscript - sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@ - - GNU distributions usually contain some files which are not source -files--for example, Info files, and the output from Autoconf, Automake, -Bison or Flex. Since these files normally appear in the source -directory, they should always appear in the source directory, not in the -build directory. So Makefile rules to update them should put the -updated files in the source directory. - - However, if a file does not appear in the distribution, then the -Makefile should not put it in the source directory, because building a -program in ordinary circumstances should not modify the source directory -in any way. - - Try to make the build and installation targets, at least (and all -their subtargets) work correctly with a parallel `make'. - - -File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions - -7.2.2 Utilities in Makefiles ----------------------------- - -Write the Makefile commands (and any shell scripts, such as -`configure') to run in `sh', not in `csh'. Don't use any special -features of `ksh' or `bash'. - - The `configure' script and the Makefile rules for building and -installation should not use any utilities directly except these: - - cat cmp cp diff echo egrep expr false grep install-info - ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true - - The compression program `gzip' can be used in the `dist' rule. - - Stick to the generally supported options for these programs. For -example, don't use `mkdir -p', convenient as it may be, because most -systems don't support it. - - It is a good idea to avoid creating symbolic links in makefiles, -since a few systems don't support them. - - The Makefile rules for building and installation can also use -compilers and related programs, but should do so via `make' variables -so that the user can substitute alternatives. Here are some of the -programs we mean: - - ar bison cc flex install ld ldconfig lex - make makeinfo ranlib texi2dvi yacc - - Use the following `make' variables to run those programs: - - $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) - $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) - - When you use `ranlib' or `ldconfig', you should make sure nothing -bad happens if the system does not have the program in question. -Arrange to ignore an error from that command, and print a message before -the command to tell the user that failure of this command does not mean -a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.) - - If you use symbolic links, you should implement a fallback for -systems that don't have symbolic links. - - Additional utilities that can be used via Make variables are: - - chgrp chmod chown mknod - - It is ok to use other utilities in Makefile portions (or scripts) -intended only for particular systems where you know those utilities -exist. - - -File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions - -7.2.3 Variables for Specifying Commands ---------------------------------------- - -Makefiles should provide variables for overriding certain commands, -options, and so on. - - In particular, you should run most utility programs via variables. -Thus, if you use Bison, have a variable named `BISON' whose default -value is set with `BISON = bison', and refer to it with `$(BISON)' -whenever you need to use Bison. - - File management utilities such as `ln', `rm', `mv', and so on, need -not be referred to through variables in this way, since users don't -need to replace them with other programs. - - Each program-name variable should come with an options variable that -is used to supply options to the program. Append `FLAGS' to the -program-name variable name to get the options variable name--for -example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler, -`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule, -but we keep them because they are standard.) Use `CPPFLAGS' in any -compilation command that runs the preprocessor, and use `LDFLAGS' in -any compilation command that does linking as well as in any direct use -of `ld'. - - If there are C compiler options that _must_ be used for proper -compilation of certain files, do not include them in `CFLAGS'. Users -expect to be able to specify `CFLAGS' freely themselves. Instead, -arrange to pass the necessary options to the C compiler independently -of `CFLAGS', by writing them explicitly in the compilation commands or -by defining an implicit rule, like this: - - CFLAGS = -g - ALL_CFLAGS = -I. $(CFLAGS) - .c.o: - $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< - - Do include the `-g' option in `CFLAGS', because that is not -_required_ for proper compilation. You can consider it a default that -is only recommended. If the package is set up so that it is compiled -with GCC by default, then you might as well include `-O' in the default -value of `CFLAGS' as well. - - Put `CFLAGS' last in the compilation command, after other variables -containing compiler options, so the user can use `CFLAGS' to override -the others. - - `CFLAGS' should be used in every invocation of the C compiler, both -those which do compilation and those which do linking. - - Every Makefile should define the variable `INSTALL', which is the -basic command for installing a file into the system. - - Every Makefile should also define the variables `INSTALL_PROGRAM' -and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be -`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m -644'.) Then it should use those variables as the commands for actual -installation, for executables and nonexecutables respectively. Use -these variables as follows: - - $(INSTALL_PROGRAM) foo $(bindir)/foo - $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a - - Optionally, you may prepend the value of `DESTDIR' to the target -filename. Doing this allows the installer to create a snapshot of the -installation to be copied onto the real target filesystem later. Do not -set the value of `DESTDIR' in your Makefile, and do not include it in -any installed files. With support for `DESTDIR', the above examples -become: - - $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo - $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a - -Always use a file name, not a directory name, as the second argument of -the installation commands. Use a separate command for each file to be -installed. - - -File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions - -7.2.4 Variables for Installation Directories --------------------------------------------- - -Installation directories should always be named by variables, so it is -easy to install in a nonstandard place. The standard names for these -variables are described below. They are based on a standard filesystem -layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4, -and other modern operating systems. - - These two variables set the root for the installation. All the other -installation directories should be subdirectories of one of these two, -and nothing should be directly installed into these two directories. - -`prefix' - A prefix used in constructing the default values of the variables - listed below. The default value of `prefix' should be - `/usr/local'. When building the complete GNU system, the prefix - will be empty and `/usr' will be a symbolic link to `/'. (If you - are using Autoconf, write it as `@prefix@'.) - - Running `make install' with a different value of `prefix' from the - one used to build the program should _not_ recompile the program. - -`exec_prefix' - A prefix used in constructing the default values of some of the - variables listed below. The default value of `exec_prefix' should - be `$(prefix)'. (If you are using Autoconf, write it as - `@exec_prefix@'.) - - Generally, `$(exec_prefix)' is used for directories that contain - machine-specific files (such as executables and subroutine - libraries), while `$(prefix)' is used directly for other - directories. - - Running `make install' with a different value of `exec_prefix' - from the one used to build the program should _not_ recompile the - program. - - Executable programs are installed in one of the following -directories. - -`bindir' - The directory for installing executable programs that users can - run. This should normally be `/usr/local/bin', but write it as - `$(exec_prefix)/bin'. (If you are using Autoconf, write it as - `@bindir@'.) - -`sbindir' - The directory for installing executable programs that can be run - from the shell, but are only generally useful to system - administrators. This should normally be `/usr/local/sbin', but - write it as `$(exec_prefix)/sbin'. (If you are using Autoconf, - write it as `@sbindir@'.) - -`libexecdir' - The directory for installing executable programs to be run by other - programs rather than by users. This directory should normally be - `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'. - (If you are using Autoconf, write it as `@libexecdir@'.) - - Data files used by the program during its execution are divided into -categories in two ways. - - * Some files are normally modified by programs; others are never - normally modified (though users may edit some of these). - - * Some files are architecture-independent and can be shared by all - machines at a site; some are architecture-dependent and can be - shared only by machines of the same kind and operating system; - others may never be shared between two machines. - - This makes for six different possibilities. However, we want to -discourage the use of architecture-dependent files, aside from object -files and libraries. It is much cleaner to make other data files -architecture-independent, and it is generally not hard. - - Therefore, here are the variables Makefiles should use to specify -directories: - -`datadir' - The directory for installing read-only architecture independent - data files. This should normally be `/usr/local/share', but write - it as `$(prefix)/share'. (If you are using Autoconf, write it as - `@datadir@'.) As a special exception, see `$(infodir)' and - `$(includedir)' below. - -`sysconfdir' - The directory for installing read-only data files that pertain to a - single machine-that is to say, files for configuring a host. - Mailer and network configuration files, `/etc/passwd', and so - forth belong here. All the files in this directory should be - ordinary ASCII text files. This directory should normally be - `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are - using Autoconf, write it as `@sysconfdir@'.) - - Do not install executables here in this directory (they probably - belong in `$(libexecdir)' or `$(sbindir)'). Also do not install - files that are modified in the normal course of their use (programs - whose purpose is to change the configuration of the system - excluded). Those probably belong in `$(localstatedir)'. - -`sharedstatedir' - The directory for installing architecture-independent data files - which the programs modify while they run. This should normally be - `/usr/local/com', but write it as `$(prefix)/com'. (If you are - using Autoconf, write it as `@sharedstatedir@'.) - -`localstatedir' - The directory for installing data files which the programs modify - while they run, and that pertain to one specific machine. Users - should never need to modify files in this directory to configure - the package's operation; put such configuration information in - separate files that go in `$(datadir)' or `$(sysconfdir)'. - `$(localstatedir)' should normally be `/usr/local/var', but write - it as `$(prefix)/var'. (If you are using Autoconf, write it as - `@localstatedir@'.) - -`libdir' - The directory for object files and libraries of object code. Do - not install executables here, they probably ought to go in - `$(libexecdir)' instead. The value of `libdir' should normally be - `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you - are using Autoconf, write it as `@libdir@'.) - -`infodir' - The directory for installing the Info files for this package. By - default, it should be `/usr/local/info', but it should be written - as `$(prefix)/info'. (If you are using Autoconf, write it as - `@infodir@'.) - -`lispdir' - The directory for installing any Emacs Lisp files in this package. - By default, it should be `/usr/local/share/emacs/site-lisp', but - it should be written as `$(prefix)/share/emacs/site-lisp'. - - If you are using Autoconf, write the default as `@lispdir@'. In - order to make `@lispdir@' work, you need the following lines in - your `configure.in' file: - - lispdir='${datadir}/emacs/site-lisp' - AC_SUBST(lispdir) - -`includedir' - The directory for installing header files to be included by user - programs with the C `#include' preprocessor directive. This - should normally be `/usr/local/include', but write it as - `$(prefix)/include'. (If you are using Autoconf, write it as - `@includedir@'.) - - Most compilers other than GCC do not look for header files in - directory `/usr/local/include'. So installing the header files - this way is only useful with GCC. Sometimes this is not a problem - because some libraries are only really intended to work with GCC. - But some libraries are intended to work with other compilers. - They should install their header files in two places, one - specified by `includedir' and one specified by `oldincludedir'. - -`oldincludedir' - The directory for installing `#include' header files for use with - compilers other than GCC. This should normally be `/usr/include'. - (If you are using Autoconf, you can write it as `@oldincludedir@'.) - - The Makefile commands should check whether the value of - `oldincludedir' is empty. If it is, they should not try to use - it; they should cancel the second installation of the header files. - - A package should not replace an existing header in this directory - unless the header came from the same package. Thus, if your Foo - package provides a header file `foo.h', then it should install the - header file in the `oldincludedir' directory if either (1) there - is no `foo.h' there or (2) the `foo.h' that exists came from the - Foo package. - - To tell whether `foo.h' came from the Foo package, put a magic - string in the file--part of a comment--and `grep' for that string. - - Unix-style man pages are installed in one of the following: - -`mandir' - The top-level directory for installing the man pages (if any) for - this package. It will normally be `/usr/local/man', but you should - write it as `$(prefix)/man'. (If you are using Autoconf, write it - as `@mandir@'.) - -`man1dir' - The directory for installing section 1 man pages. Write it as - `$(mandir)/man1'. - -`man2dir' - The directory for installing section 2 man pages. Write it as - `$(mandir)/man2' - -`...' - *Don't make the primary documentation for any GNU software be a - man page. Write a manual in Texinfo instead. Man pages are just - for the sake of people running GNU software on Unix, which is a - secondary application only.* - -`manext' - The file name extension for the installed man page. This should - contain a period followed by the appropriate digit; it should - normally be `.1'. - -`man1ext' - The file name extension for installed section 1 man pages. - -`man2ext' - The file name extension for installed section 2 man pages. - -`...' - Use these names instead of `manext' if the package needs to - install man pages in more than one section of the manual. - - And finally, you should set the following variable: - -`srcdir' - The directory for the sources being compiled. The value of this - variable is normally inserted by the `configure' shell script. - (If you are using Autconf, use `srcdir = @srcdir@'.) - - For example: - - # Common prefix for installation directories. - # NOTE: This directory must exist when you start the install. - prefix = /usr/local - exec_prefix = $(prefix) - # Where to put the executable for the command `gcc'. - bindir = $(exec_prefix)/bin - # Where to put the directories used by the compiler. - libexecdir = $(exec_prefix)/libexec - # Where to put the Info files. - infodir = $(prefix)/info - - If your program installs a large number of files into one of the -standard user-specified directories, it might be useful to group them -into a subdirectory particular to that program. If you do this, you -should write the `install' rule to create these subdirectories. - - Do not expect the user to include the subdirectory name in the value -of any of the variables listed above. The idea of having a uniform set -of variable names for installation directories is to enable the user to -specify the exact same values for several different GNU packages. In -order for this to be useful, all the packages must be designed so that -they will work sensibly when the user does so. - - -File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions - -7.2.5 Standard Targets for Users --------------------------------- - -All GNU programs should have the following targets in their Makefiles: - -`all' - Compile the entire program. This should be the default target. - This target need not rebuild any documentation files; Info files - should normally be included in the distribution, and DVI files - should be made only when explicitly asked for. - - By default, the Make rules should compile and link with `-g', so - that executable programs have debugging symbols. Users who don't - mind being helpless can strip the executables later if they wish. - -`install' - Compile the program and copy the executables, libraries, and so on - to the file names where they should reside for actual use. If - there is a simple test to verify that a program is properly - installed, this target should run that test. - - Do not strip executables when installing them. Devil-may-care - users can use the `install-strip' target to do that. - - If possible, write the `install' target rule so that it does not - modify anything in the directory where the program was built, - provided `make all' has just been done. This is convenient for - building the program under one user name and installing it under - another. - - The commands should create all the directories in which files are - to be installed, if they don't already exist. This includes the - directories specified as the values of the variables `prefix' and - `exec_prefix', as well as all subdirectories that are needed. One - way to do this is by means of an `installdirs' target as described - below. - - Use `-' before any command for installing a man page, so that - `make' will ignore any errors. This is in case there are systems - that don't have the Unix man page documentation system installed. - - The way to install Info files is to copy them into `$(infodir)' - with `$(INSTALL_DATA)' (*note Command Variables::), and then run - the `install-info' program if it is present. `install-info' is a - program that edits the Info `dir' file to add or update the menu - entry for the given Info file; it is part of the Texinfo package. - Here is a sample rule to install an Info file: - - $(DESTDIR)$(infodir)/foo.info: foo.info - $(POST_INSTALL) - # There may be a newer info file in . than in srcdir. - -if test -f foo.info; then d=.; \ - else d=$(srcdir); fi; \ - $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \ - # Run install-info only if it exists. - # Use `if' instead of just prepending `-' to the - # line so we notice real errors from install-info. - # We use `$(SHELL) -c' because some shells do not - # fail gracefully when there is an unknown command. - if $(SHELL) -c 'install-info --version' \ - >/dev/null 2>&1; then \ - install-info --dir-file=$(DESTDIR)$(infodir)/dir \ - $(DESTDIR)$(infodir)/foo.info; \ - else true; fi - - When writing the `install' target, you must classify all the - commands into three categories: normal ones, "pre-installation" - commands and "post-installation" commands. *Note Install Command - Categories::. - -`uninstall' - Delete all the installed files--the copies that the `install' - target creates. - - This rule should not modify the directories where compilation is - done, only the directories where files are installed. - - The uninstallation commands are divided into three categories, - just like the installation commands. *Note Install Command - Categories::. - -`install-strip' - Like `install', but strip the executable files while installing - them. In simple cases, this target can use the `install' target in - a simple way: - - install-strip: - $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ - install - - But if the package installs scripts as well as real executables, - the `install-strip' target can't just refer to the `install' - target; it has to strip the executables but not the scripts. - - `install-strip' should not strip the executables in the build - directory which are being copied for installation. It should only - strip the copies that are installed. - - Normally we do not recommend stripping an executable unless you - are sure the program has no bugs. However, it can be reasonable - to install a stripped executable for actual execution while saving - the unstripped executable elsewhere in case there is a bug. - -`clean' - Delete all files from the current directory that are normally - created by building the program. Don't delete the files that - record the configuration. Also preserve files that could be made - by building, but normally aren't because the distribution comes - with them. - - Delete `.dvi' files here if they are not part of the distribution. - -`distclean' - Delete all files from the current directory that are created by - configuring or building the program. If you have unpacked the - source and built the program without creating any other files, - `make distclean' should leave only the files that were in the - distribution. - -`mostlyclean' - Like `clean', but may refrain from deleting a few files that people - normally don't want to recompile. For example, the `mostlyclean' - target for GCC does not delete `libgcc.a', because recompiling it - is rarely necessary and takes a lot of time. - -`maintainer-clean' - Delete almost everything from the current directory that can be - reconstructed with this Makefile. This typically includes - everything deleted by `distclean', plus more: C source files - produced by Bison, tags tables, Info files, and so on. - - The reason we say "almost everything" is that running the command - `make maintainer-clean' should not delete `configure' even if - `configure' can be remade using a rule in the Makefile. More - generally, `make maintainer-clean' should not delete anything that - needs to exist in order to run `configure' and then begin to build - the program. This is the only exception; `maintainer-clean' should - delete everything else that can be rebuilt. - - The `maintainer-clean' target is intended to be used by a - maintainer of the package, not by ordinary users. You may need - special tools to reconstruct some of the files that `make - maintainer-clean' deletes. Since these files are normally - included in the distribution, we don't take care to make them easy - to reconstruct. If you find you need to unpack the full - distribution again, don't blame us. - - To help make users aware of this, the commands for the special - `maintainer-clean' target should start with these two: - - @echo 'This command is intended for maintainers to use; it' - @echo 'deletes files that may need special tools to rebuild.' - -`TAGS' - Update a tags table for this program. - -`info' - Generate any Info files needed. The best way to write the rules - is as follows: - - info: foo.info - - foo.info: foo.texi chap1.texi chap2.texi - $(MAKEINFO) $(srcdir)/foo.texi - - You must define the variable `MAKEINFO' in the Makefile. It should - run the `makeinfo' program, which is part of the Texinfo - distribution. - - Normally a GNU distribution comes with Info files, and that means - the Info files are present in the source directory. Therefore, - the Make rule for an info file should update it in the source - directory. When users build the package, ordinarily Make will not - update the Info files because they will already be up to date. - -`dvi' - Generate DVI files for all Texinfo documentation. For example: - - dvi: foo.dvi - - foo.dvi: foo.texi chap1.texi chap2.texi - $(TEXI2DVI) $(srcdir)/foo.texi - - You must define the variable `TEXI2DVI' in the Makefile. It should - run the program `texi2dvi', which is part of the Texinfo - distribution.(1) Alternatively, write just the dependencies, and - allow GNU `make' to provide the command. - -`dist' - Create a distribution tar file for this program. The tar file - should be set up so that the file names in the tar file start with - a subdirectory name which is the name of the package it is a - distribution for. This name can include the version number. - - For example, the distribution tar file of GCC version 1.40 unpacks - into a subdirectory named `gcc-1.40'. - - The easiest way to do this is to create a subdirectory - appropriately named, use `ln' or `cp' to install the proper files - in it, and then `tar' that subdirectory. - - Compress the tar file with `gzip'. For example, the actual - distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'. - - The `dist' target should explicitly depend on all non-source files - that are in the distribution, to make sure they are up to date in - the distribution. *Note Making Releases: Releases. - -`check' - Perform self-tests (if any). The user must build the program - before running the tests, but need not install the program; you - should write the self-tests so that they work when the program is - built but not installed. - - The following targets are suggested as conventional names, for -programs in which they are useful. - -`installcheck' - Perform installation tests (if any). The user must build and - install the program before running the tests. You should not - assume that `$(bindir)' is in the search path. - -`installdirs' - It's useful to add a target named `installdirs' to create the - directories where files are installed, and their parent - directories. There is a script called `mkinstalldirs' which is - convenient for this; you can find it in the Texinfo package. You - can use a rule like this: - - # Make sure all installation directories (e.g. $(bindir)) - # actually exist by making them if necessary. - installdirs: mkinstalldirs - $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ - $(libdir) $(infodir) \ - $(mandir) - - or, if you wish to support `DESTDIR', - - # Make sure all installation directories (e.g. $(bindir)) - # actually exist by making them if necessary. - installdirs: mkinstalldirs - $(srcdir)/mkinstalldirs \ - $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ - $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ - $(DESTDIR)$(mandir) - - This rule should not modify the directories where compilation is - done. It should do nothing but create installation directories. - - ---------- Footnotes ---------- - - (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is -not distributed with Texinfo. - - -File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions - -7.2.6 Install Command Categories --------------------------------- - -When writing the `install' target, you must classify all the commands -into three categories: normal ones, "pre-installation" commands and -"post-installation" commands. - - Normal commands move files into their proper places, and set their -modes. They may not alter any files except the ones that come entirely -from the package they belong to. - - Pre-installation and post-installation commands may alter other -files; in particular, they can edit global configuration files or data -bases. - - Pre-installation commands are typically executed before the normal -commands, and post-installation commands are typically run after the -normal commands. - - The most common use for a post-installation command is to run -`install-info'. This cannot be done with a normal command, since it -alters a file (the Info directory) which does not come entirely and -solely from the package being installed. It is a post-installation -command because it needs to be done after the normal command which -installs the package's Info files. - - Most programs don't need any pre-installation commands, but we have -the feature just in case it is needed. - - To classify the commands in the `install' rule into these three -categories, insert "category lines" among them. A category line -specifies the category for the commands that follow. - - A category line consists of a tab and a reference to a special Make -variable, plus an optional comment at the end. There are three -variables you can use, one for each category; the variable name -specifies the category. Category lines are no-ops in ordinary execution -because these three Make variables are normally undefined (and you -_should not_ define them in the makefile). - - Here are the three possible category lines, each with a comment that -explains what it means: - - $(PRE_INSTALL) # Pre-install commands follow. - $(POST_INSTALL) # Post-install commands follow. - $(NORMAL_INSTALL) # Normal commands follow. - - If you don't use a category line at the beginning of the `install' -rule, all the commands are classified as normal until the first category -line. If you don't use any category lines, all the commands are -classified as normal. - - These are the category lines for `uninstall': - - $(PRE_UNINSTALL) # Pre-uninstall commands follow. - $(POST_UNINSTALL) # Post-uninstall commands follow. - $(NORMAL_UNINSTALL) # Normal commands follow. - - Typically, a pre-uninstall command would be used for deleting entries -from the Info directory. - - If the `install' or `uninstall' target has any dependencies which -act as subroutines of installation, then you should start _each_ -dependency's commands with a category line, and start the main target's -commands with a category line also. This way, you can ensure that each -command is placed in the right category regardless of which of the -dependencies actually run. - - Pre-installation and post-installation commands should not run any -programs except for these: - - [ basename bash cat chgrp chmod chown cmp cp dd diff echo - egrep expand expr false fgrep find getopt grep gunzip gzip - hostname install install-info kill ldconfig ln ls md5sum - mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee - test touch true uname xargs yes - - The reason for distinguishing the commands in this way is for the -sake of making binary packages. Typically a binary package contains -all the executables and other files that need to be installed, and has -its own method of installing them--so it does not need to run the normal -installation commands. But installing the binary package does need to -execute the pre-installation and post-installation commands. - - Programs to build binary packages work by extracting the -pre-installation and post-installation commands. Here is one way of -extracting the pre-installation commands: - - make -n install -o all \ - PRE_INSTALL=pre-install \ - POST_INSTALL=post-install \ - NORMAL_INSTALL=normal-install \ - | gawk -f pre-install.awk - -where the file `pre-install.awk' could contain this: - - $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0} - on {print $0} - $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1} - - The resulting file of pre-installation commands is executed as a -shell script as part of installing the binary package. - - -File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases - -7.3 Making Releases -=================== - -Package the distribution of `Foo version 69.96' up in a gzipped tar -file with the name `foo-69.96.tar.gz'. It should unpack into a -subdirectory named `foo-69.96'. - - Building and installing the program should never modify any of the -files contained in the distribution. This means that all the files -that form part of the program in any way must be classified into "source -files" and "non-source files". Source files are written by humans and -never changed automatically; non-source files are produced from source -files by programs under the control of the Makefile. - - The distribution should contain a file named `README' which gives -the name of the package, and a general description of what it does. It -is also good to explain the purpose of each of the first-level -subdirectories in the package, if there are any. The `README' file -should either state the version number of the package, or refer to where -in the package it can be found. - - The `README' file should refer to the file `INSTALL', which should -contain an explanation of the installation procedure. - - The `README' file should also refer to the file which contains the -copying conditions. The GNU GPL, if used, should be in a file called -`COPYING'. If the GNU LGPL is used, it should be in a file called -`COPYING.LIB'. - - Naturally, all the source files must be in the distribution. It is -okay to include non-source files in the distribution, provided they are -up-to-date and machine-independent, so that building the distribution -normally will never modify them. We commonly include non-source files -produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid -unnecessary dependencies between our distributions, so that users can -install whichever packages they want to install. - - Non-source files that might actually be modified by building and -installing the program should *never* be included in the distribution. -So if you do distribute non-source files, always make sure they are up -to date when you make a new distribution. - - Make sure that the directory into which the distribution unpacks (as -well as any subdirectories) are all world-writable (octal mode 777). -This is so that old versions of `tar' which preserve the ownership and -permissions of the files from the tar archive will be able to extract -all the files even if the user is unprivileged. - - Make sure that all the files in the distribution are world-readable. - - Make sure that no file name in the distribution is more than 14 -characters long. Likewise, no file created by building the program -should have a name longer than 14 characters. The reason for this is -that some systems adhere to a foolish interpretation of the POSIX -standard, and refuse to open a longer name, rather than truncating as -they did in the past. - - Don't include any symbolic links in the distribution itself. If the -tar file contains symbolic links, then people cannot even unpack it on -systems that don't support symbolic links. Also, don't use multiple -names for one file in different directories, because certain file -systems cannot handle this and that prevents unpacking the distribution. - - Try to make sure that all the file names will be unique on MS-DOS. A -name on MS-DOS consists of up to 8 characters, optionally followed by a -period and up to three characters. MS-DOS will truncate extra -characters both before and after the period. Thus, `foobarhacker.c' -and `foobarhacker.o' are not ambiguous; they are truncated to -`foobarha.c' and `foobarha.o', which are distinct. - - Include in your distribution a copy of the `texinfo.tex' you used to -test print any `*.texinfo' or `*.texi' files. - - Likewise, if your program uses small GNU software packages like -regex, getopt, obstack, or termcap, include them in the distribution -file. Leaving them out would make the distribution file a little -smaller at the expense of possible inconvenience to a user who doesn't -know what other files to get. - - -File: standards.info, Node: References, Next: Copying This Manual, Prev: Managing Releases, Up: Top - -8 References to Non-Free Software and Documentation -*************************************************** - -A GNU program should not recommend use of any non-free program. We -can't stop some people from writing proprietary programs, or stop other -people from using them, but we can and should avoid helping to -advertise them to new potential customers. Proprietary software is a -social and ethical problem, and the point of GNU is to solve that -problem. - - When a non-free program or system is well known, you can mention it -in passing--that is harmless, since users who might want to use it -probably already know about it. For instance, it is fine to explain -how to build your package on top of some non-free operating system, or -how to use it together with some widely used non-free program. - - However, you should give only the necessary information to help those -who already use the non-free program to use your program with it--don't -give, or refer to, any further information about the proprietary -program, and don't imply that the proprietary program enhances your -program, or that its existence is in any way a good thing. The goal -should be that people already using the proprietary program will get -the advice they need about how to use your free program, while people -who don't already use the proprietary program will not see anything to -lead them to take an interest in it. - - If a non-free program or system is obscure in your program's domain, -your program should not mention or support it at all, since doing so -would tend to popularize the non-free program more than it popularizes -your program. (You cannot hope to find many additional users among the -users of Foobar if the users of Foobar are few.) - - A GNU package should not refer the user to any non-free documentation -for free software. Free documentation that can be included in free -operating systems is essential for completing the GNU system, so it is -a major focus of the GNU Project; to recommend use of documentation -that we are not allowed to use in GNU would undermine the efforts to -get documentation that we can include. So GNU packages should never -recommend non-free documentation. - - -File: standards.info, Node: Copying This Manual, Next: Index, Prev: References, Up: Top - -Appendix A Copying This Manual -****************************** - -* Menu: - -* GNU Free Documentation License:: License for copying this manual - - -File: standards.info, Node: GNU Free Documentation License, Up: Copying This Manual - -Appendix B GNU Free Documentation License -***************************************** - - Version 1.1, March 2000 - - Copyright (C) 2000 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - - 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 - written 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 that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you." - - 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. - (For example, 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. - - 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 "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and 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 has been designed - to thwart or discourage subsequent modification by readers is not - Transparent. 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 designed for human modification. - Opaque formats include PostScript, PDF, 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 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. - - 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 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 publicly-accessible - computer-network location containing a complete Transparent copy - of the Document, free of added material, which the general - network-using public has access to download anonymously at no - charge using public-standard network protocols. 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 less than five). - 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", and 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. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, 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 as "Endorsements" or to - conflict in title with any Invariant Section. - - 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. - - 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, does not as a whole count as a - Modified Version of the Document, provided no compilation - copyright is claimed for the compilation. Such a compilation is - called an "aggregate", and this License does not apply to the - other self-contained works thus compiled with the Document, on - account of their being thus compiled, if they 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 - quarter of the entire aggregate, the Document's Cover Texts may be - placed on covers that surround only the Document within the - aggregate. Otherwise they must appear on covers around the whole - aggregate. - - 8. TRANSLATION - - Translation is considered a kind of modification, so you may - distribute translations of the Document under the terms of section - 4. Replacing Invariant Sections with translations requires special - permission from their copyright holders, but you may include - translations of some or all Invariant Sections in addition to the - original versions of these Invariant Sections. You may include a - translation of this License provided that you also include the - original English version of this License. In case of a - disagreement between the translation and the original English - version of this License, the original English version will prevail. - - 9. TERMINATION - - You may not copy, modify, sublicense, or distribute the Document - except as expressly provided for under this License. Any other - attempt to copy, modify, sublicense or distribute the Document is - void, and will automatically terminate your rights under this - License. However, parties who have received copies, or rights, - from you under this License will not have their licenses - terminated so long as such parties remain in full compliance. - - 10. FUTURE REVISIONS OF THIS LICENSE - - The Free Software Foundation may publish new, revised versions of - the GNU Free Documentation License from time to time. Such new - versions will be similar in spirit to the present version, but may - differ in detail to address new problems or concerns. See - http://www.gnu.org/copyleft/. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If - the Document does not specify a version number of this License, - you may choose any version ever published (not as a draft) by the - Free Software Foundation. - - -ADDENDUM: How to use this License for your documents -==================================================== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright (C) YEAR YOUR NAME. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.1 - or any later version published by the Free Software Foundation; - with the Invariant Sections being LIST THEIR TITLES, with the - Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. - A copy of the license is included in the section entitled "GNU - Free Documentation License." - - If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no Front-Cover -Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being -LIST"; likewise for Back-Cover Texts. - - If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, to -permit their use in free software. - - -File: standards.info, Node: Index, Prev: Copying This Manual, Up: Top - -Index -***** - - -* Menu: - -* #endif, commenting: Comments. (line 54) -* --help option: Command-Line Interfaces. - (line 119) -* --version option: Command-Line Interfaces. - (line 34) -* -Wall compiler option: Syntactic Conventions. - (line 10) -* accepting contributions: Contributions. (line 6) -* address for bug reports: Command-Line Interfaces. - (line 125) -* ANSI C standard: Standard C. (line 6) -* arbitrary limits on data: Semantics. (line 6) -* autoconf: System Portability. (line 23) -* avoiding proprietary code: Reading Non-Free Code. - (line 6) -* behavior, dependent on program's name: User Interfaces. (line 6) -* binary packages: Install Command Categories. - (line 80) -* bindir: Directory Variables. (line 45) -* braces, in C source: Formatting. (line 6) -* bug reports: Command-Line Interfaces. - (line 125) -* canonical name of a program: Command-Line Interfaces. - (line 41) -* casting pointers to integers: CPU Portability. (line 67) -* change logs: Change Logs. (line 6) -* change logs, conditional changes: Conditional Changes. (line 6) -* change logs, style: Style of Change Logs. - (line 6) -* command-line arguments, decoding: Semantics. (line 46) -* command-line interface: Command-Line Interfaces. - (line 6) -* commenting: Comments. (line 6) -* compatibility with C and POSIX standards: Compatibility. (line 6) -* compiler warnings: Syntactic Conventions. - (line 10) -* conditional changes, and change logs: Conditional Changes. (line 6) -* conditionals, comments for: Comments. (line 54) -* configure: Configuration. (line 6) -* control-L: Formatting. (line 114) -* conventions for makefiles: Makefile Conventions. - (line 6) -* corba: Graphical Interfaces. - (line 16) -* credits for manuals: Manual Credits. (line 6) -* data types, and portability: CPU Portability. (line 6) -* declaration for system functions: System Functions. (line 21) -* documentation: Documentation. (line 6) -* doschk: Names. (line 38) -* downloading this manual: Preface. (line 17) -* error messages: Semantics. (line 19) -* error messages, formatting: Errors. (line 6) -* exec_prefix: Directory Variables. (line 27) -* expressions, splitting: Formatting. (line 77) -* file usage: File Usage. (line 6) -* file-name limitations: Names. (line 38) -* formatting error messages: Errors. (line 6) -* formatting source code: Formatting. (line 6) -* formfeed: Formatting. (line 114) -* function argument, declaring: Syntactic Conventions. - (line 6) -* function prototypes: Standard C. (line 17) -* getopt: Command-Line Interfaces. - (line 6) -* gettext: Internationalization. - (line 6) -* gnome: Graphical Interfaces. - (line 16) -* graphical user interface: Graphical Interfaces. - (line 6) -* gtk: Graphical Interfaces. - (line 6) -* GUILE: Source Language. (line 38) -* implicit int: Syntactic Conventions. - (line 6) -* impossible conditions: Semantics. (line 70) -* internationalization: Internationalization. - (line 6) -* legal aspects: Legal Issues. (line 6) -* legal papers: Contributions. (line 6) -* libexecdir: Directory Variables. (line 58) -* libraries: Libraries. (line 6) -* library functions, and portability: System Functions. (line 6) -* license for manuals: License for Manuals. (line 6) -* lint: Syntactic Conventions. - (line 109) -* long option names: Option Table. (line 6) -* long-named options: Command-Line Interfaces. - (line 12) -* makefile, conventions for: Makefile Conventions. - (line 6) -* malloc return value: Semantics. (line 25) -* man pages: Man Pages. (line 6) -* manual structure: Manual Structure Details. - (line 6) -* memory allocation failure: Semantics. (line 25) -* memory usage: Memory Usage. (line 6) -* message text, and internationalization: Internationalization. - (line 29) -* mmap: Mmap. (line 6) -* multiple variables in a line: Syntactic Conventions. - (line 35) -* names of variables, functions, and files: Names. (line 6) -* NEWS file: NEWS File. (line 6) -* non-POSIX systems, and portability: System Portability. (line 32) -* non-standard extensions: Using Extensions. (line 6) -* NUL characters: Semantics. (line 11) -* open brace: Formatting. (line 6) -* optional features, configure-time: Configuration. (line 76) -* options for compatibility: Compatibility. (line 14) -* output device and program's behavior: User Interfaces. (line 13) -* packaging: Releases. (line 6) -* portability, and data types: CPU Portability. (line 6) -* portability, and library functions: System Functions. (line 6) -* portability, between system types: System Portability. (line 6) -* POSIX compatibility: Compatibility. (line 6) -* POSIXLY_CORRECT, environment variable: Compatibility. (line 21) -* post-installation commands: Install Command Categories. - (line 6) -* pre-installation commands: Install Command Categories. - (line 6) -* prefix: Directory Variables. (line 17) -* program configuration: Configuration. (line 6) -* program design: Design Advice. (line 6) -* program name and its behavior: User Interfaces. (line 6) -* program's canonical name: Command-Line Interfaces. - (line 41) -* programming languges: Source Language. (line 6) -* proprietary programs: Reading Non-Free Code. - (line 6) -* README file: Releases. (line 17) -* references to non-free material: References. (line 6) -* releasing: Managing Releases. (line 6) -* sbindir: Directory Variables. (line 51) -* signal handling: Semantics. (line 59) -* spaces before open-paren: Formatting. (line 71) -* standard command-line options: Command-Line Interfaces. - (line 31) -* standards for makefiles: Makefile Conventions. - (line 6) -* string library functions: System Functions. (line 55) -* syntactic conventions: Syntactic Conventions. - (line 6) -* table of long options: Option Table. (line 6) -* temporary files: Semantics. (line 84) -* temporary variables: Syntactic Conventions. - (line 23) -* texinfo.tex, in a distribution: Releases. (line 73) -* TMPDIR environment variable: Semantics. (line 84) -* trademarks: Trademarks. (line 6) -* where to obtain standards.texi: Preface. (line 17) - - - -Tag Table: -Node: Top696 -Node: Preface1396 -Node: Legal Issues3616 -Node: Reading Non-Free Code4080 -Node: Contributions5808 -Node: Trademarks7962 -Node: Design Advice9025 -Node: Source Language9609 -Node: Compatibility11621 -Node: Using Extensions13249 -Node: Standard C14825 -Node: Conditional Compilation17228 -Node: Program Behavior18527 -Node: Semantics19446 -Node: Libraries24139 -Node: Errors25384 -Node: User Interfaces27165 -Node: Graphical Interfaces28770 -Node: Command-Line Interfaces29805 -Node: Option Table35876 -Node: Memory Usage50885 -Node: File Usage51910 -Node: Writing C52658 -Node: Formatting53508 -Node: Comments57571 -Node: Syntactic Conventions60873 -Node: Names64285 -Node: System Portability66494 -Node: CPU Portability68879 -Node: System Functions72135 -Node: Internationalization77332 -Node: Mmap80485 -Node: Documentation81195 -Node: GNU Manuals82300 -Node: Doc Strings and Manuals87357 -Node: Manual Structure Details88910 -Node: License for Manuals90328 -Node: Manual Credits91302 -Node: Printed Manuals91695 -Node: NEWS File92381 -Node: Change Logs93059 -Node: Change Log Concepts93813 -Node: Style of Change Logs95677 -Node: Simple Changes97712 -Node: Conditional Changes98956 -Node: Indicating the Part Changed100378 -Node: Man Pages100905 -Node: Reading other Manuals102529 -Node: Managing Releases103320 -Node: Configuration104083 -Node: Makefile Conventions110988 -Node: Makefile Basics111794 -Node: Utilities in Makefiles114968 -Node: Command Variables117113 -Node: Directory Variables120690 -Node: Standard Targets131584 -Ref: Standard Targets-Footnote-1142824 -Node: Install Command Categories142924 -Node: Releases147506 -Node: References151594 -Node: Copying This Manual153879 -Node: GNU Free Documentation License154115 -Node: Index173816 - -End Tag Table diff --git a/opcodes/po/da.gmo b/opcodes/po/da.gmo Binary files differdeleted file mode 100644 index 42d668d1827..00000000000 --- a/opcodes/po/da.gmo +++ /dev/null diff --git a/opcodes/po/de.gmo b/opcodes/po/de.gmo Binary files differdeleted file mode 100644 index acd983f25e6..00000000000 --- a/opcodes/po/de.gmo +++ /dev/null diff --git a/opcodes/po/es.gmo b/opcodes/po/es.gmo Binary files differdeleted file mode 100644 index b4084c506d7..00000000000 --- a/opcodes/po/es.gmo +++ /dev/null diff --git a/opcodes/po/fr.gmo b/opcodes/po/fr.gmo Binary files differdeleted file mode 100644 index 47a17c62c28..00000000000 --- a/opcodes/po/fr.gmo +++ /dev/null diff --git a/opcodes/po/id.gmo b/opcodes/po/id.gmo Binary files differdeleted file mode 100644 index 5d6dcd45e5e..00000000000 --- a/opcodes/po/id.gmo +++ /dev/null diff --git a/opcodes/po/nl.gmo b/opcodes/po/nl.gmo Binary files differdeleted file mode 100644 index d90ae8d030b..00000000000 --- a/opcodes/po/nl.gmo +++ /dev/null diff --git a/opcodes/po/pt_BR.gmo b/opcodes/po/pt_BR.gmo Binary files differdeleted file mode 100644 index 083e8f42199..00000000000 --- a/opcodes/po/pt_BR.gmo +++ /dev/null diff --git a/opcodes/po/ro.gmo b/opcodes/po/ro.gmo Binary files differdeleted file mode 100644 index 6125448e623..00000000000 --- a/opcodes/po/ro.gmo +++ /dev/null diff --git a/opcodes/po/sv.gmo b/opcodes/po/sv.gmo Binary files differdeleted file mode 100644 index 2bbaca69dd3..00000000000 --- a/opcodes/po/sv.gmo +++ /dev/null diff --git a/opcodes/po/tr.gmo b/opcodes/po/tr.gmo Binary files differdeleted file mode 100644 index 98b9df15351..00000000000 --- a/opcodes/po/tr.gmo +++ /dev/null |