diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/COPYING-GFDL | 455 | ||||
| -rw-r--r-- | doc/ChangeLog | 53 | ||||
| -rw-r--r-- | doc/Makefile.am | 24 | ||||
| -rw-r--r-- | doc/README | 20 | ||||
| -rw-r--r-- | doc/debuginfod-find.1 | 144 | ||||
| -rw-r--r-- | doc/debuginfod.8 | 387 | ||||
| -rw-r--r-- | doc/debuginfod_begin.3 | 1 | ||||
| -rw-r--r-- | doc/debuginfod_end.3 | 1 | ||||
| -rw-r--r-- | doc/debuginfod_find_debuginfo.3 | 242 | ||||
| -rw-r--r-- | doc/debuginfod_find_executable.3 | 1 | ||||
| -rw-r--r-- | doc/debuginfod_find_source.3 | 1 | ||||
| -rw-r--r-- | doc/debuginfod_set_progressfn.3 | 1 | ||||
| -rw-r--r-- | doc/elf_begin.3 | 37 | ||||
| -rw-r--r-- | doc/elf_clone.3 | 14 | ||||
| -rw-r--r-- | doc/elf_getdata.3 | 28 | ||||
| -rw-r--r-- | doc/elf_update.3 | 14 | ||||
| -rw-r--r-- | doc/elfclassify.1 | 197 | ||||
| -rw-r--r-- | doc/readelf.1 | 511 |
18 files changed, 2118 insertions, 13 deletions
diff --git a/doc/COPYING-GFDL b/doc/COPYING-GFDL new file mode 100644 index 00000000..98310abe --- /dev/null +++ b/doc/COPYING-GFDL @@ -0,0 +1,455 @@ +This license applies to the eu-readelf.1 man page which was forked +from the binutils readelf version of the man page. The rest of the +documentation is provided under the license found in the top level +directory. + + GNU Free Documentation License + Version 1.3, 3 November 2008 + + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + <https://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 +https://www.gnu.org/licenses/. + +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. diff --git a/doc/ChangeLog b/doc/ChangeLog index 380a0cd7..00a61ac3 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,56 @@ +2019-09-02 Mark Wielaard <[email protected]> + + * readelf.1 (symbols): Add optional section name. + (dyn-sym): Document new option. + +2019-08-28 Mark Wielaard <[email protected]> + + * COPYING: Rename to... + * COPYING-GFDL: ... this. + +2019-08-23 Ben Woodard <[email protected]> + + * Updated the eu-readelf man page to make it match the options + that eu-readelf actually supports. + +2019-08-22 Ben Woodard <[email protected]>S + + * Move the .1 man pages to the correct place. + +2019-08-21 Ben Woodard <[email protected]> + + * Updated Changelog + * Added README + +2019-08-20 Ben Woodard <[email protected]> + + * Added eu-elfclassify.1 man page based upon --help + * Forked binutils readelf page to make eu-readelf.1 man page + * Modified eu-readelf.1 to add -n:: option. + * Disabled sgml file building per mjw. + * Added man pages to Makefile.am + +2019-06-20 Ben Woodard <[email protected]> + + * Added the beginnings of some man pages + +2019-08-21 Ben Woodard <[email protected]> + + * Updated Changelog + * Added README + +2019-08-20 Ben Woodard <[email protected]> + + * Added eu-elfclassify.1 man page based upon --help + * Forked binutils readelf page to make eu-readelf.1 man page + * Modified eu-readelf.1 to add -n:: option. + * Disabled sgml file building per mjw. + * Added man pages to Makefile.am + +2019-06-20 Ben Woodard <[email protected]> + + * Added the beginnings of some man pages + 2005-04-29 Ulrich Drepper <[email protected]> * elfutils.sgml: Some typo fixes and a few extensions. diff --git a/doc/Makefile.am b/doc/Makefile.am index 44f0c11a..b5db01ff 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,7 +1,7 @@ ## Process this file with automake to create Makefile.in ## Configure input file for elfutils. ## -## Copyright (C) 1996-2001, 2002, 2005 Red Hat, Inc. +## Copyright (C) 1996-2001, 2002, 2005, 2019 Red Hat, Inc. ## This file is part of elfutils. ## ## This file is free software; you can redistribute it and/or modify @@ -16,17 +16,15 @@ ## ## You should have received a copy of the GNU General Public License ## along with this program. If not, see <http://www.gnu.org/licenses/>. -EXTRA_DIST = elfutils.sgml +EXTRA_DIST = COPYING-GFDL README +dist_man1_MANS=readelf.1 elfclassify.1 +notrans_dist_man3_MANS=elf_update.3 elf_getdata.3 elf_clone.3 elf_begin.3 +notrans_dist_man8_MANS= +notrans_dist_man1_MANS= -CLEANFILES = elfutils.dvi +if DEBUGINFOD +notrans_dist_man8_MANS += debuginfod.8 +notrans_dist_man3_MANS += debuginfod_find_debuginfo.3 debuginfod_find_source.3 debuginfod_find_executable.3 debuginfod_set_progressfn.3 +notrans_dist_man1_MANS += debuginfod-find.1 +endif -# We need only a few special rules to generate the various output formats -# from the SGML sources. -.PHONY: dvi pdf html -pdf: $(srcdir)elfutils.pdf -dvi: $(srcdir)elfutils.dvi - -$(srcdir)%.dvi: %.sgml - db2dvi $^ -$(srcdir)%.pdf: %.sgml - db2pdf $^ diff --git a/doc/README b/doc/README new file mode 100644 index 00000000..67f61fac --- /dev/null +++ b/doc/README @@ -0,0 +1,20 @@ +The elfutils documentation is very much a work in +progress. Contributions are welcome. +Please reports bugs at https://sourceware.org/bugzilla/ +Please send additions and patches to: [email protected] + +The elfutils utilities are a new implementation of many of the +utilities found in binutils and consequently, the documentation for +most of the tools has been the the man pages for binutils. For example +you could refer to readelf's man page for instructions on +eu-readelf. This has been fine up until this point but as tools gain +new capabilities, they will need to have their own individual man +page. Forking the man pages from binutils is acceptable and the +current plan of action. + +New utilities that do not have an analog in binutils can have their +initial man pages generated using a tool like help2man. + +The C language interfaces for libelf, libdw, and libdwfl are in +particular need of documentation. The aspirational goal is write these +in sphinx.
\ No newline at end of file diff --git a/doc/debuginfod-find.1 b/doc/debuginfod-find.1 new file mode 100644 index 00000000..a759ecba --- /dev/null +++ b/doc/debuginfod-find.1 @@ -0,0 +1,144 @@ +'\"! tbl | nroff \-man +'\" t macro stdmacro + +.de SAMPLE +.br +.RS 0 +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.TH DEBUGINFOD-FIND 1 +.SH NAME +debuginfod-find \- request debuginfo-related data + +.SH SYNOPSIS +.B debuginfod-find [\fIOPTION\fP]... debuginfo \fIBUILDID\fP + +.B debuginfod-find [\fIOPTION\fP]... executable \fIBUILDID\fP + +.B debuginfod-find [\fIOPTION\fP]... source \fIBUILDID\fP \fI/FILENAME\fP + +.SH DESCRIPTION +\fBdebuginfod-find\fP queries one or more \fBdebuginfod\fP servers for +debuginfo-related data. In case of a match, it saves the the +requested file into a local cache, prints the file name to standard +output, and exits with a success status of 0. In case of any error, +it exits with a failure status and an error message to standard error. + +.\" Much of the following text is duplicated with debuginfod.8 + +The debuginfod system uses buildids to identify debuginfo-related data. +These are stored as binary notes in ELF/DWARF files, and are +represented as lowercase hexadecimal. For example, for a program +/bin/ls, look at the ELF note GNU_BUILD_ID: + +.SAMPLE +% readelf -n /bin/ls | grep -A4 build.id +Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340: +Owner Data size Type +GNU 20 GNU_BUILD_ID +Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d +.ESAMPLE + +Then the hexadecimal BUILDID is simply: + +.SAMPLE +8713b9c3fb8a720137a4a08b325905c7aaf8429d +.ESAMPLE + +.SS debuginfo \fIBUILDID\fP + +If the given buildid is known to a server, this request will result +in a binary object that contains the customary \fB.*debug_*\fP +sections. This may be a split debuginfo file as created by +\fBstrip\fP, or it may be an original unstripped executable. + +.SS executable \fIBUILDID\fP + +If the given buildid is known to the server, this request will result +in a binary object that contains the normal executable segments. This +may be a executable stripped by \fBstrip\fP, or it may be an original +unstripped executable. \fBET_DYN\fP shared libraries are considered +to be a type of executable. + +.SS source \fIBUILDID\fP \fI/SOURCE/FILE\fP + +If the given buildid is known to the server, this request will result +in a binary object that contains the source file mentioned. The path +should be absolute. Relative path names commonly appear in the DWARF +file's source directory, but these paths are relative to +individual compilation unit AT_comp_dir paths, and yet an executable +is made up of multiple CUs. Therefore, to disambiguate, debuginfod +expects source queries to prefix relative path names with the CU +compilation-directory, followed by a mandatory "/". + +Note: the user should not elide \fB../\fP or \fB/./\fP or extraneous +\fB///\fP sorts of path components in the directory names, because if +this is how those names appear in the DWARF files, that is what +debuginfod needs to see too. + +For example: +.TS +l l. +#include <stdio.h> source BUILDID /usr/include/stdio.h +/path/to/foo.c source BUILDID /path/to/foo.c +\../bar/foo.c AT_comp_dir=/zoo/ source BUILDID /zoo//../bar/foo.c +.TE + +.SH "OPTIONS" + +.TP +.B "\-v" +Increase verbosity, including printing frequent download-progress messages. + + +.SH "SECURITY" + +debuginfod-find \fBdoes not\fP include any particular security +features. It trusts that the binaries returned by the debuginfod(s) +are accurate. Therefore, the list of servers should include only +trustworthy ones. If accessed across HTTP rather than HTTPS, the +network should be trustworthy. Authentication information through +the internal \fIlibcurl\fP library is not currently enabled, except +for the basic plaintext \%\fIhttp[s]://userid:password@hostname/\fP style. +(The debuginfod server does not perform authentication, but a front-end +proxy server could.) + +.SH "ENVIRONMENT VARIABLES" + +.TP 21 +.B DEBUGINFOD_URLS +This environment variable contains a list of URL prefixes for trusted +debuginfod instances. Alternate URL prefixes are separated by space. + +.TP 21 +.B DEBUGINFOD_TIMEOUT +This environment variable governs the timeout for each debuginfod HTTP +connection. A server that fails to respond within this many seconds +is skipped. The default is 5. + +.TP 21 +.B DEBUGINFOD_CACHE_PATH +This environment variable governs the location of the cache where +downloaded files are kept. It is cleaned periodically as this program +is reexecuted. Cache management parameters may be set by files under +this directory: see the \fBdebuginfod_find_debuginfo(3)\fP man page +for details. The default is $HOME/.debuginfod_client_cache. + +.SH "FILES" +.LP +.PD .1v +.TP 20 +.B $HOME/.debuginfod_client_cache +Default cache directory. +.PD + +.SH "SEE ALSO" +.I "debuginfod(8)" +.I "debuginfod_find_debuginfod(3)" diff --git a/doc/debuginfod.8 b/doc/debuginfod.8 new file mode 100644 index 00000000..210550e8 --- /dev/null +++ b/doc/debuginfod.8 @@ -0,0 +1,387 @@ +'\"! tbl | nroff \-man +'\" t macro stdmacro + +.de SAMPLE +.br +.RS 0 +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.TH DEBUGINFOD 8 +.SH NAME +debuginfod \- debuginfo-related http file-server daemon + +.SH SYNOPSIS +.B debuginfod +[\fIOPTION\fP]... [\fIPATH\fP]... + +.SH DESCRIPTION +\fBdebuginfod\fP serves debuginfo-related artifacts over HTTP. It +periodically scans a set of directories for ELF/DWARF files and their +associated source code, as well as RPM files containing the above, to +build an index by their buildid. This index is used when remote +clients use the HTTP webapi, to fetch these files by the same buildid. + +If a debuginfod cannot service a given buildid artifact request +itself, and it is configured with information about upstream +debuginfod servers, it queries them for the same information, just as +\fBdebuginfod-find\fP would. If successful, it locally caches then +relays the file content to the original requester. + +If the \fB\-F\fP option is given, each listed PATH creates a thread to +scan for matching ELF/DWARF/source files under the given physical +directory. Source files are matched with DWARF files based on the +AT_comp_dir (compilation directory) attributes inside it. Duplicate +directories are ignored. You may use a file name for a PATH, but +source code indexing may be incomplete; prefer using a directory that +contains the binaries. Caution: source files listed in the DWARF may +be a path \fIanywhere\fP in the file system, and debuginfod will +readily serve their content on demand. (Imagine a doctored DWARF file +that lists \fI/etc/passwd\fP as a source file.) If this is a concern, +audit your binaries with tools such as: + +.SAMPLE +% eu-readelf -wline BINARY | sed -n '/^Directory.table/,/^File.name.table/p' +or +% eu-readelf -wline BINARY | sed -n '/^Directory.table/,/^Line.number/p' +or even use debuginfod itself: +% debuginfod -vvv -d :memory: -F BINARY 2>&1 | grep 'recorded.*source' +^C +.ESAMPLE + +If the \fB\-R\fP option is given each listed PATH creates a thread to +scan for ELF/DWARF/source files contained in matching RPMs under the +given physical directory. Duplicate directories are ignored. You may +use a file name for a PATH, but source code indexing may be +incomplete; prefer using a directory that contains normal RPMs +alongside debuginfo/debugsource RPMs. Because of complications such +as DWZ-compressed debuginfo, may require \fItwo\fP scan passes to +identify all source code. Source files for RPMs are only served +from other RPMs, so the caution for \-F does not apply. + +If no PATH is listed, or neither \-F nor \-R option is given, then +\fBdebuginfod\fP will simply serve content that it scanned into its +index in previous runs: the data is cumulative. + +File names must match extended regular expressions given by the \-I +option and not the \-X option (if any) in order to be considered. + + +.SH OPTIONS + +.TP +.B "\-F" +Activate ELF/DWARF file scanning threads. The default is off. + +.TP +.B "\-R" +Activate RPM file scanning threads. The default is off. + +.TP +.B "\-d FILE" "\-\-database=FILE" +Set the path of the sqlite database used to store the index. This +file is disposable in the sense that a later rescan will repopulate +data. It will contain absolute file path names, so it may not be +portable across machines. It may be frequently read/written, so it +should be on a fast filesytem. It should not be shared across +machines or users, to maximize sqlite locking performance. The +default database file is $HOME/.debuginfod.sqlite. + +.TP +.B "\-D SQL" "\-\-ddl=SQL" +Execute given sqlite statement after the database is opened and +initialized as extra DDL (SQL data definition language). This may be +useful to tune performance-related pragmas or indexes. May be +repeated. The default is nothing extra. + +.TP +.B "\-p NUM" "\-\-port=NUM" +Set the TCP port number on which debuginfod should listen, to service +HTTP requests. Both IPv4 and IPV6 sockets are opened, if possible. +The webapi is documented below. The default port number is 8002. + +.TP +.B "\-I REGEX" "\-\-include=REGEX" "\-X REGEX" "\-\-exclude=REGEX" +Govern the inclusion and exclusion of file names under the search +paths. The regular expressions are interpreted as unanchored POSIX +extended REs, thus may include alternation. They are evaluated +against the full path of each file, based on its \fBrealpath(3)\fP +canonicalization. By default, all files are included and none are +excluded. A file that matches both include and exclude REGEX is +excluded. (The \fIcontents\fP of RPM files are not subject to +inclusion or exclusion filtering: they are all processed.) + +.TP +.B "\-t SECONDS" "\-\-rescan\-time=SECONDS" +Set the rescan time for the file and RPM directories. This is the +amount of time the scanning threads will wait after finishing a scan, +before doing it again. A rescan for unchanged files is fast (because +the index also stores the file mtimes). A time of zero is acceptable, +and means that only one initial scan should performed. The default +rescan time is 300 seconds. Receiving a SIGUSR1 signal triggers a new +scan, independent of the rescan time (including if it was zero). + +.TP +.B "\-g SECONDS" "\-\-groom\-time=SECONDS" +Set the groom time for the index database. This is the amount of time +the grooming thread will wait after finishing a grooming pass before +doing it again. A groom operation quickly rescans all previously +scanned files, only to see if they are still present and current, so +it can deindex obsolete files. See also the \fIDATA MANAGEMENT\fP +section. The default groom time is 86400 seconds (1 day). A time of +zero is acceptable, and means that only one initial groom should be +performed. Receiving a SIGUSR2 signal triggers a new grooming pass, +independent of the groom time (including if it was zero). + +.TP +.B "\-G" +Run an extraordinary maximal-grooming pass at debuginfod startup. +This pass can take considerable time, because it tries to remove any +debuginfo-unrelated content from the RPM-related parts of the index. +It should not be run if any recent RPM-related indexing operations +were aborted early. It can take considerable space, because it +finishes up with an sqlite "vacuum" operation, which repacks the +database file by triplicating it temporarily. The default is not to +do maximal-grooming. See also the \fIDATA MANAGEMENT\fP section. + +.TP +.B "\-c NUM" "\-\-concurrency=NUM" +Set the concurrency limit for all the scanning threads. While many +threads may be spawned to cover all the given PATHs, only NUM may +concurrently do CPU-intensive operations like parsing an ELF file +or an RPM. The default is the number of processors on the system; +the minimum is 1. + +.TP +.B "\-L" +Traverse symbolic links encountered during traversal of the PATHs, +including across devices - as in \fIfind\ -L\fP. The default is to +traverse the physical directory structure only, stay on the same +device, and ignore symlinks - as in \fIfind\ -P\ -xdev\fP. Caution: a +loops in the symbolic directory tree might lead to \fIinfinite +traversal\fP. + +.TP +.B "\-v" +Increase verbosity of logging to the standard error file descriptor. +May be repeated to increase details. The default verbosity is 0. + +.SH WEBAPI + +.\" Much of the following text is duplicated with debuginfod-find.1 + +debuginfod's webapi resembles ordinary file service, where a GET +request with a path containing a known buildid results in a file. +Unknown buildid / request combinations result in HTTP error codes. +This file service resemblance is intentional, so that an installation +can take advantage of standard HTTP management infrastructure. + +There are three requests. In each case, the buildid is encoded as a +lowercase hexadecimal string. For example, for a program \fI/bin/ls\fP, +look at the ELF note GNU_BUILD_ID: + +.SAMPLE +% readelf -n /bin/ls | grep -A4 build.id +Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340: +Owner Data size Type +GNU 20 GNU_BUILD_ID +Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d +.ESAMPLE + +Then the hexadecimal BUILDID is simply: + +.SAMPLE +8713b9c3fb8a720137a4a08b325905c7aaf8429d +.ESAMPLE + +.SS /buildid/\fIBUILDID\fP/debuginfo + +If the given buildid is known to the server, this request will result +in a binary object that contains the customary \fB.*debug_*\fP +sections. This may be a split debuginfo file as created by +\fBstrip\fP, or it may be an original unstripped executable. + +.SS /buildid/\fIBUILDID\fP/executable + +If the given buildid is known to the server, this request will result +in a binary object that contains the normal executable segments. This +may be a executable stripped by \fBstrip\fP, or it may be an original +unstripped executable. \fBET_DYN\fP shared libraries are considered +to be a type of executable. + +.SS /buildid/\fIBUILDID\fP/source\fI/SOURCE/FILE\fP + +If the given buildid is known to the server, this request will result +in a binary object that contains the source file mentioned. The path +should be absolute. Relative path names commonly appear in the DWARF +file's source directory, but these paths are relative to +individual compilation unit AT_comp_dir paths, and yet an executable +is made up of multiple CUs. Therefore, to disambiguate, debuginfod +expects source queries to prefix relative path names with the CU +compilation-directory, followed by a mandatory "/". + +Note: contrary to RFC 3986, the client should not elide \fB../\fP or +\fB/./\fP or extraneous \fB///\fP sorts of path components in the +directory names, because if this is how those names appear in the +DWARF files, that is what debuginfod needs to see too. + +For example: +.TS +l l. +#include <stdio.h> /buildid/BUILDID/source/usr/include/stdio.h +/path/to/foo.c /buildid/BUILDID/source/path/to/foo.c +\../bar/foo.c AT_comp_dir=/zoo/ /buildid/BUILDID/source/zoo//../bar/foo.c +.TE + +.SS /metrics + +This endpoint returns a Prometheus formatted text/plain dump of a +variety of statistics about the operation of the debuginfod server. +The exact set of metrics and their meanings may change in future +versions. Caution: configuration information (path names, versions) +may be disclosed. + +.SH DATA MANAGEMENT + +debuginfod stores its index in an sqlite database in a densely packed +set of interlinked tables. While the representation is as efficient +as we have been able to make it, it still takes a considerable amount +of data to record all debuginfo-related data of potentially a great +many files. This section offers some advice about the implications. + +As a general explanation for size, consider that debuginfod indexes +ELF/DWARF files, it stores their names and referenced source file +names, and buildids will be stored. When indexing RPMs, it stores +every file name \fIof or in\fP an RPM, every buildid, plus every +source file name referenced from a DWARF file. (Indexing RPMs takes +more space because the source files often reside in separate +subpackages that may not be indexed at the same pass, so extra +metadata has to be kept.) + +Getting down to numbers, in the case of Fedora RPMs (essentially, +gzip-compressed cpio files), the sqlite index database tends to be +from 0.5% to 3% of their size. It's larger for binaries that are +assembled out of a great many source files, or packages that carry +much debuginfo-unrelated content. It may be even larger during the +indexing phase due to temporary sqlite write-ahead-logging files; +these are checkpointed (cleaned out and removed) at shutdown. It may +be helpful to apply tight \-I or \-X regular-expression constraints to +exclude files from scanning that you know have no debuginfo-relevant +content. + +As debuginfod runs, it periodically rescans its target directories, +and any new content found is added to the database. Old content, such +as data for files that have disappeared or that have been replaced +with newer versions is removed at a periodic \fIgrooming\fP pass. +This means that the sqlite files grow fast during initial indexing, +slowly during index rescans, and periodically shrink during grooming. +There is also an optional one-shot \fImaximal grooming\fP pass is +available. It removes information debuginfo-unrelated data from the +RPM content index such as file names found in RPMs ("rpm sdef" +records) that are not referred to as source files from any binaries +find in RPMs ("rpm sref" records). This can save considerable disk +space. However, it is slow and temporarily requires up to twice the +database size as free space. Worse: it may result in missing +source-code info if the RPM traversals were interrupted, so the not +all source file references were known. Use it rarely to polish a +complete index. + +You should ensure that ample disk space remains available. (The flood +of error messages on -ENOSPC is ugly and nagging. But, like for most +other errors, debuginfod will resume when resources permit.) If +necessary, debuginfod can be stopped, the database file moved or +removed, and debuginfod restarted. + +sqlite offers several performance-related options in the form of +pragmas. Some may be useful to fine-tune the defaults plus the +debuginfod extras. The \-D option may be useful to tell debuginfod to +execute the given bits of SQL after the basic schema creation +commands. For example, the "synchronous", "cache_size", +"auto_vacuum", "threads", "journal_mode" pragmas may be fun to tweak +via \-D, if you're searching for peak performance. The "optimize", +"wal_checkpoint" pragmas may be useful to run periodically, outside +debuginfod. The default settings are performance- rather than +reliability-oriented, so a hardware crash might corrupt the database. +In these cases, it may be necessary to manually delete the sqlite +database and start over. + +As debuginfod changes in the future, we may have no choice but to +change the database schema in an incompatible manner. If this +happens, new versions of debuginfod will issue SQL statements to +\fIdrop\fP all prior schema & data, and start over. So, disk space +will not be wasted for retaining a no-longer-useable dataset. + +In summary, if your system can bear a 0.5%-3% index-to-RPM-dataset +size ratio, and slow growth afterwards, you should not need to +worry about disk space. If a system crash corrupts the database, +or you want to force debuginfod to reset and start over, simply +erase the sqlite file before restarting debuginfod. + + +.SH SECURITY + +debuginfod \fBdoes not\fP include any particular security features. +While it is robust with respect to inputs, some abuse is possible. It +forks a new thread for each incoming HTTP request, which could lead to +a denial-of-service in terms of RAM, CPU, disk I/O, or network I/O. +If this is a problem, users are advised to install debuginfod with a +HTTPS reverse-proxy front-end that enforces site policies for +firewalling, authentication, integrity, authorization, and load +control. The \fI/metrics\fP webapi endpoint is probably not +appropriate for disclosure to the public. + +When relaying queries to upstream debuginfods, debuginfod \fBdoes not\fP +include any particular security features. It trusts that the binaries +returned by the debuginfods are accurate. Therefore, the list of +servers should include only trustworthy ones. If accessed across HTTP +rather than HTTPS, the network should be trustworthy. Authentication +information through the internal \fIlibcurl\fP library is not currently +enabled. + + +.SH "ENVIRONMENT VARIABLES" + +.TP 21 +.B DEBUGINFOD_URLS +This environment variable contains a list of URL prefixes for trusted +debuginfod instances. Alternate URL prefixes are separated by space. +Avoid referential loops that cause a server to contact itself, directly +or indirectly - the results would be hilarious. + +.TP 21 +.B DEBUGINFOD_TIMEOUT +This environment variable governs the timeout for each debuginfod HTTP +connection. A server that fails to respond within this many seconds +is skipped. The default is 5. + +.TP 21 +.B DEBUGINFOD_CACHE_PATH +This environment variable governs the location of the cache where +downloaded files are kept. It is cleaned periodically as this +program is reexecuted. The default is $HOME/.debuginfod_client_cache. +.\" XXX describe cache eviction policy + +.SH FILES +.LP +.PD .1v +.TP 20 +.B $HOME/.debuginfod.sqlite +Default database file. +.PD + +.TP 20 +.B $HOME/.debuginfod_client_cache +Default cache directory for content from upstream debuginfods. +.PD + + +.SH "SEE ALSO" +.I "debuginfod-find(1)" +.I "sqlite3(1)" +.I \%https://prometheus.io/docs/instrumenting/exporters/ diff --git a/doc/debuginfod_begin.3 b/doc/debuginfod_begin.3 new file mode 100644 index 00000000..16279936 --- /dev/null +++ b/doc/debuginfod_begin.3 @@ -0,0 +1 @@ +.so man3/debuginfod_find_debuginfo.3 diff --git a/doc/debuginfod_end.3 b/doc/debuginfod_end.3 new file mode 100644 index 00000000..16279936 --- /dev/null +++ b/doc/debuginfod_end.3 @@ -0,0 +1 @@ +.so man3/debuginfod_find_debuginfo.3 diff --git a/doc/debuginfod_find_debuginfo.3 b/doc/debuginfod_find_debuginfo.3 new file mode 100644 index 00000000..be8eed09 --- /dev/null +++ b/doc/debuginfod_find_debuginfo.3 @@ -0,0 +1,242 @@ +'\"! tbl | nroff \-man +'\" t macro stdmacro + +.de SAMPLE +.br +.RS 0 +.nf +.nh +.. +.de ESAMPLE +.hy +.fi +.RE +.. + +.TH DEBUGINFOD_FIND_* 3 +.SH NAME +debuginfod_find_debuginfo \- request debuginfo from debuginfod + +.SH SYNOPSIS +.nf +.B #include <elfutils/debuginfod.h> +.PP +.BI "debuginfod_client *debuginfod_begin(void);" +.BI "void debuginfod_end(debuginfod_client *" client ");" + +.BI "int debuginfod_find_debuginfo(debuginfod_client *" client "," +.BI " const unsigned char *" build_id "," +.BI " int " build_id_len "," +.BI " char ** " path ");" +.BI "int debuginfod_find_executable(debuginfod_client *" client "," +.BI " const unsigned char *" build_id "," +.BI " int " build_id_len "," +.BI " char ** " path ");" +.BI "int debuginfod_find_source(debuginfod_client *" client "," +.BI " const unsigned char *" build_id "," +.BI " int " build_id_len "," +.BI " const char *" filename "," +.BI " char ** " path ");" + +.BI "typedef int (*debuginfo_progressfn_t)(debuginfod_client *" client "," +.BI " long a, long b);" +.BI "void debuginfod_set_progressfn(debuginfod_client *" client "," +.BI " debuginfo_progressfn_t " progressfn ");" + +Link with \fB-ldebuginfod\fP. + +.SH DESCRIPTION + +.BR debuginfod_begin () +creates a \fBdebuginfod_client\fP connection handle that should be used +with all other calls. +.BR debuginfod_end () +should be called on the \fBclient\fP handle to release all state and +storage when done. + +.BR debuginfod_find_debuginfo (), +.BR debuginfod_find_executable (), +and +.BR debuginfod_find_source () +query the debuginfod server URLs contained in +.BR $DEBUGINFOD_URLS +(see below) for the debuginfo, executable or source file with the +given \fIbuild_id\fP. \fIbuild_id\fP should be a pointer to either +a null-terminated, lowercase hex string or a binary blob. If +\fIbuild_id\fP is given as a hex string, \fIbuild_id_len\fP should +be 0. Otherwise \fIbuild_id_len\fP should be the number of bytes in +the binary blob. + +.BR debuginfod_find_source () +also requries a \fIfilename\fP in order to specify a particular +source file. \fIfilename\fP should be an absolute path that includes +the compilation directory of the CU associated with the source file. +Relative path names commonly appear in the DWARF file's source directory, +but these paths are relative to individual compilation unit AT_comp_dir +paths, and yet an executable is made up of multiple CUs. Therefore, to +disambiguate, debuginfod expects source queries to prefix relative path +names with the CU compilation-directory, followed by a mandatory "/". + +Note: the caller should not elide \fB../\fP or \fB/./\fP or extraneous +\fB///\fP sorts of path components in the directory names, because if +this is how those names appear in the DWARF files, that is what +debuginfod needs to see too. + +If \fIpath\fP is not NULL and the query is successful, \fIpath\fP is set +to the path of the file in the cache. The caller must \fBfree\fP() this value. + +The URLs in \fB$DEBUGINFOD_URLS\fP may be queried in parallel. As soon +as a debuginfod server begins transferring the target file all of the +connections to the other servers are closed. + +A \fBclient\fP handle should be used from only one thread at a time. + +.SH "RETURN VALUE" + +\fBdebuginfod_begin\fP returns the \fBdebuginfod_client\fP handle to +use with all other calls. On error \fBNULL\fP will be returned and +\fBerrno\fP will be set. + +If a find family function is successful, the resulting file is saved +to the client cache and a file descriptor to that file is returned. +The caller needs to \fBclose\fP() this descriptor. Otherwise, a +negative error code is returned. + +.SH "PROGRESS CALLBACK" + +As the \fBdebuginfod_find_*\fP() functions may block for seconds or +longer, a progress callback function is called periodically, if +configured with +.BR debuginfod_set_progressfn (). +This function sets a new progress callback function (or NULL) for the +client handle. + +The given callback function is called from the context of each thread +that is invoking any of the other lookup functions. It is given two +numeric parameters that, if thought of as a numerator \fIa\fP and +denominator \fIb\fP, together represent a completion fraction +\fIa/b\fP. The denominator may be zero initially, until a quantity +such as an exact download size becomes known. + +The progress callback function is also the supported way to +\fIinterrupt\fP the download operation. (The library does \fInot\fP +modify or trigger signals.) The progress callback must return 0 to +continue the work, or any other value to stop work as soon as +possible. Consequently, the \fBdebuginfod_find_*\fP() function will +likely return with an error, but might still succeed. + + +.SH "CACHE" +If the query is successful, the \fBdebuginfod_find_*\fP() functions save +the target file to a local cache. The location of the cache is controlled +by the \fB$DEBUGINFOD_CACHE_PATH\fP environment variable (see below). +Cleaning of the cache is controlled by the \fIcache_clean_interval_s\fP +and \fImax_unused_age_s\fP files, which are found in the +\fB$DEBUGINFOD_CACHE_PATH\fP directory. \fIcache_clean_interval_s\fP controls +how frequently the cache is traversed for cleaning and \fImax_unused_age_s\fP +controls how long a file can go unused (fstat(2) atime) before it's +removed from the cache during cleaning. These files should contain only an +ASCII decimal integer representing the interval or max unused age in seconds. +The default is one day and one week, respectively. Values of zero mean "immediately". + +.SH "SECURITY" +.BR debuginfod_find_debuginfo (), +.BR debuginfod_find_executable (), +and +.BR debuginfod_find_source () +\fBdo not\fP include any particular security +features. They trust that the binaries returned by the debuginfod(s) +are accurate. Therefore, the list of servers should include only +trustworthy ones. If accessed across HTTP rather than HTTPS, the +network should be trustworthy. Passing user authentication information +through the internal \fIlibcurl\fP library is not currently enabled, except +for the basic plaintext \%\fIhttp[s]://userid:password@hostname/\fP style. +(The debuginfod server does not perform authentication, but a front-end +proxy server could.) + +.SH "ENVIRONMENT VARIABLES" + +.TP 21 +.B DEBUGINFOD_URLS +This environment variable contains a list of URL prefixes for trusted +debuginfod instances. Alternate URL prefixes are separated by space. + +.TP 21 +.B DEBUGINFOD_TIMEOUT +This environment variable governs the timeout for each debuginfod HTTP +connection. A server that fails to respond within this many seconds +is skipped. The default is 5. + +.TP 21 +.B DEBUGINFOD_CACHE_PATH +This environment variable governs the location of the cache where +downloaded files are kept. It is cleaned periodically as this +program is reexecuted. The default is $HOME/.debuginfod_client_cache. + +.SH "ERRORS" +The following list is not comprehensive. Error codes may also +originate from calls to various C Library functions. + +.TP +.BR EACCESS +Denied access to resource located at the URL. + +.TP +.BR ECONNREFUSED +Unable to connect to remote host. + +.TP +.BR ECONNRESET +Unable to either send or recieve network data. + +.TP +.BR EHOSTUNREACH +Unable to resolve remote host. + +.TP +.BR EINVAL +One or more arguments are incorrectly formatted. \fIbuild_id\fP may +be too long (greater than 256 characters), \fIfilename\fP may not +be an absolute path or a debuginfod URL is malformed. + +.TP +.BR EIO +Unable to write data received from server to local file. + +.TP +.BR EMLINK +Too many HTTP redirects. + +.TP +.BR ENETUNREACH +Unable to initialize network connection. + +.TP +.BR ENOENT +Could not find the resource located at URL. Often this error code +indicates that a debuginfod server was successfully contacted but +the server could not find the target file. + +.TP +.BR ENOMEM +System is unable to allocate resources. + +.TP +.BR ENOSYS +\fB$DEBUGINFOD_URLS\fP is not defined. + +.TP +.BR ETIME +Query failed due to timeout. \fB$DEBUGINFOD_TIMEOUT\fP controls +the timeout duration. See debuginfod(8) for more information. + +.SH "FILES" +.LP +.PD .1v +.TP 20 +.B $HOME/.debuginfod_client_cache +Default cache directory. +.PD + +.SH "SEE ALSO" +.I "debuginfod(8)" diff --git a/doc/debuginfod_find_executable.3 b/doc/debuginfod_find_executable.3 new file mode 100644 index 00000000..16279936 --- /dev/null +++ b/doc/debuginfod_find_executable.3 @@ -0,0 +1 @@ +.so man3/debuginfod_find_debuginfo.3 diff --git a/doc/debuginfod_find_source.3 b/doc/debuginfod_find_source.3 new file mode 100644 index 00000000..16279936 --- /dev/null +++ b/doc/debuginfod_find_source.3 @@ -0,0 +1 @@ +.so man3/debuginfod_find_debuginfo.3 diff --git a/doc/debuginfod_set_progressfn.3 b/doc/debuginfod_set_progressfn.3 new file mode 100644 index 00000000..16279936 --- /dev/null +++ b/doc/debuginfod_set_progressfn.3 @@ -0,0 +1 @@ +.so man3/debuginfod_find_debuginfo.3 diff --git a/doc/elf_begin.3 b/doc/elf_begin.3 new file mode 100644 index 00000000..6a1d0c27 --- /dev/null +++ b/doc/elf_begin.3 @@ -0,0 +1,37 @@ +.\" Modified Thu Sep 5 2017 by Ben Woodard <[email protected]> +.\" +.TH ELF_BEGIN 3 2017-09-05 "Libelf" "Libelf Programmer's Manual" +.SH NAME +elf_begin \- Return descriptor for ELF file. +.nf +.SH SYNOPSIS +.B #include <libelf.h> +.sp +.BI "Elf *elf_begin (int " filedes ", Elf_Cmd " cmd ", Elf *" ref ");" +.BI "Elf *elf_clone (int " filedes ", Elf_Cmd " cmd ");" +.BI "int elf_end (Elf *" elf ");" +.fi +.SH DESCRIPTION +The +.BR elf_begin () +.SH RETURN VALUE +.SH ERRORS +elf_begin ELF_E_NO_VERSION ELF_E_INVALID_FILE ELF_E_INVALID_CMD ELF_E_NOMEM +elf_clone ELF_E_NOMEM +elf_end +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw29 lb lb +l l l. +Interface Attribute Value +T{ +.BR elf_begin (), +.BR elf_clone (), +.BR elf_end () +T} Thread safety MT-Safe +.TE + +.SH SEE ALSO diff --git a/doc/elf_clone.3 b/doc/elf_clone.3 new file mode 100644 index 00000000..38ec9217 --- /dev/null +++ b/doc/elf_clone.3 @@ -0,0 +1,14 @@ +.\" Modified Thu Sep 5 2017 by Ben Woodard <[email protected]> +.\" +.TH ELF_CLONE 3 2017-09-05 "Libelf" "Libelf Programmer's Manual" +.SH NAME +elf_clone \- Create a clone of an existing ELF descriptor. +.nf +.SH SYNOPSIS +.B #include <libelf.h> +.sp +.BI "Elf *elf_clone (int " filedes ", Elf_Cmd " cmd ");" +.fi +.SH DESCRIPTION +The +.BR elf_clone () diff --git a/doc/elf_getdata.3 b/doc/elf_getdata.3 new file mode 100644 index 00000000..44d9304e --- /dev/null +++ b/doc/elf_getdata.3 @@ -0,0 +1,28 @@ +.\" Modified Thu Aug 17 2017 by Ben Woodard <[email protected]> +.\" +.TH ELF_GETDATA 3 2017-08-17 "Libelf" "Libelf Programmer's Manual" +.SH NAME +elf_getdata \- Get washed data of section +.nf +.SH SYNOPSIS +.B #include <libelf.h> +.sp +.BI "Elf_Data * elf_getdata (Elf_Scn *" scn ", Elf_Data *" data ");" +.fi +.SH DESCRIPTION +The +.BR elf_getdata () +function allows the user to retrieve the data buffers of the section +.I scn + . There can be more than one buffer if the user explicitly added them. +When a file is read the libelf library creates exactly one data buffer. + +The first buffer in the list can be obtained by passing a null pointer in the +parameter data. To get the next data buffer the previously returned value must +be passed in the data parameter. If there are no more buffer left in the list a +null pointer is returned. + +If the data parameter is not a null pointer it must be a descriptor for a +buffer associated with the section scn . If this is not the case a null pointer +is returned. To facilitate error handling elf_getdata also returns a null +pointer if the scn parameter is a null pointer. diff --git a/doc/elf_update.3 b/doc/elf_update.3 new file mode 100644 index 00000000..d0a7ab10 --- /dev/null +++ b/doc/elf_update.3 @@ -0,0 +1,14 @@ +.\" Modified Thu Sep 5 2017 by Ben Woodard <[email protected]> +.\" +.TH ELF_UPDATE 3 2017-09-05 "Libelf" "Libelf Programmer's Manual" +.SH NAME +elf_update \- update an ELF descriptor +.nf +.SH SYNOPSIS +.B #include <libelf.h> +.sp +.BI "off_t elf_update (Elf *" elf ", Elf_Cmd " cmd ");" +.fi +.SH DESCRIPTION +The +.BR elf_update () diff --git a/doc/elfclassify.1 b/doc/elfclassify.1 new file mode 100644 index 00000000..cbfdae48 --- /dev/null +++ b/doc/elfclassify.1 @@ -0,0 +1,197 @@ +.\" Copyright 2019 Red Hat Inc. +.\" Tue 2019-Aug 20 Ben Woodard <[email protected]> +.\" Florian Wiemer <[email protected]> +.\" Mark Wielaard <[email protected]> +.\" Contact [email protected] to correct errors or typos. +.TH EU-ELFCLASSIFY 1 "2019-Aug-20" "elfutils" +.SH "NAME" +eu-elfclassify \- Determine the type of an ELF file. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +eu-elfclassify [\fB\-\-core\fR] + [\fB\-\-debug-only\fR] + [\fB\-\-elf\fR] + [\fB\-\-elf\-archive\fR] + [\fB\-\-elf\-file\fR] + [\fB\-\-executable\fR] + [\fB\-\-library\fR] + [\fB\-\-linux\-kernel\-module\fR] + [\fB\-\-loadable\fR] + [\fB\-\-program\fR] + [\fB\-\-shared\fR] + [\fB\-\-unstripped\fR] + [\fB\-f\fR|\fB \-\-file\fR] + [\fB\-\-no\-stdin\fR] + [\fB\-\-stdin\fR] + [\fB\-\-stdin0\fR] + [\fB\-z\fR|\fB \-\-compressed\fR] + [\fB\-\-matching\fR] + [\fB\-\-no\-print\fR] + [\fB\-\-not\-matching\fR] + [\fB\-\-print\fR] + [\fB\-\-print0\fR] + [\fB\-q\fR|\fB \-\-quiet\fR] + [\fB\-v\fR|\fB \-\-verbose\fR] + [\fB\-?\fR|\fB \-\-help\fR] + [\fB\-\-usage\fR] + [\fB\-V\fR|\fB \-\-version\fR] + \fIelffile\fR... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBeu-elfclassify\fR identifies the primary purpose of a particular kind of + \s-1ELF\s0 file or files +.SH "OPTIONS" +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. All of the classification options must apply at the same time to a +particular file. Classification options can be negated using a +\fB\-\-not\-\fR prefix. +.SS "Classification Options" +.IX Subsection "Classification Options" +.IP "\fB\-\-core\fR" 4 +.IX Item "--core" +.PD +File is an ELF core dump file. +.IP "\FB\-\-debug\-only\fR" 4 +.IX Item "--debug-only" +.PD +File is a debug only ELF file (separate .debug, .dwo or dwz multi-file). +.IP "\fB\-\-elf\fR" 4 +.IX Item "--elf" +.PD +File looks like an ELF object or archive/static library (default). +.IP "\fB\-\-elf\-archive\fR" 4 +.IX Item "--elf-archive" +.PD +File is an ELF archive or static library. +.IP "\fB\-\-elf\-file\fR" 4 +.IX Item "--elf-file" +.PD +File is an regular ELF object (not an archive/static library). +.IP "\fB\-\-executable\fR" 4 +.IX Item "--executable" +.PD +File is (primarily) an ELF program executable (not primarily a DS.O) +.IP "\fB\-\-library\fR" 4 +.IX Item "--library" +.PD +File is an ELF shared object (DSO) (might also be an executable). +.IP "\fB\-\-linux\-kernel\-module\fR" 4 +.IX Item "--linux-kernel-module" +.PD +File is a linux kernel module. +.IP "\fB\-\-loadable\fR" 4 +.IX Item "--loadable" +.PD +File is a loadable ELF object (program or shared object). +.IP "\fB\--program\fR" 4 +.IX Item "--program" +.PD +File is an ELF program executable (might also be a DSO). +.IP "\fB\-\-shared\fR" 4 +.IX Item "--shared" +.PD +File is (primarily) an ELF shared object (DSO) (not primarily an executable). +.IP "\fB\-\-unstripped\fR" 4 +.IX Item "--unstripped" +.PD +File is an ELF file with symbol table or .debug_* sections and can be stripped +further. +.SS "Input flags" +.IX Subsection "Input flags" +.IP "\fB\-f\fR" 4 +.IX Item "-f" +.PD 0 +.IP "\fB\-\-file\fR" 4 +.IX Item "--file" +.PD +Only classify regular (not symlink nor special device) files. +.IP "\fB\-\-no\-stdin\fR" 4 +.IX Item "--no-stdin" +.PD +Do not read files from standard input (default). +.IP "\fB\-\-stdin\fR" 4 +.IX Item "--stdin" +.PD +Also read file names to process from standard input, separated by newlines. +.IP "\fB\-\-stdin0\fR" 4 +.IX Item "--stdin0" +.PD +Also read file names to process from standard input, separated by ASCII NUL +bytes. +.IP "\fB\-z\fR" 4 +.IX Item "-z" +.PD 0 +.IP "\fB\-\-compressed\fR" 4 +.IX Item "--compressed" +.PD +Try to open compressed files or embedded (kernel) ELF images. +.SS "Output flags" +.IX Subsection "Output flags" +.IP "\fB\-\-matching\fR" 4 +.IX Item "--matching" +.PD +If printing file names, print matching files (default). +.IP "\fB\-\-no\-print\fR" 4 +.IX Item "--no-print" +.PD +Do not output file names. +.IP "\fB\-\-not\-matching\fR" 4 +.IX Item "--not-matching" +.PD +If printing file names, print files that do not match. +.IP "\fB\-\-print\fR" 4 +.IX Item "--print" +.PD +Output names of files, separated by newline. +.IP "\fB\-\-print0\fR" 4 +.IX Item "--print0" +.PD +Output names of files, separated by ASCII NUL. +.SS " Additional flags" +.IX Subsection " Additional flags" +.IP "\fB\-q\fR" 4 +.IX Item "-q," +.PD +.IP "\fB\-\-quiet\fR" 4 +.IX Item "--quiet" +.PD +Suppress some error output (counterpart to --verbose). +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD +.IP "\fB\-\-verbose\fR" 4 +.IX Item "--verbose" +.PD +Output additional information (can be specified multiple times). +.IP "\fB\-?\fR" 4 +.IX Item "-?" +.PD +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.PD +Give this help list. +.IP "\fB\-\-usage\fR" 4 +.IX Item "--usage" +.PD +Give a short usage message. +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Print program version. + +.SH "AUTHOR" +.IX Header "AUTHOR" +Written by Florian Wiemer. +.SH "REPORTING BUGS" +.IX Header "REPORTING BUGS" +Please reports bugs at https://sourceware.org/bugzilla/ +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright © 2019 Red Hat Inc. License GPLv3+: GNU GPL version 3 or +later <https://gnu.org/licenses/gpl.html>. This is free software: you +are free to change and redistribute it. There is NO WARRANTY, to the +extent permitted by law. diff --git a/doc/readelf.1 b/doc/readelf.1 new file mode 100644 index 00000000..33263819 --- /dev/null +++ b/doc/readelf.1 @@ -0,0 +1,511 @@ +.\" Modified from readelf.1 man page +.\" Tue 2019-Aug 20 by Ben Woodard <[email protected]> +.\" Contact [email protected] to correct errors or typos. +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1q +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "EU-READELF 1" +.TH EU-READELF 1 "2019-Aug-20" "elfutils" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +eu-readelf \- Displays information about ELF files. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +eu-readelf [\fB\-a\fR|\fB\-\-all\fR] + [\fB\-h\fR|\fB\-\-file\-header\fR] + [\fB\-l\fR|\fB\-\-program\-headers\fR|\fB\-\-segments\fR] + [\fB\-S\fR|\fB\-\-section\-headers\fR|\fB\-\-sections\fR] + [\fB\-g\fR|\fB\-\-section\-groups\fR] + [\fB\-e\fR|\fB\-\-exception\fR] + [\fB\-s\fR|\fB\-\-symbols\fR] [section name] ] + [\fB\-\-dyn-syms\fR] + [\fB\-n\fR|\fB\-\-notes\fR [section name] ] + [\fB\-r\fR|\fB\-\-relocs\fR] + [\fB\-d\fR|\fB\-\-dynamic\fR] + [\fB\-V\fR|\fB\-\-version\-info\fR] + [\fB\-A\fR|\fB\-\-arch\-specific\fR] + [\fB\-x\fR <number or name>|\fB\-\-hex\-dump=\fR<number or name>] + [\fB\-p\fR <number or name>|\fB\-\-string\-dump=\fR<number or name>] + [\fB\-z\fR|\fB\-\-decompress\fR] + [\fB\-c\fR|\fB\-\-archive\-index\fR] + [\fB\-\-dwarf\-skeleton\fR <file> ] + [\fB\-\-elf\-section\fR [section] ] + [\fB\-w\fR| + \fB\-\-debug\-dump\fR[=line,=decodedline,=info,=info+,=abbrev,=pubnames,=aranges,=macro,=frames,=str,=loc,=ranges,=gdb_index,=addr]] + [\fB\-I\fR|\fB\-\-histogram\fR] + [\fB\-v\fR|\fB\-\-version\fR] + [\fB\-W\fR|\fB\-\-wide\fR] + [\fB\-H\fR|\fB\-\-help\fR] + \fIelffile\fR... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBeu-readelf\fR displays information about one or more \s-1ELF\s0 format object +files. The options control what particular information to display. +.PP +\&\fIelffile\fR... are the object files to be examined. 32\-bit and +64\-bit \s-1ELF\s0 files are supported, as are archives containing \s-1ELF\s0 files. +.PP +This program performs a similar function to \fBobjdump\fR but it +goes into more detail and it exists independently of the \s-1BFD\s0 +library, so if there is a bug in \s-1BFD\s0 then readelf will not be +affected. +.SH "OPTIONS" +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. At least one option in addition to \fB\-v\fR or \fB\-H\fR must be +given. +.SS "ELF Input Selection" +.IX Subsection "ELF Input Selection" +.IP "\fB\-\-dwarf\-skeleton <file>\fR" 4 +.IX Item "--dwarf-skeleton <file>" +.PD +Used with -w to find the skeleton Compile Units in FILE associated +with the Split Compile units in a .dwo input file. +.IP "\fB\-\-elf\-section [section]\fR" 4 +.IX Item "--elf-section [section]" +.PD +Use the named SECTION (default .gnu_debugdata) as (compressed) ELF input data +.SS "ELF Output Selection" +.IX Subsection "ELF Output Selection" +.IP "\fB\-a\fR" 4 +.IX Item "-a" +.PD 0 +.IP "\fB\-\-all\fR" 4 +.IX Item "--all" +.PD +Equivalent to specifying \fB\-\-file\-header\fR, +\&\fB\-\-program\-headers\fR, \fB\-\-sections\fR, \fB\-\-symbols\fR, +\&\fB\-\-relocs\fR, \fB\-\-dynamic\fR, \fB\-\-notes\fR, +\&\fB\-\-version\-info\fR, \fB\-\-arch\-specific\fR, +\&\fB\-\-section\-groups\fR and \fB\-\-histogram\fR. +.Sp +.IP "\fB\-h\fR" 4 +.IX Item "-h" +.PD 0 +.IP "\fB\-\-file\-header\fR" 4 +.IX Item "--file-header" +.PD +Displays the information contained in the \s-1ELF\s0 header at the start of the +file. +.IP "\fB\-l\fR" 4 +.IX Item "-l" +.PD 0 +.IP "\fB\-\-program\-headers\fR" 4 +.IX Item "--program-headers" +.IP "\fB\-\-segments\fR" 4 +.IX Item "--segments" +.PD +Displays the information contained in the file's segment headers, if it +has any. +.IP "\fB\-S\fR" 4 +.IX Item "-S" +.PD 0 +.IP "\fB\-\-sections\fR" 4 +.IX Item "--sections" +.IP "\fB\-\-section\-headers\fR" 4 +.IX Item "--section-headers" +.PD +Displays the information contained in the file's section headers, if it +has any. +.IP "\fB\-g\fR" 4 +.IX Item "-g" +.PD 0 +.IP "\fB\-\-section\-groups\fR" 4 +.IX Item "--section-groups" +.PD +Displays the information contained in the file's section groups, if it +has any. +.IP "\fB\-I\fR" 4 +.IX Item "-I" +.PD 0 +.IP "\fB\-\-histogram\fR" 4 +.IX Item "--histogram" +.PD +Display a histogram of bucket list lengths when displaying the contents +of the symbol tables. +.IP "\fB\-s\fR" 4 +.IX Item "-s" +.PD 0 +.IP "\fB\-\-symbols\fR [section name]" 4 +.IX Item "--symbols" +.PD +Displays the entries in symbol table section of the file, if it has one. +If a symbol has version information associated with it then this is +displayed as well. The version string is displayed as a suffix to the +symbol name, preceeded by an @ character. For example +\&\fBfoo@VER_1\fR. If the version is the default version to be used +when resolving unversioned references to the symbol then it is +displayed as a suffix preceeded by two @ characters. For example +\&\fBfoo@@VER_2\fR. +.IP "\fB\-\-dyn-syms\fR" 4 +.IX Item "--dyn-syms" +.PD +Display (only) the dynamic symbol table. +.IP "\fB\-e\fR" 4 +.IX Item "-e" +.PD 0 +.IP "\fB\-\-exception\fR" 4 +.IX Item "--exception" +.PD +Display sections for exception handling. +.IP "\fB\-n\fR" 4 +.IX Item "-n [section name]" +.PD 0 +.IP "\fB\-\-notes [section name]\fR" 4 +.IX Item "--notes" +.PD +Displays the contents of the \s-1NOTE\s0 segments and/or sections, if any. +.IP "\fB\-r\fR" 4 +.IX Item "-r" +.PD 0 +.IP "\fB\-\-relocs\fR" 4 +.IX Item "--relocs" +.PD +Displays the contents of the file's relocation section, if it has one. +.IP "\fB\-d\fR" 4 +.IX Item "-d" +.PD 0 +.IP "\fB\-\-dynamic\fR" 4 +.IX Item "--dynamic" +.PD +Displays the contents of the file's dynamic section, if it has one. +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD 0 +.IP "\fB\-\-version\-info\fR" 4 +.IX Item "--version-info" +.PD +Displays the contents of the version sections in the file, it they +exist. +.IP "\fB\-A\fR" 4 +.IX Item "-A" +.PD 0 +.IP "\fB\-\-arch\-specific\fR" 4 +.IX Item "--arch-specific" +.PD +Displays architecture-specific information in the file, if there +is any. +.SS "Additional output selection" +.IX Subsection "Additional output selection" +.IP "\fB\-x <name>\fR" 4 +.IX Item "-x <name>" +.PD 0 +.IP "\fB\-\-hex\-dump=<name>\fR" 4 +.IX Item "--hex-dump=<name>" +.PD +Displays the contents of the indicated section name as a hexadecimal bytes. +.IP "\fB\-w\fR" 4 +.IX Item "-w" +.PD 0 +.IP "\fB\-\-debug\-dump[=decodedline,=info,=info+,=abbrev,=pubnames,=aranges,=macro,=frames,=str,=loc,=ranges,=gdb_index,=addr]\fR" 4 +.IX Item "--debug-dump[=line,=decodedline,=info,=info+,=abbrev,=pubnames,=aranges,=macro,=frames,=str,=loc,=ranges,=gdb_index,=addr]" +.PD +Displays the contents of the \s-1DWARF\s0 debug sections in the file, if any +are present. Compressed debug sections are automatically decompressed +(temporarily) before they are displayed. If one or more of the +optional letters or words follows the switch then only those type(s) +of data will be dumped. The letters and words refer to the following +information: +.RS 4 +.PD 0 +.ie n .IP """=abbrev""" 4 +.el .IP "\f(CW=abbrev\fR" 4 +.IX Item "=abbrev" +.PD +Displays the contents of the \fB.debug_abbrev\fR section. +.PD 0 +.ie n .IP """=addr""" 4 +.el .IP "\f(CW=addr\fR" 4 +.IX Item "=addr" +.PD +Displays the contents of the \fB.debug_addr\fR section. +.PD 0 +.ie n .IP """=frames""" 4 +.el .IP "\f(CW=frames\fR" 4 +.IX Item "=frames" +.PD +Display the raw contents of a \fB.debug_frame\fR section. +.PD 0 +.ie n .IP """=gdb_index""" 4 +.el .IP "\f(CW=gdb_index\fR" 4 +.IX Item "=gdb_index" +.PD +Displays the contents of the \fB.gdb_index\fR and/or +\&\fB.debug_names\fR sections. +.PD 0 +.ie n .IP """=info""" 4 +.el .IP "\f(CW=info\fR" 4 +.IX Item "=info" +.PD +Displays the contents of the \fB.debug_info\fR section. +.PD 0 +.ie n .IP """=info+""" 4 +.el .IP "\f(CW=info+\fR" 4 +.IX Item "=info+" +.PD +Displays the contents of the \fB.debug_info\fR section, plus any skeleton +unit will be immediately followed by the corresponding split compile unit +(from the .dwo file). To show the difference between "regular" CUs and +split CUs print offsets and references between { and } instead of [ and ]. +.PD 0 +.ie n .IP """=decodedline""" 4 +.el .IP "\f(CW=decodedline\fR" 4 +.IX Item "=decodedline" +.PD +Displays the interpreted contents of the \fB.debug_line\fR section. +.PD 0 +.ie n .IP """=macro""" 4 +.el .IP "\f(CW=macro\fR" 4 +.IX Item "=macro" +.PD +Displays the contents of the \fB.debug_macro\fR and/or +\&\fB.debug_macinfo\fR sections. +.PD 0 +.ie n .IP """=loc""" 4 +.el .IP "\f(CW=loc\fR" 4 +.IX Item "=loc" +.PD +Displays the contents of the \fB.debug_loc\fR and/or +\&\fB.debug_loclists\fR sections. +.PD 0 +.ie n .IP """=pubnames""" 4 +.el .IP "\f(CW=pubnames\fR" 4 +.IX Item "=pubnames" +.PD +Displays the contents of the \fB.debug_pubnames\fR and/or +\&\fB.debug_gnu_pubnames\fR sections. +.PD 0 +.ie n .IP """=aranges""" 4 +.el .IP "\f(CW=aranges\fR" 4 +.IX Item "=aranges" +.PD +Displays the contents of the \fB.debug_aranges\fR section. +.PD 0 +.ie n .IP """=ranges""" 4 +.el .IP "\f(CW=ranges\fR" 4 +.IX Item "=ranges" +.PD +Displays the contents of the \fB.debug_ranges\fR and/or +\&\fB.debug_rnglists\fR sections. +.PD 0 +.ie n .IP """=str""" 4 +.el .IP "\f(CW=str\fR" 4 +.IX Item "=str" +.PD +Displays the contents of the \fB.debug_str\fR, \fB.debug_line_str\fR +and/or \fB.debug_str_offsets\fR sections. +.PD 0 +.RS 4 +.Sp +Note: displaying the contents of \fB.debug_static_funcs\fR, +\&\fB.debug_static_vars\fR and \fBdebug_weaknames\fR sections is not +currently supported. +.RE +.IP "\fB\-p <number or name>\fR" 4 +.IX Item "-p <number or name>" +.PD 0 +.IP "\fB\-\-string\-dump=<number or name>\fR" 4 +.IX Item "--string-dump=<number or name>" +.PD +Displays the contents of the indicated section as printable strings. +A number identifies a particular section by index in the section table; +any other string identifies all sections with that name in the object file. +.IP "\fB\-c\fR" 4 +.IX Item "-c" +.PD 0 +.IP "\fB\-\-archive\-index\fR" 4 +.IX Item "--archive-index" +.PD +Displays the file symbol index information contained in the header part +of binary archives. Performs the same function as the \fBt\fR +command to \fBar\fR, but without using the \s-1BFD\s0 library. +.SS "Output control" +.IX Subsection "Output control" +.IP "\fB\-z\fR" 4 +.IX Item "-z" +.PD 0 +.IP "\fB\-\-decompress\fR" 4 +.IX Item "--decompress" +.PD +Requests that the section(s) being dumped by \fBx\fR, \fBR\fR or +\&\fBp\fR options are decompressed before being displayed. If the +section(s) are not compressed then they are displayed as is. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Display the version number of eu-readelf. +.IP "\fB\-W\fR" 4 +.IX Item "-W" +.PD 0 +.IP "\fB\-\-wide\fR" 4 +.IX Item "--wide" +.PD +Ignored for compatibility (lines always wide). +.IP "\fB\-H\fR" 4 +.IX Item "-H" +.PD 0 +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.PD +Display the command line options understood by \fBeu-readelf\fR. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR 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 \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIobjdump\fR\|(1), \fIreadelf\fR\|(1) and the Info entries for +\fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991\-2018 Free Software Foundation, Inc. + +Copyright (c) 2019 Red Hat Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". |