1================
2bpftool-btf
3================
4-------------------------------------------------------------------------------
5tool for inspection of BTF data
6-------------------------------------------------------------------------------
7
8:Manual section: 8
9
10SYNOPSIS
11========
12
13	**bpftool** [*OPTIONS*] **btf** *COMMAND*
14
15	*OPTIONS* := { { **-j** | **--json** } [{ **-p** | **--pretty** }] }
16
17	*COMMANDS* := { **dump** | **help** }
18
19BTF COMMANDS
20=============
21
22|	**bpftool** **btf dump** *BTF_SRC* [**format** *FORMAT*]
23|	**bpftool** **btf help**
24|
25|	*BTF_SRC* := { **id** *BTF_ID* | **prog** *PROG* | **map** *MAP* [{**key** | **value** | **kv** | **all**}] | **file** *FILE* }
26|	*FORMAT* := { **raw** | **c** }
27|	*MAP* := { **id** *MAP_ID* | **pinned** *FILE* }
28|	*PROG* := { **id** *PROG_ID* | **pinned** *FILE* | **tag** *PROG_TAG* }
29
30DESCRIPTION
31===========
32	**bpftool btf dump** *BTF_SRC*
33		  Dump BTF entries from a given *BTF_SRC*.
34
35		  When **id** is specified, BTF object with that ID will be
36		  loaded and all its BTF types emitted.
37
38		  When **map** is provided, it's expected that map has
39		  associated BTF object with BTF types describing key and
40		  value. It's possible to select whether to dump only BTF
41		  type(s) associated with key (**key**), value (**value**),
42		  both key and value (**kv**), or all BTF types present in
43		  associated BTF object (**all**). If not specified, **kv**
44		  is assumed.
45
46		  When **prog** is provided, it's expected that program has
47		  associated BTF object with BTF types.
48
49		  When specifying *FILE*, an ELF file is expected, containing
50		  .BTF section with well-defined BTF binary format data,
51		  typically produced by clang or pahole.
52
53		  **format** option can be used to override default (raw)
54		  output format. Raw (**raw**) or C-syntax (**c**) output
55		  formats are supported.
56
57	**bpftool btf help**
58		  Print short help message.
59
60OPTIONS
61=======
62	-h, --help
63		  Print short generic help message (similar to **bpftool help**).
64
65	-V, --version
66		  Print version number (similar to **bpftool version**).
67
68	-j, --json
69		  Generate JSON output. For commands that cannot produce JSON, this
70		  option has no effect.
71
72	-p, --pretty
73		  Generate human-readable JSON output. Implies **-j**.
74
75	-d, --debug
76		  Print all logs available from libbpf, including debug-level
77		  information.
78
79EXAMPLES
80========
81**# bpftool btf dump id 1226**
82::
83
84  [1] PTR '(anon)' type_id=2
85  [2] STRUCT 'dummy_tracepoint_args' size=16 vlen=2
86          'pad' type_id=3 bits_offset=0
87          'sock' type_id=4 bits_offset=64
88  [3] INT 'long long unsigned int' size=8 bits_offset=0 nr_bits=64 encoding=(none)
89  [4] PTR '(anon)' type_id=5
90  [5] FWD 'sock' fwd_kind=union
91
92This gives an example of default output for all supported BTF kinds.
93
94**$ cat prog.c**
95::
96
97  struct fwd_struct;
98
99  enum my_enum {
100          VAL1 = 3,
101          VAL2 = 7,
102  };
103
104  typedef struct my_struct my_struct_t;
105
106  struct my_struct {
107          const unsigned int const_int_field;
108          int bitfield_field: 4;
109          char arr_field[16];
110          const struct fwd_struct *restrict fwd_field;
111          enum my_enum enum_field;
112          volatile my_struct_t *typedef_ptr_field;
113  };
114
115  union my_union {
116          int a;
117          struct my_struct b;
118  };
119
120  struct my_struct struct_global_var __attribute__((section("data_sec"))) = {
121          .bitfield_field = 3,
122          .enum_field = VAL1,
123  };
124  int global_var __attribute__((section("data_sec"))) = 7;
125
126  __attribute__((noinline))
127  int my_func(union my_union *arg1, int arg2)
128  {
129          static int static_var __attribute__((section("data_sec"))) = 123;
130          static_var++;
131          return static_var;
132  }
133
134**$ bpftool btf dump file prog.o**
135::
136
137  [1] PTR '(anon)' type_id=2
138  [2] UNION 'my_union' size=48 vlen=2
139          'a' type_id=3 bits_offset=0
140          'b' type_id=4 bits_offset=0
141  [3] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
142  [4] STRUCT 'my_struct' size=48 vlen=6
143          'const_int_field' type_id=5 bits_offset=0
144          'bitfield_field' type_id=3 bits_offset=32 bitfield_size=4
145          'arr_field' type_id=8 bits_offset=40
146          'fwd_field' type_id=10 bits_offset=192
147          'enum_field' type_id=14 bits_offset=256
148          'typedef_ptr_field' type_id=15 bits_offset=320
149  [5] CONST '(anon)' type_id=6
150  [6] INT 'unsigned int' size=4 bits_offset=0 nr_bits=32 encoding=(none)
151  [7] INT 'char' size=1 bits_offset=0 nr_bits=8 encoding=SIGNED
152  [8] ARRAY '(anon)' type_id=7 index_type_id=9 nr_elems=16
153  [9] INT '__ARRAY_SIZE_TYPE__' size=4 bits_offset=0 nr_bits=32 encoding=(none)
154  [10] RESTRICT '(anon)' type_id=11
155  [11] PTR '(anon)' type_id=12
156  [12] CONST '(anon)' type_id=13
157  [13] FWD 'fwd_struct' fwd_kind=union
158  [14] ENUM 'my_enum' size=4 vlen=2
159          'VAL1' val=3
160          'VAL2' val=7
161  [15] PTR '(anon)' type_id=16
162  [16] VOLATILE '(anon)' type_id=17
163  [17] TYPEDEF 'my_struct_t' type_id=4
164  [18] FUNC_PROTO '(anon)' ret_type_id=3 vlen=2
165          'arg1' type_id=1
166          'arg2' type_id=3
167  [19] FUNC 'my_func' type_id=18
168  [20] VAR 'struct_global_var' type_id=4, linkage=global-alloc
169  [21] VAR 'global_var' type_id=3, linkage=global-alloc
170  [22] VAR 'my_func.static_var' type_id=3, linkage=static
171  [23] DATASEC 'data_sec' size=0 vlen=3
172          type_id=20 offset=0 size=48
173          type_id=21 offset=0 size=4
174          type_id=22 offset=52 size=4
175
176The following commands print BTF types associated with specified map's key,
177value, both key and value, and all BTF types, respectively. By default, both
178key and value types will be printed.
179
180**# bpftool btf dump map id 123 key**
181
182::
183
184  [39] TYPEDEF 'u32' type_id=37
185
186**# bpftool btf dump map id 123 value**
187
188::
189
190  [86] PTR '(anon)' type_id=87
191
192**# bpftool btf dump map id 123 kv**
193
194::
195
196  [39] TYPEDEF 'u32' type_id=37
197  [86] PTR '(anon)' type_id=87
198
199**# bpftool btf dump map id 123 all**
200
201::
202
203  [1] PTR '(anon)' type_id=0
204  .
205  .
206  .
207  [2866] ARRAY '(anon)' type_id=52 index_type_id=51 nr_elems=4
208
209All the standard ways to specify map or program are supported:
210
211**# bpftool btf dump map id 123**
212
213**# bpftool btf dump map pinned /sys/fs/bpf/map_name**
214
215**# bpftool btf dump prog id 456**
216
217**# bpftool btf dump prog tag b88e0a09b1d9759d**
218
219**# bpftool btf dump prog pinned /sys/fs/bpf/prog_name**
220
221SEE ALSO
222========
223	**bpf**\ (2),
224	**bpf-helpers**\ (7),
225	**bpftool**\ (8),
226	**bpftool-map**\ (8),
227	**bpftool-prog**\ (8),
228	**bpftool-cgroup**\ (8),
229	**bpftool-feature**\ (8),
230	**bpftool-net**\ (8),
231	**bpftool-perf**\ (8)
232