NAME¶
pahole - Shows and manipulates data structure layout.
SYNOPSIS¶
pahole [
options]
files
DESCRIPTION¶
pahole shows data structure layouts encoded in debugging information
formats, DWARF and CTF being supported.
This is useful for, among other things: optimizing important data structures by
reducing its size, figuring out what is the field sitting at an offset from
the start of a data structure, investigating ABI changes and more generally
understanding a new codebase you have to work with.
The files must have associated debugging information. This information may be
inside the file itself, in ELF sections, or in another file.
One way to have this information is to specify the
-g option to the
compiler when building it. When this is done the information will be stored in
an ELF section. For the DWARF debugging information format this, adds, among
others, the
.debug_info ELF section. For CTF it is found in just one
ELF section,
.SUNW_ctf.
The
debuginfo packages available in most Linux distributions are also
supported by
pahole, where the debugging information is available in a
separate file.
By default,
pahole shows the layout of all named structs in the files
specified.
OPTIONS¶
pahole supports the following options.
- -C, --class_name=CLASS_NAMES
- Show just these classes. This can be a comma separated list of class names
or file URLs (e.g.: file://class_list.txt)
- -c, --cacheline_size=SIZE
- Set cacheline size to SIZE bytes.
- -E, --expand_types
- Expand class members. Useful to find in what member of inner structs where
an offset from the beginning of a struct is.
- -F, --format_path
- Allows specifying a list of debugging formats to try, in order. Right now
this includes "ctf" and "dwarf". The default format
path used is equivalent to "-F dwarf,ctf".
- -r, --rel_offset
- Show relative offsets of members in inner structs.
- -p, --expand_pointers
- Expand class pointer members.
- -R, --reorganize
- Reorganize struct, demoting and combining bitfields, moving members to
remove alignment holes and padding.
- -S, --show_reorg_steps
- Show the struct layout at each reorganization step.
- -i, --contains=CLASS_NAME
- Show classes that contains CLASS_NAME.
- -a, --anon_include
- Include anonymous classes.
- -A, --nested_anon_include
- Include nested (inside other structs) anonymous classes.
- -B, --bit_holes=NR_HOLES
- Show only structs at least NR_HOLES bit holes.
- -d, --recursive
- Recursive mode, affects several other flags.
- -D, --decl_exclude=PREFIX
- exclude classes declared in files with PREFIX.
- -f, --find_pointers_to=CLASS_NAME
- Find pointers to CLASS_NAME.
- -H, --holes=NR_HOLES
- Show only structs with at least NR_HOLES holes.
- -I, --show_decl_info
- Show the file and line number where the tags were defined, if available in
the debugging information.
- -l, --show_first_biggest_size_base_type_member
- Show first biggest size base_type member.
- -m, --nr_methods
- Show number of methods.
- -M, --show_only_data_members
- Show only the members that use space in the class layout. C++ methods will
be suppressed.
- -n, --nr_members
- Show number of members.
- -N, --class_name_len
- Show size of classes.
- -O, --dwarf_offset=OFFSET
- Show tag with DWARF OFFSET.
- -P, --packable
- Show only structs that has holes that can be packed if members are
reorganized, for instance when using the --reorganize option.
- -q, --quiet
- Be quieter.
- -s, --sizes
- Show size of classes.
- -t, --separator=SEP
- Use SEP as the field separator.
- -T, --nr_definitions
- Show how many times struct was defined.
- -u, --defined_in
- Show CUs where CLASS_NAME (-C) is defined.
- --flat_arrays
- Flatten arrays, so that array[10][2] becomes array[20]. Useful when
generating from both CTF and DWARF encodings for the same binary for
testing purposes.
- --fixup_silly_bitfields
- Converts silly bitfields such as "int foo:32" to plain "int
foo".
- -V, --verbose
- be verbose
- -w, --word_size=WORD_SIZE
- Change the arch word size to WORD_SIZE.
- -x, --exclude=PREFIX
- Exclude PREFIXed classes.
- -X, --cu_exclude=PREFIX
- Exclude PREFIXed compilation units.
- -y, --prefix_filter=PREFIX
- Include PREFIXed classes.
- -z, --hole_size_ge=HOLE_SIZE
- Show only structs with at least one hole greater or equal to HOLE_SIZE.
NOTES¶
To enable the generation of debugging information in the Linux kernel build
process select CONFIG_DEBUG_INFO. This can be done using make menuconfig by
this path: "Kernel Hacking" -> "Kernel Debugging" ->
"Compile the kernel with debug info".
Many distributions also come with debuginfo packages, so just enable it in your
package manager repository configuration and install the kernel-debuginfo, or
any other userspace program written in a language that the compiler generates
debuginfo (C, C++, for instance).
SEE ALSO¶
eu-readelf(1),
readelf(1),
objdump(1).
http://oops.ghostprotocols.net:81/acme/7dwarves.pdf.
AUTHOR¶
pahole was written by Arnaldo Carvalho de Melo
<acme@ghostprotocols.net>.
Please send bug reports to <dwarves@vger.kernel.org>.
No subscription is required.
