1 <html devsite> 2 <head> 3 <title>Dalvik Executable format</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 <p>This document describes the layout and contents of <code>.dex</code> 26 files, which are used to hold a set of class definitions and their associated 27 adjunct data.</p> 28 29 <h2 id="types">Guide to types</h2> 30 31 <table class="guide"> 32 <thead> 33 <tr> 34 <th>Name</th> 35 <th>Description</th> 36 </tr> 37 </thead> 38 <tbody> 39 <tr> 40 <td>byte</td> 41 <td>8-bit signed int</td> 42 </tr> 43 <tr> 44 <td>ubyte</td> 45 <td>8-bit unsigned int</td> 46 </tr> 47 <tr> 48 <td>short</td> 49 <td>16-bit signed int, little-endian</td> 50 </tr> 51 <tr> 52 <td>ushort</td> 53 <td>16-bit unsigned int, little-endian</td> 54 </tr> 55 <tr> 56 <td>int</td> 57 <td>32-bit signed int, little-endian</td> 58 </tr> 59 <tr> 60 <td>uint</td> 61 <td>32-bit unsigned int, little-endian</td> 62 </tr> 63 <tr> 64 <td>long</td> 65 <td>64-bit signed int, little-endian</td> 66 </tr> 67 <tr> 68 <td>ulong</td> 69 <td>64-bit unsigned int, little-endian</td> 70 </tr> 71 <tr> 72 <td>sleb128</td> 73 <td>signed LEB128, variable-length (see below)</td> 74 </tr> 75 <tr> 76 <td>uleb128</td> 77 <td>unsigned LEB128, variable-length (see below)</td> 78 </tr> 79 <tr> 80 <td>uleb128p1</td> 81 <td>unsigned LEB128 plus <code>1</code>, variable-length (see below)</td> 82 </tr> 83 </tbody> 84 </table> 85 86 <h3 id="leb128">LEB128</h3> 87 88 <p>LEB128 ("<b>L</b>ittle-<b>E</b>ndian <b>B</b>ase <b>128</b>") is a 89 variable-length encoding for 90 arbitrary signed or unsigned integer quantities. The format was 91 borrowed from the <a href="http://dwarfstd.org/Dwarf3Std.php">DWARF3</a> 92 specification. In a <code>.dex</code> file, LEB128 is only ever used to 93 encode 32-bit quantities.</p> 94 95 <p>Each LEB128 encoded value consists of one to five 96 bytes, which together represent a single 32-bit value. Each 97 byte has its most significant bit set except for the final byte in the 98 sequence, which has its most significant bit clear. The remaining 99 seven bits of each byte are payload, with the least significant seven 100 bits of the quantity in the first byte, the next seven in the second 101 byte and so on. In the case of a signed LEB128 (<code>sleb128</code>), 102 the most significant payload bit of the final byte in the sequence is 103 sign-extended to produce the final value. In the unsigned case 104 (<code>uleb128</code>), any bits not explicitly represented are 105 interpreted as <code>0</code>. 106 107 <table class="leb128Bits"> 108 <thead> 109 <tr><th colspan="16">Bitwise diagram of a two-byte LEB128 value</th></tr> 110 <tr> 111 <th colspan="8">First byte</td> 112 <th colspan="8">Second byte</td> 113 </tr> 114 </thead> 115 <tbody> 116 <tr> 117 <td class="start1"><code>1</code></td> 118 <td>bit<sub>6</sub></td> 119 <td>bit<sub>5</sub></td> 120 <td>bit<sub>4</sub></td> 121 <td>bit<sub>3</sub></td> 122 <td>bit<sub>2</sub></td> 123 <td>bit<sub>1</sub></td> 124 <td>bit<sub>0</sub></td> 125 <td class="start2"><code>0</code></td> 126 <td>bit<sub>13</sub></td> 127 <td>bit<sub>12</sub></td> 128 <td>bit<sub>11</sub></td> 129 <td>bit<sub>10</sub></td> 130 <td>bit<sub>9</sub></td> 131 <td>bit<sub>8</sub></td> 132 <td class="end2">bit<sub>7</sub></td> 133 </tr> 134 </tbody> 135 </table> 136 137 <p>The variant <code>uleb128p1</code> is used to represent a signed 138 value, where the representation is of the value <i>plus one</i> encoded 139 as a <code>uleb128</code>. This makes the encoding of <code>-1</code> 140 (alternatively thought of as the unsigned value <code>0xffffffff</code>) 141 — but no other negative number — a single byte, and is 142 useful in exactly those cases where the represented number must either 143 be non-negative or <code>-1</code> (or <code>0xffffffff</code>), 144 and where no other negative values are allowed (or where large unsigned 145 values are unlikely to be needed).</p> 146 147 <p>Here are some examples of the formats:</p> 148 149 <table class="leb128"> 150 <thead> 151 <tr> 152 <th>Encoded Sequence</th> 153 <th>As <code>sleb128</code></th> 154 <th>As <code>uleb128</code></th> 155 <th>As <code>uleb128p1</code></th> 156 </tr> 157 </thead> 158 <tbody> 159 <tr><td>00</td><td>0</td><td>0</td><td>-1</td></tr> 160 <tr><td>01</td><td>1</td><td>1</td><td>0</td></tr> 161 <tr><td>7f</td><td>-1</td><td>127</td><td>126</td></tr> 162 <tr><td>80 7f</td><td>-128</td><td>16256</td><td>16255</td></tr> 163 </tbody> 164 </table> 165 166 <h2 id="file-layout">File layout</h2> 167 168 <table class="format"> 169 <thead> 170 <tr> 171 <th>Name</th> 172 <th>Format</th> 173 <th>Description</th> 174 </tr> 175 </thead> 176 <tbody> 177 <tr> 178 <td>header</td> 179 <td>header_item</td> 180 <td>the header</td> 181 </tr> 182 <tr> 183 <td>string_ids</td> 184 <td>string_id_item[]</td> 185 <td>string identifiers list. These are identifiers for all the strings 186 used by this file, either for internal naming (e.g., type descriptors) 187 or as constant objects referred to by code. This list must be sorted 188 by string contents, using UTF-16 code point values (not in a 189 locale-sensitive manner), and it must not contain any duplicate entries. 190 </td> 191 </tr> 192 <tr> 193 <td>type_ids</td> 194 <td>type_id_item[]</td> 195 <td>type identifiers list. These are identifiers for all types (classes, 196 arrays, or primitive types) referred to by this file, whether defined 197 in the file or not. This list must be sorted by <code>string_id</code> 198 index, and it must not contain any duplicate entries. 199 </td> 200 </tr> 201 <tr> 202 <td>proto_ids</td> 203 <td>proto_id_item[]</td> 204 <td>method prototype identifiers list. These are identifiers for all 205 prototypes referred to by this file. This list must be sorted in 206 return-type (by <code>type_id</code> index) major order, and then 207 by argument list (lexicographic ordering, individual arguments 208 ordered by <code>type_id</code> index). The list must not 209 contain any duplicate entries. 210 </td> 211 </tr> 212 <tr> 213 <td>field_ids</td> 214 <td>field_id_item[]</td> 215 <td>field identifiers list. These are identifiers for all fields 216 referred to by this file, whether defined in the file or not. This 217 list must be sorted, where the defining type (by <code>type_id</code> 218 index) is the major order, field name (by <code>string_id</code> index) 219 is the intermediate order, and type (by <code>type_id</code> index) 220 is the minor order. The list must not contain any duplicate entries. 221 </td> 222 </tr> 223 <tr> 224 <td>method_ids</td> 225 <td>method_id_item[]</td> 226 <td>method identifiers list. These are identifiers for all methods 227 referred to by this file, whether defined in the file or not. This 228 list must be sorted, where the defining type (by <code>type_id</code> 229 index) is the major order, method name (by <code>string_id</code> 230 index) is the intermediate order, and method prototype (by 231 <code>proto_id</code> index) is the minor order. The list must not 232 contain any duplicate entries. 233 </td> 234 </tr> 235 <tr> 236 <td>class_defs</td> 237 <td>class_def_item[]</td> 238 <td>class definitions list. The classes must be ordered such that a given 239 class's superclass and implemented interfaces appear in the 240 list earlier than the referring class. Furthermore, it is invalid for 241 a definition for the same-named class to appear more than once in 242 the list. 243 </td> 244 </tr> 245 <tr> 246 <td>call_site_ids</td> 247 <td>call_site_id_item[]</td> 248 <td>call site identifiers list. These are identifiers for all call sites 249 referred to by this file, whether defined in the file or not. This list 250 must be sorted in ascending order of <code>call_site_off</code>. 251 </tr> 252 <tr> 253 <td>method_handles</td> 254 <td>method_handle_item[]</td> 255 <td>method handles list. A list of all method handles referred to by this file, 256 whether defined in the file or not. This list is not sorted and may contain 257 duplicates which will logically correspond to different method handle instances. 258 </tr> 259 <tr> 260 <td>data</td> 261 <td>ubyte[]</td> 262 <td>data area, containing all the support data for the tables listed above. 263 Different items have different alignment requirements, and 264 padding bytes are inserted before each item if necessary to achieve 265 proper alignment. 266 </td> 267 </tr> 268 <tr> 269 <td>link_data</td> 270 <td>ubyte[]</td> 271 <td>data used in statically linked files. The format of the data in 272 this section is left unspecified by this document. 273 This section is empty in unlinked files, and runtime implementations 274 may use it as they see fit. 275 </td> 276 </tr> 277 </tbody> 278 </table> 279 280 <h2 id="definitions">Bitfield, string and constant definitions</h2> 281 282 <h3 id="dex-file-magic">DEX_FILE_MAGIC</h3> 283 <h4>embedded in header_item</h4> 284 285 <p>The constant array/string <code>DEX_FILE_MAGIC</code> is the list of 286 bytes that must appear at the beginning of a <code>.dex</code> file 287 in order for it to be recognized as such. The value intentionally 288 contains a newline (<code>"\n"</code> or <code>0x0a</code>) and a 289 null byte (<code>"\0"</code> or <code>0x00</code>) in order to help 290 in the detection of certain forms of corruption. The value also 291 encodes a format version number as three decimal digits, which is 292 expected to increase monotonically over time as the format evolves.</p> 293 294 <pre class="devsite-click-to-copy"> 295 ubyte[8] DEX_FILE_MAGIC = { 0x64 0x65 0x78 0x0a 0x30 0x33 0x38 0x00 } 296 = "dex\n038\0" 297 </pre> 298 299 <p class="note"><strong>Note:</strong> At least a couple earlier versions of the format have 300 been used in widely-available public software releases. For example, 301 version <code>009</code> was used for the M3 releases of the 302 Android platform (November–December 2007), 303 and version <code>013</code> was used for the M5 releases of the Android 304 platform (February–March 2008). In several respects, these earlier 305 versions of the format differ significantly from the version described in this 306 document.</p> 307 308 <p class="note"><strong>Note:</strong> Support for version 309 <code>038</code> of the format was added in the Android 8.0 310 release. Version <code>038</code> added new bytecodes 311 (<code>invoke-polymorphic</code> and <code>invoke-custom</code>) and 312 data for method handles. 313 314 <p class="note"><strong>Note:</strong> Support for version <code>037</code> of 315 the format was added in the Android 7.0 release. Prior to version <code>037</code> most 316 versions of Android have used version <code>035</code> of the format. The only 317 difference between versions <code>035</code> and <code>037</code> is the 318 addition of default methods and the adjustment of the <code>invoke</code>. 319 320 <h3 id="endian-constant">ENDIAN_CONSTANT and REVERSE_ENDIAN_CONSTANT</h3> 321 <h4>embedded in header_item</h4> 322 323 <p>The constant <code>ENDIAN_CONSTANT</code> is used to indicate the 324 endianness of the file in which it is found. Although the standard 325 <code>.dex</code> format is little-endian, implementations may choose 326 to perform byte-swapping. Should an implementation come across a 327 header whose <code>endian_tag</code> is <code>REVERSE_ENDIAN_CONSTANT</code> 328 instead of <code>ENDIAN_CONSTANT</code>, it would know that the file 329 has been byte-swapped from the expected form.</p> 330 331 <pre class="devsite-click-to-copy"> 332 uint ENDIAN_CONSTANT = 0x12345678; 333 uint REVERSE_ENDIAN_CONSTANT = 0x78563412; 334 </pre> 335 336 <h3 id="no-index">NO_INDEX</h3> 337 <h4>embedded in class_def_item and debug_info_item</h4> 338 339 <p>The constant <code>NO_INDEX</code> is used to indicate that 340 an index value is absent.</p> 341 342 <p class="note"><strong>Note:</strong> This value isn't defined to be 343 <code>0</code>, because that is in fact typically a valid index.</p> 344 345 <p>The chosen value for <code>NO_INDEX</code> is 346 representable as a single byte in the <code>uleb128p1</code> encoding.</p> 347 348 <pre class="devsite-click-to-copy"> 349 uint NO_INDEX = 0xffffffff; // == -1 if treated as a signed int 350 </pre> 351 352 <h3 id="access-flags">access_flags definitions</h3> 353 <h4>embedded in class_def_item, encoded_field, encoded_method, and 354 InnerClass</h4> 355 356 <p>Bitfields of these flags are used to indicate the accessibility and 357 overall properties of classes and class members.</p> 358 359 <table class="accessFlags"> 360 <thead> 361 <tr> 362 <th>Name</th> 363 <th>Value</th> 364 <th>For Classes (and <code>InnerClass</code> annotations)</th> 365 <th>For Fields</th> 366 <th>For Methods</th> 367 </tr> 368 </thead> 369 <tbody> 370 <tr> 371 <td>ACC_PUBLIC</td> 372 <td>0x1</td> 373 <td><code>public</code>: visible everywhere</td> 374 <td><code>public</code>: visible everywhere</td> 375 <td><code>public</code>: visible everywhere</td> 376 </tr> 377 <tr> 378 <td>ACC_PRIVATE</td> 379 <td>0x2</td> 380 <td><super>*</super> 381 <code>private</code>: only visible to defining class 382 </td> 383 <td><code>private</code>: only visible to defining class</td> 384 <td><code>private</code>: only visible to defining class</td> 385 </tr> 386 <tr> 387 <td>ACC_PROTECTED</td> 388 <td>0x4</td> 389 <td><super>*</super> 390 <code>protected</code>: visible to package and subclasses 391 </td> 392 <td><code>protected</code>: visible to package and subclasses</td> 393 <td><code>protected</code>: visible to package and subclasses</td> 394 </tr> 395 <tr> 396 <td>ACC_STATIC</td> 397 <td>0x8</td> 398 <td><super>*</super> 399 <code>static</code>: is not constructed with an outer 400 <code>this</code> reference</td> 401 <td><code>static</code>: global to defining class</td> 402 <td><code>static</code>: does not take a <code>this</code> argument</td> 403 </tr> 404 <tr> 405 <td>ACC_FINAL</td> 406 <td>0x10</td> 407 <td><code>final</code>: not subclassable</td> 408 <td><code>final</code>: immutable after construction</td> 409 <td><code>final</code>: not overridable</td> 410 </tr> 411 <tr> 412 <td>ACC_SYNCHRONIZED</td> 413 <td>0x20</td> 414 <td> </td> 415 <td> </td> 416 <td><code>synchronized</code>: associated lock automatically acquired 417 around call to this method. <p class="note"><strong>Note:</strong> This is only valid to set when 418 <code>ACC_NATIVE</code> is also set. </p></td> 419 </tr> 420 <tr> 421 <td>ACC_VOLATILE</td> 422 <td>0x40</td> 423 <td> </td> 424 <td><code>volatile</code>: special access rules to help with thread 425 safety</td> 426 <td> </td> 427 </tr> 428 <tr> 429 <td>ACC_BRIDGE</td> 430 <td>0x40</td> 431 <td> </td> 432 <td> </td> 433 <td>bridge method, added automatically by compiler as a type-safe 434 bridge</td> 435 </tr> 436 <tr> 437 <td>ACC_TRANSIENT</td> 438 <td>0x80</td> 439 <td> </td> 440 <td><code>transient</code>: not to be saved by default serialization</td> 441 <td> </td> 442 </tr> 443 <tr> 444 <td>ACC_VARARGS</td> 445 <td>0x80</td> 446 <td> </td> 447 <td> </td> 448 <td>last argument should be treated as a "rest" argument by compiler</td> 449 </tr> 450 <tr> 451 <td>ACC_NATIVE</td> 452 <td>0x100</td> 453 <td> </td> 454 <td> </td> 455 <td><code>native</code>: implemented in native code</td> 456 </tr> 457 <tr> 458 <td>ACC_INTERFACE</td> 459 <td>0x200</td> 460 <td><code>interface</code>: multiply-implementable abstract class</td> 461 <td> </td> 462 <td> </td> 463 </tr> 464 <tr> 465 <td>ACC_ABSTRACT</td> 466 <td>0x400</td> 467 <td><code>abstract</code>: not directly instantiable</td> 468 <td> </td> 469 <td><code>abstract</code>: unimplemented by this class</td> 470 </tr> 471 <tr> 472 <td>ACC_STRICT</td> 473 <td>0x800</td> 474 <td> </td> 475 <td> </td> 476 <td><code>strictfp</code>: strict rules for floating-point arithmetic</td> 477 </tr> 478 <tr> 479 <td>ACC_SYNTHETIC</td> 480 <td>0x1000</td> 481 <td>not directly defined in source code</td> 482 <td>not directly defined in source code</td> 483 <td>not directly defined in source code</td> 484 </tr> 485 <tr> 486 <td>ACC_ANNOTATION</td> 487 <td>0x2000</td> 488 <td>declared as an annotation class</td> 489 <td> </td> 490 <td> </td> 491 </tr> 492 <tr> 493 <td>ACC_ENUM</td> 494 <td>0x4000</td> 495 <td>declared as an enumerated type</td> 496 <td>declared as an enumerated value</td> 497 <td> </td> 498 </tr> 499 <tr> 500 <td><i>(unused)</i></td> 501 <td>0x8000</td> 502 <td> </td> 503 <td> </td> 504 <td> </td> 505 </tr> 506 <tr> 507 <td>ACC_CONSTRUCTOR</td> 508 <td>0x10000</td> 509 <td> </td> 510 <td> </td> 511 <td>constructor method (class or instance initializer)</td> 512 </tr> 513 <tr> 514 <td>ACC_DECLARED_<br/>SYNCHRONIZED</td> 515 <td>0x20000</td> 516 <td> </td> 517 <td> </td> 518 <td>declared <code>synchronized</code>. <p class="note"><strong>Note:</strong> This has no effect on 519 execution (other than in reflection of this flag, per se).</p> 520 </td> 521 </tr> 522 </tbody> 523 </table> 524 525 <p><super>*</super> Only allowed on for <code>InnerClass</code> annotations, 526 and must not ever be on in a <code>class_def_item</code>.</p> 527 528 <h3 id="mutf-8">MUTF-8 (Modified UTF-8) Encoding</h3> 529 530 <p>As a concession to easier legacy support, the <code>.dex</code> format 531 encodes its string data in a de facto standard modified UTF-8 form, hereafter 532 referred to as MUTF-8. This form is identical to standard UTF-8, except:</p> 533 534 <ul> 535 <li>Only the one-, two-, and three-byte encodings are used.</li> 536 <li>Code points in the range <code>U+10000</code> … 537 <code>U+10ffff</code> are encoded as a surrogate pair, each of 538 which is represented as a three-byte encoded value.</li> 539 <li>The code point <code>U+0000</code> is encoded in two-byte form.</li> 540 <li>A plain null byte (value <code>0</code>) indicates the end of 541 a string, as is the standard C language interpretation.</li> 542 </ul> 543 544 <p>The first two items above can be summarized as: MUTF-8 545 is an encoding format for UTF-16, instead of being a more direct 546 encoding format for Unicode characters.</p> 547 548 <p>The final two items above make it simultaneously possible to include 549 the code point <code>U+0000</code> in a string <i>and</i> still manipulate 550 it as a C-style null-terminated string.</p> 551 552 <p>However, the special encoding of <code>U+0000</code> means that, unlike 553 normal UTF-8, the result of calling the standard C function 554 <code>strcmp()</code> on a pair of MUTF-8 strings does not always 555 indicate the properly signed result of comparison of <i>unequal</i> strings. 556 When ordering (not just equality) is a concern, the most straightforward 557 way to compare MUTF-8 strings is to decode them character by character, 558 and compare the decoded values. (However, more clever implementations are 559 also possible.)</p> 560 561 <p>Please refer to <a href="http://unicode.org">The Unicode 562 Standard</a> for further information about character encoding. 563 MUTF-8 is actually closer to the (relatively less well-known) encoding 564 <a href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8 565 per se.</p> 566 567 <h3 id="encoding">encoded_value encoding</h3> 568 <h4>embedded in annotation_element and encoded_array_item </h4> 569 570 <p>An <code>encoded_value</code> is an encoded piece of (nearly) 571 arbitrary hierarchically structured data. The encoding is meant to 572 be both compact and straightforward to parse.</p> 573 574 <table class="format"> 575 <thead> 576 <tr> 577 <th>Name</th> 578 <th>Format</th> 579 <th>Description</th> 580 </tr> 581 </thead> 582 <tbody> 583 <tr> 584 <td>(value_arg << 5) | value_type</td> 585 <td>ubyte</td> 586 <td>byte indicating the type of the immediately subsequent 587 <code>value</code> along 588 with an optional clarifying argument in the high-order three bits. 589 See below for the various <code>value</code> definitions. 590 In most cases, <code>value_arg</code> encodes the length of 591 the immediately-subsequent <code>value</code> in bytes, as 592 <code>(size - 1)</code>, e.g., <code>0</code> means that 593 the value requires one byte, and <code>7</code> means it requires 594 eight bytes; however, there are exceptions as noted below. 595 </td> 596 </tr> 597 <tr> 598 <td>value</td> 599 <td>ubyte[]</td> 600 <td>bytes representing the value, variable in length and interpreted 601 differently for different <code>value_type</code> bytes, though 602 always little-endian. See the various value definitions below for 603 details. 604 </td> 605 </tr> 606 </tbody> 607 </table> 608 609 <h3 id="value-formats">Value formats</h3> 610 611 <table class="encodedValue"> 612 <thead> 613 <tr> 614 <th>Type Name</th> 615 <th><code>value_type</code></th> 616 <th><code>value_arg</code> Format</th> 617 <th><code>value</code> Format</th> 618 <th>Description</th> 619 </tr> 620 </thead> 621 <tbody> 622 <tr> 623 <td>VALUE_BYTE</td> 624 <td>0x00</td> 625 <td><i>(none; must be <code>0</code>)</i></td> 626 <td>ubyte[1]</td> 627 <td>signed one-byte integer value</td> 628 </tr> 629 <tr> 630 <td>VALUE_SHORT</td> 631 <td>0x02</td> 632 <td>size - 1 (0…1)</td> 633 <td>ubyte[size]</td> 634 <td>signed two-byte integer value, sign-extended</td> 635 </tr> 636 <tr> 637 <td>VALUE_CHAR</td> 638 <td>0x03</td> 639 <td>size - 1 (0…1)</td> 640 <td>ubyte[size]</td> 641 <td>unsigned two-byte integer value, zero-extended</td> 642 </tr> 643 <tr> 644 <td>VALUE_INT</td> 645 <td>0x04</td> 646 <td>size - 1 (0…3)</td> 647 <td>ubyte[size]</td> 648 <td>signed four-byte integer value, sign-extended</td> 649 </tr> 650 <tr> 651 <td>VALUE_LONG</td> 652 <td>0x06</td> 653 <td>size - 1 (0…7)</td> 654 <td>ubyte[size]</td> 655 <td>signed eight-byte integer value, sign-extended</td> 656 </tr> 657 <tr> 658 <td>VALUE_FLOAT</td> 659 <td>0x10</td> 660 <td>size - 1 (0…3)</td> 661 <td>ubyte[size]</td> 662 <td>four-byte bit pattern, zero-extended <i>to the right</i>, and 663 interpreted as an IEEE754 32-bit floating point value 664 </td> 665 </tr> 666 <tr> 667 <td>VALUE_DOUBLE</td> 668 <td>0x11</td> 669 <td>size - 1 (0…7)</td> 670 <td>ubyte[size]</td> 671 <td>eight-byte bit pattern, zero-extended <i>to the right</i>, and 672 interpreted as an IEEE754 64-bit floating point value 673 </td> 674 </tr> 675 <tr> 676 <td>VALUE_METHOD_TYPE</td> 677 <td>0x15</td> 678 <td>size - 1 (0…3)</td> 679 <td>ubyte[size]</td> 680 <td>unsigned (zero-extended) four-byte integer value, 681 interpreted as an index into 682 the <code>proto_ids</code> section and representing a method type value 683 </td> 684 </tr> 685 <tr> 686 <td>VALUE_METHOD_HANDLE</td> 687 <td>0x16</td> 688 <td>size - 1 (0…3)</td> 689 <td>ubyte[size]</td> 690 <td>unsigned (zero-extended) four-byte integer value, 691 interpreted as an index into 692 the <code>method_handles</code> section and representing a method handle value 693 </td> 694 </tr> 695 <tr> 696 <td>VALUE_STRING</td> 697 <td>0x17</td> 698 <td>size - 1 (0…3)</td> 699 <td>ubyte[size]</td> 700 <td>unsigned (zero-extended) four-byte integer value, 701 interpreted as an index into 702 the <code>string_ids</code> section and representing a string value 703 </td> 704 </tr> 705 <tr> 706 <td>VALUE_TYPE</td> 707 <td>0x18</td> 708 <td>size - 1 (0…3)</td> 709 <td>ubyte[size]</td> 710 <td>unsigned (zero-extended) four-byte integer value, 711 interpreted as an index into 712 the <code>type_ids</code> section and representing a reflective 713 type/class value 714 </td> 715 </tr> 716 <tr> 717 <td>VALUE_FIELD</td> 718 <td>0x19</td> 719 <td>size - 1 (0…3)</td> 720 <td>ubyte[size]</td> 721 <td>unsigned (zero-extended) four-byte integer value, 722 interpreted as an index into 723 the <code>field_ids</code> section and representing a reflective 724 field value 725 </td> 726 </tr> 727 <tr> 728 <td>VALUE_METHOD</td> 729 <td>0x1a</td> 730 <td>size - 1 (0…3)</td> 731 <td>ubyte[size]</td> 732 <td>unsigned (zero-extended) four-byte integer value, 733 interpreted as an index into 734 the <code>method_ids</code> section and representing a reflective 735 method value 736 </td> 737 </tr> 738 <tr> 739 <td>VALUE_ENUM</td> 740 <td>0x1b</td> 741 <td>size - 1 (0…3)</td> 742 <td>ubyte[size]</td> 743 <td>unsigned (zero-extended) four-byte integer value, 744 interpreted as an index into 745 the <code>field_ids</code> section and representing the value of 746 an enumerated type constant 747 </td> 748 </tr> 749 <tr> 750 <td>VALUE_ARRAY</td> 751 <td>0x1c</td> 752 <td><i>(none; must be <code>0</code>)</i></td> 753 <td>encoded_array</td> 754 <td>an array of values, in the format specified by 755 "<code>encoded_array</code> format" below. The size 756 of the <code>value</code> is implicit in the encoding. 757 </td> 758 </tr> 759 <tr> 760 <td>VALUE_ANNOTATION</td> 761 <td>0x1d</td> 762 <td><i>(none; must be <code>0</code>)</i></td> 763 <td>encoded_annotation</td> 764 <td>a sub-annotation, in the format specified by 765 "<code>encoded_annotation</code> format" below. The size 766 of the <code>value</code> is implicit in the encoding. 767 </td> 768 </tr> 769 <tr> 770 <td>VALUE_NULL</td> 771 <td>0x1e</td> 772 <td><i>(none; must be <code>0</code>)</i></td> 773 <td><i>(none)</i></td> 774 <td><code>null</code> reference value</td> 775 </tr> 776 <tr> 777 <td>VALUE_BOOLEAN</td> 778 <td>0x1f</td> 779 <td>boolean (0…1)</td> 780 <td><i>(none)</i></td> 781 <td>one-bit value; <code>0</code> for <code>false</code> and 782 <code>1</code> for <code>true</code>. The bit is represented in the 783 <code>value_arg</code>. 784 </td> 785 </tr> 786 </tbody> 787 </table> 788 789 <h3 id="encoded-array">encoded_array format</h3> 790 791 <table class="format"> 792 <thead> 793 <tr> 794 <th>Name</th> 795 <th>Format</th> 796 <th>Description</th> 797 </tr> 798 </thead> 799 <tbody> 800 <tr> 801 <td>size</td> 802 <td>uleb128</td> 803 <td>number of elements in the array</td> 804 </tr> 805 <tr> 806 <td>values</td> 807 <td>encoded_value[size]</td> 808 <td>a series of <code>size</code> <code>encoded_value</code> byte 809 sequences in the format specified by this section, concatenated 810 sequentially. 811 </td> 812 </tr> 813 </tbody> 814 </table> 815 816 <h3 id="encoded-annotation">encoded_annotation format</h3> 817 818 <table class="format"> 819 <thead> 820 <tr> 821 <th>Name</th> 822 <th>Format</th> 823 <th>Description</th> 824 </tr> 825 </thead> 826 <tbody> 827 <tr> 828 <td>type_idx</td> 829 <td>uleb128</td> 830 <td>type of the annotation. This must be a class (not array or primitive) 831 type. 832 </td> 833 </tr> 834 <tr> 835 <td>size</td> 836 <td>uleb128</td> 837 <td>number of name-value mappings in this annotation</td> 838 </tr> 839 <tr> 840 <td>elements</td> 841 <td>annotation_element[size]</td> 842 <td>elements of the annotation, represented directly in-line (not as 843 offsets). Elements must be sorted in increasing order by 844 <code>string_id</code> index. 845 </td> 846 </tr> 847 </tbody> 848 </table> 849 850 <h3 id="annotation-element">annotation_element format</h3> 851 852 <table class="format"> 853 <thead> 854 <tr> 855 <th>Name</th> 856 <th>Format</th> 857 <th>Description</th> 858 </tr> 859 </thead> 860 <tbody> 861 <tr> 862 <td>name_idx</td> 863 <td>uleb128</td> 864 <td>element name, represented as an index into the 865 <code>string_ids</code> section. The string must conform to the 866 syntax for <i>MemberName</i>, defined above. 867 </td> 868 </tr> 869 <tr> 870 <td>value</td> 871 <td>encoded_value</td> 872 <td>element value</td> 873 </tr> 874 </tbody> 875 </table> 876 877 <h2 id="string-syntax">String syntax</h2> 878 879 <p>There are several kinds of item in a <code>.dex</code> file which 880 ultimately refer to a string. The following BNF-style definitions 881 indicate the acceptable syntax for these strings.</p> 882 883 <h3 id="simplename"><i>SimpleName</i></h3> 884 885 <p>A <i>SimpleName</i> is the basis for the syntax of the names of other 886 things. The <code>.dex</code> format allows a fair amount of latitude 887 here (much more than most common source languages). In brief, a simple 888 name consists of any low-ASCII alphabetic character or digit, a few 889 specific low-ASCII symbols, and most non-ASCII code points that are not 890 control, space, or special characters. Note that surrogate code points 891 (in the range <code>U+d800</code> … <code>U+dfff</code>) are not 892 considered valid name characters, per se, but Unicode supplemental 893 characters <i>are</i> valid (which are represented by the final 894 alternative of the rule for <i>SimpleNameChar</i>), and they should be 895 represented in a file as pairs of surrogate code points in the MUTF-8 896 encoding.</p> 897 898 <table class="bnf"> 899 <tr><td colspan="2" class="def"><i>SimpleName</i> →</td></tr> 900 <tr> 901 <td/> 902 <td><i>SimpleNameChar</i> (<i>SimpleNameChar</i>)*</td> 903 </tr> 904 905 <tr><td colspan="2" class="def"><i>SimpleNameChar</i> →</td></tr> 906 <tr> 907 <td/> 908 <td><code>'A'</code> … <code>'Z'</code></td> 909 </tr> 910 <tr> 911 <td class="bar">|</td> 912 <td><code>'a'</code> … <code>'z'</code></td> 913 </tr> 914 <tr> 915 <td class="bar">|</td> 916 <td><code>'0'</code> … <code>'9'</code></td> 917 </tr> 918 <tr> 919 <td class="bar">|</td> 920 <td><code>'$'</code></td> 921 </tr> 922 <tr> 923 <td class="bar">|</td> 924 <td><code>'-'</code></td> 925 </tr> 926 <tr> 927 <td class="bar">|</td> 928 <td><code>'_'</code></td> 929 </tr> 930 <tr> 931 <td class="bar">|</td> 932 <td><code>U+00a1</code> … <code>U+1fff</code></td> 933 </tr> 934 <tr> 935 <td class="bar">|</td> 936 <td><code>U+2010</code> … <code>U+2027</code></td> 937 </tr> 938 <tr> 939 <td class="bar">|</td> 940 <td><code>U+2030</code> … <code>U+d7ff</code></td> 941 </tr> 942 <tr> 943 <td class="bar">|</td> 944 <td><code>U+e000</code> … <code>U+ffef</code></td> 945 </tr> 946 <tr> 947 <td class="bar">|</td> 948 <td><code>U+10000</code> … <code>U+10ffff</code></td> 949 </tr> 950 </table> 951 952 <h3 id="membername"><i>MemberName</i></h3> 953 <h4>used by field_id_item and method_id_item</h4> 954 955 <p>A <i>MemberName</i> is the name of a member of a class, members being 956 fields, methods, and inner classes.</p> 957 958 <table class="bnf"> 959 <tr><td colspan="2" class="def"><i>MemberName</i> →</td></tr> 960 <tr> 961 <td/> 962 <td><i>SimpleName</i></td> 963 </tr> 964 <tr> 965 <td class="bar">|</td> 966 <td><code>'<'</code> <i>SimpleName</i> <code>'>'</code></td> 967 </tr> 968 </table> 969 970 <h3 id="fullclassname"><i>FullClassName</i></h3> 971 972 <p>A <i>FullClassName</i> is a fully-qualified class name, including an 973 optional package specifier followed by a required name.</p> 974 975 <table class="bnf"> 976 <tr><td colspan="2" class="def"><i>FullClassName</i> →</td></tr> 977 <tr> 978 <td/> 979 <td><i>OptionalPackagePrefix</i> <i>SimpleName</i></td> 980 </tr> 981 982 <tr><td colspan="2" class="def"><i>OptionalPackagePrefix</i> →</td></tr> 983 <tr> 984 <td/> 985 <td>(<i>SimpleName</i> <code>'/'</code>)*</td> 986 </tr> 987 </table> 988 989 <h3 id="typedescriptor"><i>TypeDescriptor</i></h3> 990 <h4>used by type_id_item</h4> 991 992 <p>A <i>TypeDescriptor</i> is the representation of any type, including 993 primitives, classes, arrays, and <code>void</code>. See below for 994 the meaning of the various versions.</p> 995 996 <table class="bnf"> 997 <tr><td colspan="2" class="def"><i>TypeDescriptor</i> →</td></tr> 998 <tr> 999 <td/> 1000 <td><code>'V'</code></td> 1001 </tr> 1002 <tr> 1003 <td class="bar">|</td> 1004 <td><i>FieldTypeDescriptor</i></td> 1005 </tr> 1006 1007 <tr><td colspan="2" class="def"><i>FieldTypeDescriptor</i> →</td></tr> 1008 <tr> 1009 <td/> 1010 <td><i>NonArrayFieldTypeDescriptor</i></td> 1011 </tr> 1012 <tr> 1013 <td class="bar">|</td> 1014 <td>(<code>'['</code> * 1…255) 1015 <i>NonArrayFieldTypeDescriptor</i></td> 1016 </tr> 1017 1018 <tr> 1019 <td colspan="2" class="def"><i>NonArrayFieldTypeDescriptor</i>→</td> 1020 </tr> 1021 <tr> 1022 <td/> 1023 <td><code>'Z'</code></td> 1024 </tr> 1025 <tr> 1026 <td class="bar">|</td> 1027 <td><code>'B'</code></td> 1028 </tr> 1029 <tr> 1030 <td class="bar">|</td> 1031 <td><code>'S'</code></td> 1032 </tr> 1033 <tr> 1034 <td class="bar">|</td> 1035 <td><code>'C'</code></td> 1036 </tr> 1037 <tr> 1038 <td class="bar">|</td> 1039 <td><code>'I'</code></td> 1040 </tr> 1041 <tr> 1042 <td class="bar">|</td> 1043 <td><code>'J'</code></td> 1044 </tr> 1045 <tr> 1046 <td class="bar">|</td> 1047 <td><code>'F'</code></td> 1048 </tr> 1049 <tr> 1050 <td class="bar">|</td> 1051 <td><code>'D'</code></td> 1052 </tr> 1053 <tr> 1054 <td class="bar">|</td> 1055 <td><code>'L'</code> <i>FullClassName</i> <code>';'</code></td> 1056 </tr> 1057 </table> 1058 1059 <h3 id="shortydescriptor"><i>ShortyDescriptor</i></h3> 1060 <h4>used by proto_id_item</h4> 1061 1062 <p>A <i>ShortyDescriptor</i> is the short form representation of a method 1063 prototype, including return and parameter types, except that there is 1064 no distinction between various reference (class or array) types. Instead, 1065 all reference types are represented by a single <code>'L'</code> character.</p> 1066 1067 <table class="bnf"> 1068 <tr><td colspan="2" class="def"><i>ShortyDescriptor</i> →</td></tr> 1069 <tr> 1070 <td/> 1071 <td><i>ShortyReturnType</i> (<i>ShortyFieldType</i>)*</td> 1072 </tr> 1073 1074 <tr><td colspan="2" class="def"><i>ShortyReturnType</i> →</td></tr> 1075 <tr> 1076 <td/> 1077 <td><code>'V'</code></td> 1078 </tr> 1079 <tr> 1080 <td class="bar">|</td> 1081 <td><i>ShortyFieldType</i></td> 1082 </tr> 1083 1084 <tr><td colspan="2" class="def"><i>ShortyFieldType</i> →</td></tr> 1085 <tr> 1086 <td/> 1087 <td><code>'Z'</code></td> 1088 </tr> 1089 <tr> 1090 <td class="bar">|</td> 1091 <td><code>'B'</code></td> 1092 </tr> 1093 <tr> 1094 <td class="bar">|</td> 1095 <td><code>'S'</code></td> 1096 </tr> 1097 <tr> 1098 <td class="bar">|</td> 1099 <td><code>'C'</code></td> 1100 </tr> 1101 <tr> 1102 <td class="bar">|</td> 1103 <td><code>'I'</code></td> 1104 </tr> 1105 <tr> 1106 <td class="bar">|</td> 1107 <td><code>'J'</code></td> 1108 </tr> 1109 <tr> 1110 <td class="bar">|</td> 1111 <td><code>'F'</code></td> 1112 </tr> 1113 <tr> 1114 <td class="bar">|</td> 1115 <td><code>'D'</code></td> 1116 </tr> 1117 <tr> 1118 <td class="bar">|</td> 1119 <td><code>'L'</code></td> 1120 </tr> 1121 </table> 1122 1123 <h3 id="typedescriptor"><i>TypeDescriptor</i> Semantics</h3> 1124 1125 <p>This is the meaning of each of the variants of <i>TypeDescriptor</i>.</p> 1126 1127 <table class="descriptor"> 1128 <thead> 1129 <tr> 1130 <th>Syntax</th> 1131 <th>Meaning</th> 1132 </tr> 1133 </thead> 1134 <tbody> 1135 <tr> 1136 <td>V</td> 1137 <td><code>void</code>; only valid for return types</td> 1138 </tr> 1139 <tr> 1140 <td>Z</td> 1141 <td><code>boolean</code></td> 1142 </tr> 1143 <tr> 1144 <td>B</td> 1145 <td><code>byte</code></td> 1146 </tr> 1147 <tr> 1148 <td>S</td> 1149 <td><code>short</code></td> 1150 </tr> 1151 <tr> 1152 <td>C</td> 1153 <td><code>char</code></td> 1154 </tr> 1155 <tr> 1156 <td>I</td> 1157 <td><code>int</code></td> 1158 </tr> 1159 <tr> 1160 <td>J</td> 1161 <td><code>long</code></td> 1162 </tr> 1163 <tr> 1164 <td>F</td> 1165 <td><code>float</code></td> 1166 </tr> 1167 <tr> 1168 <td>D</td> 1169 <td><code>double</code></td> 1170 </tr> 1171 <tr> 1172 <td>L<i>fully/qualified/Name</i>;</td> 1173 <td>the class <code><i>fully.qualified.Name</i></code></td> 1174 </tr> 1175 <tr> 1176 <td>[<i>descriptor</i></td> 1177 <td>array of <code><i>descriptor</i></code>, usable recursively for 1178 arrays-of-arrays, though it is invalid to have more than 255 1179 dimensions. 1180 </td> 1181 </tr> 1182 </tbody> 1183 </table> 1184 1185 <h2 id="items">Items and related structures</h2> 1186 1187 <p>This section includes definitions for each of the top-level items that 1188 may appear in a <code>.dex</code> file. 1189 1190 <h3 id="header-item">header_item</h3> 1191 <h4>appears in the header section</h4> 1192 <h4>alignment: 4 bytes</h4> 1193 1194 <table class="format"> 1195 <thead> 1196 <tr> 1197 <th>Name</th> 1198 <th>Format</th> 1199 <th>Description</th> 1200 </tr> 1201 </thead> 1202 <tbody> 1203 <tr> 1204 <td>magic</td> 1205 <td>ubyte[8] = DEX_FILE_MAGIC</td> 1206 <td>magic value. See discussion above under "<code>DEX_FILE_MAGIC</code>" 1207 for more details. 1208 </td> 1209 </tr> 1210 <tr> 1211 <td>checksum</td> 1212 <td>uint</td> 1213 <td>adler32 checksum of the rest of the file (everything but 1214 <code>magic</code> and this field); used to detect file corruption 1215 </td> 1216 </tr> 1217 <tr> 1218 <td>signature</td> 1219 <td>ubyte[20]</td> 1220 <td>SHA-1 signature (hash) of the rest of the file (everything but 1221 <code>magic</code>, <code>checksum</code>, and this field); used 1222 to uniquely identify files 1223 </td> 1224 </tr> 1225 <tr> 1226 <td>file_size</td> 1227 <td>uint</td> 1228 <td>size of the entire file (including the header), in bytes 1229 </tr> 1230 <tr> 1231 <td>header_size</td> 1232 <td>uint = 0x70</td> 1233 <td>size of the header (this entire section), in bytes. This allows for at 1234 least a limited amount of backwards/forwards compatibility without 1235 invalidating the format. 1236 </td> 1237 </tr> 1238 <tr> 1239 <td>endian_tag</td> 1240 <td>uint = ENDIAN_CONSTANT</td> 1241 <td>endianness tag. See discussion above under "<code>ENDIAN_CONSTANT</code> 1242 and <code>REVERSE_ENDIAN_CONSTANT</code>" for more details. 1243 </td> 1244 </tr> 1245 <tr> 1246 <td>link_size</td> 1247 <td>uint</td> 1248 <td>size of the link section, or <code>0</code> if this file isn't 1249 statically linked</td> 1250 </tr> 1251 <tr> 1252 <td>link_off</td> 1253 <td>uint</td> 1254 <td>offset from the start of the file to the link section, or 1255 <code>0</code> if <code>link_size == 0</code>. The offset, if non-zero, 1256 should be to an offset into the <code>link_data</code> section. The 1257 format of the data pointed at is left unspecified by this document; 1258 this header field (and the previous) are left as hooks for use by 1259 runtime implementations. 1260 </td> 1261 </tr> 1262 <tr> 1263 <td>map_off</td> 1264 <td>uint</td> 1265 <td>offset from the start of the file to the map item. The offset, which must 1266 be non-zero, should be to an offset into the <code>data</code> section, 1267 and the data should be in the format specified by "<code>map_list</code>" 1268 below. 1269 </td> 1270 </tr> 1271 <tr> 1272 <td>string_ids_size</td> 1273 <td>uint</td> 1274 <td>count of strings in the string identifiers list</td> 1275 </tr> 1276 <tr> 1277 <td>string_ids_off</td> 1278 <td>uint</td> 1279 <td>offset from the start of the file to the string identifiers list, or 1280 <code>0</code> if <code>string_ids_size == 0</code> (admittedly a 1281 strange edge case). The offset, if non-zero, 1282 should be to the start of the <code>string_ids</code> section. 1283 </td> 1284 </tr> 1285 <tr> 1286 <td>type_ids_size</td> 1287 <td>uint</td> 1288 <td>count of elements in the type identifiers list, at most 65535</td> 1289 </tr> 1290 <tr> 1291 <td>type_ids_off</td> 1292 <td>uint</td> 1293 <td>offset from the start of the file to the type identifiers list, or 1294 <code>0</code> if <code>type_ids_size == 0</code> (admittedly a 1295 strange edge case). The offset, if non-zero, 1296 should be to the start of the <code>type_ids</code> 1297 section. 1298 </td> 1299 </tr> 1300 <tr> 1301 <td>proto_ids_size</td> 1302 <td>uint</td> 1303 <td>count of elements in the prototype identifiers list, at most 65535</td> 1304 </tr> 1305 <tr> 1306 <td>proto_ids_off</td> 1307 <td>uint</td> 1308 <td>offset from the start of the file to the prototype identifiers list, or 1309 <code>0</code> if <code>proto_ids_size == 0</code> (admittedly a 1310 strange edge case). The offset, if non-zero, 1311 should be to the start of the <code>proto_ids</code> 1312 section. 1313 </td> 1314 </tr> 1315 <tr> 1316 <td>field_ids_size</td> 1317 <td>uint</td> 1318 <td>count of elements in the field identifiers list</td> 1319 </tr> 1320 <tr> 1321 <td>field_ids_off</td> 1322 <td>uint</td> 1323 <td>offset from the start of the file to the field identifiers list, or 1324 <code>0</code> if <code>field_ids_size == 0</code>. The offset, if 1325 non-zero, should be to the start of the <code>field_ids</code> 1326 section.</td> 1327 </tr> 1328 <tr> 1329 <td>method_ids_size</td> 1330 <td>uint</td> 1331 <td>count of elements in the method identifiers list</td> 1332 </tr> 1333 <tr> 1334 <td>method_ids_off</td> 1335 <td>uint</td> 1336 <td>offset from the start of the file to the method identifiers list, or 1337 <code>0</code> if <code>method_ids_size == 0</code>. The offset, if 1338 non-zero, should be to the start of the <code>method_ids</code> 1339 section.</td> 1340 </tr> 1341 <tr> 1342 <td>class_defs_size</td> 1343 <td>uint</td> 1344 <td>count of elements in the class definitions list</td> 1345 </tr> 1346 <tr> 1347 <td>class_defs_off</td> 1348 <td>uint</td> 1349 <td>offset from the start of the file to the class definitions list, or 1350 <code>0</code> if <code>class_defs_size == 0</code> (admittedly a 1351 strange edge case). The offset, if non-zero, 1352 should be to the start of the <code>class_defs</code> section. 1353 </td> 1354 </tr> 1355 <tr> 1356 <td>data_size</td> 1357 <td>uint</td> 1358 <td>Size of <code>data</code> section in bytes. Must be an even 1359 multiple of sizeof(uint).</td> 1360 </tr> 1361 <tr> 1362 <td>data_off</td> 1363 <td>uint</td> 1364 <td>offset from the start of the file to the start of the 1365 <code>data</code> section. 1366 </td> 1367 </tr> 1368 </tbody> 1369 </table> 1370 1371 <h3 id="map-list">map_list</h3> 1372 <h4>appears in the data section</h4> 1373 <h4>referenced from header_item</h4> 1374 <h4>alignment: 4 bytes</h4> 1375 1376 <p>This is a list of the entire contents of a file, in order. It 1377 contains some redundancy with respect to the <code>header_item</code> 1378 but is intended to be an easy form to use to iterate over an entire 1379 file. A given type must appear at most once in a map, but there is no 1380 restriction on what order types may appear in, other than the 1381 restrictions implied by the rest of the format (e.g., a 1382 <code>header</code> section must appear first, followed by a 1383 <code>string_ids</code> section, etc.). Additionally, the map entries must 1384 be ordered by initial offset and must not overlap.</p> 1385 1386 <table class="format"> 1387 <thead> 1388 <tr> 1389 <th>Name</th> 1390 <th>Format</th> 1391 <th>Description</th> 1392 </tr> 1393 </thead> 1394 <tbody> 1395 <tr> 1396 <td>size</td> 1397 <td>uint</td> 1398 <td>size of the list, in entries</td> 1399 </tr> 1400 <tr> 1401 <td>list</td> 1402 <td>map_item[size]</td> 1403 <td>elements of the list</td> 1404 </tr> 1405 </tbody> 1406 </table> 1407 1408 <h3 id="map-item">map_item format</h3> 1409 1410 <table class="format"> 1411 <thead> 1412 <tr> 1413 <th>Name</th> 1414 <th>Format</th> 1415 <th>Description</th> 1416 </tr> 1417 </thead> 1418 <tbody> 1419 <tr> 1420 <td>type</td> 1421 <td>ushort</td> 1422 <td>type of the items; see table below</td> 1423 </tr> 1424 <tr> 1425 <td>unused</td> 1426 <td>ushort</td> 1427 <td><i>(unused)</i></td> 1428 </tr> 1429 <tr> 1430 <td>size</td> 1431 <td>uint</td> 1432 <td>count of the number of items to be found at the indicated offset</td> 1433 </tr> 1434 <tr> 1435 <td>offset</td> 1436 <td>uint</td> 1437 <td>offset from the start of the file to the items in question</td> 1438 </tr> 1439 </tbody> 1440 </table> 1441 1442 1443 <h3 id="type-codes">Type Codes</h3> 1444 1445 <table class="typeCodes"> 1446 <thead> 1447 <tr> 1448 <th>Item Type</th> 1449 <th>Constant</th> 1450 <th>Value</th> 1451 <th>Item Size In Bytes</th> 1452 </tr> 1453 </thead> 1454 <tbody> 1455 <tr> 1456 <td>header_item</td> 1457 <td>TYPE_HEADER_ITEM</td> 1458 <td>0x0000</td> 1459 <td>0x70</td> 1460 </tr> 1461 <tr> 1462 <td>string_id_item</td> 1463 <td>TYPE_STRING_ID_ITEM</td> 1464 <td>0x0001</td> 1465 <td>0x04</td> 1466 </tr> 1467 <tr> 1468 <td>type_id_item</td> 1469 <td>TYPE_TYPE_ID_ITEM</td> 1470 <td>0x0002</td> 1471 <td>0x04</td> 1472 </tr> 1473 <tr> 1474 <td>proto_id_item</td> 1475 <td>TYPE_PROTO_ID_ITEM</td> 1476 <td>0x0003</td> 1477 <td>0x0c</td> 1478 </tr> 1479 <tr> 1480 <td>field_id_item</td> 1481 <td>TYPE_FIELD_ID_ITEM</td> 1482 <td>0x0004</td> 1483 <td>0x08</td> 1484 </tr> 1485 <tr> 1486 <td>method_id_item</td> 1487 <td>TYPE_METHOD_ID_ITEM</td> 1488 <td>0x0005</td> 1489 <td>0x08</td> 1490 </tr> 1491 <tr> 1492 <td>class_def_item</td> 1493 <td>TYPE_CLASS_DEF_ITEM</td> 1494 <td>0x0006</td> 1495 <td>0x20</td> 1496 </tr> 1497 <tr> 1498 <td>call_site_id_item</td> 1499 <td>TYPE_CALL_SITE_ID_ITEM</td> 1500 <td>0x0007</td> 1501 <td>0x04</td> 1502 </tr> 1503 <tr> 1504 <td>method_handle_item</td> 1505 <td>TYPE_METHOD_HANDLE_ITEM</td> 1506 <td>0x0008</td> 1507 <td>0x08</td> 1508 </tr> 1509 <tr> 1510 <td>map_list</td> 1511 <td>TYPE_MAP_LIST</td> 1512 <td>0x1000</td> 1513 <td>4 + (item.size * 12)</td> 1514 </tr> 1515 <tr> 1516 <td>type_list</td> 1517 <td>TYPE_TYPE_LIST</td> 1518 <td>0x1001</td> 1519 <td>4 + (item.size * 2)</td> 1520 </tr> 1521 <tr> 1522 <td>annotation_set_ref_list</td> 1523 <td>TYPE_ANNOTATION_SET_REF_LIST</td> 1524 <td>0x1002</td> 1525 <td>4 + (item.size * 4)</td> 1526 </tr> 1527 <tr> 1528 <td>annotation_set_item</td> 1529 <td>TYPE_ANNOTATION_SET_ITEM</td> 1530 <td>0x1003</td> 1531 <td>4 + (item.size * 4)</td> 1532 </tr> 1533 <tr> 1534 <td>class_data_item</td> 1535 <td>TYPE_CLASS_DATA_ITEM</td> 1536 <td>0x2000</td> 1537 <td><i>implicit; must parse</i></td> 1538 </tr> 1539 <tr> 1540 <td>code_item</td> 1541 <td>TYPE_CODE_ITEM</td> 1542 <td>0x2001</td> 1543 <td><i>implicit; must parse</i></td> 1544 </tr> 1545 <tr> 1546 <td>string_data_item</td> 1547 <td>TYPE_STRING_DATA_ITEM</td> 1548 <td>0x2002</td> 1549 <td><i>implicit; must parse</i></td> 1550 </tr> 1551 <tr> 1552 <td>debug_info_item</td> 1553 <td>TYPE_DEBUG_INFO_ITEM</td> 1554 <td>0x2003</td> 1555 <td><i>implicit; must parse</i></td> 1556 </tr> 1557 <tr> 1558 <td>annotation_item</td> 1559 <td>TYPE_ANNOTATION_ITEM</td> 1560 <td>0x2004</td> 1561 <td><i>implicit; must parse</i></td> 1562 </tr> 1563 <tr> 1564 <td>encoded_array_item</td> 1565 <td>TYPE_ENCODED_ARRAY_ITEM</td> 1566 <td>0x2005</td> 1567 <td><i>implicit; must parse</i></td> 1568 </tr> 1569 <tr> 1570 <td>annotations_directory_item</td> 1571 <td>TYPE_ANNOTATIONS_DIRECTORY_ITEM</td> 1572 <td>0x2006</td> 1573 <td><i>implicit; must parse</i></td> 1574 </tr> 1575 </tbody> 1576 </table> 1577 1578 1579 <h3 id="string-item">string_id_item</h3> 1580 <h4>appears in the string_ids section</h4> 1581 <h4>alignment: 4 bytes</h4> 1582 1583 <table class="format"> 1584 <thead> 1585 <tr> 1586 <th>Name</th> 1587 <th>Format</th> 1588 <th>Description</th> 1589 </tr> 1590 </thead> 1591 <tbody> 1592 <tr> 1593 <td>string_data_off</td> 1594 <td>uint</td> 1595 <td>offset from the start of the file to the string data for this 1596 item. The offset should be to a location 1597 in the <code>data</code> section, and the data should be in the 1598 format specified by "<code>string_data_item</code>" below. 1599 There is no alignment requirement for the offset. 1600 </td> 1601 </tr> 1602 </tbody> 1603 </table> 1604 1605 <h3 id="string-data-item">string_data_item</h3> 1606 <h4>appears in the data section</h4> 1607 <h4>alignment: none (byte-aligned)</h4> 1608 1609 <table class="format"> 1610 <thead> 1611 <tr> 1612 <th>Name</th> 1613 <th>Format</th> 1614 <th>Description</th> 1615 </tr> 1616 </thead> 1617 <tbody> 1618 <tr> 1619 <td>utf16_size</td> 1620 <td>uleb128</td> 1621 <td>size of this string, in UTF-16 code units (which is the "string 1622 length" in many systems). That is, this is the decoded length of 1623 the string. (The encoded length is implied by the position of 1624 the <code>0</code> byte.)</td> 1625 </tr> 1626 <tr> 1627 <td>data</td> 1628 <td>ubyte[]</td> 1629 <td>a series of MUTF-8 code units (a.k.a. octets, a.k.a. bytes) 1630 followed by a byte of value <code>0</code>. See 1631 "MUTF-8 (Modified UTF-8) Encoding" above for details and 1632 discussion about the data format. 1633 <p class="note"><strong>Note:</strong> It is acceptable to have a string which includes 1634 (the encoded form of) UTF-16 surrogate code units (that is, 1635 <code>U+d800</code> … <code>U+dfff</code>) 1636 either in isolation or out-of-order with respect to the usual 1637 encoding of Unicode into UTF-16. It is up to higher-level uses of 1638 strings to reject such invalid encodings, if appropriate.</p> 1639 </td> 1640 </tr> 1641 </tbody> 1642 </table> 1643 1644 <h3 id="type-id-item">type_id_item</h3> 1645 <h4>appears in the type_ids section</h4> 1646 <h4>alignment: 4 bytes</h4> 1647 1648 <table class="format"> 1649 <thead> 1650 <tr> 1651 <th>Name</th> 1652 <th>Format</th> 1653 <th>Description</th> 1654 </tr> 1655 </thead> 1656 <tbody> 1657 <tr> 1658 <td>descriptor_idx</td> 1659 <td>uint</td> 1660 <td>index into the <code>string_ids</code> list for the descriptor 1661 string of this type. The string must conform to the syntax for 1662 <i>TypeDescriptor</i>, defined above. 1663 </td> 1664 </tr> 1665 </tbody> 1666 </table> 1667 1668 <h3 id="proto-id-item">proto_id_item</h3> 1669 <h4>appears in the proto_ids section</h4> 1670 <h4>alignment: 4 bytes</h4> 1671 1672 <table class="format"> 1673 <thead> 1674 <tr> 1675 <th>Name</th> 1676 <th>Format</th> 1677 <th>Description</th> 1678 </tr> 1679 </thead> 1680 <tbody> 1681 <tr> 1682 <td>shorty_idx</td> 1683 <td>uint</td> 1684 <td>index into the <code>string_ids</code> list for the short-form 1685 descriptor string of this prototype. The string must conform to the 1686 syntax for <i>ShortyDescriptor</i>, defined above, and must correspond 1687 to the return type and parameters of this item. 1688 </td> 1689 </tr> 1690 <tr> 1691 <td>return_type_idx</td> 1692 <td>uint</td> 1693 <td>index into the <code>type_ids</code> list for the return type 1694 of this prototype 1695 </td> 1696 </tr> 1697 <tr> 1698 <td>parameters_off</td> 1699 <td>uint</td> 1700 <td>offset from the start of the file to the list of parameter types 1701 for this prototype, or <code>0</code> if this prototype has no 1702 parameters. This offset, if non-zero, should be in the 1703 <code>data</code> section, and the data there should be in the 1704 format specified by <code>"type_list"</code> below. Additionally, there 1705 should be no reference to the type <code>void</code> in the list. 1706 </td> 1707 </tr> 1708 </tbody> 1709 </table> 1710 1711 <h3 id="field-id-item">field_id_item</h3> 1712 <h4>appears in the field_ids section</h4> 1713 <h4>alignment: 4 bytes</h4> 1714 1715 <table class="format"> 1716 <thead> 1717 <tr> 1718 <th>Name</th> 1719 <th>Format</th> 1720 <th>Description</th> 1721 </tr> 1722 </thead> 1723 <tbody> 1724 <tr> 1725 <td>class_idx</td> 1726 <td>ushort</td> 1727 <td>index into the <code>type_ids</code> list for the definer of this 1728 field. This must be a class type, and not an array or primitive type. 1729 </td> 1730 </tr> 1731 <tr> 1732 <td>type_idx</td> 1733 <td>ushort</td> 1734 <td>index into the <code>type_ids</code> list for the type of 1735 this field 1736 </td> 1737 </tr> 1738 <tr> 1739 <td>name_idx</td> 1740 <td>uint</td> 1741 <td>index into the <code>string_ids</code> list for the name of this 1742 field. The string must conform to the syntax for <i>MemberName</i>, 1743 defined above. 1744 </td> 1745 </tr> 1746 </tbody> 1747 </table> 1748 1749 <h3 id="method-id-item">method_id_item</h3> 1750 <h4>appears in the method_ids section</h4> 1751 <h4>alignment: 4 bytes</h4> 1752 1753 <table class="format"> 1754 <thead> 1755 <tr> 1756 <th>Name</th> 1757 <th>Format</th> 1758 <th>Description</th> 1759 </tr> 1760 </thead> 1761 <tbody> 1762 <tr> 1763 <td>class_idx</td> 1764 <td>ushort</td> 1765 <td>index into the <code>type_ids</code> list for the definer of this 1766 method. This must be a class or array type, and not a primitive type. 1767 </td> 1768 </tr> 1769 <tr> 1770 <td>proto_idx</td> 1771 <td>ushort</td> 1772 <td>index into the <code>proto_ids</code> list for the prototype of 1773 this method 1774 </td> 1775 </tr> 1776 <tr> 1777 <td>name_idx</td> 1778 <td>uint</td> 1779 <td>index into the <code>string_ids</code> list for the name of this 1780 method. The string must conform to the syntax for <i>MemberName</i>, 1781 defined above. 1782 </td> 1783 </tr> 1784 </tbody> 1785 </table> 1786 1787 <h3 id="class-def-item">class_def_item</h3> 1788 <h4>appears in the class_defs section</h4> 1789 <h4>alignment: 4 bytes</h4> 1790 1791 <table class="format"> 1792 <thead> 1793 <tr> 1794 <th>Name</th> 1795 <th>Format</th> 1796 <th>Description</th> 1797 </tr> 1798 </thead> 1799 <tbody> 1800 <tr> 1801 <td>class_idx</td> 1802 <td>uint</td> 1803 <td>index into the <code>type_ids</code> list for this class. 1804 This must be a class type, and not an array or primitive type. 1805 </td> 1806 </tr> 1807 <tr> 1808 <td>access_flags</td> 1809 <td>uint</td> 1810 <td>access flags for the class (<code>public</code>, <code>final</code>, 1811 etc.). See "<code>access_flags</code> Definitions" for details. 1812 </td> 1813 </tr> 1814 <tr> 1815 <td>superclass_idx</td> 1816 <td>uint</td> 1817 <td>index into the <code>type_ids</code> list for the superclass, or 1818 the constant value <code>NO_INDEX</code> if this class has no 1819 superclass (i.e., it is a root class such as <code>Object</code>). 1820 If present, this must be a class type, and not an array or primitive type. 1821 </td> 1822 </tr> 1823 <tr> 1824 <td>interfaces_off</td> 1825 <td>uint</td> 1826 <td>offset from the start of the file to the list of interfaces, or 1827 <code>0</code> if there are none. This offset 1828 should be in the <code>data</code> section, and the data 1829 there should be in the format specified by 1830 "<code>type_list</code>" below. Each of the elements of the list 1831 must be a class type (not an array or primitive type), and there 1832 must not be any duplicates. 1833 </td> 1834 </tr> 1835 <tr> 1836 <td>source_file_idx</td> 1837 <td>uint</td> 1838 <td>index into the <code>string_ids</code> list for the name of the 1839 file containing the original source for (at least most of) this class, 1840 or the special value <code>NO_INDEX</code> to represent a lack of 1841 this information. The <code>debug_info_item</code> of any given method 1842 may override this source file, but the expectation is that most classes 1843 will only come from one source file. 1844 </td> 1845 </tr> 1846 <tr> 1847 <td>annotations_off</td> 1848 <td>uint</td> 1849 <td>offset from the start of the file to the annotations structure 1850 for this class, or <code>0</code> if there are no annotations on 1851 this class. This offset, if non-zero, should be in the 1852 <code>data</code> section, and the data there should be in 1853 the format specified by "<code>annotations_directory_item</code>" below, 1854 with all items referring to this class as the definer. 1855 </td> 1856 </tr> 1857 <tr> 1858 <td>class_data_off</td> 1859 <td>uint</td> 1860 <td>offset from the start of the file to the associated 1861 class data for this item, or <code>0</code> if there is no class 1862 data for this class. (This may be the case, for example, if this class 1863 is a marker interface.) The offset, if non-zero, should be in the 1864 <code>data</code> section, and the data there should be in the 1865 format specified by "<code>class_data_item</code>" below, with all 1866 items referring to this class as the definer. 1867 </td> 1868 </tr> 1869 <tr> 1870 <td>static_values_off</td> 1871 <td>uint</td> 1872 <td>offset from the start of the file to the list of initial 1873 values for <code>static</code> fields, or <code>0</code> if there 1874 are none (and all <code>static</code> fields are to be initialized with 1875 <code>0</code> or <code>null</code>). This offset should be in the 1876 <code>data</code> section, and the data there should be in the 1877 format specified by "<code>encoded_array_item</code>" below. The size 1878 of the array must be no larger than the number of <code>static</code> 1879 fields declared by this class, and the elements correspond to the 1880 <code>static</code> fields in the same order as declared in the 1881 corresponding <code>field_list</code>. The type of each array 1882 element must match the declared type of its corresponding field. 1883 If there are fewer elements in the array than there are 1884 <code>static</code> fields, then the leftover fields are initialized 1885 with a type-appropriate <code>0</code> or <code>null</code>. 1886 </td> 1887 </tr> 1888 </tbody> 1889 </table> 1890 1891 <h3 id="call-site-id-item">call_site_id_item</h3> 1892 <h4>appears in the call_site_ids section</h4> 1893 <h4>alignment: 4 bytes</h4> 1894 1895 <table class="format"> 1896 <thead> 1897 <tr> 1898 <th>Name</th> 1899 <th>Format</th> 1900 <th>Description</th> 1901 </tr> 1902 </thead> 1903 <tbody> 1904 <tr> 1905 <td>call_site_off</td> 1906 <td>uint</td> 1907 <td>offset from the start of the file to call site definition. The offset should 1908 be in the data section, and the data there should be in the format specified by 1909 "call_site_item" below. 1910 </td> 1911 </tr> 1912 </tbody> 1913 </table> 1914 1915 <h3 id="call-site-item">call_site_item</h3> 1916 <h4>appears in the data section</h4> 1917 <h4>alignment: none (byte aligned)</h4> 1918 1919 <p> The call_site_item is an encoded_array_item whose elements correspond to the arguments 1920 provided to a bootstrap linker method. The first three arguments are: 1921 <ol> 1922 <li>A method handle representing the bootstrap linker method (VALUE_METHOD_HANDLE).</li> 1923 <li>A method name that the bootstrap linker should resolve (VALUE_STRING).</li> 1924 <li>A method type corresponding to the type of the method name to be resolved (VALUE_METHOD_TYPE).</li> 1925 </ol> 1926 1927 <p>Any additional arguments are constant values passed to the bootstrap linker method. These arguments are 1928 passed in order and without any type conversions. 1929 1930 <p>The method handle representing the bootstrap linker method must have return type <code>java.lang.invoke.CallSite</code>. The first three parameter types are: 1931 <ol> 1932 <li><code>java.lang.invoke.Lookup</code></li> 1933 <li><code>java.lang.String</code></li> 1934 <li><code>java.lang.invoke.MethodType</code></li> 1935 </ol> 1936 1937 <p>The parameter types of any additional arguments are determined from their constant values. 1938 1939 <h3 id="method-handle-item">method_handle_item</h3> 1940 <h4>appears in the method_handles section</h4> 1941 <h4>alignment: 4 bytes</h4> 1942 1943 <table class="format"> 1944 <thead> 1945 <tr> 1946 <th>Name</th> 1947 <th>Format</th> 1948 <th>Description</th> 1949 </tr> 1950 </thead> 1951 <tbody> 1952 <tr> 1953 <td>method_handle_type</td> 1954 <td>ushort</td> 1955 <td>type of the method handle; see table below 1956 </td> 1957 </tr> 1958 <tr> 1959 <td>unused</td> 1960 <td>ushort</td> 1961 <td><i>(unused)</i></td> 1962 </tr> 1963 <tr> 1964 <td>field_or_method_id</td> 1965 <td>ushort</td> 1966 <td>Field or method id depending on whether the method handle type is an accessor or a method invoker</td> 1967 </tr> 1968 <tr> 1969 <td>unused</td> 1970 <td>ushort</td> 1971 <td><i>(unused)</i></td> 1972 </tr> 1973 </tbody> 1974 </table> 1975 1976 <h3 id="method-handle-type-codes">Method Handle Type Codes</h3> 1977 1978 <table class="format"> 1979 <thead> 1980 <tr> 1981 <th>Constant</th> 1982 <th>Value</th> 1983 <th>Description</th> 1984 </tr> 1985 </thead> 1986 <tbody> 1987 <tr> 1988 <td>METHOD_HANDLE_TYPE_STATIC_PUT</td> 1989 <td>0x00</td> 1990 <td>Method handle is a static field setter (accessor)</td> 1991 </tr> 1992 <tr> 1993 <td>METHOD_HANDLE_TYPE_STATIC_GET</td> 1994 <td>0x01</td> 1995 <td>Method handle is a static field getter (accessor)</td> 1996 </tr> 1997 <tr> 1998 <td>METHOD_HANDLE_TYPE_INSTANCE_PUT</td> 1999 <td>0x02</td> 2000 <td>Method handle is an instance field setter (accessor)</td> 2001 </tr> 2002 <tr> 2003 <td>METHOD_HANDLE_TYPE_INSTANCE_GET</td> 2004 <td>0x03</td> 2005 <td>Method handle is an instance field getter (accessor)</td> 2006 </tr> 2007 <tr> 2008 <td>METHOD_HANDLE_TYPE_INVOKE_STATIC</td> 2009 <td>0x04</td> 2010 <td>Method handle is a static method invoker</td> 2011 </tr> 2012 <tr> 2013 <td>METHOD_HANDLE_TYPE_INVOKE_INSTANCE</td> 2014 <td>0x05</td> 2015 <td>Method handle is an instance method invoker</td> 2016 </tr> 2017 </tbody> 2018 </table> 2019 2020 <h3 id="class-data-item">class_data_item</h3> 2021 <h4>referenced from class_def_item</h4> 2022 <h4>appears in the data section</h4> 2023 <h4>alignment: none (byte-aligned)</h4> 2024 2025 <table class="format"> 2026 <thead> 2027 <tr> 2028 <th>Name</th> 2029 <th>Format</th> 2030 <th>Description</th> 2031 </tr> 2032 </thead> 2033 <tbody> 2034 <tr> 2035 <td>static_fields_size</td> 2036 <td>uleb128</td> 2037 <td>the number of static fields defined in this item</td> 2038 </tr> 2039 <tr> 2040 <td>instance_fields_size</td> 2041 <td>uleb128</td> 2042 <td>the number of instance fields defined in this item</td> 2043 </tr> 2044 <tr> 2045 <td>direct_methods_size</td> 2046 <td>uleb128</td> 2047 <td>the number of direct methods defined in this item</td> 2048 </tr> 2049 <tr> 2050 <td>virtual_methods_size</td> 2051 <td>uleb128</td> 2052 <td>the number of virtual methods defined in this item</td> 2053 </tr> 2054 <tr> 2055 <td>static_fields</td> 2056 <td>encoded_field[static_fields_size]</td> 2057 <td>the defined static fields, represented as a sequence of 2058 encoded elements. The fields must be sorted by 2059 <code>field_idx</code> in increasing order. 2060 </td> 2061 </tr> 2062 <tr> 2063 <td>instance_fields</td> 2064 <td>encoded_field[instance_fields_size]</td> 2065 <td>the defined instance fields, represented as a sequence of 2066 encoded elements. The fields must be sorted by 2067 <code>field_idx</code> in increasing order. 2068 </td> 2069 </tr> 2070 <tr> 2071 <td>direct_methods</td> 2072 <td>encoded_method[direct_methods_size]</td> 2073 <td>the defined direct (any of <code>static</code>, <code>private</code>, 2074 or constructor) methods, represented as a sequence of 2075 encoded elements. The methods must be sorted by 2076 <code>method_idx</code> in increasing order. 2077 </td> 2078 </tr> 2079 <tr> 2080 <td>virtual_methods</td> 2081 <td>encoded_method[virtual_methods_size]</td> 2082 <td>the defined virtual (none of <code>static</code>, <code>private</code>, 2083 or constructor) methods, represented as a sequence of 2084 encoded elements. This list should <i>not</i> include inherited 2085 methods unless overridden by the class that this item represents. The 2086 methods must be sorted by <code>method_idx</code> in increasing order. 2087 The <code>method_idx</code> of a virtual method must <i>not</i> be the same 2088 as any direct method. 2089 </td> 2090 </tr> 2091 </tbody> 2092 </table> 2093 2094 <p class="note"><strong>Note:</strong> All elements' <code>field_id</code>s and 2095 <code>method_id</code>s must refer to the same defining class.</p> 2096 2097 <h3 id="encoded-field-format">encoded_field format</h3> 2098 2099 <table class="format"> 2100 <thead> 2101 <tr> 2102 <th>Name</th> 2103 <th>Format</th> 2104 <th>Description</th> 2105 </tr> 2106 </thead> 2107 <tbody> 2108 <tr> 2109 <td>field_idx_diff</td> 2110 <td>uleb128</td> 2111 <td>index into the <code>field_ids</code> list for the identity of this 2112 field (includes the name and descriptor), represented as a difference 2113 from the index of previous element in the list. The index of the 2114 first element in a list is represented directly. 2115 </td> 2116 </tr> 2117 <tr> 2118 <td>access_flags</td> 2119 <td>uleb128</td> 2120 <td>access flags for the field (<code>public</code>, <code>final</code>, 2121 etc.). See "<code>access_flags</code> Definitions" for details. 2122 </td> 2123 </tr> 2124 </tbody> 2125 </table> 2126 2127 <h3 id="encoded-method">encoded_method format</h3> 2128 2129 <table class="format"> 2130 <thead> 2131 <tr> 2132 <th>Name</th> 2133 <th>Format</th> 2134 <th>Description</th> 2135 </tr> 2136 </thead> 2137 <tbody> 2138 <tr> 2139 <td>method_idx_diff</td> 2140 <td>uleb128</td> 2141 <td>index into the <code>method_ids</code> list for the identity of this 2142 method (includes the name and descriptor), represented as a difference 2143 from the index of previous element in the list. The index of the 2144 first element in a list is represented directly. 2145 </td> 2146 </tr> 2147 <tr> 2148 <td>access_flags</td> 2149 <td>uleb128</td> 2150 <td>access flags for the method (<code>public</code>, <code>final</code>, 2151 etc.). See "<code>access_flags</code> Definitions" for details. 2152 </td> 2153 </tr> 2154 <tr> 2155 <td>code_off</td> 2156 <td>uleb128</td> 2157 <td>offset from the start of the file to the code structure for this 2158 method, or <code>0</code> if this method is either <code>abstract</code> 2159 or <code>native</code>. The offset should be to a location in the 2160 <code>data</code> section. The format of the data is specified by 2161 "<code>code_item</code>" below. 2162 </td> 2163 </tr> 2164 </tbody> 2165 </table> 2166 2167 <h3 id="type-list">type_list</h3> 2168 <h4>referenced from class_def_item and proto_id_item</h4> 2169 <h4>appears in the data section</h4> 2170 <h4>alignment: 4 bytes</h4> 2171 2172 <table class="format"> 2173 <thead> 2174 <tr> 2175 <th>Name</th> 2176 <th>Format</th> 2177 <th>Description</th> 2178 </tr> 2179 </thead> 2180 <tbody> 2181 <tr> 2182 <td>size</td> 2183 <td>uint</td> 2184 <td>size of the list, in entries</td> 2185 </tr> 2186 <tr> 2187 <td>list</td> 2188 <td>type_item[size]</td> 2189 <td>elements of the list</td> 2190 </tr> 2191 </tbody> 2192 </table> 2193 2194 <h3 id="type-item-format">type_item format</h3> 2195 2196 <table class="format"> 2197 <thead> 2198 <tr> 2199 <th>Name</th> 2200 <th>Format</th> 2201 <th>Description</th> 2202 </tr> 2203 </thead> 2204 <tbody> 2205 <tr> 2206 <td>type_idx</td> 2207 <td>ushort</td> 2208 <td>index into the <code>type_ids</code> list</td> 2209 </tr> 2210 </tbody> 2211 </table> 2212 2213 <h3 id="code-item">code_item</h3> 2214 <h4>referenced from encoded_method</h4> 2215 <h4>appears in the data section</h4> 2216 <h4>alignment: 4 bytes</h4> 2217 2218 <table class="format"> 2219 <thead> 2220 <tr> 2221 <th>Name</th> 2222 <th>Format</th> 2223 <th>Description</th> 2224 </tr> 2225 </thead> 2226 <tbody> 2227 <tr> 2228 <td>registers_size</td> 2229 <td>ushort</td> 2230 <td>the number of registers used by this code</td> 2231 </tr> 2232 <tr> 2233 <td>ins_size</td> 2234 <td>ushort</td> 2235 <td>the number of words of incoming arguments to the method that this 2236 code is for</td> 2237 </tr> 2238 <tr> 2239 <td>outs_size</td> 2240 <td>ushort</td> 2241 <td>the number of words of outgoing argument space required by this 2242 code for method invocation 2243 </td> 2244 </tr> 2245 <tr> 2246 <td>tries_size</td> 2247 <td>ushort</td> 2248 <td>the number of <code>try_item</code>s for this instance. If non-zero, 2249 then these appear as the <code>tries</code> array just after the 2250 <code>insns</code> in this instance. 2251 </td> 2252 </tr> 2253 <tr> 2254 <td>debug_info_off</td> 2255 <td>uint</td> 2256 <td>offset from the start of the file to the debug info (line numbers + 2257 local variable info) sequence for this code, or <code>0</code> if 2258 there simply is no information. The offset, if non-zero, should be 2259 to a location in the <code>data</code> section. The format of 2260 the data is specified by "<code>debug_info_item</code>" below. 2261 </td> 2262 </tr> 2263 <tr> 2264 <td>insns_size</td> 2265 <td>uint</td> 2266 <td>size of the instructions list, in 16-bit code units</td> 2267 </tr> 2268 <tr> 2269 <td>insns</td> 2270 <td>ushort[insns_size]</td> 2271 <td>actual array of bytecode. The format of code in an <code>insns</code> 2272 array is specified by the companion document 2273 <a href="dalvik-bytecode.html">Dalvik bytecode</a>. Note 2274 that though this is defined as an array of <code>ushort</code>, there 2275 are some internal structures that prefer four-byte alignment. Also, 2276 if this happens to be in an endian-swapped file, then the swapping is 2277 <i>only</i> done on individual <code>ushort</code>s and not on the 2278 larger internal structures. 2279 </td> 2280 </tr> 2281 <tr> 2282 <td>padding</td> 2283 <td>ushort <i>(optional)</i> = 0</td> 2284 <td>two bytes of padding to make <code>tries</code> four-byte aligned. 2285 This element is only present if <code>tries_size</code> is non-zero 2286 and <code>insns_size</code> is odd. 2287 </td> 2288 </tr> 2289 <tr> 2290 <td>tries</td> 2291 <td>try_item[tries_size] <i>(optional)</i></td> 2292 <td>array indicating where in the code exceptions are caught and 2293 how to handle them. Elements of the array must be non-overlapping in 2294 range and in order from low to high address. This element is only 2295 present if <code>tries_size</code> is non-zero. 2296 </td> 2297 </tr> 2298 <tr> 2299 <td>handlers</td> 2300 <td>encoded_catch_handler_list <i>(optional)</i></td> 2301 <td>bytes representing a list of lists of catch types and associated 2302 handler addresses. Each <code>try_item</code> has a byte-wise offset 2303 into this structure. This element is only present if 2304 <code>tries_size</code> is non-zero. 2305 </td> 2306 </tr> 2307 </tbody> 2308 </table> 2309 2310 <h3 id="type-item">try_item format</h3> 2311 2312 <table class="format"> 2313 <thead> 2314 <tr> 2315 <th>Name</th> 2316 <th>Format</th> 2317 <th>Description</th> 2318 </tr> 2319 </thead> 2320 <tbody> 2321 <tr> 2322 <td>start_addr</td> 2323 <td>uint</td> 2324 <td>start address of the block of code covered by this entry. The address 2325 is a count of 16-bit code units to the start of the first covered 2326 instruction. 2327 </td> 2328 </tr> 2329 <tr> 2330 <td>insn_count</td> 2331 <td>ushort</td> 2332 <td>number of 16-bit code units covered by this entry. The last code 2333 unit covered (inclusive) is <code>start_addr + insn_count - 1</code>. 2334 </td> 2335 </tr> 2336 <tr> 2337 <td>handler_off</td> 2338 <td>ushort</td> 2339 <td>offset in bytes from the start of the associated 2340 <code>encoded_catch_hander_list</code> to the 2341 <code>encoded_catch_handler</code> for this entry. This must be an 2342 offset to the start of an <code>encoded_catch_handler</code>. 2343 </td> 2344 </tr> 2345 </tbody> 2346 </table> 2347 2348 <h3 id="encoded-catch-handlerlist">encoded_catch_handler_list format</h3> 2349 2350 <table class="format"> 2351 <thead> 2352 <tr> 2353 <th>Name</th> 2354 <th>Format</th> 2355 <th>Description</th> 2356 </tr> 2357 </thead> 2358 <tbody> 2359 <tr> 2360 <td>size</td> 2361 <td>uleb128</td> 2362 <td>size of this list, in entries</td> 2363 </tr> 2364 <tr> 2365 <td>list</td> 2366 <td>encoded_catch_handler[handlers_size]</td> 2367 <td>actual list of handler lists, represented directly (not as offsets), 2368 and concatenated sequentially</td> 2369 </tr> 2370 </tbody> 2371 </table> 2372 2373 <h3 id="encoded-catch-handler">encoded_catch_handler format</h3> 2374 2375 <table class="format"> 2376 <thead> 2377 <tr> 2378 <th>Name</th> 2379 <th>Format</th> 2380 <th>Description</th> 2381 </tr> 2382 </thead> 2383 <tbody> 2384 <tr> 2385 <td>size</td> 2386 <td>sleb128</td> 2387 <td>number of catch types in this list. If non-positive, then this is 2388 the negative of the number of catch types, and the catches are followed 2389 by a catch-all handler. For example: A <code>size</code> of <code>0</code> 2390 means that there is a catch-all but no explicitly typed catches. 2391 A <code>size</code> of <code>2</code> means that there are two explicitly 2392 typed catches and no catch-all. And a <code>size</code> of <code>-1</code> 2393 means that there is one typed catch along with a catch-all. 2394 </td> 2395 </tr> 2396 <tr> 2397 <td>handlers</td> 2398 <td>encoded_type_addr_pair[abs(size)]</td> 2399 <td>stream of <code>abs(size)</code> encoded items, one for each caught 2400 type, in the order that the types should be tested. 2401 </td> 2402 </tr> 2403 <tr> 2404 <td>catch_all_addr</td> 2405 <td>uleb128 <i>(optional)</i></td> 2406 <td>bytecode address of the catch-all handler. This element is only 2407 present if <code>size</code> is non-positive. 2408 </td> 2409 </tr> 2410 </tbody> 2411 </table> 2412 2413 <h3 id="encoded-type-addr-pair">encoded_type_addr_pair format</h3> 2414 2415 <table class="format"> 2416 <thead> 2417 <tr> 2418 <th>Name</th> 2419 <th>Format</th> 2420 <th>Description</th> 2421 </tr> 2422 </thead> 2423 <tbody> 2424 <tr> 2425 <td>type_idx</td> 2426 <td>uleb128</td> 2427 <td>index into the <code>type_ids</code> list for the type of the 2428 exception to catch 2429 </td> 2430 </tr> 2431 <tr> 2432 <td>addr</td> 2433 <td>uleb128</td> 2434 <td>bytecode address of the associated exception handler</td> 2435 </tr> 2436 </tbody> 2437 </table> 2438 2439 <h3 id="debug-info-item">debug_info_item</h3> 2440 <h4>referenced from code_item</h4> 2441 <h4>appears in the data section</h4> 2442 <h4>alignment: none (byte-aligned)</h4> 2443 2444 <p>Each <code>debug_info_item</code> defines a DWARF3-inspired byte-coded 2445 state machine that, when interpreted, emits the positions 2446 table and (potentially) the local variable information for a 2447 <code>code_item</code>. The sequence begins with a variable-length 2448 header (the length of which depends on the number of method 2449 parameters), is followed by the state machine bytecodes, and ends 2450 with an <code>DBG_END_SEQUENCE</code> byte.</p> 2451 2452 <p>The state machine consists of five registers. The 2453 <code>address</code> register represents the instruction offset in the 2454 associated <code>insns_item</code> in 16-bit code units. The 2455 <code>address</code> register starts at <code>0</code> at the beginning of each 2456 <code>debug_info</code> sequence and must only monotonically increase. 2457 The <code>line</code> register represents what source line number 2458 should be associated with the next positions table entry emitted by 2459 the state machine. It is initialized in the sequence header, and may 2460 change in positive or negative directions but must never be less than 2461 <code>1</code>. The <code>source_file</code> register represents the 2462 source file that the line number entries refer to. It is initialized to 2463 the value of <code>source_file_idx</code> in <code>class_def_item</code>. 2464 The other two variables, <code>prologue_end</code> and 2465 <code>epilogue_begin</code>, are boolean flags (initialized to 2466 <code>false</code>) that indicate whether the next position emitted 2467 should be considered a method prologue or epilogue. The state machine 2468 must also track the name and type of the last local variable live in 2469 each register for the <code>DBG_RESTART_LOCAL</code> code.</p> 2470 2471 <p>The header is as follows:</p> 2472 2473 <table class="format"> 2474 <thead> 2475 <tr> 2476 <th>Name</th> 2477 <th>Format</th> 2478 <th>Description</th> 2479 </tr> 2480 </thead> 2481 <tbody> 2482 <tr> 2483 <td>line_start</td> 2484 <td>uleb128</td> 2485 <td>the initial value for the state machine's <code>line</code> register. 2486 Does not represent an actual positions entry. 2487 </td> 2488 </tr> 2489 <tr> 2490 <td>parameters_size</td> 2491 <td>uleb128</td> 2492 <td>the number of parameter names that are encoded. There should be 2493 one per method parameter, excluding an instance method's <code>this</code>, 2494 if any. 2495 </td> 2496 </tr> 2497 <tr> 2498 <td>parameter_names</td> 2499 <td>uleb128p1[parameters_size]</td> 2500 <td>string index of the method parameter name. An encoded value of 2501 <code>NO_INDEX</code> indicates that no name 2502 is available for the associated parameter. The type descriptor 2503 and signature are implied from the method descriptor and signature. 2504 </td> 2505 </tr> 2506 </tbody> 2507 </table> 2508 2509 <p>The byte code values are as follows:</p> 2510 2511 <table class="debugByteCode"> 2512 <thead> 2513 <tr> 2514 <th>Name</th> 2515 <th>Value</th> 2516 <th>Format</th> 2517 <th>Arguments</th> 2518 <th>Description</th> 2519 </tr> 2520 </thead> 2521 <tbody> 2522 <tr> 2523 <td>DBG_END_SEQUENCE</td> 2524 <td>0x00</td> 2525 <td></td> 2526 <td><i>(none)</i></td> 2527 <td>terminates a debug info sequence for a <code>code_item</code></td> 2528 </tr> 2529 <tr> 2530 <td>DBG_ADVANCE_PC</td> 2531 <td>0x01</td> 2532 <td>uleb128 addr_diff</td> 2533 <td><code>addr_diff</code>: amount to add to address register</td> 2534 <td>advances the address register without emitting a positions entry</td> 2535 </tr> 2536 <tr> 2537 <td>DBG_ADVANCE_LINE</td> 2538 <td>0x02</td> 2539 <td>sleb128 line_diff</td> 2540 <td><code>line_diff</code>: amount to change line register by</td> 2541 <td>advances the line register without emitting a positions entry</td> 2542 </tr> 2543 <tr> 2544 <td>DBG_START_LOCAL</td> 2545 <td>0x03</td> 2546 <td>uleb128 register_num<br/> 2547 uleb128p1 name_idx<br/> 2548 uleb128p1 type_idx 2549 </td> 2550 <td><code>register_num</code>: register that will contain local<br/> 2551 <code>name_idx</code>: string index of the name<br/> 2552 <code>type_idx</code>: type index of the type 2553 </td> 2554 <td>introduces a local variable at the current address. Either 2555 <code>name_idx</code> or <code>type_idx</code> may be 2556 <code>NO_INDEX</code> to indicate that that value is unknown. 2557 </td> 2558 </tr> 2559 <tr> 2560 <td>DBG_START_LOCAL_EXTENDED</td> 2561 <td>0x04</td> 2562 <td>uleb128 register_num<br/> 2563 uleb128p1 name_idx<br/> 2564 uleb128p1 type_idx<br/> 2565 uleb128p1 sig_idx 2566 </td> 2567 <td><code>register_num</code>: register that will contain local<br/> 2568 <code>name_idx</code>: string index of the name<br/> 2569 <code>type_idx</code>: type index of the type<br/> 2570 <code>sig_idx</code>: string index of the type signature 2571 </td> 2572 <td>introduces a local with a type signature at the current address. 2573 Any of <code>name_idx</code>, <code>type_idx</code>, or 2574 <code>sig_idx</code> may be <code>NO_INDEX</code> 2575 to indicate that that value is unknown. (If <code>sig_idx</code> is 2576 <code>-1</code>, though, the same data could be represented more 2577 efficiently using the opcode <code>DBG_START_LOCAL</code>.) 2578 <p class="note"><strong>Note:</strong> See the discussion under 2579 "<code>dalvik.annotation.Signature</code>" below for caveats about 2580 handling signatures.</p> 2581 </td> 2582 </tr> 2583 <tr> 2584 <td>DBG_END_LOCAL</td> 2585 <td>0x05</td> 2586 <td>uleb128 register_num</td> 2587 <td><code>register_num</code>: register that contained local</td> 2588 <td>marks a currently-live local variable as out of scope at the current 2589 address 2590 </td> 2591 </tr> 2592 <tr> 2593 <td>DBG_RESTART_LOCAL</td> 2594 <td>0x06</td> 2595 <td>uleb128 register_num</td> 2596 <td><code>register_num</code>: register to restart</td> 2597 <td>re-introduces a local variable at the current address. The name 2598 and type are the same as the last local that was live in the specified 2599 register. 2600 </td> 2601 </tr> 2602 <tr> 2603 <td>DBG_SET_PROLOGUE_END</td> 2604 <td>0x07</td> 2605 <td></td> 2606 <td><i>(none)</i></td> 2607 <td>sets the <code>prologue_end</code> state machine register, 2608 indicating that the next position entry that is added should be 2609 considered the end of a method prologue (an appropriate place for 2610 a method breakpoint). The <code>prologue_end</code> register is 2611 cleared by any special (<code>>= 0x0a</code>) opcode. 2612 </td> 2613 </tr> 2614 <tr> 2615 <td>DBG_SET_EPILOGUE_BEGIN</td> 2616 <td>0x08</td> 2617 <td></td> 2618 <td><i>(none)</i></td> 2619 <td>sets the <code>epilogue_begin</code> state machine register, 2620 indicating that the next position entry that is added should be 2621 considered the beginning of a method epilogue (an appropriate place 2622 to suspend execution before method exit). 2623 The <code>epilogue_begin</code> register is cleared by any special 2624 (<code>>= 0x0a</code>) opcode. 2625 </td> 2626 </tr> 2627 <tr> 2628 <td>DBG_SET_FILE</td> 2629 <td>0x09</td> 2630 <td>uleb128p1 name_idx</td> 2631 <td><code>name_idx</code>: string index of source file name; 2632 <code>NO_INDEX</code> if unknown 2633 </td> 2634 <td>indicates that all subsequent line number entries make reference to this 2635 source file name, instead of the default name specified in 2636 <code>code_item</code> 2637 </td> 2638 </tr> 2639 <tr> 2640 <td><i>Special Opcodes</i></td> 2641 <!-- When updating the range below, make sure to search for other 2642 instances of 0x0a in this section. --> 2643 <td>0x0a…0xff</td> 2644 <td></td> 2645 <td><i>(none)</i></td> 2646 <td>advances the <code>line</code> and <code>address</code> registers, 2647 emits a position entry, and clears <code>prologue_end</code> and 2648 <code>epilogue_begin</code>. See below for description. 2649 </td> 2650 </tr> 2651 </tbody> 2652 </table> 2653 2654 <h3 id="opcodes">Special opcodes</h3> 2655 2656 <p>Opcodes with values between <code>0x0a</code> and <code>0xff</code> 2657 (inclusive) move both the <code>line</code> and <code>address</code> 2658 registers by a small amount and then emit a new position table entry. 2659 The formula for the increments are as follows:</p> 2660 2661 <pre class="devsite-click-to-copy"> 2662 DBG_FIRST_SPECIAL = 0x0a // the smallest special opcode 2663 DBG_LINE_BASE = -4 // the smallest line number increment 2664 DBG_LINE_RANGE = 15 // the number of line increments represented 2665 2666 adjusted_opcode = opcode - DBG_FIRST_SPECIAL 2667 2668 line += DBG_LINE_BASE + (adjusted_opcode % DBG_LINE_RANGE) 2669 address += (adjusted_opcode / DBG_LINE_RANGE) 2670 </pre> 2671 2672 <h3 id="annotations-directory">annotations_directory_item</h3> 2673 <h4>referenced from class_def_item</h4> 2674 <h4>appears in the data section</h4> 2675 <h4>alignment: 4 bytes</h4> 2676 2677 <table class="format"> 2678 <thead> 2679 <tr> 2680 <th>Name</th> 2681 <th>Format</th> 2682 <th>Description</th> 2683 </tr> 2684 </thead> 2685 <tbody> 2686 <tr> 2687 <td>class_annotations_off</td> 2688 <td>uint</td> 2689 <td>offset from the start of the file to the annotations made directly 2690 on the class, or <code>0</code> if the class has no direct annotations. 2691 The offset, if non-zero, should be to a location in the 2692 <code>data</code> section. The format of the data is specified 2693 by "<code>annotation_set_item</code>" below. 2694 </td> 2695 </tr> 2696 <tr> 2697 <td>fields_size</td> 2698 <td>uint</td> 2699 <td>count of fields annotated by this item</td> 2700 </tr> 2701 <tr> 2702 <td>annotated_methods_size</td> 2703 <td>uint</td> 2704 <td>count of methods annotated by this item</td> 2705 </tr> 2706 <tr> 2707 <td>annotated_parameters_size</td> 2708 <td>uint</td> 2709 <td>count of method parameter lists annotated by this item</td> 2710 </tr> 2711 <tr> 2712 <td>field_annotations</td> 2713 <td>field_annotation[fields_size] <i>(optional)</i></td> 2714 <td>list of associated field annotations. The elements of the list must 2715 be sorted in increasing order, by <code>field_idx</code>. 2716 </td> 2717 </tr> 2718 <tr> 2719 <td>method_annotations</td> 2720 <td>method_annotation[methods_size] <i>(optional)</i></td> 2721 <td>list of associated method annotations. The elements of the list must 2722 be sorted in increasing order, by <code>method_idx</code>. 2723 </td> 2724 </tr> 2725 <tr> 2726 <td>parameter_annotations</td> 2727 <td>parameter_annotation[parameters_size] <i>(optional)</i></td> 2728 <td>list of associated method parameter annotations. The elements of the 2729 list must be sorted in increasing order, by <code>method_idx</code>. 2730 </td> 2731 </tr> 2732 </tbody> 2733 </table> 2734 2735 <p class="note"><strong>Note:</strong> All elements' <code>field_id</code>s and 2736 <code>method_id</code>s must refer to the same defining class.</p> 2737 2738 <h3 id="field-annotation">field_annotation format</h3> 2739 2740 <table class="format"> 2741 <thead> 2742 <tr> 2743 <th>Name</th> 2744 <th>Format</th> 2745 <th>Description</th> 2746 </tr> 2747 </thead> 2748 <tbody> 2749 <tr> 2750 <td>field_idx</td> 2751 <td>uint</td> 2752 <td>index into the <code>field_ids</code> list for the identity of the 2753 field being annotated 2754 </td> 2755 </tr> 2756 <tr> 2757 <td>annotations_off</td> 2758 <td>uint</td> 2759 <td>offset from the start of the file to the list of annotations for 2760 the field. The offset should be to a location in the <code>data</code> 2761 section. The format of the data is specified by 2762 "<code>annotation_set_item</code>" below. 2763 </td> 2764 </tr> 2765 </tbody> 2766 </table> 2767 2768 <h3 id="method-annotation">method_annotation format</h3> 2769 2770 <table class="format"> 2771 <thead> 2772 <tr> 2773 <th>Name</th> 2774 <th>Format</th> 2775 <th>Description</th> 2776 </tr> 2777 </thead> 2778 <tbody> 2779 <tr> 2780 <td>method_idx</td> 2781 <td>uint</td> 2782 <td>index into the <code>method_ids</code> list for the identity of the 2783 method being annotated 2784 </td> 2785 </tr> 2786 <tr> 2787 <td>annotations_off</td> 2788 <td>uint</td> 2789 <td>offset from the start of the file to the list of annotations for 2790 the method. The offset should be to a location in the 2791 <code>data</code> section. The format of the data is specified by 2792 "<code>annotation_set_item</code>" below. 2793 </td> 2794 </tr> 2795 </tbody> 2796 </table> 2797 2798 <h3 id="parameter-annotation">parameter_annotation format</h3> 2799 2800 <table class="format"> 2801 <thead> 2802 <tr> 2803 <th>Name</th> 2804 <th>Format</th> 2805 <th>Description</th> 2806 </tr> 2807 </thead> 2808 <tbody> 2809 <tr> 2810 <td>method_idx</td> 2811 <td>uint</td> 2812 <td>index into the <code>method_ids</code> list for the identity of the 2813 method whose parameters are being annotated 2814 </td> 2815 </tr> 2816 <tr> 2817 <td>annotations_off</td> 2818 <td>uint</td> 2819 <td>offset from the start of the file to the list of annotations for 2820 the method parameters. The offset should be to a location in the 2821 <code>data</code> section. The format of the data is specified by 2822 "<code>annotation_set_ref_list</code>" below. 2823 </td> 2824 </tr> 2825 </tbody> 2826 </table> 2827 2828 <h3 id="set-ref-list">annotation_set_ref_list</h3> 2829 <h4>referenced from parameter_annotations_item</h4> 2830 <h4>appears in the data section</h4> 2831 <h4>alignment: 4 bytes</h4> 2832 2833 <table class="format"> 2834 <thead> 2835 <tr> 2836 <th>Name</th> 2837 <th>Format</th> 2838 <th>Description</th> 2839 </tr> 2840 </thead> 2841 <tbody> 2842 <tr> 2843 <td>size</td> 2844 <td>uint</td> 2845 <td>size of the list, in entries</td> 2846 </tr> 2847 <tr> 2848 <td>list</td> 2849 <td>annotation_set_ref_item[size]</td> 2850 <td>elements of the list</td> 2851 </tr> 2852 </tbody> 2853 </table> 2854 2855 <h3 id="set-ref-item">annotation_set_ref_item format</h3> 2856 2857 <table class="format"> 2858 <thead> 2859 <tr> 2860 <th>Name</th> 2861 <th>Format</th> 2862 <th>Description</th> 2863 </tr> 2864 </thead> 2865 <tbody> 2866 <tr> 2867 <td>annotations_off</td> 2868 <td>uint</td> 2869 <td>offset from the start of the file to the referenced annotation set 2870 or <code>0</code> if there are no annotations for this element. 2871 The offset, if non-zero, should be to a location in the <code>data</code> 2872 section. The format of the data is specified by 2873 "<code>annotation_set_item</code>" below. 2874 </td> 2875 </tr> 2876 </tbody> 2877 </table> 2878 2879 <h3 id="annotation-set-item">annotation_set_item</h3> 2880 <h4>referenced from annotations_directory_item, field_annotations_item, 2881 method_annotations_item, and annotation_set_ref_item</h4> 2882 <h4>appears in the data section</h4> 2883 <h4>alignment: 4 bytes</h4> 2884 2885 <table class="format"> 2886 <thead> 2887 <tr> 2888 <th>Name</th> 2889 <th>Format</th> 2890 <th>Description</th> 2891 </tr> 2892 </thead> 2893 <tbody> 2894 <tr> 2895 <td>size</td> 2896 <td>uint</td> 2897 <td>size of the set, in entries</td> 2898 </tr> 2899 <tr> 2900 <td>entries</td> 2901 <td>annotation_off_item[size]</td> 2902 <td>elements of the set. The elements must be sorted in increasing order, 2903 by <code>type_idx</code>. 2904 </td> 2905 </tr> 2906 </tbody> 2907 </table> 2908 2909 <h3 id="off-item">annotation_off_item format</h3> 2910 2911 <table class="format"> 2912 <thead> 2913 <tr> 2914 <th>Name</th> 2915 <th>Format</th> 2916 <th>Description</th> 2917 </tr> 2918 </thead> 2919 <tbody> 2920 <tr> 2921 <td>annotation_off</td> 2922 <td>uint</td> 2923 <td>offset from the start of the file to an annotation. 2924 The offset should be to a location in the <code>data</code> section, 2925 and the format of the data at that location is specified by 2926 "<code>annotation_item</code>" below. 2927 </td> 2928 </tr> 2929 </tbody> 2930 </table> 2931 2932 2933 <h3 id="annotation-item">annotation_item</h3> 2934 <h4>referenced from annotation_set_item</h4> 2935 <h4>appears in the data section</h4> 2936 <h4>alignment: none (byte-aligned)</h4> 2937 2938 <table class="format"> 2939 <thead> 2940 <tr> 2941 <th>Name</th> 2942 <th>Format</th> 2943 <th>Description</th> 2944 </tr> 2945 </thead> 2946 <tbody> 2947 <tr> 2948 <td>visibility</td> 2949 <td>ubyte</td> 2950 <td>intended visibility of this annotation (see below)</td> 2951 </tr> 2952 <tr> 2953 <td>annotation</td> 2954 <td>encoded_annotation</td> 2955 <td>encoded annotation contents, in the format described by 2956 "<code>encoded_annotation</code> format" under 2957 "<code>encoded_value</code> encoding" above. 2958 </td> 2959 </tr> 2960 </tbody> 2961 </table> 2962 2963 <h3 id="visibility">Visibility values</h3> 2964 2965 <p>These are the options for the <code>visibility</code> field in an 2966 <code>annotation_item</code>:</p> 2967 2968 <table class="format"> 2969 <thead> 2970 <tr> 2971 <th>Name</th> 2972 <th>Value</th> 2973 <th>Description</th> 2974 </tr> 2975 </thead> 2976 <tbody> 2977 <tr> 2978 <td>VISIBILITY_BUILD</td> 2979 <td>0x00</td> 2980 <td>intended only to be visible at build time (e.g., during compilation 2981 of other code) 2982 </td> 2983 </tr> 2984 <tr> 2985 <td>VISIBILITY_RUNTIME</td> 2986 <td>0x01</td> 2987 <td>intended to visible at runtime</td> 2988 </tr> 2989 <tr> 2990 <td>VISIBILITY_SYSTEM</td> 2991 <td>0x02</td> 2992 <td>intended to visible at runtime, but only to the underlying system 2993 (and not to regular user code) 2994 </td> 2995 </tr> 2996 </tbody> 2997 </table> 2998 2999 <h3 id="encoded-array-item">encoded_array_item</h3> 3000 <h4>referenced from class_def_item</h4> 3001 <h4>appears in the data section</h4> 3002 <h4>alignment: none (byte-aligned)</h4> 3003 3004 <table class="format"> 3005 <thead> 3006 <tr> 3007 <th>Name</th> 3008 <th>Format</th> 3009 <th>Description</th> 3010 </tr> 3011 </thead> 3012 <tbody> 3013 <tr> 3014 <td>value</td> 3015 <td>encoded_array</td> 3016 <td>bytes representing the encoded array value, in the format specified 3017 by "<code>encoded_array</code> Format" under "<code>encoded_value</code> 3018 Encoding" above. 3019 </td> 3020 </tr> 3021 </tbody> 3022 </table> 3023 3024 <h2 id="system-annotation">System annotations</h2> 3025 3026 <p>System annotations are used to represent various pieces of reflective 3027 information about classes (and methods and fields). This information is 3028 generally only accessed indirectly by client (non-system) code.</p> 3029 3030 <p>System annotations are represented in <code>.dex</code> files as 3031 annotations with visibility set to <code>VISIBILITY_SYSTEM</code>. 3032 3033 <h3 id="dalvik-annotation-default">dalvik.annotation.AnnotationDefault</h3> 3034 <h4>appears on methods in annotation interfaces</h4> 3035 3036 <p>An <code>AnnotationDefault</code> annotation is attached to each 3037 annotation interface which wishes to indicate default bindings.</p> 3038 3039 <table class="format"> 3040 <thead> 3041 <tr> 3042 <th>Name</th> 3043 <th>Format</th> 3044 <th>Description</th> 3045 </tr> 3046 </thead> 3047 <tbody> 3048 <tr> 3049 <td>value</td> 3050 <td>Annotation</td> 3051 <td>the default bindings for this annotation, represented as an annotation 3052 of this type. The annotation need not include all names defined by the 3053 annotation; missing names simply do not have defaults. 3054 </td> 3055 </tr> 3056 </tbody> 3057 </table> 3058 3059 <h3 id="dalvik-enclosingclass">dalvik.annotation.EnclosingClass</h3> 3060 <h4>appears on classes</h4> 3061 3062 <p>An <code>EnclosingClass</code> annotation is attached to each class 3063 which is either defined as a member of another class, per se, or is 3064 anonymous but not defined within a method body (e.g., a synthetic 3065 inner class). Every class that has this annotation must also have an 3066 <code>InnerClass</code> annotation. Additionally, a class must not have 3067 both an <code>EnclosingClass</code> and an 3068 <code>EnclosingMethod</code> annotation.</p> 3069 3070 <table class="format"> 3071 <thead> 3072 <tr> 3073 <th>Name</th> 3074 <th>Format</th> 3075 <th>Description</th> 3076 </tr> 3077 </thead> 3078 <tbody> 3079 <tr> 3080 <td>value</td> 3081 <td>Class</td> 3082 <td>the class which most closely lexically scopes this class</td> 3083 </tr> 3084 </tbody> 3085 </table> 3086 3087 <h3 id="dalvik-enclosingmethod">dalvik.annotation.EnclosingMethod</h3> 3088 <h4>appears on classes</h4> 3089 3090 <p>An <code>EnclosingMethod</code> annotation is attached to each class 3091 which is defined inside a method body. Every class that has this 3092 annotation must also have an <code>InnerClass</code> annotation. 3093 Additionally, a class must not have both an <code>EnclosingClass</code> 3094 and an <code>EnclosingMethod</code> annotation.</p> 3095 3096 <table class="format"> 3097 <thead> 3098 <tr> 3099 <th>Name</th> 3100 <th>Format</th> 3101 <th>Description</th> 3102 </tr> 3103 </thead> 3104 <tbody> 3105 <tr> 3106 <td>value</td> 3107 <td>Method</td> 3108 <td>the method which most closely lexically scopes this class</td> 3109 </tr> 3110 </tbody> 3111 </table> 3112 3113 <h3 id="dalvik-innerclass">dalvik.annotation.InnerClass</h3> 3114 <h4>appears on classes</h4> 3115 3116 <p>An <code>InnerClass</code> annotation is attached to each class 3117 which is defined in the lexical scope of another class's definition. 3118 Any class which has this annotation must also have <i>either</i> an 3119 <code>EnclosingClass</code> annotation <i>or</i> an 3120 <code>EnclosingMethod</code> annotation.</p> 3121 3122 <table class="format"> 3123 <thead> 3124 <tr> 3125 <th>Name</th> 3126 <th>Format</th> 3127 <th>Description</th> 3128 </tr> 3129 </thead> 3130 <tbody> 3131 <tr> 3132 <td>name</td> 3133 <td>String</td> 3134 <td>the originally declared simple name of this class (not including any 3135 package prefix). If this class is anonymous, then the name is 3136 <code>null</code>. 3137 </td> 3138 </tr> 3139 <tr> 3140 <td>accessFlags</td> 3141 <td>int</td> 3142 <td>the originally declared access flags of the class (which may differ 3143 from the effective flags because of a mismatch between the execution 3144 models of the source language and target virtual machine) 3145 </td> 3146 </tr> 3147 </tbody> 3148 </table> 3149 3150 <h3 id="dalvik-memberclasses">dalvik.annotation.MemberClasses</h3> 3151 <h4>appears on classes</h4> 3152 3153 <p>A <code>MemberClasses</code> annotation is attached to each class 3154 which declares member classes. (A member class is a direct inner class 3155 that has a name.)</p> 3156 3157 <table class="format"> 3158 <thead> 3159 <tr> 3160 <th>Name</th> 3161 <th>Format</th> 3162 <th>Description</th> 3163 </tr> 3164 </thead> 3165 <tbody> 3166 <tr> 3167 <td>value</td> 3168 <td>Class[]</td> 3169 <td>array of the member classes</td> 3170 </tr> 3171 </tbody> 3172 </table> 3173 3174 <h3 id="dalvik-annotation-method-parameters">dalvik.annotation.MethodParameters</h3> 3175 <h4>appears on methods</h4> 3176 3177 <p class="note"><strong>Note:</strong> This annotation was added after Android 3178 7.1. Its presence on earlier Android releases will be ignored.</p> 3179 3180 <p>A <code>MethodParameters</code> annotation is optional and can be used to 3181 provide parameter metadata such as parameter names and modifiers.</p> 3182 3183 <p>The annotation can be omitted from a method or constructor safely when the 3184 parameter metadata is not required at runtime. 3185 <code>java.lang.reflect.Parameter.isNamePresent()</code> can be used to check 3186 whether metadata is present for a parameter, and the associated reflection 3187 methods such as <code>java.lang.reflect.Parameter.getName()</code> will fall 3188 back to default behavior at runtime if the information is not present.</p> 3189 3190 <p>When including parameter metadata, compilers must include information 3191 for generated classes such as enums, since the parameter metadata 3192 includes whether or not a parameter is synthetic or mandated.</p> 3193 3194 <p>A <code>MethodParameters</code> annotation describes only individual method 3195 parameters. Therefore, compilers may omit the annotation entirely 3196 for constructors and methods that have no parameters, for the sake of code-size 3197 and runtime efficiency.</p> 3198 3199 <p>The arrays documented below must be the same size as for the 3200 <code>method_id_item</code> dex structure associated with the method, otherwise 3201 a <code>java.lang.reflect.MalformedParametersException</code> will be thrown at 3202 runtime.</p> 3203 3204 <p>That is: <code>method_id_item.proto_idx</code> -> 3205 <code>proto_id_item.parameters_off</code> -> 3206 <code>type_list.size</code> must be the same as <code>names().length</code> and 3207 <code>accessFlags().length</code>.</p> 3208 3209 <p>Because <code>MethodParameters</code> describes all formal method 3210 parameters, even those not explicitly or implicitly declared in source code, 3211 the size of the arrays may differ from the Signature or other metadata 3212 information that is based only on explicit parameters declared in source 3213 code. <code>MethodParameters</code> will also not include any information about 3214 type annotation receiver parameters that do not exist in the actual method 3215 signature.</p> 3216 3217 <table class="format"> 3218 <thead> 3219 <tr> 3220 <th>Name</th> 3221 <th>Format</th> 3222 <th>Description</th> 3223 </tr> 3224 </thead> 3225 <tbody> 3226 <tr> 3227 <td>names</td> 3228 <td>String[]</td> 3229 <td>The names of formal parameters for the associated method. The array 3230 must not be null but must be empty if there are no formal parameters. A value in 3231 the array must be null if the formal parameter with that index has no name.<br> 3232 If parameter name strings are empty or contain '.', ';', '[' or '/' then a 3233 <code>java.lang.reflect.MalformedParametersException</code> will be thrown at 3234 runtime. 3235 </td> 3236 </tr> 3237 <tr> 3238 <td>accessFlags</td> 3239 <td>int[]</td> 3240 <td>The access flags of the formal parameters for the associated method. The 3241 array must not be null but must be empty if there are no formal parameters.<br> 3242 3243 The value is a bit mask with the following values:<br> 3244 <ul> 3245 <li>0x0010 : final, the parameter was declared final</li> 3246 <li>0x1000 : synthetic, the parameter was introduced by the compiler</li> 3247 <li>0x8000 : mandated, the parameter is synthetic but also implied by the language 3248 specification</li> 3249 </ul> 3250 3251 If any bits are set outside of this set then a 3252 <code>java.lang.reflect.MalformedParametersException</code> will be thrown at runtime. 3253 </td> 3254 </tr> 3255 </tbody> 3256 </table> 3257 3258 <h3 id="dalvik-signature">dalvik.annotation.Signature</h3> 3259 <h4>appears on classes, fields, and methods</h4> 3260 3261 <p>A <code>Signature</code> annotation is attached to each class, 3262 field, or method which is defined in terms of a more complicated type 3263 than is representable by a <code>type_id_item</code>. The 3264 <code>.dex</code> format does not define the format for signatures; it 3265 is merely meant to be able to represent whatever signatures a source 3266 language requires for successful implementation of that language's 3267 semantics. As such, signatures are not generally parsed (or verified) 3268 by virtual machine implementations. The signatures simply get handed 3269 off to higher-level APIs and tools (such as debuggers). Any use of a 3270 signature, therefore, should be written so as not to make any 3271 assumptions about only receiving valid signatures, explicitly guarding 3272 itself against the possibility of coming across a syntactically 3273 invalid signature.</p> 3274 3275 <p>Because signature strings tend to have a lot of duplicated content, 3276 a <code>Signature</code> annotation is defined as an <i>array</i> of 3277 strings, where duplicated elements naturally refer to the same 3278 underlying data, and the signature is taken to be the concatenation of 3279 all the strings in the array. There are no rules about how to pull 3280 apart a signature into separate strings; that is entirely up to the 3281 tools that generate <code>.dex</code> files.</p> 3282 3283 <table class="format"> 3284 <thead> 3285 <tr> 3286 <th>Name</th> 3287 <th>Format</th> 3288 <th>Description</th> 3289 </tr> 3290 </thead> 3291 <tbody> 3292 <tr> 3293 <td>value</td> 3294 <td>String[]</td> 3295 <td>the signature of this class or member, as an array of strings that 3296 is to be concatenated together</td> 3297 </tr> 3298 </tbody> 3299 </table> 3300 3301 <h3 id="dalvik-throws">dalvik.annotation.Throws</h3> 3302 <h4>appears on methods</h4> 3303 3304 <p>A <code>Throws</code> annotation is attached to each method which is 3305 declared to throw one or more exception types.</p> 3306 3307 <table class="format"> 3308 <thead> 3309 <tr> 3310 <th>Name</th> 3311 <th>Format</th> 3312 <th>Description</th> 3313 </tr> 3314 </thead> 3315 <tbody> 3316 <tr> 3317 <td>value</td> 3318 <td>Class[]</td> 3319 <td>the array of exception types thrown</td> 3320 </tr> 3321 </tbody> 3322 </table> 3323 3324 </body> 3325 </html> 3326
