1 This is doc/gcj.info, produced by makeinfo version 4.8 from
2 /scratch/mitchell/gcc-releases/gcc-4.0.1/gcc-4.0.1/gcc/java/gcj.texi.
4 Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation,
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being "GNU General Public License", the Front-Cover
11 texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the section entitled
13 "GNU Free Documentation License".
15 (a) The FSF's Front-Cover Text is:
19 (b) The FSF's Back-Cover Text is:
21 You have freedom to copy and modify this GNU Manual, like GNU
22 software. Copies published by the Free Software Foundation raise
23 funds for GNU development.
25 INFO-DIR-SECTION Programming
27 * Gcj: (gcj). Ahead-of-time compiler for the Java language
30 INFO-DIR-SECTION Individual utilities
32 * gcjh: (gcj)Invoking gcjh.
33 Generate header files from Java class files
34 * gjnih: (gcj)Invoking gjnih.
35 Generate JNI header files from Java class files
36 * jv-scan: (gcj)Invoking jv-scan.
37 Print information about Java source files
38 * jcf-dump: (gcj)Invoking jcf-dump.
39 Print information about Java class files
40 * gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
41 * gcj-dbtool: (gcj)Invoking gcj-dbtool.
42 Tool for manipulating class file databases.
43 * jv-convert: (gcj)Invoking jv-convert.
44 Convert file from one encoding to another
45 * grmic: (gcj)Invoking grmic.
46 Generate stubs for Remote Method Invocation.
47 * grmiregistry: (gcj)Invoking grmiregistry.
48 The remote object registry.
51 Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation,
54 Permission is granted to copy, distribute and/or modify this document
55 under the terms of the GNU Free Documentation License, Version 1.2 or
56 any later version published by the Free Software Foundation; with the
57 Invariant Sections being "GNU General Public License", the Front-Cover
58 texts being (a) (see below), and with the Back-Cover Texts being (b)
59 (see below). A copy of the license is included in the section entitled
60 "GNU Free Documentation License".
62 (a) The FSF's Front-Cover Text is:
66 (b) The FSF's Back-Cover Text is:
68 You have freedom to copy and modify this GNU Manual, like GNU
69 software. Copies published by the Free Software Foundation raise
70 funds for GNU development.
73 File: gcj.info, Node: Top, Next: Copying, Up: (dir)
78 This manual describes how to use `gcj', the GNU compiler for the Java
79 programming language. `gcj' can generate both `.class' files and
80 object files, and it can read both Java source code and `.class' files.
84 * Copying:: The GNU General Public License
85 * GNU Free Documentation License::
86 How you can share and copy this manual
87 * Invoking gcj:: Compiler options supported by `gcj'
88 * Compatibility:: Compatibility between gcj and other tools for Java
89 * Invoking gcjh:: Generate header files from class files
90 * Invoking gjnih:: Generate JNI header files from class files
91 * Invoking jv-scan:: Print information about source files
92 * Invoking jcf-dump:: Print information about class files
93 * Invoking gij:: Interpreting Java bytecodes
94 * Invoking gcj-dbtool:: Tool for manipulating class file databases.
95 * Invoking jv-convert:: Converting from one encoding to another
96 * Invoking grmic:: Generate stubs for Remote Method Invocation.
97 * Invoking grmiregistry:: The remote object registry.
98 * About CNI:: Description of the Compiled Native Interface
99 * System properties:: Modifying runtime behavior of the libgcj library
100 * Resources:: Where to look for more information
103 File: gcj.info, Node: Copying, Next: GNU Free Documentation License, Prev: Top, Up: Top
105 GNU GENERAL PUBLIC LICENSE
106 **************************
110 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
111 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
113 Everyone is permitted to copy and distribute verbatim copies
114 of this license document, but changing it is not allowed.
119 The licenses for most software are designed to take away your freedom
120 to share and change it. By contrast, the GNU General Public License is
121 intended to guarantee your freedom to share and change free
122 software--to make sure the software is free for all its users. This
123 General Public License applies to most of the Free Software
124 Foundation's software and to any other program whose authors commit to
125 using it. (Some other Free Software Foundation software is covered by
126 the GNU Library General Public License instead.) You can apply it to
129 When we speak of free software, we are referring to freedom, not
130 price. Our General Public Licenses are designed to make sure that you
131 have the freedom to distribute copies of free software (and charge for
132 this service if you wish), that you receive source code or can get it
133 if you want it, that you can change the software or use pieces of it in
134 new free programs; and that you know you can do these things.
136 To protect your rights, we need to make restrictions that forbid
137 anyone to deny you these rights or to ask you to surrender the rights.
138 These restrictions translate to certain responsibilities for you if you
139 distribute copies of the software, or if you modify it.
141 For example, if you distribute copies of such a program, whether
142 gratis or for a fee, you must give the recipients all the rights that
143 you have. You must make sure that they, too, receive or can get the
144 source code. And you must show them these terms so they know their
147 We protect your rights with two steps: (1) copyright the software,
148 and (2) offer you this license which gives you legal permission to copy,
149 distribute and/or modify the software.
151 Also, for each author's protection and ours, we want to make certain
152 that everyone understands that there is no warranty for this free
153 software. If the software is modified by someone else and passed on, we
154 want its recipients to know that what they have is not the original, so
155 that any problems introduced by others will not reflect on the original
156 authors' reputations.
158 Finally, any free program is threatened constantly by software
159 patents. We wish to avoid the danger that redistributors of a free
160 program will individually obtain patent licenses, in effect making the
161 program proprietary. To prevent this, we have made it clear that any
162 patent must be licensed for everyone's free use or not licensed at all.
164 The precise terms and conditions for copying, distribution and
167 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
168 0. This License applies to any program or other work which contains a
169 notice placed by the copyright holder saying it may be distributed
170 under the terms of this General Public License. The "Program",
171 below, refers to any such program or work, and a "work based on
172 the Program" means either the Program or any derivative work under
173 copyright law: that is to say, a work containing the Program or a
174 portion of it, either verbatim or with modifications and/or
175 translated into another language. (Hereinafter, translation is
176 included without limitation in the term "modification".) Each
177 licensee is addressed as "you".
179 Activities other than copying, distribution and modification are
180 not covered by this License; they are outside its scope. The act
181 of running the Program is not restricted, and the output from the
182 Program is covered only if its contents constitute a work based on
183 the Program (independent of having been made by running the
184 Program). Whether that is true depends on what the Program does.
186 1. You may copy and distribute verbatim copies of the Program's
187 source code as you receive it, in any medium, provided that you
188 conspicuously and appropriately publish on each copy an appropriate
189 copyright notice and disclaimer of warranty; keep intact all the
190 notices that refer to this License and to the absence of any
191 warranty; and give any other recipients of the Program a copy of
192 this License along with the Program.
194 You may charge a fee for the physical act of transferring a copy,
195 and you may at your option offer warranty protection in exchange
198 2. You may modify your copy or copies of the Program or any portion
199 of it, thus forming a work based on the Program, and copy and
200 distribute such modifications or work under the terms of Section 1
201 above, provided that you also meet all of these conditions:
203 a. You must cause the modified files to carry prominent notices
204 stating that you changed the files and the date of any change.
206 b. You must cause any work that you distribute or publish, that
207 in whole or in part contains or is derived from the Program
208 or any part thereof, to be licensed as a whole at no charge
209 to all third parties under the terms of this License.
211 c. If the modified program normally reads commands interactively
212 when run, you must cause it, when started running for such
213 interactive use in the most ordinary way, to print or display
214 an announcement including an appropriate copyright notice and
215 a notice that there is no warranty (or else, saying that you
216 provide a warranty) and that users may redistribute the
217 program under these conditions, and telling the user how to
218 view a copy of this License. (Exception: if the Program
219 itself is interactive but does not normally print such an
220 announcement, your work based on the Program is not required
221 to print an announcement.)
223 These requirements apply to the modified work as a whole. If
224 identifiable sections of that work are not derived from the
225 Program, and can be reasonably considered independent and separate
226 works in themselves, then this License, and its terms, do not
227 apply to those sections when you distribute them as separate
228 works. But when you distribute the same sections as part of a
229 whole which is a work based on the Program, the distribution of
230 the whole must be on the terms of this License, whose permissions
231 for other licensees extend to the entire whole, and thus to each
232 and every part regardless of who wrote it.
234 Thus, it is not the intent of this section to claim rights or
235 contest your rights to work written entirely by you; rather, the
236 intent is to exercise the right to control the distribution of
237 derivative or collective works based on the Program.
239 In addition, mere aggregation of another work not based on the
240 Program with the Program (or with a work based on the Program) on
241 a volume of a storage or distribution medium does not bring the
242 other work under the scope of this License.
244 3. You may copy and distribute the Program (or a work based on it,
245 under Section 2) in object code or executable form under the terms
246 of Sections 1 and 2 above provided that you also do one of the
249 a. Accompany it with the complete corresponding machine-readable
250 source code, which must be distributed under the terms of
251 Sections 1 and 2 above on a medium customarily used for
252 software interchange; or,
254 b. Accompany it with a written offer, valid for at least three
255 years, to give any third party, for a charge no more than your
256 cost of physically performing source distribution, a complete
257 machine-readable copy of the corresponding source code, to be
258 distributed under the terms of Sections 1 and 2 above on a
259 medium customarily used for software interchange; or,
261 c. Accompany it with the information you received as to the offer
262 to distribute corresponding source code. (This alternative is
263 allowed only for noncommercial distribution and only if you
264 received the program in object code or executable form with
265 such an offer, in accord with Subsection b above.)
267 The source code for a work means the preferred form of the work for
268 making modifications to it. For an executable work, complete
269 source code means all the source code for all modules it contains,
270 plus any associated interface definition files, plus the scripts
271 used to control compilation and installation of the executable.
272 However, as a special exception, the source code distributed need
273 not include anything that is normally distributed (in either
274 source or binary form) with the major components (compiler,
275 kernel, and so on) of the operating system on which the executable
276 runs, unless that component itself accompanies the executable.
278 If distribution of executable or object code is made by offering
279 access to copy from a designated place, then offering equivalent
280 access to copy the source code from the same place counts as
281 distribution of the source code, even though third parties are not
282 compelled to copy the source along with the object code.
284 4. You may not copy, modify, sublicense, or distribute the Program
285 except as expressly provided under this License. Any attempt
286 otherwise to copy, modify, sublicense or distribute the Program is
287 void, and will automatically terminate your rights under this
288 License. However, parties who have received copies, or rights,
289 from you under this License will not have their licenses
290 terminated so long as such parties remain in full compliance.
292 5. You are not required to accept this License, since you have not
293 signed it. However, nothing else grants you permission to modify
294 or distribute the Program or its derivative works. These actions
295 are prohibited by law if you do not accept this License.
296 Therefore, by modifying or distributing the Program (or any work
297 based on the Program), you indicate your acceptance of this
298 License to do so, and all its terms and conditions for copying,
299 distributing or modifying the Program or works based on it.
301 6. Each time you redistribute the Program (or any work based on the
302 Program), the recipient automatically receives a license from the
303 original licensor to copy, distribute or modify the Program
304 subject to these terms and conditions. You may not impose any
305 further restrictions on the recipients' exercise of the rights
306 granted herein. You are not responsible for enforcing compliance
307 by third parties to this License.
309 7. If, as a consequence of a court judgment or allegation of patent
310 infringement or for any other reason (not limited to patent
311 issues), conditions are imposed on you (whether by court order,
312 agreement or otherwise) that contradict the conditions of this
313 License, they do not excuse you from the conditions of this
314 License. If you cannot distribute so as to satisfy simultaneously
315 your obligations under this License and any other pertinent
316 obligations, then as a consequence you may not distribute the
317 Program at all. For example, if a patent license would not permit
318 royalty-free redistribution of the Program by all those who
319 receive copies directly or indirectly through you, then the only
320 way you could satisfy both it and this License would be to refrain
321 entirely from distribution of the Program.
323 If any portion of this section is held invalid or unenforceable
324 under any particular circumstance, the balance of the section is
325 intended to apply and the section as a whole is intended to apply
326 in other circumstances.
328 It is not the purpose of this section to induce you to infringe any
329 patents or other property right claims or to contest validity of
330 any such claims; this section has the sole purpose of protecting
331 the integrity of the free software distribution system, which is
332 implemented by public license practices. Many people have made
333 generous contributions to the wide range of software distributed
334 through that system in reliance on consistent application of that
335 system; it is up to the author/donor to decide if he or she is
336 willing to distribute software through any other system and a
337 licensee cannot impose that choice.
339 This section is intended to make thoroughly clear what is believed
340 to be a consequence of the rest of this License.
342 8. If the distribution and/or use of the Program is restricted in
343 certain countries either by patents or by copyrighted interfaces,
344 the original copyright holder who places the Program under this
345 License may add an explicit geographical distribution limitation
346 excluding those countries, so that distribution is permitted only
347 in or among countries not thus excluded. In such case, this
348 License incorporates the limitation as if written in the body of
351 9. The Free Software Foundation may publish revised and/or new
352 versions of the General Public License from time to time. Such
353 new versions will be similar in spirit to the present version, but
354 may differ in detail to address new problems or concerns.
356 Each version is given a distinguishing version number. If the
357 Program specifies a version number of this License which applies
358 to it and "any later version", you have the option of following
359 the terms and conditions either of that version or of any later
360 version published by the Free Software Foundation. If the Program
361 does not specify a version number of this License, you may choose
362 any version ever published by the Free Software Foundation.
364 10. If you wish to incorporate parts of the Program into other free
365 programs whose distribution conditions are different, write to the
366 author to ask for permission. For software which is copyrighted
367 by the Free Software Foundation, write to the Free Software
368 Foundation; we sometimes make exceptions for this. Our decision
369 will be guided by the two goals of preserving the free status of
370 all derivatives of our free software and of promoting the sharing
371 and reuse of software generally.
374 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
375 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
376 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
377 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
378 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
379 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
380 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
381 QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
382 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
383 SERVICING, REPAIR OR CORRECTION.
385 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
386 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
387 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
388 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
389 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
390 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
391 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
392 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
393 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
394 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
396 END OF TERMS AND CONDITIONS
397 How to Apply These Terms to Your New Programs
398 =============================================
400 If you develop a new program, and you want it to be of the greatest
401 possible use to the public, the best way to achieve this is to make it
402 free software which everyone can redistribute and change under these
405 To do so, attach the following notices to the program. It is safest
406 to attach them to the start of each source file to most effectively
407 convey the exclusion of warranty; and each file should have at least
408 the "copyright" line and a pointer to where the full notice is found.
410 ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
411 Copyright (C) YEAR NAME OF AUTHOR
413 This program is free software; you can redistribute it and/or modify
414 it under the terms of the GNU General Public License as published by
415 the Free Software Foundation; either version 2 of the License, or
416 (at your option) any later version.
418 This program is distributed in the hope that it will be useful,
419 but WITHOUT ANY WARRANTY; without even the implied warranty of
420 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
421 GNU General Public License for more details.
423 You should have received a copy of the GNU General Public License
424 along with this program; if not, write to the Free Software Foundation,
425 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
427 Also add information on how to contact you by electronic and paper
430 If the program is interactive, make it output a short notice like
431 this when it starts in an interactive mode:
433 Gnomovision version 69, Copyright (C) YEAR NAME OF AUTHOR
434 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
436 This is free software, and you are welcome to redistribute it
437 under certain conditions; type `show c' for details.
439 The hypothetical commands `show w' and `show c' should show the
440 appropriate parts of the General Public License. Of course, the
441 commands you use may be called something other than `show w' and `show
442 c'; they could even be mouse-clicks or menu items--whatever suits your
445 You should also get your employer (if you work as a programmer) or
446 your school, if any, to sign a "copyright disclaimer" for the program,
447 if necessary. Here is a sample; alter the names:
449 Yoyodyne, Inc., hereby disclaims all copyright interest in the program
450 `Gnomovision' (which makes passes at compilers) written by James Hacker.
452 SIGNATURE OF TY COON, 1 April 1989
453 Ty Coon, President of Vice
455 This General Public License does not permit incorporating your
456 program into proprietary programs. If your program is a subroutine
457 library, you may consider it more useful to permit linking proprietary
458 applications with the library. If this is what you want to do, use the
459 GNU Library General Public License instead of this License.
462 File: gcj.info, Node: GNU Free Documentation License, Next: Invoking gcj, Prev: Copying, Up: Top
464 GNU Free Documentation License
465 ******************************
467 Version 1.2, November 2002
469 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
470 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
472 Everyone is permitted to copy and distribute verbatim copies
473 of this license document, but changing it is not allowed.
477 The purpose of this License is to make a manual, textbook, or other
478 functional and useful document "free" in the sense of freedom: to
479 assure everyone the effective freedom to copy and redistribute it,
480 with or without modifying it, either commercially or
481 noncommercially. Secondarily, this License preserves for the
482 author and publisher a way to get credit for their work, while not
483 being considered responsible for modifications made by others.
485 This License is a kind of "copyleft", which means that derivative
486 works of the document must themselves be free in the same sense.
487 It complements the GNU General Public License, which is a copyleft
488 license designed for free software.
490 We have designed this License in order to use it for manuals for
491 free software, because free software needs free documentation: a
492 free program should come with manuals providing the same freedoms
493 that the software does. But this License is not limited to
494 software manuals; it can be used for any textual work, regardless
495 of subject matter or whether it is published as a printed book.
496 We recommend this License principally for works whose purpose is
497 instruction or reference.
499 1. APPLICABILITY AND DEFINITIONS
501 This License applies to any manual or other work, in any medium,
502 that contains a notice placed by the copyright holder saying it
503 can be distributed under the terms of this License. Such a notice
504 grants a world-wide, royalty-free license, unlimited in duration,
505 to use that work under the conditions stated herein. The
506 "Document", below, refers to any such manual or work. Any member
507 of the public is a licensee, and is addressed as "you". You
508 accept the license if you copy, modify or distribute the work in a
509 way requiring permission under copyright law.
511 A "Modified Version" of the Document means any work containing the
512 Document or a portion of it, either copied verbatim, or with
513 modifications and/or translated into another language.
515 A "Secondary Section" is a named appendix or a front-matter section
516 of the Document that deals exclusively with the relationship of the
517 publishers or authors of the Document to the Document's overall
518 subject (or to related matters) and contains nothing that could
519 fall directly within that overall subject. (Thus, if the Document
520 is in part a textbook of mathematics, a Secondary Section may not
521 explain any mathematics.) The relationship could be a matter of
522 historical connection with the subject or with related matters, or
523 of legal, commercial, philosophical, ethical or political position
526 The "Invariant Sections" are certain Secondary Sections whose
527 titles are designated, as being those of Invariant Sections, in
528 the notice that says that the Document is released under this
529 License. If a section does not fit the above definition of
530 Secondary then it is not allowed to be designated as Invariant.
531 The Document may contain zero Invariant Sections. If the Document
532 does not identify any Invariant Sections then there are none.
534 The "Cover Texts" are certain short passages of text that are
535 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
536 that says that the Document is released under this License. A
537 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
540 A "Transparent" copy of the Document means a machine-readable copy,
541 represented in a format whose specification is available to the
542 general public, that is suitable for revising the document
543 straightforwardly with generic text editors or (for images
544 composed of pixels) generic paint programs or (for drawings) some
545 widely available drawing editor, and that is suitable for input to
546 text formatters or for automatic translation to a variety of
547 formats suitable for input to text formatters. A copy made in an
548 otherwise Transparent file format whose markup, or absence of
549 markup, has been arranged to thwart or discourage subsequent
550 modification by readers is not Transparent. An image format is
551 not Transparent if used for any substantial amount of text. A
552 copy that is not "Transparent" is called "Opaque".
554 Examples of suitable formats for Transparent copies include plain
555 ASCII without markup, Texinfo input format, LaTeX input format,
556 SGML or XML using a publicly available DTD, and
557 standard-conforming simple HTML, PostScript or PDF designed for
558 human modification. Examples of transparent image formats include
559 PNG, XCF and JPG. Opaque formats include proprietary formats that
560 can be read and edited only by proprietary word processors, SGML or
561 XML for which the DTD and/or processing tools are not generally
562 available, and the machine-generated HTML, PostScript or PDF
563 produced by some word processors for output purposes only.
565 The "Title Page" means, for a printed book, the title page itself,
566 plus such following pages as are needed to hold, legibly, the
567 material this License requires to appear in the title page. For
568 works in formats which do not have any title page as such, "Title
569 Page" means the text near the most prominent appearance of the
570 work's title, preceding the beginning of the body of the text.
572 A section "Entitled XYZ" means a named subunit of the Document
573 whose title either is precisely XYZ or contains XYZ in parentheses
574 following text that translates XYZ in another language. (Here XYZ
575 stands for a specific section name mentioned below, such as
576 "Acknowledgements", "Dedications", "Endorsements", or "History".)
577 To "Preserve the Title" of such a section when you modify the
578 Document means that it remains a section "Entitled XYZ" according
581 The Document may include Warranty Disclaimers next to the notice
582 which states that this License applies to the Document. These
583 Warranty Disclaimers are considered to be included by reference in
584 this License, but only as regards disclaiming warranties: any other
585 implication that these Warranty Disclaimers may have is void and
586 has no effect on the meaning of this License.
590 You may copy and distribute the Document in any medium, either
591 commercially or noncommercially, provided that this License, the
592 copyright notices, and the license notice saying this License
593 applies to the Document are reproduced in all copies, and that you
594 add no other conditions whatsoever to those of this License. You
595 may not use technical measures to obstruct or control the reading
596 or further copying of the copies you make or distribute. However,
597 you may accept compensation in exchange for copies. If you
598 distribute a large enough number of copies you must also follow
599 the conditions in section 3.
601 You may also lend copies, under the same conditions stated above,
602 and you may publicly display copies.
604 3. COPYING IN QUANTITY
606 If you publish printed copies (or copies in media that commonly
607 have printed covers) of the Document, numbering more than 100, and
608 the Document's license notice requires Cover Texts, you must
609 enclose the copies in covers that carry, clearly and legibly, all
610 these Cover Texts: Front-Cover Texts on the front cover, and
611 Back-Cover Texts on the back cover. Both covers must also clearly
612 and legibly identify you as the publisher of these copies. The
613 front cover must present the full title with all words of the
614 title equally prominent and visible. You may add other material
615 on the covers in addition. Copying with changes limited to the
616 covers, as long as they preserve the title of the Document and
617 satisfy these conditions, can be treated as verbatim copying in
620 If the required texts for either cover are too voluminous to fit
621 legibly, you should put the first ones listed (as many as fit
622 reasonably) on the actual cover, and continue the rest onto
625 If you publish or distribute Opaque copies of the Document
626 numbering more than 100, you must either include a
627 machine-readable Transparent copy along with each Opaque copy, or
628 state in or with each Opaque copy a computer-network location from
629 which the general network-using public has access to download
630 using public-standard network protocols a complete Transparent
631 copy of the Document, free of added material. If you use the
632 latter option, you must take reasonably prudent steps, when you
633 begin distribution of Opaque copies in quantity, to ensure that
634 this Transparent copy will remain thus accessible at the stated
635 location until at least one year after the last time you
636 distribute an Opaque copy (directly or through your agents or
637 retailers) of that edition to the public.
639 It is requested, but not required, that you contact the authors of
640 the Document well before redistributing any large number of
641 copies, to give them a chance to provide you with an updated
642 version of the Document.
646 You may copy and distribute a Modified Version of the Document
647 under the conditions of sections 2 and 3 above, provided that you
648 release the Modified Version under precisely this License, with
649 the Modified Version filling the role of the Document, thus
650 licensing distribution and modification of the Modified Version to
651 whoever possesses a copy of it. In addition, you must do these
652 things in the Modified Version:
654 A. Use in the Title Page (and on the covers, if any) a title
655 distinct from that of the Document, and from those of
656 previous versions (which should, if there were any, be listed
657 in the History section of the Document). You may use the
658 same title as a previous version if the original publisher of
659 that version gives permission.
661 B. List on the Title Page, as authors, one or more persons or
662 entities responsible for authorship of the modifications in
663 the Modified Version, together with at least five of the
664 principal authors of the Document (all of its principal
665 authors, if it has fewer than five), unless they release you
666 from this requirement.
668 C. State on the Title page the name of the publisher of the
669 Modified Version, as the publisher.
671 D. Preserve all the copyright notices of the Document.
673 E. Add an appropriate copyright notice for your modifications
674 adjacent to the other copyright notices.
676 F. Include, immediately after the copyright notices, a license
677 notice giving the public permission to use the Modified
678 Version under the terms of this License, in the form shown in
681 G. Preserve in that license notice the full lists of Invariant
682 Sections and required Cover Texts given in the Document's
685 H. Include an unaltered copy of this License.
687 I. Preserve the section Entitled "History", Preserve its Title,
688 and add to it an item stating at least the title, year, new
689 authors, and publisher of the Modified Version as given on
690 the Title Page. If there is no section Entitled "History" in
691 the Document, create one stating the title, year, authors,
692 and publisher of the Document as given on its Title Page,
693 then add an item describing the Modified Version as stated in
694 the previous sentence.
696 J. Preserve the network location, if any, given in the Document
697 for public access to a Transparent copy of the Document, and
698 likewise the network locations given in the Document for
699 previous versions it was based on. These may be placed in
700 the "History" section. You may omit a network location for a
701 work that was published at least four years before the
702 Document itself, or if the original publisher of the version
703 it refers to gives permission.
705 K. For any section Entitled "Acknowledgements" or "Dedications",
706 Preserve the Title of the section, and preserve in the
707 section all the substance and tone of each of the contributor
708 acknowledgements and/or dedications given therein.
710 L. Preserve all the Invariant Sections of the Document,
711 unaltered in their text and in their titles. Section numbers
712 or the equivalent are not considered part of the section
715 M. Delete any section Entitled "Endorsements". Such a section
716 may not be included in the Modified Version.
718 N. Do not retitle any existing section to be Entitled
719 "Endorsements" or to conflict in title with any Invariant
722 O. Preserve any Warranty Disclaimers.
724 If the Modified Version includes new front-matter sections or
725 appendices that qualify as Secondary Sections and contain no
726 material copied from the Document, you may at your option
727 designate some or all of these sections as invariant. To do this,
728 add their titles to the list of Invariant Sections in the Modified
729 Version's license notice. These titles must be distinct from any
730 other section titles.
732 You may add a section Entitled "Endorsements", provided it contains
733 nothing but endorsements of your Modified Version by various
734 parties--for example, statements of peer review or that the text
735 has been approved by an organization as the authoritative
736 definition of a standard.
738 You may add a passage of up to five words as a Front-Cover Text,
739 and a passage of up to 25 words as a Back-Cover Text, to the end
740 of the list of Cover Texts in the Modified Version. Only one
741 passage of Front-Cover Text and one of Back-Cover Text may be
742 added by (or through arrangements made by) any one entity. If the
743 Document already includes a cover text for the same cover,
744 previously added by you or by arrangement made by the same entity
745 you are acting on behalf of, you may not add another; but you may
746 replace the old one, on explicit permission from the previous
747 publisher that added the old one.
749 The author(s) and publisher(s) of the Document do not by this
750 License give permission to use their names for publicity for or to
751 assert or imply endorsement of any Modified Version.
753 5. COMBINING DOCUMENTS
755 You may combine the Document with other documents released under
756 this License, under the terms defined in section 4 above for
757 modified versions, provided that you include in the combination
758 all of the Invariant Sections of all of the original documents,
759 unmodified, and list them all as Invariant Sections of your
760 combined work in its license notice, and that you preserve all
761 their Warranty Disclaimers.
763 The combined work need only contain one copy of this License, and
764 multiple identical Invariant Sections may be replaced with a single
765 copy. If there are multiple Invariant Sections with the same name
766 but different contents, make the title of each such section unique
767 by adding at the end of it, in parentheses, the name of the
768 original author or publisher of that section if known, or else a
769 unique number. Make the same adjustment to the section titles in
770 the list of Invariant Sections in the license notice of the
773 In the combination, you must combine any sections Entitled
774 "History" in the various original documents, forming one section
775 Entitled "History"; likewise combine any sections Entitled
776 "Acknowledgements", and any sections Entitled "Dedications". You
777 must delete all sections Entitled "Endorsements."
779 6. COLLECTIONS OF DOCUMENTS
781 You may make a collection consisting of the Document and other
782 documents released under this License, and replace the individual
783 copies of this License in the various documents with a single copy
784 that is included in the collection, provided that you follow the
785 rules of this License for verbatim copying of each of the
786 documents in all other respects.
788 You may extract a single document from such a collection, and
789 distribute it individually under this License, provided you insert
790 a copy of this License into the extracted document, and follow
791 this License in all other respects regarding verbatim copying of
794 7. AGGREGATION WITH INDEPENDENT WORKS
796 A compilation of the Document or its derivatives with other
797 separate and independent documents or works, in or on a volume of
798 a storage or distribution medium, is called an "aggregate" if the
799 copyright resulting from the compilation is not used to limit the
800 legal rights of the compilation's users beyond what the individual
801 works permit. When the Document is included an aggregate, this
802 License does not apply to the other works in the aggregate which
803 are not themselves derivative works of the Document.
805 If the Cover Text requirement of section 3 is applicable to these
806 copies of the Document, then if the Document is less than one half
807 of the entire aggregate, the Document's Cover Texts may be placed
808 on covers that bracket the Document within the aggregate, or the
809 electronic equivalent of covers if the Document is in electronic
810 form. Otherwise they must appear on printed covers that bracket
815 Translation is considered a kind of modification, so you may
816 distribute translations of the Document under the terms of section
817 4. Replacing Invariant Sections with translations requires special
818 permission from their copyright holders, but you may include
819 translations of some or all Invariant Sections in addition to the
820 original versions of these Invariant Sections. You may include a
821 translation of this License, and all the license notices in the
822 Document, and any Warrany Disclaimers, provided that you also
823 include the original English version of this License and the
824 original versions of those notices and disclaimers. In case of a
825 disagreement between the translation and the original version of
826 this License or a notice or disclaimer, the original version will
829 If a section in the Document is Entitled "Acknowledgements",
830 "Dedications", or "History", the requirement (section 4) to
831 Preserve its Title (section 1) will typically require changing the
836 You may not copy, modify, sublicense, or distribute the Document
837 except as expressly provided for under this License. Any other
838 attempt to copy, modify, sublicense or distribute the Document is
839 void, and will automatically terminate your rights under this
840 License. However, parties who have received copies, or rights,
841 from you under this License will not have their licenses
842 terminated so long as such parties remain in full compliance.
844 10. FUTURE REVISIONS OF THIS LICENSE
846 The Free Software Foundation may publish new, revised versions of
847 the GNU Free Documentation License from time to time. Such new
848 versions will be similar in spirit to the present version, but may
849 differ in detail to address new problems or concerns. See
850 `http://www.gnu.org/copyleft/'.
852 Each version of the License is given a distinguishing version
853 number. If the Document specifies that a particular numbered
854 version of this License "or any later version" applies to it, you
855 have the option of following the terms and conditions either of
856 that specified version or of any later version that has been
857 published (not as a draft) by the Free Software Foundation. If
858 the Document does not specify a version number of this License,
859 you may choose any version ever published (not as a draft) by the
860 Free Software Foundation.
862 ADDENDUM: How to use this License for your documents
863 ====================================================
865 To use this License in a document you have written, include a copy of
866 the License in the document and put the following copyright and license
867 notices just after the title page:
869 Copyright (C) YEAR YOUR NAME.
870 Permission is granted to copy, distribute and/or modify this document
871 under the terms of the GNU Free Documentation License, Version 1.2
872 or any later version published by the Free Software Foundation;
873 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
874 A copy of the license is included in the section entitled ``GNU
875 Free Documentation License''.
877 If you have Invariant Sections, Front-Cover Texts and Back-Cover
878 Texts, replace the "with...Texts." line with this:
880 with the Invariant Sections being LIST THEIR TITLES, with
881 the Front-Cover Texts being LIST, and with the Back-Cover Texts
884 If you have Invariant Sections without Cover Texts, or some other
885 combination of the three, merge those two alternatives to suit the
888 If your document contains nontrivial examples of program code, we
889 recommend releasing these examples in parallel under your choice of
890 free software license, such as the GNU General Public License, to
891 permit their use in free software.
894 File: gcj.info, Node: Invoking gcj, Next: Compatibility, Prev: GNU Free Documentation License, Up: Top
899 As `gcj' is just another front end to `gcc', it supports many of the
900 same options as gcc. *Note Option Summary: (gcc)Option Summary. This
901 manual only documents the options specific to `gcj'.
905 * Input and output files::
906 * Input Options:: How gcj finds files
907 * Encodings:: Options controlling source file encoding
908 * Warnings:: Options controlling warnings specific to gcj
909 * Linking:: Options for making an executable
910 * Code Generation:: Options controlling the output of gcj
911 * Configure-time Options:: Options you won't use
914 File: gcj.info, Node: Input and output files, Next: Input Options, Up: Invoking gcj
916 1.1 Input and output files
917 ==========================
919 A `gcj' command is like a `gcc' command, in that it consists of a
920 number of options and file names. The following kinds of input file
931 An archive containing one or more `.class' files, all of which are
932 compiled. The archive may be compressed. Files in an archive
933 which don't end with `.class' are treated as resource files; they
934 are compiled into the resulting object file as `core:' URLs.
937 A file containing a whitespace-separated list of input file names.
938 (Currently, these must all be `.java' source files, but that may
939 change.) Each named file is compiled, just as if it had been on
945 Libraries to use when linking. See the `gcc' manual.
947 You can specify more than one input file on the `gcj' command line,
948 in which case they will all be compiled. If you specify a `-o FILENAME'
949 option, all the input files will be compiled together, producing a
950 single output file, named FILENAME. This is allowed even when using
951 `-S' or `-c', but not when using `-C' or `--resource'. (This is an
952 extension beyond the what plain `gcc' allows.) (If more than one input
953 file is specified, all must currently be `.java' files, though we hope
957 File: gcj.info, Node: Input Options, Next: Encodings, Prev: Input and output files, Up: Invoking gcj
962 `gcj' has options to control where it looks to find files it needs.
963 For instance, `gcj' might need to load a class that is referenced by
964 the file it has been asked to compile. Like other compilers for the
965 Java language, `gcj' has a notion of a "class path". There are several
966 options and environment variables which can be used to manipulate the
967 class path. When `gcj' looks for a given class, it searches the class
968 path looking for matching `.class' or `.java' file. `gcj' comes with a
969 built-in class path which points at the installed `libgcj.jar', a file
970 which contains all the standard classes.
972 In the below, a directory or path component can refer either to an
973 actual directory on the filesystem, or to a `.zip' or `.jar' file,
974 which `gcj' will search as if it is a directory.
977 All directories specified by `-I' are kept in order and prepended
978 to the class path constructed from all the other options. Unless
979 compatibility with tools like `javac' is important, we recommend
980 always using `-I' instead of the other options for manipulating the
984 This sets the class path to PATH, a colon-separated list of paths
985 (on Windows-based systems, a semicolon-separate list of paths).
986 This does not override the builtin ("boot") search path.
989 Deprecated synonym for `--classpath'.
991 `--bootclasspath=PATH'
992 Where to find the standard builtin classes, such as
996 For each directory in the PATH, place the contents of that
997 directory at the end of the class path.
1000 This is an environment variable which holds a list of paths.
1002 The final class path is constructed like so:
1004 * First come all directories specified via `-I'.
1006 * If `--classpath' is specified, its value is appended. Otherwise,
1007 if the `CLASSPATH' environment variable is specified, then its
1008 value is appended. Otherwise, the current directory (`"."') is
1011 * If `--bootclasspath' was specified, append its value. Otherwise,
1012 append the built-in system directory, `libgcj.jar'.
1014 * Finally, if `--extdirs' was specified, append the contents of the
1015 specified directories at the end of the class path. Otherwise,
1016 append the contents of the built-in extdirs at
1017 `$(prefix)/share/java/ext'.
1019 The classfile built by `gcj' for the class `java.lang.Object' (and
1020 placed in `libgcj.jar') contains a special zero length attribute
1021 `gnu.gcj.gcj-compiled'. The compiler looks for this attribute when
1022 loading `java.lang.Object' and will report an error if it isn't found,
1023 unless it compiles to bytecode (the option
1024 `-fforce-classes-archive-check' can be used to override this behavior
1025 in this particular case.)
1027 `-fforce-classes-archive-check'
1028 This forces the compiler to always check for the special zero
1029 length attribute `gnu.gcj.gcj-compiled' in `java.lang.Object' and
1030 issue an error if it isn't found.
1033 File: gcj.info, Node: Encodings, Next: Warnings, Prev: Input Options, Up: Invoking gcj
1038 The Java programming language uses Unicode throughout. In an effort to
1039 integrate well with other locales, `gcj' allows `.java' files to be
1040 written using almost any encoding. `gcj' knows how to convert these
1041 encodings into its internal encoding at compile time.
1043 You can use the `--encoding=NAME' option to specify an encoding (of
1044 a particular character set) to use for source files. If this is not
1045 specified, the default encoding comes from your current locale. If
1046 your host system has insufficient locale support, then `gcj' assumes
1047 the default encoding to be the `UTF-8' encoding of Unicode.
1049 To implement `--encoding', `gcj' simply uses the host platform's
1050 `iconv' conversion routine. This means that in practice `gcj' is
1051 limited by the capabilities of the host platform.
1053 The names allowed for the argument `--encoding' vary from platform
1054 to platform (since they are not standardized anywhere). However, `gcj'
1055 implements the encoding named `UTF-8' internally, so if you choose to
1056 use this for your source files you can be assured that it will work on
1060 File: gcj.info, Node: Warnings, Next: Linking, Prev: Encodings, Up: Invoking gcj
1065 `gcj' implements several warnings. As with other generic `gcc'
1066 warnings, if an option of the form `-Wfoo' enables a warning, then
1067 `-Wno-foo' will disable it. Here we've chosen to document the form of
1068 the warning which will have an effect - the default being the opposite
1071 `-Wredundant-modifiers'
1072 With this flag, `gcj' will warn about redundant modifiers. For
1073 instance, it will warn if an interface method is declared `public'.
1075 `-Wextraneous-semicolon'
1076 This causes `gcj' to warn about empty statements. Empty statements
1077 have been deprecated.
1080 This option will cause `gcj' not to warn when a source file is
1081 newer than its matching class file. By default `gcj' will warn
1085 Warn if a deprecated class, method, or field is referred to.
1088 This is the same as `gcc''s `-Wunused'.
1091 This is the same as `-Wredundant-modifiers -Wextraneous-semicolon
1095 File: gcj.info, Node: Linking, Next: Code Generation, Prev: Warnings, Up: Invoking gcj
1100 To turn a Java application into an executable program, you need to link
1101 it with the needed libraries, just as for C or C++. The linker by
1102 default looks for a global function named `main'. Since Java does not
1103 have global functions, and a collection of Java classes may have more
1104 than one class with a `main' method, you need to let the linker know
1105 which of those `main' methods it should invoke when starting the
1106 application. You can do that in any of these ways:
1108 * Specify the class containing the desired `main' method when you
1109 link the application, using the `--main' flag, described below.
1111 * Link the Java package(s) into a shared library (dll) rather than an
1112 executable. Then invoke the application using the `gij' program,
1113 making sure that `gij' can find the libraries it needs.
1115 * Link the Java packages(s) with the flag `-lgij', which links in
1116 the `main' routine from the `gij' command. This allows you to
1117 select the class whose `main' method you want to run when you run
1118 the application. You can also use other `gij' flags, such as `-D'
1119 flags to set properties. Using the `-lgij' library (rather than
1120 the `gij' program of the previous mechanism) has some advantages:
1121 it is compatible with static linking, and does not require
1122 configuring or installing libraries.
1124 These `gij' options relate to linking an executable:
1127 This option is used when linking to specify the name of the class
1128 whose `main' method should be invoked when the resulting
1132 This option can only be used with `--main'. It defines a system
1133 property named NAME with value VALUE. If VALUE is not specified
1134 then it defaults to the empty string. These system properties are
1135 initialized at the program's startup and can be retrieved at
1136 runtime using the `java.lang.System.getProperty' method.
1139 Create an application whose command-line processing is that of the
1142 This option is an alternative to using `--main'; you cannot use
1146 File: gcj.info, Node: Code Generation, Next: Configure-time Options, Prev: Linking, Up: Invoking gcj
1151 In addition to the many `gcc' options controlling code generation,
1152 `gcj' has several options specific to itself.
1155 This option is used to tell `gcj' to generate bytecode (`.class'
1156 files) rather than object code.
1158 `--resource RESOURCE-NAME'
1159 This option is used to tell `gcj' to compile the contents of a
1160 given file to object code so it may be accessed at runtime with
1161 the core protocol handler as `core:/RESOURCE-NAME'. Note that
1162 RESOURCE-NAME is the name of the resource as found at runtime; for
1163 instance, it could be used in a call to `ResourceBundle.getBundle'.
1164 The actual file name to be compiled this way must be specified
1168 When used with `-C', this causes all generated `.class' files to
1169 be put in the appropriate subdirectory of DIRECTORY. By default
1170 they will be put in subdirectories of the current working
1174 By default, `gcj' generates code which checks the bounds of all
1175 array indexing operations. With this option, these checks are
1176 omitted, which can improve performance for code that uses arrays
1177 extensively. Note that this can result in unpredictable behavior
1178 if the code in question actually does violate array bounds
1179 constraints. It is safe to use this option if you are sure that
1180 your code will never throw an `ArrayIndexOutOfBoundsException'.
1183 Don't generate array store checks. When storing objects into
1184 arrays, a runtime check is normally generated in order to ensure
1185 that the object is assignment compatible with the component type
1186 of the array (which may not be known at compile-time). With this
1187 option, these checks are omitted. This can improve performance
1188 for code which stores objects into arrays frequently. It is safe
1189 to use this option if you are sure your code will never throw an
1190 `ArrayStoreException'.
1193 With `gcj' there are two options for writing native methods: CNI
1194 and JNI. By default `gcj' assumes you are using CNI. If you are
1195 compiling a class with native methods, and these methods are
1196 implemented using JNI, then you must use `-fjni'. This option
1197 causes `gcj' to generate stubs which will invoke the underlying JNI
1201 Don't recognize the `assert' keyword. This is for compatibility
1202 with older versions of the language specification.
1204 `-fno-optimize-static-class-initialization'
1205 When the optimization level is greater or equal to `-O2', `gcj'
1206 will try to optimize the way calls into the runtime are made to
1207 initialize static classes upon their first use (this optimization
1208 isn't carried out if `-C' was specified.) When compiling to native
1209 code, `-fno-optimize-static-class-initialization' will turn this
1210 optimization off, regardless of the optimization level in use.
1212 `--disable-assertions[=CLASS-OR-PACKAGE]'
1213 Don't include code for checking assertions in the compiled code.
1214 If `=CLASS-OR-PACKAGE' is missing disables assertion code
1215 generation for all classes, unless overridden by a more specific
1216 `--enable-assertions' flag. If CLASS-OR-PACKAGE is a class name,
1217 only disables generating assertion checks within the named class
1218 or its inner classes. If CLASS-OR-PACKAGE is a package name,
1219 disables generating assertion checks within the named package or a
1222 By default, assertions are enabled when generating class files or
1223 when not optimizing, and disabled when generating optimized
1226 `--enable-assertions[=CLASS-OR-PACKAGE]'
1227 Generates code to check assertions. The option is perhaps
1228 misnamed, as you still need to turn on assertion checking at
1229 run-time, and we don't support any easy way to do that. So this
1230 flag isn't very useful yet, except to partially override
1231 `--disable-assertions'.
1233 `-findirect-dispatch'
1234 `gcj' has a special binary compatibility ABI, which is enabled by
1235 the `-findirect-dispatch' option. In this mode, the code
1236 generated by `gcj' honors the binary compatibility guarantees in
1237 the Java Language Specification, and the resulting object files do
1238 not need to be directly linked against their dependencies.
1239 Instead, all dependencies are looked up at runtime. This allows
1240 free mixing of interpreted and compiled code.
1242 Note that, at present, `-findirect-dispatch' can only be used when
1243 compiling `.class' files. It will not work when compiling from
1244 source. CNI also does not yet work with the binary compatibility
1245 ABI. These restrictions will be lifted in some future release.
1247 However, if you compile CNI code with the standard ABI, you can
1248 call it from code built with the binary compatibility ABI.
1252 File: gcj.info, Node: Configure-time Options, Prev: Code Generation, Up: Invoking gcj
1254 1.7 Configure-time Options
1255 ==========================
1257 Some `gcj' code generations options affect the resulting ABI, and so
1258 can only be meaningfully given when `libgcj', the runtime package, is
1259 configured. `libgcj' puts the appropriate options from this group into
1260 a `spec' file which is read by `gcj'. These options are listed here
1261 for completeness; if you are using `libgcj' then you won't want to
1262 touch these options.
1265 This enables the use of the Boehm GC bitmap marking code. In
1266 particular this causes `gcj' to put an object marking descriptor
1269 `-fhash-synchronization'
1270 By default, synchronization data (the data used for `synchronize',
1271 `wait', and `notify') is pointed to by a word in each object.
1272 With this option `gcj' assumes that this information is stored in a
1273 hash table and not in the object itself.
1275 `-fuse-divide-subroutine'
1276 On some systems, a library routine is called to perform integer
1277 division. This is required to get exception handling correct when
1280 `-fcheck-references'
1281 On some systems it's necessary to insert inline checks whenever
1282 accessing an object via a reference. On other systems you won't
1283 need this because null pointer accesses are caught automatically
1287 File: gcj.info, Node: Compatibility, Next: Invoking gcjh, Prev: Invoking gcj, Up: Top
1289 2 Compatibility with the Java Platform
1290 **************************************
1292 As we believe it is important that the Java platform not be fragmented,
1293 `gcj' and `libgcj' try to conform to the relevant Java specifications.
1294 However, limited manpower and incomplete and unclear documentation work
1295 against us. So, there are caveats to using `gcj'.
1303 File: gcj.info, Node: Limitations, Next: Extensions, Up: Compatibility
1305 2.1 Standard features not yet supported
1306 =======================================
1308 This list of compatibility issues is by no means complete.
1310 * `gcj' implements the JDK 1.2 language. It supports inner classes
1311 and the new 1.4 `assert' keyword. It does not yet support the
1312 Java 2 `strictfp' keyword (it recognizes the keyword but ignores
1315 * `libgcj' is largely compatible with the JDK 1.2 libraries.
1316 However, `libgcj' is missing many packages, most notably
1317 `java.awt'. There are also individual missing classes and methods.
1318 We currently do not have a list showing differences between
1319 `libgcj' and the Java 2 platform.
1321 * Sometimes the `libgcj' implementation of a method or class differs
1322 from the JDK implementation. This is not always a bug. Still, if
1323 it affects you, it probably makes sense to report it so that we
1324 can discuss the appropriate response.
1326 * `gcj' does not currently allow for piecemeal replacement of
1327 components within `libgcj'. Unfortunately, programmers often want
1328 to use newer versions of certain packages, such as those provided
1329 by the Apache Software Foundation's Jakarta project. This has
1330 forced us to place the `org.w3c.dom' and `org.xml.sax' packages
1331 into their own libraries, separate from `libgcj'. If you intend to
1332 use these classes, you must link them explicitly with
1333 `-l-org-w3c-dom' and `-l-org-xml-sax'. Future versions of `gcj'
1334 may not have this restriction.
1337 File: gcj.info, Node: Extensions, Prev: Limitations, Up: Compatibility
1339 2.2 Extra features unique to gcj
1340 ================================
1342 The main feature of `gcj' is that it can compile programs written in
1343 the Java programming language to native code. Most extensions that
1344 have been added are to facilitate this functionality.
1346 * `gcj' makes it easy and efficient to mix code written in Java and
1347 C++. *Note About CNI::, for more info on how to use this in your
1350 * When you compile your classes into a shared library they can be
1351 automatically loaded by the `libgcj' system classloader. When
1352 trying to load a class `gnu.pkg.SomeClass' the system classloader
1353 will first try to load the shared library
1354 `lib-gnu-pkg-SomeClass.so', if that fails to load the class then
1355 it will try to load `lib-gnu-pkg.so' and finally when the class is
1356 still not loaded it will try to load `lib-gnu.so'. Note that all
1357 `.'s will be transformed into `-'s and that searching for inner
1358 classes starts with their outermost outer class. If the class
1359 cannot be found this way the system classloader tries to use the
1360 `libgcj' bytecode interpreter to load the class from the standard
1361 classpath. This process can be controlled to some degree via the
1362 `gnu.gcj.runtime.VMClassLoader.library_control' property; *Note
1363 libgcj Runtime Properties::.
1365 * `libgcj' includes a special `gcjlib' URL type. A URL of this form
1366 is like a `jar' URL, and looks like
1367 `gcjlib:/path/to/shared/library.so!/path/to/resource'. An access
1368 to one of these URLs causes the shared library to be `dlopen()'d,
1369 and then the resource is looked for in that library. These URLs
1370 are most useful when used in conjunction with
1371 `java.net.URLClassLoader'. Note that, due to implementation
1372 limitations, currently any such URL can be accessed by only one
1373 class loader, and libraries are never unloaded. This means some
1374 care must be exercised to make sure that a `gcjlib' URL is not
1375 accessed by more than one class loader at once. In a future
1376 release this limitation will be lifted, and such libraries will be
1379 * A program compiled by `gcj' will examine the `GCJ_PROPERTIES'
1380 environment variable and change its behavior in some ways. In
1381 particular `GCJ_PROPERTIES' holds a list of assignments to global
1382 properties, such as would be set with the `-D' option to `java'.
1383 For instance, `java.compiler=gcj' is a valid (but currently
1384 meaningless) setting.
1388 File: gcj.info, Node: Invoking gcjh, Next: Invoking gjnih, Prev: Compatibility, Up: Top
1393 The `gcjh' program is used to generate header files from class files.
1394 It can generate both CNI and JNI header files, as well as stub
1395 implementation files which can be used as a basis for implementing the
1396 required native methods.
1399 This causes `gcjh' to generate stub files instead of header files.
1400 By default the stub file will be named after the class, with a
1401 suffix of `.cc'. In JNI mode, the default output file will have
1405 This tells `gcjh' to generate a JNI header or stub. By default,
1406 CNI headers are generated.
1409 This option forces `gcjh' to write the output file.
1412 This option is accepted but ignored for compatibility.
1415 This option is accepted but ignored for compatibility.
1418 This option is accepted but ignored for compatibility.
1421 Inserts TEXT into the class body. This is ignored in JNI mode.
1424 Inserts TEXT into the header file after the class declaration.
1425 This is ignored in JNI mode.
1428 Inserts TEXT into the class as a `friend' declaration. This is
1429 ignored in JNI mode.
1432 Inserts TEXT into the header file before the class declaration.
1433 This is ignored in JNI mode.
1437 `--bootclasspath=PATH'
1441 These options are all identical to the corresponding `gcj' options.
1444 Sets the output file name. This cannot be used if there is more
1445 than one class on the command line.
1448 Sets the name of the directory to use for temporary files.
1451 Print all dependencies to stdout; suppress ordinary output.
1454 Print non-system dependencies to stdout; suppress ordinary output.
1457 Print all dependencies to stdout.
1460 Print non-system dependencies to stdout.
1463 Print help about `gcjh' and exit. No further processing is done.
1466 Print version information for `gcjh' and exit. No further
1470 Print extra information while running.
1472 All remaining options are considered to be names of classes.
1475 File: gcj.info, Node: Invoking gjnih, Next: Invoking jv-scan, Prev: Invoking gcjh, Up: Top
1480 The `gjnih' program is used to generate JNI header files from class
1481 files. Running it is equivalent to running `gcjh -jni'.
1484 This causes `gjnih' to generate stub files instead of header files.
1485 By default the stub file will be named after the class, with a
1489 This option specifies the default behavior which is to generate a
1493 This option forces `gjnih' to write the output file.
1496 This option is accepted but ignored for compatibility.
1499 This option is accepted but ignored for compatibility.
1502 This option is accepted but ignored for compatibility.
1505 Inserts TEXT into the class body. This is ignored in by `gjnih'.
1508 Inserts TEXT into the header file after the class declaration.
1509 This is ignored in by `gjnih'.
1512 Inserts TEXT into the class as a `friend' declaration. This is
1516 Inserts TEXT into the header file before the class declaration.
1517 This is ignored in by `gjnih'.
1521 `--bootclasspath=PATH'
1525 These options are all identical to the corresponding `gcj' options.
1528 Sets the output file name. This cannot be used if there is more
1529 than one class on the command line.
1532 Sets the name of the directory to use for temporary files.
1535 Print all dependencies to stdout; suppress ordinary output.
1538 Print non-system dependencies to stdout; suppress ordinary output.
1541 Print all dependencies to stdout.
1544 Print non-system dependencies to stdout.
1547 Print help about `gjnih' and exit. No further processing is done.
1550 Print version information for `gjnih' and exit. No further
1554 Print extra information while running.
1556 All remaining options are considered to be names of classes.
1559 File: gcj.info, Node: Invoking jv-scan, Next: Invoking jcf-dump, Prev: Invoking gjnih, Up: Top
1564 The `jv-scan' program can be used to print information about a Java
1565 source file (`.java' file).
1568 Don't recognize the `assert' keyword, for backwards compatibility
1569 with older versions of the language specification.
1572 This prints a complexity measure, related to cyclomatic
1573 complexity, for each input file.
1576 This works like the corresponding `gcj' option.
1579 This prints the name of the class in this file containing a `main'
1583 This lists the names of all classes defined in the input files.
1586 If `--list-class' is given, this option causes `jv-scan' to also
1587 print the name of the file in which each class was found.
1590 Print output to the named file.
1593 Print help, then exit.
1596 Print version number, then exit.
1599 File: gcj.info, Node: Invoking jcf-dump, Next: Invoking gij, Prev: Invoking jv-scan, Up: Top
1604 This is a class file examiner, similar to `javap'. It will print
1605 information about a number of classes, which are specified by class name
1609 Disassemble method bodies. By default method bodies are not
1613 Print the constant pool. When printing a reference to a constant
1614 also print its index in the constant pool.
1617 Generate output in `javap' format. The implementation of this
1618 feature is very incomplete.
1624 These options as the same as the corresponding `gcj' options.
1627 Print help, then exit.
1630 Print version number, then exit.
1633 Print extra information while running. Implies
1634 `--print-constants'.
1637 File: gcj.info, Node: Invoking gij, Next: Invoking gcj-dbtool, Prev: Invoking jcf-dump, Up: Top
1642 `gij' is a Java bytecode interpreter included with `libgcj'. `gij' is
1643 not available on every platform; porting it requires a small amount of
1644 assembly programming which has not been done for all the targets
1647 The primary argument to `gij' is the name of a class or, with
1648 `-jar', a jar file. Options before this argument are interpreted by
1649 `gij'; remaining options are passed to the interpreted program.
1651 If a class name is specified and this class does not have a `main'
1652 method with the appropriate signature (a `static void' method with a
1653 `String[]' as its sole argument), then `gij' will print an error and
1656 If a jar file is specified then `gij' will use information in it to
1657 determine which class' `main' method will be invoked.
1659 `gij' will invoke the `main' method with all the remaining
1660 command-line options.
1662 Note that `gij' is not limited to interpreting code. Because
1663 `libgcj' includes a class loader which can dynamically load shared
1664 objects, it is possible to give `gij' the name of a class which has
1665 been compiled and put into a shared library on the class path.
1669 Set the initial class path. The class path is used for finding
1670 class and resource files. If specified, this option overrides the
1671 `CLASSPATH' environment variable. Note that this option is
1672 ignored if `-jar' is used.
1675 This defines a system property named NAME with value VALUE. If
1676 VALUE is not specified then it defaults to the empty string.
1677 These system properties are initialized at the program's startup
1678 and can be retrieved at runtime using the
1679 `java.lang.System.getProperty' method.
1682 Equivalent to `-Xms'.
1685 Equivalent to `-Xmx'.
1688 Do not verify compliance of bytecode with the VM specification. In
1689 addition, this option disables type verification which is
1690 otherwise performed on BC-ABI compiled code.
1694 Supplying `-X' by itself will cause `gij' to list all the
1695 supported `-X' options. Currently these options are supported:
1698 Set the initial heap size.
1701 Set the maximum heap size.
1703 Unrecognized `-X' options are ignored, for compatibility with
1707 This indicates that the name passed to `gij' should be interpreted
1708 as the name of a jar file, not a class.
1712 Print help, then exit.
1715 Print version number and continue.
1718 Print detailed version information, then exit.
1721 Print version number, then exit.
1725 Each time a class is initialized, print a short message on
1728 `gij' also recognizes and ignores the following options, for
1729 compatibility with existing application launch scripts: `-client',
1730 `-server', `-hotspot', `-jrockit', `-agentlib', `-agentpath', `-debug',
1731 `-d32', `-d64', `-javaagent', `-noclassgc', `-verify', and
1735 File: gcj.info, Node: Invoking gcj-dbtool, Next: Invoking jv-convert, Prev: Invoking gij, Up: Top
1737 8 Invoking gcj-dbtool.
1738 **********************
1740 `gcj-dbtool' is a tool for creating and manipulating class file mapping
1741 databases. `libgcj' can use these databases to find a shared library
1742 corresponding to the bytecode representation of a class. This
1743 functionality is useful for ahead-of-time compilation of a program that
1744 has no knowledge of `gcj'.
1746 `gcj-dbtool' works best if all the jar files added to it are
1747 compiled using `-findirect-dispatch'.
1749 Note that `gcj-dbtool' is currently available as "preview
1750 technology". We believe it is a reasonable way to allow
1751 application-transparent ahead-of-time compilation, but this is an
1752 unexplored area. We welcome your comments.
1755 This creates a new database. Currently, databases cannot be
1756 resized; you can choose a larger initial size if desired. The
1757 default size is 32,749.
1759 `-a DBFILE JARFILE LIB'
1760 `-f DBFILE JARFILE LIB'
1761 This adds a jar file to the database. For each class file in the
1762 jar, a cryptographic signature of the bytecode representation of
1763 the class is recorded in the database. At runtime, a class is
1764 looked up by its signature and the compiled form of the class is
1765 looked for in the corresponding shared library. The `-a' option
1766 will verify that LIB exists before adding it to the database; `-f'
1769 `[`-'][`-0'] -m DBFILE DBFILE,[DBFILE]'
1770 Merge a number of databases. The output database overwrites any
1771 existing database. To add databases into an existing database,
1772 include the destination in the list of sources.
1774 If `-' or `-0' are used, the list of files to read is taken from
1775 standard input instead of the command line. For `-0', Input
1776 filenames are terminated by a null character instead of by
1777 whitespace. Useful when arguments might contain white space. The
1778 GNU find -print0 option produces input suitable for this mode.
1784 List the contents of a database.
1787 Print the name of the default database. If there is no default
1788 database, this prints a blank line. If LIBDIR is specified, use
1789 it instead of the default library directory component of the
1793 Print a help message, then exit.
1797 Print version information, then exit.
1801 File: gcj.info, Node: Invoking jv-convert, Next: Invoking grmic, Prev: Invoking gcj-dbtool, Up: Top
1803 9 Invoking jv-convert
1804 *********************
1806 `jv-convert' [`OPTION'] ... [INPUTFILE [OUTPUTFILE]]
1808 `jv-convert' is a utility included with `libgcj' which converts a
1809 file from one encoding to another. It is similar to the Unix `iconv'
1812 The encodings supported by `jv-convert' are platform-dependent.
1813 Currently there is no way to get a list of all supported encodings.
1817 Use NAME as the input encoding. The default is the current
1821 Use NAME as the output encoding. The default is the `JavaSrc'
1822 encoding; this is ASCII with `\u' escapes for non-ASCII characters.
1825 Read from FILE. The default is to read from standard input.
1828 Write to FILE. The default is to write to standard output.
1831 Swap the input and output encodings.
1834 Print a help message, then exit.
1837 Print version information, then exit.
1840 File: gcj.info, Node: Invoking grmic, Next: Invoking grmiregistry, Prev: Invoking jv-convert, Up: Top
1845 `grmic' [`OPTION'] ... CLASS ...
1847 `grmic' is a utility included with `libgcj' which generates stubs
1850 Note that this program isn't yet fully compatible with the JDK
1851 `grmic'. Some options, such as `-classpath', are recognized but
1852 currently ignored. We have left these options undocumented for now.
1854 Long options can also be given with a GNU-style leading `--'. For
1855 instance, `--help' is accepted.
1859 By default, `grmic' deletes intermediate files. Either of these
1860 options causes it not to delete such files.
1863 Cause `grmic' to create stubs and skeletons for the 1.1 protocol
1867 Cause `grmic' to create stubs and skeletons compatible with both
1868 the 1.1 and 1.2 protocol versions. This is the default.
1871 Cause `grmic' to create stubs and skeletons for the 1.2 protocol
1875 Don't compile the generated files.
1878 Print information about what `grmic' is doing.
1881 Put output files in DIRECTORY. By default the files are put in
1882 the current working directory.
1885 Print a help message, then exit.
1888 Print version information, then exit.
1891 File: gcj.info, Node: Invoking grmiregistry, Next: About CNI, Prev: Invoking grmic, Up: Top
1893 11 Invoking grmiregistry
1894 ************************
1896 `grmic' [`OPTION'] ... [PORT]
1898 `grmiregistry' starts a remote object registry on the current host.
1899 If no port number is specified, then port 1099 is used.
1902 Print a help message, then exit.
1905 Print version information, then exit.
1908 File: gcj.info, Node: About CNI, Next: System properties, Prev: Invoking grmiregistry, Up: Top
1913 This documents CNI, the Compiled Native Interface, which is is a
1914 convenient way to write Java native methods using C++. This is a more
1915 efficient, more convenient, but less portable alternative to the
1916 standard JNI (Java Native Interface).
1920 * Basic concepts:: Introduction to using CNI.
1921 * Packages:: How packages are mapped to C++.
1922 * Primitive types:: Handling Java types in C++.
1923 * Interfaces:: How Java interfaces map to C++.
1924 * Objects and Classes:: C++ and Java classes.
1925 * Class Initialization:: How objects are initialized.
1926 * Object allocation:: How to create Java objects in C++.
1927 * Memory allocation:: How to allocate and free memory.
1928 * Arrays:: Dealing with Java arrays in C++.
1929 * Methods:: Java methods in C++.
1930 * Strings:: Information about Java Strings.
1931 * Mixing with C++:: How CNI can interoperate with C++.
1932 * Exception Handling:: How exceptions are handled.
1933 * Synchronization:: Synchronizing between Java and C++.
1934 * Invocation:: Starting the Java runtime from C++.
1935 * Reflection:: Using reflection from C++.
1938 File: gcj.info, Node: Basic concepts, Next: Packages, Up: About CNI
1943 In terms of languages features, Java is mostly a subset of C++. Java
1944 has a few important extensions, plus a powerful standard class library,
1945 but on the whole that does not change the basic similarity. Java is a
1946 hybrid object-oriented language, with a few native types, in addition
1947 to class types. It is class-based, where a class may have static as
1948 well as per-object fields, and static as well as instance methods.
1949 Non-static methods may be virtual, and may be overloaded. Overloading
1950 is resolved at compile time by matching the actual argument types
1951 against the parameter types. Virtual methods are implemented using
1952 indirect calls through a dispatch table (virtual function table).
1953 Objects are allocated on the heap, and initialized using a constructor
1954 method. Classes are organized in a package hierarchy.
1956 All of the listed attributes are also true of C++, though C++ has
1957 extra features (for example in C++ objects may be allocated not just on
1958 the heap, but also statically or in a local stack frame). Because
1959 `gcj' uses the same compiler technology as G++ (the GNU C++ compiler),
1960 it is possible to make the intersection of the two languages use the
1961 same ABI (object representation and calling conventions). The key idea
1962 in CNI is that Java objects are C++ objects, and all Java classes are
1963 C++ classes (but not the other way around). So the most important task
1964 in integrating Java and C++ is to remove gratuitous incompatibilities.
1966 You write CNI code as a regular C++ source file. (You do have to use
1967 a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
1969 A CNI C++ source file must have:
1971 #include <gcj/cni.h>
1973 and then must include one header file for each Java class it uses, e.g.:
1975 #include <java/lang/Character.h>
1976 #include <java/util/Date.h>
1977 #include <java/lang/IndexOutOfBoundsException.h>
1979 These header files are automatically generated by `gcjh'.
1981 CNI provides some functions and macros to make using Java objects and
1982 primitive types from C++ easier. In general, these CNI functions and
1983 macros start with the `Jv' prefix, for example the function
1984 `JvNewObjectArray'. This convention is used to avoid conflicts with
1985 other libraries. Internal functions in CNI start with the prefix
1986 `_Jv_'. You should not call these; if you find a need to, let us know
1987 and we will try to come up with an alternate solution.
1992 Whilst a Java class is just a C++ class that doesn't mean that you are
1993 freed from the shackles of Java, a CNI C++ class must adhere to the
1994 rules of the Java programming language.
1996 For example: it is not possible to declare a method in a CNI class
1997 that will take a C string (`char*') as an argument, or to declare a
1998 member variable of some non-Java datatype.
2001 File: gcj.info, Node: Packages, Next: Primitive types, Prev: Basic concepts, Up: About CNI
2006 The only global names in Java are class names, and packages. A
2007 "package" can contain zero or more classes, and also zero or more
2008 sub-packages. Every class belongs to either an unnamed package or a
2009 package that has a hierarchical and globally unique name.
2011 A Java package is mapped to a C++ "namespace". The Java class
2012 `java.lang.String' is in the package `java.lang', which is a
2013 sub-package of `java'. The C++ equivalent is the class
2014 `java::lang::String', which is in the namespace `java::lang' which is
2015 in the namespace `java'.
2017 Here is how you could express this:
2019 (// Declare the class(es), possibly in a header file:
2028 class java::lang::String : public java::lang::Object
2033 The `gcjh' tool automatically generates the necessary namespace
2036 12.2.1 Leaving out package names
2037 --------------------------------
2039 Always using the fully-qualified name of a java class can be tiresomely
2040 verbose. Using the full qualified name also ties the code to a single
2041 package making code changes necessary should the class move from one
2042 package to another. The Java `package' declaration specifies that the
2043 following class declarations are in the named package, without having
2044 to explicitly name the full package qualifiers. The `package'
2045 declaration can be followed by zero or more `import' declarations, which
2046 allows either a single class or all the classes in a package to be
2047 named by a simple identifier. C++ provides something similar with the
2048 `using' declaration and directive.
2052 import PACKAGE-NAME.CLASS-NAME;
2054 allows the program text to refer to CLASS-NAME as a shorthand for the
2055 fully qualified name: `PACKAGE-NAME.CLASS-NAME'.
2057 To achieve the same effect C++, you have to do this:
2059 using PACKAGE-NAME::CLASS-NAME;
2061 Java can also cause imports on demand, like this:
2063 import PACKAGE-NAME.*;
2065 Doing this allows any class from the package PACKAGE-NAME to be
2066 referred to only by its class-name within the program text.
2068 The same effect can be achieved in C++ like this:
2070 using namespace PACKAGE-NAME;
2073 File: gcj.info, Node: Primitive types, Next: Interfaces, Prev: Packages, Up: About CNI
2075 12.3 Primitive types
2076 ====================
2078 Java provides 8 "primitives" types which represent integers, floats,
2079 characters and booleans (and also the void type). C++ has its own very
2080 similar concrete types. Such types in C++ however are not always
2081 implemented in the same way (an int might be 16, 32 or 64 bits for
2082 example) so CNI provides a special C++ type for each primitive Java
2085 *Java type* *C/C++ typename* *Description*
2086 `char' `jchar' 16 bit Unicode character
2087 `boolean' `jboolean' logical (true or false) values
2088 `byte' `jbyte' 8-bit signed integer
2089 `short' `jshort' 16 bit signed integer
2090 `int' `jint' 32 bit signed integer
2091 `long' `jlong' 64 bit signed integer
2092 `float' `jfloat' 32 bit IEEE floating point number
2093 `double' `jdouble' 64 bit IEEE floating point number
2094 `void' `void' no value
2096 When referring to a Java type You should always use these C++
2097 typenames (e.g.: `jint') to avoid disappointment.
2099 12.3.1 Reference types associated with primitive types
2100 ------------------------------------------------------
2102 In Java each primitive type has an associated reference type, e.g.:
2103 `boolean' has an associated `java.lang.Boolean' class. In order to
2104 make working with such classes easier GCJ provides the macro
2107 -- macro: JvPrimClass type
2108 Return a pointer to the `Class' object corresponding to the type
2111 JvPrimClass(void) => java.lang.Void.TYPE
2115 File: gcj.info, Node: Interfaces, Next: Objects and Classes, Prev: Primitive types, Up: About CNI
2120 A Java class can "implement" zero or more "interfaces", in addition to
2121 inheriting from a single base class.
2123 CNI allows CNI code to implement methods of interfaces. You can
2124 also call methods through interface references, with some limitations.
2126 CNI doesn't understand interface inheritance at all yet. So, you
2127 can only call an interface method when the declared type of the field
2128 being called matches the interface which declares that method. The
2129 workaround is to cast the interface reference to the right
2132 For example if you have:
2139 interface B extends A
2144 and declare a variable of type `B' in C++, you can't call `a()'
2145 unless you cast it to an `A' first.
2148 File: gcj.info, Node: Objects and Classes, Next: Class Initialization, Prev: Interfaces, Up: About CNI
2150 12.5 Objects and Classes
2151 ========================
2156 All Java classes are derived from `java.lang.Object'. C++ does not
2157 have a unique root class, but we use the C++ class `java::lang::Object'
2158 as the C++ version of the `java.lang.Object' Java class. All other
2159 Java classes are mapped into corresponding C++ classes derived from
2160 `java::lang::Object'.
2162 Interface inheritance (the `implements' keyword) is currently not
2163 reflected in the C++ mapping.
2165 12.5.2 Object fields
2166 --------------------
2168 Each object contains an object header, followed by the instance fields
2169 of the class, in order. The object header consists of a single pointer
2170 to a dispatch or virtual function table. (There may be extra fields
2171 _in front of_ the object, for example for memory management, but this
2172 is invisible to the application, and the reference to the object points
2173 to the dispatch table pointer.)
2175 The fields are laid out in the same order, alignment, and size as in
2176 C++. Specifically, 8-bite and 16-bit native types (`byte', `short',
2177 `char', and `boolean') are _not_ widened to 32 bits. Note that the
2178 Java VM does extend 8-bit and 16-bit types to 32 bits when on the VM
2179 stack or temporary registers.
2181 If you include the `gcjh'-generated header for a class, you can
2182 access fields of Java classes in the _natural_ way. For example, given
2183 the following Java class:
2188 public Integer (int i) { this.i = i; }
2189 public static zero = new Integer(0);
2194 #include <gcj/cni.h>;
2198 mult (Int *p, jint k)
2201 return Int::zero; // Static member access.
2202 return new Int(p->i * k);
2205 12.5.3 Access specifiers
2206 ------------------------
2208 CNI does not strictly enforce the Java access specifiers, because Java
2209 permissions cannot be directly mapped into C++ permission. Private
2210 Java fields and methods are mapped to private C++ fields and methods,
2211 but other fields and methods are mapped to public fields and methods.
2214 File: gcj.info, Node: Class Initialization, Next: Object allocation, Prev: Objects and Classes, Up: About CNI
2216 12.6 Class Initialization
2217 =========================
2219 Java requires that each class be automatically initialized at the time
2220 of the first active use. Initializing a class involves initializing
2221 the static fields, running code in class initializer methods, and
2222 initializing base classes. There may also be some implementation
2223 specific actions, such as allocating `String' objects corresponding to
2224 string literals in the code.
2226 The GCJ compiler inserts calls to `JvInitClass' at appropriate
2227 places to ensure that a class is initialized when required. The C++
2228 compiler does not insert these calls automatically--it is the
2229 programmer's responsibility to make sure classes are initialized.
2230 However, this is fairly painless because of the conventions assumed by
2233 First, `libgcj' will make sure a class is initialized before an
2234 instance of that object is created. This is one of the
2235 responsibilities of the `new' operation. This is taken care of both in
2236 Java code, and in C++ code. When G++ sees a `new' of a Java class, it
2237 will call a routine in `libgcj' to allocate the object, and that
2238 routine will take care of initializing the class. Note however that
2239 this does not happen for Java arrays; you must allocate those using the
2240 appropriate CNI function. It follows that you can access an instance
2241 field, or call an instance (non-static) method and be safe in the
2242 knowledge that the class and all of its base classes have been
2245 Invoking a static method is also safe. This is because the Java
2246 compiler adds code to the start of a static method to make sure the
2247 class is initialized. However, the C++ compiler does not add this
2248 extra code. Hence, if you write a native static method using CNI, you
2249 are responsible for calling `JvInitClass' before doing anything else in
2250 the method (unless you are sure it is safe to leave it out).
2252 Accessing a static field also requires the class of the field to be
2253 initialized. The Java compiler will generate code to call
2254 `Jv_InitClass' before getting or setting the field. However, the C++
2255 compiler will not generate this extra code, so it is your
2256 responsibility to make sure the class is initialized before you access
2257 a static field from C++.
2260 File: gcj.info, Node: Object allocation, Next: Memory allocation, Prev: Class Initialization, Up: About CNI
2262 12.7 Object allocation
2263 ======================
2265 New Java objects are allocated using a "class instance creation
2270 The same syntax is used in C++. The main difference is that C++
2271 objects have to be explicitly deleted; in Java they are automatically
2272 deleted by the garbage collector. Using CNI, you can allocate a new
2273 Java object using standard C++ syntax and the C++ compiler will allocate
2274 memory from the garbage collector. If you have overloaded
2275 constructors, the compiler will choose the correct one using standard
2276 C++ overload resolution rules.
2280 java::util::Hashtable *ht = new java::util::Hashtable(120);
2283 File: gcj.info, Node: Memory allocation, Next: Arrays, Prev: Object allocation, Up: About CNI
2285 12.8 Memory allocation
2286 ======================
2288 When allocting memory in CNI methods it is best to handle out-of-memory
2289 conditions by throwing a Java exception. These functions are provided
2292 -- Function: void* JvMalloc (jsize SIZE)
2293 Calls malloc. Throws `java.lang.OutOfMemoryError' if allocation
2296 -- Function: void* JvRealloc (void* PTR, jsize SIZE)
2297 Calls realloc. Throws `java.lang.OutOfMemoryError' if
2300 -- Function: void JvFree (void* PTR)
2304 File: gcj.info, Node: Arrays, Next: Methods, Prev: Memory allocation, Up: About CNI
2309 While in many ways Java is similar to C and C++, it is quite different
2310 in its treatment of arrays. C arrays are based on the idea of pointer
2311 arithmetic, which would be incompatible with Java's security
2312 requirements. Java arrays are true objects (array types inherit from
2313 `java.lang.Object'). An array-valued variable is one that contains a
2314 reference (pointer) to an array object.
2316 Referencing a Java array in C++ code is done using the `JArray'
2317 template, which as defined as follows:
2319 class __JArray : public java::lang::Object
2326 class JArray : public __JArray
2330 T& operator[](jint i) { return data[i]; }
2333 There are a number of `typedef's which correspond to `typedef's from
2334 the JNI. Each is the type of an array holding objects of the relevant
2337 typedef __JArray *jarray;
2338 typedef JArray<jobject> *jobjectArray;
2339 typedef JArray<jboolean> *jbooleanArray;
2340 typedef JArray<jbyte> *jbyteArray;
2341 typedef JArray<jchar> *jcharArray;
2342 typedef JArray<jshort> *jshortArray;
2343 typedef JArray<jint> *jintArray;
2344 typedef JArray<jlong> *jlongArray;
2345 typedef JArray<jfloat> *jfloatArray;
2346 typedef JArray<jdouble> *jdoubleArray;
2348 -- Method on template<class T>: T* elements (JArray<T> ARRAY)
2349 This template function can be used to get a pointer to the
2350 elements of the `array'. For instance, you can fetch a pointer to
2351 the integers that make up an `int[]' like so:
2353 extern jintArray foo;
2354 jint *intp = elements (foo);
2356 The name of this function may change in the future.
2358 -- Function: jobjectArray JvNewObjectArray (jsize LENGTH, jclass
2359 KLASS, jobject INIT)
2360 Here `klass' is the type of elements of the array and `init' is
2361 the initial value put into every slot in the array.
2363 12.9.1 Creating arrays
2364 ----------------------
2366 For each primitive type there is a function which can be used to create
2367 a new array of that type. The name of the function is of the form:
2375 can be used to create an array of Java primitive boolean types.
2377 The following function definition is the template for all such
2380 -- Function: jbooleanArray JvNewBooleanArray (jint LENGTH)
2381 Create's an array LENGTH indices long.
2383 -- Function: jsize JvGetArrayLength (jarray ARRAY)
2384 Returns the length of the ARRAY.
2387 File: gcj.info, Node: Methods, Next: Strings, Prev: Arrays, Up: About CNI
2392 Java methods are mapped directly into C++ methods. The header files
2393 generated by `gcjh' include the appropriate method definitions.
2394 Basically, the generated methods have the same names and
2395 _corresponding_ types as the Java methods, and are called in the
2401 Both Java and C++ provide method overloading, where multiple methods in
2402 a class have the same name, and the correct one is chosen (at compile
2403 time) depending on the argument types. The rules for choosing the
2404 correct method are (as expected) more complicated in C++ than in Java,
2405 but given a set of overloaded methods generated by `gcjh' the C++
2406 compiler will choose the expected one.
2408 Common assemblers and linkers are not aware of C++ overloading, so
2409 the standard implementation strategy is to encode the parameter types
2410 of a method into its assembly-level name. This encoding is called
2411 "mangling", and the encoded name is the "mangled name". The same
2412 mechanism is used to implement Java overloading. For C++/Java
2413 interoperability, it is important that both the Java and C++ compilers
2414 use the _same_ encoding scheme.
2416 12.10.2 Static methods
2417 ----------------------
2419 Static Java methods are invoked in CNI using the standard C++ syntax,
2420 using the `::' operator rather than the `.' operator.
2424 jint i = java::lang::Math::round((jfloat) 2.3);
2426 C++ method definition syntax is used to define a static native method.
2429 #include <java/lang/Integer>
2430 java::lang::Integer*
2431 java::lang::Integer::getInteger(jstring str)
2436 12.10.3 Object Constructors
2437 ---------------------------
2439 Constructors are called implicitly as part of object allocation using
2444 java::lang::Integer *x = new java::lang::Integer(234);
2446 Java does not allow a constructor to be a native method. This
2447 limitation can be coded round however because a constructor can _call_
2450 12.10.4 Instance methods
2451 ------------------------
2453 Calling a Java instance method from a C++ CNI method is done using the
2454 standard C++ syntax, e.g.:
2456 // First create the Java object.
2457 java::lang::Integer *x = new java::lang::Integer(234);
2458 // Now call a method.
2459 jint prim_value = x->intValue();
2460 if (x->longValue == 0)
2463 Defining a Java native instance method is also done the natural way:
2465 #include <java/lang/Integer.h>
2468 java::lang:Integer::doubleValue()
2470 return (jdouble) value;
2473 12.10.5 Interface methods
2474 -------------------------
2476 In Java you can call a method using an interface reference. This is
2477 supported, but not completely. *Note Interfaces::.
2480 File: gcj.info, Node: Strings, Next: Mixing with C++, Prev: Methods, Up: About CNI
2485 CNI provides a number of utility functions for working with Java Java
2486 `String' objects. The names and interfaces are analogous to those of
2489 -- Function: jstring JvNewString (const char* CHARS, jsize LEN)
2490 Returns a Java `String' object with characters from the C string
2491 CHARS up to the index LEN in that array.
2493 -- Function: jstring JvNewStringLatin1 (const char* BYTES, jsize LEN)
2494 Returns a Java `String' made up of LEN bytes from BYTES.
2496 -- Function: jstring JvNewStringLatin1 (const char* BYTES)
2497 As above but the length of the `String' is `strlen(BYTES)'.
2499 -- Function: jstring JvNewStringUTF (const char* BYTES)
2500 Returns a `String' which is made up of the UTF encoded characters
2501 present in the C string BYTES.
2503 -- Function: jchar* JvGetStringChars (jstring STR)
2504 Returns a pointer to an array of characters making up the `String'
2507 -- Function: int JvGetStringUTFLength (jstring STR)
2508 Returns the number of bytes required to encode the contents of the
2509 `String' STR in UTF-8.
2511 -- Function: jsize JvGetStringUTFRegion (jstring STR, jsize START,
2512 jsize LEN, char* BUF)
2513 Puts the UTF-8 encoding of a region of the `String' STR into the
2514 buffer `buf'. The region to fetch is marked by START and LEN.
2516 Note that BUF is a buffer, not a C string. It is _not_ null
2520 File: gcj.info, Node: Mixing with C++, Next: Exception Handling, Prev: Strings, Up: About CNI
2522 12.12 Interoperating with C/C++
2523 ===============================
2525 Because CNI is designed to represent Java classes and methods it cannot
2526 be mixed readily with C/C++ types.
2528 One important restriction is that Java classes cannot have non-Java
2529 type instance or static variables and cannot have methods which take
2530 non-Java types as arguments or return non-Java types.
2532 None of the following is possible with CNI:
2535 class ::MyClass : public java::lang::Object
2537 char* variable; // char* is not a valid Java type.
2542 ::SomeClass::someMethod (char *arg)
2547 } // `uint' is not a valid Java type, neither is `char*'
2549 Of course, it is ok to use C/C++ types within the scope of a method:
2552 ::SomeClass::otherMethod (jstring str)
2563 The above restriction can be problematic, so CNI includes the
2564 `gnu.gcj.RawData' class. The `RawData' class is a "non-scanned
2565 reference" type. In other words variables declared of type `RawData'
2566 can contain any data and are not checked by the compiler or memory
2569 This means that you can put C/C++ data structures (including classes)
2570 in your CNI classes, as long as you use the appropriate cast.
2572 Here are some examples:
2575 class ::MyClass : public java::lang::Object
2577 gnu.gcj.RawData string;
2580 gnu.gcj.RawData getText ();
2584 ::MyClass::MyClass ()
2591 ::MyClass::getText ()
2597 ::MyClass::printText ()
2599 printf("%s\n", (char*) string);
2602 12.12.2 RawDataManaged
2603 ----------------------
2605 `gnu.gcj.RawDataManaged' is another type used to indicate special data
2606 used by native code. Unlike the `RawData' type, fields declared as
2607 `RawDataManaged' will be "marked" by the memory manager and considered
2608 for garbage collection.
2610 Native data which is allocated using CNI's `JvAllocBytes()' function
2611 and stored in a `RawDataManaged' will be automatically freed when the
2612 Java object it is associated with becomes unreachable.
2614 12.12.3 Native memory allocation
2615 --------------------------------
2617 -- Function: void* JvAllocBytes (jsize SIZE)
2618 Allocates SIZE bytes from the heap. The memory returned is zeroed.
2619 This memory is not scanned for pointers by the garbage collector,
2620 but will be freed if no references to it are discovered.
2622 This function can be useful if you need to associate some native
2623 data with a Java object. Using a CNI's special `RawDataManaged'
2624 type, native data allocated with `JvAllocBytes' will be
2625 automatically freed when the Java object itself becomes
2628 12.12.4 Posix signals
2629 ---------------------
2631 On Posix based systems the `libgcj' library uses several signals
2632 internally. CNI code should not attempt to use the same signals as
2633 doing so may cause `libgcj' and/or the CNI code to fail.
2635 SIGSEGV is used on many systems to generate `NullPointerExceptions'.
2636 SIGCHLD is used internally by `Runtime.exec()'. Several other signals
2637 (that vary from platform to platform) can be used by the memory manager
2638 and by `Thread.interrupt()'.
2641 File: gcj.info, Node: Exception Handling, Next: Synchronization, Prev: Mixing with C++, Up: About CNI
2643 12.13 Exception Handling
2644 ========================
2646 While C++ and Java share a common exception handling framework, things
2647 are not yet perfectly integrated. The main issue is that the run-time
2648 type information facilities of the two languages are not integrated.
2650 Still, things work fairly well. You can throw a Java exception from
2651 C++ using the ordinary `throw' construct, and this exception can be
2652 caught by Java code. Similarly, you can catch an exception thrown from
2653 Java using the C++ `catch' construct.
2658 throw new java::lang::IndexOutOfBoundsException();
2660 Normally, G++ will automatically detect when you are writing C++
2661 code that uses Java exceptions, and handle them appropriately.
2662 However, if C++ code only needs to execute destructors when Java
2663 exceptions are thrown through it, GCC will guess incorrectly. Sample
2668 extern void bar(); // Is implemented in Java and may throw exceptions.
2676 The usual effect of an incorrect guess is a link failure,
2677 complaining of a missing routine called `__gxx_personality_v0'.
2679 You can inform the compiler that Java exceptions are to be used in a
2680 translation unit, irrespective of what it might think, by writing
2681 `#pragma GCC java_exceptions' at the head of the file. This `#pragma'
2682 must appear before any functions that throw or catch exceptions, or run
2683 destructors when exceptions are thrown through them.
2686 File: gcj.info, Node: Synchronization, Next: Invocation, Prev: Exception Handling, Up: About CNI
2688 12.14 Synchronization
2689 =====================
2691 Each Java object has an implicit monitor. The Java VM uses the
2692 instruction `monitorenter' to acquire and lock a monitor, and
2693 `monitorexit' to release it.
2695 The corresponding CNI macros are `JvMonitorEnter' and
2696 `JvMonitorExit' (JNI has similar methods `MonitorEnter' and
2699 The Java source language does not provide direct access to these
2700 primitives. Instead, there is a `synchronized' statement that does an
2701 implicit `monitorenter' before entry to the block, and does a
2702 `monitorexit' on exit from the block. Note that the lock has to be
2703 released even when the block is abnormally terminated by an exception,
2704 which means there is an implicit `try finally' surrounding
2705 synchronization locks.
2707 From C++, it makes sense to use a destructor to release a lock. CNI
2708 defines the following utility class:
2710 class JvSynchronize() {
2712 JvSynchronize(jobject o) { obj = o; JvMonitorEnter(o); }
2713 ~JvSynchronize() { JvMonitorExit(obj); }
2723 might become this C++ code:
2726 JvSynchronize dummy (OBJ);
2730 Java also has methods with the `synchronized' attribute. This is
2731 equivalent to wrapping the entire method body in a `synchronized'
2732 statement. (Alternatively, an implementation could require the caller
2733 to do the synchronization. This is not practical for a compiler,
2734 because each virtual method call would have to test at run-time if
2735 synchronization is needed.) Since in `gcj' the `synchronized'
2736 attribute is handled by the method implementation, it is up to the
2737 programmer of a synchronized native method to handle the synchronization
2738 (in the C++ implementation of the method). In other words, you need to
2739 manually add `JvSynchronize' in a `native synchronized' method.
2742 File: gcj.info, Node: Invocation, Next: Reflection, Prev: Synchronization, Up: About CNI
2747 CNI permits C++ applications to make calls into Java classes, in
2748 addition to allowing Java code to call into C++. Several functions,
2749 known as the "invocation API", are provided to support this.
2751 -- Function: jint JvCreateJavaVM (JvVMInitArgs* VM_ARGS)
2752 Initializes the Java runtime. This function performs essential
2753 initialization of the threads interface, garbage collector,
2754 exception handling and other key aspects of the runtime. It must
2755 be called once by an application with a non-Java `main()'
2756 function, before any other Java or CNI calls are made. It is
2757 safe, but not recommended, to call `JvCreateJavaVM()' more than
2758 once provided it is only called from a single thread. The VMARGS
2759 parameter can be used to specify initialization parameters for the
2760 Java runtime. It may be `NULL'.
2762 JvVMInitArgs represents a list of virtual machine initialization
2763 arguments. `JvCreateJavaVM()' ignores the version field.
2765 typedef struct JvVMOption
2767 // a VM initialization option
2769 // extra information associated with this option
2773 typedef struct JvVMInitArgs
2775 // for compatibility with JavaVMInitArgs
2778 // number of VM initialization options
2781 // an array of VM initialization options
2782 JvVMOption* options;
2784 // true if the option parser should ignore unrecognized options
2785 jboolean ignoreUnrecognized;
2788 `JvCreateJavaVM()' returns `0' upon success, or `-1' if the
2789 runtime is already initialized.
2791 _Note:_ In GCJ 3.1, the `vm_args' parameter is ignored. It is
2792 recognized and used as of release 4.0.
2794 -- Function: java::lang::Thread* JvAttachCurrentThread (jstring NAME,
2795 java::lang::ThreadGroup* GROUP)
2796 Registers an existing thread with the Java runtime. This must be
2797 called once from each thread, before that thread makes any other
2798 Java or CNI calls. It must be called after `JvCreateJavaVM'. NAME
2799 specifies a name for the thread. It may be `NULL', in which case a
2800 name will be generated. GROUP is the ThreadGroup in which this
2801 thread will be a member. If it is `NULL', the thread will be a
2802 member of the main thread group. The return value is the Java
2803 `Thread' object that represents the thread. It is safe to call
2804 `JvAttachCurrentThread()' more than once from the same thread. If
2805 the thread is already attached, the call is ignored and the current
2806 thread object is returned.
2808 -- Function: jint JvDetachCurrentThread ()
2809 Unregisters a thread from the Java runtime. This should be called
2810 by threads that were attached using `JvAttachCurrentThread()',
2811 after they have finished making calls to Java code. This ensures
2812 that any resources associated with the thread become eligible for
2813 garbage collection. This function returns `0' upon success, or
2814 `-1' if the current thread is not attached.
2816 12.15.1 Handling uncaught exceptions
2817 ------------------------------------
2819 If an exception is thrown from Java code called using the invocation
2820 API, and no handler for the exception can be found, the runtime will
2821 abort the application. In order to make the application more robust, it
2822 is recommended that code which uses the invocation API be wrapped by a
2823 top-level try/catch block that catches all Java exceptions.
2828 The following code demonstrates the use of the invocation API. In this
2829 example, the C++ application initializes the Java runtime and attaches
2830 itself. The `java.lang.System' class is initialized in order to access
2831 its `out' field, and a Java string is printed. Finally, the thread is
2832 detached from the runtime once it has finished making Java calls.
2833 Everything is wrapped with a try/catch block to provide a default
2834 handler for any uncaught exceptions.
2836 The example can be compiled with `c++ test.cc -lgcj'.
2839 #include <gcj/cni.h>
2840 #include <java/lang/System.h>
2841 #include <java/io/PrintStream.h>
2842 #include <java/lang/Throwable.h>
2844 int main(int argc, char *argv)
2846 using namespace java::lang;
2850 JvCreateJavaVM(NULL);
2851 JvAttachCurrentThread(NULL, NULL);
2853 String *message = JvNewStringLatin1("Hello from C++");
2854 JvInitClass(&System::class$);
2855 System::out->println(message);
2857 JvDetachCurrentThread();
2859 catch (Throwable *t)
2861 System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
2862 t->printStackTrace();
2867 File: gcj.info, Node: Reflection, Prev: Invocation, Up: About CNI
2872 Reflection is possible with CNI code, it functions similarly to how it
2875 The types `jfieldID' and `jmethodID' are as in JNI.
2879 * `JvFromReflectedField',
2881 * `JvFromReflectedMethod',
2883 * `JvToReflectedField'
2885 * `JvToFromReflectedMethod'
2887 will be added shortly, as will other functions corresponding to JNI.
2890 File: gcj.info, Node: System properties, Next: Resources, Prev: About CNI, Up: Top
2892 13 System properties
2893 ********************
2895 The runtime behavior of the `libgcj' library can be modified by setting
2896 certain system properties. These properties can be compiled into the
2897 program using the `-DNAME[=VALUE]' option to `gcj' or by setting them
2898 explicitly in the program by calling the
2899 `java.lang.System.setProperty()' method. Some system properties are
2900 only used for informational purposes (like giving a version number or a
2901 user name). A program can inspect the current value of a property by
2902 calling the `java.lang.System.getProperty()' method.
2906 * Standard Properties:: Standard properties supported by `libgcj'
2907 * GNU Classpath Properties:: Properties found in Classpath based libraries
2908 * libgcj Runtime Properties:: Properties specific to `libgcj'
2911 File: gcj.info, Node: Standard Properties, Next: GNU Classpath Properties, Up: System properties
2913 13.1 Standard Properties
2914 ========================
2916 The following properties are normally found in all implementations of
2917 the core libraries for the Java language.
2920 The `libgcj' version number.
2923 Set to `The Free Software Foundation, Inc.'
2926 Set to `http://gcc.gnu.org/java/'.
2929 The directory where `gcj' was installed. Taken from the `--prefix'
2930 option given to `configure'.
2932 `java.class.version'
2933 The class format version number supported by the libgcj byte code
2934 interpreter. (Currently `46.0')
2936 `java.vm.specification.version'
2937 The Virtual Machine Specification version implemented by `libgcj'.
2940 `java.vm.specification.vendor'
2941 The name of the Virtual Machine specification designer.
2943 `java.vm.specification.name'
2944 The name of the Virtual Machine specification (Set to `Java
2945 Virtual Machine Specification').
2948 The `gcj' version number.
2951 Set to `The Free Software Foundation, Inc.'
2954 Set to `GNU libgcj'.
2956 `java.specification.version'
2957 The Runtime Environment specification version implemented by
2958 `libgcj'. (Currently set to `1.3')
2960 `java.specification.vendor'
2961 The Runtime Environment specification designer.
2963 `java.specification.name'
2964 The name of the Runtime Environment specification (Set to `Java
2965 Platform API Specification').
2968 The paths (jar files, zip files and directories) used for finding
2972 Directory path used for finding native libraries.
2975 The directory used to put temporary files in.
2978 Name of the Just In Time compiler to use by the byte code
2979 interpreter. Currently not used in `libgcj'.
2982 Directories containing jar files with extra libraries. Will be
2983 used when resolving classes.
2985 `java.protocol.handler.pkgs'
2986 A `|' separated list of package names that is used to find classes
2987 that implement handlers for `java.net.URL'.
2989 `java.rmi.server.codebase'
2990 A list of URLs that is used by the `java.rmi.server.RMIClassLoader'
2991 to load classes from.
2994 A list of class names that will be loaded by the
2995 `java.sql.DriverManager' when it starts up.
2998 The separator used in when directories are included in a filename
2999 (normally `/' or `\' ).
3002 The default character encoding used when converting platform
3003 native files to Unicode (usually set to `8859_1').
3006 The standard separator used when a string contains multiple paths
3007 (normally `:' or `;'), the string is usually not a valid character
3008 to use in normal directory names.)
3011 The default line separator used on the platform (normally `\n',
3012 `\r' or a combination of those two characters).
3015 The class name used for the default policy provider returned by
3016 `java.security.Policy.getPolicy'.
3019 The name of the user running the program. Can be the full name,
3020 the login name or empty if unknown.
3023 The default directory to put user specific files in.
3026 The current working directory from which the program was started.
3029 The default language as used by the `java.util.Locale' class.
3032 The default region as used by the `java.util.Local' class.
3035 The default variant of the language and region local used.
3038 The default timezone as used by the `java.util.TimeZone' class.
3041 The operating system/kernel name that the program runs on.
3044 The hardware that we are running on.
3047 The version number of the operating system/kernel.
3050 The string to display when an untrusted applet is displayed.
3051 Returned by `java.awt.Window.getWarningString()' when the window is
3055 The class name used for initializing the default
3056 `java.awt.Toolkit'. Defaults to `gnu.awt.gtk.GtkToolkit'.
3059 Name of proxy host for http connections.
3062 Port number to use when a proxy host is in use.
3066 File: gcj.info, Node: GNU Classpath Properties, Next: libgcj Runtime Properties, Prev: Standard Properties, Up: System properties
3068 13.2 GNU Classpath Properties
3069 =============================
3071 `libgcj' is based on the GNU Classpath (Essential Libraries for Java) a
3072 GNU project to create free core class libraries for use with virtual
3073 machines and compilers for the Java language. The following properties
3074 are common to libraries based on GNU Classpath.
3077 Enables printing serialization debugging by the
3078 `java.io.ObjectInput' and `java.io.ObjectOutput' classes when set
3079 to something else then the empty string. Only used when running a
3080 debug build of the library.
3082 `gnu.classpath.vm.shortname'
3083 This is a succint name of the virtual machine. For `libgcj', this
3084 will always be `libgcj'.
3086 `gnu.classpath.home.url'
3087 A base URL used for finding system property files (e.g.,
3088 `classpath.security'). By default this is a `file:' URL pointing
3089 to the `lib' directory under `java.home'.
3093 File: gcj.info, Node: libgcj Runtime Properties, Prev: GNU Classpath Properties, Up: System properties
3095 13.3 libgcj Runtime Properties
3096 ==============================
3098 The following properties are specific to the `libgcj' runtime and will
3099 normally not be found in other core libraries for the java language.
3102 The combination of `java.vm.name' and `java.vm.version'.
3105 Same as `java.fullversion'.
3108 Used by the `java.net.DatagramSocket' class when set to something
3109 else then the empty string. When set all newly created
3110 `DatagramSocket's will try to load a class
3111 `java.net.[impl.prefix]DatagramSocketImpl' instead of the normal
3112 `java.net.PlainDatagramSocketImpl'.
3115 The name that was used to invoked the program.
3117 `gnu.gcj.runtime.NameFinder.demangle'
3118 Whether names in a stack trace should be demangled. Defaults to
3121 `gnu.gcj.runtime.NameFinder.sanitize'
3122 Whether calls to initialize exceptions and starting the runtime
3123 system should be removed from the stack trace. Only done when
3124 names are demangled. Defaults to `true'.
3126 `gnu.gcj.runtime.NameFinder.remove_unknown'
3127 Whether calls to unknown functions (class and method names are
3128 unknown) should be removed from the stack trace. Only done when
3129 the stack is sanitized. Ignored if this means no stack trace
3130 information would be available anymore. Defaults to `true'.
3132 `gnu.gcj.runtime.NameFinder.remove_interpreter'
3133 Whether runtime interpreter calls (methods in the
3134 `_Jv_InterpMethod' class and functions starting with `ffi_')
3135 should be removed from the stack trace. Only done when the stack
3136 is sanitized. Defaults to `true'.
3138 `gnu.gcj.runtime.NameFinder.use_addr2line'
3139 Whether an external process (`addr2line' or `addr2name.awk')
3140 should be used as fallback to convert the addresses to function
3141 names when the runtime is unable to do it through `dladdr'.
3143 `gnu.gcj.runtime.VMClassLoader.library_control'
3144 This controls how shared libraries are automatically loaded by the
3145 built-in class loader. If this property is set to `full', a full
3146 search is done for each requested class. If this property is set
3147 to `cache' (the default), then any failed lookups are cached and
3148 not tried again. If this property is set to `never', then lookups
3149 are never done. For more information, *Note Extensions::.
3151 `gnu.gcj.runtime.endorsed.dirs'
3152 This is like the standard `java.endorsed.dirs', property, but
3153 specifies some extra directories which are searched after the
3154 standard endorsed directories. This is primarily useful for
3155 telling `libgcj' about additional libraries which are ordinarily
3156 incorporated into the JDK, and which should be loaded by the
3157 bootstrap class loader, but which are not yet part of `libgcj'
3158 itself for some reason.
3160 `gnu.gcj.jit.compiler'
3161 This is the full path to `gcj' executable which should be used to
3162 compile classes just-in-time when `ClassLoader.defineClass' is
3163 called. If not set, `gcj' will not be invoked by the runtime;
3164 this can also be controlled via `Compiler.disable'.
3166 `gnu.gcj.jit.options'
3167 This is a space-separated string of options which should be passed
3168 to `gcj' when in JIT mode. If not set, a sensible default is
3171 `gnu.gcj.jit.cachedir'
3172 This is the directory where cached shared library files are
3173 stored. If not set, JIT compilation is disabled. This should
3174 never be set to a directory that is writable by any other user.
3176 `gnu.gcj.precompiled.db.path'
3177 This is a sequence of file names, each referring to a file created
3178 by `gcj-dbtool'. These files will be used by `libgcj' to find
3179 shared libraries corresponding to classes that are loaded from
3180 bytecode. `libgcj' often has a built-in default database; it can
3181 be queried using `gcj-dbtool -p'.
3185 File: gcj.info, Node: Resources, Prev: System properties, Up: Top
3190 While writing `gcj' and `libgcj' we have, of course, relied heavily on
3191 documentation from Sun Microsystems. In particular we have used The
3192 Java Language Specification (both first and second editions), the Java
3193 Class Libraries (volumes one and two), and the Java Virtual Machine
3194 Specification. In addition we've used the online documentation at
3195 `http://java.sun.com/'.
3197 The current `gcj' home page is `http://gcc.gnu.org/java/'.
3199 For more information on gcc, see `http://gcc.gnu.org/'.
3201 Some `libgcj' testing is done using the Mauve test suite. This is a
3202 free software Java class library test suite which is being written
3203 because the JCK is not free. See `http://sources.redhat.com/mauve/'
3204 for more information.
3210 Node: Copying
\7f4128
3211 Node: GNU Free Documentation License
\7f23296
3212 Node: Invoking gcj
\7f45698
3213 Node: Input and output files
\7f46397
3214 Node: Input Options
\7f47923
3215 Node: Encodings
\7f51071
3216 Node: Warnings
\7f52277
3217 Node: Linking
\7f53390
3218 Node: Code Generation
\7f55623
3219 Node: Configure-time Options
\7f60640
3220 Node: Compatibility
\7f62063
3221 Node: Limitations
\7f62543
3222 Node: Extensions
\7f64125
3223 Node: Invoking gcjh
\7f66723
3224 Node: Invoking gjnih
\7f69078
3225 Node: Invoking jv-scan
\7f71266
3226 Node: Invoking jcf-dump
\7f72308
3227 Node: Invoking gij
\7f73256
3228 Node: Invoking gcj-dbtool
\7f76454
3229 Node: Invoking jv-convert
\7f78920
3230 Node: Invoking grmic
\7f79999
3231 Node: Invoking grmiregistry
\7f81389
3232 Node: About CNI
\7f81802
3233 Node: Basic concepts
\7f83164
3234 Node: Packages
\7f86060
3235 Node: Primitive types
\7f88388
3236 Node: Interfaces
\7f90056
3237 Node: Objects and Classes
\7f90967
3238 Node: Class Initialization
\7f93167
3239 Node: Object allocation
\7f95510
3240 Node: Memory allocation
\7f96300
3241 Node: Arrays
\7f96931
3242 Node: Methods
\7f99535
3243 Node: Strings
\7f102356
3244 Node: Mixing with C++
\7f103840
3245 Node: Exception Handling
\7f107311
3246 Node: Synchronization
\7f108945
3247 Node: Invocation
\7f110935
3248 Node: Reflection
\7f115860
3249 Node: System properties
\7f116321
3250 Node: Standard Properties
\7f117198
3251 Node: GNU Classpath Properties
\7f121630
3252 Node: libgcj Runtime Properties
\7f122676
3253 Node: Resources
\7f126658