1pahole(1)                           dwarves                          pahole(1)
2
3
4

NAME

6       pahole - Shows and manipulates data structure layout.
7

SYNOPSIS

9       pahole [options] files
10

DESCRIPTION

12       pahole  shows  data  structure layouts encoded in debugging information
13       formats, DWARF and CTF being supported.
14
15       This is useful for,  among  other  things:  optimizing  important  data
16       structures by reducing its size, figuring out what is the field sitting
17       at an offset from the start of  a  data  structure,  investigating  ABI
18       changes  and  more  generally  understanding a new codebase you have to
19       work with.
20
21       The files must have associated debugging information.  This information
22       may be inside the file itself, in ELF sections, or in another file.
23
24       One  way  to  have  this information is to specify the -g option to the
25       compiler when building it. When this is done the  information  will  be
26       stored  in  an  ELF section. For the DWARF debugging information format
27       this, adds, among others, the .debug_info ELF section. For  CTF  it  is
28       found in just one ELF section, .SUNW_ctf.
29
30       The  debuginfo  packages available in most Linux distributions are also
31       supported by pahole, where the debugging information is available in  a
32       separate file.
33
34       By  default,  pahole shows the layout of all named structs in the files
35       specified.
36
37

OPTIONS

39       pahole supports the following options.
40
41
42       -C, --class_name=CLASS_NAMES
43              Show just these classes. This can be a comma separated  list  of
44              class names or file URLs (e.g.: file://class_list.txt)
45
46
47       -c, --cacheline_size=SIZE
48              Set cacheline size to SIZE bytes.
49
50
51       -E, --expand_types
52              Expand  class  members.  Useful  to find in what member of inner
53              structs where an offset from the beginning of a struct is.
54
55
56       -F, --format_path
57              Allows specifying a list of debugging formats to try, in  order.
58              Right  now  this  includes "ctf" and "dwarf". The default format
59              path used is equivalent to "-F dwarf,ctf".
60
61
62       --hex  Print offsets and sizes in hexadecimal.
63
64
65       -r, --rel_offset
66              Show relative offsets of members in inner structs.
67
68
69       -p, --expand_pointers
70              Expand class pointer members.
71
72
73       -R, --reorganize
74              Reorganize struct, demoting and combining bitfields, moving mem‐
75              bers to remove alignment holes and padding.
76
77
78       -S, --show_reorg_steps
79              Show the struct layout at each reorganization step.
80
81
82       -i, --contains=CLASS_NAME
83              Show classes that contains CLASS_NAME.
84
85
86       -a, --anon_include
87              Include anonymous classes.
88
89
90       -A, --nested_anon_include
91              Include nested (inside other structs) anonymous classes.
92
93
94       -B, --bit_holes=NR_HOLES
95              Show only structs at least NR_HOLES bit holes.
96
97
98       -d, --recursive
99              Recursive mode, affects several other flags.
100
101
102       -D, --decl_exclude=PREFIX
103              exclude classes declared in files with PREFIX.
104
105
106       -f, --find_pointers_to=CLASS_NAME
107              Find pointers to CLASS_NAME.
108
109
110       -H, --holes=NR_HOLES
111              Show only structs with at least NR_HOLES holes.
112
113
114       -I, --show_decl_info
115              Show  the  file  and line number where the tags were defined, if
116              available in the debugging information.
117
118
119       -l, --show_first_biggest_size_base_type_member
120              Show first biggest size base_type member.
121
122
123       -m, --nr_methods
124              Show number of methods.
125
126
127       -M, --show_only_data_members
128              Show only the members that use space in the  class  layout.  C++
129              methods will be suppressed.
130
131
132       -n, --nr_members
133              Show number of members.
134
135
136       -N, --class_name_len
137              Show size of classes.
138
139
140       -O, --dwarf_offset=OFFSET
141              Show tag with DWARF OFFSET.
142
143
144       -P, --packable
145              Show  only  structs that has holes that can be packed if members
146              are  reorganized,  for  instance  when  using  the  --reorganize
147              option.
148
149
150       -q, --quiet
151              Be quieter.
152
153
154       -s, --sizes
155              Show size of classes.
156
157
158       -t, --separator=SEP
159              Use SEP as the field separator.
160
161
162       -T, --nr_definitions
163              Show how many times struct was defined.
164
165
166       -u, --defined_in
167              Show CUs where CLASS_NAME (-C) is defined.
168
169
170       --flat_arrays
171              Flatten  arrays, so that array[10][2] becomes array[20].  Useful
172              when generating from both CTF/BTF and DWARF  encodings  for  the
173              same binary for testing purposes.
174
175
176       --suppress_aligned_attribute
177              Suppress  forced  alignment markers, so that one can compare BTF
178              or CTF output, that don't have that info, to output  from  DWARF
179              >= 5.
180
181
182       --suppress_force_paddings
183
184              Suppress  bitfield forced padding at the end of structs, as this
185              requires something like DWARF's DW_AT_alignment, so that one can
186              compare BTF or CTF output, that don't have that info.
187
188
189       --suppress_packed
190
191              Suppress      the     output     of     the     inference     of
192              __attribute__((__packed__)), so that one can compare BTF or  CTF
193              output,  the  inference  algorithm uses things like DW_AT_align‐
194              ment, so until it is improved to infer that  as  well  for  BTF,
195              allow disabling this output.
196
197
198       --fixup_silly_bitfields
199              Converts  silly  bitfields  such  as  "int foo:32" to plain "int
200              foo".
201
202
203       -V, --verbose
204              be verbose
205
206
207       -w, --word_size=WORD_SIZE
208              Change the arch word size to WORD_SIZE.
209
210
211       -x, --exclude=PREFIX
212              Exclude PREFIXed classes.
213
214
215       -X, --cu_exclude=PREFIX
216              Exclude PREFIXed compilation units.
217
218
219       -y, --prefix_filter=PREFIX
220              Include PREFIXed classes.
221
222
223       -z, --hole_size_ge=HOLE_SIZE
224              Show only structs with at least one hole  greater  or  equal  to
225              HOLE_SIZE.
226
227

NOTES

229       To  enable  the generation of debugging information in the Linux kernel
230       build process select CONFIG_DEBUG_INFO. This can  be  done  using  make
231       menuconfig  by  this  path:  "Kernel  Hacking" -> "Kernel Debugging" ->
232       "Compile the kernel with debug info".
233
234       Many distributions also come with debuginfo packages, so just enable it
235       in  your  package manager repository configuration and install the ker‐
236       nel-debuginfo, or any other userspace program  written  in  a  language
237       that the compiler generates debuginfo (C, C++, for instance).
238
239

SEE ALSO

241       eu-readelf(1), readelf(1), objdump(1).
242
243       https://www.kernel.org/doc/ols/2007/ols2007v2-pages-35-44.pdf.
244

AUTHOR

246       pahole  was  written  by  Arnaldo  Carvalho  de  Melo <acme@ghostproto‐
247       cols.net>.
248
249       Please send bug reports to <dwarves@vger.kernel.org>.
250
251       No subscription is required.
252
253
254
255dwarves                        February 13, 2009                     pahole(1)
Impressum