Mercurial > illumos > git > illumos-omnios
annotate usr/src/man/man1/ctfdump.1 @ 23918:f3c8f3a2a25c
13404 man page spelling errors
Reviewed by: Ryan Zezeski <ryan@oxide.computer>
Reviewed by: Robert Mustacchi <rm@fingolfin.org>
Approved by: Richard Lowe <richlowe@richlowe.net>
| author | Peter Tribble <peter.tribble@gmail.com> |
|---|---|
| date | Thu, 31 Dec 2020 10:47:42 +0000 |
| parents | 9a8bc2a52753 |
| children |
| rev | line source |
|---|---|
| 20646 | 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 .\" | |
|
23918
f3c8f3a2a25c
13404 man page spelling errors
Peter Tribble <peter.tribble@gmail.com>
parents:
20646
diff
changeset
|
14 .Dd December 28, 2020 |
| 20646 | 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 | |
| 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. | |
| 62 When writing out data, it always ensures that the | |
| 63 .Sy CTF | |
| 64 data is decompressed. | |
| 65 In this form, the | |
| 66 .Sy CTF | |
| 67 data can be inspected using | |
| 68 .Nm | |
| 69 and other tools such as | |
| 70 .Xr mdb 1 . | |
| 71 .Lp | |
| 72 .Nm | |
| 73 in | |
| 74 .Fl c | |
| 75 mode will generate C-style output, which can be used for comparison. | |
| 76 Note that this output is not directly compilable. | |
| 77 .Lp | |
| 78 When no options are specified, | |
| 79 .Nm | |
| 80 displays all information, except the C-style output. | |
| 81 However, when the | |
| 82 .Fl u | |
| 83 option is used, then no information is displayed by default, unless | |
| 84 requested through the appropriate option. | |
| 85 .Sh OPTIONS | |
| 86 The following options are supported: | |
| 87 .Bl -hang -width Ds | |
| 88 .It Fl c | |
| 89 .Bd -filled -compact | |
| 90 Generate C-style output. | |
| 91 .Ed | |
| 92 .It Fl d | |
| 93 .Bd -filled -compact | |
| 94 Dump the types of symbols that correspond to objects. | |
| 95 .Ed | |
| 96 .It Fl f | |
| 97 .Bd -filled -compact | |
| 98 Dump the types of the return values and arguments of the functions. | |
| 99 .Ed | |
| 100 .It Fl h | |
| 101 .Bd -filled -compact | |
| 102 Dump the | |
| 103 .Sy CTF | |
| 104 header | |
| 105 .Ed | |
| 106 .It Fl l | |
| 107 .Bd -filled -compact | |
| 108 Dump all | |
| 109 .Sy CTF | |
| 110 labels associated with the file. | |
| 111 .Ed | |
| 112 .It Fl p Ar parent | |
| 113 .Bd -filled -compact | |
| 114 Use the type information in | |
| 115 .Em parent | |
| 116 to supplement output. | |
| 117 This is useful when a | |
| 118 .Nm CTF | |
| 119 container has been | |
| 120 .Sy uniquified | |
| 121 against | |
| 122 .Em parent . | |
| 123 This allows | |
| 124 .Nm | |
| 125 to use the names of types when used with | |
| 126 .Fl t . | |
| 127 .Ed | |
| 128 .It Fl s | |
| 129 .Bd -filled -compact | |
| 130 Dump the internal | |
| 131 .Sy CTF | |
| 132 string table | |
| 133 .Ed | |
| 134 .It Fl S | |
| 135 .Bd -filled -compact | |
| 136 Displays statistics about the | |
| 137 .Sy CTF | |
| 138 container. | |
| 139 .Ed | |
| 140 .It Fl t | |
| 141 .Bd -filled -compact | |
| 142 Dump the type information contained in the | |
| 143 .Sy CTF | |
|
23918
f3c8f3a2a25c
13404 man page spelling errors
Peter Tribble <peter.tribble@gmail.com>
parents:
20646
diff
changeset
|
144 container. |
| 20646 | 145 .Ed |
| 146 .It Fl u Ar outfile | |
| 147 .Bd -filled -compact | |
| 148 Copies the uncompressed | |
| 149 .Sy CTF | |
| 150 data to the file specified by | |
| 151 .Em outfile . | |
| 152 This can be used to make it easier to inspect the raw | |
| 153 .Sy CTF | |
| 154 data. | |
| 155 .Ed | |
| 156 .El | |
| 157 .Sh OUTPUT | |
| 158 When the | |
| 159 .Nm | |
| 160 utility is executed with its default options, it prints out a textual | |
| 161 representation of the | |
| 162 .Sy CTF | |
| 163 information. | |
| 164 Note, the output format of | |
| 165 .Nm | |
| 166 is subject to change at any time and should not be relied upon as a | |
| 167 stable format to be used for parsing. | |
| 168 .Ss CTF Header | |
| 169 This section describes the values in the | |
| 170 .Sy CTF | |
| 171 header. | |
| 172 Each line in the section describes the value of one of the | |
| 173 members of the header. | |
| 174 For more information on the meaning and interpretation of these members, | |
| 175 see | |
| 176 .Xr ctf 4 . | |
| 177 .Ss Label Table | |
| 178 This section describes information about the labels present in the | |
| 179 .Sy CTF | |
| 180 information. | |
| 181 Each entry in this section, if present, starts with a | |
| 182 number and is followed by a string. | |
| 183 An example entry in the label section might look like: | |
| 184 .Bd -literal | |
| 185 \&... | |
| 186 2270 joyent_20151001T070028Z | |
| 187 \&... | |
| 188 .Ed | |
| 189 .Pp | |
| 190 The number, | |
| 191 .Em 2270 , | |
| 192 represents the last type that the label applies to. | |
| 193 The string, | |
| 194 .Em joyent_20151001T070028Z , | |
| 195 is the name of the label. | |
| 196 In this case, if there were no other labels, | |
| 197 it would indicate that the label applied to all types up to, and | |
| 198 including, the type number 2270. | |
| 199 For more information on how labels are used with | |
| 200 .Sy CTF | |
| 201 information, see the section | |
| 202 .Em The Label Section | |
| 203 in | |
| 204 .Xr ctf 4 . | |
| 205 .Ss Data Objects | |
| 206 This section describes the type information relating to data objects | |
| 207 from the symbol table. | |
| 208 An entry for a data object consists of four columns. | |
| 209 The first column is just a monotonic ID. | |
| 210 The second number is the type id of the object. | |
| 211 The third column is the name of the symbol and the fourth column is the | |
| 212 corresponding index from the symbol table. | |
| 213 .Pp | |
| 214 Take 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 | |
| 226 Let's take the first entry in the list above. | |
| 227 The symbol is named | |
| 228 .Sy hz . | |
| 229 It is the first data object, as indicated by the number zero in | |
| 230 brackets. | |
| 231 It has a type id of 13 and in this case, it has a symbol table index of | |
| 232 48. | |
| 233 .Ss Functions | |
| 234 This section describes the type information for functions. | |
| 235 For each function present in the symbol table with type information, the | |
| 236 function's entry into the function section, the function's name, the | |
| 237 function's symbol table index, the function's return type, and the types | |
| 238 of the function's arguments are printed. | |
| 239 If a function is a variadic function, then the variadic argument is | |
| 240 printed as the string | |
| 241 .Sy '...' . | |
| 242 .Pp | |
| 243 Take 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 | |
| 254 The first column is the function's entry number in the function type | |
| 255 information section. | |
| 256 It is enclosed in brackets. | |
| 257 The next column is the function's name and it is followed in parenthesis | |
| 258 by the its index in the | |
| 259 symbol table. | |
| 260 The following portions of this entry describe the return | |
| 261 type and then all of the arguments, in positional order. | |
| 262 .Ss Types | |
| 263 The types section gives information about each type in the | |
| 264 .Sy CTF | |
| 265 container. | |
| 266 Each entry begins with its type identifier. | |
| 267 The type identifier may either be in square brackets or in angle | |
| 268 brackets. | |
| 269 If the type identifier is enclosed in angle brackets, then that | |
| 270 represents that it is a root type or top-level type. | |
| 271 If it is square brackets, then it is not. | |
| 272 For more information on root types, see | |
| 273 .Xr ctf 4 . | |
| 274 .Pp | |
| 275 Next, the type will have its name and kind. | |
| 276 If it is an array, it will be followed with a subscript that describes | |
| 277 the number of entries in the array. | |
| 278 If it is a pointer, it will followed by the | |
| 279 .Sy * | |
| 280 symbol to indicate that it is a pointer. | |
| 281 If the type has the | |
| 282 .Sy const , | |
| 283 .Sy volatile , | |
| 284 .Sy typedef , | |
| 285 or | |
| 286 .Sy restrict | |
| 287 keyword applied to it, that will precede the name. | |
| 288 All of these reference types, including pointer, will then be followed | |
| 289 with an example of the type that they refer to. | |
| 290 .Pp | |
| 291 Types which are an integral or floating point value will be followed by | |
| 292 information about their encoding and the number of bits represented in | |
| 293 the type. | |
| 294 .Pp | |
| 295 Arrays will be followed by two different entries, the contents and | |
| 296 index. | |
| 297 The contents member contains the type id of the array's contents | |
| 298 and the index member describes a type which can represent the array's | |
| 299 index. | |
| 300 .Pp | |
| 301 Structures and unions will be preceded with the corresponding C keyword, | |
| 302 .Sy struct | |
| 303 or | |
| 304 .Sy union . | |
| 305 After that, the size in bytes of the structure will be indicated. | |
| 306 ON each subsequent line, a single member will be listed. | |
| 307 That line will contain the member's name, it's type identifier, and the | |
| 308 offset into the structure that it can be found in, in bits. | |
| 309 .Pp | |
| 310 The following show examples of type information for all of these | |
| 311 different 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 | |
| 338 This section describes all of the strings that are present in the | |
| 339 .Sy CTF | |
| 340 container. | |
| 341 Each line represents an entry in the string table. | |
| 342 First the byte offset into the string table is shown in brackets and | |
| 343 then the | |
| 344 string's value is displayed. | |
| 345 Note 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 | |
| 354 This section contains miscellaneous statistics about the | |
| 355 .Sy CTF | |
| 356 data present. | |
| 357 Each line contains a single statistic. | |
| 358 A brief explanation of the statistic is placed first, followed by an | |
| 359 equals 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 | |
| 371 Displaying the Type Section of a Single File | |
| 372 .Lp | |
| 373 The 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 | |
| 390 Dumping the CTF data to Another File | |
| 391 .Lp | |
| 392 The following example dumps the entire CTF data from the file | |
| 393 .Sy /usr/lib/libc.so.1 | |
| 394 and places it into the file | |
| 395 .Sy ctf.out . | |
| 396 This then shows how you can use the | |
| 397 .Xr mdb 1 | |
| 398 to 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 | |
| 422 Dumping C-style output | |
| 423 .Bd -literal -offset 6n | |
| 424 $ ctfdump -c ./genunix | more | |
| 425 /* Types */ | |
| 426 | |
| 427 typedef Elf64_Addr Addr; | |
| 428 | |
| 429 typedef unsigned char Bool; | |
| 430 | |
| 431 typedef struct CK_AES_CCM_PARAMS CK_AES_CCM_PARAMS; | |
| 432 | |
| 433 typedef struct CK_AES_GCM_PARAMS CK_AES_GCM_PARAMS; | |
| 434 \&... | |
| 435 .Ed | |
| 436 .Sh INTERFACE STABILITY | |
| 437 The command syntax is | |
| 438 .Sy Committed . | |
| 439 The 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 |