| blob | a8c2d978aede3d016172dd286595dc169f617813 |
1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright (c) 2015, Joyent, Inc.
13 .\"
14 .Dd Oct 4, 2014
15 .Dt CTFDUMP 1
16 .Os
17 .Sh NAME
18 .Nm ctfdump
19 .Nd dump parts of ctf data from files
20 .Sh SYNOPSIS
21 .Nm ctfdump
22 .Op Fl dfhlsSt
23 .Op Fl p Ar parent
24 .Op Fl u Ar outfile
25 .Ar file
26 .Sh DESCRIPTION
27 The
28 .Nm
29 utility dumps and decodes the
30 .Sy CTF
31 data contained inside of
32 .Sy ELF
33 objects and raw
34 .Sy CTF
35 files.
36 .Lp
37 .Nm
38 can dump information about the
39 .Sy CTF header ,
40 the
41 .Sy labels
42 encoded in the
43 .Sy CTF
44 container,
45 the types of
46 .Sy data objects ,
47 the internal
48 .Sy string
49 table,
50 the types of the return function and the arguments for
51 .Sy functions ,
52 and of course, it displays information about the
53 .Sy types
54 defined in the
55 .Sy CTF
56 container.
57 .Lp
58 .Nm
59 can also be used to dump out the raw
60 .Sy CTF
61 data and send it to another file. When writing out data, it always
62 ensures that the
63 .Sy CTF
64 data is decompressed. In this form, the
65 .Sy CTF
66 data can be inspected using
67 .Nm
68 and other tools such as
69 .Xr mdb 1 .
70 .Lp
71 When no options are specified,
72 .Nm
73 displays all information. However, when the
74 .Fl u
75 option is used, then no information is displayed by default, unless
76 requested through the the appropriate option.
77 .Sh OPTIONS
78 The following options are supported:
79 .Bl -hang -width Ds
80 .It Fl d
81 .Bd -filled -compact
82 Dump the types of symbols that correspond to objects.
83 .Ed
84 .It Fl f
85 .Bd -filled -compact
86 Dump the types of the return values and arguments of the functions.
87 .Ed
88 .It Fl h
89 .Bd -filled -compact
90 Dump the
91 .Sy CTF
92 header
93 .Ed
94 .It Fl l
95 .Bd -filled -compact
96 Dump all
97 .Sy CTF
98 labels associated with the file.
99 .Ed
100 .It Fl p Ar parent
101 .Bd -filled -compact
102 Use the type information in
103 .Em parent
104 to supplement output. This is useful when a
105 .Nm CTF
106 container has been
107 .Sy uniquified
108 against
109 .Em parent .
110 This allows
111 .Nm
112 to use the names of types when used with
113 .Fl t .
114 .Ed
115 .It Fl s
116 .Bd -filled -compact
117 Dump the internal
118 .Sy CTF
119 string table
120 .Ed
121 .It Fl S
122 .Bd -filled -compact
123 Displays statistics about the
124 .Sy CTF
125 container.
126 .Ed
127 .It Fl t
128 .Bd -filled -compact
129 Dump the type information contained in the
130 .Sy CTF
131 conatiner.
132 .Ed
133 .It Fl u Ar outfile
134 .Bd -filled -compact
135 Copies the uncompressed
136 .Sy CTF
137 data to the file specified by
138 .Em outfile .
139 This can be used to make it easier to inspect the raw
140 .Sy CTF
141 data.
142 .Ed
143 .El
144 .Sh OUTPUT
145 When the
146 .Nm
147 utility is executed with its default options, it prints out a textual
148 representation of the
149 .Sy CTF
150 information. Note, the output format of
151 .Nm
152 is subject to change at any time and should not be relied upon as a
153 stable format to be used for parsing.
154 .Ss CTF Header
155 This section describes the values in the
156 .Sy CTF
157 header. Each line in the section describes the value of one of the
158 members of the header. For more information on the meaning and
159 interpretation of these members, see
160 .Xr ctf 4 .
161 .Ss Label Table
162 This section describes information about the labels present in the
163 .Sy CTF
164 information. Each entry in this section, if present, starts with a
165 number and is followed by a string. An example entry in the label
166 section might look like:
167 .Bd -literal
168 \&...
169 2270 joyent_20151001T070028Z
170 \&...
171 .Ed
172 .Pp
173 The number,
174 .Em 2270 ,
175 represents the last type that the label applies to. The string,
176 .Em joyent_20151001T070028Z ,
177 is the name of the label. In this case, if there were no other labels,
178 it would indicate that the label applied to all types up to, and
179 including, the type number 2270. For more information
180 on how labels are used with
181 .Sy CTF
182 information, see the section
183 .Em The Label Section
184 in
185 .Xr ctf 4 .
186 .Ss Data Objects
187 This section describes the type information relating to data objects
188 from the symbol table. An entry for a data object consists of four
189 columns. The first column is just a monotonic ID. The second number is
190 the type id of the object. The third column is the name of the symbol
191 and the fourth column is the corresponding index from the symbol table.
192 .Pp
193 Take for example, the following couple of entries:
194 .Bd -literal
195 \&...
196 [0] 13 hz (48)
197 [1] 78 _nd (49)
198 [2] 1656 __pfmt_label (56)
199 [3] 926 _aio_hash (68)
200 [4] 13 _lio_free (70)
201 [5] 1321 u8_number_of_bytes (73)
202 \&...
203 .Ed
204 .Pp
205 Let's take the first entry in the list above. The symbol is named
206 .Sy hz .
207 It is the first data object, as indicated by the number zero in
208 brackets. It has a type id of 13 and in this case, it has a symbol table
209 index of 48.
210 .Ss Functions
211 This section describes the type information for functions. For each
212 function present in the symbol table with type information, the
213 function's entry into the function section, the function's name, the
214 function's symbol table index, the function's return type, and the types
215 of the function's arguments are printed. If a function is a variadic
216 function, then the variadic argument is printed as the string
217 .Sy '...' .
218 .Pp
219 Take for example, the following couple of entries:
220 .Bd -literal
221 \&...
222 [687] pfprint_stack (3110) returns: 11 args: (385, 115, 29, 1704, 223, 116, 2)
223 [688] pfprint_stddev (3111) returns: 11 args: (385, 115, 29, 1704, 223, 116, 2)
224 [689] pfprint_quantize (3112) returns: 11 args: (385, 115, 29, 1704, 223, 116, 2)
225 [690] pfprint_lquantize (3113) returns: 11 args: (385, 115, 29, 1704, 223, 116, 2)
226 [691] pfprint_llquantize (3114) returns: 11 args: (385, 115, 29, 1704, 223, 116, 2)
227 \&...
228 .Ed
229 .Pp
230 The first column is the function's entry number in the function type
231 information section. It is enclosed in brackets. The next column is the
232 function's name and it is followed in parenthesis by the its index in the
233 symbol table. The following portions of this entry describe the return
234 type and then all of the arguments, in positional order.
235 .Ss Types
236 The types section gives information about each type in the
237 .Sy CTF
238 container. Each entry begins with its type identifier. The type
239 identifier may either be in square brackets or in angle brackets. If the
240 type identifier is enclosed in angle brackets, then that represents that
241 it is a root type or top-level type. If it is square brackets, then it
242 is not. For more information on root types, see
243 .Xr ctf 4 .
244 .Pp
245 Next, the type will have its name and kind. If it is an array, it will
246 be followed with a subscript that describes the number of entries in the
247 array. If it is a pointer, it will followed by the
248 .Sy *
249 symbol to indicate that it is a pointer. If the type has the
250 .Sy const ,
251 .Sy volatile ,
252 .Sy typedef ,
253 or
254 .Sy restrict
255 keyword applied to it, that will precede the name. All of these
256 reference types, including pointer, will then be followed with an
257 example of the type that they refer to.
258 .Pp
259 Types which are an integral or floating point value will be followed by
260 information about their encoding and the number of bits represented in
261 the type.
262 .Pp
263 Arrays will be followed by two different entries, the contents and
264 index. The contents member contains the type id of the array's contents
265 and the index member describes a type which can represent the array's
266 index.
267 .Pp
268 Structures and unions will be preceded with the corresponding C keyword,
269 .Sy struct
270 or
271 .Sy union .
272 After that, the size in bytes of the structure will be indicated. ON
273 each subsequent line, a single member will be listed. That line will
274 contain the member's name, it's type identifier, and the offset into the
275 structure that it can be found in, in bits.
276 .Pp
277 The following show examples of type information for all of these
278 different types:
279 .Bd -literal
280 \&...
281 [5] char [12] contents: 1, index: 2
282 [6] short encoding=SIGNED offset=0 bits=16
283 <7> struct exit_status (4 bytes)
284 e_termination type=6 off=0
285 e_exit type=6 off=16
287 <8> typedef time_t refers to 2
288 <9> struct utmp (36 bytes)
289 ut_user type=3 off=0
290 ut_id type=4 off=64
291 ut_line type=5 off=96
292 ut_pid type=6 off=192
293 ut_type type=6 off=208
294 ut_exit type=7 off=224
295 ut_time type=8 off=256
297 <10> struct utmp * refers to 9
298 [11] const struct utmp refers to 9
299 [12] const struct utmp * refers to 11
300 <13> int encoding=SIGNED offset=0 bits=32
301 <14> typedef int32_t refers to 13
302 \&...
303 .Ed
304 .Ss String Table
305 This section describes all of the strings that are present in the
306 .Sy CTF
307 container. Each line represents an entry in the string table. First the
308 byte offset into the string table is shown in brackets and then the
309 string's value is displayed. Note the following examples:
310 .Bd -literal
311 [0] \0
312 [1] joyent_20151001T070028Z
313 [25] char
314 [30] long
315 [35] short
316 .Ed
317 .Ss Statistics
318 This section contains miscellaneous statistics about the
319 .Sy CTF
320 data present. Each line contains a single statistic. A brief explanation
321 of the statistic is placed first, followed by an equals sign, and then
322 finally the value.
323 .Sh EXIT STATUS
324 .Bl -inset
325 .It Sy 0
326 .Dl Execution completed successfully.
327 .It Sy 1
328 .Dl A fatal error occured.
329 .It Sy 2
330 .Dl Invalid command line options were specified.
331 .El
332 .Sh EXAMPLES
333 .Sy Example 1
334 Displaying the Type Section of a Single File
335 .Lp
336 The following example dumps the type section of the file
337 .Sy /usr/lib/libc.so.1 .
338 .Bd -literal -offset 6n
339 $ ctfdump -t /usr/lib/libc.so.1
340 - Types ----------------------------------------------------
342 <1> int encoding=SIGNED offset=0 bits=32
343 <2> long encoding=SIGNED offset=0 bits=32
344 <3> typedef pid_t refers to 2
345 <4> unsigned int encoding=0x0 offset=0 bits=32
346 <5> typedef uid_t refers to 4
347 <6> typedef gid_t refers to 5
348 <7> typedef uintptr_t refers to 4
349 \&...
350 .Ed
351 .Lp
352 .Sy Example 2
353 Dumping the CTF data to Another File
354 .Lp
355 The following example dumps the entire CTF data from the file
356 .Sy /usr/lib/libc.so.1
357 and places it into the file
358 .Sy ctf.out .
359 This then shows how you can use the
360 .Xr mdb 1
361 to inspect its contents.
362 .Bd -literal -offset 6n
363 $ ctfdump -u ctf.out /usr/lib/libc.so.1
364 $ mdb ./ctf.out
365 > ::typedef -r /usr/lib/libctf.so.1
366 > 0::print ctf_header_t
367 {
368 cth_preamble = {
369 ctp_magic = 0xcff1
370 ctp_version = 0x2
371 ctp_flags = 0
372 }
373 cth_parlabel = 0
374 cth_parname = 0
375 cth_lbloff = 0
376 cth_objtoff = 0x8
377 cth_funcoff = 0x5e0
378 cth_typeoff = 0x7178
379 cth_stroff = 0x12964
380 cth_strlen = 0x7c9c
381 }
382 .Ed
383 .Sh INTERFACE STABILITY
384 The command syntax is
385 .Sy Committed .
386 The output format is
387 .Sy Uncommitted .
388 .Sh SEE ALSO
389 .Xr ctfdiff 1 ,
390 .Xr dump 1 ,
391 .Xr elfdump 1 ,
392 .Xr mdb 1 ,
393 .Xr ctf 4