the Target System, Prev: dlltool, Up: Top 17 Common Options ***************** The following command-line options are supported by all of the programs described in this manual. `@FILE' Read command-line options from FILE. The options read are inserted in place of the original @FILE option. If FILE does not exist, or cannot be read, then the option will be treated literally, and not removed. Options in FILE are separated by whitespace. A whitespace character may be included in an option by surrounding the entire option in either single or double quotes. Any character (including a backslash) may be included by prefixing the character to be included with a backslash. The FILE may itself contain additional @FILE options; any such options will be processed recursively. `--help' Display the command-line options supported by the program. `--version' Display the version number of the program.  File: binutils.info, Node: Selecting the Target System, Next: Reporting Bugs, Prev: Common Options, Up: Top 18 Selecting the Target System ****************************** You can specify two aspects of the target system to the GNU binary file utilities, each in several ways: * the target * the architecture In the following summaries, the lists of ways to specify values are in order of decreasing precedence. The ways listed first override those listed later. The commands to list valid values only list the values for which the programs you are running were configured. If they were configured with `--enable-targets=all', the commands list most of the available values, but a few are left out; not all targets can be configured in at once because some of them can only be configured "native" (on hosts with the same type as the target system). * Menu: * Target Selection:: * Architecture Selection::  File: binutils.info, Node: Target Selection, Next: Architecture Selection, Up: Selecting the Target System 18.1 Target Selection ===================== A "target" is an object file format. A given target may be supported for multiple architectures (*note Architecture Selection::). A target selection may also have variations for different operating systems or architectures. The command to list valid target values is `objdump -i' (the first column of output contains the relevant information). Some sample values are: `a.out-hp300bsd', `ecoff-littlemips', `a.out-sunos-big'. You can also specify a target using a configuration triplet. This is the same sort of name that is passed to `configure' to specify a target. When you use a configuration triplet as an argument, it must be fully canonicalized. You can see the canonical version of a triplet by running the shell script `config.sub' which is included with the sources. Some sample configuration triplets are: `m68k-hp-bsd', `mips-dec-ultrix', `sparc-sun-sunos'. `objdump' Target ---------------- Ways to specify: 1. command line option: `-b' or `--target' 2. environment variable `GNUTARGET' 3. deduced from the input file `objcopy' and `strip' Input Target ---------------------------------- Ways to specify: 1. command line options: `-I' or `--input-target', or `-F' or `--target' 2. environment variable `GNUTARGET' 3. deduced from the input file `objcopy' and `strip' Output Target ----------------------------------- Ways to specify: 1. command line options: `-O' or `--output-target', or `-F' or `--target' 2. the input target (see "`objcopy' and `strip' Input Target" above) 3. environment variable `GNUTARGET' 4. deduced from the input file `nm', `size', and `strings' Target ---------------------------------- Ways to specify: 1. command line option: `--target' 2. environment variable `GNUTARGET' 3. deduced from the input file  File: binutils.info, Node: Architecture Selection, Prev: Target Selection, Up: Selecting the Target System 18.2 Architecture Selection =========================== An "architecture" is a type of CPU on which an object file is to run. Its name may contain a colon, separating the name of the processor family from the name of the particular CPU. The command to list valid architecture values is `objdump -i' (the second column contains the relevant information). Sample values: `m68k:68020', `mips:3000', `sparc'. `objdump' Architecture ---------------------- Ways to specify: 1. command line option: `-m' or `--architecture' 2. deduced from the input file `objcopy', `nm', `size', `strings' Architecture ----------------------------------------------- Ways to specify: 1. deduced from the input file  File: binutils.info, Node: Reporting Bugs, Next: GNU Free Documentation License, Prev: Selecting the Target System, Up: Top 19 Reporting Bugs ***************** Your bug reports play an essential role in making the binary utilities reliable. Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the principal function of a bug report is to help the entire community by making the next version of the binary utilities work better. Bug reports are your contribution to their maintenance. In order for a bug report to serve its purpose, you must include the information that enables us to fix the bug. * Menu: * Bug Criteria:: Have you found a bug? * Bug Reporting:: How to report bugs  File: binutils.info, Node: Bug Criteria, Next: Bug Reporting, Up: Reporting Bugs 19.1 Have You Found a Bug? ========================== If you are not sure whether you have found a bug, here are some guidelines: * If a binary utility gets a fatal signal, for any input whatever, that is a bug. Reliable utilities never crash. * If a binary utility produces an error message for valid input, that is a bug. * If you are an experienced user of binary utilities, your suggestions for improvement are welcome in any case.  File: binutils.info, Node: Bug Reporting, Prev: Bug Criteria, Up: Reporting Bugs 19.2 How to Report Bugs ======================= A number of companies and individuals offer support for GNU products. If you obtained the binary utilities from a support organization, we recommend you contact that organization first. You can find contact information for many support companies and individuals in the file `etc/SERVICE' in the GNU Emacs distribution. In any event, we also recommend that you send bug reports for the binary utilities to `http://www.sourceware.org/bugzilla/'. The fundamental principle of reporting bugs usefully is this: *report all the facts*. If you are not sure whether to state a fact or leave it out, state it! Often people omit facts because they think they know what causes the problem and assume that some details do not matter. Thus, you might assume that the name of a file you use in an example does not matter. Well, probably it does not, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that pathname is stored in memory; perhaps, if the pathname were different, the contents of that location would fool the utility into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful. Keep in mind that the purpose of a bug report is to enable us to fix the bug if it is new to us. Therefore, always write your bug reports on the assumption that the bug has not been reported previously. Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" This cannot help us fix a bug, so it is basically useless. We respond by asking for enough details to enable us to investigate. You might as well expedite matters by sending them to begin with. To enable us to fix the bug, you should include all these things: * The version of the utility. Each utility announces it if you start it with the `--version' argument. Without this, we will not know whether there is any point in looking for the bug in the current version of the binary utilities. * Any patches you may have applied to the source, including any patches made to the `BFD' library. * The type of machine you are using, and the operating system name and version number. * What compiler (and its version) was used to compile the utilities--e.g. "`gcc-2.7'". * The command arguments you gave the utility to observe the bug. To guarantee you will not omit something important, list them all. A copy of the Makefile (or the output from make) is sufficient. If we were to try to guess the arguments, we would probably guess wrong and then we might not encounter the bug. * A complete input file, or set of input files, that will reproduce the bug. If the utility is reading an object file or files, then it is generally most helpful to send the actual object files. If the source files were produced exclusively using GNU programs (e.g., `gcc', `gas', and/or the GNU `ld'), then it may be OK to send the source files rather than the object files. In this case, be sure to say exactly what version of `gcc', or whatever, was used to produce the object files. Also say how `gcc', or whatever, was configured. * A description of what behavior you observe that you believe is incorrect. For example, "It gets a fatal signal." Of course, if the bug is that the utility gets a fatal signal, then we will certainly notice it. But if the bug is incorrect output, we might not notice unless it is glaringly wrong. You might as well not give us a chance to make a mistake. Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as your copy of the utility is out of sync, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations. * If you wish to suggest changes to the source, send us context diffs, as generated by `diff' with the `-u', `-c', or `-p' option. Always send diffs from the old file to the new file. If you wish to discuss something in the `ld' source, refer to it by context, not by line number. The line numbers in our development sources will not match those in your sources. Your line numbers would convey no useful information to us. Here are some things that are not necessary: * A description of the envelope of the bug. Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it. This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. We recommend that you save your time for something else. Of course, if you can find a simpler example to report _instead_ of the original one, that is a convenience for us. Errors in the output will be easier to spot, running under the debugger will take less time, and so on. However, simplification is not vital; if you do not want to do this, report the bug anyway and send us the entire test case you used. * A patch for the bug. A patch for the bug does help us if it is a good one. But do not omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. Sometimes with programs as complicated as the binary utilities it is very hard to construct an example that will make the program follow a certain path through the code. If you do not send us the example, we will not be able to construct one, so we will not be able to verify that the bug is fixed. And if we cannot understand what bug you are trying to fix, or why your patch should be an improvement, we will not install it. A test case will help us to understand. * A guess about what the bug is or what it depends on. Such guesses are usually wrong. Even we cannot guess right about such things without first using the debugger to find the facts.  File: binutils.info, Node: GNU Free Documentation License, Next: Binutils Index, Prev: Reporting Bugs, Up: Top Appendix A GNU Free Documentation License ***************************************** Version 1.3, 3 November 2008 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. `http://fsf.org/' Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. The "publisher" means any person or entity that distributes copies of the Document to the public. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the 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, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License. However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it. 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. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document. 11. RELICENSING "Massive Multiauthor Collaboration Site" (or "MMC Site") means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A "Massive Multiauthor Collaboration" (or "MMC") contained in the site means any set of copyrightable works thus published on the MMC site. "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization. "Incorporate" means to publish or republish a Document, in whole or in part, as part of another Document. An MMC is "eligible for relicensing" if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008. The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing. 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.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this: with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. 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: binutils.info, Node: Binutils Index, Prev: GNU Free Documentation License, Up: Top Binutils Index ************** [index] * Menu: * .stab: objdump. (line 373) * Add prefix to absolute paths: objdump. (line 341) * addr2line: addr2line. (line 6) * address to file name and line number: addr2line. (line 6) * all header information, object file: objdump. (line 492) * ar: ar. (line 6) * ar compatibility: ar. (line 50) * architecture: objdump. (line 195) * architectures available: objdump. (line 180) * archive contents: ranlib. (line 6) * Archive file symbol index information: readelf. (line 153) * archive headers: objdump. (line 65) * archives: ar. (line 6) * base files: dlltool. (line 124) * bug criteria: Bug Criteria. (line 6) * bug reports: Bug Reporting. (line 6) * bugs: Reporting Bugs. (line 6) * bugs, reporting: Bug Reporting. (line 6) * c++filt: c++filt. (line 6) * changing object addresses: objcopy. (line 308) * changing section address: objcopy. (line 318) * changing section LMA: objcopy. (line 326) * changing section VMA: objcopy. (line 339) * changing start address: objcopy. (line 303) * collections of files: ar. (line 6) * compatibility, ar: ar. (line 50) * contents of archive: ar cmdline. (line 94) * crash: Bug Criteria. (line 9) * creating archives: ar cmdline. (line 135) * creating thin archive: ar cmdline. (line 196) * cxxfilt: c++filt. (line 14) * dates in archive: ar cmdline. (line 170) * debug symbols: objdump. (line 373) * debugging symbols: nm. (line 141) * deleting from archive: ar cmdline. (line 26) * demangling C++ symbols: c++filt. (line 6) * demangling in nm: nm. (line 149) * demangling in objdump <1>: objdump. (line 93) * demangling in objdump: addr2line. (line 64) * deterministic archives: ar cmdline. (line 141) * disassembling object code: objdump. (line 115) * disassembly architecture: objdump. (line 195) * disassembly endianness: objdump. (line 135) * disassembly, with source: objdump. (line 337) * discarding symbols: strip. (line 6) * DLL: dlltool. (line 6) * dlltool: dlltool. (line 6) * DWARF: objdump. (line 363) * dynamic relocation entries, in object file: objdump. (line 325) * dynamic symbol table entries, printing: objdump. (line 476) * dynamic symbols: nm. (line 161) * ELF dynamic section information: readelf. (line 111) * ELF dynamic symbol table information: readelf. (line 86) * ELF file header information: readelf. (line 55) * ELF file information: readelf. (line 6) * ELF notes: readelf. (line 95) * ELF object file format: objdump. (line 373) * ELF program header information: readelf. (line 61) * ELF reloc information: readelf. (line 99) * ELF section group information: readelf. (line 72) * ELF section information: readelf. (line 67) * ELF segment information: readelf. (line 61) * ELF symbol table information: readelf. (line 82) * ELF version sections informations: readelf. (line 115) * elfedit: elfedit. (line 6) * endianness: objdump. (line 135) * error on valid input: Bug Criteria. (line 12) * external symbols: nm. (line 173) * extract from archive: ar cmdline. (line 109) * fatal signal: Bug Criteria. (line 9) * file name: nm. (line 135) * header information, all: objdump. (line 492) * input .def file: dlltool. (line 120) * input file name: nm. (line 135) * Instruction width: objdump. (line 358) * libraries: ar. (line 25) * listings strings: strings. (line 6) * load plugin: nm. (line 176) * machine instructions: objdump. (line 115) * moving in archive: ar cmdline. (line 34) * MRI compatibility, ar: ar scripts. (line 8) * name duplication in archive: ar cmdline. (line 103) * name length: ar. (line 18) * nm: nm. (line 6) * nm compatibility: nm. (line 167) * nm format: nm. (line 167) * not writing archive index: ar cmdline. (line 189) * objdump: objdump. (line 6) * object code format <1>: strings. (line 67) * object code format <2>: nm. (line 244) * object code format <3>: objdump. (line 79) * object code format <4>: addr2line. (line 59) * object code format: size. (line 84) * object file header: objdump. (line 141) * object file information: objdump. (line 6) * object file offsets: objdump. (line 146) * object file sections: objdump. (line 332) * object formats available: objdump. (line 180) * operations on archive: ar cmdline. (line 22) * printing from archive: ar cmdline. (line 46) * printing strings: strings. (line 6) * quick append to archive: ar cmdline. (line 54) * radix for section sizes: size. (line 66) * ranlib <1>: ranlib. (line 6) * ranlib: ar cmdline. (line 88) * readelf: readelf. (line 6) * relative placement in archive: ar cmdline. (line 123) * relocation entries, in object file: objdump. (line 319) * removing symbols: strip. (line 6) * repeated names in archive: ar cmdline. (line 103) * replacement in archive: ar cmdline. (line 70) * reporting bugs: Reporting Bugs. (line 6) * scripts, ar: ar scripts. (line 8) * section addresses in objdump: objdump. (line 71) * section headers: objdump. (line 162) * section information: objdump. (line 185) * section sizes: size. (line 6) * sections, full contents: objdump. (line 332) * size: size. (line 6) * size display format: size. (line 27) * size number format: size. (line 66) * sorting symbols: nm. (line 197) * source code context: objdump. (line 155) * source disassembly: objdump. (line 337) * source file name: nm. (line 135) * source filenames for object files: objdump. (line 189) * stab: objdump. (line 373) * start-address: objdump. (line 383) * stop-address: objdump. (line 387) * strings: strings. (line 6) * strings, printing: strings. (line 6) * strip: strip. (line 6) * Strip absolute paths: objdump. (line 344) * symbol index <1>: ar. (line 28) * symbol index: ranlib. (line 6) * symbol index, listing: nm. (line 214) * symbol line numbers: nm. (line 182) * symbol table entries, printing: objdump. (line 392) * symbols: nm. (line 6) * symbols, discarding: strip. (line 6) * thin archives: ar. (line 40) * undefined symbols: nm. (line 249) * Unix compatibility, ar: ar cmdline. (line 8) * unwind information: readelf. (line 104) * Update ELF header: elfedit. (line 6) * updating an archive: ar cmdline. (line 201) * version: Top. (line 6) * VMA in objdump: objdump. (line 71) * wide output, printing: objdump. (line 498) * writing archive index: ar cmdline. (line 183)  Tag Table: Node: Top2005 Node: ar3715 Node: ar cmdline6520 Node: ar scripts15844 Node: nm21532 Node: objcopy31006 Node: objdump60614 Node: ranlib81286 Node: size82107 Node: strings85112 Node: strip87570 Node: c++filt93521 Ref: c++filt-Footnote-198368 Node: addr2line98474 Node: nlmconv102274 Node: windmc104880 Node: windres108529 Node: dlltool114556 Node: def file format127442 Node: readelf129373 Node: elfedit135958 Node: Common Options138178 Node: Selecting the Target System139218 Node: Target Selection140150 Node: Architecture Selection142132 Node: Reporting Bugs142960 Node: Bug Criteria143739 Node: Bug Reporting144292 Node: GNU Free Documentation License151162 Node: Binutils Index176341  End Tag Table This is standards.info, produced by makeinfo version 4.8 from ./standards.texi. INFO-DIR-SECTION GNU organization START-INFO-DIR-ENTRY * Standards: (standards). GNU coding standards. END-INFO-DIR-ENTRY The GNU coding standards, last updated April 12, 2010. Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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.3 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 ******* The GNU coding standards, last updated April 12, 2010. Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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.3 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". * 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:: Mentioning non-free software or documentation. * GNU Free Documentation License:: Copying and sharing 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. If you did not obtain this file directly from the GNU project and recently, please check for a newer version. You can get the GNU Coding Standards from the GNU web server in many different formats, including the Texinfo source, PDF, HTML, DVI, plain text, and more, at: `http://www.gnu.org/prep/standards/'. If you are maintaining an official GNU package, in addition to this document, please read and follow the GNU maintainer information (*note Contents: (maintain)Top.). If you want to receive diffs for every change to these GNU documents, join the mailing list `gnustandards-commit@gnu.org', via the web interface at `http://lists.gnu.org/mailman/listinfo/gnustandards-commit'. Archives are also available there. Please send corrections or suggestions for this document to . If you make a suggestion, please include a suggested new wording for it, to help us consider the suggestion efficiently. We prefer a context diff to the Texinfo source, but if that's difficult for you, you can make a context diff for some other version of this document, or propose it in any way that makes it clear. The source repository for this document can be found at `http://savannah.gnu.org/projects/gnustandards'. These standards cover the minimum of what is important when writing a GNU package. Likely, the need 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. The GNU Hello program serves as an example of how to follow the GNU coding standards for a trivial program. `http://www.gnu.org/software/hello/hello.html'. This release of the GNU Coding Standards was last updated April 12, 2010.  File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top 2 Keeping Free Software Free **************************** This chapter 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 memory 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 sent 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. It is also available online for your perusal: `http://www.gnu.org/prep/maintain/'.  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, and there is no legal requirement for them, so we don't use them. What is legally required, as regards other people's trademarks, is to avoid using them in ways which a reader might reasonably understand 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 would have been meant as a shorter way of saying 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. Please don't use "win" as an abbreviation for Microsoft Windows in GNU software or documentation. In hacker terminology, calling something a "win" is a form of praise. If you wish to praise Microsoft Windows when speaking on your own, by all means do so, but not in GNU software. Usually we write the name "Windows" in full, but when brevity is very important (as in file names and sometimes symbol names), we abbreviate it to "w". For instance, the files and functions in Emacs that deal with Windows start with `w32'.  File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top 3 General Program Design ************************ This chapter discusses some of the issues you should take into account when designing your program. * Menu: * Source Language:: Which languages 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 >?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~    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 (`http://www.gnu.org/software/guile/'), which implements the language Scheme (an especially clean and simple dialect of Lisp). Guile also includes bindings for GTK+/GNOME, making it practical to write modern GUI functionality within 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 th