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