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       -r, --rel_offset
63              Show relative offsets of members in inner structs.
64
65
66       -p, --expand_pointers
67              Expand class pointer members.
68
69
70       -R, --reorganize
71              Reorganize struct, demoting and combining bitfields, moving mem‐
72              bers to remove alignment holes and padding.
73
74
75       -S, --show_reorg_steps
76              Show the struct layout at each reorganization step.
77
78
79       -i, --contains=CLASS_NAME
80              Show classes that contains CLASS_NAME.
81
82
83       -a, --anon_include
84              Include anonymous classes.
85
86
87       -A, --nested_anon_include
88              Include nested (inside other structs) anonymous classes.
89
90
91       -B, --bit_holes=NR_HOLES
92              Show only structs at least NR_HOLES bit holes.
93
94
95       -d, --recursive
96              Recursive mode, affects several other flags.
97
98
99       -D, --decl_exclude=PREFIX
100              exclude classes declared in files with PREFIX.
101
102
103       -f, --find_pointers_to=CLASS_NAME
104              Find pointers to CLASS_NAME.
105
106
107       -H, --holes=NR_HOLES
108              Show only structs with at least NR_HOLES holes.
109
110
111       -I, --show_decl_info
112              Show  the  file  and line number where the tags were defined, if
113              available in the debugging information.
114
115
116       -l, --show_first_biggest_size_base_type_member
117              Show first biggest size base_type member.
118
119
120       -m, --nr_methods
121              Show number of methods.
122
123
124       -M, --show_only_data_members
125              Show only the members that use space in the  class  layout.  C++
126              methods will be suppressed.
127
128
129       -n, --nr_members
130              Show number of members.
131
132
133       -N, --class_name_len
134              Show size of classes.
135
136
137       -O, --dwarf_offset=OFFSET
138              Show tag with DWARF OFFSET.
139
140
141       -P, --packable
142              Show  only  structs that has holes that can be packed if members
143              are  reorganized,  for  instance  when  using  the  --reorganize
144              option.
145
146
147       -q, --quiet
148              Be quieter.
149
150
151       -s, --sizes
152              Show size of classes.
153
154
155       -t, --separator=SEP
156              Use SEP as the field separator.
157
158
159       -T, --nr_definitions
160              Show how many times struct was defined.
161
162
163       -u, --defined_in
164              Show CUs where CLASS_NAME (-C) is defined.
165
166
167       --flat_arrays
168              Flatten  arrays, so that array[10][2] becomes array[20].  Useful
169              when generating from both CTF and DWARF encodings for  the  same
170              binary for testing purposes.
171
172
173       --fixup_silly_bitfields
174              Converts  silly  bitfields  such  as  "int foo:32" to plain "int
175              foo".
176
177
178       -V, --verbose
179              be verbose
180
181
182       -w, --word_size=WORD_SIZE
183              Change the arch word size to WORD_SIZE.
184
185
186       -x, --exclude=PREFIX
187              Exclude PREFIXed classes.
188
189
190       -X, --cu_exclude=PREFIX
191              Exclude PREFIXed compilation units.
192
193
194       -y, --prefix_filter=PREFIX
195              Include PREFIXed classes.
196
197
198       -z, --hole_size_ge=HOLE_SIZE
199              Show only structs with at least one hole  greater  or  equal  to
200              HOLE_SIZE.
201
202

NOTES

204       To  enable  the generation of debugging information in the Linux kernel
205       build process select CONFIG_DEBUG_INFO. This can  be  done  using  make
206       menuconfig  by  this  path:  "Kernel  Hacking" -> "Kernel Debugging" ->
207       "Compile the kernel with debug info".
208
209       Many distributions also come with debuginfo packages, so just enable it
210       in  your  package manager repository configuration and install the ker‐
211       nel-debuginfo, or any other userspace program  written  in  a  language
212       that the compiler generates debuginfo (C, C++, for instance).
213
214

SEE ALSO

216       eu-readelf(1), readelf(1), objdump(1).
217
218       http://oops.ghostprotocols.net:81/acme/7dwarves.pdf.
219

AUTHOR

221       pahole  was  written  by  Arnaldo  Carvalho  de  Melo <acme@ghostproto‐
222       cols.net>.
223
224       Please send bug reports to <dwarves@vger.kernel.org>.
225
226       No subscription is required.
227
228
229
230dwarves                        February 13, 2009                     pahole(1)
Impressum