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