pahole(1)

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".

--hex
    Print offsets and sizes in hexadecimal.

-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/BTF and DWARF encodings for the same binary for testing purposes.

--suppress_aligned_attribute
    Suppress forced alignment markers, so that one can compare BTF or CTF output, that don't have that info, to output from DWARF >= 5.

--suppress_force_paddings
    Suppress bitfield forced padding at the end of structs, as this requires something like DWARF's DW_AT_alignment, so that one can compare BTF or CTF output, that don't have that info.

--suppress_packed
    Suppress the output of the inference of __attribute__((__packed__)), so that one can compare BTF or CTF output, the inference algorithm uses things like DW_AT_alignment, so until it is improved to infer that as well for BTF, allow disabling this output.

--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).

https://www.kernel.org/doc/ols/2007/ols2007v2-pages-35-44.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.