1\input texinfo @c -*-texinfo-*- 2@setfilename gcj.info 3@settitle Guide to GNU gcj 4 5@include gcc-common.texi 6 7@c Note: When reading this manual you'll find lots of strange 8@c circumlocutions like ``compiler for the Java language''. 9@c This is necessary due to Sun's restrictions on the use of 10@c the word ``Java'. 11 12@c When this manual is copyrighted. 13@set copyrights-gcj 2001, 2002 14 15@c Versions 16@set which-gcj GCC-@value{version-GCC} 17 18@copying 19@c man begin COPYRIGHT 20Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc. 21 22Permission is granted to copy, distribute and/or modify this document 23under the terms of the GNU Free Documentation License, Version 1.2 or 24any later version published by the Free Software Foundation; with the 25Invariant Sections being ``GNU General Public License'', the Front-Cover 26texts being (a) (see below), and with the Back-Cover Texts being (b) 27(see below). A copy of the license is included in the 28@c man end 29section entitled 30``GNU Free Documentation License''. 31@ignore 32@c man begin COPYRIGHT 33man page gfdl(7). 34@c man end 35@end ignore 36 37@c man begin COPYRIGHT 38 39(a) The FSF's Front-Cover Text is: 40 41 A GNU Manual 42 43(b) The FSF's Back-Cover Text is: 44 45 You have freedom to copy and modify this GNU Manual, like GNU 46 software. Copies published by the Free Software Foundation raise 47 funds for GNU development. 48@c man end 49@end copying 50 51@ifinfo 52@format 53@dircategory Programming 54@direntry 55* Gcj: (gcj). Ahead-of-time compiler for the Java language 56@end direntry 57 58@dircategory Individual utilities 59@direntry 60* gcjh: (gcj)Invoking gcjh. 61 Generate header files from Java class files 62* jv-scan: (gcj)Invoking jv-scan. 63 Print information about Java source files 64* jcf-dump: (gcj)Invoking jcf-dump. 65 Print information about Java class files 66* gij: (gcj)Invoking gij. GNU interpreter for Java bytecode 67* jv-convert: (gcj)Invoking jv-convert. 68 Convert file from one encoding to another 69* rmic: (gcj)Invoking rmic. 70 Generate stubs for Remote Method Invocation. 71* rmiregistry: (gcj)Invoking rmiregistry. 72 The remote object registry. 73@end direntry 74@end format 75 76@insertcopying 77@end ifinfo 78 79@titlepage 80@title GNU gcj 81@author Tom Tromey 82 83@page 84@vskip 0pt plus 1filll 85For the @value{which-gcj} Version* 86@sp 1 87Published by the Free Software Foundation @* 8859 Temple Place - Suite 330@* 89Boston, MA 02111-1307, USA@* 90@sp 1 91@insertcopying 92@end titlepage 93@contents 94@page 95 96 97@node Top 98@top Introduction 99 100This manual describes how to use @command{gcj}, the GNU compiler for the 101Java programming language. @command{gcj} can generate both @file{.class} 102files and object files, and it can read both Java source code and 103@file{.class} files. 104 105@menu 106* Copying:: The GNU General Public License 107* GNU Free Documentation License:: 108 How you can share and copy this manual 109* Invoking gcj:: Compiler options supported by @command{gcj} 110* Compatibility:: Compatibility between gcj and other tools for Java 111* Invoking gcjh:: Generate header files from class files 112* Invoking jv-scan:: Print information about source files 113* Invoking jcf-dump:: Print information about class files 114* Invoking gij:: Interpreting Java bytecodes 115* Invoking jv-convert:: Converting from one encoding to another 116* Invoking rmic:: Generate stubs for Remote Method Invocation. 117* Invoking rmiregistry:: The remote object registry. 118* About CNI:: Description of the Cygnus Native Interface 119* System properties:: Modifying runtime behavior of the libgcj library 120* Resources:: Where to look for more information 121@end menu 122 123 124@include gpl.texi 125 126@include fdl.texi 127 128 129@node Invoking gcj 130@chapter Invoking gcj 131 132@c man title gcj Ahead-of-time compiler for the Java language 133 134@ignore 135@c man begin SYNOPSIS gcj 136gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}] 137 [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}] 138 [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}] 139 [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}] 140 [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}] 141 [@option{-W}@var{warn}@dots{}] 142 @var{sourcefile}@dots{} 143@c man end 144@c man begin SEEALSO gcj 145gcc(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7), 146and the Info entries for @file{gcj} and @file{gcc}. 147@c man end 148@end ignore 149 150@c man begin DESCRIPTION gcj 151 152As @command{gcj} is just another front end to @command{gcc}, it supports many 153of the same options as gcc. @xref{Option Summary, , Option Summary, 154gcc, Using the GNU Compiler Collection (GCC)}. This manual only documents the 155options specific to @command{gcj}. 156 157@c man end 158 159@menu 160* Input and output files:: 161* Input Options:: How gcj finds files 162* Encodings:: Options controlling source file encoding 163* Warnings:: Options controlling warnings specific to gcj 164* Code Generation:: Options controlling the output of gcj 165* Configure-time Options:: Options you won't use 166@end menu 167 168@c man begin OPTIONS gcj 169 170@node Input and output files 171@section Input and output files 172 173A @command{gcj} command is like a @command{gcc} command, in that it 174consists of a number of options and file names. The following kinds 175of input file names are supported: 176 177@table @gcctabopt 178@item @var{file}.java 179Java source files. 180@item @var{file}.class 181Java bytecode files. 182@item @var{file}.zip 183@itemx @var{file}.jar 184An archive containing one or more @code{.class} files, all of 185which are compiled. The archive may be compressed. 186@item @@@var{file} 187A file containing a whitespace-separated list of input file names. 188(Currently, these must all be @code{.java} source files, but that 189may change.) 190Each named file is compiled, just as if it had been on the command line. 191@item @var{library}.a 192@itemx @var{library}.so 193@itemx -l@var{libname} 194Libraries to use when linking. See the @command{gcc} manual. 195@end table 196 197You can specify more than one input file on the @command{gcj} command line, 198in which case they will all be compiled. If you specify a 199@code{-o @var{FILENAME}} 200option, all the input files will be compiled together, producing a 201single output file, named @var{FILENAME}. 202This is allowed even when using @code{-S} or @code{-c}, 203but not when using @code{-C} or @code{--resource}. 204(This is an extension beyond the what plain @command{gcc} allows.) 205(If more than one input file is specified, all must currently 206be @code{.java} files, though we hope to fix this.) 207 208@node Input Options 209@section Input Options 210 211@cindex class path 212 213@command{gcj} has options to control where it looks to find files it needs. 214For instance, @command{gcj} might need to load a class that is referenced 215by the file it has been asked to compile. Like other compilers for the 216Java language, @command{gcj} has a notion of a @dfn{class path}. There are 217several options and environment variables which can be used to 218manipulate the class path. When @command{gcj} looks for a given class, it 219searches the class path looking for matching @file{.class} or 220@file{.java} file. @command{gcj} comes with a built-in class path which 221points at the installed @file{libgcj.jar}, a file which contains all the 222standard classes. 223 224In the below, a directory or path component can refer either to an 225actual directory on the filesystem, or to a @file{.zip} or @file{.jar} 226file, which @command{gcj} will search as if it is a directory. 227 228@table @gcctabopt 229@item -I@var{dir} 230All directories specified by @code{-I} are kept in order and prepended 231to the class path constructed from all the other options. Unless 232compatibility with tools like @code{javac} is important, we recommend 233always using @code{-I} instead of the other options for manipulating the 234class path. 235 236@item --classpath=@var{path} 237This sets the class path to @var{path}, a colon-separated list of paths 238(on Windows-based systems, a semicolon-separate list of paths). 239This does not override the builtin (``boot'') search path. 240 241@item --CLASSPATH=@var{path} 242Deprecated synonym for @code{--classpath}. 243 244@item --bootclasspath=@var{path} 245Where to find the standard builtin classes, such as @code{java.lang.String}. 246 247@item --extdirs=@var{path} 248For each directory in the @var{path}, place the contents of that 249directory at the end of the class path. 250 251@item CLASSPATH 252This is an environment variable which holds a list of paths. 253@end table 254 255The final class path is constructed like so: 256 257@itemize @bullet 258@item 259First come all directories specified via @code{-I}. 260 261@item 262If @option{--classpath} is specified, its value is appended. 263Otherwise, if the @code{CLASSPATH} environment variable is specified, 264then its value is appended. 265Otherwise, the current directory (@code{"."}) is appended. 266 267@item 268If @code{--bootclasspath} was specified, append its value. 269Otherwise, append the built-in system directory, @file{libgcj.jar}. 270 271@item 272Finally, if @code{--extdirs} was specified, append the contents of the 273specified directories at the end of the class path. Otherwise, append 274the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}. 275@end itemize 276 277The classfile built by @command{gcj} for the class @code{java.lang.Object} 278(and placed in @code{libgcj.jar}) contains a special zero length 279attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this 280attribute when loading @code{java.lang.Object} and will report an error 281if it isn't found, unless it compiles to bytecode (the option 282@code{-fforce-classes-archive-check} can be used to override this 283behavior in this particular case.) 284 285@table @gcctabopt 286@item -fforce-classes-archive-check 287This forces the compiler to always check for the special zero length 288attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and 289issue an error if it isn't found. 290@end table 291 292@node Encodings 293@section Encodings 294 295The Java programming language uses Unicode throughout. In an effort to 296integrate well with other locales, @command{gcj} allows @file{.java} files 297to be written using almost any encoding. @command{gcj} knows how to 298convert these encodings into its internal encoding at compile time. 299 300You can use the @code{--encoding=@var{NAME}} option to specify an 301encoding (of a particular character set) to use for source files. If 302this is not specified, the default encoding comes from your current 303locale. If your host system has insufficient locale support, then 304@command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding 305of Unicode. 306 307To implement @code{--encoding}, @command{gcj} simply uses the host 308platform's @code{iconv} conversion routine. This means that in practice 309@command{gcj} is limited by the capabilities of the host platform. 310 311The names allowed for the argument @code{--encoding} vary from platform 312to platform (since they are not standardized anywhere). However, 313@command{gcj} implements the encoding named @samp{UTF-8} internally, so if 314you choose to use this for your source files you can be assured that it 315will work on every host. 316 317 318@node Warnings 319@section Warnings 320 321@command{gcj} implements several warnings. As with other generic 322@command{gcc} warnings, if an option of the form @code{-Wfoo} enables a 323warning, then @code{-Wno-foo} will disable it. Here we've chosen to 324document the form of the warning which will have an effect -- the 325default being the opposite of what is listed. 326 327@table @gcctabopt 328@item -Wredundant-modifiers 329With this flag, @command{gcj} will warn about redundant modifiers. For 330instance, it will warn if an interface method is declared @code{public}. 331 332@item -Wextraneous-semicolon 333This causes @command{gcj} to warn about empty statements. Empty statements 334have been deprecated. 335 336@item -Wno-out-of-date 337This option will cause @command{gcj} not to warn when a source file is 338newer than its matching class file. By default @command{gcj} will warn 339about this. 340 341@item -Wunused 342This is the same as @command{gcc}'s @code{-Wunused}. 343 344@item -Wall 345This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon 346-Wunused}. 347@end table 348 349 350@node Code Generation 351@section Code Generation 352 353In addition to the many @command{gcc} options controlling code generation, 354@command{gcj} has several options specific to itself. 355 356@table @gcctabopt 357@item --main=@var{CLASSNAME} 358This option is used when linking to specify the name of the class whose 359@code{main} method should be invoked when the resulting executable is 360run. @footnote{The linker by default looks for a global function named 361@code{main}. Since Java does not have global functions, and a 362collection of Java classes may have more than one class with a 363@code{main} method, you need to let the linker know which of those 364@code{main} methods it should invoke when starting the application.} 365 366@item -D@var{name}[=@var{value}] 367This option can only be used with @code{--main}. It defines a system 368property named @var{name} with value @var{value}. If @var{value} is not 369specified then it defaults to the empty string. These system properties 370are initialized at the program's startup and can be retrieved at runtime 371using the @code{java.lang.System.getProperty} method. 372 373@item -C 374This option is used to tell @command{gcj} to generate bytecode 375(@file{.class} files) rather than object code. 376 377@item --resource @var{resource-name} 378This option is used to tell @command{gcj} to compile the contents of a 379given file to object code so it may be accessed at runtime with the core 380protocol handler as @samp{core:/@var{resource-name}}. Note that 381@var{resource-name} is the name of the resource as found at runtime; for 382instance, it could be used in a call to @code{ResourceBundle.getBundle}. 383The actual file name to be compiled this way must be specified 384separately. 385 386@item -d @var{directory} 387When used with @code{-C}, this causes all generated @file{.class} files 388to be put in the appropriate subdirectory of @var{directory}. By 389default they will be put in subdirectories of the current working 390directory. 391 392@item -fno-bounds-check 393By default, @command{gcj} generates code which checks the bounds of all 394array indexing operations. With this option, these checks are omitted, which 395can improve performance for code that uses arrays extensively. Note that this 396can result in unpredictable behavior if the code in question actually does 397violate array bounds constraints. It is safe to use this option if you are 398sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}. 399 400@item -fno-store-check 401Don't generate array store checks. When storing objects into arrays, a runtime 402check is normally generated in order to ensure that the object is assignment 403compatible with the component type of the array (which may not be known 404at compile-time). With this option, these checks are omitted. This can 405improve performance for code which stores objects into arrays frequently. 406It is safe to use this option if you are sure your code will never throw an 407@code{ArrayStoreException}. 408 409@item -fjni 410With @command{gcj} there are two options for writing native methods: CNI 411and JNI@. By default @command{gcj} assumes you are using CNI@. If you are 412compiling a class with native methods, and these methods are implemented 413using JNI, then you must use @code{-fjni}. This option causes 414@command{gcj} to generate stubs which will invoke the underlying JNI 415methods. 416 417@item -fno-assert 418Don't recognize the @code{assert} keyword. This is for compatibility 419with older versions of the language specification. 420 421@item -fno-optimize-static-class-initialization 422When the optimization level is greater or equal to @code{-O2}, 423@command{gcj} will try to optimize the way calls into the runtime are made 424to initialize static classes upon their first use (this optimization 425isn't carried out if @code{-C} was specified.) When compiling to native 426code, @code{-fno-optimize-static-class-initialization} will turn this 427optimization off, regardless of the optimization level in use. 428@end table 429 430 431@node Configure-time Options 432@section Configure-time Options 433 434Some @command{gcj} code generations options affect the resulting ABI, and 435so can only be meaningfully given when @code{libgcj}, the runtime 436package, is configured. @code{libgcj} puts the appropriate options from 437this group into a @samp{spec} file which is read by @command{gcj}. These 438options are listed here for completeness; if you are using @code{libgcj} 439then you won't want to touch these options. 440 441@table @gcctabopt 442@item -fuse-boehm-gc 443This enables the use of the Boehm GC bitmap marking code. In particular 444this causes @command{gcj} to put an object marking descriptor into each 445vtable. 446 447@item -fhash-synchronization 448By default, synchronization data (the data used for @code{synchronize}, 449@code{wait}, and @code{notify}) is pointed to by a word in each object. 450With this option @command{gcj} assumes that this information is stored in a 451hash table and not in the object itself. 452 453@item -fuse-divide-subroutine 454On some systems, a library routine is called to perform integer 455division. This is required to get exception handling correct when 456dividing by zero. 457 458@item -fcheck-references 459On some systems it's necessary to insert inline checks whenever 460accessing an object via a reference. On other systems you won't need 461this because null pointer accesses are caught automatically by the 462processor. 463@end table 464 465@c man end 466 467@node Compatibility 468@chapter Compatibility with the Java Platform 469 470As we believe it is important that the Java platform not be fragmented, 471@command{gcj} and @code{libgcj} try to conform to the relevant Java 472specifications. However, limited manpower and incomplete and unclear 473documentation work against us. So, there are caveats to using 474@command{gcj}. 475 476@menu 477* Limitations:: 478* Extensions:: 479@end menu 480 481@node Limitations 482@section Standard features not yet supported 483 484This list of compatibility issues is by no means complete. 485 486@itemize @bullet 487@item 488@command{gcj} implements the JDK 1.2 language. It supports inner classes 489and the new 1.4 @code{assert} keyword. It does not yet support the Java 2 490@code{strictfp} keyword (it recognizes the keyword but ignores it). 491 492@item 493@code{libgcj} is largely compatible with the JDK 1.2 libraries. 494However, @code{libgcj} is missing many packages, most notably 495@code{java.awt}. There are also individual missing classes and methods. 496We currently do not have a list showing differences between 497@code{libgcj} and the Java 2 platform. 498 499@item 500Sometimes the @code{libgcj} implementation of a method or class differs 501from the JDK implementation. This is not always a bug. Still, if it 502affects you, it probably makes sense to report it so that we can discuss 503the appropriate response. 504 505@item 506@command{gcj} does not currently allow for piecemeal replacement of 507components within @code{libgcj}. Unfortunately, programmers often want 508to use newer versions of certain packages, such as those provided by 509the Apache Software Foundation's Jakarta project. This has forced us 510to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into 511their own libraries, separate from @code{libgcj}. If you intend to 512use these classes, you must link them explicitly with 513@code{-l-org-w3c-dom} and @code{-l-org-xml-sax}. Future versions of 514@command{gcj} may not have this restriction. 515@end itemize 516 517@node Extensions 518@section Extra features unique to gcj 519 520The main feature of @command{gcj} is that it can compile programs 521written in the Java programming language to native code. Most 522extensions that have been added are to facilitate this functionality. 523 524@itemize @bullet 525@item 526@command{gcj} makes it easy and efficient to mix code written in Java and C++. 527@xref{About CNI}, for more info on how to use this in your programs. 528 529@item 530When you compile your classes into a shared library they can be automatically 531loaded by the @code{libgcj} system classloader. When trying to load a class 532@code{gnu.pkg.SomeClass} the system classloader will first try to load the 533shared library @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the 534class then it will try to load @file{lib-gnu-pkg.so} and finally when the 535class is still not loaded it will try to load @file{lib-gnu.so}. Note that 536all @samp{.}s will be transformed into @samp{-}s and that searching 537for inner classes starts with their outermost outer class. If the class 538cannot be found this way the system classloader tries to use 539the @code{libgcj} bytecode interpreter to load the class from the standard 540classpath. 541@end itemize 542 543@node Invoking gcjh 544@chapter Invoking gcjh 545 546@c man title gcjh generate header files from Java class files 547 548@c man begin DESCRIPTION gcjh 549 550The @code{gcjh} program is used to generate header files from class 551files. It can generate both CNI and JNI header files, as well as stub 552implementation files which can be used as a basis for implementing the 553required native methods. 554 555@c man end 556 557@ignore 558@c man begin SYNOPSIS gcjh 559gcjh [@option{-stubs}] [@option{-jni}] 560 [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}] 561 [@option{-preprend} @var{text}] 562 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}] 563 [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}] 564 [@option{-o} @var{file}] [@option{-td} @var{dir}] 565 [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}] 566 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}] 567 @var{classname}@dots{} 568@c man end 569@c man begin SEEALSO gcjh 570gcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7), 571and the Info entries for @file{gcj} and @file{gcc}. 572@c man end 573@end ignore 574 575@c man begin OPTIONS gcjh 576 577@table @gcctabopt 578@item -stubs 579This causes @code{gcjh} to generate stub files instead of header files. 580By default the stub file will be named after the class, with a suffix of 581@samp{.cc}. In JNI mode, the default output file will have the suffix 582@samp{.c}. 583 584@item -jni 585This tells @code{gcjh} to generate a JNI header or stub. By default, 586CNI headers are generated. 587 588@item -add @var{text} 589Inserts @var{text} into the class body. This is ignored in JNI mode. 590 591@item -append @var{text} 592Inserts @var{text} into the header file after the class declaration. 593This is ignored in JNI mode. 594 595@item -friend @var{text} 596Inserts @var{text} into the class as a @code{friend} declaration. 597This is ignored in JNI mode. 598 599@item -prepend @var{text} 600Inserts @var{text} into the header file before the class declaration. 601This is ignored in JNI mode. 602 603@item --classpath=@var{path} 604@itemx --CLASSPATH=@var{path} 605@itemx -I@var{directory} 606@itemx -d @var{directory} 607@itemx -o @var{file} 608These options are all identical to the corresponding @command{gcj} options. 609 610@item -o @var{file} 611Sets the output file name. This cannot be used if there is more than 612one class on the command line. 613 614@item -td @var{directory} 615Sets the name of the directory to use for temporary files. 616 617@item -M 618Print all dependencies to stdout; suppress ordinary output. 619 620@item -MM 621Print non-system dependencies to stdout; suppress ordinary output. 622 623@item -MD 624Print all dependencies to stdout. 625 626@item -MMD 627Print non-system dependencies to stdout. 628 629@item --help 630Print help about @code{gcjh} and exit. No further processing is done. 631 632@item --version 633Print version information for @code{gcjh} and exit. No further 634processing is done. 635 636@item -v, --verbose 637Print extra information while running. 638@end table 639 640All remaining options are considered to be names of classes. 641 642@c man end 643 644@node Invoking jv-scan 645@chapter Invoking jv-scan 646 647@c man title jv-scan print information about Java source file 648 649@c man begin DESCRIPTION jv-scan 650 651The @code{jv-scan} program can be used to print information about a Java 652source file (@file{.java} file). 653 654@c man end 655 656@ignore 657@c man begin SYNOPSIS jv-scan 658jv-scan [@option{--no-assert}] [@option{--complexity}] 659 [@option{--encoding}=@var{name}] [@option{--print-main}] 660 [@option{--list-class}] [@option{--list-filename}] 661 [@option{--version}] [@option{--help}] 662 [@option{-o} @var{file}] @var{inputfile}@dots{} 663@c man end 664@c man begin SEEALSO jv-scan 665gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7), 666and the Info entries for @file{gcj} and @file{gcc}. 667@c man end 668@end ignore 669 670@c man begin OPTIONS jv-scan 671 672@table @gcctabopt 673@item --no-assert 674Don't recognize the @code{assert} keyword, for backwards compatibility 675with older versions of the language specification. 676 677@item --complexity 678This prints a complexity measure, related to cyclomatic complexity, for 679each input file. 680 681@item --encoding=@var{name} 682This works like the corresponding @command{gcj} option. 683 684@item --print-main 685This prints the name of the class in this file containing a @code{main} 686method. 687 688@item --list-class 689This lists the names of all classes defined in the input files. 690 691@item --list-filename 692If @code{--list-class} is given, this option causes @code{jv-scan} to 693also print the name of the file in which each class was found. 694 695@item -o @var{file} 696Print output to the named file. 697 698@item --help 699Print help, then exit. 700 701@item --version 702Print version number, then exit. 703@end table 704 705@c man end 706 707@node Invoking jcf-dump 708@chapter Invoking jcf-dump 709 710@c man title jcf-dump print information about Java class files 711 712@ignore 713@c man begin SYNOPSIS jcf-dump 714jcf-dump [@option{-c}] [@option{--javap}] 715 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}] 716 [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}] 717 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}] 718 @var{classname}@dots{} 719@c man end 720@c man begin SEEALSO jcf-dump 721gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7), 722and the Info entries for @file{gcj} and @file{gcc}. 723@c man end 724@end ignore 725 726@c man begin DESCRIPTION jcf-dump 727 728This is a class file examiner, similar to @code{javap}. It will print 729information about a number of classes, which are specified by class name 730or file name. 731 732@c man end 733 734@c man begin OPTIONS jcf-dump 735 736@table @gcctabopt 737@item -c 738Disassemble method bodies. By default method bodies are not printed. 739 740@item --javap 741Generate output in @code{javap} format. The implementation of this 742feature is very incomplete. 743 744@item --classpath=@var{path} 745@itemx --CLASSPATH=@var{path} 746@itemx -I@var{directory} 747@itemx -o @var{file} 748These options as the same as the corresponding @command{gcj} options. 749 750@item --help 751Print help, then exit. 752 753@item --version 754Print version number, then exit. 755 756@item -v, --verbose 757Print extra information while running. 758@end table 759 760@c man end 761 762@node Invoking gij 763@chapter Invoking gij 764 765@c man title gij GNU interpreter for Java bytecode 766 767@ignore 768@c man begin SYNOPSIS gij 769gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}] 770 771gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}] 772 [@option{-cp} @var{path}] [@option{-classpath} @var{path}] 773 [@option{-D}@var{name}[=@var{value}]@dots{}] 774 [@option{-ms=}@var{number}] [@option{-mx=}@var{number}] 775 [@option{--showversion}] [@option{--version}] [@option{--help}] 776@c man end 777@c man begin SEEALSO gij 778gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7), 779and the Info entries for @file{gcj} and @file{gcc}. 780@c man end 781@end ignore 782 783@c man begin DESCRIPTION gij 784 785@code{gij} is a Java bytecode interpreter included with @code{libgcj}. 786@code{gij} is not available on every platform; porting it requires a 787small amount of assembly programming which has not been done for all the 788targets supported by @command{gcj}. 789 790The primary argument to @code{gij} is the name of a class or, with 791@code{-jar}, a jar file. Options before this argument are interpreted 792by @code{gij}; remaining options are passed to the interpreted program. 793 794If a class name is specified and this class does not have a @code{main} 795method with the appropriate signature (a @code{static void} method with 796a @code{String[]} as its sole argument), then @code{gij} will print an 797error and exit. 798 799If a jar file is specified then @code{gij} will use information in it to 800determine which class' @code{main} method will be invoked. 801 802@code{gij} will invoke the @code{main} method with all the remaining 803command-line options. 804 805Note that @code{gij} is not limited to interpreting code. Because 806@code{libgcj} includes a class loader which can dynamically load shared 807objects, it is possible to give @code{gij} the name of a class which has 808been compiled and put into a shared library on the class path. 809 810@c man end 811 812@c man begin OPTIONS gij 813 814@table @gcctabopt 815@item -cp @var{path} 816@itemx -classpath @var{path} 817Set the initial class path. The class path is used for finding 818class and resource files. If specified, this option overrides the 819@code{CLASSPATH} environment variable. Note that this option is 820ignored if @code{-jar} is used. 821 822@item -D@var{name}[=@var{value}] 823This defines a system property named @var{name} with value @var{value}. 824If @var{value} is not specified then it defaults to the empty string. 825These system properties are initialized at the program's startup and can 826be retrieved at runtime using the @code{java.lang.System.getProperty} 827method. 828 829@item -ms=@var{number} 830This sets the initial heap size. 831 832@item -mx=@var{number} 833This sets the maximum heap size. 834 835@item -jar 836This indicates that the name passed to @code{gij} should be interpreted 837as the name of a jar file, not a class. 838 839@item --help 840Print help, then exit. 841 842@item --showversion 843Print version number and continue. 844 845@item --version 846Print version number, then exit. 847@end table 848 849@c man end 850 851@node Invoking jv-convert 852@chapter Invoking jv-convert 853 854@c man title jv-convert Convert file from one encoding to another 855 856@c man begin SYNOPSIS jv-convert 857@command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]] 858@ignore 859 860 [@option{--encoding} @var{name}] 861 [@option{--from} @var{name}] 862 [@option{--to} @var{name}] 863 [@option{-i} @var{file}] [@option{-o} @var{file}] 864 [@option{--reverse}] [@option{--help}] [@option{--version}] 865@end ignore 866@c man end 867 868@c man begin DESCRIPTION jv-convert 869 870@command{jv-convert} is a utility included with @code{libgcj} which 871converts a file from one encoding to another. It is similar to the Unix 872@command{iconv} utility. 873 874The encodings supported by @command{jv-convert} are platform-dependent. 875Currently there is no way to get a list of all supported encodings. 876 877@c man end 878 879@c man begin OPTIONS jv-convert 880 881@table @gcctabopt 882@item --encoding @var{name} 883@itemx --from @var{name} 884Use @var{name} as the input encoding. The default is the current 885locale's encoding. 886 887@item --to @var{name} 888Use @var{name} as the output encoding. The default is the 889@code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for 890non-ASCII characters. 891 892@item -i @var{file} 893Read from @var{file}. The default is to read from standard input. 894 895@item -o @var{file} 896Write to @var{file}. The default is to write to standard output. 897 898@item --reverse 899Swap the input and output encodings. 900 901@item --help 902Print a help message, then exit. 903 904@item --version 905Print version information, then exit. 906@end table 907 908@c man end 909 910@node Invoking rmic 911@chapter Invoking rmic 912 913@c man title rmic Generate stubs for Remote Method Invocation 914 915@c man begin SYNOPSIS rmic 916@command{rmic} [@option{OPTION}] @dots{} @var{class} @dots{} 917@ignore 918 [@option{-keep}] 919 [@option{-keepgenerated}] 920 [@option{-v1.1}] 921 [@option{-vcompat}] 922 [@option{-v1.2}] 923 [@option{-nocompile}] 924 [@option{-verbose}] 925 [@option{-d} @var{directory}] 926 [@option{-help}] 927 [@option{-version}] 928@end ignore 929@c man end 930 931@c man begin DESCRIPTION rmic 932 933@command{rmic} is a utility included with @code{libgcj} which generates 934stubs for remote objects. 935 936@c FIXME: Add real information here. 937@c This really isn't much more than the --help output. 938 939Note that this program isn't yet fully compatible with the JDK 940@command{rmic}. Some options, such as @option{-classpath}, are 941recognized but currently ignored. We have left these options 942undocumented for now. 943 944Long options can also be given with a GNU-style leading @samp{--}. For 945instance, @option{--help} is accepted. 946 947@c man end 948 949@c man begin OPTIONS rmic 950 951@table @gcctabopt 952@item -keep 953@itemx -keepgenerated 954By default, @command{rmic} deletes intermediate files. Either of these 955options causes it not to delete such files. 956 957@item -v1.1 958Cause @command{rmic} to create stubs and skeletons for the 1.1 959protocol version. 960 961@item -vcompat 962Cause @command{rmic} to create stubs and skeletons compatible with both 963the 1.1 and 1.2 protocol versions. This is the default. 964 965@item -v1.2 966Cause @command{rmic} to create stubs and skeletons for the 1.2 967protocol version. 968 969@item -nocompile 970Don't compile the generated files. 971 972@item -verbose 973Print information about what @command{rmic} is doing. 974 975@item -d @var{directory} 976Put output files in @var{directory}. By default the files are put in 977the current working directory. 978 979@item -help 980Print a help message, then exit. 981 982@item -version 983Print version information, then exit. 984@end table 985 986@c man end 987 988 989@node Invoking rmiregistry 990@chapter Invoking rmiregistry 991 992@c man title rmiregistry Remote object registry 993 994@c man begin SYNOPSIS rmiregistry 995@command{rmic} [@option{OPTION}] @dots{} [@var{port}] 996@ignore 997 [@option{--help}] 998 [@option{--version}] 999@end ignore 1000@c man end 1001 1002@c man begin DESCRIPTION rmiregistry 1003 1004@command{rmiregistry} starts a remote object registry on the current 1005host. If no port number is specified, then port 1099 is used. 1006 1007@c FIXME: Add real information here. 1008@c This really isn't much more than the --help output. 1009 1010@c man end 1011 1012@c man begin OPTIONS rmiregistry 1013 1014@table @gcctabopt 1015@item --help 1016Print a help message, then exit. 1017 1018@item --version 1019Print version information, then exit. 1020@end table 1021 1022@c man end 1023 1024 1025@node About CNI 1026@chapter About CNI 1027 1028This documents CNI, the Cygnus Native Interface, 1029which is is a convenient way to write Java native methods using C++. 1030This is a more efficient, more convenient, but less portable 1031alternative to the standard JNI (Java Native Interface). 1032 1033@menu 1034* Basic concepts:: Introduction to using CNI@. 1035* Packages:: How packages are mapped to C++. 1036* Primitive types:: Handling Java types in C++. 1037* Interfaces:: How Java interfaces map to C++. 1038* Objects and Classes:: C++ and Java classes. 1039* Class Initialization:: How objects are initialized. 1040* Object allocation:: How to create Java objects in C++. 1041* Arrays:: Dealing with Java arrays in C++. 1042* Methods:: Java methods in C++. 1043* Strings:: Information about Java Strings. 1044* Mixing with C++:: How CNI can interoperate with C++. 1045* Exception Handling:: How exceptions are handled. 1046* Synchronization:: Synchronizing between Java and C++. 1047* Invocation:: Starting the Java runtime from C++. 1048* Reflection:: Using reflection from C++. 1049@end menu 1050 1051 1052@node Basic concepts 1053@section Basic concepts 1054 1055In terms of languages features, Java is mostly a subset 1056of C++. Java has a few important extensions, plus a powerful standard 1057class library, but on the whole that does not change the basic similarity. 1058Java is a hybrid object-oriented language, with a few native types, 1059in addition to class types. It is class-based, where a class may have 1060static as well as per-object fields, and static as well as instance methods. 1061Non-static methods may be virtual, and may be overloaded. Overloading is 1062resolved at compile time by matching the actual argument types against 1063the parameter types. Virtual methods are implemented using indirect calls 1064through a dispatch table (virtual function table). Objects are 1065allocated on the heap, and initialized using a constructor method. 1066Classes are organized in a package hierarchy. 1067 1068All of the listed attributes are also true of C++, though C++ has 1069extra features (for example in C++ objects may be allocated not just 1070on the heap, but also statically or in a local stack frame). Because 1071@command{gcj} uses the same compiler technology as G++ (the GNU 1072C++ compiler), it is possible to make the intersection of the two 1073languages use the same ABI (object representation and calling 1074conventions). The key idea in CNI is that Java objects are C++ 1075objects, and all Java classes are C++ classes (but not the other way 1076around). So the most important task in integrating Java and C++ is to 1077remove gratuitous incompatibilities. 1078 1079You write CNI code as a regular C++ source file. (You do have to use 1080a Java/CNI-aware C++ compiler, specifically a recent version of G++.) 1081 1082@noindent A CNI C++ source file must have: 1083 1084@example 1085#include <gcj/cni.h> 1086@end example 1087 1088@noindent and then must include one header file for each Java class it uses, e.g.: 1089 1090@example 1091#include <java/lang/Character.h> 1092#include <java/util/Date.h> 1093#include <java/lang/IndexOutOfBoundsException.h> 1094@end example 1095 1096@noindent These header files are automatically generated by @code{gcjh}. 1097 1098 1099CNI provides some functions and macros to make using Java objects and 1100primitive types from C++ easier. In general, these CNI functions and 1101macros start with the @code{Jv} prefix, for example the function 1102@code{JvNewObjectArray}. This convention is used to avoid conflicts 1103with other libraries. Internal functions in CNI start with the prefix 1104@code{_Jv_}. You should not call these; if you find a need to, let us 1105know and we will try to come up with an alternate solution. (This 1106manual lists @code{_Jv_AllocBytes} as an example; CNI should instead 1107provide a @code{JvAllocBytes} function.) 1108 1109 1110@subsection Limitations 1111 1112Whilst a Java class is just a C++ class that doesn't mean that you are 1113freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the 1114rules of the Java programming language. 1115 1116For example: it is not possible to declare a method in a CNI class 1117that will take a C string (@code{char*}) as an argument, or to declare a 1118member variable of some non-Java datatype. 1119 1120 1121@node Packages 1122@section Packages 1123 1124The only global names in Java are class names, and packages. A 1125@dfn{package} can contain zero or more classes, and also zero or more 1126sub-packages. Every class belongs to either an unnamed package or a 1127package that has a hierarchical and globally unique name. 1128 1129A Java package is mapped to a C++ @dfn{namespace}. The Java class 1130@code{java.lang.String} is in the package @code{java.lang}, which is a 1131sub-package of @code{java}. The C++ equivalent is the class 1132@code{java::lang::String}, which is in the namespace @code{java::lang} 1133which is in the namespace @code{java}. 1134 1135@noindent Here is how you could express this: 1136 1137@example 1138(// @r{Declare the class(es), possibly in a header file:} 1139namespace java @{ 1140 namespace lang @{ 1141 class Object; 1142 class String; 1143 ... 1144 @} 1145@} 1146 1147class java::lang::String : public java::lang::Object 1148@{ 1149 ... 1150@}; 1151@end example 1152 1153@noindent The @code{gcjh} tool automatically generates the necessary namespace 1154declarations. 1155 1156 1157@subsection Leaving out package names 1158 1159Always using the fully-qualified name of a java class can be 1160tiresomely verbose. Using the full qualified name also ties the code 1161to a single package making code changes necessary should the class 1162move from one package to another. The Java @code{package} declaration 1163specifies that the following class declarations are in the named 1164package, without having to explicitly name the full package 1165qualifiers. The @code{package} declaration can be 1166followed by zero or more @code{import} declarations, which 1167allows either a single class or all the classes in a package to be 1168named by a simple identifier. C++ provides something similar with the 1169@code{using} declaration and directive. 1170 1171@noindent In Java: 1172 1173@example 1174import @var{package-name}.@var{class-name}; 1175@end example 1176 1177@noindent allows the program text to refer to @var{class-name} as a shorthand for 1178the fully qualified name: @code{@var{package-name}.@var{class-name}}. 1179 1180 1181@noindent To achieve the same effect C++, you have to do this: 1182 1183@example 1184using @var{package-name}::@var{class-name}; 1185@end example 1186 1187 1188@noindent Java can also cause imports on demand, like this: 1189 1190@example 1191import @var{package-name}.*; 1192@end example 1193 1194@noindent Doing this allows any class from the package @var{package-name} to be 1195referred to only by its class-name within the program text. 1196 1197 1198@noindent The same effect can be achieved in C++ like this: 1199 1200@example 1201using namespace @var{package-name}; 1202@end example 1203 1204 1205@node Primitive types 1206@section Primitive types 1207 1208Java provides 8 @dfn{primitives} types which represent integers, floats, 1209characters and booleans (and also the void type). C++ has its own 1210very similar concrete types. Such types in C++ however are not always 1211implemented in the same way (an int might be 16, 32 or 64 bits for example) 1212so CNI provides a special C++ type for each primitive Java type: 1213 1214@multitable @columnfractions .20 .25 .60 1215@item @strong{Java type} @tab @strong{C/C++ typename} @tab @strong{Description} 1216@item @code{char} @tab @code{jchar} @tab 16 bit Unicode character 1217@item @code{boolean} @tab @code{jboolean} @tab logical (true or false) values 1218@item @code{byte} @tab @code{jbyte} @tab 8-bit signed integer 1219@item @code{short} @tab @code{jshort} @tab 16 bit signed integer 1220@item @code{int} @tab @code{jint} @tab 32 bit signed integer 1221@item @code{long} @tab @code{jlong} @tab 64 bit signed integer 1222@item @code{float} @tab @code{jfloat} @tab 32 bit IEEE floating point number 1223@item @code{double} @tab @code{jdouble} @tab 64 bit IEEE floating point number 1224@item @code{void} @tab @code{void} @tab no value 1225@end multitable 1226 1227When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint}) 1228to avoid disappointment. 1229 1230 1231@subsection Reference types associated with primitive types 1232 1233In Java each primitive type has an associated reference type, 1234e.g.: @code{boolean} has an associated @code{java.lang.Boolean} class. 1235In order to make working with such classes easier GCJ provides the macro 1236@code{JvPrimClass}: 1237 1238@deffn macro JvPrimClass type 1239Return a pointer to the @code{Class} object corresponding to the type supplied. 1240 1241@example 1242JvPrimClass(void) @result{} java.lang.Void.TYPE 1243@end example 1244 1245@end deffn 1246 1247 1248@node Interfaces 1249@section Interfaces 1250 1251A Java class can @dfn{implement} zero or more 1252@dfn{interfaces}, in addition to inheriting from 1253a single base class. 1254 1255@acronym{CNI} allows CNI code to implement methods of interfaces. 1256You can also call methods through interface references, with some 1257limitations. 1258 1259@acronym{CNI} doesn't understand interface inheritance at all yet. So, 1260you can only call an interface method when the declared type of the 1261field being called matches the interface which declares that 1262method. The workaround is to cast the interface reference to the right 1263superinterface. 1264 1265For example if you have: 1266 1267@example 1268interface A 1269@{ 1270 void a(); 1271@} 1272 1273interface B extends A 1274@{ 1275 void b(); 1276@} 1277@end example 1278 1279and declare a variable of type @code{B} in C++, you can't call 1280@code{a()} unless you cast it to an @code{A} first. 1281 1282@node Objects and Classes 1283@section Objects and Classes 1284 1285@subsection Classes 1286 1287All Java classes are derived from @code{java.lang.Object}. C++ does 1288not have a unique root class, but we use the C++ class 1289@code{java::lang::Object} as the C++ version of the 1290@code{java.lang.Object} Java class. All other Java classes are mapped 1291into corresponding C++ classes derived from @code{java::lang::Object}. 1292 1293Interface inheritance (the @code{implements} keyword) is currently not 1294reflected in the C++ mapping. 1295 1296 1297@subsection Object fields 1298 1299Each object contains an object header, followed by the instance fields 1300of the class, in order. The object header consists of a single 1301pointer to a dispatch or virtual function table. (There may be extra 1302fields @emph{in front of} the object, for example for memory 1303management, but this is invisible to the application, and the 1304reference to the object points to the dispatch table pointer.) 1305 1306The fields are laid out in the same order, alignment, and size as in 1307C++. Specifically, 8-bite and 16-bit native types (@code{byte}, 1308@code{short}, @code{char}, and @code{boolean}) are @emph{not} widened 1309to 32 bits. Note that the Java VM does extend 8-bit and 16-bit types 1310to 32 bits when on the VM stack or temporary registers. 1311 1312If you include the @code{gcjh}-generated header for a 1313class, you can access fields of Java classes in the @emph{natural} 1314way. For example, given the following Java class: 1315 1316@example 1317public class Int 1318@{ 1319 public int i; 1320 public Integer (int i) @{ this.i = i; @} 1321 public static zero = new Integer(0); 1322@} 1323@end example 1324 1325you can write: 1326 1327@example 1328#include <gcj/cni.h>; 1329#include <Int>; 1330 1331Int* 1332mult (Int *p, jint k) 1333@{ 1334 if (k == 0) 1335 return Int::zero; // @r{Static member access.} 1336 return new Int(p->i * k); 1337@} 1338@end example 1339 1340 1341@subsection Access specifiers 1342 1343CNI does not strictly enforce the Java access 1344specifiers, because Java permissions cannot be directly mapped 1345into C++ permission. Private Java fields and methods are mapped 1346to private C++ fields and methods, but other fields and methods 1347are mapped to public fields and methods. 1348 1349 1350 1351@node Class Initialization 1352@section Class Initialization 1353 1354Java requires that each class be automatically initialized at the time 1355of the first active use. Initializing a class involves 1356initializing the static fields, running code in class initializer 1357methods, and initializing base classes. There may also be 1358some implementation specific actions, such as allocating 1359@code{String} objects corresponding to string literals in 1360the code. 1361 1362The GCJ compiler inserts calls to @code{JvInitClass} at appropriate 1363places to ensure that a class is initialized when required. The C++ 1364compiler does not insert these calls automatically---it is the 1365programmer's responsibility to make sure classes are initialized. 1366However, this is fairly painless because of the conventions assumed by 1367the Java system. 1368 1369First, @code{libgcj} will make sure a class is initialized before an 1370instance of that object is created. This is one of the 1371responsibilities of the @code{new} operation. This is taken care of 1372both in Java code, and in C++ code. When G++ sees a @code{new} of a 1373Java class, it will call a routine in @code{libgcj} to allocate the 1374object, and that routine will take care of initializing the class. 1375Note however that this does not happen for Java arrays; you must 1376allocate those using the appropriate CNI function. It follows that 1377you can access an instance field, or call an instance (non-static) 1378method and be safe in the knowledge that the class and all of its base 1379classes have been initialized. 1380 1381Invoking a static method is also safe. This is because the 1382Java compiler adds code to the start of a static method to make sure 1383the class is initialized. However, the C++ compiler does not 1384add this extra code. Hence, if you write a native static method 1385using CNI, you are responsible for calling @code{JvInitClass} 1386before doing anything else in the method (unless you are sure 1387it is safe to leave it out). 1388 1389Accessing a static field also requires the class of the 1390field to be initialized. The Java compiler will generate code 1391to call @code{Jv_InitClass} before getting or setting the field. 1392However, the C++ compiler will not generate this extra code, 1393so it is your responsibility to make sure the class is 1394initialized before you access a static field from C++. 1395 1396 1397@node Object allocation 1398@section Object allocation 1399 1400New Java objects are allocated using a 1401@dfn{class instance creation expression}, e.g.: 1402 1403@example 1404new @var{Type} ( ... ) 1405@end example 1406 1407The same syntax is used in C++. The main difference is that 1408C++ objects have to be explicitly deleted; in Java they are 1409automatically deleted by the garbage collector. 1410Using @acronym{CNI}, you can allocate a new Java object 1411using standard C++ syntax and the C++ compiler will allocate 1412memory from the garbage collector. If you have overloaded 1413constructors, the compiler will choose the correct one 1414using standard C++ overload resolution rules. 1415 1416@noindent For example: 1417 1418@example 1419java::util::Hashtable *ht = new java::util::Hashtable(120); 1420@end example 1421 1422@deftypefun void* _Jv_AllocBytes (jsize @var{size}) 1423Allocates @var{size} bytes from the heap. The memory is not scanned 1424by the garbage collector but it freed if no references to it are discovered. 1425@end deftypefun 1426 1427 1428@node Arrays 1429@section Arrays 1430 1431While in many ways Java is similar to C and C++, it is quite different 1432in its treatment of arrays. C arrays are based on the idea of pointer 1433arithmetic, which would be incompatible with Java's security 1434requirements. Java arrays are true objects (array types inherit from 1435@code{java.lang.Object}). An array-valued variable is one that 1436contains a reference (pointer) to an array object. 1437 1438Referencing a Java array in C++ code is done using the 1439@code{JArray} template, which as defined as follows: 1440 1441@example 1442class __JArray : public java::lang::Object 1443@{ 1444public: 1445 int length; 1446@}; 1447 1448template<class T> 1449class JArray : public __JArray 1450@{ 1451 T data[0]; 1452public: 1453 T& operator[](jint i) @{ return data[i]; @} 1454@}; 1455@end example 1456 1457 1458There are a number of @code{typedef}s which correspond to @code{typedef}s 1459from the @acronym{JNI}. Each is the type of an array holding objects 1460of the relevant type: 1461 1462@example 1463typedef __JArray *jarray; 1464typedef JArray<jobject> *jobjectArray; 1465typedef JArray<jboolean> *jbooleanArray; 1466typedef JArray<jbyte> *jbyteArray; 1467typedef JArray<jchar> *jcharArray; 1468typedef JArray<jshort> *jshortArray; 1469typedef JArray<jint> *jintArray; 1470typedef JArray<jlong> *jlongArray; 1471typedef JArray<jfloat> *jfloatArray; 1472typedef JArray<jdouble> *jdoubleArray; 1473@end example 1474 1475 1476@deftypemethod {template<class T>} T* elements (JArray<T> @var{array}) 1477This template function can be used to get a pointer to the elements of 1478the @code{array}. For instance, you can fetch a pointer to the 1479integers that make up an @code{int[]} like so: 1480 1481@example 1482extern jintArray foo; 1483jint *intp = elements (foo); 1484@end example 1485 1486The name of this function may change in the future. 1487@end deftypemethod 1488 1489 1490@deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init}) 1491Here @code{klass} is the type of elements of the array and 1492@code{init} is the initial value put into every slot in the array. 1493@end deftypefun 1494 1495 1496@subsection Creating arrays 1497 1498For each primitive type there is a function which can be used to 1499create a new array of that type. The name of the function is of the 1500form: 1501 1502@example 1503JvNew@var{Type}Array 1504@end example 1505 1506@noindent For example: 1507 1508@example 1509JvNewBooleanArray 1510@end example 1511 1512@noindent can be used to create an array of Java primitive boolean types. 1513 1514@noindent The following function definition is the template for all such functions: 1515 1516@deftypefun jbooleanArray JvNewBooleanArray (jint @var{length}) 1517Create's an array @var{length} indices long. 1518@end deftypefun 1519 1520@deftypefun jsize JvGetArrayLength (jarray @var{array}) 1521Returns the length of the @var{array}. 1522@end deftypefun 1523 1524 1525@node Methods 1526@section Methods 1527 1528Java methods are mapped directly into C++ methods. 1529The header files generated by @code{gcjh} 1530include the appropriate method definitions. 1531Basically, the generated methods have the same names and 1532@emph{corresponding} types as the Java methods, 1533and are called in the natural manner. 1534 1535@subsection Overloading 1536 1537Both Java and C++ provide method overloading, where multiple 1538methods in a class have the same name, and the correct one is chosen 1539(at compile time) depending on the argument types. 1540The rules for choosing the correct method are (as expected) more complicated 1541in C++ than in Java, but given a set of overloaded methods 1542generated by @code{gcjh} the C++ compiler will choose 1543the expected one. 1544 1545Common assemblers and linkers are not aware of C++ overloading, 1546so the standard implementation strategy is to encode the 1547parameter types of a method into its assembly-level name. 1548This encoding is called @dfn{mangling}, 1549and the encoded name is the @dfn{mangled name}. 1550The same mechanism is used to implement Java overloading. 1551For C++/Java interoperability, it is important that both the Java 1552and C++ compilers use the @emph{same} encoding scheme. 1553 1554@subsection Static methods 1555 1556Static Java methods are invoked in @acronym{CNI} using the standard 1557C++ syntax, using the @code{::} operator rather 1558than the @code{.} operator. 1559 1560@noindent For example: 1561 1562@example 1563jint i = java::lang::Math::round((jfloat) 2.3); 1564@end example 1565 1566@noindent C++ method definition syntax is used to define a static native method. 1567For example: 1568 1569@example 1570#include <java/lang/Integer> 1571java::lang::Integer* 1572java::lang::Integer::getInteger(jstring str) 1573@{ 1574 ... 1575@} 1576@end example 1577 1578 1579@subsection Object Constructors 1580 1581Constructors are called implicitly as part of object allocation 1582using the @code{new} operator. 1583 1584@noindent For example: 1585 1586@example 1587java::lang::Integer *x = new java::lang::Integer(234); 1588@end example 1589 1590Java does not allow a constructor to be a native method. 1591This limitation can be coded round however because a constructor 1592can @emph{call} a native method. 1593 1594 1595@subsection Instance methods 1596 1597Calling a Java instance method from a C++ @acronym{CNI} method is done 1598using the standard C++ syntax, e.g.: 1599 1600@example 1601// @r{First create the Java object.} 1602java::lang::Integer *x = new java::lang::Integer(234); 1603// @r{Now call a method.} 1604jint prim_value = x->intValue(); 1605if (x->longValue == 0) 1606 ... 1607@end example 1608 1609@noindent Defining a Java native instance method is also done the natural way: 1610 1611@example 1612#include <java/lang/Integer.h> 1613 1614jdouble 1615java::lang:Integer::doubleValue() 1616@{ 1617 return (jdouble) value; 1618@} 1619@end example 1620 1621 1622@subsection Interface methods 1623 1624In Java you can call a method using an interface reference. This is 1625supported, but not completely. @xref{Interfaces}. 1626 1627 1628 1629 1630@node Strings 1631@section Strings 1632 1633@acronym{CNI} provides a number of utility functions for 1634working with Java Java @code{String} objects. 1635The names and interfaces are analogous to those of @acronym{JNI}. 1636 1637 1638@deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len}) 1639Returns a Java @code{String} object with characters from the C string 1640@var{chars} up to the index @var{len} in that array. 1641@end deftypefun 1642 1643@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len}) 1644Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}. 1645@end deftypefun 1646 1647 1648@deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}) 1649As above but the length of the @code{String} is @code{strlen(@var{bytes})}. 1650@end deftypefun 1651 1652@deftypefun jstring JvNewStringUTF (const char* @var{bytes}) 1653Returns a @code{String} which is made up of the UTF encoded characters 1654present in the C string @var{bytes}. 1655@end deftypefun 1656 1657@deftypefun jchar* JvGetStringChars (jstring @var{str}) 1658Returns a pointer to an array of characters making up the @code{String} @var{str}. 1659@end deftypefun 1660 1661@deftypefun int JvGetStringUTFLength (jstring @var{str}) 1662Returns the number of bytes required to encode the contents of the 1663@code{String} @var{str} in UTF-8. 1664@end deftypefun 1665 1666@deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf}) 1667Puts the UTF-8 encoding of a region of the @code{String} @var{str} into 1668the buffer @code{buf}. The region to fetch is marked by @var{start} and @var{len}. 1669 1670Note that @var{buf} is a buffer, not a C string. It is @emph{not} 1671null terminated. 1672@end deftypefun 1673 1674 1675@node Mixing with C++ 1676@section Interoperating with C/C++ 1677 1678Because @acronym{CNI} is designed to represent Java classes and methods it 1679cannot be mixed readily with C/C++ types. 1680 1681One important restriction is that Java classes cannot have non-Java 1682type instance or static variables and cannot have methods which take 1683non-Java types as arguments or return non-Java types. 1684 1685@noindent None of the following is possible with CNI: 1686 1687@example 1688 1689class ::MyClass : public java::lang::Object 1690@{ 1691 char* variable; // @r{char* is not a valid Java type.} 1692@} 1693 1694 1695uint 1696::SomeClass::someMethod (char *arg) 1697@{ 1698 . 1699 . 1700 . 1701@} // @r{@code{uint} is not a valid Java type, neither is @code{char*}} 1702@end example 1703 1704@noindent Of course, it is ok to use C/C++ types within the scope of a method: 1705 1706 1707@example 1708jint 1709::SomeClass::otherMethod (jstring str) 1710@{ 1711 char *arg = ... 1712 . 1713 . 1714 . 1715@} 1716@end example 1717 1718But this restriction can cause a problem so @acronym{CNI} includes the 1719@code{gnu.gcj.RawData} class. The @code{RawData} class is a 1720@dfn{non-scanned reference} type. In other words variables declared 1721of type @code{RawData} can contain any data and are not checked by the 1722compiler in any way. 1723 1724This means that you can put C/C++ data structures (including classes) 1725in your @acronym{CNI} classes, as long as you use the appropriate cast. 1726 1727@noindent Here are some examples: 1728 1729@example 1730 1731class ::MyClass : public java::lang::Object 1732@{ 1733 gnu.gcj.RawData string; 1734 1735 MyClass (); 1736 gnu.gcj.RawData getText (); 1737 void printText (); 1738@} 1739 1740::MyClass::MyClass () 1741@{ 1742 char* text = ... 1743 string = text; 1744@} 1745 1746gnu.gcj.RawData 1747::MyClass::getText () 1748@{ 1749 return string; 1750@} 1751 1752void 1753::MyClass::printText () 1754@{ 1755 printf("%s\n", (char*) string); 1756@} 1757@end example 1758 1759 1760@node Exception Handling 1761@section Exception Handling 1762 1763While C++ and Java share a common exception handling framework, 1764things are not yet perfectly integrated. The main issue is that the 1765run-time type information facilities of the two 1766languages are not integrated. 1767 1768Still, things work fairly well. You can throw a Java exception from 1769C++ using the ordinary @code{throw} construct, and this 1770exception can be caught by Java code. Similarly, you can catch an 1771exception thrown from Java using the C++ @code{catch} 1772construct. 1773 1774@noindent Here is an example: 1775 1776@example 1777if (i >= count) 1778 throw new java::lang::IndexOutOfBoundsException(); 1779@end example 1780 1781Normally, G++ will automatically detect when you are writing C++ 1782code that uses Java exceptions, and handle them appropriately. 1783However, if C++ code only needs to execute destructors when Java 1784exceptions are thrown through it, GCC will guess incorrectly. Sample 1785problematic code: 1786 1787@example 1788struct S @{ ~S(); @}; 1789 1790extern void bar(); // @r{Is implemented in Java and may throw exceptions.} 1791 1792void foo() 1793@{ 1794 S s; 1795 bar(); 1796@} 1797@end example 1798 1799The usual effect of an incorrect guess is a link failure, complaining of 1800a missing routine called @code{__gxx_personality_v0}. 1801 1802You can inform the compiler that Java exceptions are to be used in a 1803translation unit, irrespective of what it might think, by writing 1804@code{#pragma GCC java_exceptions} at the head of the 1805file. This @code{#pragma} must appear before any 1806functions that throw or catch exceptions, or run destructors when 1807exceptions are thrown through them. 1808 1809@node Synchronization 1810@section Synchronization 1811 1812Each Java object has an implicit monitor. 1813The Java VM uses the instruction @code{monitorenter} to acquire 1814and lock a monitor, and @code{monitorexit} to release it. 1815 1816The corresponding CNI macros are @code{JvMonitorEnter} and 1817@code{JvMonitorExit} (JNI has similar methods @code{MonitorEnter} 1818and @code{MonitorExit}). 1819 1820 1821The Java source language does not provide direct access to these primitives. 1822Instead, there is a @code{synchronized} statement that does an 1823implicit @code{monitorenter} before entry to the block, 1824and does a @code{monitorexit} on exit from the block. 1825Note that the lock has to be released even when the block is abnormally 1826terminated by an exception, which means there is an implicit 1827@code{try finally} surrounding synchronization locks. 1828 1829From C++, it makes sense to use a destructor to release a lock. 1830@acronym{CNI} defines the following utility class: 1831 1832@example 1833class JvSynchronize() @{ 1834 jobject obj; 1835 JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @} 1836 ~JvSynchronize() @{ JvMonitorExit(obj); @} 1837@}; 1838@end example 1839 1840So this Java code: 1841 1842@example 1843synchronized (OBJ) 1844@{ 1845 CODE 1846@} 1847@end example 1848 1849@noindent might become this C++ code: 1850 1851@example 1852@{ 1853 JvSynchronize dummy (OBJ); 1854 CODE; 1855@} 1856@end example 1857 1858Java also has methods with the @code{synchronized} attribute. 1859This is equivalent to wrapping the entire method body in a 1860@code{synchronized} statement. 1861(Alternatively, an implementation could require the caller to do 1862the synchronization. This is not practical for a compiler, because 1863each virtual method call would have to test at run-time if 1864synchronization is needed.) Since in @command{gcj} 1865the @code{synchronized} attribute is handled by the 1866method implementation, it is up to the programmer 1867of a synchronized native method to handle the synchronization 1868(in the C++ implementation of the method). 1869In other words, you need to manually add @code{JvSynchronize} 1870in a @code{native synchronized} method. 1871 1872@node Invocation 1873@section Invocation 1874 1875CNI permits C++ applications to make calls into Java classes, in addition to 1876allowing Java code to call into C++. Several functions, known as the 1877@dfn{invocation API}, are provided to support this. 1878 1879@deftypefun jint JvCreateJavaVM (void* @var{vm_args}) 1880Initializes the Java runtime. This function performs essential initialization 1881of the threads interface, garbage collector, exception handling and other key 1882aspects of the runtime. It must be called once by an application with 1883a non-Java @code{main()} function, before any other Java or CNI calls are made. 1884It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than 1885once provided it is only called from a single thread. 1886The @var{vmargs} parameter can be used to specify initialization parameters 1887for the Java runtime. It may be @code{NULL}. 1888This function returns @code{0} upon success, or @code{-1} if the runtime is 1889already initialized. 1890 1891@emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It may be 1892used in a future release. 1893@end deftypefun 1894 1895@deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group}) 1896Registers an existing thread with the Java runtime. This must be called once 1897from each thread, before that thread makes any other Java or CNI calls. It 1898must be called after @code{JvCreateJavaVM}. 1899@var{name} specifies a name for the thread. It may be @code{NULL}, in which 1900case a name will be generated. 1901@var{group} is the ThreadGroup in which this thread will be a member. If it 1902is @code{NULL}, the thread will be a member of the main thread group. 1903The return value is the Java @code{Thread} object that represents the thread. 1904It is safe to call @code{JvAttachCurrentThread()} more than once from the same 1905thread. If the thread is already attached, the call is ignored and the current 1906thread object is returned. 1907@end deftypefun 1908 1909@deftypefun jint JvDetachCurrentThread () 1910Unregisters a thread from the Java runtime. This should be called by threads 1911that were attached using @code{JvAttachCurrentThread()}, after they have 1912finished making calls to Java code. This ensures that any resources associated 1913with the thread become eligible for garbage collection. 1914This function returns @code{0} upon success, or @code{-1} if the current thread 1915is not attached. 1916@end deftypefun 1917 1918@subsection Handling uncaught exceptions 1919 1920If an exception is thrown from Java code called using the invocation API, and 1921no handler for the exception can be found, the runtime will abort the 1922application. In order to make the application more robust, it is recommended 1923that code which uses the invocation API be wrapped by a top-level try/catch 1924block that catches all Java exceptions. 1925 1926@subsection Example 1927 1928The following code demonstrates the use of the invocation API. In this 1929example, the C++ application initializes the Java runtime and attaches 1930itself. The @code{java.lang.System} class is initialized in order to 1931access its @code{out} field, and a Java string is printed. Finally, the thread 1932is detached from the runtime once it has finished making Java calls. Everything 1933is wrapped with a try/catch block to provide a default handler for any uncaught 1934exceptions. 1935 1936The example can be compiled with @command{c++ test.cc -lgcj}. 1937 1938@example 1939// test.cc 1940#include <gcj/cni.h> 1941#include <java/lang/System.h> 1942#include <java/io/PrintStream.h> 1943#include <java/lang/Throwable.h> 1944 1945int main(int argc, char *argv) 1946@{ 1947 using namespace java::lang; 1948 1949 try 1950 @{ 1951 JvCreateJavaVM(NULL); 1952 JvAttachCurrentThread(NULL, NULL); 1953 1954 String *message = JvNewStringLatin1("Hello from C++"); 1955 JvInitClass(&System::class$); 1956 System::out->println(message); 1957 1958 JvDetachCurrentThread(); 1959 @} 1960 catch (Throwable *t) 1961 @{ 1962 System::err->println(JvNewStringLatin1("Unhandled Java exception:")); 1963 t->printStackTrace(); 1964 @} 1965@} 1966@end example 1967 1968@node Reflection 1969@section Reflection 1970 1971Reflection is possible with CNI code, it functions similarly to how it 1972functions with JNI@. 1973 1974@c clean this up... I mean, what are the types jfieldID and jmethodID in JNI? 1975The types @code{jfieldID} and @code{jmethodID} 1976are as in JNI@. 1977 1978@noindent The functions: 1979 1980@itemize 1981@item @code{JvFromReflectedField}, 1982@item @code{JvFromReflectedMethod}, 1983@item @code{JvToReflectedField} 1984@item @code{JvToFromReflectedMethod} 1985@end itemize 1986 1987@noindent will be added shortly, as will other functions corresponding to JNI@. 1988 1989 1990@node System properties 1991@chapter System properties 1992 1993The runtime behavior of the @code{libgcj} library can be modified by setting 1994certain system properties. These properties can be compiled into the program 1995using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by 1996setting them explicitly in the program by calling the 1997@code{java.lang.System.setProperty()} method. Some system properties are only 1998used for informational purposes (like giving a version number or a user name). 1999A program can inspect the current value of a property by calling the 2000@code{java.lang.System.getProperty()} method. 2001 2002@menu 2003* Standard Properties:: Standard properties supported by @code{libgcj} 2004* GNU Classpath Properties:: Properties found in Classpath based libraries 2005* libgcj Runtime Properties:: Properties specific to @code{libgcj} 2006@end menu 2007 2008@node Standard Properties 2009@section Standard Properties 2010 2011The following properties are normally found in all implementations of the core 2012libraries for the Java language. 2013 2014@table @gcctabopt 2015 2016@item java.version 2017The @code{libgcj} version number. 2018 2019@item java.vendor 2020Set to @samp{The Free Software Foundation, Inc.} 2021 2022@item java.vendor.url 2023Set to @uref{http://gcc.gnu.org/java/}. 2024 2025@item java.home 2026The directory where @code{gcj} was installed. Taken from the @code{--prefix} 2027option given to @command{configure}. 2028 2029@item java.class.version 2030The class format version number supported by the libgcj byte code interpreter. 2031(Currently @samp{46.0}) 2032 2033@item java.vm.specification.version 2034The Virtual Machine Specification version implemented by @code{libgcj}. 2035(Currently @samp{1.0}) 2036 2037@item java.vm.specification.vendor 2038The name of the Virtual Machine specification designer. 2039 2040@item java.vm.specification.name 2041The name of the Virtual Machine specification 2042(Set to @samp{Java Virtual Machine Specification}). 2043 2044@item java.vm.version 2045The @command{gcj} version number. 2046 2047@item java.vm.vendor 2048Set to @samp{The Free Software Foundation, Inc.} 2049 2050@item java.vm.name 2051Set to @samp{GNU libgcj}. 2052 2053@item java.specification.version 2054The Runtime Environment specification version implemented by @code{libgcj}. 2055(Currently set to @samp{1.3}) 2056 2057@item java.specification.vendor 2058The Runtime Environment specification designer. 2059 2060@item java.specification.name 2061The name of the Runtime Environment specification 2062(Set to @samp{Java Platform API Specification}). 2063 2064@item java.class.path 2065The paths (jar files, zip files and directories) used for finding class files. 2066 2067@item java.library.path 2068Directory path used for finding native libraries. 2069 2070@item java.io.tmpdir 2071The directory used to put temporary files in. 2072 2073@item java.compiler 2074Name of the Just In Time compiler to use by the byte code interpreter. 2075Currently not used in @code{libgcj}. 2076 2077@item java.ext.dirs 2078Directories containing jar files with extra libraries. Will be used when 2079resolving classes. Currently not used in @code{libgcj}. 2080 2081@item java.protocol.handler.pkgs 2082A @samp{|} separated list of package names that is used to find classes that 2083implement handlers for @code{java.net.URL}. 2084 2085@item java.rmi.server.codebase 2086A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader} 2087to load classes from. 2088 2089@item jdbc.drivers 2090A list of class names that will be loaded by the @code{java.sql.DriverManager} 2091when it starts up. 2092 2093@item file.separator 2094The separator used in when directories are included in a filename 2095(normally @samp{/} or @samp{\} ). 2096 2097@item file.encoding 2098The default character encoding used when converting platform native files to 2099Unicode (usually set to @samp{8859_1}). 2100 2101@item path.separator 2102The standard separator used when a string contains multiple paths 2103(normally @samp{:} or @samp{;}), the string is usually not a valid character 2104to use in normal directory names.) 2105 2106@item line.separator 2107The default line separator used on the platform (normally @samp{\n}, @samp{\r} 2108or a combination of those two characters). 2109 2110@item policy.provider 2111The class name used for the default policy provider returned by 2112@code{java.security.Policy.getPolicy}. 2113 2114@item user.name 2115The name of the user running the program. Can be the full name, the login name 2116or empty if unknown. 2117 2118@item user.home 2119The default directory to put user specific files in. 2120 2121@item user.dir 2122The current working directory from which the program was started. 2123 2124@item user.language 2125The default language as used by the @code{java.util.Locale} class. 2126 2127@item user.region 2128The default region as used by the @code{java.util.Local} class. 2129 2130@item user.variant 2131The default variant of the language and region local used. 2132 2133@item user.timezone 2134The default timezone as used by the @code{java.util.TimeZone} class. 2135 2136@item os.name 2137The operating system/kernel name that the program runs on. 2138 2139@item os.arch 2140The hardware that we are running on. 2141 2142@item os.version 2143The version number of the operating system/kernel. 2144 2145@item awt.appletWarning 2146The string to display when an untrusted applet is displayed. 2147Returned by @code{java.awt.Window.getWarningString()} when the window is 2148``insecure''. 2149 2150@item awt.toolkit 2151The class name used for initializing the default @code{java.awt.Toolkit}. 2152Defaults to @code{gnu.awt.gtk.GtkToolkit}. 2153 2154@item http.proxyHost 2155Name of proxy host for http connections. 2156 2157@item http.proxyPort 2158Port number to use when a proxy host is in use. 2159 2160@end table 2161 2162@node GNU Classpath Properties 2163@section GNU Classpath Properties 2164 2165@code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a 2166GNU project to create free core class libraries for use with virtual machines 2167and compilers for the Java language. The following properties are common to 2168libraries based on GNU Classpath. 2169 2170@table @gcctabopt 2171 2172@item gcj.dumpobject 2173Enables printing serialization debugging by the @code{java.io.ObjectInput} and 2174@code{java.io.ObjectOutput} classes when set to something else then the empty 2175string. Only used when running a debug build of the library. 2176 2177@item gnu.classpath.vm.shortname 2178This is a succint name of the virtual machine. For @code{libgcj}, 2179this will always be @samp{libgcj}. 2180 2181@item gnu.classpath.home.url 2182A base URL used for finding system property files (e.g., 2183@file{classpath.security}). By default this is a @samp{file:} URL 2184pointing to the @file{lib} directory under @samp{java.home}. 2185 2186@end table 2187 2188@node libgcj Runtime Properties 2189@section libgcj Runtime Properties 2190 2191The following properties are specific to the @code{libgcj} runtime and will 2192normally not be found in other core libraries for the java language. 2193 2194@table @gcctabopt 2195 2196@item java.fullversion 2197The combination of @code{java.vm.name} and @code{java.vm.version}. 2198 2199@item java.vm.info 2200Same as @code{java.fullversion}. 2201 2202@item impl.prefix 2203Used by the @code{java.net.DatagramSocket} class when set to something else 2204then the empty string. When set all newly created @code{DatagramSocket}s will 2205try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of 2206the normal @code{java.net.PlainDatagramSocketImpl}. 2207 2208@item gnu.gcj.progname 2209The name that was used to invoked the program. 2210 2211@item gnu.gcj.runtime.NameFinder.demangle 2212Whether names in a stack trace should be demangled. Defaults to @code{true}. 2213 2214@item gnu.gcj.runtime.NameFinder.sanitize 2215Whether calls to initialize exceptions and starting the runtime system 2216should be removed from the stack trace. Only done when names are 2217demangled. Defaults to @code{true}. 2218 2219@item gnu.gcj.runtime.NameFinder.remove_unknown 2220Whether calls to unknown functions (class and method names are unknown) 2221should be removed from the stack trace. Only done when the stack is 2222sanitized. Ignored if this means no stack trace information would be 2223available anymore. Defaults to @code{true}. 2224 2225@item gnu.gcj.runtime.NameFinder.remove_interpreter 2226Whether runtime interpreter calls (methods in the @code{_Jv_InterpMethod} class 2227and functions starting with @samp{ffi_}) should be removed from the stack 2228trace. Only done when the stack is sanitized. Defaults to @code{true}. 2229 2230 2231@item gnu.gcj.runtime.NameFinder.use_addr2line 2232Whether an external process (@command{addr2line} or @command{addr2name.awk}) 2233should be used as fallback to convert the addresses to function names when 2234the runtime is unable to do it through @code{dladdr}. 2235 2236@end table 2237 2238 2239@node Resources 2240@chapter Resources 2241 2242While writing @command{gcj} and @code{libgcj} we have, of course, relied 2243heavily on documentation from Sun Microsystems. In particular we have 2244used The Java Language Specification (both first and second editions), 2245the Java Class Libraries (volumes one and two), and the Java Virtual 2246Machine Specification. In addition we've used the online documentation 2247at @uref{http://java.sun.com/}. 2248 2249The current @command{gcj} home page is 2250@uref{http://gcc.gnu.org/java/}. 2251 2252For more information on gcc, see @uref{http://gcc.gnu.org/}. 2253 2254Some @code{libgcj} testing is done using the Mauve test suite. This is 2255a free software Java class library test suite which is being written 2256because the JCK is not free. See 2257@uref{http://sources.redhat.com/mauve/} for more information. 2258 2259@bye 2260