llvm.org GIT mirror llvm / dc878ec
[docs][llvm-readobj] Improve llvm-readobj documentation There were a number of issues with the llvm-readobj documentation. The following points were raised in https://bugs.llvm.org/show_bug.cgi?id=42255, and have been fixed in this patch: 1. The description section claimed "The tool and its output is primarily designed for use in FileCheck-based tests" which is not really the case any more. 2. The documentation used single-dash long options for option names, but references in the help text to other options exclusively used double-dashes. Fixed by standardising on double-dashes for all long-form options. 3. The majority of options available and in the help text were not present in the documentation. This patch adds them. 4. Several aliases, both long and short, were missing, e.g. --relocs. Additionally, this patch improves the documentation by: 1. Splitting the options into categories based on the file format they are specific to. 2. Updating the Exit Status section to correctly mention that errors lead to a non-zero exit code. 3. Adding a See Also section referencing other similar LLVM tools. 4. Improving/correcting some of the descriptions of options that did not quite match up with what llvm-readobj does. Reviewed by: peter.smith, MaskRay, mtrent Differential Revision: https://reviews.llvm.org/D63719 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@364306 91177308-0d34-0410-b5e6-96231b3b80d8 James Henderson a month ago
1 changed file(s) with 243 addition(s) and 62 deletion(s). Raw diff Collapse all Expand all
99 -----------
1010
1111 The :program:`llvm-readobj` tool displays low-level format-specific information
12 about one or more object files. The tool and its output is primarily designed
13 for use in FileCheck-based tests.
14
15 OPTIONS
16 -------
12 about one or more object files.
1713
1814 If ``input`` is "``-``" or omitted, :program:`llvm-readobj` reads from standard
1915 input. Otherwise, it will read from the specified ``filenames``.
2016
21 .. option:: -help
22
23 Print a summary of command line options.
24
25 .. option:: -version
26
27 Display the version of this program
28
29 .. option:: -file-headers, -h
17 GENERAL AND MULTI-FORMAT OPTIONS
18 --------------------------------
19
20 These options are applicable to more than one file format, or are unrelated to
21 file formats.
22
23 .. option:: --all
24
25 Equivalent to specifying all the main display options relevant to the file
26 format.
27
28 .. option:: --addrsig
29
30 Display the address-significance table.
31
32 .. option:: --color
33
34 Use colors in the output for warnings and errors.
35
36 .. option:: --expand-relocs
37
38 When used with :option:`--relocations`, display each relocation in an expanded
39 multi-line format.
40
41 .. option:: --file-headers, -h
3042
3143 Display file headers.
3244
33 .. option:: -sections, -s
45 .. option:: --headers, -e
46
47 Equivalent to setting: :option:`--file-headers`, :option:`--program-headers`,
48 and :option:`--sections`.
49
50 .. option:: --help
51
52 Display a summary of command line options.
53
54 .. option:: --help-list
55
56 Display an uncategorized summary of command line options.
57
58 .. option:: --hex-dump=, -x
59
60 Display the specified section(s) as hexadecimal bytes. ``section`` may be a
61 section index or section name.
62
63 .. option:: --needed-libs
64
65 Display the needed libraries.
66
67 .. option:: --relocations, --relocs, -r
68
69 Display the relocation entries in the file.
70
71 .. option:: --sections, --section-headers, -s, -S
3472
3573 Display all sections.
3674
37 .. option:: -section-data, -sd
38
39 When used with ``-sections``, display section data for each section shown.
40
41 .. option:: -section-relocations, -sr
42
43 When used with ``-sections``, display relocations for each section shown.
44
45 .. option:: -section-symbols, -st
46
47 When used with ``-sections``, display symbols for each section shown.
48
49 .. option:: -relocations, -r
50
51 Display the relocation entries in the file.
52
53 .. option:: -symbols, -t
75 .. option:: --section-data, --sd
76
77 When used with :option:`--sections`, display section data for each section shown.
78
79 .. option:: --section-relocations, --sr
80
81 When used with :option:`--sections`, display relocations for each section shown.
82
83 .. option:: --section-symbols, --st
84
85 When used with :option:`--sections`, display symbols for each section shown.
86
87 .. option:: --stackmap
88
89 Display contents of the stackmap section.
90
91 .. option:: --string-dump=, -p
92
93 Display the specified section(s) as a list of strings. ``section`` may be a
94 section index or section name.
95
96 .. option:: --symbols, --syms, -t
5497
5598 Display the symbol table.
5699
57 .. option:: -dyn-symbols
58
59 Display the dynamic symbol table (only for ELF object files).
60
61 .. option:: -unwind, -u
100 .. option:: --unwind, -u
62101
63102 Display unwind information.
64103
65 .. option:: -expand-relocs
66
67 When used with ``-relocations``, display each relocation in an expanded
68 multi-line format.
69
70 .. option:: -dynamic-table
71
72 Display the ELF .dynamic section table (only for ELF object files).
73
74 .. option:: -needed-libs
75
76 Display the needed libraries (only for ELF object files).
77
78 .. option:: -program-headers
79
80 Display the ELF program headers (only for ELF object files).
81
82 .. option:: -elf-section-groups, -g
83
84 Display section groups (only for ELF object files).
85
86 .. option:: -demangle, -C
87
88 Print demangled symbol names in the output.
104 .. option:: --version
105
106 Display the version of this program.
89107
90108 .. option:: @
91109
92110 Read command-line options from response file ``.
111
112 ELF SPECIFIC OPTIONS
113 --------------------
114
115 The following options are implemented only for the ELF file format.
116
117 .. option:: --arm-attributes
118
119 Display the ARM attributes section. Only applicable for ARM architectures.
120
121 .. option:: --demangle, -C
122
123 Display demangled symbol names in the output.
124
125 .. option:: --dyn-relocations
126
127 Display the dynamic relocation entries.
128
129 .. option:: --dyn-symbols, --dyn-syms, --dt
130
131 Display the dynamic symbol table.
132
133 .. option:: --dynamic-table, --dynamic, -d
134
135 Display the dynamic table.
136
137 .. option:: --elf-cg-profile
138
139 Display the callgraph profile section.
140
141 .. option:: --elf-hash-histogram, --histogram, -I
142
143 Display a bucket list histogram for dynamic symbol hash tables.
144
145 .. option:: --elf-linker-options
146
147 Display the linker options section.
148
149 .. option:: --elf-output-style=
150
151 Specify the style to dump ELF information in. Valid options are ``LLVM`` and
152 ``GNU``. ``LLVM`` output (the default) is an expanded and structured format,
153 whilst ``GNU`` output mimics the equivalent GNU :program:`readelf` output.
154
155 .. option:: --elf-section-groups, --section-groups, -g
156
157 Display section groups.
158
159 .. option:: --gnu-hash-table
160
161 Display the GNU hash table for dynamic symbols.
162
163 .. option:: --hash-symbols
164
165 Display the dynamic symbols derived from the hash table.
166
167 .. option:: --hash-table
168
169 Display the hash table for dynamic symbols.
170
171 .. option:: --notes, -n
172
173 Display all notes.
174
175 .. option:: --program-headers, --segments, -l
176
177 Display the program headers.
178
179 .. option:: --raw-relr
180
181 Do not decode relocations in RELR relocation sections when displaying them.
182
183 .. option:: --section-mapping
184
185 Display the section to segment mapping.
186
187 .. option:: --version-info, -V
188
189 Display version sections.
190
191 MACH-O SPECIFIC OPTIONS
192 -----------------------
193
194 The following options are implemented only for the Mach-O file format.
195
196 .. option:: --macho-data-in-code
197
198 Display the Data in Code command.
199
200 .. option:: --macho-dsymtab
201
202 Display the Dsymtab command.
203
204 .. option:: --macho-indirect-symbols
205
206 Display indirect symbols.
207
208 .. option:: --macho-linker-options
209
210 Display the Mach-O-specific linker options.
211
212 .. option:: --macho-segment
213
214 Display the Segment command.
215
216 .. option:: --macho-version-min
217
218 Display the version min command.
219
220 PE/COFF SPECIFIC OPTIONS
221 ------------------------
222
223 The following options are implemented only for the PE/COFF file format.
224
225 .. option:: --codeview
226
227 Display CodeView debug information.
228
229 .. option:: --codeview-ghash
230
231 Enable global hashing for CodeView type stream de-duplication.
232
233 .. option:: --codeview-merged-types
234
235 Display the merged CodeView type stream.
236
237 .. option:: --codeview-subsection-bytes
238
239 Dump raw contents of CodeView debug sections and records.
240
241 .. option:: --coff-basereloc
242
243 Display the .reloc section.
244
245 .. option:: --coff-debug-directory
246
247 Display the debug directory.
248
249 .. option:: --coff-directives
250
251 Display the .drectve section.
252
253 .. option:: --coff-exports
254
255 Display the export table.
256
257 .. option:: --coff-imports
258
259 Display the import table.
260
261 .. option:: --coff-load-config
262
263 Display the load config.
264
265 .. option:: --coff-resources
266
267 Display the .rsrc section.
93268
94269 EXIT STATUS
95270 -----------
96271
97 :program:`llvm-readobj` returns 0.
272 :program:`llvm-readobj` returns 0 under normal operation. It returns a non-zero
273 exit code if there were any errors.
274
275 SEE ALSO
276 --------
277
278 :manpage:`llvm-nm(1)`, :manpage:`llvm-objdump(1)`, :manpage:`llvm-readelf(1)`