1 \input texinfo @c -*-texinfo-*-
3 @settitle Guide to GNU gcj
5 @c Merge the standard indexes into a single one.
12 @include gcc-common.texi
14 @c Note: When reading this manual you'll find lots of strange
15 @c circumlocutions like ``compiler for the Java language''.
16 @c This is necessary due to Sun's restrictions on the use of
19 @c When this manual is copyrighted.
20 @set copyrights-gcj 2001, 2002, 2003, 2004, 2005
23 @set which-gcj GCC-@value{version-GCC}
26 @c man begin COPYRIGHT
27 Copyright @copyright{} @value{copyrights-gcj} Free Software Foundation, Inc.
29 Permission is granted to copy, distribute and/or modify this document
30 under the terms of the GNU Free Documentation License, Version 1.2 or
31 any later version published by the Free Software Foundation; with the
32 Invariant Sections being ``GNU General Public License'', the Front-Cover
33 texts being (a) (see below), and with the Back-Cover Texts being (b)
34 (see below). A copy of the license is included in the
37 ``GNU Free Documentation License''.
39 @c man begin COPYRIGHT
44 @c man begin COPYRIGHT
46 (a) The FSF's Front-Cover Text is:
50 (b) The FSF's Back-Cover Text is:
52 You have freedom to copy and modify this GNU Manual, like GNU
53 software. Copies published by the Free Software Foundation raise
54 funds for GNU development.
60 @dircategory Programming
62 * Gcj: (gcj). Ahead-of-time compiler for the Java language
65 @dircategory Individual utilities
67 * gcjh: (gcj)Invoking gcjh.
68 Generate header files from Java class files
69 * gjnih: (gcj)Invoking gjnih.
70 Generate JNI header files from Java class files
71 * jv-scan: (gcj)Invoking jv-scan.
72 Print information about Java source files
73 * jcf-dump: (gcj)Invoking jcf-dump.
74 Print information about Java class files
75 * gij: (gcj)Invoking gij. GNU interpreter for Java bytecode
76 * gcj-dbtool: (gcj)Invoking gcj-dbtool.
77 Tool for manipulating class file databases.
78 * jv-convert: (gcj)Invoking jv-convert.
79 Convert file from one encoding to another
80 * grmic: (gcj)Invoking grmic.
81 Generate stubs for Remote Method Invocation.
82 * grmiregistry: (gcj)Invoking grmiregistry.
83 The remote object registry.
95 @vskip 0pt plus 1filll
96 For the @value{which-gcj} Version*
98 Published by the Free Software Foundation @*
99 51 Franklin Street, Fifth Floor@*
100 Boston, MA 02110-1301, USA@*
111 This manual describes how to use @command{gcj}, the GNU compiler for the
112 Java programming language. @command{gcj} can generate both @file{.class}
113 files and object files, and it can read both Java source code and
117 * Copying:: The GNU General Public License
118 * GNU Free Documentation License::
119 How you can share and copy this manual
120 * Invoking gcj:: Compiler options supported by @command{gcj}
121 * Compatibility:: Compatibility between gcj and other tools for Java
122 * Invoking gcjh:: Generate header files from class files
123 * Invoking gjnih:: Generate JNI header files from class files
124 * Invoking jv-scan:: Print information about source files
125 * Invoking jcf-dump:: Print information about class files
126 * Invoking gij:: Interpreting Java bytecodes
127 * Invoking gcj-dbtool:: Tool for manipulating class file databases.
128 * Invoking jv-convert:: Converting from one encoding to another
129 * Invoking grmic:: Generate stubs for Remote Method Invocation.
130 * Invoking grmiregistry:: The remote object registry.
131 * About CNI:: Description of the Compiled Native Interface
132 * System properties:: Modifying runtime behavior of the libgcj library
133 * Resources:: Where to look for more information
144 @chapter Invoking gcj
146 @c man title gcj Ahead-of-time compiler for the Java language
149 @c man begin SYNOPSIS gcj
150 gcj [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
151 [@option{--CLASSPATH}=@var{path}] [@option{--classpath}=@var{path}]
152 [@option{-f}@var{option}@dots{}] [@option{--encoding}=@var{name}]
153 [@option{--main}=@var{classname}] [@option{-D}@var{name}[=@var{value}]@dots{}]
154 [@option{-C}] [@option{--resource} @var{resource-name}] [@option{-d} @var{directory}]
155 [@option{-W}@var{warn}@dots{}]
156 @var{sourcefile}@dots{}
158 @c man begin SEEALSO gcj
159 gcc(1), gcjh(1), gjnih(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
160 and the Info entries for @file{gcj} and @file{gcc}.
164 @c man begin DESCRIPTION gcj
166 As @command{gcj} is just another front end to @command{gcc}, it supports many
167 of the same options as gcc. @xref{Option Summary, , Option Summary,
168 gcc, Using the GNU Compiler Collection (GCC)}. This manual only documents the
169 options specific to @command{gcj}.
174 * Input and output files::
175 * Input Options:: How gcj finds files
176 * Encodings:: Options controlling source file encoding
177 * Warnings:: Options controlling warnings specific to gcj
178 * Linking:: Options for making an executable
179 * Code Generation:: Options controlling the output of gcj
180 * Configure-time Options:: Options you won't use
183 @c man begin OPTIONS gcj
185 @node Input and output files
186 @section Input and output files
188 A @command{gcj} command is like a @command{gcc} command, in that it
189 consists of a number of options and file names. The following kinds
190 of input file names are supported:
193 @item @var{file}.java
195 @item @var{file}.class
198 @itemx @var{file}.jar
199 An archive containing one or more @code{.class} files, all of
200 which are compiled. The archive may be compressed. Files in
201 an archive which don't end with @samp{.class} are treated as
202 resource files; they are compiled into the resulting object file
203 as @samp{core:} URLs.
205 A file containing a whitespace-separated list of input file names.
206 (Currently, these must all be @code{.java} source files, but that
208 Each named file is compiled, just as if it had been on the command line.
209 @item @var{library}.a
210 @itemx @var{library}.so
211 @itemx -l@var{libname}
212 Libraries to use when linking. See the @command{gcc} manual.
215 You can specify more than one input file on the @command{gcj} command line,
216 in which case they will all be compiled. If you specify a
217 @code{-o @var{FILENAME}}
218 option, all the input files will be compiled together, producing a
219 single output file, named @var{FILENAME}.
220 This is allowed even when using @code{-S} or @code{-c},
221 but not when using @code{-C} or @code{--resource}.
222 (This is an extension beyond the what plain @command{gcc} allows.)
223 (If more than one input file is specified, all must currently
224 be @code{.java} files, though we hope to fix this.)
227 @section Input Options
231 @command{gcj} has options to control where it looks to find files it needs.
232 For instance, @command{gcj} might need to load a class that is referenced
233 by the file it has been asked to compile. Like other compilers for the
234 Java language, @command{gcj} has a notion of a @dfn{class path}. There are
235 several options and environment variables which can be used to
236 manipulate the class path. When @command{gcj} looks for a given class, it
237 searches the class path looking for matching @file{.class} or
238 @file{.java} file. @command{gcj} comes with a built-in class path which
239 points at the installed @file{libgcj.jar}, a file which contains all the
242 In the below, a directory or path component can refer either to an
243 actual directory on the filesystem, or to a @file{.zip} or @file{.jar}
244 file, which @command{gcj} will search as if it is a directory.
248 All directories specified by @code{-I} are kept in order and prepended
249 to the class path constructed from all the other options. Unless
250 compatibility with tools like @code{javac} is important, we recommend
251 always using @code{-I} instead of the other options for manipulating the
254 @item --classpath=@var{path}
255 This sets the class path to @var{path}, a colon-separated list of paths
256 (on Windows-based systems, a semicolon-separate list of paths).
257 This does not override the builtin (``boot'') search path.
259 @item --CLASSPATH=@var{path}
260 Deprecated synonym for @code{--classpath}.
262 @item --bootclasspath=@var{path}
263 Where to find the standard builtin classes, such as @code{java.lang.String}.
265 @item --extdirs=@var{path}
266 For each directory in the @var{path}, place the contents of that
267 directory at the end of the class path.
270 This is an environment variable which holds a list of paths.
273 The final class path is constructed like so:
277 First come all directories specified via @code{-I}.
280 If @option{--classpath} is specified, its value is appended.
281 Otherwise, if the @code{CLASSPATH} environment variable is specified,
282 then its value is appended.
283 Otherwise, the current directory (@code{"."}) is appended.
286 If @code{--bootclasspath} was specified, append its value.
287 Otherwise, append the built-in system directory, @file{libgcj.jar}.
290 Finally, if @code{--extdirs} was specified, append the contents of the
291 specified directories at the end of the class path. Otherwise, append
292 the contents of the built-in extdirs at @code{$(prefix)/share/java/ext}.
295 The classfile built by @command{gcj} for the class @code{java.lang.Object}
296 (and placed in @code{libgcj.jar}) contains a special zero length
297 attribute @code{gnu.gcj.gcj-compiled}. The compiler looks for this
298 attribute when loading @code{java.lang.Object} and will report an error
299 if it isn't found, unless it compiles to bytecode (the option
300 @code{-fforce-classes-archive-check} can be used to override this
301 behavior in this particular case.)
304 @item -fforce-classes-archive-check
305 This forces the compiler to always check for the special zero length
306 attribute @code{gnu.gcj.gcj-compiled} in @code{java.lang.Object} and
307 issue an error if it isn't found.
313 The Java programming language uses Unicode throughout. In an effort to
314 integrate well with other locales, @command{gcj} allows @file{.java} files
315 to be written using almost any encoding. @command{gcj} knows how to
316 convert these encodings into its internal encoding at compile time.
318 You can use the @code{--encoding=@var{NAME}} option to specify an
319 encoding (of a particular character set) to use for source files. If
320 this is not specified, the default encoding comes from your current
321 locale. If your host system has insufficient locale support, then
322 @command{gcj} assumes the default encoding to be the @samp{UTF-8} encoding
325 To implement @code{--encoding}, @command{gcj} simply uses the host
326 platform's @code{iconv} conversion routine. This means that in practice
327 @command{gcj} is limited by the capabilities of the host platform.
329 The names allowed for the argument @code{--encoding} vary from platform
330 to platform (since they are not standardized anywhere). However,
331 @command{gcj} implements the encoding named @samp{UTF-8} internally, so if
332 you choose to use this for your source files you can be assured that it
333 will work on every host.
339 @command{gcj} implements several warnings. As with other generic
340 @command{gcc} warnings, if an option of the form @code{-Wfoo} enables a
341 warning, then @code{-Wno-foo} will disable it. Here we've chosen to
342 document the form of the warning which will have an effect -- the
343 default being the opposite of what is listed.
346 @item -Wredundant-modifiers
347 With this flag, @command{gcj} will warn about redundant modifiers. For
348 instance, it will warn if an interface method is declared @code{public}.
350 @item -Wextraneous-semicolon
351 This causes @command{gcj} to warn about empty statements. Empty statements
352 have been deprecated.
354 @item -Wno-out-of-date
355 This option will cause @command{gcj} not to warn when a source file is
356 newer than its matching class file. By default @command{gcj} will warn
359 @item -Wno-deprecated
360 Warn if a deprecated class, method, or field is referred to.
363 This is the same as @command{gcc}'s @code{-Wunused}.
366 This is the same as @code{-Wredundant-modifiers -Wextraneous-semicolon
374 To turn a Java application into an executable program,
375 you need to link it with the needed libraries, just as for C or C++.
376 The linker by default looks for a global function named @code{main}.
377 Since Java does not have global functions, and a
378 collection of Java classes may have more than one class with a
379 @code{main} method, you need to let the linker know which of those
380 @code{main} methods it should invoke when starting the application.
381 You can do that in any of these ways:
385 Specify the class containing the desired @code{main} method
386 when you link the application, using the @code{--main} flag,
389 Link the Java package(s) into a shared library (dll) rather than an
390 executable. Then invoke the application using the @code{gij} program,
391 making sure that @code{gij} can find the libraries it needs.
393 Link the Java packages(s) with the flag @code{-lgij}, which links
394 in the @code{main} routine from the @code{gij} command.
395 This allows you to select the class whose @code{main} method you
396 want to run when you run the application. You can also use
397 other @code{gij} flags, such as @code{-D} flags to set properties.
398 Using the @code{-lgij} library (rather than the @code{gij} program
399 of the previous mechanism) has some advantages: it is compatible with
400 static linking, and does not require configuring or installing libraries.
403 These @code{gij} options relate to linking an executable:
406 @item --main=@var{CLASSNAME}
407 This option is used when linking to specify the name of the class whose
408 @code{main} method should be invoked when the resulting executable is
411 @item -D@var{name}[=@var{value}]
412 This option can only be used with @code{--main}. It defines a system
413 property named @var{name} with value @var{value}. If @var{value} is not
414 specified then it defaults to the empty string. These system properties
415 are initialized at the program's startup and can be retrieved at runtime
416 using the @code{java.lang.System.getProperty} method.
419 Create an application whose command-line processing is that
420 of the @code{gij} command.
422 This option is an alternative to using @code{--main}; you cannot use both.
425 @node Code Generation
426 @section Code Generation
428 In addition to the many @command{gcc} options controlling code generation,
429 @command{gcj} has several options specific to itself.
434 This option is used to tell @command{gcj} to generate bytecode
435 (@file{.class} files) rather than object code.
437 @item --resource @var{resource-name}
438 This option is used to tell @command{gcj} to compile the contents of a
439 given file to object code so it may be accessed at runtime with the core
440 protocol handler as @samp{core:/@var{resource-name}}. Note that
441 @var{resource-name} is the name of the resource as found at runtime; for
442 instance, it could be used in a call to @code{ResourceBundle.getBundle}.
443 The actual file name to be compiled this way must be specified
446 @item -d @var{directory}
447 When used with @code{-C}, this causes all generated @file{.class} files
448 to be put in the appropriate subdirectory of @var{directory}. By
449 default they will be put in subdirectories of the current working
452 @item -fno-bounds-check
453 By default, @command{gcj} generates code which checks the bounds of all
454 array indexing operations. With this option, these checks are omitted, which
455 can improve performance for code that uses arrays extensively. Note that this
456 can result in unpredictable behavior if the code in question actually does
457 violate array bounds constraints. It is safe to use this option if you are
458 sure that your code will never throw an @code{ArrayIndexOutOfBoundsException}.
460 @item -fno-store-check
461 Don't generate array store checks. When storing objects into arrays, a runtime
462 check is normally generated in order to ensure that the object is assignment
463 compatible with the component type of the array (which may not be known
464 at compile-time). With this option, these checks are omitted. This can
465 improve performance for code which stores objects into arrays frequently.
466 It is safe to use this option if you are sure your code will never throw an
467 @code{ArrayStoreException}.
470 With @command{gcj} there are two options for writing native methods: CNI
471 and JNI@. By default @command{gcj} assumes you are using CNI@. If you are
472 compiling a class with native methods, and these methods are implemented
473 using JNI, then you must use @code{-fjni}. This option causes
474 @command{gcj} to generate stubs which will invoke the underlying JNI
478 Don't recognize the @code{assert} keyword. This is for compatibility
479 with older versions of the language specification.
481 @item -fno-optimize-static-class-initialization
482 When the optimization level is greater or equal to @code{-O2},
483 @command{gcj} will try to optimize the way calls into the runtime are made
484 to initialize static classes upon their first use (this optimization
485 isn't carried out if @code{-C} was specified.) When compiling to native
486 code, @code{-fno-optimize-static-class-initialization} will turn this
487 optimization off, regardless of the optimization level in use.
489 @item --disable-assertions[=@var{class-or-package}]
490 Don't include code for checking assertions in the compiled code.
491 If @code{=@var{class-or-package}} is missing disables assertion code
492 generation for all classes, unless overridden by a more
493 specific @code{--enable-assertions} flag.
494 If @var{class-or-package} is a class name, only disables generating
495 assertion checks within the named class or its inner classes.
496 If @var{class-or-package} is a package name, disables generating
497 assertion checks within the named package or a subpackage.
499 By default, assertions are enabled when generating class files
500 or when not optimizing, and disabled when generating optimized binaries.
502 @item --enable-assertions[=@var{class-or-package}]
503 Generates code to check assertions. The option is perhaps misnamed,
504 as you still need to turn on assertion checking at run-time,
505 and we don't support any easy way to do that.
506 So this flag isn't very useful yet, except to partially override
507 @code{--disable-assertions}.
509 @item -findirect-dispatch
510 @command{gcj} has a special binary compatibility ABI, which is enabled
511 by the @code{-findirect-dispatch} option. In this mode, the code
512 generated by @command{gcj} honors the binary compatibility guarantees
513 in the Java Language Specification, and the resulting object files do
514 not need to be directly linked against their dependencies. Instead,
515 all dependencies are looked up at runtime. This allows free mixing of
516 interpreted and compiled code.
518 Note that, at present, @code{-findirect-dispatch} can only be used
519 when compiling @file{.class} files. It will not work when compiling
520 from source. CNI also does not yet work with the binary compatibility
521 ABI. These restrictions will be lifted in some future release.
523 However, if you compile CNI code with the standard ABI, you can call
524 it from code built with the binary compatibility ABI.
526 @item -fbootstrap-classes
527 This option can be use to tell @code{libgcj} that the compiled classes
528 should be loaded by the bootstrap loader, not the system class loader.
529 By default, if you compile a class and link it into an executable, it
530 will be treated as if it was loaded using the system class loader.
531 This is convenient, as it means that things like
532 @code{Class.forName()} will search @samp{CLASSPATH} to find the
538 @node Configure-time Options
539 @section Configure-time Options
541 Some @command{gcj} code generations options affect the resulting ABI, and
542 so can only be meaningfully given when @code{libgcj}, the runtime
543 package, is configured. @code{libgcj} puts the appropriate options from
544 this group into a @samp{spec} file which is read by @command{gcj}. These
545 options are listed here for completeness; if you are using @code{libgcj}
546 then you won't want to touch these options.
550 This enables the use of the Boehm GC bitmap marking code. In particular
551 this causes @command{gcj} to put an object marking descriptor into each
554 @item -fhash-synchronization
555 By default, synchronization data (the data used for @code{synchronize},
556 @code{wait}, and @code{notify}) is pointed to by a word in each object.
557 With this option @command{gcj} assumes that this information is stored in a
558 hash table and not in the object itself.
560 @item -fuse-divide-subroutine
561 On some systems, a library routine is called to perform integer
562 division. This is required to get exception handling correct when
565 @item -fcheck-references
566 On some systems it's necessary to insert inline checks whenever
567 accessing an object via a reference. On other systems you won't need
568 this because null pointer accesses are caught automatically by the
575 @chapter Compatibility with the Java Platform
577 As we believe it is important that the Java platform not be fragmented,
578 @command{gcj} and @code{libgcj} try to conform to the relevant Java
579 specifications. However, limited manpower and incomplete and unclear
580 documentation work against us. So, there are caveats to using
589 @section Standard features not yet supported
591 This list of compatibility issues is by no means complete.
595 @command{gcj} implements the JDK 1.2 language. It supports inner classes
596 and the new 1.4 @code{assert} keyword. It does not yet support the Java 2
597 @code{strictfp} keyword (it recognizes the keyword but ignores it).
600 @code{libgcj} is largely compatible with the JDK 1.2 libraries.
601 However, @code{libgcj} is missing many packages, most notably
602 @code{java.awt}. There are also individual missing classes and methods.
603 We currently do not have a list showing differences between
604 @code{libgcj} and the Java 2 platform.
607 Sometimes the @code{libgcj} implementation of a method or class differs
608 from the JDK implementation. This is not always a bug. Still, if it
609 affects you, it probably makes sense to report it so that we can discuss
610 the appropriate response.
613 @command{gcj} does not currently allow for piecemeal replacement of
614 components within @code{libgcj}. Unfortunately, programmers often want
615 to use newer versions of certain packages, such as those provided by
616 the Apache Software Foundation's Jakarta project. This has forced us
617 to place the @code{org.w3c.dom} and @code{org.xml.sax} packages into
618 their own libraries, separate from @code{libgcj}. If you intend to
619 use these classes, you must link them explicitly with
620 @code{-l-org-w3c-dom} and @code{-l-org-xml-sax}. Future versions of
621 @command{gcj} may not have this restriction.
625 @section Extra features unique to gcj
627 The main feature of @command{gcj} is that it can compile programs written in
628 the Java programming language to native code. Most extensions that have been
629 added are to facilitate this functionality.
633 @command{gcj} makes it easy and efficient to mix code written in Java and C++.
634 @xref{About CNI}, for more info on how to use this in your programs.
637 When you compile your classes into a shared library they can be automatically
638 loaded by the @code{libgcj} system classloader. When trying to load a class
639 @code{gnu.pkg.SomeClass} the system classloader will first try to load the
640 shared library @file{lib-gnu-pkg-SomeClass.so}, if that fails to load the
641 class then it will try to load @file{lib-gnu-pkg.so} and finally when the
642 class is still not loaded it will try to load @file{lib-gnu.so}. Note that
643 all @samp{.}s will be transformed into @samp{-}s and that searching
644 for inner classes starts with their outermost outer class. If the class
645 cannot be found this way the system classloader tries to use
646 the @code{libgcj} bytecode interpreter to load the class from the standard
647 classpath. This process can be controlled to some degree via the
648 @code{gnu.gcj.runtime.VMClassLoader.library_control} property;
649 @xref{libgcj Runtime Properties}.
652 @code{libgcj} includes a special @samp{gcjlib} URL type. A URL of
653 this form is like a @code{jar} URL, and looks like
654 @samp{gcjlib:/path/to/shared/library.so!/path/to/resource}. An access
655 to one of these URLs causes the shared library to be @code{dlopen()}d,
656 and then the resource is looked for in that library. These URLs are
657 most useful when used in conjunction with @code{java.net.URLClassLoader}.
658 Note that, due to implementation limitations, currently any such URL
659 can be accessed by only one class loader, and libraries are never
660 unloaded. This means some care must be exercised to make sure that
661 a @code{gcjlib} URL is not accessed by more than one class loader at once.
662 In a future release this limitation will be lifted, and such
663 libraries will be mapped privately.
666 A program compiled by @command{gcj} will examine the
667 @env{GCJ_PROPERTIES} environment variable and change its behavior in
668 some ways. In particular @env{GCJ_PROPERTIES} holds a list of
669 assignments to global properties, such as would be set with the
670 @option{-D} option to @command{java}. For instance,
671 @samp{java.compiler=gcj} is a valid (but currently meaningless)
673 @cindex GCJ_PROPERTIES
674 @vindex GCJ_PROPERTIES
680 @chapter Invoking gcjh
682 @c man title gcjh generate header files from Java class files
684 @c man begin DESCRIPTION gcjh
686 The @code{gcjh} program is used to generate header files from class
687 files. It can generate both CNI and JNI header files, as well as stub
688 implementation files which can be used as a basis for implementing the
689 required native methods.
694 @c man begin SYNOPSIS gcjh
695 gcjh [@option{-stubs}] [@option{-jni}]
696 [@option{-force}] [@option{-old}] [@option{-trace}] [@option{-J} @var{option}]
697 [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
698 [@option{-preprend} @var{text}]
699 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
700 [@option{--bootclasspath}=@var{path}]
701 [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
702 [@option{-o} @var{file}] [@option{-td} @var{dir}]
703 [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
704 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
705 @var{classname}@dots{}
707 @c man begin SEEALSO gcjh
708 gcc(1), gcj(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
709 and the Info entries for @file{gcj} and @file{gcc}.
713 @c man begin OPTIONS gcjh
717 This causes @code{gcjh} to generate stub files instead of header files.
718 By default the stub file will be named after the class, with a suffix of
719 @samp{.cc}. In JNI mode, the default output file will have the suffix
723 This tells @code{gcjh} to generate a JNI header or stub. By default,
724 CNI headers are generated.
727 This option forces @code{gcjh} to write the output file.
730 This option is accepted but ignored for compatibility.
733 This option is accepted but ignored for compatibility.
735 @item -J @var{option}
736 This option is accepted but ignored for compatibility.
738 @item -add @var{text}
739 Inserts @var{text} into the class body. This is ignored in JNI mode.
741 @item -append @var{text}
742 Inserts @var{text} into the header file after the class declaration.
743 This is ignored in JNI mode.
745 @item -friend @var{text}
746 Inserts @var{text} into the class as a @code{friend} declaration.
747 This is ignored in JNI mode.
749 @item -prepend @var{text}
750 Inserts @var{text} into the header file before the class declaration.
751 This is ignored in JNI mode.
753 @item --classpath=@var{path}
754 @itemx --CLASSPATH=@var{path}
755 @itemx --bootclasspath=@var{path}
756 @itemx -I@var{directory}
757 @itemx -d @var{directory}
759 These options are all identical to the corresponding @command{gcj} options.
762 Sets the output file name. This cannot be used if there is more than
763 one class on the command line.
765 @item -td @var{directory}
766 Sets the name of the directory to use for temporary files.
769 Print all dependencies to stdout; suppress ordinary output.
772 Print non-system dependencies to stdout; suppress ordinary output.
775 Print all dependencies to stdout.
778 Print non-system dependencies to stdout.
781 Print help about @code{gcjh} and exit. No further processing is done.
784 Print version information for @code{gcjh} and exit. No further
788 Print extra information while running.
791 All remaining options are considered to be names of classes.
796 @chapter Invoking gjnih
798 @c man title gjnih generate JNI header files from Java class files
800 @c man begin DESCRIPTION gjnih
802 The @code{gjnih} program is used to generate JNI header files from class
803 files. Running it is equivalent to running @code{gcjh -jni}.
808 @c man begin SYNOPSIS gjnih
809 gjnih [@option{-stubs}] [@option{-jni}]
810 [@option{-force}] [@option{-old}] [@option{-trace}] [@option{-J} @var{option}]
811 [@option{-add} @var{text}] [@option{-append} @var{text}] [@option{-friend} @var{text}]
812 [@option{-preprend} @var{text}]
813 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
814 [@option{--bootclasspath}=@var{path}]
815 [@option{-I}@var{dir}@dots{}] [@option{-d} @var{dir}@dots{}]
816 [@option{-o} @var{file}] [@option{-td} @var{dir}]
817 [@option{-M}] [@option{-MM}] [@option{-MD}] [@option{-MMD}]
818 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
819 @var{classname}@dots{}
821 @c man begin SEEALSO gjnih
822 gcc(1), gcj(1), gcjh(1), gij(1), jv-scan(1), jcf-dump(1), gfdl(7),
823 and the Info entries for @file{gcj} and @file{gcc}.
827 @c man begin OPTIONS gjnih
831 This causes @code{gjnih} to generate stub files instead of header files.
832 By default the stub file will be named after the class, with a suffix of
836 This option specifies the default behavior which is to generate a JNI
840 This option forces @code{gjnih} to write the output file.
843 This option is accepted but ignored for compatibility.
846 This option is accepted but ignored for compatibility.
848 @item -J @var{option}
849 This option is accepted but ignored for compatibility.
851 @item -add @var{text}
852 Inserts @var{text} into the class body. This is ignored in by
855 @item -append @var{text}
856 Inserts @var{text} into the header file after the class declaration.
857 This is ignored in by @code{gjnih}.
859 @item -friend @var{text}
860 Inserts @var{text} into the class as a @code{friend} declaration.
861 This is ignored by @code{gjnih}.
863 @item -prepend @var{text}
864 Inserts @var{text} into the header file before the class declaration.
865 This is ignored in by @code{gjnih}.
867 @item --classpath=@var{path}
868 @itemx --CLASSPATH=@var{path}
869 @itemx --bootclasspath=@var{path}
870 @itemx -I@var{directory}
871 @itemx -d @var{directory}
873 These options are all identical to the corresponding @command{gcj} options.
876 Sets the output file name. This cannot be used if there is more than
877 one class on the command line.
879 @item -td @var{directory}
880 Sets the name of the directory to use for temporary files.
883 Print all dependencies to stdout; suppress ordinary output.
886 Print non-system dependencies to stdout; suppress ordinary output.
889 Print all dependencies to stdout.
892 Print non-system dependencies to stdout.
895 Print help about @code{gjnih} and exit. No further processing is done.
898 Print version information for @code{gjnih} and exit. No further
902 Print extra information while running.
905 All remaining options are considered to be names of classes.
909 @node Invoking jv-scan
910 @chapter Invoking jv-scan
912 @c man title jv-scan print information about Java source file
914 @c man begin DESCRIPTION jv-scan
916 The @code{jv-scan} program can be used to print information about a Java
917 source file (@file{.java} file).
922 @c man begin SYNOPSIS jv-scan
923 jv-scan [@option{--no-assert}] [@option{--complexity}]
924 [@option{--encoding}=@var{name}] [@option{--print-main}]
925 [@option{--list-class}] [@option{--list-filename}]
926 [@option{--version}] [@option{--help}]
927 [@option{-o} @var{file}] @var{inputfile}@dots{}
929 @c man begin SEEALSO jv-scan
930 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
931 and the Info entries for @file{gcj} and @file{gcc}.
935 @c man begin OPTIONS jv-scan
939 Don't recognize the @code{assert} keyword, for backwards compatibility
940 with older versions of the language specification.
943 This prints a complexity measure, related to cyclomatic complexity, for
946 @item --encoding=@var{name}
947 This works like the corresponding @command{gcj} option.
950 This prints the name of the class in this file containing a @code{main}
954 This lists the names of all classes defined in the input files.
956 @item --list-filename
957 If @code{--list-class} is given, this option causes @code{jv-scan} to
958 also print the name of the file in which each class was found.
961 Print output to the named file.
964 Print help, then exit.
967 Print version number, then exit.
972 @node Invoking jcf-dump
973 @chapter Invoking jcf-dump
975 @c man title jcf-dump print information about Java class files
978 @c man begin SYNOPSIS jcf-dump
979 jcf-dump [@option{-c}] [@option{--javap}]
980 [@option{--classpath}=@var{path}] [@option{--CLASSPATH}=@var{path}]
981 [@option{-I}@var{dir}@dots{}] [@option{-o} @var{file}]
982 [@option{--version}] [@option{--help}] [@option{-v}] [@option{--verbose}]
983 @var{classname}@dots{}
985 @c man begin SEEALSO jcf-dump
986 gcc(1), gcj(1), gcjh(1), gij(1), jcf-dump(1), gfdl(7),
987 and the Info entries for @file{gcj} and @file{gcc}.
991 @c man begin DESCRIPTION jcf-dump
993 This is a class file examiner, similar to @code{javap}. It will print
994 information about a number of classes, which are specified by class name
999 @c man begin OPTIONS jcf-dump
1003 Disassemble method bodies. By default method bodies are not printed.
1005 @item --print-constants
1006 Print the constant pool. When printing a reference to a constant
1007 also print its index in the constant pool.
1010 Generate output in @code{javap} format. The implementation of this
1011 feature is very incomplete.
1013 @item --classpath=@var{path}
1014 @itemx --CLASSPATH=@var{path}
1015 @itemx -I@var{directory}
1016 @itemx -o @var{file}
1017 These options as the same as the corresponding @command{gcj} options.
1020 Print help, then exit.
1023 Print version number, then exit.
1026 Print extra information while running.
1027 Implies @code{--print-constants}.
1033 @chapter Invoking gij
1035 @c man title gij GNU interpreter for Java bytecode
1038 @c man begin SYNOPSIS gij
1039 gij [@option{OPTION}] @dots{} @var{JARFILE} [@var{ARGS}@dots{}]
1041 gij [@option{-jar}] [@option{OPTION}] @dots{} @var{CLASS} [@var{ARGS}@dots{}]
1042 [@option{-cp} @var{path}] [@option{-classpath} @var{path}]
1043 [@option{-D}@var{name}[=@var{value}]@dots{}]
1044 [@option{-ms=}@var{number}] [@option{-mx=}@var{number}]
1045 [@option{-X@var{argument}}] [@option{-verbose}] [@option{-verbose:class}]
1046 [@option{--showversion}] [@option{--version}] [@option{--help}][@option{-?}]
1048 @c man begin SEEALSO gij
1049 gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
1050 and the Info entries for @file{gcj} and @file{gcc}.
1054 @c man begin DESCRIPTION gij
1056 @code{gij} is a Java bytecode interpreter included with @code{libgcj}.
1057 @code{gij} is not available on every platform; porting it requires a
1058 small amount of assembly programming which has not been done for all the
1059 targets supported by @command{gcj}.
1061 The primary argument to @code{gij} is the name of a class or, with
1062 @code{-jar}, a jar file. Options before this argument are interpreted
1063 by @code{gij}; remaining options are passed to the interpreted program.
1065 If a class name is specified and this class does not have a @code{main}
1066 method with the appropriate signature (a @code{static void} method with
1067 a @code{String[]} as its sole argument), then @code{gij} will print an
1070 If a jar file is specified then @code{gij} will use information in it to
1071 determine which class' @code{main} method will be invoked.
1073 @code{gij} will invoke the @code{main} method with all the remaining
1074 command-line options.
1076 Note that @code{gij} is not limited to interpreting code. Because
1077 @code{libgcj} includes a class loader which can dynamically load shared
1078 objects, it is possible to give @code{gij} the name of a class which has
1079 been compiled and put into a shared library on the class path.
1083 @c man begin OPTIONS gij
1086 @item -cp @var{path}
1087 @itemx -classpath @var{path}
1088 Set the initial class path. The class path is used for finding
1089 class and resource files. If specified, this option overrides the
1090 @code{CLASSPATH} environment variable. Note that this option is
1091 ignored if @code{-jar} is used.
1093 @item -D@var{name}[=@var{value}]
1094 This defines a system property named @var{name} with value @var{value}.
1095 If @var{value} is not specified then it defaults to the empty string.
1096 These system properties are initialized at the program's startup and can
1097 be retrieved at runtime using the @code{java.lang.System.getProperty}
1100 @item -ms=@var{number}
1101 Equivalent to @code{-Xms}.
1103 @item -mx=@var{number}
1104 Equivalent to @code{-Xmx}.
1107 Do not verify compliance of bytecode with the VM specification. In addition,
1108 this option disables type verification which is otherwise performed on BC-ABI
1112 @itemx -X@var{argument}
1113 Supplying @code{-X} by itself will cause @code{gij} to list all the
1114 supported @code{-X} options. Currently these options are supported:
1117 @item -Xms@var{size}
1118 Set the initial heap size.
1120 @item -Xmx@var{size}
1121 Set the maximum heap size.
1123 @item -Xss@var{size}
1124 Set the thread stack size.
1127 Unrecognized @code{-X} options are ignored, for compatibility with
1131 This indicates that the name passed to @code{gij} should be interpreted
1132 as the name of a jar file, not a class.
1136 Print help, then exit.
1139 Print version number and continue.
1142 Print detailed version information, then exit.
1145 Print version number, then exit.
1148 @itemx -verbose:class
1149 Each time a class is initialized, print a short message on standard error.
1152 @code{gij} also recognizes and ignores the following options, for
1153 compatibility with existing application launch scripts:
1154 @code{-client}, @code{-server}, @code{-hotspot}, @code{-jrockit},
1155 @code{-agentlib}, @code{-agentpath}, @code{-debug}, @code{-d32},
1156 @code{-d64}, @code{-javaagent}, @code{-noclassgc}, @code{-verify},
1157 and @code{-verifyremote}.
1161 @node Invoking gcj-dbtool
1162 @chapter Invoking gcj-dbtool.
1164 @c man title gcj-dbtool Manipulate class file mapping databases for libgcj
1167 @c man begin SYNOPSIS gcj-dbtool
1168 gcj-dbtool @option{OPTION} @var{DBFILE} [@option{MORE}] @dots{}
1170 gcj-dbtool [@option{-0}] [@option{-}] [@option{-n}] [@option{-a}] [@option{-f}]
1171 [@option{-t}] [@option{-l}] [@option{-p} [@var{LIBDIR}]]
1172 [@option{-v}] [@option{-m}] [@option{--version}] [@option{--help}]
1175 @c man begin SEEALSO gij
1176 gcc(1), gcj(1), gcjh(1), jv-scan(1), jcf-dump(1), gfdl(7),
1177 and the Info entries for @file{gcj} and @file{gcc}.
1181 @c man begin DESCRIPTION gcj-dbtool
1183 @code{gcj-dbtool} is a tool for creating and manipulating class file
1184 mapping databases. @code{libgcj} can use these databases to find a
1185 shared library corresponding to the bytecode representation of a
1186 class. This functionality is useful for ahead-of-time compilation of
1187 a program that has no knowledge of @code{gcj}.
1189 @code{gcj-dbtool} works best if all the jar files added to it are
1190 compiled using @code{-findirect-dispatch}.
1192 Note that @code{gcj-dbtool} is currently available as ``preview
1193 technology''. We believe it is a reasonable way to allow
1194 application-transparent ahead-of-time compilation, but this is an
1195 unexplored area. We welcome your comments.
1199 @c man begin OPTIONS gcj-dbtool
1202 @item -n @var{DBFILE} [@var{SIZE}]
1203 This creates a new database. Currently, databases cannot be resized;
1204 you can choose a larger initial size if desired. The default size is
1207 @item -a @var{DBFILE} @var{JARFILE} @var{LIB}
1208 @itemx -f @var{DBFILE} @var{JARFILE} @var{LIB}
1209 This adds a jar file to the database. For each class file in the jar,
1210 a cryptographic signature of the bytecode representation of the class
1211 is recorded in the database. At runtime, a class is looked up by its
1212 signature and the compiled form of the class is looked for in the
1213 corresponding shared library. The @option{-a} option will verify
1214 that @var{LIB} exists before adding it to the database; @option{-f}
1217 @item [@option{-}][@option{-0}] -m @var{DBFILE} @var{DBFILE},[@var{DBFILE}]
1218 Merge a number of databases. The output database overwrites any
1219 existing database. To add databases into an existing database,
1220 include the destination in the list of sources.
1222 If @option{-} or @option{-0} are used, the list of files to read is
1223 taken from standard input instead of the command line. For
1224 @option{-0}, Input filenames are terminated by a null character
1225 instead of by whitespace. Useful when arguments might contain white
1226 space. The GNU find -print0 option produces input suitable for this
1229 @item -t @var{DBFILE}
1232 @item -l @var{DBFILE}
1233 List the contents of a database.
1236 Print the name of the default database. If there is no default
1237 database, this prints a blank line. If @var{LIBDIR} is specified, use
1238 it instead of the default library directory component of the database
1242 Print a help message, then exit.
1246 Print version information, then exit.
1252 @node Invoking jv-convert
1253 @chapter Invoking jv-convert
1255 @c man title jv-convert Convert file from one encoding to another
1257 @c man begin SYNOPSIS jv-convert
1258 @command{jv-convert} [@option{OPTION}] @dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
1261 [@option{--encoding} @var{name}]
1262 [@option{--from} @var{name}]
1263 [@option{--to} @var{name}]
1264 [@option{-i} @var{file}] [@option{-o} @var{file}]
1265 [@option{--reverse}] [@option{--help}] [@option{--version}]
1269 @c man begin DESCRIPTION jv-convert
1271 @command{jv-convert} is a utility included with @code{libgcj} which
1272 converts a file from one encoding to another. It is similar to the Unix
1273 @command{iconv} utility.
1275 The encodings supported by @command{jv-convert} are platform-dependent.
1276 Currently there is no way to get a list of all supported encodings.
1280 @c man begin OPTIONS jv-convert
1283 @item --encoding @var{name}
1284 @itemx --from @var{name}
1285 Use @var{name} as the input encoding. The default is the current
1288 @item --to @var{name}
1289 Use @var{name} as the output encoding. The default is the
1290 @code{JavaSrc} encoding; this is ASCII with @samp{\u} escapes for
1291 non-ASCII characters.
1294 Read from @var{file}. The default is to read from standard input.
1297 Write to @var{file}. The default is to write to standard output.
1300 Swap the input and output encodings.
1303 Print a help message, then exit.
1306 Print version information, then exit.
1311 @node Invoking grmic
1312 @chapter Invoking grmic
1314 @c man title grmic Generate stubs for Remote Method Invocation
1316 @c man begin SYNOPSIS grmic
1317 @command{grmic} [@option{OPTION}] @dots{} @var{class} @dots{}
1320 [@option{-keepgenerated}]
1324 [@option{-nocompile}]
1326 [@option{-d} @var{directory}]
1332 @c man begin DESCRIPTION grmic
1334 @command{grmic} is a utility included with @code{libgcj} which generates
1335 stubs for remote objects.
1337 @c FIXME: Add real information here.
1338 @c This really isn't much more than the --help output.
1340 Note that this program isn't yet fully compatible with the JDK
1341 @command{grmic}. Some options, such as @option{-classpath}, are
1342 recognized but currently ignored. We have left these options
1343 undocumented for now.
1345 Long options can also be given with a GNU-style leading @samp{--}. For
1346 instance, @option{--help} is accepted.
1350 @c man begin OPTIONS grmic
1354 @itemx -keepgenerated
1355 By default, @command{grmic} deletes intermediate files. Either of these
1356 options causes it not to delete such files.
1359 Cause @command{grmic} to create stubs and skeletons for the 1.1
1363 Cause @command{grmic} to create stubs and skeletons compatible with both
1364 the 1.1 and 1.2 protocol versions. This is the default.
1367 Cause @command{grmic} to create stubs and skeletons for the 1.2
1371 Don't compile the generated files.
1374 Print information about what @command{grmic} is doing.
1376 @item -d @var{directory}
1377 Put output files in @var{directory}. By default the files are put in
1378 the current working directory.
1381 Print a help message, then exit.
1384 Print version information, then exit.
1390 @node Invoking grmiregistry
1391 @chapter Invoking grmiregistry
1393 @c man title grmiregistry Remote object registry
1395 @c man begin SYNOPSIS grmiregistry
1396 @command{grmic} [@option{OPTION}] @dots{} [@var{port}]
1399 [@option{--version}]
1403 @c man begin DESCRIPTION grmiregistry
1405 @command{grmiregistry} starts a remote object registry on the current
1406 host. If no port number is specified, then port 1099 is used.
1408 @c FIXME: Add real information here.
1409 @c This really isn't much more than the --help output.
1413 @c man begin OPTIONS grmiregistry
1417 Print a help message, then exit.
1420 Print version information, then exit.
1429 This documents CNI, the Compiled Native Interface,
1430 which is is a convenient way to write Java native methods using C++.
1431 This is a more efficient, more convenient, but less portable
1432 alternative to the standard JNI (Java Native Interface).
1435 * Basic concepts:: Introduction to using CNI@.
1436 * Packages:: How packages are mapped to C++.
1437 * Primitive types:: Handling primitive Java types in C++.
1438 * Reference types:: Handling Java reference types in C++.
1439 * Interfaces:: How Java interfaces map to C++.
1440 * Objects and Classes:: C++ and Java classes.
1441 * Class Initialization:: How objects are initialized.
1442 * Object allocation:: How to create Java objects in C++.
1443 * Memory allocation:: How to allocate and free memory.
1444 * Arrays:: Dealing with Java arrays in C++.
1445 * Methods:: Java methods in C++.
1446 * Strings:: Information about Java Strings.
1447 * Mixing with C++:: How CNI can interoperate with C++.
1448 * Exception Handling:: How exceptions are handled.
1449 * Synchronization:: Synchronizing between Java and C++.
1450 * Invocation:: Starting the Java runtime from C++.
1451 * Reflection:: Using reflection from C++.
1455 @node Basic concepts
1456 @section Basic concepts
1458 In terms of languages features, Java is mostly a subset
1459 of C++. Java has a few important extensions, plus a powerful standard
1460 class library, but on the whole that does not change the basic similarity.
1461 Java is a hybrid object-oriented language, with a few native types,
1462 in addition to class types. It is class-based, where a class may have
1463 static as well as per-object fields, and static as well as instance methods.
1464 Non-static methods may be virtual, and may be overloaded. Overloading is
1465 resolved at compile time by matching the actual argument types against
1466 the parameter types. Virtual methods are implemented using indirect calls
1467 through a dispatch table (virtual function table). Objects are
1468 allocated on the heap, and initialized using a constructor method.
1469 Classes are organized in a package hierarchy.
1471 All of the listed attributes are also true of C++, though C++ has
1472 extra features (for example in C++ objects may be allocated not just
1473 on the heap, but also statically or in a local stack frame). Because
1474 @command{gcj} uses the same compiler technology as G++ (the GNU
1475 C++ compiler), it is possible to make the intersection of the two
1476 languages use the same ABI (object representation and calling
1477 conventions). The key idea in CNI is that Java objects are C++
1478 objects, and all Java classes are C++ classes (but not the other way
1479 around). So the most important task in integrating Java and C++ is to
1480 remove gratuitous incompatibilities.
1482 You write CNI code as a regular C++ source file. (You do have to use
1483 a Java/CNI-aware C++ compiler, specifically a recent version of G++.)
1485 @noindent A CNI C++ source file must have:
1488 #include <gcj/cni.h>
1491 @noindent and then must include one header file for each Java class it uses, e.g.:
1494 #include <java/lang/Character.h>
1495 #include <java/util/Date.h>
1496 #include <java/lang/IndexOutOfBoundsException.h>
1499 @noindent These header files are automatically generated by @code{gcjh}.
1502 CNI provides some functions and macros to make using Java objects and
1503 primitive types from C++ easier. In general, these CNI functions and
1504 macros start with the @code{Jv} prefix, for example the function
1505 @code{JvNewObjectArray}. This convention is used to avoid conflicts
1506 with other libraries. Internal functions in CNI start with the prefix
1507 @code{_Jv_}. You should not call these; if you find a need to, let us
1508 know and we will try to come up with an alternate solution.
1511 @subsection Limitations
1513 Whilst a Java class is just a C++ class that doesn't mean that you are
1514 freed from the shackles of Java, a @acronym{CNI} C++ class must adhere to the
1515 rules of the Java programming language.
1517 For example: it is not possible to declare a method in a CNI class
1518 that will take a C string (@code{char*}) as an argument, or to declare a
1519 member variable of some non-Java datatype.
1525 The only global names in Java are class names, and packages. A
1526 @dfn{package} can contain zero or more classes, and also zero or more
1527 sub-packages. Every class belongs to either an unnamed package or a
1528 package that has a hierarchical and globally unique name.
1530 A Java package is mapped to a C++ @dfn{namespace}. The Java class
1531 @code{java.lang.String} is in the package @code{java.lang}, which is a
1532 sub-package of @code{java}. The C++ equivalent is the class
1533 @code{java::lang::String}, which is in the namespace @code{java::lang}
1534 which is in the namespace @code{java}.
1536 @noindent Here is how you could express this:
1539 (// @r{Declare the class(es), possibly in a header file:}
1548 class java::lang::String : public java::lang::Object
1554 @noindent The @code{gcjh} tool automatically generates the necessary namespace
1558 @subsection Leaving out package names
1560 Always using the fully-qualified name of a java class can be
1561 tiresomely verbose. Using the full qualified name also ties the code
1562 to a single package making code changes necessary should the class
1563 move from one package to another. The Java @code{package} declaration
1564 specifies that the following class declarations are in the named
1565 package, without having to explicitly name the full package
1566 qualifiers. The @code{package} declaration can be
1567 followed by zero or more @code{import} declarations, which
1568 allows either a single class or all the classes in a package to be
1569 named by a simple identifier. C++ provides something similar with the
1570 @code{using} declaration and directive.
1575 import @var{package-name}.@var{class-name};
1578 @noindent allows the program text to refer to @var{class-name} as a shorthand for
1579 the fully qualified name: @code{@var{package-name}.@var{class-name}}.
1582 @noindent To achieve the same effect C++, you have to do this:
1585 using @var{package-name}::@var{class-name};
1589 @noindent Java can also cause imports on demand, like this:
1592 import @var{package-name}.*;
1595 @noindent Doing this allows any class from the package @var{package-name} to be
1596 referred to only by its class-name within the program text.
1599 @noindent The same effect can be achieved in C++ like this:
1602 using namespace @var{package-name};
1606 @node Primitive types
1607 @section Primitive types
1609 Java provides 8 @dfn{primitives} types which represent integers, floats,
1610 characters and booleans (and also the void type). C++ has its own
1611 very similar concrete types. Such types in C++ however are not always
1612 implemented in the same way (an int might be 16, 32 or 64 bits for example)
1613 so CNI provides a special C++ type for each primitive Java type:
1615 @multitable @columnfractions .20 .25 .60
1616 @item @strong{Java type} @tab @strong{C/C++ typename} @tab @strong{Description}
1617 @item @code{char} @tab @code{jchar} @tab 16 bit Unicode character
1618 @item @code{boolean} @tab @code{jboolean} @tab logical (true or false) values
1619 @item @code{byte} @tab @code{jbyte} @tab 8-bit signed integer
1620 @item @code{short} @tab @code{jshort} @tab 16 bit signed integer
1621 @item @code{int} @tab @code{jint} @tab 32 bit signed integer
1622 @item @code{long} @tab @code{jlong} @tab 64 bit signed integer
1623 @item @code{float} @tab @code{jfloat} @tab 32 bit IEEE floating point number
1624 @item @code{double} @tab @code{jdouble} @tab 64 bit IEEE floating point number
1625 @item @code{void} @tab @code{void} @tab no value
1628 When referring to a Java type You should always use these C++ typenames (e.g.: @code{jint})
1629 to avoid disappointment.
1632 @subsection Reference types associated with primitive types
1634 In Java each primitive type has an associated reference type,
1635 e.g.: @code{boolean} has an associated @code{java.lang.Boolean.TYPE} class.
1636 In order to make working with such classes easier GCJ provides the macro
1639 @deffn macro JvPrimClass type
1640 Return a pointer to the @code{Class} object corresponding to the type supplied.
1643 JvPrimClass(void) @result{} java.lang.Void.TYPE
1649 @node Reference types
1650 @section Reference types
1652 A Java reference type is treated as a class in C++. Classes and
1653 interfaces are handled this way. A Java reference is translated to a
1654 C++ pointer, so for instance a Java @code{java.lang.String} becomes,
1655 in C++, @code{java::lang::String *}.
1657 CNI provides a few built-in typedefs for the most common classes:
1658 @multitable @columnfractions .30 .25 .60
1659 @item @strong{Java type} @tab @strong{C++ typename} @tab @strong{Description}
1660 @item @code{java.lang.Object} @tab @code{jobject} @tab Object type
1661 @item @code{java.lang.String} @tab @code{jstring} @tab String type
1662 @item @code{java.lang.Class} @tab @code{jclass} @tab Class type
1668 Every Java class or interface has a corresponding @code{Class}
1669 instance. These can be accessed in CNI via the static @code{class$}
1670 field of a class. The @code{class$} field is of type @code{Class}
1671 (and not @code{Class *}), so you will typically take the address of
1675 Here is how you can refer to the class of @code{String}, which in
1676 Java would be written @code{String.class}:
1679 using namespace java::lang;
1680 doSomething (&String::class$);
1687 A Java class can @dfn{implement} zero or more
1688 @dfn{interfaces}, in addition to inheriting from
1689 a single base class.
1691 @acronym{CNI} allows CNI code to implement methods of interfaces.
1692 You can also call methods through interface references, with some
1695 @acronym{CNI} doesn't understand interface inheritance at all yet. So,
1696 you can only call an interface method when the declared type of the
1697 field being called matches the interface which declares that
1698 method. The workaround is to cast the interface reference to the right
1701 For example if you have:
1709 interface B extends A
1715 and declare a variable of type @code{B} in C++, you can't call
1716 @code{a()} unless you cast it to an @code{A} first.
1718 @node Objects and Classes
1719 @section Objects and Classes
1723 All Java classes are derived from @code{java.lang.Object}. C++ does
1724 not have a unique root class, but we use the C++ class
1725 @code{java::lang::Object} as the C++ version of the
1726 @code{java.lang.Object} Java class. All other Java classes are mapped
1727 into corresponding C++ classes derived from @code{java::lang::Object}.
1729 Interface inheritance (the @code{implements} keyword) is currently not
1730 reflected in the C++ mapping.
1733 @subsection Object fields
1735 Each object contains an object header, followed by the instance fields
1736 of the class, in order. The object header consists of a single
1737 pointer to a dispatch or virtual function table. (There may be extra
1738 fields @emph{in front of} the object, for example for memory
1739 management, but this is invisible to the application, and the
1740 reference to the object points to the dispatch table pointer.)
1742 The fields are laid out in the same order, alignment, and size as in
1743 C++. Specifically, 8-bit and 16-bit native types (@code{byte},
1744 @code{short}, @code{char}, and @code{boolean}) are @emph{not} widened
1745 to 32 bits. Note that the Java VM does extend 8-bit and 16-bit types
1746 to 32 bits when on the VM stack or temporary registers.
1748 If you include the @code{gcjh}-generated header for a
1749 class, you can access fields of Java classes in the @emph{natural}
1750 way. For example, given the following Java class:
1756 public Int (int i) @{ this.i = i; @}
1757 public static Int zero = new Int(0);
1764 #include <gcj/cni.h>;
1768 mult (Int *p, jint k)
1771 return Int::zero; // @r{Static member access.}
1772 return new Int(p->i * k);
1777 @subsection Access specifiers
1779 CNI does not strictly enforce the Java access
1780 specifiers, because Java permissions cannot be directly mapped
1781 into C++ permission. Private Java fields and methods are mapped
1782 to private C++ fields and methods, but other fields and methods
1783 are mapped to public fields and methods.
1787 @node Class Initialization
1788 @section Class Initialization
1790 Java requires that each class be automatically initialized at the time
1791 of the first active use. Initializing a class involves
1792 initializing the static fields, running code in class initializer
1793 methods, and initializing base classes. There may also be
1794 some implementation specific actions, such as allocating
1795 @code{String} objects corresponding to string literals in
1798 The GCJ compiler inserts calls to @code{JvInitClass} at appropriate
1799 places to ensure that a class is initialized when required. The C++
1800 compiler does not insert these calls automatically---it is the
1801 programmer's responsibility to make sure classes are initialized.
1802 However, this is fairly painless because of the conventions assumed by
1805 First, @code{libgcj} will make sure a class is initialized before an
1806 instance of that object is created. This is one of the
1807 responsibilities of the @code{new} operation. This is taken care of
1808 both in Java code, and in C++ code. When G++ sees a @code{new} of a
1809 Java class, it will call a routine in @code{libgcj} to allocate the
1810 object, and that routine will take care of initializing the class.
1811 Note however that this does not happen for Java arrays; you must
1812 allocate those using the appropriate CNI function. It follows that
1813 you can access an instance field, or call an instance (non-static)
1814 method and be safe in the knowledge that the class and all of its base
1815 classes have been initialized.
1817 Invoking a static method is also safe. This is because the
1818 Java compiler adds code to the start of a static method to make sure
1819 the class is initialized. However, the C++ compiler does not
1820 add this extra code. Hence, if you write a native static method
1821 using CNI, you are responsible for calling @code{JvInitClass}
1822 before doing anything else in the method (unless you are sure
1823 it is safe to leave it out).
1825 Accessing a static field also requires the class of the
1826 field to be initialized. The Java compiler will generate code
1827 to call @code{JvInitClass} before getting or setting the field.
1828 However, the C++ compiler will not generate this extra code,
1829 so it is your responsibility to make sure the class is
1830 initialized before you access a static field from C++.
1833 @node Object allocation
1834 @section Object allocation
1836 New Java objects are allocated using a
1837 @dfn{class instance creation expression}, e.g.:
1840 new @var{Type} ( ... )
1843 The same syntax is used in C++. The main difference is that
1844 C++ objects have to be explicitly deleted; in Java they are
1845 automatically deleted by the garbage collector.
1846 Using @acronym{CNI}, you can allocate a new Java object
1847 using standard C++ syntax and the C++ compiler will allocate
1848 memory from the garbage collector. If you have overloaded
1849 constructors, the compiler will choose the correct one
1850 using standard C++ overload resolution rules.
1852 @noindent For example:
1855 java::util::Hashtable *ht = new java::util::Hashtable(120);
1859 @node Memory allocation
1860 @section Memory allocation
1862 When allocating memory in @acronym{CNI} methods it is best to handle
1863 out-of-memory conditions by throwing a Java exception. These
1864 functions are provided for that purpose:
1866 @deftypefun void* JvMalloc (jsize @var{size})
1867 Calls malloc. Throws @code{java.lang.OutOfMemoryError} if allocation
1871 @deftypefun void* JvRealloc (void* @var{ptr}, jsize @var{size})
1872 Calls realloc. Throws @code{java.lang.OutOfMemoryError} if
1876 @deftypefun void JvFree (void* @var{ptr})
1883 While in many ways Java is similar to C and C++, it is quite different
1884 in its treatment of arrays. C arrays are based on the idea of pointer
1885 arithmetic, which would be incompatible with Java's security
1886 requirements. Java arrays are true objects (array types inherit from
1887 @code{java.lang.Object}). An array-valued variable is one that
1888 contains a reference (pointer) to an array object.
1890 Referencing a Java array in C++ code is done using the
1891 @code{JArray} template, which as defined as follows:
1894 class __JArray : public java::lang::Object
1901 class JArray : public __JArray
1905 T& operator[](jint i) @{ return data[i]; @}
1910 There are a number of @code{typedef}s which correspond to @code{typedef}s
1911 from the @acronym{JNI}. Each is the type of an array holding objects
1912 of the relevant type:
1915 typedef __JArray *jarray;
1916 typedef JArray<jobject> *jobjectArray;
1917 typedef JArray<jboolean> *jbooleanArray;
1918 typedef JArray<jbyte> *jbyteArray;
1919 typedef JArray<jchar> *jcharArray;
1920 typedef JArray<jshort> *jshortArray;
1921 typedef JArray<jint> *jintArray;
1922 typedef JArray<jlong> *jlongArray;
1923 typedef JArray<jfloat> *jfloatArray;
1924 typedef JArray<jdouble> *jdoubleArray;
1928 @deftypemethod {template<class T>} T* elements (JArray<T> @var{array})
1929 This template function can be used to get a pointer to the elements of
1930 the @code{array}. For instance, you can fetch a pointer to the
1931 integers that make up an @code{int[]} like so:
1934 extern jintArray foo;
1935 jint *intp = elements (foo);
1938 The name of this function may change in the future.
1942 @deftypefun jobjectArray JvNewObjectArray (jsize @var{length}, jclass @var{klass}, jobject @var{init})
1943 This creates a new array whose elements have reference type.
1944 @code{klass} is the type of elements of the array and
1945 @code{init} is the initial value put into every slot in the array.
1949 using namespace java::lang;
1950 JArray<String *> *array
1951 = (JArray<String *> *) JvNewObjectArray(length, &String::class$, NULL);
1955 @subsection Creating arrays
1957 For each primitive type there is a function which can be used to
1958 create a new array of that type. The name of the function is of the
1962 JvNew@var{Type}Array
1965 @noindent For example:
1971 @noindent can be used to create an array of Java primitive boolean types.
1973 @noindent The following function definition is the template for all such functions:
1975 @deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
1976 Create's an array @var{length} indices long.
1979 @deftypefun jsize JvGetArrayLength (jarray @var{array})
1980 Returns the length of the @var{array}.
1987 Java methods are mapped directly into C++ methods.
1988 The header files generated by @code{gcjh}
1989 include the appropriate method definitions.
1990 Basically, the generated methods have the same names and
1991 @emph{corresponding} types as the Java methods,
1992 and are called in the natural manner.
1994 @subsection Overloading
1996 Both Java and C++ provide method overloading, where multiple
1997 methods in a class have the same name, and the correct one is chosen
1998 (at compile time) depending on the argument types.
1999 The rules for choosing the correct method are (as expected) more complicated
2000 in C++ than in Java, but given a set of overloaded methods
2001 generated by @code{gcjh} the C++ compiler will choose
2004 Common assemblers and linkers are not aware of C++ overloading,
2005 so the standard implementation strategy is to encode the
2006 parameter types of a method into its assembly-level name.
2007 This encoding is called @dfn{mangling},
2008 and the encoded name is the @dfn{mangled name}.
2009 The same mechanism is used to implement Java overloading.
2010 For C++/Java interoperability, it is important that both the Java
2011 and C++ compilers use the @emph{same} encoding scheme.
2013 @subsection Static methods
2015 Static Java methods are invoked in @acronym{CNI} using the standard
2016 C++ syntax, using the @code{::} operator rather
2017 than the @code{.} operator.
2019 @noindent For example:
2022 jint i = java::lang::Math::round((jfloat) 2.3);
2025 @noindent C++ method definition syntax is used to define a static native method.
2029 #include <java/lang/Integer>
2030 java::lang::Integer*
2031 java::lang::Integer::getInteger(jstring str)
2038 @subsection Object Constructors
2040 Constructors are called implicitly as part of object allocation
2041 using the @code{new} operator.
2043 @noindent For example:
2046 java::lang::Integer *x = new java::lang::Integer(234);
2049 Java does not allow a constructor to be a native method.
2050 This limitation can be coded round however because a constructor
2051 can @emph{call} a native method.
2054 @subsection Instance methods
2056 Calling a Java instance method from a C++ @acronym{CNI} method is done
2057 using the standard C++ syntax, e.g.:
2060 // @r{First create the Java object.}
2061 java::lang::Integer *x = new java::lang::Integer(234);
2062 // @r{Now call a method.}
2063 jint prim_value = x->intValue();
2064 if (x->longValue == 0)
2068 @noindent Defining a Java native instance method is also done the natural way:
2071 #include <java/lang/Integer.h>
2074 java::lang:Integer::doubleValue()
2076 return (jdouble) value;
2081 @subsection Interface methods
2083 In Java you can call a method using an interface reference. This is
2084 supported, but not completely. @xref{Interfaces}.
2092 @acronym{CNI} provides a number of utility functions for
2093 working with Java Java @code{String} objects.
2094 The names and interfaces are analogous to those of @acronym{JNI}.
2097 @deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len})
2098 Returns a Java @code{String} object with characters from the C string
2099 @var{chars} up to the index @var{len} in that array.
2102 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes}, jsize @var{len})
2103 Returns a Java @code{String} made up of @var{len} bytes from @var{bytes}.
2107 @deftypefun jstring JvNewStringLatin1 (const char* @var{bytes})
2108 As above but the length of the @code{String} is @code{strlen(@var{bytes})}.
2111 @deftypefun jstring JvNewStringUTF (const char* @var{bytes})
2112 Returns a @code{String} which is made up of the UTF encoded characters
2113 present in the C string @var{bytes}.
2116 @deftypefun jchar* JvGetStringChars (jstring @var{str})
2117 Returns a pointer to an array of characters making up the @code{String} @var{str}.
2120 @deftypefun int JvGetStringUTFLength (jstring @var{str})
2121 Returns the number of bytes required to encode the contents of the
2122 @code{String} @var{str} in UTF-8.
2125 @deftypefun jsize JvGetStringUTFRegion (jstring @var{str}, jsize @var{start}, jsize @var{len}, char* @var{buf})
2126 Puts the UTF-8 encoding of a region of the @code{String} @var{str} into
2127 the buffer @code{buf}. The region to fetch is marked by @var{start} and @var{len}.
2129 Note that @var{buf} is a buffer, not a C string. It is @emph{not}
2134 @node Mixing with C++
2135 @section Interoperating with C/C++
2137 Because @acronym{CNI} is designed to represent Java classes and methods it
2138 cannot be mixed readily with C/C++ types.
2140 One important restriction is that Java classes cannot have non-Java
2141 type instance or static variables and cannot have methods which take
2142 non-Java types as arguments or return non-Java types.
2144 @noindent None of the following is possible with CNI:
2148 class ::MyClass : public java::lang::Object
2150 char* variable; // @r{char* is not a valid Java type.}
2155 ::SomeClass::someMethod (char *arg)
2160 @} // @r{@code{uint} is not a valid Java type, neither is @code{char*}}
2163 @noindent Of course, it is ok to use C/C++ types within the scope of a method:
2168 ::SomeClass::otherMethod (jstring str)
2179 The above restriction can be problematic, so @acronym{CNI} includes the
2180 @code{gnu.gcj.RawData} class. The @code{RawData} class is a
2181 @dfn{non-scanned reference} type. In other words variables declared
2182 of type @code{RawData} can contain any data and are not checked by the
2183 compiler or memory manager in any way.
2185 This means that you can put C/C++ data structures (including classes)
2186 in your @acronym{CNI} classes, as long as you use the appropriate cast.
2188 @noindent Here are some examples:
2192 class ::MyClass : public java::lang::Object
2194 gnu.gcj.RawData string;
2197 gnu.gcj.RawData getText ();
2201 ::MyClass::MyClass ()
2208 ::MyClass::getText ()
2214 ::MyClass::printText ()
2216 printf("%s\n", (char*) string);
2221 @subsection RawDataManaged
2223 @code{gnu.gcj.RawDataManaged} is another type used to indicate special data used
2224 by native code. Unlike the @code{RawData} type, fields declared as
2225 @code{RawDataManaged} will be "marked" by the memory manager and
2226 considered for garbage collection.
2228 Native data which is allocated using CNI's @code{JvAllocBytes()}
2229 function and stored in a @code{RawDataManaged} will be automatically
2230 freed when the Java object it is associated with becomes unreachable.
2232 @subsection Native memory allocation
2234 @deftypefun void* JvAllocBytes (jsize @var{size})
2235 Allocates @var{size} bytes from the heap. The memory returned is zeroed.
2236 This memory is not scanned for pointers by the garbage collector, but will
2237 be freed if no references to it are discovered.
2239 This function can be useful if you need to associate some native data with a
2240 Java object. Using a CNI's special @code{RawDataManaged} type, native data
2241 allocated with @code{JvAllocBytes} will be automatically freed when the Java
2242 object itself becomes unreachable.
2245 @subsection Posix signals
2247 On Posix based systems the @code{libgcj} library uses several signals
2248 internally. @acronym{CNI} code should not attempt to use the same
2249 signals as doing so may cause @code{libgcj} and/or the @acronym{CNI}
2252 SIGSEGV is used on many systems to generate
2253 @code{NullPointerExceptions}. SIGCHLD is used internally by
2254 @code{Runtime.exec()}. Several other signals (that vary from platform to
2255 platform) can be used by the memory manager and by
2256 @code{Thread.interrupt()}.
2258 @node Exception Handling
2259 @section Exception Handling
2261 While C++ and Java share a common exception handling framework,
2262 things are not yet perfectly integrated. The main issue is that the
2263 run-time type information facilities of the two
2264 languages are not integrated.
2266 Still, things work fairly well. You can throw a Java exception from
2267 C++ using the ordinary @code{throw} construct, and this
2268 exception can be caught by Java code. Similarly, you can catch an
2269 exception thrown from Java using the C++ @code{catch}
2272 @noindent Here is an example:
2276 throw new java::lang::IndexOutOfBoundsException();
2279 Normally, G++ will automatically detect when you are writing C++
2280 code that uses Java exceptions, and handle them appropriately.
2281 However, if C++ code only needs to execute destructors when Java
2282 exceptions are thrown through it, GCC will guess incorrectly. Sample
2286 struct S @{ ~S(); @};
2288 extern void bar(); // @r{Is implemented in Java and may throw exceptions.}
2297 The usual effect of an incorrect guess is a link failure, complaining of
2298 a missing routine called @code{__gxx_personality_v0}.
2300 You can inform the compiler that Java exceptions are to be used in a
2301 translation unit, irrespective of what it might think, by writing
2302 @code{#pragma GCC java_exceptions} at the head of the
2303 file. This @code{#pragma} must appear before any
2304 functions that throw or catch exceptions, or run destructors when
2305 exceptions are thrown through them.
2307 @node Synchronization
2308 @section Synchronization
2310 Each Java object has an implicit monitor.
2311 The Java VM uses the instruction @code{monitorenter} to acquire
2312 and lock a monitor, and @code{monitorexit} to release it.
2314 The corresponding CNI macros are @code{JvMonitorEnter} and
2315 @code{JvMonitorExit} (JNI has similar methods @code{MonitorEnter}
2316 and @code{MonitorExit}).
2319 The Java source language does not provide direct access to these primitives.
2320 Instead, there is a @code{synchronized} statement that does an
2321 implicit @code{monitorenter} before entry to the block,
2322 and does a @code{monitorexit} on exit from the block.
2323 Note that the lock has to be released even when the block is abnormally
2324 terminated by an exception, which means there is an implicit
2325 @code{try finally} surrounding synchronization locks.
2327 From C++, it makes sense to use a destructor to release a lock.
2328 @acronym{CNI} defines the following utility class:
2331 class JvSynchronize() @{
2333 JvSynchronize(jobject o) @{ obj = o; JvMonitorEnter(o); @}
2334 ~JvSynchronize() @{ JvMonitorExit(obj); @}
2347 @noindent might become this C++ code:
2351 JvSynchronize dummy (OBJ);
2356 Java also has methods with the @code{synchronized} attribute.
2357 This is equivalent to wrapping the entire method body in a
2358 @code{synchronized} statement.
2359 (Alternatively, an implementation could require the caller to do
2360 the synchronization. This is not practical for a compiler, because
2361 each virtual method call would have to test at run-time if
2362 synchronization is needed.) Since in @command{gcj}
2363 the @code{synchronized} attribute is handled by the
2364 method implementation, it is up to the programmer
2365 of a synchronized native method to handle the synchronization
2366 (in the C++ implementation of the method).
2367 In other words, you need to manually add @code{JvSynchronize}
2368 in a @code{native synchronized} method.
2373 CNI permits C++ applications to make calls into Java classes, in addition to
2374 allowing Java code to call into C++. Several functions, known as the
2375 @dfn{invocation API}, are provided to support this.
2377 @deftypefun jint JvCreateJavaVM (JvVMInitArgs* @var{vm_args})
2379 Initializes the Java runtime. This function performs essential initialization
2380 of the threads interface, garbage collector, exception handling and other key
2381 aspects of the runtime. It must be called once by an application with
2382 a non-Java @code{main()} function, before any other Java or CNI calls are made.
2383 It is safe, but not recommended, to call @code{JvCreateJavaVM()} more than
2384 once provided it is only called from a single thread.
2385 The @var{vmargs} parameter can be used to specify initialization parameters
2386 for the Java runtime. It may be @code{NULL}.
2388 JvVMInitArgs represents a list of virtual machine initialization
2389 arguments. @code{JvCreateJavaVM()} ignores the version field.
2392 typedef struct JvVMOption
2394 // a VM initialization option
2396 // extra information associated with this option
2400 typedef struct JvVMInitArgs
2402 // for compatibility with JavaVMInitArgs
2405 // number of VM initialization options
2408 // an array of VM initialization options
2409 JvVMOption* options;
2411 // true if the option parser should ignore unrecognized options
2412 jboolean ignoreUnrecognized;
2416 @code{JvCreateJavaVM()} returns @code{0} upon success, or @code{-1} if
2417 the runtime is already initialized.
2419 @emph{Note:} In GCJ 3.1, the @code{vm_args} parameter is ignored. It
2420 is recognized and used as of release 4.0.
2423 @deftypefun java::lang::Thread* JvAttachCurrentThread (jstring @var{name}, java::lang::ThreadGroup* @var{group})
2424 Registers an existing thread with the Java runtime. This must be called once
2425 from each thread, before that thread makes any other Java or CNI calls. It
2426 must be called after @code{JvCreateJavaVM}.
2427 @var{name} specifies a name for the thread. It may be @code{NULL}, in which
2428 case a name will be generated.
2429 @var{group} is the ThreadGroup in which this thread will be a member. If it
2430 is @code{NULL}, the thread will be a member of the main thread group.
2431 The return value is the Java @code{Thread} object that represents the thread.
2432 It is safe to call @code{JvAttachCurrentThread()} more than once from the same
2433 thread. If the thread is already attached, the call is ignored and the current
2434 thread object is returned.
2437 @deftypefun jint JvDetachCurrentThread ()
2438 Unregisters a thread from the Java runtime. This should be called by threads
2439 that were attached using @code{JvAttachCurrentThread()}, after they have
2440 finished making calls to Java code. This ensures that any resources associated
2441 with the thread become eligible for garbage collection.
2442 This function returns @code{0} upon success, or @code{-1} if the current thread
2446 @subsection Handling uncaught exceptions
2448 If an exception is thrown from Java code called using the invocation API, and
2449 no handler for the exception can be found, the runtime will abort the
2450 application. In order to make the application more robust, it is recommended
2451 that code which uses the invocation API be wrapped by a top-level try/catch
2452 block that catches all Java exceptions.
2456 The following code demonstrates the use of the invocation API. In this
2457 example, the C++ application initializes the Java runtime and attaches
2458 itself. The @code{java.lang.System} class is initialized in order to
2459 access its @code{out} field, and a Java string is printed. Finally, the thread
2460 is detached from the runtime once it has finished making Java calls. Everything
2461 is wrapped with a try/catch block to provide a default handler for any uncaught
2464 The example can be compiled with @command{c++ test.cc -lgcj}.
2468 #include <gcj/cni.h>
2469 #include <java/lang/System.h>
2470 #include <java/io/PrintStream.h>
2471 #include <java/lang/Throwable.h>
2473 int main(int argc, char *argv)
2475 using namespace java::lang;
2479 JvCreateJavaVM(NULL);
2480 JvAttachCurrentThread(NULL, NULL);
2482 String *message = JvNewStringLatin1("Hello from C++");
2483 JvInitClass(&System::class$);
2484 System::out->println(message);
2486 JvDetachCurrentThread();
2488 catch (Throwable *t)
2490 System::err->println(JvNewStringLatin1("Unhandled Java exception:"));
2491 t->printStackTrace();
2499 Reflection is possible with CNI code, it functions similarly to how it
2500 functions with JNI@.
2502 @c clean this up... I mean, what are the types jfieldID and jmethodID in JNI?
2503 The types @code{jfieldID} and @code{jmethodID}
2506 @noindent The functions:
2509 @item @code{JvFromReflectedField},
2510 @item @code{JvFromReflectedMethod},
2511 @item @code{JvToReflectedField}
2512 @item @code{JvToFromReflectedMethod}
2515 @noindent will be added shortly, as will other functions corresponding to JNI@.
2518 @node System properties
2519 @chapter System properties
2521 The runtime behavior of the @code{libgcj} library can be modified by setting
2522 certain system properties. These properties can be compiled into the program
2523 using the @code{-D@var{name}[=@var{value}]} option to @command{gcj} or by
2524 setting them explicitly in the program by calling the
2525 @code{java.lang.System.setProperty()} method. Some system properties are only
2526 used for informational purposes (like giving a version number or a user name).
2527 A program can inspect the current value of a property by calling the
2528 @code{java.lang.System.getProperty()} method.
2531 * Standard Properties:: Standard properties supported by @code{libgcj}
2532 * GNU Classpath Properties:: Properties found in Classpath based libraries
2533 * libgcj Runtime Properties:: Properties specific to @code{libgcj}
2536 @node Standard Properties
2537 @section Standard Properties
2539 The following properties are normally found in all implementations of the core
2540 libraries for the Java language.
2545 The @code{libgcj} version number.
2548 Set to @samp{The Free Software Foundation, Inc.}
2550 @item java.vendor.url
2551 Set to @uref{http://gcc.gnu.org/java/}.
2554 The directory where @code{gcj} was installed. Taken from the @code{--prefix}
2555 option given to @command{configure}.
2557 @item java.class.version
2558 The class format version number supported by the libgcj byte code interpreter.
2559 (Currently @samp{46.0})
2561 @item java.vm.specification.version
2562 The Virtual Machine Specification version implemented by @code{libgcj}.
2563 (Currently @samp{1.0})
2565 @item java.vm.specification.vendor
2566 The name of the Virtual Machine specification designer.
2568 @item java.vm.specification.name
2569 The name of the Virtual Machine specification
2570 (Set to @samp{Java Virtual Machine Specification}).
2572 @item java.vm.version
2573 The @command{gcj} version number.
2575 @item java.vm.vendor
2576 Set to @samp{The Free Software Foundation, Inc.}
2579 Set to @samp{GNU libgcj}.
2581 @item java.specification.version
2582 The Runtime Environment specification version implemented by @code{libgcj}.
2583 (Currently set to @samp{1.3})
2585 @item java.specification.vendor
2586 The Runtime Environment specification designer.
2588 @item java.specification.name
2589 The name of the Runtime Environment specification
2590 (Set to @samp{Java Platform API Specification}).
2592 @item java.class.path
2593 The paths (jar files, zip files and directories) used for finding class files.
2595 @item java.library.path
2596 Directory path used for finding native libraries.
2598 @item java.io.tmpdir
2599 The directory used to put temporary files in.
2602 Name of the Just In Time compiler to use by the byte code interpreter.
2603 Currently not used in @code{libgcj}.
2606 Directories containing jar files with extra libraries. Will be used when
2609 @item java.protocol.handler.pkgs
2610 A @samp{|} separated list of package names that is used to find classes that
2611 implement handlers for @code{java.net.URL}.
2613 @item java.rmi.server.codebase
2614 A list of URLs that is used by the @code{java.rmi.server.RMIClassLoader}
2615 to load classes from.
2618 A list of class names that will be loaded by the @code{java.sql.DriverManager}
2621 @item file.separator
2622 The separator used in when directories are included in a filename
2623 (normally @samp{/} or @samp{\} ).
2626 The default character encoding used when converting platform native files to
2627 Unicode (usually set to @samp{8859_1}).
2629 @item path.separator
2630 The standard separator used when a string contains multiple paths
2631 (normally @samp{:} or @samp{;}), the string is usually not a valid character
2632 to use in normal directory names.)
2634 @item line.separator
2635 The default line separator used on the platform (normally @samp{\n}, @samp{\r}
2636 or a combination of those two characters).
2638 @item policy.provider
2639 The class name used for the default policy provider returned by
2640 @code{java.security.Policy.getPolicy}.
2643 The name of the user running the program. Can be the full name, the login name
2644 or empty if unknown.
2647 The default directory to put user specific files in.
2650 The current working directory from which the program was started.
2653 The default language as used by the @code{java.util.Locale} class.
2656 The default region as used by the @code{java.util.Local} class.
2659 The default variant of the language and region local used.
2662 The default timezone as used by the @code{java.util.TimeZone} class.
2665 The operating system/kernel name that the program runs on.
2668 The hardware that we are running on.
2671 The version number of the operating system/kernel.
2673 @item awt.appletWarning
2674 The string to display when an untrusted applet is displayed.
2675 Returned by @code{java.awt.Window.getWarningString()} when the window is
2679 The class name used for initializing the default @code{java.awt.Toolkit}.
2680 Defaults to @code{gnu.awt.gtk.GtkToolkit}.
2682 @item http.proxyHost
2683 Name of proxy host for http connections.
2685 @item http.proxyPort
2686 Port number to use when a proxy host is in use.
2690 @node GNU Classpath Properties
2691 @section GNU Classpath Properties
2693 @code{libgcj} is based on the GNU Classpath (Essential Libraries for Java) a
2694 GNU project to create free core class libraries for use with virtual machines
2695 and compilers for the Java language. The following properties are common to
2696 libraries based on GNU Classpath.
2700 @item gcj.dumpobject
2701 Enables printing serialization debugging by the @code{java.io.ObjectInput} and
2702 @code{java.io.ObjectOutput} classes when set to something else then the empty
2703 string. Only used when running a debug build of the library.
2705 @item gnu.classpath.vm.shortname
2706 This is a succinct name of the virtual machine. For @code{libgcj},
2707 this will always be @samp{libgcj}.
2709 @item gnu.classpath.home.url
2710 A base URL used for finding system property files (e.g.,
2711 @file{classpath.security}). By default this is a @samp{file:} URL
2712 pointing to the @file{lib} directory under @samp{java.home}.
2716 @node libgcj Runtime Properties
2717 @section libgcj Runtime Properties
2719 The following properties are specific to the @code{libgcj} runtime and will
2720 normally not be found in other core libraries for the java language.
2724 @item java.fullversion
2725 The combination of @code{java.vm.name} and @code{java.vm.version}.
2728 Same as @code{java.fullversion}.
2731 Used by the @code{java.net.DatagramSocket} class when set to something else
2732 then the empty string. When set all newly created @code{DatagramSocket}s will
2733 try to load a class @code{java.net.[impl.prefix]DatagramSocketImpl} instead of
2734 the normal @code{java.net.PlainDatagramSocketImpl}.
2736 @item gnu.gcj.progname
2737 The class or binary name that was used to invoke the program. This will be
2738 the name of the "main" class in the case where the @code{gij} front end is
2739 used, or the program binary name in the case where an application is compiled
2742 @item gnu.gcj.runtime.NameFinder.use_addr2line
2743 Whether an external process, @command{addr2line}, should be used to determine
2744 line number information when tracing the stack. Setting this to @code{false}
2745 may suppress line numbers when printing stack traces and when using
2746 the java.util.logging infrastructure. However, performance may improve
2747 significantly for applications that print stack traces or make logging calls
2750 @item gnu.gcj.runtime.VMClassLoader.library_control
2751 This controls how shared libraries are automatically loaded by the
2752 built-in class loader. If this property is set to @samp{full}, a full
2753 search is done for each requested class. If this property is set to
2754 @samp{cache} (the default), then any failed lookups are cached and not
2755 tried again. If this property is set to @samp{never}, then lookups
2756 are never done. For more information, @xref{Extensions}.
2758 @item gnu.gcj.runtime.endorsed.dirs
2759 This is like the standard @code{java.endorsed.dirs}, property, but
2760 specifies some extra directories which are searched after the standard
2761 endorsed directories. This is primarily useful for telling
2762 @code{libgcj} about additional libraries which are ordinarily
2763 incorporated into the JDK, and which should be loaded by the bootstrap
2764 class loader, but which are not yet part of @code{libgcj} itself for
2767 @item gnu.gcj.jit.compiler
2768 @c FIXME we should probably have a whole node on this...
2769 This is the full path to @command{gcj} executable which should be
2770 used to compile classes just-in-time when
2771 @code{ClassLoader.defineClass} is called. If not set, @command{gcj}
2772 will not be invoked by the runtime; this can also be controlled via
2773 @code{Compiler.disable}.
2775 @item gnu.gcj.jit.options
2776 This is a space-separated string of options which should be passed to
2777 @command{gcj} when in JIT mode. If not set, a sensible default is
2780 @item gnu.gcj.jit.cachedir
2781 This is the directory where cached shared library files are
2782 stored. If not set, JIT compilation is disabled. This should never
2783 be set to a directory that is writable by any other user.
2785 @item gnu.gcj.precompiled.db.path
2786 This is a sequence of file names, each referring to a file created by
2787 @command{gcj-dbtool}. These files will be used by @code{libgcj} to
2788 find shared libraries corresponding to classes that are loaded from
2789 bytecode. @code{libgcj} often has a built-in default database; it
2790 can be queried using @code{gcj-dbtool -p}.
2798 While writing @command{gcj} and @code{libgcj} we have, of course, relied
2799 heavily on documentation from Sun Microsystems. In particular we have
2800 used The Java Language Specification (both first and second editions),
2801 the Java Class Libraries (volumes one and two), and the Java Virtual
2802 Machine Specification. In addition we've used the online documentation
2803 at @uref{http://java.sun.com/}.
2805 The current @command{gcj} home page is
2806 @uref{http://gcc.gnu.org/java/}.
2808 For more information on gcc, see @uref{http://gcc.gnu.org/}.
2810 Some @code{libgcj} testing is done using the Mauve test suite. This is
2811 a free software Java class library test suite which is being written
2812 because the JCK is not free. See
2813 @uref{http://sources.redhat.com/mauve/} for more information.