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 Oct 2, 2018 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 144conatiner. 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