1This is gcj.info, produced by makeinfo version 5.2 from gcj.texi. 2 3Copyright (C) 2001-2014 Free Software Foundation, Inc. 4 5 Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with no 8Invariant Sections, the Front-Cover Texts being (a) (see below), and 9with the Back-Cover Texts being (b) (see below). A copy of the license 10is included in the section entitled "GNU Free Documentation License". 11 12 (a) The FSF's Front-Cover Text is: 13 14 A GNU Manual 15 16 (b) The FSF's Back-Cover Text is: 17 18 You have freedom to copy and modify this GNU Manual, like GNU 19software. Copies published by the Free Software Foundation raise funds 20for GNU development. 21INFO-DIR-SECTION Software development 22START-INFO-DIR-ENTRY 23* Gcj: (gcj). Ahead-of-time compiler for the Java language 24END-INFO-DIR-ENTRY 25 26INFO-DIR-SECTION Individual utilities 27START-INFO-DIR-ENTRY 28* jcf-dump: (gcj)Invoking jcf-dump. 29 Print information about Java class files 30* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode 31* gcj-dbtool: (gcj)Invoking gcj-dbtool. 32 Tool for manipulating class file databases. 33* jv-convert: (gcj)Invoking jv-convert. 34 Convert file from one encoding to another 35* grmic: (gcj)Invoking grmic. 36 Generate stubs for Remote Method Invocation. 37* gc-analyze: (gcj)Invoking gc-analyze. 38 Analyze Garbage Collector (GC) memory dumps. 39* aot-compile: (gcj)Invoking aot-compile. 40 Compile bytecode to native and generate databases. 41* rebuild-gcj-db: (gcj)Invoking rebuild-gcj-db. 42 Merge the per-solib databases made by aot-compile 43 into one system-wide database. 44END-INFO-DIR-ENTRY 45 46 47 48 Copyright (C) 2001-2014 Free Software Foundation, Inc. 49 50 Permission is granted to copy, distribute and/or modify this document 51under the terms of the GNU Free Documentation License, Version 1.3 or 52any later version published by the Free Software Foundation; with no 53Invariant Sections, the Front-Cover Texts being (a) (see below), and 54with the Back-Cover Texts being (b) (see below). A copy of the license 55is included in the section entitled "GNU Free Documentation License". 56 57 (a) The FSF's Front-Cover Text is: 58 59 A GNU Manual 60 61 (b) The FSF's Back-Cover Text is: 62 63 You have freedom to copy and modify this GNU Manual, like GNU 64software. Copies published by the Free Software Foundation raise funds 65for GNU development. 66 67 68File: gcj.info, Node: Top, Next: Copying, Up: (dir) 69 70Introduction 71************ 72 73This manual describes how to use 'gcj', the GNU compiler for the Java 74programming language. 'gcj' can generate both '.class' files and object 75files, and it can read both Java source code and '.class' files. 76 77* Menu: 78 79* Copying:: The GNU General Public License 80* GNU Free Documentation License:: 81 How you can share and copy this manual 82* Invoking gcj:: Compiler options supported by 'gcj' 83* Compatibility:: Compatibility between gcj and other tools for Java 84* Invoking jcf-dump:: Print information about class files 85* Invoking gij:: Interpreting Java bytecodes 86* Invoking gcj-dbtool:: Tool for manipulating class file databases. 87* Invoking jv-convert:: Converting from one encoding to another 88* Invoking grmic:: Generate stubs for Remote Method Invocation. 89* Invoking gc-analyze:: Analyze Garbage Collector (GC) memory dumps. 90* Invoking aot-compile:: Compile bytecode to native and generate databases. 91* Invoking rebuild-gcj-db:: Merge the per-solib databases made by aot-compile 92 into one system-wide database. 93* About CNI:: Description of the Compiled Native Interface 94* System properties:: Modifying runtime behavior of the libgcj library 95* Resources:: Where to look for more information 96* Index:: Index. 97 98 99File: gcj.info, Node: Copying, Next: GNU Free Documentation License, Prev: Top, Up: Top 100 101GNU General Public License 102************************** 103 104 Version 3, 29 June 2007 105 106 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> 107 108 Everyone is permitted to copy and distribute verbatim copies of this 109 license document, but changing it is not allowed. 110 111Preamble 112======== 113 114The GNU General Public License is a free, copyleft license for software 115and other kinds of works. 116 117 The licenses for most software and other practical works are designed 118to take away your freedom to share and change the works. By contrast, 119the GNU General Public License is intended to guarantee your freedom to 120share and change all versions of a program-to make sure it remains free 121software for all its users. We, the Free Software Foundation, use the 122GNU General Public License for most of our software; it applies also to 123any other work released this way by its authors. You can apply it to 124your programs, too. 125 126 When we speak of free software, we are referring to freedom, not 127price. Our General Public Licenses are designed to make sure that you 128have the freedom to distribute copies of free software (and charge for 129them if you wish), that you receive source code or can get it if you 130want it, that you can change the software or use pieces of it in new 131free programs, and that you know you can do these things. 132 133 To protect your rights, we need to prevent others from denying you 134these rights or asking you to surrender the rights. Therefore, you have 135certain responsibilities if you distribute copies of the software, or if 136you modify it: responsibilities to respect the freedom of others. 137 138 For example, if you distribute copies of such a program, whether 139gratis or for a fee, you must pass on to the recipients the same 140freedoms that you received. You must make sure that they, too, receive 141or can get the source code. And you must show them these terms so they 142know their rights. 143 144 Developers that use the GNU GPL protect your rights with two steps: 145(1) assert copyright on the software, and (2) offer you this License 146giving you legal permission to copy, distribute and/or modify it. 147 148 For the developers' and authors' protection, the GPL clearly explains 149that there is no warranty for this free software. For both users' and 150authors' sake, the GPL requires that modified versions be marked as 151changed, so that their problems will not be attributed erroneously to 152authors of previous versions. 153 154 Some devices are designed to deny users access to install or run 155modified versions of the software inside them, although the manufacturer 156can do so. This is fundamentally incompatible with the aim of 157protecting users' freedom to change the software. The systematic 158pattern of such abuse occurs in the area of products for individuals to 159use, which is precisely where it is most unacceptable. Therefore, we 160have designed this version of the GPL to prohibit the practice for those 161products. If such problems arise substantially in other domains, we 162stand ready to extend this provision to those domains in future versions 163of the GPL, as needed to protect the freedom of users. 164 165 Finally, every program is threatened constantly by software patents. 166States should not allow patents to restrict development and use of 167software on general-purpose computers, but in those that do, we wish to 168avoid the special danger that patents applied to a free program could 169make it effectively proprietary. To prevent this, the GPL assures that 170patents cannot be used to render the program non-free. 171 172 The precise terms and conditions for copying, distribution and 173modification follow. 174 175TERMS AND CONDITIONS 176==================== 177 178 0. Definitions. 179 180 "This License" refers to version 3 of the GNU General Public 181 License. 182 183 "Copyright" also means copyright-like laws that apply to other 184 kinds of works, such as semiconductor masks. 185 186 "The Program" refers to any copyrightable work licensed under this 187 License. Each licensee is addressed as "you". "Licensees" and 188 "recipients" may be individuals or organizations. 189 190 To "modify" a work means to copy from or adapt all or part of the 191 work in a fashion requiring copyright permission, other than the 192 making of an exact copy. The resulting work is called a "modified 193 version" of the earlier work or a work "based on" the earlier work. 194 195 A "covered work" means either the unmodified Program or a work 196 based on the Program. 197 198 To "propagate" a work means to do anything with it that, without 199 permission, would make you directly or secondarily liable for 200 infringement under applicable copyright law, except executing it on 201 a computer or modifying a private copy. Propagation includes 202 copying, distribution (with or without modification), making 203 available to the public, and in some countries other activities as 204 well. 205 206 To "convey" a work means any kind of propagation that enables other 207 parties to make or receive copies. Mere interaction with a user 208 through a computer network, with no transfer of a copy, is not 209 conveying. 210 211 An interactive user interface displays "Appropriate Legal Notices" 212 to the extent that it includes a convenient and prominently visible 213 feature that (1) displays an appropriate copyright notice, and (2) 214 tells the user that there is no warranty for the work (except to 215 the extent that warranties are provided), that licensees may convey 216 the work under this License, and how to view a copy of this 217 License. If the interface presents a list of user commands or 218 options, such as a menu, a prominent item in the list meets this 219 criterion. 220 221 1. Source Code. 222 223 The "source code" for a work means the preferred form of the work 224 for making modifications to it. "Object code" means any non-source 225 form of a work. 226 227 A "Standard Interface" means an interface that either is an 228 official standard defined by a recognized standards body, or, in 229 the case of interfaces specified for a particular programming 230 language, one that is widely used among developers working in that 231 language. 232 233 The "System Libraries" of an executable work include anything, 234 other than the work as a whole, that (a) is included in the normal 235 form of packaging a Major Component, but which is not part of that 236 Major Component, and (b) serves only to enable use of the work with 237 that Major Component, or to implement a Standard Interface for 238 which an implementation is available to the public in source code 239 form. A "Major Component", in this context, means a major 240 essential component (kernel, window system, and so on) of the 241 specific operating system (if any) on which the executable work 242 runs, or a compiler used to produce the work, or an object code 243 interpreter used to run it. 244 245 The "Corresponding Source" for a work in object code form means all 246 the source code needed to generate, install, and (for an executable 247 work) run the object code and to modify the work, including scripts 248 to control those activities. However, it does not include the 249 work's System Libraries, or general-purpose tools or generally 250 available free programs which are used unmodified in performing 251 those activities but which are not part of the work. For example, 252 Corresponding Source includes interface definition files associated 253 with source files for the work, and the source code for shared 254 libraries and dynamically linked subprograms that the work is 255 specifically designed to require, such as by intimate data 256 communication or control flow between those subprograms and other 257 parts of the work. 258 259 The Corresponding Source need not include anything that users can 260 regenerate automatically from other parts of the Corresponding 261 Source. 262 263 The Corresponding Source for a work in source code form is that 264 same work. 265 266 2. Basic Permissions. 267 268 All rights granted under this License are granted for the term of 269 copyright on the Program, and are irrevocable provided the stated 270 conditions are met. This License explicitly affirms your unlimited 271 permission to run the unmodified Program. The output from running 272 a covered work is covered by this License only if the output, given 273 its content, constitutes a covered work. This License acknowledges 274 your rights of fair use or other equivalent, as provided by 275 copyright law. 276 277 You may make, run and propagate covered works that you do not 278 convey, without conditions so long as your license otherwise 279 remains in force. You may convey covered works to others for the 280 sole purpose of having them make modifications exclusively for you, 281 or provide you with facilities for running those works, provided 282 that you comply with the terms of this License in conveying all 283 material for which you do not control copyright. Those thus making 284 or running the covered works for you must do so exclusively on your 285 behalf, under your direction and control, on terms that prohibit 286 them from making any copies of your copyrighted material outside 287 their relationship with you. 288 289 Conveying under any other circumstances is permitted solely under 290 the conditions stated below. Sublicensing is not allowed; section 291 10 makes it unnecessary. 292 293 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 294 295 No covered work shall be deemed part of an effective technological 296 measure under any applicable law fulfilling obligations under 297 article 11 of the WIPO copyright treaty adopted on 20 December 298 1996, or similar laws prohibiting or restricting circumvention of 299 such measures. 300 301 When you convey a covered work, you waive any legal power to forbid 302 circumvention of technological measures to the extent such 303 circumvention is effected by exercising rights under this License 304 with respect to the covered work, and you disclaim any intention to 305 limit operation or modification of the work as a means of 306 enforcing, against the work's users, your or third parties' legal 307 rights to forbid circumvention of technological measures. 308 309 4. Conveying Verbatim Copies. 310 311 You may convey verbatim copies of the Program's source code as you 312 receive it, in any medium, provided that you conspicuously and 313 appropriately publish on each copy an appropriate copyright notice; 314 keep intact all notices stating that this License and any 315 non-permissive terms added in accord with section 7 apply to the 316 code; keep intact all notices of the absence of any warranty; and 317 give all recipients a copy of this License along with the Program. 318 319 You may charge any price or no price for each copy that you convey, 320 and you may offer support or warranty protection for a fee. 321 322 5. Conveying Modified Source Versions. 323 324 You may convey a work based on the Program, or the modifications to 325 produce it from the Program, in the form of source code under the 326 terms of section 4, provided that you also meet all of these 327 conditions: 328 329 a. The work must carry prominent notices stating that you 330 modified it, and giving a relevant date. 331 332 b. The work must carry prominent notices stating that it is 333 released under this License and any conditions added under 334 section 7. This requirement modifies the requirement in 335 section 4 to "keep intact all notices". 336 337 c. You must license the entire work, as a whole, under this 338 License to anyone who comes into possession of a copy. This 339 License will therefore apply, along with any applicable 340 section 7 additional terms, to the whole of the work, and all 341 its parts, regardless of how they are packaged. This License 342 gives no permission to license the work in any other way, but 343 it does not invalidate such permission if you have separately 344 received it. 345 346 d. If the work has interactive user interfaces, each must display 347 Appropriate Legal Notices; however, if the Program has 348 interactive interfaces that do not display Appropriate Legal 349 Notices, your work need not make them do so. 350 351 A compilation of a covered work with other separate and independent 352 works, which are not by their nature extensions of the covered 353 work, and which are not combined with it such as to form a larger 354 program, in or on a volume of a storage or distribution medium, is 355 called an "aggregate" if the compilation and its resulting 356 copyright are not used to limit the access or legal rights of the 357 compilation's users beyond what the individual works permit. 358 Inclusion of a covered work in an aggregate does not cause this 359 License to apply to the other parts of the aggregate. 360 361 6. Conveying Non-Source Forms. 362 363 You may convey a covered work in object code form under the terms 364 of sections 4 and 5, provided that you also convey the 365 machine-readable Corresponding Source under the terms of this 366 License, in one of these ways: 367 368 a. Convey the object code in, or embodied in, a physical product 369 (including a physical distribution medium), accompanied by the 370 Corresponding Source fixed on a durable physical medium 371 customarily used for software interchange. 372 373 b. Convey the object code in, or embodied in, a physical product 374 (including a physical distribution medium), accompanied by a 375 written offer, valid for at least three years and valid for as 376 long as you offer spare parts or customer support for that 377 product model, to give anyone who possesses the object code 378 either (1) a copy of the Corresponding Source for all the 379 software in the product that is covered by this License, on a 380 durable physical medium customarily used for software 381 interchange, for a price no more than your reasonable cost of 382 physically performing this conveying of source, or (2) access 383 to copy the Corresponding Source from a network server at no 384 charge. 385 386 c. Convey individual copies of the object code with a copy of the 387 written offer to provide the Corresponding Source. This 388 alternative is allowed only occasionally and noncommercially, 389 and only if you received the object code with such an offer, 390 in accord with subsection 6b. 391 392 d. Convey the object code by offering access from a designated 393 place (gratis or for a charge), and offer equivalent access to 394 the Corresponding Source in the same way through the same 395 place at no further charge. You need not require recipients 396 to copy the Corresponding Source along with the object code. 397 If the place to copy the object code is a network server, the 398 Corresponding Source may be on a different server (operated by 399 you or a third party) that supports equivalent copying 400 facilities, provided you maintain clear directions next to the 401 object code saying where to find the Corresponding Source. 402 Regardless of what server hosts the Corresponding Source, you 403 remain obligated to ensure that it is available for as long as 404 needed to satisfy these requirements. 405 406 e. Convey the object code using peer-to-peer transmission, 407 provided you inform other peers where the object code and 408 Corresponding Source of the work are being offered to the 409 general public at no charge under subsection 6d. 410 411 A separable portion of the object code, whose source code is 412 excluded from the Corresponding Source as a System Library, need 413 not be included in conveying the object code work. 414 415 A "User Product" is either (1) a "consumer product", which means 416 any tangible personal property which is normally used for personal, 417 family, or household purposes, or (2) anything designed or sold for 418 incorporation into a dwelling. In determining whether a product is 419 a consumer product, doubtful cases shall be resolved in favor of 420 coverage. For a particular product received by a particular user, 421 "normally used" refers to a typical or common use of that class of 422 product, regardless of the status of the particular user or of the 423 way in which the particular user actually uses, or expects or is 424 expected to use, the product. A product is a consumer product 425 regardless of whether the product has substantial commercial, 426 industrial or non-consumer uses, unless such uses represent the 427 only significant mode of use of the product. 428 429 "Installation Information" for a User Product means any methods, 430 procedures, authorization keys, or other information required to 431 install and execute modified versions of a covered work in that 432 User Product from a modified version of its Corresponding Source. 433 The information must suffice to ensure that the continued 434 functioning of the modified object code is in no case prevented or 435 interfered with solely because modification has been made. 436 437 If you convey an object code work under this section in, or with, 438 or specifically for use in, a User Product, and the conveying 439 occurs as part of a transaction in which the right of possession 440 and use of the User Product is transferred to the recipient in 441 perpetuity or for a fixed term (regardless of how the transaction 442 is characterized), the Corresponding Source conveyed under this 443 section must be accompanied by the Installation Information. But 444 this requirement does not apply if neither you nor any third party 445 retains the ability to install modified object code on the User 446 Product (for example, the work has been installed in ROM). 447 448 The requirement to provide Installation Information does not 449 include a requirement to continue to provide support service, 450 warranty, or updates for a work that has been modified or installed 451 by the recipient, or for the User Product in which it has been 452 modified or installed. Access to a network may be denied when the 453 modification itself materially and adversely affects the operation 454 of the network or violates the rules and protocols for 455 communication across the network. 456 457 Corresponding Source conveyed, and Installation Information 458 provided, in accord with this section must be in a format that is 459 publicly documented (and with an implementation available to the 460 public in source code form), and must require no special password 461 or key for unpacking, reading or copying. 462 463 7. Additional Terms. 464 465 "Additional permissions" are terms that supplement the terms of 466 this License by making exceptions from one or more of its 467 conditions. Additional permissions that are applicable to the 468 entire Program shall be treated as though they were included in 469 this License, to the extent that they are valid under applicable 470 law. If additional permissions apply only to part of the Program, 471 that part may be used separately under those permissions, but the 472 entire Program remains governed by this License without regard to 473 the additional permissions. 474 475 When you convey a copy of a covered work, you may at your option 476 remove any additional permissions from that copy, or from any part 477 of it. (Additional permissions may be written to require their own 478 removal in certain cases when you modify the work.) You may place 479 additional permissions on material, added by you to a covered work, 480 for which you have or can give appropriate copyright permission. 481 482 Notwithstanding any other provision of this License, for material 483 you add to a covered work, you may (if authorized by the copyright 484 holders of that material) supplement the terms of this License with 485 terms: 486 487 a. Disclaiming warranty or limiting liability differently from 488 the terms of sections 15 and 16 of this License; or 489 490 b. Requiring preservation of specified reasonable legal notices 491 or author attributions in that material or in the Appropriate 492 Legal Notices displayed by works containing it; or 493 494 c. Prohibiting misrepresentation of the origin of that material, 495 or requiring that modified versions of such material be marked 496 in reasonable ways as different from the original version; or 497 498 d. Limiting the use for publicity purposes of names of licensors 499 or authors of the material; or 500 501 e. Declining to grant rights under trademark law for use of some 502 trade names, trademarks, or service marks; or 503 504 f. Requiring indemnification of licensors and authors of that 505 material by anyone who conveys the material (or modified 506 versions of it) with contractual assumptions of liability to 507 the recipient, for any liability that these contractual 508 assumptions directly impose on those licensors and authors. 509 510 All other non-permissive additional terms are considered "further 511 restrictions" within the meaning of section 10. If the Program as 512 you received it, or any part of it, contains a notice stating that 513 it is governed by this License along with a term that is a further 514 restriction, you may remove that term. If a license document 515 contains a further restriction but permits relicensing or conveying 516 under this License, you may add to a covered work material governed 517 by the terms of that license document, provided that the further 518 restriction does not survive such relicensing or conveying. 519 520 If you add terms to a covered work in accord with this section, you 521 must place, in the relevant source files, a statement of the 522 additional terms that apply to those files, or a notice indicating 523 where to find the applicable terms. 524 525 Additional terms, permissive or non-permissive, may be stated in 526 the form of a separately written license, or stated as exceptions; 527 the above requirements apply either way. 528 529 8. Termination. 530 531 You may not propagate or modify a covered work except as expressly 532 provided under this License. Any attempt otherwise to propagate or 533 modify it is void, and will automatically terminate your rights 534 under this License (including any patent licenses granted under the 535 third paragraph of section 11). 536 537 However, if you cease all violation of this License, then your 538 license from a particular copyright holder is reinstated (a) 539 provisionally, unless and until the copyright holder explicitly and 540 finally terminates your license, and (b) permanently, if the 541 copyright holder fails to notify you of the violation by some 542 reasonable means prior to 60 days after the cessation. 543 544 Moreover, your license from a particular copyright holder is 545 reinstated permanently if the copyright holder notifies you of the 546 violation by some reasonable means, this is the first time you have 547 received notice of violation of this License (for any work) from 548 that copyright holder, and you cure the violation prior to 30 days 549 after your receipt of the notice. 550 551 Termination of your rights under this section does not terminate 552 the licenses of parties who have received copies or rights from you 553 under this License. If your rights have been terminated and not 554 permanently reinstated, you do not qualify to receive new licenses 555 for the same material under section 10. 556 557 9. Acceptance Not Required for Having Copies. 558 559 You are not required to accept this License in order to receive or 560 run a copy of the Program. Ancillary propagation of a covered work 561 occurring solely as a consequence of using peer-to-peer 562 transmission to receive a copy likewise does not require 563 acceptance. However, nothing other than this License grants you 564 permission to propagate or modify any covered work. These actions 565 infringe copyright if you do not accept this License. Therefore, 566 by modifying or propagating a covered work, you indicate your 567 acceptance of this License to do so. 568 569 10. Automatic Licensing of Downstream Recipients. 570 571 Each time you convey a covered work, the recipient automatically 572 receives a license from the original licensors, to run, modify and 573 propagate that work, subject to this License. You are not 574 responsible for enforcing compliance by third parties with this 575 License. 576 577 An "entity transaction" is a transaction transferring control of an 578 organization, or substantially all assets of one, or subdividing an 579 organization, or merging organizations. If propagation of a 580 covered work results from an entity transaction, each party to that 581 transaction who receives a copy of the work also receives whatever 582 licenses to the work the party's predecessor in interest had or 583 could give under the previous paragraph, plus a right to possession 584 of the Corresponding Source of the work from the predecessor in 585 interest, if the predecessor has it or can get it with reasonable 586 efforts. 587 588 You may not impose any further restrictions on the exercise of the 589 rights granted or affirmed under this License. For example, you 590 may not impose a license fee, royalty, or other charge for exercise 591 of rights granted under this License, and you may not initiate 592 litigation (including a cross-claim or counterclaim in a lawsuit) 593 alleging that any patent claim is infringed by making, using, 594 selling, offering for sale, or importing the Program or any portion 595 of it. 596 597 11. Patents. 598 599 A "contributor" is a copyright holder who authorizes use under this 600 License of the Program or a work on which the Program is based. 601 The work thus licensed is called the contributor's "contributor 602 version". 603 604 A contributor's "essential patent claims" are all patent claims 605 owned or controlled by the contributor, whether already acquired or 606 hereafter acquired, that would be infringed by some manner, 607 permitted by this License, of making, using, or selling its 608 contributor version, but do not include claims that would be 609 infringed only as a consequence of further modification of the 610 contributor version. For purposes of this definition, "control" 611 includes the right to grant patent sublicenses in a manner 612 consistent with the requirements of this License. 613 614 Each contributor grants you a non-exclusive, worldwide, 615 royalty-free patent license under the contributor's essential 616 patent claims, to make, use, sell, offer for sale, import and 617 otherwise run, modify and propagate the contents of its contributor 618 version. 619 620 In the following three paragraphs, a "patent license" is any 621 express agreement or commitment, however denominated, not to 622 enforce a patent (such as an express permission to practice a 623 patent or covenant not to sue for patent infringement). To "grant" 624 such a patent license to a party means to make such an agreement or 625 commitment not to enforce a patent against the party. 626 627 If you convey a covered work, knowingly relying on a patent 628 license, and the Corresponding Source of the work is not available 629 for anyone to copy, free of charge and under the terms of this 630 License, through a publicly available network server or other 631 readily accessible means, then you must either (1) cause the 632 Corresponding Source to be so available, or (2) arrange to deprive 633 yourself of the benefit of the patent license for this particular 634 work, or (3) arrange, in a manner consistent with the requirements 635 of this License, to extend the patent license to downstream 636 recipients. "Knowingly relying" means you have actual knowledge 637 that, but for the patent license, your conveying the covered work 638 in a country, or your recipient's use of the covered work in a 639 country, would infringe one or more identifiable patents in that 640 country that you have reason to believe are valid. 641 642 If, pursuant to or in connection with a single transaction or 643 arrangement, you convey, or propagate by procuring conveyance of, a 644 covered work, and grant a patent license to some of the parties 645 receiving the covered work authorizing them to use, propagate, 646 modify or convey a specific copy of the covered work, then the 647 patent license you grant is automatically extended to all 648 recipients of the covered work and works based on it. 649 650 A patent license is "discriminatory" if it does not include within 651 the scope of its coverage, prohibits the exercise of, or is 652 conditioned on the non-exercise of one or more of the rights that 653 are specifically granted under this License. You may not convey a 654 covered work if you are a party to an arrangement with a third 655 party that is in the business of distributing software, under which 656 you make payment to the third party based on the extent of your 657 activity of conveying the work, and under which the third party 658 grants, to any of the parties who would receive the covered work 659 from you, a discriminatory patent license (a) in connection with 660 copies of the covered work conveyed by you (or copies made from 661 those copies), or (b) primarily for and in connection with specific 662 products or compilations that contain the covered work, unless you 663 entered into that arrangement, or that patent license was granted, 664 prior to 28 March 2007. 665 666 Nothing in this License shall be construed as excluding or limiting 667 any implied license or other defenses to infringement that may 668 otherwise be available to you under applicable patent law. 669 670 12. No Surrender of Others' Freedom. 671 672 If conditions are imposed on you (whether by court order, agreement 673 or otherwise) that contradict the conditions of this License, they 674 do not excuse you from the conditions of this License. If you 675 cannot convey a covered work so as to satisfy simultaneously your 676 obligations under this License and any other pertinent obligations, 677 then as a consequence you may not convey it at all. For example, 678 if you agree to terms that obligate you to collect a royalty for 679 further conveying from those to whom you convey the Program, the 680 only way you could satisfy both those terms and this License would 681 be to refrain entirely from conveying the Program. 682 683 13. Use with the GNU Affero General Public License. 684 685 Notwithstanding any other provision of this License, you have 686 permission to link or combine any covered work with a work licensed 687 under version 3 of the GNU Affero General Public License into a 688 single combined work, and to convey the resulting work. The terms 689 of this License will continue to apply to the part which is the 690 covered work, but the special requirements of the GNU Affero 691 General Public License, section 13, concerning interaction through 692 a network will apply to the combination as such. 693 694 14. Revised Versions of this License. 695 696 The Free Software Foundation may publish revised and/or new 697 versions of the GNU General Public License from time to time. Such 698 new versions will be similar in spirit to the present version, but 699 may differ in detail to address new problems or concerns. 700 701 Each version is given a distinguishing version number. If the 702 Program specifies that a certain numbered version of the GNU 703 General Public License "or any later version" applies to it, you 704 have the option of following the terms and conditions either of 705 that numbered version or of any later version published by the Free 706 Software Foundation. If the Program does not specify a version 707 number of the GNU General Public License, you may choose any 708 version ever published by the Free Software Foundation. 709 710 If the Program specifies that a proxy can decide which future 711 versions of the GNU General Public License can be used, that 712 proxy's public statement of acceptance of a version permanently 713 authorizes you to choose that version for the Program. 714 715 Later license versions may give you additional or different 716 permissions. However, no additional obligations are imposed on any 717 author or copyright holder as a result of your choosing to follow a 718 later version. 719 720 15. Disclaimer of Warranty. 721 722 THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 723 APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE 724 COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" 725 WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, 726 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 727 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE 728 RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. 729 SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 730 NECESSARY SERVICING, REPAIR OR CORRECTION. 731 732 16. Limitation of Liability. 733 734 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 735 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES 736 AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR 737 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR 738 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE 739 THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA 740 BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 741 PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 742 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF 743 THE POSSIBILITY OF SUCH DAMAGES. 744 745 17. Interpretation of Sections 15 and 16. 746 747 If the disclaimer of warranty and limitation of liability provided 748 above cannot be given local legal effect according to their terms, 749 reviewing courts shall apply local law that most closely 750 approximates an absolute waiver of all civil liability in 751 connection with the Program, unless a warranty or assumption of 752 liability accompanies a copy of the Program in return for a fee. 753 754END OF TERMS AND CONDITIONS 755=========================== 756 757How to Apply These Terms to Your New Programs 758============================================= 759 760If you develop a new program, and you want it to be of the greatest 761possible use to the public, the best way to achieve this is to make it 762free software which everyone can redistribute and change under these 763terms. 764 765 To do so, attach the following notices to the program. It is safest 766to attach them to the start of each source file to most effectively 767state the exclusion of warranty; and each file should have at least the 768"copyright" line and a pointer to where the full notice is found. 769 770 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. 771 Copyright (C) YEAR NAME OF AUTHOR 772 773 This program is free software: you can redistribute it and/or modify 774 it under the terms of the GNU General Public License as published by 775 the Free Software Foundation, either version 3 of the License, or (at 776 your option) any later version. 777 778 This program is distributed in the hope that it will be useful, but 779 WITHOUT ANY WARRANTY; without even the implied warranty of 780 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 781 General Public License for more details. 782 783 You should have received a copy of the GNU General Public License 784 along with this program. If not, see <http://www.gnu.org/licenses/>. 785 786 Also add information on how to contact you by electronic and paper 787mail. 788 789 If the program does terminal interaction, make it output a short 790notice like this when it starts in an interactive mode: 791 792 PROGRAM Copyright (C) YEAR NAME OF AUTHOR 793 This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. 794 This is free software, and you are welcome to redistribute it 795 under certain conditions; type 'show c' for details. 796 797 The hypothetical commands 'show w' and 'show c' should show the 798appropriate parts of the General Public License. Of course, your 799program's commands might be different; for a GUI interface, you would 800use an "about box". 801 802 You should also get your employer (if you work as a programmer) or 803school, if any, to sign a "copyright disclaimer" for the program, if 804necessary. For more information on this, and how to apply and follow 805the GNU GPL, see <http://www.gnu.org/licenses/>. 806 807 The GNU General Public License does not permit incorporating your 808program into proprietary programs. If your program is a subroutine 809library, you may consider it more useful to permit linking proprietary 810applications with the library. If this is what you want to do, use the 811GNU Lesser General Public License instead of this License. But first, 812please read <http://www.gnu.org/philosophy/why-not-lgpl.html>. 813 814 815File: gcj.info, Node: GNU Free Documentation License, Next: Invoking gcj, Prev: Copying, Up: Top 816 817GNU Free Documentation License 818****************************** 819 820 Version 1.3, 3 November 2008 821 822 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 823 <http://fsf.org/> 824 825 Everyone is permitted to copy and distribute verbatim copies 826 of this license document, but changing it is not allowed. 827 828 0. PREAMBLE 829 830 The purpose of this License is to make a manual, textbook, or other 831 functional and useful document "free" in the sense of freedom: to 832 assure everyone the effective freedom to copy and redistribute it, 833 with or without modifying it, either commercially or 834 noncommercially. Secondarily, this License preserves for the 835 author and publisher a way to get credit for their work, while not 836 being considered responsible for modifications made by others. 837 838 This License is a kind of "copyleft", which means that derivative 839 works of the document must themselves be free in the same sense. 840 It complements the GNU General Public License, which is a copyleft 841 license designed for free software. 842 843 We have designed this License in order to use it for manuals for 844 free software, because free software needs free documentation: a 845 free program should come with manuals providing the same freedoms 846 that the software does. But this License is not limited to 847 software manuals; it can be used for any textual work, regardless 848 of subject matter or whether it is published as a printed book. We 849 recommend this License principally for works whose purpose is 850 instruction or reference. 851 852 1. APPLICABILITY AND DEFINITIONS 853 854 This License applies to any manual or other work, in any medium, 855 that contains a notice placed by the copyright holder saying it can 856 be distributed under the terms of this License. Such a notice 857 grants a world-wide, royalty-free license, unlimited in duration, 858 to use that work under the conditions stated herein. The 859 "Document", below, refers to any such manual or work. Any member 860 of the public is a licensee, and is addressed as "you". You accept 861 the license if you copy, modify or distribute the work in a way 862 requiring permission under copyright law. 863 864 A "Modified Version" of the Document means any work containing the 865 Document or a portion of it, either copied verbatim, or with 866 modifications and/or translated into another language. 867 868 A "Secondary Section" is a named appendix or a front-matter section 869 of the Document that deals exclusively with the relationship of the 870 publishers or authors of the Document to the Document's overall 871 subject (or to related matters) and contains nothing that could 872 fall directly within that overall subject. (Thus, if the Document 873 is in part a textbook of mathematics, a Secondary Section may not 874 explain any mathematics.) The relationship could be a matter of 875 historical connection with the subject or with related matters, or 876 of legal, commercial, philosophical, ethical or political position 877 regarding them. 878 879 The "Invariant Sections" are certain Secondary Sections whose 880 titles are designated, as being those of Invariant Sections, in the 881 notice that says that the Document is released under this License. 882 If a section does not fit the above definition of Secondary then it 883 is not allowed to be designated as Invariant. The Document may 884 contain zero Invariant Sections. If the Document does not identify 885 any Invariant Sections then there are none. 886 887 The "Cover Texts" are certain short passages of text that are 888 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 889 that says that the Document is released under this License. A 890 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 891 be at most 25 words. 892 893 A "Transparent" copy of the Document means a machine-readable copy, 894 represented in a format whose specification is available to the 895 general public, that is suitable for revising the document 896 straightforwardly with generic text editors or (for images composed 897 of pixels) generic paint programs or (for drawings) some widely 898 available drawing editor, and that is suitable for input to text 899 formatters or for automatic translation to a variety of formats 900 suitable for input to text formatters. A copy made in an otherwise 901 Transparent file format whose markup, or absence of markup, has 902 been arranged to thwart or discourage subsequent modification by 903 readers is not Transparent. An image format is not Transparent if 904 used for any substantial amount of text. A copy that is not 905 "Transparent" is called "Opaque". 906 907 Examples of suitable formats for Transparent copies include plain 908 ASCII without markup, Texinfo input format, LaTeX input format, 909 SGML or XML using a publicly available DTD, and standard-conforming 910 simple HTML, PostScript or PDF designed for human modification. 911 Examples of transparent image formats include PNG, XCF and JPG. 912 Opaque formats include proprietary formats that can be read and 913 edited only by proprietary word processors, SGML or XML for which 914 the DTD and/or processing tools are not generally available, and 915 the machine-generated HTML, PostScript or PDF produced by some word 916 processors for output purposes only. 917 918 The "Title Page" means, for a printed book, the title page itself, 919 plus such following pages as are needed to hold, legibly, the 920 material this License requires to appear in the title page. For 921 works in formats which do not have any title page as such, "Title 922 Page" means the text near the most prominent appearance of the 923 work's title, preceding the beginning of the body of the text. 924 925 The "publisher" means any person or entity that distributes copies 926 of the Document to the public. 927 928 A section "Entitled XYZ" means a named subunit of the Document 929 whose title either is precisely XYZ or contains XYZ in parentheses 930 following text that translates XYZ in another language. (Here XYZ 931 stands for a specific section name mentioned below, such as 932 "Acknowledgements", "Dedications", "Endorsements", or "History".) 933 To "Preserve the Title" of such a section when you modify the 934 Document means that it remains a section "Entitled XYZ" according 935 to this definition. 936 937 The Document may include Warranty Disclaimers next to the notice 938 which states that this License applies to the Document. These 939 Warranty Disclaimers are considered to be included by reference in 940 this License, but only as regards disclaiming warranties: any other 941 implication that these Warranty Disclaimers may have is void and 942 has no effect on the meaning of this License. 943 944 2. VERBATIM COPYING 945 946 You may copy and distribute the Document in any medium, either 947 commercially or noncommercially, provided that this License, the 948 copyright notices, and the license notice saying this License 949 applies to the Document are reproduced in all copies, and that you 950 add no other conditions whatsoever to those of this License. You 951 may not use technical measures to obstruct or control the reading 952 or further copying of the copies you make or distribute. However, 953 you may accept compensation in exchange for copies. If you 954 distribute a large enough number of copies you must also follow the 955 conditions in section 3. 956 957 You may also lend copies, under the same conditions stated above, 958 and you may publicly display copies. 959 960 3. COPYING IN QUANTITY 961 962 If you publish printed copies (or copies in media that commonly 963 have printed covers) of the Document, numbering more than 100, and 964 the Document's license notice requires Cover Texts, you must 965 enclose the copies in covers that carry, clearly and legibly, all 966 these Cover Texts: Front-Cover Texts on the front cover, and 967 Back-Cover Texts on the back cover. Both covers must also clearly 968 and legibly identify you as the publisher of these copies. The 969 front cover must present the full title with all words of the title 970 equally prominent and visible. You may add other material on the 971 covers in addition. Copying with changes limited to the covers, as 972 long as they preserve the title of the Document and satisfy these 973 conditions, can be treated as verbatim copying in other respects. 974 975 If the required texts for either cover are too voluminous to fit 976 legibly, you should put the first ones listed (as many as fit 977 reasonably) on the actual cover, and continue the rest onto 978 adjacent pages. 979 980 If you publish or distribute Opaque copies of the Document 981 numbering more than 100, you must either include a machine-readable 982 Transparent copy along with each Opaque copy, or state in or with 983 each Opaque copy a computer-network location from which the general 984 network-using public has access to download using public-standard 985 network protocols a complete Transparent copy of the Document, free 986 of added material. If you use the latter option, you must take 987 reasonably prudent steps, when you begin distribution of Opaque 988 copies in quantity, to ensure that this Transparent copy will 989 remain thus accessible at the stated location until at least one 990 year after the last time you distribute an Opaque copy (directly or 991 through your agents or retailers) of that edition to the public. 992 993 It is requested, but not required, that you contact the authors of 994 the Document well before redistributing any large number of copies, 995 to give them a chance to provide you with an updated version of the 996 Document. 997 998 4. MODIFICATIONS 999 1000 You may copy and distribute a Modified Version of the Document 1001 under the conditions of sections 2 and 3 above, provided that you 1002 release the Modified Version under precisely this License, with the 1003 Modified Version filling the role of the Document, thus licensing 1004 distribution and modification of the Modified Version to whoever 1005 possesses a copy of it. In addition, you must do these things in 1006 the Modified Version: 1007 1008 A. Use in the Title Page (and on the covers, if any) a title 1009 distinct from that of the Document, and from those of previous 1010 versions (which should, if there were any, be listed in the 1011 History section of the Document). You may use the same title 1012 as a previous version if the original publisher of that 1013 version gives permission. 1014 1015 B. List on the Title Page, as authors, one or more persons or 1016 entities responsible for authorship of the modifications in 1017 the Modified Version, together with at least five of the 1018 principal authors of the Document (all of its principal 1019 authors, if it has fewer than five), unless they release you 1020 from this requirement. 1021 1022 C. State on the Title page the name of the publisher of the 1023 Modified Version, as the publisher. 1024 1025 D. Preserve all the copyright notices of the Document. 1026 1027 E. Add an appropriate copyright notice for your modifications 1028 adjacent to the other copyright notices. 1029 1030 F. Include, immediately after the copyright notices, a license 1031 notice giving the public permission to use the Modified 1032 Version under the terms of this License, in the form shown in 1033 the Addendum below. 1034 1035 G. Preserve in that license notice the full lists of Invariant 1036 Sections and required Cover Texts given in the Document's 1037 license notice. 1038 1039 H. Include an unaltered copy of this License. 1040 1041 I. Preserve the section Entitled "History", Preserve its Title, 1042 and add to it an item stating at least the title, year, new 1043 authors, and publisher of the Modified Version as given on the 1044 Title Page. If there is no section Entitled "History" in the 1045 Document, create one stating the title, year, authors, and 1046 publisher of the Document as given on its Title Page, then add 1047 an item describing the Modified Version as stated in the 1048 previous sentence. 1049 1050 J. Preserve the network location, if any, given in the Document 1051 for public access to a Transparent copy of the Document, and 1052 likewise the network locations given in the Document for 1053 previous versions it was based on. These may be placed in the 1054 "History" section. You may omit a network location for a work 1055 that was published at least four years before the Document 1056 itself, or if the original publisher of the version it refers 1057 to gives permission. 1058 1059 K. For any section Entitled "Acknowledgements" or "Dedications", 1060 Preserve the Title of the section, and preserve in the section 1061 all the substance and tone of each of the contributor 1062 acknowledgements and/or dedications given therein. 1063 1064 L. Preserve all the Invariant Sections of the Document, unaltered 1065 in their text and in their titles. Section numbers or the 1066 equivalent are not considered part of the section titles. 1067 1068 M. Delete any section Entitled "Endorsements". Such a section 1069 may not be included in the Modified Version. 1070 1071 N. Do not retitle any existing section to be Entitled 1072 "Endorsements" or to conflict in title with any Invariant 1073 Section. 1074 1075 O. Preserve any Warranty Disclaimers. 1076 1077 If the Modified Version includes new front-matter sections or 1078 appendices that qualify as Secondary Sections and contain no 1079 material copied from the Document, you may at your option designate 1080 some or all of these sections as invariant. To do this, add their 1081 titles to the list of Invariant Sections in the Modified Version's 1082 license notice. These titles must be distinct from any other 1083 section titles. 1084 1085 You may add a section Entitled "Endorsements", provided it contains 1086 nothing but endorsements of your Modified Version by various 1087 parties--for example, statements of peer review or that the text 1088 has been approved by an organization as the authoritative 1089 definition of a standard. 1090 1091 You may add a passage of up to five words as a Front-Cover Text, 1092 and a passage of up to 25 words as a Back-Cover Text, to the end of 1093 the list of Cover Texts in the Modified Version. Only one passage 1094 of Front-Cover Text and one of Back-Cover Text may be added by (or 1095 through arrangements made by) any one entity. If the Document 1096 already includes a cover text for the same cover, previously added 1097 by you or by arrangement made by the same entity you are acting on 1098 behalf of, you may not add another; but you may replace the old 1099 one, on explicit permission from the previous publisher that added 1100 the old one. 1101 1102 The author(s) and publisher(s) of the Document do not by this 1103 License give permission to use their names for publicity for or to 1104 assert or imply endorsement of any Modified Version. 1105 1106 5. COMBINING DOCUMENTS 1107 1108 You may combine the Document with other documents released under 1109 this License, under the terms defined in section 4 above for 1110 modified versions, provided that you include in the combination all 1111 of the Invariant Sections of all of the original documents, 1112 unmodified, and list them all as Invariant Sections of your 1113 combined work in its license notice, and that you preserve all 1114 their Warranty Disclaimers. 1115 1116 The combined work need only contain one copy of this License, and 1117 multiple identical Invariant Sections may be replaced with a single 1118 copy. If there are multiple Invariant Sections with the same name 1119 but different contents, make the title of each such section unique 1120 by adding at the end of it, in parentheses, the name of the 1121 original author or publisher of that section if known, or else a 1122 unique number. Make the same adjustment to the section titles in 1123 the list of Invariant Sections in the license notice of the 1124 combined work. 1125 1126 In the combination, you must combine any sections Entitled 1127 "History" in the various original documents, forming one section 1128 Entitled "History"; likewise combine any sections Entitled 1129 "Acknowledgements", and any sections Entitled "Dedications". You 1130 must delete all sections Entitled "Endorsements." 1131 1132 6. COLLECTIONS OF DOCUMENTS 1133 1134 You may make a collection consisting of the Document and other 1135 documents released under this License, and replace the individual 1136 copies of this License in the various documents with a single copy 1137 that is included in the collection, provided that you follow the 1138 rules of this License for verbatim copying of each of the documents 1139 in all other respects. 1140 1141 You may extract a single document from such a collection, and 1142 distribute it individually under this License, provided you insert 1143 a copy of this License into the extracted document, and follow this 1144 License in all other respects regarding verbatim copying of that 1145 document. 1146 1147 7. AGGREGATION WITH INDEPENDENT WORKS 1148 1149 A compilation of the Document or its derivatives with other 1150 separate and independent documents or works, in or on a volume of a 1151 storage or distribution medium, is called an "aggregate" if the 1152 copyright resulting from the compilation is not used to limit the 1153 legal rights of the compilation's users beyond what the individual 1154 works permit. When the Document is included in an aggregate, this 1155 License does not apply to the other works in the aggregate which 1156 are not themselves derivative works of the Document. 1157 1158 If the Cover Text requirement of section 3 is applicable to these 1159 copies of the Document, then if the Document is less than one half 1160 of the entire aggregate, the Document's Cover Texts may be placed 1161 on covers that bracket the Document within the aggregate, or the 1162 electronic equivalent of covers if the Document is in electronic 1163 form. Otherwise they must appear on printed covers that bracket 1164 the whole aggregate. 1165 1166 8. TRANSLATION 1167 1168 Translation is considered a kind of modification, so you may 1169 distribute translations of the Document under the terms of section 1170 4. Replacing Invariant Sections with translations requires special 1171 permission from their copyright holders, but you may include 1172 translations of some or all Invariant Sections in addition to the 1173 original versions of these Invariant Sections. You may include a 1174 translation of this License, and all the license notices in the 1175 Document, and any Warranty Disclaimers, provided that you also 1176 include the original English version of this License and the 1177 original versions of those notices and disclaimers. In case of a 1178 disagreement between the translation and the original version of 1179 this License or a notice or disclaimer, the original version will 1180 prevail. 1181 1182 If a section in the Document is Entitled "Acknowledgements", 1183 "Dedications", or "History", the requirement (section 4) to 1184 Preserve its Title (section 1) will typically require changing the 1185 actual title. 1186 1187 9. TERMINATION 1188 1189 You may not copy, modify, sublicense, or distribute the Document 1190 except as expressly provided under this License. Any attempt 1191 otherwise to copy, modify, sublicense, or distribute it is void, 1192 and will automatically terminate your rights under this License. 1193 1194 However, if you cease all violation of this License, then your 1195 license from a particular copyright holder is reinstated (a) 1196 provisionally, unless and until the copyright holder explicitly and 1197 finally terminates your license, and (b) permanently, if the 1198 copyright holder fails to notify you of the violation by some 1199 reasonable means prior to 60 days after the cessation. 1200 1201 Moreover, your license from a particular copyright holder is 1202 reinstated permanently if the copyright holder notifies you of the 1203 violation by some reasonable means, this is the first time you have 1204 received notice of violation of this License (for any work) from 1205 that copyright holder, and you cure the violation prior to 30 days 1206 after your receipt of the notice. 1207 1208 Termination of your rights under this section does not terminate 1209 the licenses of parties who have received copies or rights from you 1210 under this License. If your rights have been terminated and not 1211 permanently reinstated, receipt of a copy of some or all of the 1212 same material does not give you any rights to use it. 1213 1214 10. FUTURE REVISIONS OF THIS LICENSE 1215 1216 The Free Software Foundation may publish new, revised versions of 1217 the GNU Free Documentation License from time to time. Such new 1218 versions will be similar in spirit to the present version, but may 1219 differ in detail to address new problems or concerns. See 1220 <http://www.gnu.org/copyleft/>. 1221 1222 Each version of the License is given a distinguishing version 1223 number. If the Document specifies that a particular numbered 1224 version of this License "or any later version" applies to it, you 1225 have the option of following the terms and conditions either of 1226 that specified version or of any later version that has been 1227 published (not as a draft) by the Free Software Foundation. If the 1228 Document does not specify a version number of this License, you may 1229 choose any version ever published (not as a draft) by the Free 1230 Software Foundation. If the Document specifies that a proxy can 1231 decide which future versions of this License can be used, that 1232 proxy's public statement of acceptance of a version permanently 1233 authorizes you to choose that version for the Document. 1234 1235 11. RELICENSING 1236 1237 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 1238 World Wide Web server that publishes copyrightable works and also 1239 provides prominent facilities for anybody to edit those works. A 1240 public wiki that anybody can edit is an example of such a server. 1241 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 1242 site means any set of copyrightable works thus published on the MMC 1243 site. 1244 1245 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 1246 license published by Creative Commons Corporation, a not-for-profit 1247 corporation with a principal place of business in San Francisco, 1248 California, as well as future copyleft versions of that license 1249 published by that same organization. 1250 1251 "Incorporate" means to publish or republish a Document, in whole or 1252 in part, as part of another Document. 1253 1254 An MMC is "eligible for relicensing" if it is licensed under this 1255 License, and if all works that were first published under this 1256 License somewhere other than this MMC, and subsequently 1257 incorporated in whole or in part into the MMC, (1) had no cover 1258 texts or invariant sections, and (2) were thus incorporated prior 1259 to November 1, 2008. 1260 1261 The operator of an MMC Site may republish an MMC contained in the 1262 site under CC-BY-SA on the same site at any time before August 1, 1263 2009, provided the MMC is eligible for relicensing. 1264 1265ADDENDUM: How to use this License for your documents 1266==================================================== 1267 1268To use this License in a document you have written, include a copy of 1269the License in the document and put the following copyright and license 1270notices just after the title page: 1271 1272 Copyright (C) YEAR YOUR NAME. 1273 Permission is granted to copy, distribute and/or modify this document 1274 under the terms of the GNU Free Documentation License, Version 1.3 1275 or any later version published by the Free Software Foundation; 1276 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 1277 Texts. A copy of the license is included in the section entitled ``GNU 1278 Free Documentation License''. 1279 1280 If you have Invariant Sections, Front-Cover Texts and Back-Cover 1281Texts, replace the "with...Texts." line with this: 1282 1283 with the Invariant Sections being LIST THEIR TITLES, with 1284 the Front-Cover Texts being LIST, and with the Back-Cover Texts 1285 being LIST. 1286 1287 If you have Invariant Sections without Cover Texts, or some other 1288combination of the three, merge those two alternatives to suit the 1289situation. 1290 1291 If your document contains nontrivial examples of program code, we 1292recommend releasing these examples in parallel under your choice of free 1293software license, such as the GNU General Public License, to permit 1294their use in free software. 1295 1296 1297File: gcj.info, Node: Invoking gcj, Next: Compatibility, Prev: GNU Free Documentation License, Up: Top 1298 12991 Invoking gcj 1300************** 1301 1302As 'gcj' is just another front end to 'gcc', it supports many of the 1303same options as gcc. *Note Option Summary: (gcc)Option Summary. This 1304manual only documents the options specific to 'gcj'. 1305 1306* Menu: 1307 1308* Input and output files:: 1309* Input Options:: How gcj finds files 1310* Encodings:: Options controlling source file encoding 1311* Warnings:: Options controlling warnings specific to gcj 1312* Linking:: Options for making an executable 1313* Code Generation:: Options controlling the output of gcj 1314* Configure-time Options:: Options you won't use 1315 1316 1317File: gcj.info, Node: Input and output files, Next: Input Options, Up: Invoking gcj 1318 13191.1 Input and output files 1320========================== 1321 1322A 'gcj' command is like a 'gcc' command, in that it consists of a number 1323of options and file names. The following kinds of input file names are 1324supported: 1325 1326'FILE.java' 1327 Java source files. 1328'FILE.class' 1329 Java bytecode files. 1330'FILE.zip' 1331'FILE.jar' 1332 An archive containing one or more '.class' files, all of which are 1333 compiled. The archive may be compressed. Files in an archive 1334 which don't end with '.class' are treated as resource files; they 1335 are compiled into the resulting object file as 'core:' URLs. 1336'@FILE' 1337 A file containing a whitespace-separated list of input file names. 1338 (Currently, these must all be '.java' source files, but that may 1339 change.) Each named file is compiled, just as if it had been on 1340 the command line. 1341'LIBRARY.a' 1342'LIBRARY.so' 1343'-lLIBNAME' 1344 Libraries to use when linking. See the 'gcc' manual. 1345 1346 You can specify more than one input file on the 'gcj' command line, 1347in which case they will all be compiled. If you specify a '-o FILENAME' 1348option, all the input files will be compiled together, producing a 1349single output file, named FILENAME. This is allowed even when using 1350'-S' or '-c', but not when using '-C' or '--resource'. (This is an 1351extension beyond the what plain 'gcc' allows.) (If more than one input 1352file is specified, all must currently be '.java' files, though we hope 1353to fix this.) 1354 1355 1356File: gcj.info, Node: Input Options, Next: Encodings, Prev: Input and output files, Up: Invoking gcj 1357 13581.2 Input Options 1359================= 1360 1361'gcj' has options to control where it looks to find files it needs. For 1362instance, 'gcj' might need to load a class that is referenced by the 1363file it has been asked to compile. Like other compilers for the Java 1364language, 'gcj' has a notion of a "class path". There are several 1365options and environment variables which can be used to manipulate the 1366class path. When 'gcj' looks for a given class, it searches the class 1367path looking for matching '.class' or '.java' file. 'gcj' comes with a 1368built-in class path which points at the installed 'libgcj.jar', a file 1369which contains all the standard classes. 1370 1371 In the text below, a directory or path component can refer either to 1372an actual directory on the filesystem, or to a '.zip' or '.jar' file, 1373which 'gcj' will search as if it is a directory. 1374 1375'-IDIR' 1376 All directories specified by '-I' are kept in order and prepended 1377 to the class path constructed from all the other options. Unless 1378 compatibility with tools like 'javac' is important, we recommend 1379 always using '-I' instead of the other options for manipulating the 1380 class path. 1381 1382'--classpath=PATH' 1383 This sets the class path to PATH, a colon-separated list of paths 1384 (on Windows-based systems, a semicolon-separate list of paths). 1385 This does not override the builtin ("boot") search path. 1386 1387'--CLASSPATH=PATH' 1388 Deprecated synonym for '--classpath'. 1389 1390'--bootclasspath=PATH' 1391 Where to find the standard builtin classes, such as 1392 'java.lang.String'. 1393 1394'--extdirs=PATH' 1395 For each directory in the PATH, place the contents of that 1396 directory at the end of the class path. 1397 1398'CLASSPATH' 1399 This is an environment variable which holds a list of paths. 1400 1401 The final class path is constructed like so: 1402 1403 * First come all directories specified via '-I'. 1404 1405 * If '--classpath' is specified, its value is appended. Otherwise, 1406 if the 'CLASSPATH' environment variable is specified, then its 1407 value is appended. Otherwise, the current directory ('"."') is 1408 appended. 1409 1410 * If '--bootclasspath' was specified, append its value. Otherwise, 1411 append the built-in system directory, 'libgcj.jar'. 1412 1413 * Finally, if '--extdirs' was specified, append the contents of the 1414 specified directories at the end of the class path. Otherwise, 1415 append the contents of the built-in extdirs at 1416 '$(prefix)/share/java/ext'. 1417 1418 The classfile built by 'gcj' for the class 'java.lang.Object' (and 1419placed in 'libgcj.jar') contains a special zero length attribute 1420'gnu.gcj.gcj-compiled'. The compiler looks for this attribute when 1421loading 'java.lang.Object' and will report an error if it isn't found, 1422unless it compiles to bytecode (the option 1423'-fforce-classes-archive-check' can be used to override this behavior in 1424this particular case.) 1425 1426'-fforce-classes-archive-check' 1427 This forces the compiler to always check for the special zero 1428 length attribute 'gnu.gcj.gcj-compiled' in 'java.lang.Object' and 1429 issue an error if it isn't found. 1430 1431'-fsource=VERSION' 1432 This option is used to choose the source version accepted by 'gcj'. 1433 The default is '1.5'. 1434 1435 1436File: gcj.info, Node: Encodings, Next: Warnings, Prev: Input Options, Up: Invoking gcj 1437 14381.3 Encodings 1439============= 1440 1441The Java programming language uses Unicode throughout. In an effort to 1442integrate well with other locales, 'gcj' allows '.java' files to be 1443written using almost any encoding. 'gcj' knows how to convert these 1444encodings into its internal encoding at compile time. 1445 1446 You can use the '--encoding=NAME' option to specify an encoding (of a 1447particular character set) to use for source files. If this is not 1448specified, the default encoding comes from your current locale. If your 1449host system has insufficient locale support, then 'gcj' assumes the 1450default encoding to be the 'UTF-8' encoding of Unicode. 1451 1452 To implement '--encoding', 'gcj' simply uses the host platform's 1453'iconv' conversion routine. This means that in practice 'gcj' is 1454limited by the capabilities of the host platform. 1455 1456 The names allowed for the argument '--encoding' vary from platform to 1457platform (since they are not standardized anywhere). However, 'gcj' 1458implements the encoding named 'UTF-8' internally, so if you choose to 1459use this for your source files you can be assured that it will work on 1460every host. 1461 1462 1463File: gcj.info, Node: Warnings, Next: Linking, Prev: Encodings, Up: Invoking gcj 1464 14651.4 Warnings 1466============ 1467 1468'gcj' implements several warnings. As with other generic 'gcc' 1469warnings, if an option of the form '-Wfoo' enables a warning, then 1470'-Wno-foo' will disable it. Here we've chosen to document the form of 1471the warning which will have an effect - the default being the opposite 1472of what is listed. 1473 1474'-Wredundant-modifiers' 1475 With this flag, 'gcj' will warn about redundant modifiers. For 1476 instance, it will warn if an interface method is declared 'public'. 1477 1478'-Wextraneous-semicolon' 1479 This causes 'gcj' to warn about empty statements. Empty statements 1480 have been deprecated. 1481 1482'-Wno-out-of-date' 1483 This option will cause 'gcj' not to warn when a source file is 1484 newer than its matching class file. By default 'gcj' will warn 1485 about this. 1486 1487'-Wno-deprecated' 1488 Warn if a deprecated class, method, or field is referred to. 1489 1490'-Wunused' 1491 This is the same as 'gcc''s '-Wunused'. 1492 1493'-Wall' 1494 This is the same as '-Wredundant-modifiers -Wextraneous-semicolon 1495 -Wunused'. 1496 1497 1498File: gcj.info, Node: Linking, Next: Code Generation, Prev: Warnings, Up: Invoking gcj 1499 15001.5 Linking 1501=========== 1502 1503To turn a Java application into an executable program, you need to link 1504it with the needed libraries, just as for C or C++. The linker by 1505default looks for a global function named 'main'. Since Java does not 1506have global functions, and a collection of Java classes may have more 1507than one class with a 'main' method, you need to let the linker know 1508which of those 'main' methods it should invoke when starting the 1509application. You can do that in any of these ways: 1510 1511 * Specify the class containing the desired 'main' method when you 1512 link the application, using the '--main' flag, described below. 1513 * Link the Java package(s) into a shared library (dll) rather than an 1514 executable. Then invoke the application using the 'gij' program, 1515 making sure that 'gij' can find the libraries it needs. 1516 * Link the Java packages(s) with the flag '-lgij', which links in the 1517 'main' routine from the 'gij' command. This allows you to select 1518 the class whose 'main' method you want to run when you run the 1519 application. You can also use other 'gij' flags, such as '-D' 1520 flags to set properties. Using the '-lgij' library (rather than 1521 the 'gij' program of the previous mechanism) has some advantages: 1522 it is compatible with static linking, and does not require 1523 configuring or installing libraries. 1524 1525 These 'gij' options relate to linking an executable: 1526 1527'--main=CLASSNAME' 1528 This option is used when linking to specify the name of the class 1529 whose 'main' method should be invoked when the resulting executable 1530 is run. 1531 1532'-DNAME[=VALUE]' 1533 This option can only be used with '--main'. It defines a system 1534 property named NAME with value VALUE. If VALUE is not specified 1535 then it defaults to the empty string. These system properties are 1536 initialized at the program's startup and can be retrieved at 1537 runtime using the 'java.lang.System.getProperty' method. 1538 1539'-lgij' 1540 Create an application whose command-line processing is that of the 1541 'gij' command. 1542 1543 This option is an alternative to using '--main'; you cannot use 1544 both. 1545 1546'-static-libgcj' 1547 This option causes linking to be done against a static version of 1548 the libgcj runtime library. This option is only available if 1549 corresponding linker support exists. 1550 1551 *Caution:* Static linking of libgcj may cause essential parts of 1552 libgcj to be omitted. Some parts of libgcj use reflection to load 1553 classes at runtime. Since the linker does not see these references 1554 at link time, it can omit the referred to classes. The result is 1555 usually (but not always) a 'ClassNotFoundException' being thrown at 1556 runtime. Caution must be used when using this option. For more 1557 details see: <http://gcc.gnu.org/wiki/Statically%20linking%20libgcj> 1558 1559 1560File: gcj.info, Node: Code Generation, Next: Configure-time Options, Prev: Linking, Up: Invoking gcj 1561 15621.6 Code Generation 1563=================== 1564 1565In addition to the many 'gcc' options controlling code generation, 'gcj' 1566has several options specific to itself. 1567 1568'-C' 1569 This option is used to tell 'gcj' to generate bytecode ('.class' 1570 files) rather than object code. 1571 1572'--resource RESOURCE-NAME' 1573 This option is used to tell 'gcj' to compile the contents of a 1574 given file to object code so it may be accessed at runtime with the 1575 core protocol handler as 'core:/RESOURCE-NAME'. Note that 1576 RESOURCE-NAME is the name of the resource as found at runtime; for 1577 instance, it could be used in a call to 'ResourceBundle.getBundle'. 1578 The actual file name to be compiled this way must be specified 1579 separately. 1580 1581'-ftarget=VERSION' 1582 This can be used with '-C' to choose the version of bytecode 1583 emitted by 'gcj'. The default is '1.5'. When not generating 1584 bytecode, this option has no effect. 1585 1586'-d DIRECTORY' 1587 When used with '-C', this causes all generated '.class' files to be 1588 put in the appropriate subdirectory of DIRECTORY. By default they 1589 will be put in subdirectories of the current working directory. 1590 1591'-fno-bounds-check' 1592 By default, 'gcj' generates code which checks the bounds of all 1593 array indexing operations. With this option, these checks are 1594 omitted, which can improve performance for code that uses arrays 1595 extensively. Note that this can result in unpredictable behavior 1596 if the code in question actually does violate array bounds 1597 constraints. It is safe to use this option if you are sure that 1598 your code will never throw an 'ArrayIndexOutOfBoundsException'. 1599 1600'-fno-store-check' 1601 Don't generate array store checks. When storing objects into 1602 arrays, a runtime check is normally generated in order to ensure 1603 that the object is assignment compatible with the component type of 1604 the array (which may not be known at compile-time). With this 1605 option, these checks are omitted. This can improve performance for 1606 code which stores objects into arrays frequently. It is safe to 1607 use this option if you are sure your code will never throw an 1608 'ArrayStoreException'. 1609 1610'-fjni' 1611 With 'gcj' there are two options for writing native methods: CNI 1612 and JNI. By default 'gcj' assumes you are using CNI. If you are 1613 compiling a class with native methods, and these methods are 1614 implemented using JNI, then you must use '-fjni'. This option 1615 causes 'gcj' to generate stubs which will invoke the underlying JNI 1616 methods. 1617 1618'-fno-assert' 1619 Don't recognize the 'assert' keyword. This is for compatibility 1620 with older versions of the language specification. 1621 1622'-fno-optimize-static-class-initialization' 1623 When the optimization level is greater or equal to '-O2', 'gcj' 1624 will try to optimize the way calls into the runtime are made to 1625 initialize static classes upon their first use (this optimization 1626 isn't carried out if '-C' was specified.) When compiling to native 1627 code, '-fno-optimize-static-class-initialization' will turn this 1628 optimization off, regardless of the optimization level in use. 1629 1630'--disable-assertions[=CLASS-OR-PACKAGE]' 1631 Don't include code for checking assertions in the compiled code. 1632 If '=CLASS-OR-PACKAGE' is missing disables assertion code 1633 generation for all classes, unless overridden by a more specific 1634 '--enable-assertions' flag. If CLASS-OR-PACKAGE is a class name, 1635 only disables generating assertion checks within the named class or 1636 its inner classes. If CLASS-OR-PACKAGE is a package name, disables 1637 generating assertion checks within the named package or a 1638 subpackage. 1639 1640 By default, assertions are enabled when generating class files or 1641 when not optimizing, and disabled when generating optimized 1642 binaries. 1643 1644'--enable-assertions[=CLASS-OR-PACKAGE]' 1645 Generates code to check assertions. The option is perhaps 1646 misnamed, as you still need to turn on assertion checking at 1647 run-time, and we don't support any easy way to do that. So this 1648 flag isn't very useful yet, except to partially override 1649 '--disable-assertions'. 1650 1651'-findirect-dispatch' 1652 'gcj' has a special binary compatibility ABI, which is enabled by 1653 the '-findirect-dispatch' option. In this mode, the code generated 1654 by 'gcj' honors the binary compatibility guarantees in the Java 1655 Language Specification, and the resulting object files do not need 1656 to be directly linked against their dependencies. Instead, all 1657 dependencies are looked up at runtime. This allows free mixing of 1658 interpreted and compiled code. 1659 1660 Note that, at present, '-findirect-dispatch' can only be used when 1661 compiling '.class' files. It will not work when compiling from 1662 source. CNI also does not yet work with the binary compatibility 1663 ABI. These restrictions will be lifted in some future release. 1664 1665 However, if you compile CNI code with the standard ABI, you can 1666 call it from code built with the binary compatibility ABI. 1667 1668'-fbootstrap-classes' 1669 This option can be use to tell 'libgcj' that the compiled classes 1670 should be loaded by the bootstrap loader, not the system class 1671 loader. By default, if you compile a class and link it into an 1672 executable, it will be treated as if it was loaded using the system 1673 class loader. This is convenient, as it means that things like 1674 'Class.forName()' will search 'CLASSPATH' to find the desired 1675 class. 1676 1677'-freduced-reflection' 1678 This option causes the code generated by 'gcj' to contain a reduced 1679 amount of the class meta-data used to support runtime reflection. 1680 The cost of this savings is the loss of the ability to use certain 1681 reflection capabilities of the standard Java runtime environment. 1682 When set all meta-data except for that which is needed to obtain 1683 correct runtime semantics is eliminated. 1684 1685 For code that does not use reflection (i.e. serialization, RMI, 1686 CORBA or call methods in the 'java.lang.reflect' package), 1687 '-freduced-reflection' will result in proper operation with a 1688 savings in executable code size. 1689 1690 JNI ('-fjni') and the binary compatibility ABI 1691 ('-findirect-dispatch') do not work properly without full 1692 reflection meta-data. Because of this, it is an error to use these 1693 options with '-freduced-reflection'. 1694 1695 *Caution:* If there is no reflection meta-data, code that uses a 1696 'SecurityManager' may not work properly. Also calling 1697 'Class.forName()' may fail if the calling method has no reflection 1698 meta-data. 1699 1700 1701File: gcj.info, Node: Configure-time Options, Prev: Code Generation, Up: Invoking gcj 1702 17031.7 Configure-time Options 1704========================== 1705 1706Some 'gcj' code generations options affect the resulting ABI, and so can 1707only be meaningfully given when 'libgcj', the runtime package, is 1708configured. 'libgcj' puts the appropriate options from this group into 1709a 'spec' file which is read by 'gcj'. These options are listed here for 1710completeness; if you are using 'libgcj' then you won't want to touch 1711these options. 1712 1713'-fuse-boehm-gc' 1714 This enables the use of the Boehm GC bitmap marking code. In 1715 particular this causes 'gcj' to put an object marking descriptor 1716 into each vtable. 1717 1718'-fhash-synchronization' 1719 By default, synchronization data (the data used for 'synchronize', 1720 'wait', and 'notify') is pointed to by a word in each object. With 1721 this option 'gcj' assumes that this information is stored in a hash 1722 table and not in the object itself. 1723 1724'-fuse-divide-subroutine' 1725 On some systems, a library routine is called to perform integer 1726 division. This is required to get exception handling correct when 1727 dividing by zero. 1728 1729'-fcheck-references' 1730 On some systems it's necessary to insert inline checks whenever 1731 accessing an object via a reference. On other systems you won't 1732 need this because null pointer accesses are caught automatically by 1733 the processor. 1734 1735'-fuse-atomic-builtins' 1736 On some systems, GCC can generate code for built-in atomic 1737 operations. Use this option to force gcj to use these builtins 1738 when compiling Java code. Where this capability is present it 1739 should be automatically detected, so you won't usually need to use 1740 this option. 1741 1742 1743File: gcj.info, Node: Compatibility, Next: Invoking jcf-dump, Prev: Invoking gcj, Up: Top 1744 17452 Compatibility with the Java Platform 1746************************************** 1747 1748As we believe it is important that the Java platform not be fragmented, 1749'gcj' and 'libgcj' try to conform to the relevant Java specifications. 1750However, limited manpower and incomplete and unclear documentation work 1751against us. So, there are caveats to using 'gcj'. 1752 1753* Menu: 1754 1755* Limitations:: 1756* Extensions:: 1757 1758 1759File: gcj.info, Node: Limitations, Next: Extensions, Up: Compatibility 1760 17612.1 Standard features not yet supported 1762======================================= 1763 1764This list of compatibility issues is by no means complete. 1765 1766 * 'gcj' implements the JDK 1.2 language. It supports inner classes 1767 and the new 1.4 'assert' keyword. It does not yet support the Java 1768 2 'strictfp' keyword (it recognizes the keyword but ignores it). 1769 1770 * 'libgcj' is largely compatible with the JDK 1.2 libraries. 1771 However, 'libgcj' is missing many packages, most notably 1772 'java.awt'. There are also individual missing classes and methods. 1773 We currently do not have a list showing differences between 1774 'libgcj' and the Java 2 platform. 1775 1776 * Sometimes the 'libgcj' implementation of a method or class differs 1777 from the JDK implementation. This is not always a bug. Still, if 1778 it affects you, it probably makes sense to report it so that we can 1779 discuss the appropriate response. 1780 1781 * 'gcj' does not currently allow for piecemeal replacement of 1782 components within 'libgcj'. Unfortunately, programmers often want 1783 to use newer versions of certain packages, such as those provided 1784 by the Apache Software Foundation's Jakarta project. This has 1785 forced us to place the 'org.w3c.dom' and 'org.xml.sax' packages 1786 into their own libraries, separate from 'libgcj'. If you intend to 1787 use these classes, you must link them explicitly with 1788 '-l-org-w3c-dom' and '-l-org-xml-sax'. Future versions of 'gcj' 1789 may not have this restriction. 1790 1791 1792File: gcj.info, Node: Extensions, Prev: Limitations, Up: Compatibility 1793 17942.2 Extra features unique to gcj 1795================================ 1796 1797The main feature of 'gcj' is that it can compile programs written in the 1798Java programming language to native code. Most extensions that have 1799been added are to facilitate this functionality. 1800 1801 * 'gcj' makes it easy and efficient to mix code written in Java and 1802 C++. *Note About CNI::, for more info on how to use this in your 1803 programs. 1804 1805 * When you compile your classes into a shared library using 1806 '-findirect-dispatch' then add them to the system-wide classmap.db 1807 file using 'gcj-dbtool', they will be automatically loaded by the 1808 'libgcj' system classloader. This is the new, preferred 1809 classname-to-library resolution mechanism. *Note Invoking 1810 gcj-dbtool::, for more information on using the classmap database. 1811 1812 * The old classname-to-library lookup mechanism is still supported 1813 through the 'gnu.gcj.runtime.VMClassLoader.library_control' 1814 property, but it is deprecated and will likely be removed in some 1815 future release. When trying to load a class 'gnu.pkg.SomeClass' 1816 the system classloader will first try to load the shared library 1817 'lib-gnu-pkg-SomeClass.so', if that fails to load the class then it 1818 will try to load 'lib-gnu-pkg.so' and finally when the class is 1819 still not loaded it will try to load 'lib-gnu.so'. Note that all 1820 '.'s will be transformed into '-'s and that searching for inner 1821 classes starts with their outermost outer class. If the class 1822 cannot be found this way the system classloader tries to use the 1823 'libgcj' bytecode interpreter to load the class from the standard 1824 classpath. This process can be controlled to some degree via the 1825 'gnu.gcj.runtime.VMClassLoader.library_control' property; *Note 1826 libgcj Runtime Properties::. 1827 1828 * 'libgcj' includes a special 'gcjlib' URL type. A URL of this form 1829 is like a 'jar' URL, and looks like 1830 'gcjlib:/path/to/shared/library.so!/path/to/resource'. An access 1831 to one of these URLs causes the shared library to be 'dlopen()'d, 1832 and then the resource is looked for in that library. These URLs 1833 are most useful when used in conjunction with 1834 'java.net.URLClassLoader'. Note that, due to implementation 1835 limitations, currently any such URL can be accessed by only one 1836 class loader, and libraries are never unloaded. This means some 1837 care must be exercised to make sure that a 'gcjlib' URL is not 1838 accessed by more than one class loader at once. In a future 1839 release this limitation will be lifted, and such libraries will be 1840 mapped privately. 1841 1842 * A program compiled by 'gcj' will examine the 'GCJ_PROPERTIES' 1843 environment variable and change its behavior in some ways. In 1844 particular 'GCJ_PROPERTIES' holds a list of assignments to global 1845 properties, such as would be set with the '-D' option to 'java'. 1846 For instance, 'java.compiler=gcj' is a valid (but currently 1847 meaningless) setting. 1848 1849 1850File: gcj.info, Node: Invoking jcf-dump, Next: Invoking gij, Prev: Compatibility, Up: Top 1851 18523 Invoking jcf-dump 1853******************* 1854 1855This is a class file examiner, similar to 'javap'. It will print 1856information about a number of classes, which are specified by class name 1857or file name. 1858 1859'-c' 1860 Disassemble method bodies. By default method bodies are not 1861 printed. 1862 1863'--print-constants' 1864 Print the constant pool. When printing a reference to a constant 1865 also print its index in the constant pool. 1866 1867'--javap' 1868 Generate output in 'javap' format. The implementation of this 1869 feature is very incomplete. 1870 1871'--classpath=PATH' 1872'--CLASSPATH=PATH' 1873'-IDIRECTORY' 1874'-o FILE' 1875 These options as the same as the corresponding 'gcj' options. 1876 1877'--help' 1878 Print help, then exit. 1879 1880'--version' 1881 Print version number, then exit. 1882 1883'-v, --verbose' 1884 Print extra information while running. Implies 1885 '--print-constants'. 1886 1887 1888File: gcj.info, Node: Invoking gij, Next: Invoking gcj-dbtool, Prev: Invoking jcf-dump, Up: Top 1889 18904 Invoking gij 1891************** 1892 1893'gij' is a Java bytecode interpreter included with 'libgcj'. 'gij' is 1894not available on every platform; porting it requires a small amount of 1895assembly programming which has not been done for all the targets 1896supported by 'gcj'. 1897 1898 The primary argument to 'gij' is the name of a class or, with '-jar', 1899a jar file. Options before this argument are interpreted by 'gij'; 1900remaining options are passed to the interpreted program. 1901 1902 If a class name is specified and this class does not have a 'main' 1903method with the appropriate signature (a 'static void' method with a 1904'String[]' as its sole argument), then 'gij' will print an error and 1905exit. 1906 1907 If a jar file is specified then 'gij' will use information in it to 1908determine which class' 'main' method will be invoked. 1909 1910 'gij' will invoke the 'main' method with all the remaining 1911command-line options. 1912 1913 Note that 'gij' is not limited to interpreting code. Because 1914'libgcj' includes a class loader which can dynamically load shared 1915objects, it is possible to give 'gij' the name of a class which has been 1916compiled and put into a shared library on the class path. 1917 1918'-cp PATH' 1919'-classpath PATH' 1920 Set the initial class path. The class path is used for finding 1921 class and resource files. If specified, this option overrides the 1922 'CLASSPATH' environment variable. Note that this option is ignored 1923 if '-jar' is used. 1924 1925'-DNAME[=VALUE]' 1926 This defines a system property named NAME with value VALUE. If 1927 VALUE is not specified then it defaults to the empty string. These 1928 system properties are initialized at the program's startup and can 1929 be retrieved at runtime using the 'java.lang.System.getProperty' 1930 method. 1931 1932'-ms=NUMBER' 1933 Equivalent to '-Xms'. 1934 1935'-mx=NUMBER' 1936 Equivalent to '-Xmx'. 1937 1938'-noverify' 1939 Do not verify compliance of bytecode with the VM specification. In 1940 addition, this option disables type verification which is otherwise 1941 performed on BC-ABI compiled code. 1942 1943'-X' 1944'-XARGUMENT' 1945 Supplying '-X' by itself will cause 'gij' to list all the supported 1946 '-X' options. Currently these options are supported: 1947 1948 '-XmsSIZE' 1949 Set the initial heap size. 1950 1951 '-XmxSIZE' 1952 Set the maximum heap size. 1953 1954 '-XssSIZE' 1955 Set the thread stack size. 1956 1957 Unrecognized '-X' options are ignored, for compatibility with other 1958 runtimes. 1959 1960'-jar' 1961 This indicates that the name passed to 'gij' should be interpreted 1962 as the name of a jar file, not a class. 1963 1964'--help' 1965'-?' 1966 Print help, then exit. 1967 1968'--showversion' 1969 Print version number and continue. 1970 1971'--fullversion' 1972 Print detailed version information, then exit. 1973 1974'--version' 1975 Print version number, then exit. 1976 1977'-verbose' 1978'-verbose:class' 1979 Each time a class is initialized, print a short message on standard 1980 error. 1981 1982 'gij' also recognizes and ignores the following options, for 1983compatibility with existing application launch scripts: '-client', 1984'-server', '-hotspot', '-jrockit', '-agentlib', '-agentpath', '-debug', 1985'-d32', '-d64', '-javaagent', '-noclassgc', '-verify', and 1986'-verifyremote'. 1987 1988 1989File: gcj.info, Node: Invoking gcj-dbtool, Next: Invoking jv-convert, Prev: Invoking gij, Up: Top 1990 19915 Invoking gcj-dbtool. 1992********************** 1993 1994'gcj-dbtool' is a tool for creating and manipulating class file mapping 1995databases. 'libgcj' can use these databases to find a shared library 1996corresponding to the bytecode representation of a class. This 1997functionality is useful for ahead-of-time compilation of a program that 1998has no knowledge of 'gcj'. 1999 2000 'gcj-dbtool' works best if all the jar files added to it are compiled 2001using '-findirect-dispatch'. 2002 2003 Note that 'gcj-dbtool' is currently available as "preview 2004technology". We believe it is a reasonable way to allow 2005application-transparent ahead-of-time compilation, but this is an 2006unexplored area. We welcome your comments. 2007 2008'-n DBFILE [SIZE]' 2009 This creates a new database. Currently, databases cannot be 2010 resized; you can choose a larger initial size if desired. The 2011 default size is 32,749. 2012 2013'-a DBFILE JARFILE LIB' 2014'-f DBFILE JARFILE LIB' 2015 This adds a jar file to the database. For each class file in the 2016 jar, a cryptographic signature of the bytecode representation of 2017 the class is recorded in the database. At runtime, a class is 2018 looked up by its signature and the compiled form of the class is 2019 looked for in the corresponding shared library. The '-a' option 2020 will verify that LIB exists before adding it to the database; '-f' 2021 skips this check. 2022 2023'[-][-0] -m DBFILE DBFILE,[DBFILE]' 2024 Merge a number of databases. The output database overwrites any 2025 existing database. To add databases into an existing database, 2026 include the destination in the list of sources. 2027 2028 If '-' or '-0' are used, the list of files to read is taken from 2029 standard input instead of the command line. For '-0', Input 2030 filenames are terminated by a null character instead of by 2031 whitespace. Useful when arguments might contain white space. The 2032 GNU find -print0 option produces input suitable for this mode. 2033 2034'-t DBFILE' 2035 Test a database. 2036 2037'-l DBFILE' 2038 List the contents of a database. 2039 2040'-p' 2041 Print the name of the default database. If there is no default 2042 database, this prints a blank line. If LIBDIR is specified, use it 2043 instead of the default library directory component of the database 2044 name. 2045 2046'--help' 2047 Print a help message, then exit. 2048 2049'--version' 2050'-v' 2051 Print version information, then exit. 2052 2053 2054File: gcj.info, Node: Invoking jv-convert, Next: Invoking grmic, Prev: Invoking gcj-dbtool, Up: Top 2055 20566 Invoking jv-convert 2057********************* 2058 2059'jv-convert' ['OPTION'] ... [INPUTFILE [OUTPUTFILE]] 2060 2061 'jv-convert' is a utility included with 'libgcj' which converts a 2062file from one encoding to another. It is similar to the Unix 'iconv' 2063utility. 2064 2065 The encodings supported by 'jv-convert' are platform-dependent. 2066Currently there is no way to get a list of all supported encodings. 2067 2068'--encoding NAME' 2069'--from NAME' 2070 Use NAME as the input encoding. The default is the current 2071 locale's encoding. 2072 2073'--to NAME' 2074 Use NAME as the output encoding. The default is the 'JavaSrc' 2075 encoding; this is ASCII with '\u' escapes for non-ASCII characters. 2076 2077'-i FILE' 2078 Read from FILE. The default is to read from standard input. 2079 2080'-o FILE' 2081 Write to FILE. The default is to write to standard output. 2082 2083'--reverse' 2084 Swap the input and output encodings. 2085 2086'--help' 2087 Print a help message, then exit. 2088 2089'--version' 2090 Print version information, then exit. 2091 2092 2093File: gcj.info, Node: Invoking grmic, Next: Invoking gc-analyze, Prev: Invoking jv-convert, Up: Top 2094 20957 Invoking grmic 2096**************** 2097 2098'grmic' ['OPTION'] ... CLASS ... 2099 2100 'grmic' is a utility included with 'libgcj' which generates stubs for 2101remote objects. 2102 2103 Note that this program isn't yet fully compatible with the JDK 2104'grmic'. Some options, such as '-classpath', are recognized but 2105currently ignored. We have left these options undocumented for now. 2106 2107 Long options can also be given with a GNU-style leading '--'. For 2108instance, '--help' is accepted. 2109 2110'-keep' 2111'-keepgenerated' 2112 By default, 'grmic' deletes intermediate files. Either of these 2113 options causes it not to delete such files. 2114 2115'-v1.1' 2116 Cause 'grmic' to create stubs and skeletons for the 1.1 protocol 2117 version. 2118 2119'-vcompat' 2120 Cause 'grmic' to create stubs and skeletons compatible with both 2121 the 1.1 and 1.2 protocol versions. This is the default. 2122 2123'-v1.2' 2124 Cause 'grmic' to create stubs and skeletons for the 1.2 protocol 2125 version. 2126 2127'-nocompile' 2128 Don't compile the generated files. 2129 2130'-verbose' 2131 Print information about what 'grmic' is doing. 2132 2133'-d DIRECTORY' 2134 Put output files in DIRECTORY. By default the files are put in the 2135 current working directory. 2136 2137'-help' 2138 Print a help message, then exit. 2139 2140'-version' 2141 Print version information, then exit. 2142 2143 2144File: gcj.info, Node: Invoking gc-analyze, Next: Invoking aot-compile, Prev: Invoking grmic, Up: Top 2145 21468 Invoking gc-analyze 2147********************* 2148 2149'gc-analyze' ['OPTION'] ... [FILE] 2150 2151 'gc-analyze' prints an analysis of a GC memory dump to standard out. 2152 2153 The memory dumps may be created by calling 2154'gnu.gcj.util.GCInfo.enumerate(String namePrefix)' from java code. A 2155memory dump will be created on an out of memory condition if 2156'gnu.gcj.util.GCInfo.setOOMDump(String namePrefix)' is called before the 2157out of memory occurs. 2158 2159 Running this program will create two files: 'TestDump001' and 2160'TestDump001.bytes'. 2161 2162 import gnu.gcj.util.*; 2163 import java.util.*; 2164 2165 public class GCDumpTest 2166 { 2167 static public void main(String args[]) 2168 { 2169 ArrayList<String> l = new ArrayList<String>(1000); 2170 2171 for (int i = 1; i < 1500; i++) { 2172 l.add("This is string #" + i); 2173 } 2174 GCInfo.enumerate("TestDump"); 2175 } 2176 } 2177 2178 The memory dump may then be displayed by running: 2179 2180 gc-analyze -v TestDump001 2181 2182'--verbose' 2183'-v' 2184 Verbose output. 2185 2186'-p TOOL-PREFIX' 2187 Prefix added to the names of the 'nm' and 'readelf' commands. 2188 2189'-d DIRECTORY' 2190 Directory that contains the executable and shared libraries used 2191 when the dump was generated. 2192 2193'--help' 2194 Print a help message, then exit. 2195 2196'--version' 2197 Print version information, then exit. 2198 2199 2200File: gcj.info, Node: Invoking aot-compile, Next: Invoking rebuild-gcj-db, Prev: Invoking gc-analyze, Up: Top 2201 22029 Invoking aot-compile 2203********************** 2204 2205'aot-compile' is a script that searches a directory for Java bytecode 2206(as class files, or in jars) and uses 'gcj' to compile it to native code 2207and generate the databases from it. 2208 2209'-M, --make=PATH' 2210 Specify the path to the 'make' executable to use. 2211 2212'-C, --gcj=PATH' 2213 Specify the path to the 'gcj' executable to use. 2214 2215'-D, --dbtool=PATH' 2216 Specify the path to the 'gcj-dbtool' executable to use. 2217 2218'-m, --makeflags=FLAGS' 2219 Specify flags to pass to 'make' during the build. 2220 2221'-c, --gcjflags=FLAGS' 2222 Specify flags to pass to 'gcj' during compilation, in addition to 2223 '-fPIC -findirect-dispatch -fjni'. 2224 2225'-l, --ldflags=FLAGS' 2226 Specify flags to pass to 'gcj' during linking, in addition to 2227 '-Wl,-Bsymbolic'. 2228 2229'-e, --exclude=PATH' 2230 Do not compile PATH. 2231 2232 2233File: gcj.info, Node: Invoking rebuild-gcj-db, Next: About CNI, Prev: Invoking aot-compile, Up: Top 2234 223510 Invoking rebuild-gcj-db 2236************************** 2237 2238'rebuild-gcj-db' is a script that merges the per-solib databases made by 2239'aot-compile' into one system-wide database so 'gij' can find the 2240solibs. 2241 2242 2243File: gcj.info, Node: About CNI, Next: System properties, Prev: Invoking rebuild-gcj-db, Up: Top 2244 224511 About CNI 2246************ 2247 2248This documents CNI, the Compiled Native Interface, which is is a 2249convenient way to write Java native methods using C++. This is a more 2250efficient, more convenient, but less portable alternative to the 2251standard JNI (Java Native Interface). 2252 2253* Menu: 2254 2255* Basic concepts:: Introduction to using CNI. 2256* Packages:: How packages are mapped to C++. 2257* Primitive types:: Handling primitive Java types in C++. 2258* Reference types:: Handling Java reference types in C++. 2259* Interfaces:: How Java interfaces map to C++. 2260* Objects and Classes:: C++ and Java classes. 2261* Class Initialization:: How objects are initialized. 2262* Object allocation:: How to create Java objects in C++. 2263* Memory allocation:: How to allocate and free memory. 2264* Arrays:: Dealing with Java arrays in C++. 2265* Methods:: Java methods in C++. 2266* Strings:: Information about Java Strings. 2267* Mixing with C++:: How CNI can interoperate with C++. 2268* Exception Handling:: How exceptions are handled. 2269* Synchronization:: Synchronizing between Java and C++. 2270* Invocation:: Starting the Java runtime from C++. 2271* Reflection:: Using reflection from C++. 2272 2273 2274File: gcj.info, Node: Basic concepts, Next: Packages, Up: About CNI 2275 227611.1 Basic concepts 2277=================== 2278 2279In terms of languages features, Java is mostly a subset of C++. Java 2280has a few important extensions, plus a powerful standard class library, 2281but on the whole that does not change the basic similarity. Java is a 2282hybrid object-oriented language, with a few native types, in addition to 2283class types. It is class-based, where a class may have static as well 2284as per-object fields, and static as well as instance methods. 2285Non-static methods may be virtual, and may be overloaded. Overloading 2286is resolved at compile time by matching the actual argument types 2287against the parameter types. Virtual methods are implemented using 2288indirect calls through a dispatch table (virtual function table). 2289Objects are allocated on the heap, and initialized using a constructor 2290method. Classes are organized in a package hierarchy. 2291 2292 All of the listed attributes are also true of C++, though C++ has 2293extra features (for example in C++ objects may be allocated not just on 2294the heap, but also statically or in a local stack frame). Because 'gcj' 2295uses the same compiler technology as G++ (the GNU C++ compiler), it is 2296possible to make the intersection of the two languages use the same ABI 2297(object representation and calling conventions). The key idea in CNI is 2298that Java objects are C++ objects, and all Java classes are C++ classes 2299(but not the other way around). So the most important task in 2300integrating Java and C++ is to remove gratuitous incompatibilities. 2301 2302 You write CNI code as a regular C++ source file. (You do have to use 2303a Java/CNI-aware C++ compiler, specifically a recent version of G++.) 2304 2305A CNI C++ source file must have: 2306 2307 #include <gcj/cni.h> 2308 2309and then must include one header file for each Java class it uses, e.g.: 2310 2311 #include <java/lang/Character.h> 2312 #include <java/util/Date.h> 2313 #include <java/lang/IndexOutOfBoundsException.h> 2314 2315These header files are automatically generated by 'gcjh'. 2316 2317 CNI provides some functions and macros to make using Java objects and 2318primitive types from C++ easier. In general, these CNI functions and 2319macros start with the 'Jv' prefix, for example the function 2320'JvNewObjectArray'. This convention is used to avoid conflicts with 2321other libraries. Internal functions in CNI start with the prefix 2322'_Jv_'. You should not call these; if you find a need to, let us know 2323and we will try to come up with an alternate solution. 2324 232511.1.1 Limitations 2326------------------ 2327 2328Whilst a Java class is just a C++ class that doesn't mean that you are 2329freed from the shackles of Java, a CNI C++ class must adhere to the 2330rules of the Java programming language. 2331 2332 For example: it is not possible to declare a method in a CNI class 2333that will take a C string ('char*') as an argument, or to declare a 2334member variable of some non-Java datatype. 2335 2336 2337File: gcj.info, Node: Packages, Next: Primitive types, Prev: Basic concepts, Up: About CNI 2338 233911.2 Packages 2340============= 2341 2342The only global names in Java are class names, and packages. A 2343"package" can contain zero or more classes, and also zero or more 2344sub-packages. Every class belongs to either an unnamed package or a 2345package that has a hierarchical and globally unique name. 2346 2347 A Java package is mapped to a C++ "namespace". The Java class 2348'java.lang.String' is in the package 'java.lang', which is a sub-package 2349of 'java'. The C++ equivalent is the class 'java::lang::String', which 2350is in the namespace 'java::lang' which is in the namespace 'java'. 2351 2352Here is how you could express this: 2353 2354 (// Declare the class(es), possibly in a header file: 2355 namespace java { 2356 namespace lang { 2357 class Object; 2358 class String; 2359 ... 2360 } 2361 } 2362 2363 class java::lang::String : public java::lang::Object 2364 { 2365 ... 2366 }; 2367 2368The 'gcjh' tool automatically generates the necessary namespace 2369declarations. 2370 237111.2.1 Leaving out package names 2372-------------------------------- 2373 2374Always using the fully-qualified name of a java class can be tiresomely 2375verbose. Using the full qualified name also ties the code to a single 2376package making code changes necessary should the class move from one 2377package to another. The Java 'package' declaration specifies that the 2378following class declarations are in the named package, without having to 2379explicitly name the full package qualifiers. The 'package' declaration 2380can be followed by zero or more 'import' declarations, which allows 2381either a single class or all the classes in a package to be named by a 2382simple identifier. C++ provides something similar with the 'using' 2383declaration and directive. 2384 2385In Java: 2386 2387 import PACKAGE-NAME.CLASS-NAME; 2388 2389allows the program text to refer to CLASS-NAME as a shorthand for the 2390fully qualified name: 'PACKAGE-NAME.CLASS-NAME'. 2391 2392To achieve the same effect C++, you have to do this: 2393 2394 using PACKAGE-NAME::CLASS-NAME; 2395 2396Java can also cause imports on demand, like this: 2397 2398 import PACKAGE-NAME.*; 2399 2400Doing this allows any class from the package PACKAGE-NAME to be referred 2401to only by its class-name within the program text. 2402 2403The same effect can be achieved in C++ like this: 2404 2405 using namespace PACKAGE-NAME; 2406 2407 2408File: gcj.info, Node: Primitive types, Next: Reference types, Prev: Packages, Up: About CNI 2409 241011.3 Primitive types 2411==================== 2412 2413Java provides 8 "primitives" types which represent integers, floats, 2414characters and booleans (and also the void type). C++ has its own very 2415similar concrete types. Such types in C++ however are not always 2416implemented in the same way (an int might be 16, 32 or 64 bits for 2417example) so CNI provides a special C++ type for each primitive Java 2418type: 2419 2420*Java type* *C/C++ typename* *Description* 2421'char' 'jchar' 16 bit Unicode character 2422'boolean' 'jboolean' logical (true or false) values 2423'byte' 'jbyte' 8-bit signed integer 2424'short' 'jshort' 16 bit signed integer 2425'int' 'jint' 32 bit signed integer 2426'long' 'jlong' 64 bit signed integer 2427'float' 'jfloat' 32 bit IEEE floating point number 2428'double' 'jdouble' 64 bit IEEE floating point number 2429'void' 'void' no value 2430 2431 When referring to a Java type You should always use these C++ 2432typenames (e.g.: 'jint') to avoid disappointment. 2433 243411.3.1 Reference types associated with primitive types 2435------------------------------------------------------ 2436 2437In Java each primitive type has an associated reference type, e.g.: 2438'boolean' has an associated 'java.lang.Boolean.TYPE' class. In order to 2439make working with such classes easier GCJ provides the macro 2440'JvPrimClass': 2441 2442 -- macro: JvPrimClass type 2443 Return a pointer to the 'Class' object corresponding to the type 2444 supplied. 2445 2446 JvPrimClass(void) => java.lang.Void.TYPE 2447 2448 2449File: gcj.info, Node: Reference types, Next: Interfaces, Prev: Primitive types, Up: About CNI 2450 245111.4 Reference types 2452==================== 2453 2454A Java reference type is treated as a class in C++. Classes and 2455interfaces are handled this way. A Java reference is translated to a 2456C++ pointer, so for instance a Java 'java.lang.String' becomes, in C++, 2457'java::lang::String *'. 2458 2459 CNI provides a few built-in typedefs for the most common classes: 2460*Java type* *C++ typename* *Description* 2461'java.lang.Object' 'jobject' Object type 2462'java.lang.String' 'jstring' String type 2463'java.lang.Class' 'jclass' Class type 2464 2465 Every Java class or interface has a corresponding 'Class' instance. 2466These can be accessed in CNI via the static 'class$' field of a class. 2467The 'class$' field is of type 'Class' (and not 'Class *'), so you will 2468typically take the address of it. 2469 2470 Here is how you can refer to the class of 'String', which in Java 2471would be written 'String.class': 2472 2473 using namespace java::lang; 2474 doSomething (&String::class$); 2475 2476 2477File: gcj.info, Node: Interfaces, Next: Objects and Classes, Prev: Reference types, Up: About CNI 2478 247911.5 Interfaces 2480=============== 2481 2482A Java class can "implement" zero or more "interfaces", in addition to 2483inheriting from a single base class. 2484 2485 CNI allows CNI code to implement methods of interfaces. You can also 2486call methods through interface references, with some limitations. 2487 2488 CNI doesn't understand interface inheritance at all yet. So, you can 2489only call an interface method when the declared type of the field being 2490called matches the interface which declares that method. The workaround 2491is to cast the interface reference to the right superinterface. 2492 2493 For example if you have: 2494 2495 interface A 2496 { 2497 void a(); 2498 } 2499 2500 interface B extends A 2501 { 2502 void b(); 2503 } 2504 2505 and declare a variable of type 'B' in C++, you can't call 'a()' 2506unless you cast it to an 'A' first. 2507 2508 2509File: gcj.info, Node: Objects and Classes, Next: Class Initialization, Prev: Interfaces, Up: About CNI 2510 251111.6 Objects and Classes 2512======================== 2513 251411.6.1 Classes 2515-------------- 2516 2517All Java classes are derived from 'java.lang.Object'. C++ does not have 2518a unique root class, but we use the C++ class 'java::lang::Object' as 2519the C++ version of the 'java.lang.Object' Java class. All other Java 2520classes are mapped into corresponding C++ classes derived from 2521'java::lang::Object'. 2522 2523 Interface inheritance (the 'implements' keyword) is currently not 2524reflected in the C++ mapping. 2525 252611.6.2 Object fields 2527-------------------- 2528 2529Each object contains an object header, followed by the instance fields 2530of the class, in order. The object header consists of a single pointer 2531to a dispatch or virtual function table. (There may be extra fields _in 2532front of_ the object, for example for memory management, but this is 2533invisible to the application, and the reference to the object points to 2534the dispatch table pointer.) 2535 2536 The fields are laid out in the same order, alignment, and size as in 2537C++. Specifically, 8-bit and 16-bit native types ('byte', 'short', 2538'char', and 'boolean') are _not_ widened to 32 bits. Note that the Java 2539VM does extend 8-bit and 16-bit types to 32 bits when on the VM stack or 2540temporary registers. 2541 2542 If you include the 'gcjh'-generated header for a class, you can 2543access fields of Java classes in the _natural_ way. For example, given 2544the following Java class: 2545 2546 public class Int 2547 { 2548 public int i; 2549 public Int (int i) { this.i = i; } 2550 public static Int zero = new Int(0); 2551 } 2552 2553 you can write: 2554 2555 #include <gcj/cni.h>; 2556 #include <Int>; 2557 2558 Int* 2559 mult (Int *p, jint k) 2560 { 2561 if (k == 0) 2562 return Int::zero; // Static member access. 2563 return new Int(p->i * k); 2564 } 2565 256611.6.3 Access specifiers 2567------------------------ 2568 2569CNI does not strictly enforce the Java access specifiers, because Java 2570permissions cannot be directly mapped into C++ permission. Private Java 2571fields and methods are mapped to private C++ fields and methods, but 2572other fields and methods are mapped to public fields and methods. 2573 2574 2575File: gcj.info, Node: Class Initialization, Next: Object allocation, Prev: Objects and Classes, Up: About CNI 2576 257711.7 Class Initialization 2578========================= 2579 2580Java requires that each class be automatically initialized at the time 2581of the first active use. Initializing a class involves initializing the 2582static fields, running code in class initializer methods, and 2583initializing base classes. There may also be some implementation 2584specific actions, such as allocating 'String' objects corresponding to 2585string literals in the code. 2586 2587 The GCJ compiler inserts calls to 'JvInitClass' at appropriate places 2588to ensure that a class is initialized when required. The C++ compiler 2589does not insert these calls automatically--it is the programmer's 2590responsibility to make sure classes are initialized. However, this is 2591fairly painless because of the conventions assumed by the Java system. 2592 2593 First, 'libgcj' will make sure a class is initialized before an 2594instance of that object is created. This is one of the responsibilities 2595of the 'new' operation. This is taken care of both in Java code, and in 2596C++ code. When G++ sees a 'new' of a Java class, it will call a routine 2597in 'libgcj' to allocate the object, and that routine will take care of 2598initializing the class. Note however that this does not happen for Java 2599arrays; you must allocate those using the appropriate CNI function. It 2600follows that you can access an instance field, or call an instance 2601(non-static) method and be safe in the knowledge that the class and all 2602of its base classes have been initialized. 2603 2604 Invoking a static method is also safe. This is because the Java 2605compiler adds code to the start of a static method to make sure the 2606class is initialized. However, the C++ compiler does not add this extra 2607code. Hence, if you write a native static method using CNI, you are 2608responsible for calling 'JvInitClass' before doing anything else in the 2609method (unless you are sure it is safe to leave it out). 2610 2611 Accessing a static field also requires the class of the field to be 2612initialized. The Java compiler will generate code to call 'JvInitClass' 2613before getting or setting the field. However, the C++ compiler will not 2614generate this extra code, so it is your responsibility to make sure the 2615class is initialized before you access a static field from C++. 2616 2617 2618File: gcj.info, Node: Object allocation, Next: Memory allocation, Prev: Class Initialization, Up: About CNI 2619 262011.8 Object allocation 2621====================== 2622 2623New Java objects are allocated using a "class instance creation 2624expression", e.g.: 2625 2626 new TYPE ( ... ) 2627 2628 The same syntax is used in C++. The main difference is that C++ 2629objects have to be explicitly deleted; in Java they are automatically 2630deleted by the garbage collector. Using CNI, you can allocate a new 2631Java object using standard C++ syntax and the C++ compiler will allocate 2632memory from the garbage collector. If you have overloaded constructors, 2633the compiler will choose the correct one using standard C++ overload 2634resolution rules. 2635 2636For example: 2637 2638 java::util::Hashtable *ht = new java::util::Hashtable(120); 2639 2640 2641File: gcj.info, Node: Memory allocation, Next: Arrays, Prev: Object allocation, Up: About CNI 2642 264311.9 Memory allocation 2644====================== 2645 2646When allocating memory in CNI methods it is best to handle out-of-memory 2647conditions by throwing a Java exception. These functions are provided 2648for that purpose: 2649 2650 -- Function: void* JvMalloc (jsize SIZE) 2651 Calls malloc. Throws 'java.lang.OutOfMemoryError' if allocation 2652 fails. 2653 2654 -- Function: void* JvRealloc (void* PTR, jsize SIZE) 2655 Calls realloc. Throws 'java.lang.OutOfMemoryError' if reallocation 2656 fails. 2657 2658 -- Function: void JvFree (void* PTR) 2659 Calls free. 2660 2661 2662File: gcj.info, Node: Arrays, Next: Methods, Prev: Memory allocation, Up: About CNI 2663 266411.10 Arrays 2665============ 2666 2667While in many ways Java is similar to C and C++, it is quite different 2668in its treatment of arrays. C arrays are based on the idea of pointer 2669arithmetic, which would be incompatible with Java's security 2670requirements. Java arrays are true objects (array types inherit from 2671'java.lang.Object'). An array-valued variable is one that contains a 2672reference (pointer) to an array object. 2673 2674 Referencing a Java array in C++ code is done using the 'JArray' 2675template, which as defined as follows: 2676 2677 class __JArray : public java::lang::Object 2678 { 2679 public: 2680 int length; 2681 }; 2682 2683 template<class T> 2684 class JArray : public __JArray 2685 { 2686 T data[0]; 2687 public: 2688 T& operator[](jint i) { return data[i]; } 2689 }; 2690 2691 There are a number of 'typedef's which correspond to 'typedef's from 2692the JNI. Each is the type of an array holding objects of the relevant 2693type: 2694 2695 typedef __JArray *jarray; 2696 typedef JArray<jobject> *jobjectArray; 2697 typedef JArray<jboolean> *jbooleanArray; 2698 typedef JArray<jbyte> *jbyteArray; 2699 typedef JArray<jchar> *jcharArray; 2700 typedef JArray<jshort> *jshortArray; 2701 typedef JArray<jint> *jintArray; 2702 typedef JArray<jlong> *jlongArray; 2703 typedef JArray<jfloat> *jfloatArray; 2704 typedef JArray<jdouble> *jdoubleArray; 2705 2706 -- Method on template<class T>: T* elements (JArray<T> ARRAY) 2707 This template function can be used to get a pointer to the elements 2708 of the 'array'. For instance, you can fetch a pointer to the 2709 integers that make up an 'int[]' like so: 2710 2711 extern jintArray foo; 2712 jint *intp = elements (foo); 2713 2714 The name of this function may change in the future. 2715 2716 -- Function: jobjectArray JvNewObjectArray (jsize LENGTH, jclass KLASS, 2717 jobject INIT) 2718 This creates a new array whose elements have reference type. 2719 'klass' is the type of elements of the array and 'init' is the 2720 initial value put into every slot in the array. 2721 2722 using namespace java::lang; 2723 JArray<String *> *array 2724 = (JArray<String *> *) JvNewObjectArray(length, &String::class$, NULL); 2725 272611.10.1 Creating arrays 2727----------------------- 2728 2729For each primitive type there is a function which can be used to create 2730a new array of that type. The name of the function is of the form: 2731 2732 JvNewTYPEArray 2733 2734For example: 2735 2736 JvNewBooleanArray 2737 2738can be used to create an array of Java primitive boolean types. 2739 2740The following function definition is the template for all such 2741functions: 2742 2743 -- Function: jbooleanArray JvNewBooleanArray (jint LENGTH) 2744 Creates an array LENGTH indices long. 2745 2746 -- Function: jsize JvGetArrayLength (jarray ARRAY) 2747 Returns the length of the ARRAY. 2748 2749 2750File: gcj.info, Node: Methods, Next: Strings, Prev: Arrays, Up: About CNI 2751 275211.11 Methods 2753============= 2754 2755Java methods are mapped directly into C++ methods. The header files 2756generated by 'gcjh' include the appropriate method definitions. 2757Basically, the generated methods have the same names and _corresponding_ 2758types as the Java methods, and are called in the natural manner. 2759 276011.11.1 Overloading 2761------------------- 2762 2763Both Java and C++ provide method overloading, where multiple methods in 2764a class have the same name, and the correct one is chosen (at compile 2765time) depending on the argument types. The rules for choosing the 2766correct method are (as expected) more complicated in C++ than in Java, 2767but given a set of overloaded methods generated by 'gcjh' the C++ 2768compiler will choose the expected one. 2769 2770 Common assemblers and linkers are not aware of C++ overloading, so 2771the standard implementation strategy is to encode the parameter types of 2772a method into its assembly-level name. This encoding is called 2773"mangling", and the encoded name is the "mangled name". The same 2774mechanism is used to implement Java overloading. For C++/Java 2775interoperability, it is important that both the Java and C++ compilers 2776use the _same_ encoding scheme. 2777 277811.11.2 Static methods 2779---------------------- 2780 2781Static Java methods are invoked in CNI using the standard C++ syntax, 2782using the '::' operator rather than the '.' operator. 2783 2784For example: 2785 2786 jint i = java::lang::Math::round((jfloat) 2.3); 2787 2788C++ method definition syntax is used to define a static native method. 2789For example: 2790 2791 #include <java/lang/Integer> 2792 java::lang::Integer* 2793 java::lang::Integer::getInteger(jstring str) 2794 { 2795 ... 2796 } 2797 279811.11.3 Object Constructors 2799--------------------------- 2800 2801Constructors are called implicitly as part of object allocation using 2802the 'new' operator. 2803 2804For example: 2805 2806 java::lang::Integer *x = new java::lang::Integer(234); 2807 2808 Java does not allow a constructor to be a native method. This 2809limitation can be coded round however because a constructor can _call_ a 2810native method. 2811 281211.11.4 Instance methods 2813------------------------ 2814 2815Calling a Java instance method from a C++ CNI method is done using the 2816standard C++ syntax, e.g.: 2817 2818 // First create the Java object. 2819 java::lang::Integer *x = new java::lang::Integer(234); 2820 // Now call a method. 2821 jint prim_value = x->intValue(); 2822 if (x->longValue == 0) 2823 ... 2824 2825Defining a Java native instance method is also done the natural way: 2826 2827 #include <java/lang/Integer.h> 2828 2829 jdouble 2830 java::lang:Integer::doubleValue() 2831 { 2832 return (jdouble) value; 2833 } 2834 283511.11.5 Interface methods 2836------------------------- 2837 2838In Java you can call a method using an interface reference. This is 2839supported, but not completely. *Note Interfaces::. 2840 2841 2842File: gcj.info, Node: Strings, Next: Mixing with C++, Prev: Methods, Up: About CNI 2843 284411.12 Strings 2845============= 2846 2847CNI provides a number of utility functions for working with Java Java 2848'String' objects. The names and interfaces are analogous to those of 2849JNI. 2850 2851 -- Function: jstring JvNewString (const jchar* CHARS, jsize LEN) 2852 Returns a Java 'String' object with characters from the array of 2853 Unicode characters CHARS up to the index LEN in that array. 2854 2855 -- Function: jstring JvNewStringLatin1 (const char* BYTES, jsize LEN) 2856 Returns a Java 'String' made up of LEN bytes from BYTES. 2857 2858 -- Function: jstring JvNewStringLatin1 (const char* BYTES) 2859 As above but the length of the 'String' is 'strlen(BYTES)'. 2860 2861 -- Function: jstring JvNewStringUTF (const char* BYTES) 2862 Returns a 'String' which is made up of the UTF encoded characters 2863 present in the C string BYTES. 2864 2865 -- Function: jchar* JvGetStringChars (jstring STR) 2866 Returns a pointer to an array of characters making up the 'String' 2867 STR. 2868 2869 -- Function: int JvGetStringUTFLength (jstring STR) 2870 Returns the number of bytes required to encode the contents of the 2871 'String' STR in UTF-8. 2872 2873 -- Function: jsize JvGetStringUTFRegion (jstring STR, jsize START, 2874 jsize LEN, char* BUF) 2875 Puts the UTF-8 encoding of a region of the 'String' STR into the 2876 buffer 'buf'. The region to fetch is marked by START and LEN. 2877 2878 Note that BUF is a buffer, not a C string. It is _not_ null 2879 terminated. 2880 2881 2882File: gcj.info, Node: Mixing with C++, Next: Exception Handling, Prev: Strings, Up: About CNI 2883 288411.13 Interoperating with C/C++ 2885=============================== 2886 2887Because CNI is designed to represent Java classes and methods it cannot 2888be mixed readily with C/C++ types. 2889 2890 One important restriction is that Java classes cannot have non-Java 2891type instance or static variables and cannot have methods which take 2892non-Java types as arguments or return non-Java types. 2893 2894None of the following is possible with CNI: 2895 2896 2897 class ::MyClass : public java::lang::Object 2898 { 2899 char* variable; // char* is not a valid Java type. 2900 } 2901 2902 2903 uint 2904 ::SomeClass::someMethod (char *arg) 2905 { 2906 . 2907 . 2908 . 2909 } // 'uint' is not a valid Java type, neither is 'char*' 2910 2911Of course, it is ok to use C/C++ types within the scope of a method: 2912 2913 jint 2914 ::SomeClass::otherMethod (jstring str) 2915 { 2916 char *arg = ... 2917 . 2918 . 2919 . 2920 } 2921 292211.13.1 RawData 2923--------------- 2924 2925The above restriction can be problematic, so CNI includes the 2926'gnu.gcj.RawData' class. The 'RawData' class is a "non-scanned 2927reference" type. In other words variables declared of type 'RawData' 2928can contain any data and are not checked by the compiler or memory 2929manager in any way. 2930 2931 This means that you can put C/C++ data structures (including classes) 2932in your CNI classes, as long as you use the appropriate cast. 2933 2934Here are some examples: 2935 2936 2937 class ::MyClass : public java::lang::Object 2938 { 2939 gnu.gcj.RawData string; 2940 2941 MyClass (); 2942 gnu.gcj.RawData getText (); 2943 void printText (); 2944 } 2945 2946 ::MyClass::MyClass () 2947 { 2948 char* text = ... 2949 string = text; 2950 } 2951 2952 gnu.gcj.RawData 2953 ::MyClass::getText () 2954 { 2955 return string; 2956 } 2957 2958 void 2959 ::MyClass::printText () 2960 { 2961 printf("%s\n", (char*) string); 2962 } 2963 296411.13.2 RawDataManaged 2965---------------------- 2966 2967'gnu.gcj.RawDataManaged' is another type used to indicate special data 2968used by native code. Unlike the 'RawData' type, fields declared as 2969'RawDataManaged' will be "marked" by the memory manager and considered 2970for garbage collection. 2971 2972 Native data which is allocated using CNI's 'JvAllocBytes()' function 2973and stored in a 'RawDataManaged' will be automatically freed when the 2974Java object it is associated with becomes unreachable. 2975 297611.13.3 Native memory allocation 2977-------------------------------- 2978 2979 -- Function: void* JvAllocBytes (jsize SIZE) 2980 Allocates SIZE bytes from the heap. The memory returned is zeroed. 2981 This memory is not scanned for pointers by the garbage collector, 2982 but will be freed if no references to it are discovered. 2983 2984 This function can be useful if you need to associate some native 2985 data with a Java object. Using a CNI's special 'RawDataManaged' 2986 type, native data allocated with 'JvAllocBytes' will be 2987 automatically freed when the Java object itself becomes 2988 unreachable. 2989 299011.13.4 Posix signals 2991--------------------- 2992 2993On Posix based systems the 'libgcj' library uses several signals 2994internally. CNI code should not attempt to use the same signals as 2995doing so may cause 'libgcj' and/or the CNI code to fail. 2996 2997 SIGSEGV is used on many systems to generate 'NullPointerExceptions'. 2998SIGCHLD is used internally by 'Runtime.exec()'. Several other signals 2999(that vary from platform to platform) can be used by the memory manager 3000and by 'Thread.interrupt()'. 3001 3002 3003File: gcj.info, Node: Exception Handling, Next: Synchronization, Prev: Mixing with C++, Up: About CNI 3004 300511.14 Exception Handling 3006======================== 3007 3008While C++ and Java share a common exception handling framework, things 3009are not yet perfectly integrated. The main issue is that the run-time 3010type information facilities of the two languages are not integrated. 3011 3012 Still, things work fairly well. You can throw a Java exception from 3013C++ using the ordinary 'throw' construct, and this exception can be 3014caught by Java code. Similarly, you can catch an exception thrown from 3015Java using the C++ 'catch' construct. 3016 3017Here is an example: 3018 3019 if (i >= count) 3020 throw new java::lang::IndexOutOfBoundsException(); 3021 3022 Normally, G++ will automatically detect when you are writing C++ code 3023that uses Java exceptions, and handle them appropriately. However, if 3024C++ code only needs to execute destructors when Java exceptions are 3025thrown through it, GCC will guess incorrectly. Sample problematic code: 3026 3027 struct S { ~S(); }; 3028 3029 extern void bar(); // Is implemented in Java and may throw exceptions. 3030 3031 void foo() 3032 { 3033 S s; 3034 bar(); 3035 } 3036 3037 The usual effect of an incorrect guess is a link failure, complaining 3038of a missing routine called '__gxx_personality_v0'. 3039 3040 You can inform the compiler that Java exceptions are to be used in a 3041translation unit, irrespective of what it might think, by writing 3042'#pragma GCC java_exceptions' at the head of the file. This '#pragma' 3043must appear before any functions that throw or catch exceptions, or run 3044destructors when exceptions are thrown through them. 3045 3046 3047File: gcj.info, Node: Synchronization, Next: Invocation, Prev: Exception Handling, Up: About CNI 3048 304911.15 Synchronization 3050===================== 3051 3052Each Java object has an implicit monitor. The Java VM uses the 3053instruction 'monitorenter' to acquire and lock a monitor, and 3054'monitorexit' to release it. 3055 3056 The corresponding CNI macros are 'JvMonitorEnter' and 'JvMonitorExit' 3057(JNI has similar methods 'MonitorEnter' and 'MonitorExit'). 3058 3059 The Java source language does not provide direct access to these 3060primitives. Instead, there is a 'synchronized' statement that does an 3061implicit 'monitorenter' before entry to the block, and does a 3062'monitorexit' on exit from the block. Note that the lock has to be 3063released even when the block is abnormally terminated by an exception, 3064which means there is an implicit 'try finally' surrounding 3065synchronization locks. 3066 3067 From C++, it makes sense to use a destructor to release a lock. CNI 3068defines the following utility class: 3069 3070 class JvSynchronize() { 3071 jobject obj; 3072 JvSynchronize(jobject o) { obj = o; JvMonitorEnter(o); } 3073 ~JvSynchronize() { JvMonitorExit(obj); } 3074 }; 3075 3076 So this Java code: 3077 3078 synchronized (OBJ) 3079 { 3080 CODE 3081 } 3082 3083might become this C++ code: 3084 3085 { 3086 JvSynchronize dummy (OBJ); 3087 CODE; 3088 } 3089 3090 Java also has methods with the 'synchronized' attribute. This is 3091equivalent to wrapping the entire method body in a 'synchronized' 3092statement. (Alternatively, an implementation could require the caller 3093to do the synchronization. This is not practical for a compiler, 3094because each virtual method call would have to test at run-time if 3095synchronization is needed.) Since in 'gcj' the 'synchronized' attribute 3096is handled by the method implementation, it is up to the programmer of a 3097synchronized native method to handle the synchronization (in the C++ 3098implementation of the method). In other words, you need to manually add 3099'JvSynchronize' in a 'native synchronized' method. 3100 3101 3102File: gcj.info, Node: Invocation, Next: Reflection, Prev: Synchronization, Up: About CNI 3103 310411.16 Invocation 3105================ 3106 3107CNI permits C++ applications to make calls into Java classes, in 3108addition to allowing Java code to call into C++. Several functions, 3109known as the "invocation API", are provided to support this. 3110 3111 -- Function: jint JvCreateJavaVM (JvVMInitArgs* VM_ARGS) 3112 3113 Initializes the Java runtime. This function performs essential 3114 initialization of the threads interface, garbage collector, 3115 exception handling and other key aspects of the runtime. It must 3116 be called once by an application with a non-Java 'main()' function, 3117 before any other Java or CNI calls are made. It is safe, but not 3118 recommended, to call 'JvCreateJavaVM()' more than once provided it 3119 is only called from a single thread. The VMARGS parameter can be 3120 used to specify initialization parameters for the Java runtime. It 3121 may be 'NULL'. 3122 3123 JvVMInitArgs represents a list of virtual machine initialization 3124 arguments. 'JvCreateJavaVM()' ignores the version field. 3125 3126 typedef struct JvVMOption 3127 { 3128 // a VM initialization option 3129 char* optionString; 3130 // extra information associated with this option 3131 void* extraInfo; 3132 } JvVMOption; 3133 3134 typedef struct JvVMInitArgs 3135 { 3136 // for compatibility with JavaVMInitArgs 3137 jint version; 3138 3139 // number of VM initialization options 3140 jint nOptions; 3141 3142 // an array of VM initialization options 3143 JvVMOption* options; 3144 3145 // true if the option parser should ignore unrecognized options 3146 jboolean ignoreUnrecognized; 3147 } JvVMInitArgs; 3148 3149 'JvCreateJavaVM()' returns '0' upon success, or '-1' if the runtime 3150 is already initialized. 3151 3152 _Note:_ In GCJ 3.1, the 'vm_args' parameter is ignored. It is 3153 recognized and used as of release 4.0. 3154 3155 -- Function: java::lang::Thread* JvAttachCurrentThread (jstring NAME, 3156 java::lang::ThreadGroup* GROUP) 3157 Registers an existing thread with the Java runtime. This must be 3158 called once from each thread, before that thread makes any other 3159 Java or CNI calls. It must be called after 'JvCreateJavaVM'. NAME 3160 specifies a name for the thread. It may be 'NULL', in which case a 3161 name will be generated. GROUP is the ThreadGroup in which this 3162 thread will be a member. If it is 'NULL', the thread will be a 3163 member of the main thread group. The return value is the Java 3164 'Thread' object that represents the thread. It is safe to call 3165 'JvAttachCurrentThread()' more than once from the same thread. If 3166 the thread is already attached, the call is ignored and the current 3167 thread object is returned. 3168 3169 -- Function: jint JvDetachCurrentThread () 3170 Unregisters a thread from the Java runtime. This should be called 3171 by threads that were attached using 'JvAttachCurrentThread()', 3172 after they have finished making calls to Java code. This ensures 3173 that any resources associated with the thread become eligible for 3174 garbage collection. This function returns '0' upon success, or 3175 '-1' if the current thread is not attached. 3176 317711.16.1 Handling uncaught exceptions 3178------------------------------------ 3179 3180If an exception is thrown from Java code called using the invocation 3181API, and no handler for the exception can be found, the runtime will 3182abort the application. In order to make the application more robust, it 3183is recommended that code which uses the invocation API be wrapped by a 3184top-level try/catch block that catches all Java exceptions. 3185 318611.16.2 Example 3187--------------- 3188 3189The following code demonstrates the use of the invocation API. In this 3190example, the C++ application initializes the Java runtime and attaches 3191itself. The 'java.lang.System' class is initialized in order to access 3192its 'out' field, and a Java string is printed. Finally, the thread is 3193detached from the runtime once it has finished making Java calls. 3194Everything is wrapped with a try/catch block to provide a default 3195handler for any uncaught exceptions. 3196 3197 The example can be compiled with 'c++ -c test.cc; gcj test.o'. 3198 3199 // test.cc 3200 #include <gcj/cni.h> 3201 #include <java/lang/System.h> 3202 #include <java/io/PrintStream.h> 3203 #include <java/lang/Throwable.h> 3204 3205 int main(int argc, char *argv[]) 3206 { 3207 using namespace java::lang; 3208 3209 try 3210 { 3211 JvCreateJavaVM(NULL); 3212 JvAttachCurrentThread(NULL, NULL); 3213 3214 String *message = JvNewStringLatin1("Hello from C++"); 3215 JvInitClass(&System::class$); 3216 System::out->println(message); 3217 3218 JvDetachCurrentThread(); 3219 } 3220 catch (Throwable *t) 3221 { 3222 System::err->println(JvNewStringLatin1("Unhandled Java exception:")); 3223 t->printStackTrace(); 3224 } 3225 } 3226 3227 3228File: gcj.info, Node: Reflection, Prev: Invocation, Up: About CNI 3229 323011.17 Reflection 3231================ 3232 3233Reflection is possible with CNI code, it functions similarly to how it 3234functions with JNI. 3235 3236 The types 'jfieldID' and 'jmethodID' are as in JNI. 3237 3238The functions: 3239 3240 * 'JvFromReflectedField', 3241 * 'JvFromReflectedMethod', 3242 * 'JvToReflectedField' 3243 * 'JvToFromReflectedMethod' 3244 3245will be added shortly, as will other functions corresponding to JNI. 3246 3247 3248File: gcj.info, Node: System properties, Next: Resources, Prev: About CNI, Up: Top 3249 325012 System properties 3251******************** 3252 3253The runtime behavior of the 'libgcj' library can be modified by setting 3254certain system properties. These properties can be compiled into the 3255program using the '-DNAME[=VALUE]' option to 'gcj' or by setting them 3256explicitly in the program by calling the 3257'java.lang.System.setProperty()' method. Some system properties are 3258only used for informational purposes (like giving a version number or a 3259user name). A program can inspect the current value of a property by 3260calling the 'java.lang.System.getProperty()' method. 3261 3262* Menu: 3263 3264* Standard Properties:: Standard properties supported by 'libgcj' 3265* GNU Classpath Properties:: Properties found in Classpath based libraries 3266* libgcj Runtime Properties:: Properties specific to 'libgcj' 3267 3268 3269File: gcj.info, Node: Standard Properties, Next: GNU Classpath Properties, Up: System properties 3270 327112.1 Standard Properties 3272======================== 3273 3274The following properties are normally found in all implementations of 3275the core libraries for the Java language. 3276 3277'java.version' 3278 The 'libgcj' version number. 3279 3280'java.vendor' 3281 Set to 'The Free Software Foundation, Inc.' 3282 3283'java.vendor.url' 3284 Set to <http://gcc.gnu.org/java/>. 3285 3286'java.home' 3287 The directory where 'gcj' was installed. Taken from the '--prefix' 3288 option given to 'configure'. 3289 3290'java.class.version' 3291 The class format version number supported by the libgcj byte code 3292 interpreter. (Currently '46.0') 3293 3294'java.vm.specification.version' 3295 The Virtual Machine Specification version implemented by 'libgcj'. 3296 (Currently '1.0') 3297 3298'java.vm.specification.vendor' 3299 The name of the Virtual Machine specification designer. 3300 3301'java.vm.specification.name' 3302 The name of the Virtual Machine specification (Set to 'Java Virtual 3303 Machine Specification'). 3304 3305'java.vm.version' 3306 The 'gcj' version number. 3307 3308'java.vm.vendor' 3309 Set to 'The Free Software Foundation, Inc.' 3310 3311'java.vm.name' 3312 Set to 'GNU libgcj'. 3313 3314'java.specification.version' 3315 The Runtime Environment specification version implemented by 3316 'libgcj'. (Currently set to '1.3') 3317 3318'java.specification.vendor' 3319 The Runtime Environment specification designer. 3320 3321'java.specification.name' 3322 The name of the Runtime Environment specification (Set to 'Java 3323 Platform API Specification'). 3324 3325'java.class.path' 3326 The paths (jar files, zip files and directories) used for finding 3327 class files. 3328 3329'java.library.path' 3330 Directory path used for finding native libraries. 3331 3332'java.io.tmpdir' 3333 The directory used to put temporary files in. 3334 3335'java.compiler' 3336 Name of the Just In Time compiler to use by the byte code 3337 interpreter. Currently not used in 'libgcj'. 3338 3339'java.ext.dirs' 3340 Directories containing jar files with extra libraries. Will be 3341 used when resolving classes. 3342 3343'java.protocol.handler.pkgs' 3344 A '|' separated list of package names that is used to find classes 3345 that implement handlers for 'java.net.URL'. 3346 3347'java.rmi.server.codebase' 3348 A list of URLs that is used by the 'java.rmi.server.RMIClassLoader' 3349 to load classes from. 3350 3351'jdbc.drivers' 3352 A list of class names that will be loaded by the 3353 'java.sql.DriverManager' when it starts up. 3354 3355'file.separator' 3356 The separator used in when directories are included in a filename 3357 (normally '/' or '\' ). 3358 3359'file.encoding' 3360 The default character encoding used when converting platform native 3361 files to Unicode (usually set to '8859_1'). 3362 3363'path.separator' 3364 The standard separator used when a string contains multiple paths 3365 (normally ':' or ';'), the string is usually not a valid character 3366 to use in normal directory names.) 3367 3368'line.separator' 3369 The default line separator used on the platform (normally '\n', 3370 '\r' or a combination of those two characters). 3371 3372'policy.provider' 3373 The class name used for the default policy provider returned by 3374 'java.security.Policy.getPolicy'. 3375 3376'user.name' 3377 The name of the user running the program. Can be the full name, 3378 the login name or empty if unknown. 3379 3380'user.home' 3381 The default directory to put user specific files in. 3382 3383'user.dir' 3384 The current working directory from which the program was started. 3385 3386'user.language' 3387 The default language as used by the 'java.util.Locale' class. 3388 3389'user.region' 3390 The default region as used by the 'java.util.Local' class. 3391 3392'user.variant' 3393 The default variant of the language and region local used. 3394 3395'user.timezone' 3396 The default timezone as used by the 'java.util.TimeZone' class. 3397 3398'os.name' 3399 The operating system/kernel name that the program runs on. 3400 3401'os.arch' 3402 The hardware that we are running on. 3403 3404'os.version' 3405 The version number of the operating system/kernel. 3406 3407'awt.appletWarning' 3408 The string to display when an untrusted applet is displayed. 3409 Returned by 'java.awt.Window.getWarningString()' when the window is 3410 "insecure". 3411 3412'awt.toolkit' 3413 The class name used for initializing the default 3414 'java.awt.Toolkit'. Defaults to 'gnu.awt.gtk.GtkToolkit'. 3415 3416'http.proxyHost' 3417 Name of proxy host for http connections. 3418 3419'http.proxyPort' 3420 Port number to use when a proxy host is in use. 3421 3422 3423File: gcj.info, Node: GNU Classpath Properties, Next: libgcj Runtime Properties, Prev: Standard Properties, Up: System properties 3424 342512.2 GNU Classpath Properties 3426============================= 3427 3428'libgcj' is based on the GNU Classpath (Essential Libraries for Java) a 3429GNU project to create free core class libraries for use with virtual 3430machines and compilers for the Java language. The following properties 3431are common to libraries based on GNU Classpath. 3432 3433'gcj.dumpobject' 3434 Enables printing serialization debugging by the 3435 'java.io.ObjectInput' and 'java.io.ObjectOutput' classes when set 3436 to something else then the empty string. Only used when running a 3437 debug build of the library. 3438 3439'gnu.classpath.vm.shortname' 3440 This is a succinct name of the virtual machine. For 'libgcj', this 3441 will always be 'libgcj'. 3442 3443'gnu.classpath.home.url' 3444 A base URL used for finding system property files (e.g., 3445 'classpath.security'). By default this is a 'file:' URL pointing 3446 to the 'lib' directory under 'java.home'. 3447 3448 3449File: gcj.info, Node: libgcj Runtime Properties, Prev: GNU Classpath Properties, Up: System properties 3450 345112.3 libgcj Runtime Properties 3452============================== 3453 3454The following properties are specific to the 'libgcj' runtime and will 3455normally not be found in other core libraries for the java language. 3456 3457'java.fullversion' 3458 The combination of 'java.vm.name' and 'java.vm.version'. 3459 3460'java.vm.info' 3461 Same as 'java.fullversion'. 3462 3463'impl.prefix' 3464 Used by the 'java.net.DatagramSocket' class when set to something 3465 else then the empty string. When set all newly created 3466 'DatagramSocket's will try to load a class 3467 'java.net.[impl.prefix]DatagramSocketImpl' instead of the normal 3468 'java.net.PlainDatagramSocketImpl'. 3469 3470'gnu.gcj.progname' 3471 The class or binary name that was used to invoke the program. This 3472 will be the name of the "main" class in the case where the 'gij' 3473 front end is used, or the program binary name in the case where an 3474 application is compiled to a native binary. 3475 3476'gnu.gcj.user.realname' 3477 The real name of the user, as taken from the password file. This 3478 may not always hold only the user's name (as some sites put extra 3479 information in this field). Also, this property is not available 3480 on all platforms. 3481 3482'gnu.gcj.runtime.NameFinder.use_addr2line' 3483 Whether an external process, 'addr2line', should be used to 3484 determine line number information when tracing the stack. Setting 3485 this to 'false' may suppress line numbers when printing stack 3486 traces and when using the java.util.logging infrastructure. 3487 However, performance may improve significantly for applications 3488 that print stack traces or make logging calls frequently. 3489 3490'gnu.gcj.runtime.NameFinder.show_raw' 3491 Whether the address of a stack frame should be printed when the 3492 line number is unavailable. Setting this to 'true' will cause the 3493 name of the object and the offset within that object to be printed 3494 when no line number is available. This allows for off-line 3495 decoding of stack traces if necessary debug information is 3496 available. The default is 'false', no raw addresses are printed. 3497 3498'gnu.gcj.runtime.NameFinder.remove_unknown' 3499 Whether stack frames for non-java code should be included in a 3500 stack trace. The default value is 'true', stack frames for 3501 non-java code are suppressed. Setting this to 'false' will cause 3502 any non-java stack frames to be printed in addition to frames for 3503 the java code. 3504 3505'gnu.gcj.runtime.VMClassLoader.library_control' 3506 This controls how shared libraries are automatically loaded by the 3507 built-in class loader. If this property is set to 'full', a full 3508 search is done for each requested class. If this property is set 3509 to 'cache', then any failed lookups are cached and not tried again. 3510 If this property is set to 'never' (the default), then lookups are 3511 never done. For more information, *Note Extensions::. 3512 3513'gnu.gcj.runtime.endorsed.dirs' 3514 This is like the standard 'java.endorsed.dirs', property, but 3515 specifies some extra directories which are searched after the 3516 standard endorsed directories. This is primarily useful for 3517 telling 'libgcj' about additional libraries which are ordinarily 3518 incorporated into the JDK, and which should be loaded by the 3519 bootstrap class loader, but which are not yet part of 'libgcj' 3520 itself for some reason. 3521 3522'gnu.gcj.jit.compiler' 3523 This is the full path to 'gcj' executable which should be used to 3524 compile classes just-in-time when 'ClassLoader.defineClass' is 3525 called. If not set, 'gcj' will not be invoked by the runtime; this 3526 can also be controlled via 'Compiler.disable'. 3527 3528'gnu.gcj.jit.options' 3529 This is a space-separated string of options which should be passed 3530 to 'gcj' when in JIT mode. If not set, a sensible default is 3531 chosen. 3532 3533'gnu.gcj.jit.cachedir' 3534 This is the directory where cached shared library files are stored. 3535 If not set, JIT compilation is disabled. This should never be set 3536 to a directory that is writable by any other user. 3537 3538'gnu.gcj.precompiled.db.path' 3539 This is a sequence of file names, each referring to a file created 3540 by 'gcj-dbtool'. These files will be used by 'libgcj' to find 3541 shared libraries corresponding to classes that are loaded from 3542 bytecode. 'libgcj' often has a built-in default database; it can 3543 be queried using 'gcj-dbtool -p'. 3544 3545 3546File: gcj.info, Node: Resources, Next: Index, Prev: System properties, Up: Top 3547 354813 Resources 3549************ 3550 3551While writing 'gcj' and 'libgcj' we have, of course, relied heavily on 3552documentation from Sun Microsystems. In particular we have used The 3553Java Language Specification (both first and second editions), the Java 3554Class Libraries (volumes one and two), and the Java Virtual Machine 3555Specification. In addition we've used Sun's online documentation. 3556 3557 The current 'gcj' home page is <http://gcc.gnu.org/java/>. 3558 3559 For more information on GCC, see <http://gcc.gnu.org/>. 3560 3561 Some 'libgcj' testing is done using the Mauve test suite. This is a 3562free software Java class library test suite which is being written 3563because the JCK is not free. See <http://www.sourceware.org/mauve/> for 3564more information. 3565 3566 3567File: gcj.info, Node: Index, Prev: Resources, Up: Top 3568 3569Index 3570***** 3571 3572�[index�] 3573* Menu: 3574 3575* class path: Input Options. (line 6) 3576* class$: Reference types. (line 20) 3577* elements on template<class T>: Arrays. (line 45) 3578* FDL, GNU Free Documentation License: GNU Free Documentation License. 3579 (line 6) 3580* GCJ_PROPERTIES: Extensions. (line 56) 3581* GCJ_PROPERTIES <1>: Extensions. (line 56) 3582* jclass: Reference types. (line 16) 3583* jobject: Reference types. (line 16) 3584* jstring: Reference types. (line 16) 3585* JvAllocBytes: Mixing with C++. (line 98) 3586* JvAttachCurrentThread: Invocation. (line 54) 3587* JvCreateJavaVM: Invocation. (line 10) 3588* JvDetachCurrentThread: Invocation. (line 68) 3589* JvFree: Memory allocation. (line 18) 3590* JvGetArrayLength: Arrays. (line 85) 3591* JvGetStringChars: Strings. (line 24) 3592* JvGetStringUTFLength: Strings. (line 28) 3593* JvGetStringUTFRegion: Strings. (line 32) 3594* JvMalloc: Memory allocation. (line 10) 3595* JvNewBooleanArray: Arrays. (line 82) 3596* JvNewObjectArray: Arrays. (line 55) 3597* JvNewString: Strings. (line 10) 3598* JvNewStringLatin1: Strings. (line 14) 3599* JvNewStringLatin1 <1>: Strings. (line 17) 3600* JvNewStringUTF: Strings. (line 20) 3601* JvPrimClass: Primitive types. (line 35) 3602* JvRealloc: Memory allocation. (line 14) 3603 3604 3605 3606Tag Table: 3607Node: Top2679 3608Node: Copying4098 3609Node: GNU Free Documentation License41630 3610Node: Invoking gcj66754 3611Node: Input and output files67517 3612Node: Input Options69039 3613Node: Encodings72314 3614Node: Warnings73520 3615Node: Linking74633 3616Node: Code Generation77566 3617Node: Configure-time Options84342 3618Node: Compatibility86082 3619Node: Limitations86601 3620Node: Extensions88179 3621Node: Invoking jcf-dump91270 3622Node: Invoking gij92215 3623Node: Invoking gcj-dbtool95471 3624Node: Invoking jv-convert97932 3625Node: Invoking grmic99011 3626Node: Invoking gc-analyze100397 3627Node: Invoking aot-compile101838 3628Node: Invoking rebuild-gcj-db102786 3629Node: About CNI103096 3630Node: Basic concepts104555 3631Node: Packages107451 3632Node: Primitive types109779 3633Node: Reference types111456 3634Node: Interfaces112540 3635Node: Objects and Classes113451 3636Node: Class Initialization115646 3637Node: Object allocation117989 3638Node: Memory allocation118779 3639Node: Arrays119411 3640Node: Methods122221 3641Node: Strings125042 3642Node: Mixing with C++126546 3643Node: Exception Handling130019 3644Node: Synchronization131654 3645Node: Invocation133643 3646Node: Reflection138595 3647Node: System properties139053 3648Node: Standard Properties139930 3649Node: GNU Classpath Properties144361 3650Node: libgcj Runtime Properties145407 3651Node: Resources149910 3652Node: Index150724 3653 3654End Tag Table 3655