Provided by: dwarves_1.15-1_amd64 bug

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.