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